hosting.api.php

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

Functions

Namesort descending Description
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_queues Define hosting queues.
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 to tasks ending, with any status.
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

File

hosting.api.php
View source
  1. <?php
  2. /**
  3. * @file
  4. * Hooks provided by the hosting module, and some other random ones.
  5. */
  6. /** @defgroup hostinghooks Frontend hooks
  7. * @{
  8. *
  9. * Those hooks are hooks usable within contrib Drupal modules running
  10. * in the Aegir frontend site.
  11. */
  12. /**
  13. * Determine if a site can be created using the specified domain.
  14. *
  15. * The frontend will only create a specified domains if all implementations of
  16. * this hook return TRUE, so in most cases you will be looking for domains that
  17. * you don't allow, and fallback to a default position of allowing the domain.
  18. *
  19. * @param string $url
  20. * The URL of the site that hosting wishes to create.
  21. * @param array $params
  22. * An array of paramters that may contain information about the site. None of
  23. * the keys are required however, so you should not depend on the value of any
  24. * particular key in this array. If the array is not empty it will usually
  25. * contain at least a 'nid' key whose value is the nid of the site being
  26. * created.
  27. *
  28. * @return bool
  29. * Return TRUE/FALSE if you allow or deny the domain respectively.
  30. *
  31. * @see hosting_domain_allowed()
  32. */
  33. function hook_allow_domain($url, $params) {
  34. // Don't allow another drupal.org, it's special.
  35. if ($url == 'drupal.org') {
  36. return FALSE;
  37. }
  38. else {
  39. return TRUE;
  40. }
  41. }
  42. /**
  43. * Import a backend context into the corresponding frontend node.
  44. *
  45. * This hook will be invoked when an object is being imported from the backend
  46. * into the frontend, for example a site that has just been cloned. You should
  47. * inspect the context coming from the backend and store anything the frontend
  48. * that you need to.
  49. *
  50. * A node to represent the object will have already been created and is
  51. * available to store things in, this node will be automatically saved after all
  52. * implementations of this hook are called. You should not call node_save()
  53. * manually on this node.
  54. *
  55. * If you implement hook_hosting_TASK_OBJECT_context_options() then you will
  56. * probably want to implement this hook also, as they mirror each other.
  57. *
  58. * @param object $context
  59. * The backend context that is being imported.
  60. * @param object $node
  61. * The node object that is being built up from the $context. You should modify
  62. * the fields and properties so that they reflect the contents of the
  63. * $context.
  64. *
  65. * @see hosting_drush_import()
  66. * @see hook_hosting_TASK_OBJECT_context_options()
  67. */
  68. function hook_drush_context_import($context, &$node) {
  69. // From hosting_alias_drush_context_import().
  70. if ($context->type == 'site') {
  71. $node->aliases = $context->aliases;
  72. $node->redirection = $context->redirection;
  73. }
  74. }
  75. /**
  76. * Register a hosting feature with Aegir.
  77. *
  78. * The frontend provides a UI for enabling and disabling features, which usually
  79. * corresponds to enabling and disabling a module providing the feature.
  80. *
  81. * This hook can be implemented in a file named:
  82. * hosting.feature.FEATURE_KEY.inc
  83. *
  84. * Note that the module providing this hook does not need to be enabled for it
  85. * to be called. The frontend will use details in this hook to enable a module
  86. * if the feature is enabled.
  87. *
  88. * @return array
  89. * An array of hosting features, keyed by the machine name of the feature.
  90. * Inner arrays may contain the following keys:
  91. * - 'title': The localised title of the feature.
  92. * - 'description': The localised description of the feature.
  93. * - 'status': The inital status of the feature, either
  94. * HOSTING_FEATURE_DISABLED, HOSTING_FEATURE_ENABLED or
  95. * HOSTING_FEATURE_REQUIRED.
  96. * - 'module': A module to enable or disable whenever the feature is enabled
  97. * or disabled.
  98. * - 'node': A node type that is associated with this feature.
  99. * - 'enable': A function name to call when this feature is enabled.
  100. * - 'disable': A function name to call when this feature is disabled.
  101. * - 'group': The group that this feature belongs to, should be either NULL or
  102. * 'experimental' (or 'required' for core features).
  103. *
  104. * @see hosting_get_features()
  105. */
  106. function hook_hosting_feature() {
  107. // From hosting_example_hosting_feature().
  108. $features['example'] = array(
  109. // Title to display in form.
  110. 'title' => t('Example feature'),
  111. // Description.
  112. 'description' => t('Example feature documenting how to create your own extensions.'),
  113. // Initial status ( HOSTING_FEATURE_DISABLED, HOSTING_FEATURE_ENABLED, HOSTING_FEATURE_REQUIRED )
  114. 'status' => HOSTING_FEATURE_DISABLED,
  115. // Module to enable/disable alongside feature.
  116. 'module' => 'hosting_example',
  117. // Callback functions to execute on enabling or disabling this feature.
  118. 'enable' => 'hosting_example_feature_enable_callback',
  119. 'disable' => 'hosting_example_feature_disable_callback',
  120. // Associate with a specific node type.
  121. // 'node' => 'nodetype',
  122. // Which group to display in ( null , experimental , required )
  123. 'group' => 'experimental',
  124. );
  125. return $features;
  126. }
  127. /**
  128. * Define hosting queues.
  129. *
  130. * @see hosting_get_queues()
  131. */
  132. function hook_hosting_queues() {
  133. }
  134. /**
  135. * Add or change context options before a hosting task runs.
  136. *
  137. * This hook is invoked just before any task that has the 'provision_save' flag
  138. * equal to TRUE. These include the 'install', 'verify' and 'import' tasks.
  139. *
  140. * The TASK_OBJECT will be either: 'server', 'platform' or 'site'.
  141. *
  142. * This gives other modules the chance to send data to the backend to be
  143. * persisted by services there. The entire task is sent so that you have access
  144. * to it, but you should avoid changing things outside of the
  145. * $task->content_options collection.
  146. *
  147. * If you are sending extra context options to the backend based on properties
  148. * in the object's node, then you should also implement the
  149. * hook_drush_context_import() hook to re-create those properties on the node
  150. * when a context is imported.
  151. *
  152. * @param object $task
  153. * The hosting task that is about to be executed, the task is passed by
  154. * reference. The context_options property of this object is about to be saved
  155. * to the backend, so you can make any changes before that happens. Note that
  156. * these changes won't persist in the backend unless you have a service that
  157. * will store them.
  158. *
  159. * The node representing the object of the task, e.g. the site that is being
  160. * verified is available in the $task->ref property.
  161. *
  162. * @see drush_hosting_task()
  163. * @see hook_drush_context_import()
  164. * @see hook_hosting_tasks()
  165. */
  166. function hook_hosting_TASK_OBJECT_context_options(&$task) {
  167. // From hosting_hosting_platform_context_options().
  168. $task->context_options['server'] = '@server_master';
  169. $task->context_options['web_server'] = hosting_context_name($task->ref->web_server);
  170. }
  171. /**
  172. * Perform actions when a task has failed and has been rolled back.
  173. *
  174. * Replace TASK_TYPE with the type of task that if rolled back you will be
  175. * notified of.
  176. *
  177. * @param object $task
  178. * The hosting task that has failed and has been rolled back.
  179. * @param array $data
  180. * An associative array of the drush output of the backend task from
  181. * drush_backend_output(). The array should contain at least the following:
  182. * - "output": The raw output from the drush command executed.
  183. * - "error_status": The error status of the command run on the backend.
  184. * - "log": The drush log messages.
  185. * - "error_log": The list of errors that occurred when running the command.
  186. * - "context": The drush options for the backend command, this may contain
  187. * options that were set when the command ran, or options that were set by
  188. * the command itself.
  189. *
  190. * @see drush_hosting_hosting_task_rollback()
  191. * @see drush_backend_output()
  192. */
  193. function hook_hosting_TASK_TYPE_task_rollback($task, $data) {
  194. // From hosting_site_hosting_install_task_rollback().
  195. // @TODO : we need to check the returned list of errors, not the code.
  196. if (drush_cmp_error('PROVISION_DRUPAL_SITE_INSTALLED')) {
  197. // Site has already been installed. Try to import instead.
  198. drush_log(dt("This site appears to be installed already. Generating an import task."));
  199. hosting_add_task($task->rid, 'import');
  200. }
  201. else {
  202. $task->ref->no_verify = TRUE;
  203. $task->ref->site_status = HOSTING_SITE_DISABLED;
  204. node_save($task->ref);
  205. }
  206. }
  207. /**
  208. * Act on nodes defined by other modules.
  209. *
  210. * This is a more specific version of hook_nodeapi() that includes a node type
  211. * and operation being performed, in the function name. When implementing this
  212. * hook you should replace TYPE with the node type and OP with the node
  213. * operation you would like to be notified for. A list of possible values for OP
  214. * can be found in the documentation for hook_nodeapi().
  215. *
  216. * This hook may help you write code that is easier to follow, but this is a
  217. * hosting specific hook so you may confuse other developers that are not so
  218. * familar with the internals of hosting.
  219. *
  220. * @param object &$node
  221. * The node the action is being performed on.
  222. * @param mixed $a3
  223. * - When OP is "view", passes in the $teaser parameter from node_view().
  224. * - When OP is "validate", passes in the $form parameter from node_validate().
  225. * @param mixed $a4
  226. * - When OP is "view", passes in the $page parameter from node_view().
  227. *
  228. * @return mixed
  229. * This varies depending on the operation (OP).
  230. * - The "presave", "insert", "update", "delete", "print" and "view"
  231. * operations have no return value.
  232. * - The "load" operation should return an array containing pairs
  233. * of fields => values to be merged into the node object.
  234. *
  235. * @see hook_nodeapi()
  236. * @see hosting_nodeapi()
  237. */
  238. function hook_nodeapi_TYPE_OP(&$node, $a3, $a4) {
  239. // From hosting_nodeapi_client_delete_revision().
  240. db_query('DELETE FROM {hosting_client} WHERE vid = %d', $node->vid);
  241. }
  242. /**
  243. * Perform actions when a task has completed succesfully.
  244. *
  245. * Replace TASK_TYPE with the type of task that if completed you will be
  246. * notified of. This is a good place to hook in and record changes in the
  247. * frontend as a result of the task executing in the backend. If you just want
  248. * to hook into the backend then you probably want to consider using the
  249. * 'standard' Drush hooks there, i.e. host_post_provision_verify(),
  250. * hook_post_provision_install() etc.
  251. *
  252. * @param object $task
  253. * The hosting task that has completed.
  254. * @param array $data
  255. * An associative array of the drush output of the completed backend task from
  256. * drush_backend_output(). The array should contain at least the following:
  257. * - "output": The raw output from the drush command executed.
  258. * - "error_status": The error status of the command run on the backend,
  259. * should be DRUSH_SUCCESS normally.
  260. * - "log": The drush log messages.
  261. * - "error_log": The list of errors that occurred when running the command.
  262. * - "context": The drush options for the backend command, this may contain
  263. * options that were set when the command ran, or options that were set by
  264. * the command itself.
  265. *
  266. * @see drush_hosting_post_hosting_task()
  267. * @see drush_backend_output()
  268. */
  269. function hook_post_hosting_TASK_TYPE_task($task, $data) {
  270. // From hosting_site_post_hosting_backup_task().
  271. if ($data['context']['backup_file'] && $task->ref->type == 'site') {
  272. $platform = node_load($task->ref->platform);
  273. $desc = $task->task_args['description'];
  274. $desc = ($desc) ? $desc : t('Generated on request');
  275. hosting_site_add_backup($task->ref->nid, $platform->web_server, $data['context']['backup_file'], $desc, $data['context']['backup_file_size']);
  276. }
  277. }
  278. /**
  279. * Process the specified queue.
  280. *
  281. * Modules providing a queue should implement this function an process the
  282. * number of items from the queue that are specified. It is up the to the
  283. * module to determine which items it wishes to process.
  284. *
  285. * If you wish to process multiple items at the same time you will need to fork
  286. * the process by calling drush_invoke_process() with the 'fork' option,
  287. * specifying a drush command with the arguments required to process your task.
  288. * Otherwise you can do all your processing in this function, or similarly call
  289. * drush_invoke_process() without the 'fork' option.
  290. *
  291. * @param int $count
  292. * The maximum number of items to process.
  293. *
  294. * @see hosting_run_queue()
  295. * @see hosting_get_queues()
  296. */
  297. function hosting_QUEUE_TYPE_queue($count = 5) {
  298. // From hosting_tasks_queue().
  299. global $provision_errors;
  300. drush_log(dt("Running tasks queue"));
  301. $tasks = _hosting_get_new_tasks($count);
  302. foreach ($tasks as $task) {
  303. drush_invoke_process('@self', "hosting-task", array($task->nid), array(), array('fork' => TRUE));
  304. }
  305. }
  306. /**
  307. * @see hosting_queues()
  308. */
  309. function hosting_TASK_SINGULAR_list() {
  310. }
  311. /**
  312. * @see hosting_queue_block()
  313. */
  314. function hosting_TASK_SINGULAR_summary() {
  315. }
  316. /**
  317. * Reacts to tasks ending, with any status.
  318. *
  319. * @param $task
  320. * The task that has just completed.
  321. * @param $status
  322. * The status of that task. Can be HOSTING_TASK_SUCCESS, etc.
  323. */
  324. function hook_hosting_task_update_status($task, $status) {
  325. // A task's "RID" is a node ID for the object the task is run on. (Site, Platform, Server, etc)
  326. $node = node_load($task->rid);
  327. // On error, output a new message.
  328. if ($status == HOSTING_TASK_ERROR) {
  329. drush_log(dt("!title: !task task ended in an Error", array(
  330. '!task' => $task->task_type,
  331. '!title' => $node->title,
  332. )), 'error');
  333. }
  334. else {
  335. drush_log(" Task completed successfully: " . $task->task_type, 'ok');
  336. drush_log(dt("!title: !task task ended with !status", array(
  337. '!task' => $task->task_type,
  338. '!title' => $node->title,
  339. '!status' => _hosting_parse_error_code($status),
  340. )), 'ok');
  341. }
  342. }
  343. /**
  344. * Return a list of Aegir entities to guard against destructive tasks.
  345. *
  346. * @see: hook_hosting_task_dangerous_tasks().
  347. * @see: hook_hosting_task_guarded_nodes_alter();
  348. */
  349. function hook_hosting_task_guarded_nodes() {
  350. // Guard against destructive tasks run on the hostmaster site or platform.
  351. $hostmaster_site_nid = hosting_get_hostmaster_site_nid();
  352. $hostmaster_platform_nid = hosting_get_hostmaster_platform_nid();
  353. $guarded_nids = array(
  354. $hostmaster_site_nid,
  355. $hostmaster_platform_nid,
  356. );
  357. return $guarded_nids;
  358. }
  359. /**
  360. * Alter the list of guarded nodes.
  361. *
  362. * @param $nids
  363. * A list of NIDs as returned by hook_hosting_task_guarded_nodes().
  364. */
  365. function hook_hosting_task_guarded_nodes_alter(&$nids) {}
  366. /**
  367. * Return a list of dangerous tasks.
  368. *
  369. * These tasks will be blocked on guarded noded.
  370. * @see: hook_hosting_task_guarded_nodes().
  371. * @see: hook_hosting_task_dangerous_tasks_alter().
  372. */
  373. function hook_hosting_task_dangerous_tasks() {
  374. $dangerous_tasks = array(
  375. 'disable',
  376. 'delete',
  377. );
  378. return $dangerous_tasks;
  379. }
  380. /**
  381. * Alter the list of dangerous tasks.
  382. *
  383. * @param $nids
  384. * A list of tasks as returned by hook_hosting_task_dangerous_tasks().
  385. */
  386. function hook_hosting_task_dangerous_tasks_alter(&$tasks) {}
  387. /**
  388. * @} End of "addtogroup hostinghooks".
  389. */