You are here

hosting.api.php in Hosting 7.4

Same filename and directory in other branches
  1. 6.2 hosting.api.php
  2. 7.3 hosting.api.php

Hooks provided by the hosting module, and some other random ones.

File

hosting.api.php
View source
<?php

/**
 * @file
 * Hooks provided by the hosting module, and some other random ones.
 */

/** @defgroup hostinghooks Frontend hooks
 * @{
 *
 * Those hooks are hooks usable within contrib Drupal modules running
 * in the Aegir frontend site.
 */

/**
 * Determine if a site can be created using the specified domain.
 *
 * The frontend will only create a specified domains if all implementations of
 * this hook return TRUE, so in most cases you will be looking for domains that
 * you don't allow, and fallback to a default position of allowing the domain.
 *
 * @param string $url
 *   The URL of the site that hosting wishes to create.
 * @param array $params
 *   An array of paramters that may contain information about the site. None of
 *   the keys are required however, so you should not depend on the value of any
 *   particular key in this array. If the array is not empty it will usually
 *   contain at least a 'nid' key whose value is the nid of the site being
 *   created.
 *
 * @return bool
 *   Return TRUE/FALSE if you allow or deny the domain respectively.
 *
 * @see hosting_domain_allowed()
 */
function hook_allow_domain($url, $params) {

  // Don't allow another drupal.org, it's special.
  if ($url == 'drupal.org') {
    return FALSE;
  }
  else {
    return TRUE;
  }
}

/**
 * Import a backend context into the corresponding frontend node.
 *
 * This hook will be invoked when an object is being imported from the backend
 * into the frontend, for example a site that has just been cloned. You should
 * inspect the context coming from the backend and store anything the frontend
 * that you need to.
 *
 * A node to represent the object will have already been created and is
 * available to store things in, this node will be automatically saved after all
 * implementations of this hook are called. You should not call node_save()
 * manually on this node.
 *
 * If you implement hook_hosting_TASK_OBJECT_context_options() then you will
 * probably want to implement this hook also, as they mirror each other.
 *
 * @param object $context
 *   The backend context that is being imported.
 * @param object $node
 *   The node object that is being built up from the $context. You should modify
 *   the fields and properties so that they reflect the contents of the
 *   $context.
 *
 * @see hosting_drush_import()
 * @see hook_hosting_TASK_OBJECT_context_options()
 */
function hook_drush_context_import($context, &$node) {

  // From hosting_alias_drush_context_import().
  if ($context->type == 'site') {
    $node->aliases = $context->aliases;
    $node->redirection = $context->redirection;
  }
}

/**
 * Register a hosting feature with Aegir.
 *
 * The frontend provides a UI for enabling and disabling features, which usually
 * corresponds to enabling and disabling a module providing the feature.
 *
 * This hook can be implemented in a file named:
 * hosting.feature.FEATURE_KEY.inc
 *
 * Note that the module providing this hook does not need to be enabled for it
 * to be called. The frontend will use details in this hook to enable a module
 * if the feature is enabled.
 *
 * @return array
 *   An array of hosting features, keyed by the machine name of the feature.
 *   Inner arrays may contain the following keys:
 *   - 'title': The localised title of the feature.
 *   - 'description': The localised description of the feature.
 *   - 'status': The inital status of the feature, either
 *      HOSTING_FEATURE_DISABLED, HOSTING_FEATURE_ENABLED or
 *      HOSTING_FEATURE_REQUIRED.
 *   - 'module': A module to enable or disable whenever the feature is enabled
 *      or disabled.
 *   - 'node': A node type that is associated with this feature.
 *   - 'enable': A function name to call when this feature is enabled.
 *   - 'disable': A function name to call when this feature is disabled.
 *   - 'group': The group that this feature belongs to, should be either NULL or
 *     'experimental' (or 'required' for core features).
 *
 * @see hosting_get_features()
 */
function hook_hosting_feature() {

  // From hosting_example_hosting_feature().
  $features['example'] = array(
    // Title to display in form.
    'title' => t('Example feature'),
    // Description.
    'description' => t('Example feature documenting how to create your own extensions.'),
    // Initial status ( HOSTING_FEATURE_DISABLED, HOSTING_FEATURE_ENABLED, HOSTING_FEATURE_REQUIRED )
    'status' => HOSTING_FEATURE_DISABLED,
    // Module to enable/disable alongside feature.
    'module' => 'hosting_example',
    // Callback functions to execute on enabling or disabling this feature.
    'enable' => 'hosting_example_feature_enable_callback',
    'disable' => 'hosting_example_feature_disable_callback',
    // Associate with a specific node type.
    // 'node' => 'nodetype',
    // Which group to display in ( null , experimental , required )
    'group' => 'experimental',
  );
  return $features;
}

