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.
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.
drush_hook_pre_COMMAND Run before a specific command executes.
drush_hook_pre_pm_enable Automatically download project dependencies at pm-enable time.
hook_drush_cache_clear Add/edit options to cache-clear command.
hook_drush_command Declare a new command.
hook_drush_command_alter 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.
hook_drush_invoke_alter Alter the order that hooks are invoked.
hook_drush_pm_download_destination_alter Adjust the location a project should be copied to after being downloaded.
hook_drush_pm_post_download Take action after a project has been downloaded.
hook_drush_sitealias_alter Adjust the contents of a site alias.
hook_drush_sql_sync_sanitize Sql-sync sanitization example.
hook_pm_post_update Take action after a project has been updated.

File

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
  11. // `drush topic docs-examplecommand`.
  12. }
  13. /**
  14. * All drush commands are invoked in a specific order, using
  15. * drush-made hooks, very similar to the Drupal hook system. See drush_invoke()
  16. * for the actual implementation.
  17. *
  18. * For any commandfile named "hook", the following hooks are called, in
  19. * order, for the command "COMMAND":
  20. *
  21. * 0. drush_COMMAND_init()
  22. * 1. drush_hook_COMMAND_pre_validate()
  23. * 2. drush_hook_COMMAND_validate()
  24. * 3. drush_hook_pre_COMMAND()
  25. * 4. drush_hook_COMMAND()
  26. * 5. drush_hook_post_COMMAND()
  27. *
  28. * For example, here are the hook opportunities for a mysite.drush.inc file
  29. * that wants to hook into the `pm-download` command.
  30. *
  31. * 1. drush_mysite_pm_download_pre_validate()
  32. * 2. drush_mysite_pm_download_validate()
  33. * 3. drush_mysite_pre_pm_download()
  34. * 4. drush_mysite_pm_download()
  35. * 5. drush_mysite_post_pm_download()
  36. *
  37. * Note that the drush_COMMAND_init() hook is only for use by the
  38. * commandfile that defines the command.
  39. *
  40. * If any of hook function fails, either by calling drush_set_error
  41. * or by returning FALSE as its function result, then the rollback
  42. * mechanism is called. To fail with an error, call drush_set_error:
  43. *
  44. * return drush_set_error('MY_ERROR_CODE', dt('Error message.'));
  45. *
  46. * To allow the user to confirm or cancel a command, use drush_confirm
  47. * and drush_user_abort:
  48. *
  49. * if (!drush_confirm(dt('Are you sure?'))) {
  50. * return drush_user_abort();
  51. * }
  52. *
  53. * The rollback mechanism will call, in reverse, all _rollback hooks.
  54. * The mysite command file can implement the following rollback hooks:
  55. *
  56. * 1. drush_mysite_post_pm_download_rollback()
  57. * 2. drush_mysite_pm_download_rollback()
  58. * 3. drush_mysite_pre_pm_download_rollback()
  59. * 4. drush_mysite_pm_download_validate_rollback()
  60. * 5. drush_mysite_pm_download_pre_validate_rollback()
  61. *
  62. * Before any command is called, hook_drush_init() is also called.
  63. * hook_drush_exit() is called at the very end of command invocation.
  64. *
  65. * @see includes/command.inc
  66. *
  67. * @see hook_drush_init()
  68. * @see drush_COMMAND_init()
  69. * @see drush_hook_COMMAND_pre_validate()
  70. * @see drush_hook_COMMAND_validate()
  71. * @see drush_hook_pre_COMMAND()
  72. * @see drush_hook_COMMAND()
  73. * @see drush_hook_post_COMMAND()
  74. * @see drush_hook_post_COMMAND_rollback()
  75. * @see drush_hook_COMMAND_rollback()
  76. * @see drush_hook_pre_COMMAND_rollback()
  77. * @see drush_hook_COMMAND_validate_rollback()
  78. * @see drush_hook_COMMAND_pre_validate_rollback()
  79. * @see hook_drush_exit()
  80. */
  81. /**
  82. * @addtogroup hooks
  83. * @{
  84. */
  85. /**
  86. * Take action before any command is run.
  87. *
  88. * Logging an error stops command execution.
  89. */
  90. function hook_drush_init() {
  91. }
  92. /**
  93. * Initialize a command prior to validation.
  94. *
  95. * If a command needs to bootstrap to a higher level, this is best done in the
  96. * command init hook. It is permisible to bootstrap in any hook, but note that
  97. * if bootstrapping adds more commandfiles (*.drush.inc) to the commandfile
  98. * list, the newly-added commandfiles will not have any hooks called until the
  99. * next phase. For example, a command that calls drush_bootstrap_max() in
  100. * drush_hook_COMMAND() would only permit commandfiles from modules enabled in
  101. * the site to participate in drush_hook_post_COMMAND() hooks.
  102. */
  103. function drush_COMMAND_init() {
  104. drush_bootstrap_max();
  105. }
  106. /**
  107. * Run before a specific command validates.
  108. *
  109. * Logging an error stops command execution, and the rollback function (if any)
  110. * for each hook implementation is invoked.
  111. *
  112. * @see drush_hook_COMMAND_pre_validate_rollback()
  113. */
  114. function drush_hook_COMMAND_pre_validate() {
  115. }
  116. /**
  117. * Run before a specific command executes.
  118. *
  119. * Logging an error stops command execution, and the rollback function (if any)
  120. * for each hook implementation is invoked.
  121. *
  122. * @see drush_hook_COMMAND_validate_rollback()
  123. */
  124. function drush_hook_COMMAND_validate() {
  125. }
  126. /**
  127. * Run before a specific command executes.
  128. *
  129. * Logging an error stops command execution, and the rollback function (if any)
  130. * for each hook implementation is invoked, in addition to the validate
  131. * rollback.
  132. *
  133. * @see drush_hook_pre_COMMAND_rollback()
  134. * @see drush_hook_COMMAND_validate_rollback()
  135. */
  136. function drush_hook_pre_COMMAND() {
  137. }
  138. /**
  139. * Implementation of the actual drush command.
  140. *
  141. * This is where most of the stuff should happen.
  142. *
  143. * Logging an error stops command execution, and the rollback function (if any)
  144. * for each hook implementation is invoked, in addition to pre and
  145. * validate rollbacks.
  146. *
  147. * @return mixed|false
  148. * The return value will be passed along to the caller if --backend option is
  149. * present. A boolean FALSE indicates failure and rollback will be inititated.
  150. *
  151. * @see drush_hook_COMMAND_rollback()
  152. * @see drush_hook_pre_COMMAND_rollback()
  153. * @see drush_hook_COMMAND_validate_rollback()
  154. */
  155. function drush_hook_COMMAND() {
  156. }
  157. /**
  158. * Run after a specific command executes.
  159. *
  160. * Logging an error stops command execution, and the rollback function (if any)
  161. * for each hook implementation is invoked, in addition to pre, normal
  162. * and validate rollbacks.
  163. *
  164. * @see drush_hook_post_COMMAND_rollback()
  165. * @see drush_hook_COMMAND_rollback()
  166. * @see drush_hook_pre_COMMAND_rollback()
  167. * @see drush_hook_COMMAND_validate_rollback()
  168. */
  169. function drush_hook_post_COMMAND() {
  170. }
  171. /**
  172. * Take action after any command is run.
  173. */
  174. function hook_drush_exit() {
  175. }
  176. /**
  177. * Adjust the contents of any command structure prior to dispatch.
  178. *
  179. * @see core_drush_command_alter()
  180. */
  181. function hook_drush_command_alter(&$command) {
  182. }
  183. /**
  184. * Adjust the contents of a site alias.
  185. */
  186. function hook_drush_sitealias_alter(&$alias_record) {
  187. // If the alias is "remote", but the remote site is
  188. // the system this command is running on, convert the
  189. // alias record to a local alias.
  190. if (isset($alias_record['remote-host'])) {
  191. $uname = php_uname('n');
  192. if ($alias_record['remote-host'] == $uname) {
  193. unset($alias_record['remote-host']);
  194. unset($alias_record['remote-user']);
  195. }
  196. }
  197. }
  198. /**
  199. * Take action after a project has been downloaded.
  200. */
  201. function hook_drush_pm_post_download($project, $release) {
  202. }
  203. /**
  204. * Take action after a project has been updated.
  205. */
  206. function hook_pm_post_update($project_name, $installed_release, $project) {
  207. }
  208. /**
  209. * Adjust the location a project should be copied to after being downloaded.
  210. *
  211. * See @pm_drush_pm_download_destination_alter().
  212. */
  213. function hook_drush_pm_download_destination_alter(&$project, $release) {
  214. if ($some_condition) {
  215. $project['project_install_location'] = '/path/to/install/to/' . $project['project_dir'];
  216. }
  217. }
  218. /**
  219. * Automatically download project dependencies at pm-enable time.
  220. *
  221. * Use a pre-pm_enable hook to download before your module is enabled,
  222. * or a post-pm_enable hook (drush_hook_post_pm_enable) to run after
  223. * your module is enabled.
  224. *
  225. * Your hook will be called every time pm-enable is executed; you should
  226. * only download dependencies when your module is being enabled. Respect
  227. * the --skip flag, and take no action if it is present.
  228. */
  229. function drush_hook_pre_pm_enable() {
  230. // Get the list of modules being enabled; only download dependencies if our
  231. // module name appears in the list.
  232. $modules = drush_get_context('PM_ENABLE_MODULES');
  233. if (in_array('hook', $modules) && !drush_get_option('skip')) {
  234. $url = 'http://server.com/path/MyLibraryName.tgz';
  235. $path = drush_get_context('DRUSH_DRUPAL_ROOT');
  236. drush_include_engine('drupal', 'environment');
  237. if (drush_module_exists('libraries')) {
  238. $path .= '/' . libraries_get_path('MyLibraryName') . '/MyLibraryName.tgz';
  239. }
  240. else {
  241. $path .= '/' . drupal_get_path('module', 'hook') . '/MyLibraryName.tgz';
  242. }
  243. drush_download_file($url, $path) && drush_tarball_extract($path);
  244. }
  245. }
  246. /**
  247. * Sql-sync sanitization example.
  248. *
  249. * This is equivalent to the built-in --sanitize option of sql-sync, but
  250. * simplified to only work with default values on Drupal 6 + mysql.
  251. *
  252. * @see sql_drush_sql_sync_sanitize()
  253. */
  254. function hook_drush_sql_sync_sanitize($source) {
  255. drush_sql_register_post_sync_op('my-sanitize-id',
  256. dt('Reset passwords and email addresses in user table.'),
  257. "UPDATE users SET pass = MD5('password'), mail = concat('user+', uid, '@localhost') WHERE uid > 0;");
  258. }
  259. /**
  260. * Add help components to a command.
  261. */
  262. function hook_drush_help_alter(&$command) {
  263. if ($command['command'] == 'sql-sync') {
  264. $command['options']['myoption'] = "Description of modification of sql-sync done by hook";
  265. $command['sub-options']['sanitize']['my-sanitize-option'] = "Description of sanitization option added by hook (grouped with --sanitize option)";
  266. }
  267. if ($command['command'] == 'global-options') {
  268. // Recommended: don't show global hook options in brief global options help.
  269. if ($command['#brief'] === FALSE) {
  270. $command['options']['myglobaloption'] = 'Description of option used globally in all commands (e.g. in a commandfile init hook)';
  271. }
  272. }
  273. }
  274. /**
  275. * Add/edit options to cache-clear command.
  276. *
  277. * @param array $types
  278. * Adjust types as needed. Is passed by reference.
  279. *
  280. * @param bool $include_bootstrapped_types
  281. * If FALSE, omit types which require a FULL bootstrap.
  282. */
  283. function hook_drush_cache_clear(&$types, $include_bootstrapped_types) {
  284. $types['views'] = 'views_invalidate_cache';
  285. }
  286. /**
  287. * Inform drush about one or more engine types.
  288. *
  289. * This hook allow to declare available engine types, the cli option to select
  290. * between engine implementatins, which one to use by default, global options
  291. * and other parameters. Commands may override this info when declaring the
  292. * engines they use.
  293. *
  294. * @return array
  295. * An array whose keys are engine type names and whose values describe
  296. * the characteristics of the engine type in relation to command definitions:
  297. *
  298. * - description: The engine type description.
  299. * - topic: If specified, the name of the topic command that will
  300. * display the automatically generated topic for this engine.
  301. * - topic-file: If specified, the path to the file that will be
  302. * displayed at the head of the automatically generated topic for
  303. * this engine. This path is relative to the Drush root directory;
  304. * non-core commandfiles should therefore use:
  305. * 'topic-file' => dirname(__FILE__) . '/mytopic.html';
  306. * - topics: If set, contains a list of topics that should be added to
  307. * the "Topics" section of any command that uses this engine. Note
  308. * that if 'topic' is set, it will automatically be added to the topics
  309. * list, and therefore does not need to also be listed here.
  310. * - option: The command line option to choose an implementation for
  311. * this engine type.
  312. * FALSE means there's no option. That is, the engine type is for internal
  313. * usage of the command and thus an implementation is not selectable.
  314. * - default: The default implementation to use by the engine type.
  315. * - options: Engine options common to all implementations.
  316. * - add-options-to-command: If there's a single implementation for this
  317. * engine type, add its options as command level options.
  318. * - combine-help: If there are multiple implementations for this engine
  319. * type, then instead of adding multiple help items in the form of
  320. * --engine-option=engine-type [description], instead combine all help
  321. * options into a single --engine-option that lists the different possible
  322. * values that can be used.
  323. *
  324. * @see drush_get_engine_types_info()
  325. * @see pm_drush_engine_type_info()
  326. */
  327. function hook_drush_engine_type_info() {
  328. return array(
  329. 'dessert' => array(
  330. 'description' => 'Choose a dessert while the sandwich is baked.',
  331. 'option' => 'dessert',
  332. 'default' => 'ice-cream',
  333. 'options' => 'sweetness',
  334. 'add-options-to-command' => FALSE,
  335. ),
  336. );
  337. }
  338. /**
  339. * Inform drush about one or more engines implementing a given engine type.
  340. *
  341. * - description: The engine implementation's description.
  342. * - implemented-by: The engine that actually implements this engine.
  343. * This is useful to allow the implementation of similar engines
  344. * in the reference one.
  345. * Defaults to the engine type key (e.g. 'ice-cream').
  346. * - verbose-only: The engine implementation will only appear in help
  347. * output in --verbose mode.
  348. *
  349. * This hook allow to declare implementations for an engine type.
  350. *
  351. * @see pm_drush_engine_package_handler()
  352. * @see pm_drush_engine_version_control()
  353. */
  354. function hook_drush_engine_ENGINE_TYPE() {
  355. return array(
  356. 'ice-cream' => array(
  357. 'description' => 'Feature rich ice-cream with all kind of additives.',
  358. 'options' => array(
  359. 'flavour' => 'Choose your favorite flavour',
  360. ),
  361. ),
  362. 'frozen-yogurt' => array(
  363. 'description' => 'Frozen dairy dessert made with yogurt instead of milk and cream.',
  364. 'implemented-by' => 'ice-cream',
  365. ),
  366. );
  367. }
  368. /**
  369. * Alter the order that hooks are invoked.
  370. *
  371. * When implementing a given hook we may need to ensure it is invoked before
  372. * or after another implementation of the same hook. For example, let's say
  373. * you want to implement a hook that would be called after drush_make. You'd
  374. * write a drush_MY_MODULE_post_make() function. But if you need your hook to
  375. * be called before drush_make_post_make(), you can ensure this by implemen-
  376. * ting MY_MODULE_drush_invoke_alter().
  377. *
  378. * @see drush_command_invoke_all_ref()
  379. */
  380. function hook_drush_invoke_alter($modules, $hook) {
  381. if ($hook == 'some_hook') {
  382. // Take the module who's hooks would normally be called last.
  383. $module = array_pop($modules);
  384. // Ensure it'll be called first for 'some_hook'.
  385. array_unshift($modules, $module);
  386. }
  387. }
  388. /**
  389. * @} End of "addtogroup hooks".
  390. */