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_command_alter A commandfile may adjust the contents of any command structure prior to dispatch.
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_invoke_alter Alter the order that hooks are invoked.
hook_drush_load A commandfile may choose to decline to load for the current bootstrap level by returning FALSE. This hook must be placed in MODULE.drush.load.inc.
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. * A commandfile may adjust the contents of any command structure
  183. * prior to dispatch. @see core_drush_command_alter() for an example.
  184. */
  185. function hook_drush_command_alter(&$command) {
  186. }
  187. /**
  188. * Take action after a project has been downloaded.
  189. */
  190. function hook_drush_pm_post_download($project, $release) {
  191. }
  192. /**
  193. * Take action after a project has been updated.
  194. */
  195. function hook_pm_post_update($release_name, $release_candidate_version, $project_parent_path) {
  196. }
  197. /**
  198. * Adjust the location that a project should be copied to after being downloaded.
  199. *
  200. * See @pm_drush_pm_download_destination_alter().
  201. */
  202. function hook_drush_pm_download_destination_alter(&$project, $release) {
  203. if ($some_condition) {
  204. $project['project_install_location'] = '/path/to/install/to/' . $project['project_dir'];
  205. }
  206. }
  207. /**
  208. * Automatically download project dependencies at pm-enable time.
  209. * Use a pre-pm_enable hook to download before your module is enabled,
  210. * or a post-pm_enable hook (drush_hook_post_pm_enable) to run after
  211. * your module is enabled.
  212. *
  213. * Your hook will be called every time pm-enable is executed; you should
  214. * only download dependencies when your module is being enabled. Respect
  215. * the --skip flag, and take no action if it is present.
  216. */
  217. function drush_hook_pre_pm_enable() {
  218. // Get the list of modules being enabled; only download dependencies if our module name appears in the list
  219. $modules = drush_get_context('PM_ENABLE_MODULES');
  220. if (in_array('hook', $modules) && !drush_get_option('skip')) {
  221. $url = 'http://server.com/path/MyLibraryName.tgz';
  222. $path = drush_get_context('DRUSH_DRUPAL_ROOT');
  223. if (module_exists('libraries')) {
  224. $path .= '/' . libraries_get_path('MyLibraryName') . '/MyLibraryName.tgz';
  225. }
  226. else {
  227. $path .= '/'. drupal_get_path('module', 'hook') . '/MyLibraryName.tgz';
  228. }
  229. drush_download_file($url, $path) && drush_tarball_extract($path);
  230. }
  231. }
  232. /**
  233. * Sql-sync sanitization example. This is equivalent to
  234. * the built-in --sanitize option of sql-sync, but simplified
  235. * to only work with default values on Drupal 6 + mysql.
  236. *
  237. * @see sql_drush_sql_sync_sanitize().
  238. */
  239. function hook_drush_sql_sync_sanitize($source) {
  240. drush_sql_register_post_sync_op('my-sanitize-id',
  241. dt('Reset passwords and email addresses in user table.'),
  242. "UPDATE users SET pass = MD5('password'), mail = concat('user+', uid, '@localhost') WHERE uid > 0;");
  243. }
  244. /**
  245. * Add help components to a command
  246. */
  247. function hook_drush_help_alter(&$command) {
  248. if ($command['command'] == 'sql-sync') {
  249. $command['options']['myoption'] = "Description of modification of sql-sync done by hook";
  250. $command['sub-options']['sanitize']['my-sanitize-option'] = "Description of sanitization option added by hook (grouped with --sanitize option)";
  251. }
  252. if ($command['command'] == 'global-options') {
  253. // Recommended: don't show global hook options in brief global options help.
  254. if ($command['#brief'] === FALSE) {
  255. $command['options']['myglobaloption'] = 'Description of option used globally in all commands (e.g. in a commandfile init hook)';
  256. }
  257. }
  258. }
  259. /**
  260. * Add/edit options to cache-clear command
  261. */
  262. function hook_drush_cache_clear(&$types) {
  263. $types['views'] = 'views_invalidate_cache';
  264. }
  265. /**
  266. * Inform drush about one or more engine types.
  267. *
  268. * This hook allow to declare available engine types, the cli option to select
  269. * between engine implementatins, which one to use by default, global options
  270. * and other parameters. Commands may override this info when declaring the
  271. * engines they use.
  272. *
  273. * @return
  274. * An array whose keys are engine type names and whose values describe
  275. * the characteristics of the engine type in relation to command definitions:
  276. *
  277. * - description: The engine type description.
  278. * - topic: If specified, the name of the topic command that will
  279. * display the automatically generated topic for this engine.
  280. * - topic-file: If specified, the path to the file that will be
  281. * displayed at the head of the automatically generated topic for
  282. * this engine. This path is relative to the Drush root directory;
  283. * non-core commandfiles should therefore use:
  284. * 'topic-file' => dirname(__FILE__) . '/mytopic.html';
  285. * - topics: If set, contains a list of topics that should be added to
  286. * the "Topics" section of any command that uses this engine. Note
  287. * that if 'topic' is set, it will automatically be added to the topics
  288. * list, and therefore does not need to also be listed here.
  289. * - option: The command line option to choose an implementation for
  290. * this engine type.
  291. * FALSE means there's no option. That is, the engine type is for internal
  292. * usage of the command and thus an implementation is not selectable.
  293. * - default: The default implementation to use by the engine type.
  294. * - options: Engine options common to all implementations.
  295. * - add-options-to-command: If there's a single implementation for this
  296. * engine type, add its options as command level options.
  297. * - combine-help: If there are multiple implementations for this engine
  298. * type, then instead of adding multiple help items in the form of
  299. * --engine-option=engine-type [description], instead combine all help
  300. * options into a single --engine-option that lists the different possible
  301. * values that can be used.
  302. *
  303. * @see drush_get_engine_types_info()
  304. * @see pm_drush_engine_type_info()
  305. */
  306. function hook_drush_engine_type_info() {
  307. return array(
  308. 'dessert' => array(
  309. 'description' => 'Choose a dessert while the sandwich is baked.',
  310. 'option' => 'dessert',
  311. 'default' => 'ice-cream',
  312. 'options' => 'sweetness',
  313. 'add-options-to-command' => FALSE,
  314. ),
  315. );
  316. }
  317. /**
  318. * Inform drush about one or more engines implementing a given engine type.
  319. *
  320. * - description: The engine implementation's description.
  321. * - engine-class: The class that contains the engine implementation.
  322. * Defaults to the engine type key (e.g. 'ice-cream').
  323. * - verbose-only: The engine implementation will only appear in help
  324. * output in --verbose mode.
  325. *
  326. * This hook allow to declare implementations for an engine type.
  327. *
  328. * @see pm_drush_engine_package_handler()
  329. * @see pm_drush_engine_version_control()
  330. */
  331. function hook_drush_engine_ENGINE_TYPE() {
  332. return array(
  333. 'ice-cream' => array(
  334. 'description' => 'Feature rich ice-cream with all kind of additives.',
  335. 'options' => array(
  336. 'flavour' => 'Choose your favorite flavour',
  337. ),
  338. ),
  339. );
  340. }
  341. /**
  342. * Alter the order that hooks are invoked.
  343. *
  344. * When implementing a given hook we may need to ensure it is invoked before
  345. * or after another implementation of the same hook. For example, let's say
  346. * you want to implement a hook that would be called after drush_make. You'd
  347. * write a drush_MY_MODULE_post_make() function. But if you need your hook to
  348. * be called before drush_make_post_make(), you can ensure this by implemen-
  349. * ting MY_MODULE_drush_invoke_alter().
  350. *
  351. * @see drush_command_invoke_all_ref()
  352. */
  353. function hook_drush_invoke_alter($modules, $hook) {
  354. if ($hook == 'some_hook') {
  355. // Take the module who's hooks would normally be called last
  356. $module = array_pop($modules);
  357. // Ensure it'll be called first for 'some_hook'
  358. array_unshift($modules, $module);
  359. }
  360. }
  361. /**
  362. * @} End of "addtogroup hooks".
  363. */