/**
 * Define hosting queues.
 *
 * @return array
 *   An array with the queue specification. @see hosting_get_queues for an example
 */
function hook_hosting_queues() {
}

/**
 * Alter module defined queue definitions before they are processed.
 *
 * This hook is invoked before hosting calculates the number of items to
 * process when processing queues, so, for example, you could alter the number of apparent
 * items in the queue.
 *
 * @param array $queues
 *   The array of queue definitions of queues provided by modules.
 *
 * @see hosting_get_queues
 * @see hook_hosting_queues
 * @see hook_hosting_processed_queues_alter
 */
function hook_hosting_queues_alter(&$queues) {
  if (isset($queues['cron'])) {

    // Do not execute the cron queue at weekends.
    if (date('N', REQUEST_TIME) > 5) {
      $queues['cron']['total_items'] = 0;
    }
  }
}

/**
 * Alter module defined queue definitions after they are processed.
 *
 * This hook is invoked after hosting module calculates the number of items to
 * process when processing queues, and after the configurable information has
 * been merged in.
 *
 * @param array $queues
 *   The processed array of queue definitions of queues provided by modules.
 *
 * @see hosting_get_queues
 * @see hook_hosting_queues
 * @see hook_hosting_queues_alter
 */
function hook_hosting_processed_queues_alter(&$queues) {
  if (isset($queues['cron'])) {

    // Force the cron queue to always be disabled.
    $queues['cron']['enabled'] = FALSE;
  }
}

/**
 * Add or change context options before a hosting task runs.
 *
 * This hook is invoked just before any task that has the 'provision_save' flag
 * equal to TRUE. These include the 'install', 'verify' and 'import' tasks.
 *
 * The TASK_OBJECT will be either: 'server', 'platform' or 'site'.
 *
 * This gives other modules the chance to send data to the backend to be
 * persisted by services there. The entire task is sent so that you have access
 * to it, but you should avoid changing things outside of the
 * $task->content_options collection.
 *
 * If you are sending extra context options to the backend based on properties
 * in the object's node, then you should also implement the
 * hook_drush_context_import() hook to re-create those properties on the node
 * when a context is imported.
 *
 * @param object $task
 *   The hosting task that is about to be executed, the task is passed by
 *   reference. The context_options property of this object is about to be saved
 *   to the backend, so you can make any changes before that happens. Note that
 *   these changes won't persist in the backend unless you have a service that
 *   will store them.
 *
 *   The node representing the object of the task, e.g. the site that is being
 *   verified is available in the $task->ref property.
 *
 * @see drush_hosting_task()
 * @see hook_drush_context_import()
 * @see hook_hosting_tasks()
 */
function hook_hosting_TASK_OBJECT_context_options(&$task) {

  // From hosting_hosting_platform_context_options().
  $task->context_options['server'] = '@server_master';
  $task->context_options['web_server'] = hosting_context_name($task->ref->web_server);
}

/**
 * Perform actions when a task has failed and has been rolled back.
 *
 * Replace TASK_TYPE with the type of task that if rolled back you will be
 * notified of.
 *
 * @param object $task
 *   The hosting task that has failed and has been rolled back.
 * @param array $data
 *   An associative array of the drush output of the backend task from
 *   drush_backend_output(). The array should contain at least the following:
 *   - "output": The raw output from the drush command executed.
 *   - "error_status": The error status of the command run on the backend.
 *   - "log": The drush log messages.
 *   - "error_log": The list of errors that occurred when running the command.
 *   - "context": The drush options for the backend command, this may contain
 *     options that were set when the command ran, or options that were set by
 *     the command itself.
 *
 * @see drush_hosting_hosting_task_rollback()
 * @see drush_backend_output()
 */
function hook_hosting_TASK_TYPE_task_rollback($task, $data) {

  // From hosting_site_hosting_install_task_rollback().
  // @TODO : we need to check the returned list of errors, not the code.
  if (drush_cmp_error('PROVISION_DRUPAL_SITE_INSTALLED')) {

    // Site has already been installed. Try to import instead.
    drush_log(dt("This site appears to be installed already. Generating an import task."));
    hosting_add_task($task->rid, 'import');
  }
  else {
    $task->ref->no_verify = TRUE;
    $task->ref->site_status = HOSTING_SITE_DISABLED;
    node_save($task->ref);
  }
}

