drush.api.php

  1. 8.0.x drush.api.php
  2. 6.x docs/drush.api.php
  3. 7.x drush.api.php
  4. 3.x drush.api.php
  5. 4.x docs/drush.api.php
  6. 5.x docs/drush.api.php
  7. master drush.api.php

Documentation of the Drush API.

Declare a new command.

Functions

Namesort descending Description
drush_COMMAND_init Initialize a command prior to validation. If a command needs to bootstrap to a higher level, this is best done in the command init hook. It is permisible to bootstrap in any hook, but note that if bootstrapping adds more commandfiles (*.drush.inc)…
drush_hook_COMMAND Implementation of the actual drush command.
drush_hook_COMMAND_validate Run before a specific command executes.
drush_hook_post_COMMAND Run after a specific command executes. Logging an error stops command execution.
drush_hook_pre_COMMAND Run before a specific command executes. Logging an error stops command execution.
drush_hook_pre_site_upgrade_prepare Take action before modules are disabled in a major upgrade. Note that when this hook fires, it will be operating on a copy of the database.
hook_cli_bashrc
hook_drush_cache_clear Add/edit options to cache-clear command
hook_drush_command @file Documentation of the Drush API.
hook_drush_exit Take action after any command is run.
hook_drush_help_alter Add help components to a command
hook_drush_init Take action before any command is run. Logging an error stops command execution.
hook_drush_load
hook_drush_pm_download_destination_alter Adjust the location that a project should be copied to after being downloaded.
hook_drush_pm_post_download Take action after a project has been downloaded.
hook_drush_sql_sync_sanitize Sql-sync sanitization example. This is equivalent to the built-in --sanitize option of sql-sync, but simplified to only work with default values on Drupal 6 + mysql.
hook_drush_upgrade_project_map_alter Add information to the upgrade project map; this information will be shown to the user when upgrading Drupal to the next major version if the module containing this hook is enabled.
hook_pm_post_update Take action after a project has been updated.

File

