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.

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_pre_validate Run before a specific command validates.
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_pm_enable Automatically download project dependencies at pm-enable time. Use a pre-pm_enable hook to download before your module is enabled, or a post-pm_enable hook (drush_hook_post_pm_enable) to run after your module is enabled.
hook_drush_cache_clear Add/edit options to cache-clear command
hook_drush_command Declare a new command.
hook_drush_engine_ENGINE_TYPE Inform drush about one or more engines implementing a given engine type.
hook_drush_engine_type_info Inform drush about one or more engine types.
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_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. /**
  13. * All drush commands are invoked in a specific order, using
  14. * drush-made hooks, very similar to the Drupal hook system. See drush_invoke()
  15. * for the actual implementation.
  16. *
  17. * For any commandfile named "hook", the following hooks are called, in
  18. * order, for the command "COMMAND":
  19. *
  20. * 0. drush_COMMAND_init()
  21. * 1. drush_hook_COMMAND_pre_validate()
  22. * 2. drush_hook_COMMAND_validate()
  23. * 3. drush_hook_pre_COMMAND()
  24. * 4. drush_hook_COMMAND()
  25. * 5. drush_hook_post_COMMAND()
  26. *
  27. * For example, here are the hook opportunities for a mysite.drush.inc file
  28. * that wants to hook into the `pm-download` command.
  29. *
  30. * 1. drush_mysite_pm_download_pre_validate()
  31. * 2. drush_mysite_pm_download_validate()
  32. * 3. drush_mysite_pre_pm_download()
  33. * 4. drush_mysite_pm_download()
  34. * 5. drush_mysite_post_pm_download()
  35. *
  36. * Note that the drush_COMMAND_init() hook is only for use by the
  37. * commandfile that defines the command.
  38. *
  39. * If any of hook function fails, either by calling drush_set_error
  40. * or by returning FALSE as its function result, then the rollback
  41. * mechanism is called. To fail with an error, call drush_set_error:
  42. *
  43. * return drush_set_error('MY_ERROR_CODE', dt('Error message.'));
  44. *
  45. * To allow the user to confirm or cancel a command, use drush_confirm
  46. * and drush_user_abort:
  47. *
  48. * if (!drush_confirm(dt('Are you sure?'))) {
  49. * return drush_user_abort();
  50. * }
  51. *
  52. * The rollback mechanism will call, in reverse, all _rollback hooks.
  53. * The mysite command file can implement the following rollback hooks:
  54. *
  55. * 1. drush_mysite_post_pm_download_rollback()
  56. * 2. drush_mysite_pm_download_rollback()
  57. * 3. drush_mysite_pre_pm_download_rollback()
  58. * 4. drush_mysite_pm_download_validate_rollback()
  59. * 5. drush_mysite_pm_download_pre_validate_rollback()
  60. *
  61. * Before any command is called, hook_drush_init() is also called.
  62. * hook_drush_exit() is called at the very end of command invocation.
  63. *
  64. * @see includes/command.inc
  65. *
  66. * @see hook_drush_init()
  67. * @see drush_COMMAND_init()
  68. * @see drush_hook_COMMAND_pre_validate()
  69. * @see drush_hook_COMMAND_validate()
  70. * @see drush_hook_pre_COMMAND()
  71. * @see drush_hook_COMMAND()
  72. * @see drush_hook_post_COMMAND()
  73. * @see drush_hook_post_COMMAND_rollback()
  74. * @see drush_hook_COMMAND_rollback()
  75. * @see drush_hook_pre_COMMAND_rollback()
  76. * @see drush_hook_COMMAND_validate_rollback()
  77. * @see drush_hook_COMMAND_pre_validate_rollback()
  78. * @see hook_drush_exit()
  79. */
  80. /**
  81. * @addtogroup hooks
  82. * @{
  83. */
  84. /**
  85. * Take action before any command is run. Logging an error stops command execution.
  86. */
  87. function hook_drush_init() {
  88. }
  89. /**
  90. * Initialize a command prior to validation. If a command
  91. * needs to bootstrap to a higher level, this is best done in
  92. * the command init hook. It is permisible to bootstrap in
  93. * any hook, but note that if bootstrapping adds more commandfiles
  94. * (*.drush.inc) to the commandfile list, the newly-added
  95. * commandfiles will not have any hooks called until the next
  96. * phase. For example, a command that calls drush_bootstrap_max()
  97. * in drush_hook_COMMAND() would only permit commandfiles from
  98. * modules enabled in the site to participate in drush_hook_post_COMMAND()
  99. * hooks.
  100. */
  101. function drush_COMMAND_init() {
  102. drush_bootstrap_max();
  103. }
  104. /**
  105. * Run before a specific command validates.
  106. *
  107. * Logging an error stops command execution, and the rollback function (if any)
  108. * for each hook implementation is invoked.
  109. *
  110. * @see drush_hook_COMMAND_pre_validate_rollback()
  111. */
  112. function drush_hook_COMMAND_pre_validate() {
  113. }
  114. /**
  115. * Run before a specific command executes.
  116. *
  117. * Logging an error stops command execution, and the rollback function (if any)
  118. * for each hook implementation is invoked.
  119. *
  120. * @see drush_hook_COMMAND_validate_rollback()
  121. */
  122. function drush_hook_COMMAND_validate() {
  123. }
  124. /**
  125. * Run before a specific command executes. Logging an error stops command execution.
  126. *
  127. * Logging an error stops command execution, and the rollback function (if any)
  128. * for each hook implementation is invoked, in addition to the
  129. * validate rollback.
  130. *
  131. * @see drush_hook_pre_COMMAND_rollback()
  132. * @see drush_hook_COMMAND_validate_rollback()
  133. */
  134. function drush_hook_pre_COMMAND() {
  135. }
  136. /**
  137. * Implementation of the actual drush command.
  138. *
  139. * This is where most of the stuff should happen.
  140. *
  141. * Logging an error stops command execution, and the rollback function (if any)
  142. * for each hook implementation is invoked, in addition to pre and
  143. * validate rollbacks.
  144. *
  145. * @return
  146. * The return value will be passed along to the caller if --backend option is
  147. * present. A boolean FALSE indicates failure and rollback will be intitated.
  148. *
  149. * @see drush_hook_COMMAND_rollback()
  150. * @see drush_hook_pre_COMMAND_rollback()
  151. * @see drush_hook_COMMAND_validate_rollback()
  152. */
  153. function drush_hook_COMMAND() {
  154. }
  155. /**
  156. * Run after a specific command executes. Logging an error stops command execution.
  157. *
  158. * Logging an error stops command execution, and the rollback function (if any)
  159. * for each hook implementation is invoked, in addition to pre, normal
  160. * and validate rollbacks.
  161. *
  162. * @see drush_hook_post_COMMAND_rollback()
  163. * @see drush_hook_COMMAND_rollback()
  164. * @see drush_hook_pre_COMMAND_rollback()
  165. * @see drush_hook_COMMAND_validate_rollback()
  166. */
  167. function drush_hook_post_COMMAND() {
  168. }
  169. /**
  170. * Take action after any command is run.
  171. */
  172. function hook_drush_exit() {
  173. }
  174. /*
  175. * A commandfile may choose to decline to load for the current bootstrap
  176. * level by returning FALSE. This hook must be placed in MODULE.drush.load.inc.
  177. * @see drush_commandfile_list().
  178. */
  179. function hook_drush_load() {
  180. }
  181. /**
  182. * Take action after a project has been downloaded.
  183. */
  184. function hook_drush_pm_post_download($project, $release) {
  185. }
  186. /**
  187. * Take action after a project has been updated.
  188. */
  189. function hook_pm_post_update($release_name, $release_candidate_version, $project_parent_path) {
  190. }
  191. /**
  192. * Adjust the location that a project should be copied to after being downloaded.
  193. *
  194. * See @pm_drush_pm_download_destination_alter().
  195. */
  196. function hook_drush_pm_download_destination_alter(&$project, $release) {
  197. if ($some_condition) {
  198. $project['project_install_location'] = '/path/to/install/to/' . $project['project_dir'];
  199. }
  200. }
  201. /**
  202. * Automatically download project dependencies at pm-enable time.
  203. * Use a pre-pm_enable hook to download before your module is enabled,
  204. * or a post-pm_enable hook (drush_hook_post_pm_enable) to run after
  205. * your module is enabled.
  206. *
  207. * Your hook will be called every time pm-enable is executed; you should
  208. * only download dependencies when your module is being enabled. Respect
  209. * the --skip flag, and take no action if it is present.
  210. */
  211. function drush_hook_pre_pm_enable() {
  212. // Get the list of modules being enabled; only download dependencies if our module name appears in the list
  213. $modules = drush_get_context('PM_ENABLE_MODULES');
  214. if (in_array('hook', $modules) && !drush_get_option('skip')) {
  215. $url = 'http://server.com/path/MyLibraryName.tgz';
  216. $path = drush_get_context('DRUSH_DRUPAL_ROOT');
  217. if (module_exists('libraries')) {
  218. $path .= '/' . libraries_get_path('MyLibraryName') . '/MyLibraryName.tgz';
  219. }
  220. else {
  221. $path .= '/'. drupal_get_path('module', 'hook') . '/MyLibraryName.tgz';
  222. }
  223. drush_download_file($url, $path) && drush_tarball_extract($path);
  224. }
  225. }
  226. /**
  227. * Sql-sync sanitization example. This is equivalent to
  228. * the built-in --sanitize option of sql-sync, but simplified
  229. * to only work with default values on Drupal 6 + mysql.
  230. *
  231. * @see sql_drush_sql_sync_sanitize().
  232. */
  233. function hook_drush_sql_sync_sanitize($source) {
  234. drush_sql_register_post_sync_op('my-sanitize-id',
  235. dt('Reset passwords and email addresses in user table'),
  236. "update users set pass = MD5('password'), mail = concat('user+', uid, '@localhost') where uid > 0;");
  237. }
  238. /**
  239. * Add help components to a command
  240. */
  241. function hook_drush_help_alter(&$command) {
  242. if ($command['command'] == 'sql-sync') {
  243. $command['options']['myoption'] = "Description of modification of sql-sync done by hook";
  244. $command['sub-options']['sanitize']['my-sanitize-option'] = "Description of sanitization option added by hook (grouped with --sanitize option)";
  245. }
  246. if ($command['command'] == 'global-options') {
  247. // Recommended: don't show global hook options in brief global options help.
  248. if ($command['#brief'] === FALSE) {
  249. $command['options']['myglobaloption'] = 'Description of option used globally in all commands (e.g. in a commandfile init hook)';
  250. }
  251. }
  252. }
  253. /**
  254. * Add/edit options to cache-clear command
  255. */
  256. function hook_drush_cache_clear(&$types) {
  257. $types['views'] = 'views_invalidate_cache';
  258. }
  259. /**
  260. * Inform drush about one or more engine types.
  261. *
  262. * This hook allow to declare available engine types, the cli option to select
  263. * between engine implementatins, which one to use by default, global options
  264. * and other parameters. Commands may override this info when declaring the
  265. * engines they use.
  266. *
  267. * @return
  268. * An array whose keys are engine type names and whose values describe
  269. * the characteristics of the engine type in relation to command definitions:
  270. *
  271. * - description: The engine type description.
  272. * - option: The command line option to choose an implementation for
  273. * this engine type.
  274. * FALSE means there's no option. That is, the engine type is for internal
  275. * usage of the command and thus an implementation is not selectable.
  276. * - default: The default implementation to use by the engine type.
  277. * - options: Engine options common to all implementations.
  278. * - add-options-to-command: If there's a single implementation for this
  279. * engine type, add its options as command level options.
  280. *
  281. * @see drush_get_engine_types_info()
  282. * @see pm_drush_engine_type_info()
  283. */
  284. function hook_drush_engine_type_info() {
  285. return array(
  286. 'dessert' => array(
  287. 'description' => 'Choose a dessert while the sandwich is baked.',
  288. 'option' => 'dessert',
  289. 'default' => 'ice-cream',
  290. 'options' => 'sweetness',
  291. 'add-options-to-command' => FALSE,
  292. ),
  293. );
  294. }
  295. /**
  296. * Inform drush about one or more engines implementing a given engine type.
  297. *
  298. * This hook allow to declare implementations for an engine type.
  299. *
  300. * @see pm_drush_engine_package_handler()
  301. * @see pm_drush_engine_version_control()
  302. */
  303. function hook_drush_engine_ENGINE_TYPE() {
  304. return array(
  305. 'ice-cream' => array(
  306. 'description' => 'Feature rich ice-cream with all kind of additives.',
  307. 'options' => array(
  308. 'flavour' => 'Choose your favorite flavour',
  309. ),
  310. ),
  311. );
  312. }
  313. /**
  314. * @} End of "addtogroup hooks".
  315. */