/**
 * Act on nodes defined by other modules.
 *
 * This is a more specific version of hook_nodeapi() that includes a node type
 * and operation being performed, in the function name. When implementing this
 * hook you should replace TYPE with the node type and OP with the node
 * operation you would like to be notified for. A list of possible values for OP
 * can be found in the documentation for hook_nodeapi().
 *
 * This hook may help you write code that is easier to follow, but this is a
 * hosting specific hook so you may confuse other developers that are not so
 * familar with the internals of hosting.
 *
 * @param object &$node
 *   The node the action is being performed on.
 * @param mixed $a3
 *   - When OP is "view", passes in the $teaser parameter from node_view().
 *   - When OP is "validate", passes in the $form parameter from node_validate().
 * @param mixed $a4
 *   - When OP is "view", passes in the $page parameter from node_view().
 *
 * @return mixed
 *   This varies depending on the operation (OP).
 *   - The "presave", "insert", "update", "delete", "print" and "view"
 *     operations have no return value.
 *   - The "load" operation should return an array containing pairs
 *     of fields => values to be merged into the node object.
 *
 * @see hook_nodeapi()
 * @see hosting_nodeapi()
 */
function hook_nodeapi_TYPE_OP(&$node, $a3, $a4) {

  // From hosting_nodeapi_client_delete_revision().
  db_query('DELETE FROM {hosting_client} WHERE vid = %d', $node->vid);
}

/**
 * Perform actions when a task has completed succesfully.
 *
 * Replace TASK_TYPE with the type of task that if completed you will be
 * notified of. This is a good place to hook in and record changes in the
 * frontend as a result of the task executing in the backend. If you just want
 * to hook into the backend then you probably want to consider using the
 * 'standard' Drush hooks there, i.e. host_post_provision_verify(),
 * hook_post_provision_install() etc.
 *
 * @param object $task
 *   The hosting task that has completed.
 * @param array $data
 *   An associative array of the drush output of the completed backend task from
 *   drush_backend_output(). The array should contain at least the following:
 *   - "output": The raw output from the drush command executed.
 *   - "error_status": The error status of the command run on the backend,
 *     should be DRUSH_SUCCESS normally.
 *   - "log": The drush log messages.
 *   - "error_log": The list of errors that occurred when running the command.
 *   - "context": The drush options for the backend command, this may contain
 *     options that were set when the command ran, or options that were set by
 *     the command itself.
 *
 * @see drush_hosting_post_hosting_task()
 * @see drush_backend_output()
 */
function hook_post_hosting_TASK_TYPE_task($task, $data) {

  // From hosting_site_post_hosting_backup_task().
  if ($data['context']['backup_file'] && $task->ref->type == 'site') {
    $platform = node_load($task->ref->platform);
    $desc = $task->task_args['description'];
    $desc = $desc ? $desc : t('Generated on request');
    hosting_site_add_backup($task->ref->nid, $platform->web_server, $data['context']['backup_file'], $desc, $data['context']['backup_file_size']);
  }
}

/**
 * Process the specified queue.
 *
 * Modules providing a queue should implement this function an process the
 * number of items from the queue that are specified. It is up the to the
 * module to determine which items it wishes to process.
 *
 * If you wish to process multiple items at the same time you will need to fork
 * the process by calling drush_invoke_process() with the 'fork' option,
 * specifying a drush command with the arguments required to process your task.
 * Otherwise you can do all your processing in this function, or similarly call
 * drush_invoke_process() without the 'fork' option.
 *
 * @param int $count
 *   The maximum number of items to process.
 *
 * @see hosting_run_queue()
 * @see hosting_get_queues()
 */
function hosting_QUEUE_TYPE_queue($count = 5) {

  // From hosting_tasks_queue().
  global $provision_errors;
  drush_log(dt("Running tasks queue"));
  $tasks = hosting_get_new_tasks($count);
  foreach ($tasks as $task) {
    drush_invoke_process('@self', "hosting-task", array(
      $task->nid,
    ), array(), array(
      'fork' => TRUE,
    ));
  }
}

/**
 * @see hosting_queues()
 */
function hosting_TASK_SINGULAR_list() {
}

/**
 * @return string
 * @see hosting_queue_block()
 */
function hosting_TASK_SINGULAR_summary() {
}

/**
 * Reacts any time a task has it's status updated, including when being run in
 * the queue, ending, or being cancelled.
 *
 * @param object $task
 *   The task that has just completed.
 *   Note that $task->task_status has the old value, $status has the new value.
 *   The database will just have been updated before this hook is called.
 * @param int $status
 *   The new status of that task. Can be HOSTING_TASK_SUCCESS, etc.
 */
function hook_hosting_task_update_status($task, $status) {

  // A task's "RID" is a node ID for the object the task is run on. (Site, Platform, Server, etc)
  $node = node_load($task->rid);

  // On error, output a new message.
  if ($status == HOSTING_TASK_ERROR) {
    drush_log(dt("!title: !task task ended in an Error", array(
      '!task' => $task->task_type,
      '!title' => $node->title,
    )), 'error');
  }
  else {
    drush_log(" Task completed successfully: " . $task->task_type, 'ok');
    drush_log(dt("!title: !task task ended with !status", array(
      '!task' => $task->task_type,
      '!title' => $node->title,
      '!status' => _hosting_parse_error_code($status),
    )), 'ok');
  }
}