docs/drush.api.php
View source
  1. <?php
  2. /**
  3. * @file
  4. * Documentation of the Drush API.
  5. *
  6. /**
  7. * Declare a new command.
  8. */
  9. function hook_drush_command() {
  10. // To learn more, run `drush topic docs-commands` and `drush topic docs-examplecommand`
  11. }
  12. /* All drush commands are invoked in a specific order, using
  13. * drush-made hooks, very similar to the Drupal hook system. See drush_invoke()
  14. * for the actual implementation.
  15. *
  16. * For any commandfile named "hook", the following hooks are called, in
  17. * order, for the command "COMMAND":
  18. *
  19. * 0. drush_COMMAND_init()
  20. * 1. drush_hook_COMMAND_validate()
  21. * 2. drush_hook_pre_COMMAND()
  22. * 3. drush_hook_COMMAND()
  23. * 4. drush_hook_post_COMMAND()
  24. *
  25. * For example, here are the hook opportunities for a mysite.drush.inc file
  26. * that wants to hook into the `pm-download` command.
  27. *
  28. * 1. drush_mysite_pm_download_validate()
  29. * 2. drush_mysite_pre_pm_download()
  30. * 3. drush_mysite_pm_download()
  31. * 4. drush_mysite_post_pm_download()
  32. *
  33. * Note that the drush_COMMAND_init() hook is only for use by the
  34. * commandfile that defines the command.
  35. *
  36. * If any of hook function fails, either by calling drush_set_error
  37. * or by returning FALSE as its function result, then the rollback
  38. * mechanism is called. To fail with an error, call drush_set_error:
  39. *
  40. * return drush_set_error('MY_ERROR_CODE', dt('Error message.'));
  41. *
  42. * To allow the user to confirm or cancel a command, use drush_confirm
  43. * and drush_user_abort:
  44. *
  45. * if (!drush_confirm(dt('Are you sure?'))) {
  46. * return drush_user_abort();
  47. * }
  48. *
  49. * The rollback mechanism will call, in reverse, all _rollback hooks.
  50. * The mysite command file can implement the following rollback hooks:
  51. *
  52. * 1. drush_mysite_post_pm_download_rollback()
  53. * 2. drush_mysite_pm_download_rollback()
  54. * 3. drush_mysite_pre_pm_download_rollback()
  55. * 4. drush_mysite_pm_download_validate_rollback()
  56. *
  57. * Before any command is called, hook_drush_init() is also called.
  58. * hook_drush_exit() is called at the very end of command invocation.
  59. *
  60. * @see includes/command.inc
  61. *
  62. * @see hook_drush_init()
  63. * @see drush_COMMAND_init()
  64. * @see drush_hook_COMMAND_validate()
  65. * @see drush_hook_pre_COMMAND()
  66. * @see drush_hook_COMMAND()
  67. * @see drush_hook_post_COMMAND()
  68. * @see drush_hook_post_COMMAND_rollback()
  69. * @see drush_hook_COMMAND_rollback()
  70. * @see drush_hook_pre_COMMAND_rollback()
  71. * @see drush_hook_COMMAND_validate_rollback()
  72. * @see hook_drush_exit()
  73. */
  74. /**
  75. * @addtogroup hooks
  76. * @{
  77. */
  78. /**
  79. * Take action before any command is run. Logging an error stops command execution.
  80. */
  81. function hook_drush_init() {
  82. }
  83. /**
  84. * Initialize a command prior to validation. If a command
  85. * needs to bootstrap to a higher level, this is best done in
  86. * the command init hook. It is permisible to bootstrap in
  87. * any hook, but note that if bootstrapping adds more commandfiles
  88. * (*.drush.inc) to the commandfile list, the newly-added
  89. * commandfiles will not have any hooks called until the next
  90. * phase. For example, a command that calls drush_bootstrap_max()
  91. * in drush_hook_COMMAND() would only permit commandfiles from
  92. * modules enabled in the site to participate in drush_hook_post_COMMAND()
  93. * hooks.
  94. */
  95. function drush_COMMAND_init() {
  96. drush_bootstrap_max();
  97. }
  98. /**
  99. * Run before a specific command executes.
  100. *
  101. * Logging an error stops command execution, and the rollback function (if any)
  102. * for each hook implementation is invoked.
  103. *
  104. * @see drush_hook_COMMAND_validate_rollback()
  105. */
  106. function drush_hook_COMMAND_validate() {
  107. }
  108. /**
  109. * Run before a specific command executes. Logging an error stops command execution.
  110. *
  111. * Logging an error stops command execution, and the rollback function (if any)
  112. * for each hook implementation is invoked, in addition to the
  113. * validate rollback.
  114. *
  115. * @see drush_hook_pre_COMMAND_rollback()
  116. * @see drush_hook_COMMAND_validate_rollback()
  117. */
  118. function drush_hook_pre_COMMAND() {
  119. }
  120. /**
  121. * Implementation of the actual drush command.
  122. *
  123. * This is where most of the stuff should happen.
  124. *
  125. * Logging an error stops command execution, and the rollback function (if any)
  126. * for each hook implementation is invoked, in addition to pre and
  127. * validate rollbacks.
  128. *
  129. * @see drush_hook_COMMAND_rollback()
  130. * @see drush_hook_pre_COMMAND_rollback()
  131. * @see drush_hook_COMMAND_validate_rollback()
  132. */
  133. function drush_hook_COMMAND() {
  134. }
  135. /**
  136. * Run after a specific command executes. Logging an error stops command execution.
  137. *
  138. * Logging an error stops command execution, and the rollback function (if any)
  139. * for each hook implementation is invoked, in addition to pre, normal
  140. * and validate rollbacks.
  141. *
  142. * @see drush_hook_post_COMMAND_rollback()
  143. * @see drush_hook_COMMAND_rollback()
  144. * @see drush_hook_pre_COMMAND_rollback()
  145. * @see drush_hook_COMMAND_validate_rollback()
  146. */
  147. function drush_hook_post_COMMAND() {
  148. }
  149. /**
  150. * Take action after any command is run.
  151. */
  152. function hook_drush_exit() {
  153. }
  154. /*
  155. * A commandfile may choose to decline to load for the current bootstrap
  156. * level by returning FALSE. This hook must be placed in MODULE.drush.load.inc.
  157. * @see drush_commandfile_list().
  158. */
  159. function hook_drush_load() {
  160. }
  161. /**
  162. * Take action after a project has been downloaded.
  163. */
  164. function hook_drush_pm_post_download($project, $release) {
  165. }
  166. /**
  167. * Take action after a project has been updated.
  168. */
  169. function hook_pm_post_update($release_name, $release_candidate_version, $project_parent_path) {
  170. }
  171. /**
  172. * Adjust the location that a project should be copied to after being downloaded.
  173. *
  174. * See @pm_drush_pm_download_destination_alter().
  175. */
  176. function hook_drush_pm_download_destination_alter(&$project, $release) {
  177. if ($some_condition) {
  178. $project['project_install_location'] = '/path/to/install/to/' . $project['project_dir'];
  179. }
  180. }
  181. /**
  182. * Add information to the upgrade project map; this information
  183. * will be shown to the user when upgrading Drupal to the next
  184. * major version if the module containing this hook is enabled.
  185. *
  186. * @see drush_upgrade_project_map().
  187. */
  188. function hook_drush_upgrade_project_map_alter(&$project_map) {
  189. $project_map['warning']['hook'] = dt("You need to take special action before upgrading this module. See http://mysite.com/mypage for more information.");
  190. }
  191. /**
  192. * Sql-sync sanitization example. This is equivalent to
  193. * the built-in --sanitize option of sql-sync, but simplified
  194. * to only work with default values on Drupal 6 + mysql.
  195. *
  196. * @see sql_drush_sql_sync_sanitize().
  197. */
  198. function hook_drush_sql_sync_sanitize($source) {
  199. drush_sql_register_post_sync_op('my-sanitize-id',
  200. dt('Reset passwords and email addresses in user table'),
  201. "update users set pass = MD5('password'), mail = concat('user+', uid, '@localhost') where uid > 0;");
  202. }
  203. /**
  204. * Take action before modules are disabled in a major upgrade.
  205. * Note that when this hook fires, it will be operating on a
  206. * copy of the database.
  207. */
  208. function drush_hook_pre_site_upgrade_prepare() {
  209. // site upgrade prepare will disable contrib_extensions and
  210. // uninstall the uninstall_extension
  211. $contrib_extensions = func_get_args();
  212. $uninstall_extensions = explode(',', drush_get_option('uninstall', ''));
  213. }
  214. /**
  215. * Add help components to a command
  216. */
  217. function hook_drush_help_alter(&$command) {
  218. if ($command['command'] == 'sql-sync') {
  219. $command['options']['myoption'] = "Description of modification of sql-sync done by hook";
  220. $command['sub-options']['sanitize']['my-sanitize-option'] = "Description of sanitization option added by hook (grouped with --sanitize option)";
  221. }
  222. }
  223. /**
  224. * Add/edit options to cache-clear command
  225. */
  226. function hook_drush_cache_clear(&$types) {
  227. $types['views'] = 'views_invalidate_cache';
  228. }
  229. /*
  230. * Make shell aliases and other .bashrc code available during core-cli command.
  231. *
  232. * @return
  233. * Bash code typically found in a .bashrc file.
  234. *
  235. * @see core_cli_bashrc() for an example implementation.
  236. */
  237. function hook_cli_bashrc() {
  238. $string = "
  239. alias siwef='drush site-install wef --account-name=super --account-mail=me@wef'
  240. alias dump='drush sql-dump --structure-tables-key=wef --ordered-dump'
  241. ";
  242. return $string;
  243. }
  244. /**
  245. * @} End of "addtogroup hooks".
  246. */