/**
 * Return a list of Aegir entities to guard against destructive tasks.
 *
 * @see: hook_hosting_task_dangerous_tasks().
 * @see: hook_hosting_task_guarded_nodes_alter();
 */
function hook_hosting_task_guarded_nodes() {

  // Guard against destructive tasks run on the hostmaster site or platform.
  $hostmaster_site_nid = hosting_get_hostmaster_site_nid();
  $hostmaster_platform_nid = hosting_get_hostmaster_platform_nid();
  $guarded_nids = array(
    $hostmaster_site_nid,
    $hostmaster_platform_nid,
  );
  return $guarded_nids;
}

/**
 * Alter the list of guarded nodes.
 *
 * @param $nids
 *   A list of NIDs as returned by hook_hosting_task_guarded_nodes().
 */
function hook_hosting_task_guarded_nodes_alter(&$nids) {
}

/**
 * Return a list of dangerous tasks.
 *
 * These tasks will be blocked on guarded noded.
 * @see: hook_hosting_task_guarded_nodes().
 * @see: hook_hosting_task_dangerous_tasks_alter().
 */
function hook_hosting_task_dangerous_tasks() {
  $dangerous_tasks = array(
    'disable',
    'delete',
  );
  return $dangerous_tasks;
}

/**
 * Alter the list of dangerous tasks.
 *
 * @param $nids
 *   A list of tasks as returned by hook_hosting_task_dangerous_tasks().
 */
function hook_hosting_task_dangerous_tasks_alter(&$tasks) {
}

/**
 * @} End of "addtogroup hostinghooks".
 */

/**
 * Easily create a new site and a platform by passing just a name and a makefile URL.
 *
 * To get a new website running from a new codebase in Aegir, you need to create
 * a platform, and then a site node. With the latest version, you can use code
 * to do both at once.
 *
 * This function will create a platform node for /var/aegir/mywebservice/$name
 * using the $makefile specified, and will then create a site node with the URL
 * $name.mywebservice.com.
 */
function example_create_site($name, $makefile) {

  // Create site node.
  $site = new stdClass();
  $site->type = 'site';
  $site->title = "{$name}.mywebservice.com";
  $site->status = 1;
  $site->uid = 1;
  $site->client = HOSTING_DEFAULT_CLIENT;
  $site->site_status = HOSTING_SITE_QUEUED;

  // Create a platform node.
  $platform_node = new stdClass();
  $platform_node->type = 'platform';
  $platform_node->title = "mywebservice_{$name}";
  $platform_node->publish_path = "/var/aegir/mywebservice/{$name}";
  $platform_node->makefile = $makefile;

  // Attach platform node to site node:
  $site->platform_node = $platform_node;

  // Save the site node, along with the platform.
  // This is possible thanks to the patch in https://www.drupal.org/node/2824731
  if ($site = node_submit($site)) {
    node_save($site);
  }
}

Functions

Namesort descending Description
example_create_site Easily create a new site and a platform by passing just a name and a makefile URL.
hook_allow_domain Determine if a site can be created using the specified domain.
hook_drush_context_import Import a backend context into the corresponding frontend node.
hook_hosting_feature Register a hosting feature with Aegir.
hook_hosting_processed_queues_alter Alter module defined queue definitions after they are processed.
hook_hosting_queues Define hosting queues.
hook_hosting_queues_alter Alter module defined queue definitions before they are processed.
hook_hosting_task_dangerous_tasks Return a list of dangerous tasks.
hook_hosting_task_dangerous_tasks_alter Alter the list of dangerous tasks.
hook_hosting_task_guarded_nodes Return a list of Aegir entities to guard against destructive tasks.
hook_hosting_task_guarded_nodes_alter Alter the list of guarded nodes.
hook_hosting_TASK_OBJECT_context_options Add or change context options before a hosting task runs.
hook_hosting_TASK_TYPE_task_rollback Perform actions when a task has failed and has been rolled back.
hook_hosting_task_update_status Reacts any time a task has it's status updated, including when being run in the queue, ending, or being cancelled.
hook_nodeapi_TYPE_OP Act on nodes defined by other modules.
hook_post_hosting_TASK_TYPE_task Perform actions when a task has completed succesfully.
hosting_QUEUE_TYPE_queue Process the specified queue.
hosting_TASK_SINGULAR_list
hosting_TASK_SINGULAR_summary