backend.inc

  1. 8.0.x includes/backend.inc
  2. 6.x includes/backend.inc
  3. 7.x includes/backend.inc
  4. 3.x includes/backend.inc
  5. 4.x includes/backend.inc
  6. 5.x includes/backend.inc
  7. master includes/backend.inc

Drush backend API

When a drush command is called with the --backend option, it will buffer all output, and instead return a JSON encoded string containing all relevant information on the command that was just executed.

Through this mechanism, it is possible for Drush commands to invoke each other.

There are many cases where a command might wish to call another command in its own process, to allow the calling command to intercept and act on any errors that may occur in the script that was called.

A simple example is if there exists an 'update' command for running update.php on a specific site. The original command might download a newer version of a module for installation on a site, and then run the update script in a separate process, so that in the case of an error running a hook_update_n function, the module can revert to a previously made database backup, and the previously installed code.

By calling the script in a separate process, the calling script is insulated from any error that occurs in the called script, to the level that if a php code error occurs (ie: misformed file, missing parenthesis, whatever), it is still able to reliably handle any problems that occur.

This is nearly a RESTful API. Instead of : http://[server]/[apipath]/[command]?[arg1]=[value1],[arg2]=[value2]

It will call : [apipath] [command] --[arg1]=[value1] --[arg2]=[value2] --backend

[apipath] in this case will be the path to the drush.php file. [command] is the command you would call, for instance 'status'.

GET parameters will be passed as options to the script. POST parameters will be passed to the script as a JSON encoded associative array over STDIN.

Because of this standard interface, Drush commands can also be executed on external servers through SSH pipes, simply by prepending, 'ssh username@server.com' in front of the command.

If the key-based ssh authentication has been set up between the servers, this will just work. By default, drush is configured to disallow password authentication; if you would like to enter a password for every connection, then in your drushrc.php file, set $options['ssh-options'] so that it does NOT include '-o PasswordAuthentication=no'. See examples/example.drushrc.php.

The results from backend API calls can be fetched via a call to drush_backend_get_result().

See also

http://en.wikipedia.org/wiki/REST

Functions

Namesort descending Description
drush_backend_generate_sitealias Helper function that generates an anonymous site alias specification for the given parameters.
drush_backend_get_result Retrieves the results from the last call to backend_invoke.
drush_backend_invoke_concurrent Execute a new local or remote command in a new process.
drush_backend_output Print the json-encoded output of this command, including the encoded log records, context information, etc.
drush_backend_output_collect Callback to collect backend command output.
drush_backend_output_discard Output buffer functions that discards all output but backend packets.
drush_backend_packet Output a backend packet if we're running as backend.
drush_backend_packet_set_error Backend command for setting errors.
drush_backend_parse_output Parse output returned from a Drush command.
drush_backend_parse_packets Parse out and remove backend packet from the supplied string and invoke the commands.
drush_backend_set_result The backend result is the original PHP data structure (usually an array) used to generate the output for the current command.
_drush_backend_adjust_options Default options for backend_invoke commands.
_drush_backend_argument_string Map the options to a string containing all the possible arguments and options.
_drush_backend_classify_options Take all of the values in the $command_options array, and place each of them into one of the following result arrays:
_drush_backend_generate_command Generate a command to execute.
_drush_backend_get_global_contexts Find all of the drush contexts that are used to cache global values and return them in an associative array.
_drush_backend_get_stdin Read options fron STDIN during POST requests.
_drush_backend_integrate Integrate log messages and error statuses into the current process.
_drush_backend_integrate_log Supress log message output during backend integrate.
_drush_backend_invoke Create a new pipe with proc_open, and attempt to parse the output.
_drush_backend_print_output Print the output received from a call to backend invoke, adding the label to the head of each line if necessary.
_drush_backend_proc_open Call an external command using proc_open.
_drush_escape_option Return a properly formatted and escaped command line option

Constants

Namesort descending Description
DRUSH_BACKEND_OUTPUT_DELIMITER
DRUSH_BACKEND_OUTPUT_START Identify the JSON encoded output from a command.
DRUSH_BACKEND_PACKET_PATTERN
DRUSH_BACKEND_PACKET_START Identify JSON encoded "packets" embedded inside of backend output; used to send out-of-band information durring a backend invoke call (currently only used for log and error messages).

File

includes/backend.inc
View source
  1. <?php
  2. /**
  3. * @file
  4. * Drush backend API
  5. *
  6. * When a drush command is called with the --backend option,
  7. * it will buffer all output, and instead return a JSON encoded
  8. * string containing all relevant information on the command that
  9. * was just executed.
  10. *
  11. * Through this mechanism, it is possible for Drush commands to
  12. * invoke each other.
  13. *
  14. * There are many cases where a command might wish to call another
  15. * command in its own process, to allow the calling command to
  16. * intercept and act on any errors that may occur in the script that
  17. * was called.
  18. *
  19. * A simple example is if there exists an 'update' command for running
  20. * update.php on a specific site. The original command might download
  21. * a newer version of a module for installation on a site, and then
  22. * run the update script in a separate process, so that in the case
  23. * of an error running a hook_update_n function, the module can revert
  24. * to a previously made database backup, and the previously installed code.
  25. *
  26. * By calling the script in a separate process, the calling script is insulated
  27. * from any error that occurs in the called script, to the level that if a
  28. * php code error occurs (ie: misformed file, missing parenthesis, whatever),
  29. * it is still able to reliably handle any problems that occur.
  30. *
  31. * This is nearly a RESTful API. @see http://en.wikipedia.org/wiki/REST
  32. *
  33. * Instead of :
  34. * http://[server]/[apipath]/[command]?[arg1]=[value1],[arg2]=[value2]
  35. *
  36. * It will call :
  37. * [apipath] [command] --[arg1]=[value1] --[arg2]=[value2] --backend
  38. *
  39. * [apipath] in this case will be the path to the drush.php file.
  40. * [command] is the command you would call, for instance 'status'.
  41. *
  42. * GET parameters will be passed as options to the script.
  43. * POST parameters will be passed to the script as a JSON encoded associative array over STDIN.
  44. *
  45. * Because of this standard interface, Drush commands can also be executed on
  46. * external servers through SSH pipes, simply by prepending, 'ssh username@server.com'
  47. * in front of the command.
  48. *
  49. * If the key-based ssh authentication has been set up between the servers,
  50. * this will just work. By default, drush is configured to disallow password
  51. * authentication; if you would like to enter a password for every connection,
  52. * then in your drushrc.php file, set $options['ssh-options'] so that it does NOT
  53. * include '-o PasswordAuthentication=no'. See examples/example.drushrc.php.
  54. *
  55. * The results from backend API calls can be fetched via a call to
  56. * drush_backend_get_result().
  57. */
  58. /**
  59. * Identify the JSON encoded output from a command.
  60. *
  61. * Note that Drush now outputs a null ("\0") before the DRUSH_BACKEND_OUTPUT_DELIMITER,
  62. * but this null occurs where this constant is output rather than being
  63. * included in the define. This is done to maintain compatibility with
  64. * older versions of Drush, so that Drush-6.x can correctly parse backend messages
  65. * from calls made to Drush-5.x and earlier. The null is removed via trim().
  66. */
  67. define('DRUSH_BACKEND_OUTPUT_START', 'DRUSH_BACKEND_OUTPUT_START>>>');
  68. define('DRUSH_BACKEND_OUTPUT_DELIMITER', DRUSH_BACKEND_OUTPUT_START . '%s<<<DRUSH_BACKEND_OUTPUT_END');
  69. /**
  70. * Identify JSON encoded "packets" embedded inside of backend
  71. * output; used to send out-of-band information durring a backend
  72. * invoke call (currently only used for log and error messages).
  73. */
  74. define('DRUSH_BACKEND_PACKET_START', "DRUSH_BACKEND:");
  75. define('DRUSH_BACKEND_PACKET_PATTERN', "\0" . DRUSH_BACKEND_PACKET_START . "%s\n\0");
  76. /**
  77. * The backend result is the original PHP data structure (usually an array)
  78. * used to generate the output for the current command.
  79. */
  80. function drush_backend_set_result($value) {
  81. if (drush_get_context('DRUSH_BACKEND')) {
  82. drush_set_context('BACKEND_RESULT', $value);
  83. }
  84. }
  85. /**
  86. * Retrieves the results from the last call to backend_invoke.
  87. *
  88. * @returns array
  89. * An associative array containing information from the last
  90. * backend invoke. The keys in the array include:
  91. *
  92. * - output: This item contains the textual output of
  93. * the command that was executed.
  94. * - object: Contains the PHP object representation of the
  95. * result of the command.
  96. * - self: The self object contains the alias record that was
  97. * used to select the bootstrapped site when the command was
  98. * executed.
  99. * - error_status: This item returns the error status for the
  100. * command. Zero means "no error".
  101. * - log: The log item contains an array of log messages from
  102. * the command execution ordered chronologically. Each log
  103. * entery is an associative array. A log entry contains
  104. * following items:
  105. * o type: The type of log entry, such as 'notice' or 'warning'
  106. * o message: The log message
  107. * o timestamp: The time that the message was logged
  108. * o memory: Available memory at the time that the message was logged
  109. * o error: The error code associated with the log message
  110. * (only for log entries whose type is 'error')
  111. * - error_log: The error_log item contains another representation
  112. * of entries from the log. Only log entries whose 'error' item
  113. * is set will appear in the error log. The error log is an
  114. * associative array whose key is the error code, and whose value
  115. * is an array of messages--one message for every log entry with
  116. * the same error code.
  117. * - context: The context item contains a representation of all option
  118. * values that affected the operation of the command, including both
  119. * the command line options, options set in a drushrc.php configuration
  120. * files, and options set from the alias record used with the command.
  121. */
  122. function drush_backend_get_result() {
  123. return drush_get_context('BACKEND_RESULT');
  124. }
  125. /**
  126. * Print the json-encoded output of this command, including the
  127. * encoded log records, context information, etc.
  128. */
  129. function drush_backend_output() {
  130. $data = array();
  131. if (drush_get_context('DRUSH_PIPE')) {
  132. $pipe = drush_get_context('DRUSH_PIPE_BUFFER');
  133. $data['output'] = $pipe; // print_r($pipe, TRUE);
  134. }
  135. else {
  136. // Strip out backend commands.
  137. $packet_regex = strtr(sprintf(DRUSH_BACKEND_PACKET_PATTERN, "([^\0]*)"), array("\0" => "\\0"));
  138. $packet_regex = str_replace("\n", "", $packet_regex);
  139. $data['output'] = preg_replace("/$packet_regex/s", '', drush_backend_output_collect(NULL));
  140. }
  141. if (drush_get_context('DRUSH_QUIET', FALSE)) {
  142. ob_end_clean();
  143. }
  144. $result_object = drush_backend_get_result();
  145. if (isset($result_object)) {
  146. $data['object'] = $result_object;
  147. }
  148. $error = drush_get_error();
  149. $data['error_status'] = ($error) ? $error : DRUSH_SUCCESS;
  150. $data['log'] = drush_get_log(); // Append logging information
  151. // The error log is a more specific version of the log, and may be used by calling
  152. // scripts to check for specific errors that have occurred.
  153. $data['error_log'] = drush_get_error_log();
  154. // If there is a @self record, then include it in the result
  155. $self_record = drush_sitealias_get_record('@self');
  156. if (!empty($self_record)) {
  157. $site_context = drush_get_context('site', array());
  158. unset($site_context['config-file']);
  159. unset($site_context['context-path']);
  160. unset($self_record['loaded-config']);
  161. unset($self_record['#name']);
  162. $data['self'] = array_merge($site_context, $self_record);
  163. }
  164. // Return the options that were set at the end of the process.
  165. $data['context'] = drush_get_merged_options();
  166. printf("\0" . DRUSH_BACKEND_OUTPUT_DELIMITER, json_encode($data));
  167. }
  168. /**
  169. * Callback to collect backend command output.
  170. */
  171. function drush_backend_output_collect($string) {
  172. static $output = '';
  173. if (!isset($string)) {
  174. return $output;
  175. }
  176. $output .= $string;
  177. return $string;
  178. }
  179. /**
  180. * Output buffer functions that discards all output but backend packets.
  181. */
  182. function drush_backend_output_discard($string) {
  183. $packet_regex = strtr(sprintf(DRUSH_BACKEND_PACKET_PATTERN, "([^\0]*)"), array("\0" => "\\0"));
  184. $packet_regex = str_replace("\n", "", $packet_regex);
  185. if (preg_match_all("/$packet_regex/s", $string, $matches)) {
  186. return implode('', $matches[0]);
  187. }
  188. }
  189. /**
  190. * Output a backend packet if we're running as backend.
  191. *
  192. * @param packet
  193. * The packet to send.
  194. * @param data
  195. * Data for the command.
  196. *
  197. * @return
  198. * A boolean indicating whether the command was output.
  199. */
  200. function drush_backend_packet($packet, $data) {
  201. if (drush_get_context('DRUSH_BACKEND')) {
  202. $data['packet'] = $packet;
  203. $data = json_encode($data);
  204. // We use 'fwrite' instead of 'drush_print' here because
  205. // this backend packet is out-of-band data.
  206. fwrite(STDERR, sprintf(DRUSH_BACKEND_PACKET_PATTERN, $data));
  207. return TRUE;
  208. }
  209. return FALSE;
  210. }
  211. /**
  212. * Parse output returned from a Drush command.
  213. *
  214. * @param string
  215. * The output of a drush command
  216. * @param integrate
  217. * Integrate the errors and log messages from the command into the current process.
  218. * @param outputted
  219. * Whether output has already been handled.
  220. *
  221. * @return
  222. * An associative array containing the data from the external command, or the string parameter if it
  223. * could not be parsed successfully.
  224. */
  225. function drush_backend_parse_output($string, $backend_options = array(), $outputted = FALSE) {
  226. $regex = sprintf(DRUSH_BACKEND_OUTPUT_DELIMITER, '(.*)');
  227. preg_match("/$regex/s", $string, $match);
  228. if (!empty($match) && $match[1]) {
  229. // we have our JSON encoded string
  230. $output = $match[1];
  231. // remove the match we just made and any non printing characters
  232. $string = trim(str_replace(sprintf(DRUSH_BACKEND_OUTPUT_DELIMITER, $match[1]), '', $string));
  233. }
  234. if (!empty($output)) {
  235. $data = json_decode($output, TRUE);
  236. if (is_array($data)) {
  237. _drush_backend_integrate($data, $backend_options, $outputted);
  238. return $data;
  239. }
  240. }
  241. return $string;
  242. }
  243. /**
  244. * Integrate log messages and error statuses into the current
  245. * process.
  246. *
  247. * Output produced by the called script will be printed if we didn't print it
  248. * on the fly, errors will be set, and log messages will be logged locally, if
  249. * not already logged.
  250. *
  251. * @param data
  252. * The associative array returned from the external command.
  253. * @param outputted
  254. * Whether output has already been handled.
  255. */
  256. function _drush_backend_integrate($data, $backend_options, $outputted) {
  257. // In 'integrate' mode, logs and errors have already been handled
  258. // by drush_backend_packet (sender) drush_backend_parse_packets (receiver - us)
  259. // during incremental output. We therefore do not need to call drush_set_error
  260. // or drush_log here. The exception is if the sender is an older version of
  261. // Drush (version 4.x) that does not send backend packets, then we will
  262. // not have processed the log entries yet, and must print them here.
  263. $received_packets = drush_get_context('DRUSH_RECEIVED_BACKEND_PACKETS', FALSE);
  264. if (is_array($data['log']) && $backend_options['log'] && (!$received_packets)) {
  265. foreach($data['log'] as $log) {
  266. $message = is_array($log['message']) ? implode("\n", $log['message']) : $log['message'];
  267. if (isset($backend_options['#output-label'])) {
  268. $message = $backend_options['#output-label'] . $message;
  269. }
  270. if (isset($log['error']) && $backend_options['integrate']) {
  271. drush_set_error($log['error'], $message);
  272. }
  273. elseif ($backend_options['integrate']) {
  274. drush_log($message, $log['type']);
  275. }
  276. }
  277. }
  278. // Output will either be printed, or buffered to the drush_backend_output command.
  279. // If the output has already been printed, then we do not need to show it again on a failure.
  280. if (!$outputted) {
  281. if (drush_cmp_error('DRUSH_APPLICATION_ERROR') && !empty($data['output'])) {
  282. drush_set_error("DRUSH_APPLICATION_ERROR", dt("Output from failed command :\n !output", array('!output' => $data['output'])));
  283. }
  284. elseif ($backend_options['output']) {
  285. _drush_backend_print_output($data['output'], $backend_options);
  286. }
  287. }
  288. }
  289. /**
  290. * Supress log message output during backend integrate.
  291. */
  292. function _drush_backend_integrate_log($entry) {
  293. }
  294. /**
  295. * Call an external command using proc_open.
  296. *
  297. * @param cmds
  298. * An array of records containing the following elements:
  299. * 'cmd' - The command to execute, already properly escaped
  300. * 'post-options' - An associative array that will be JSON encoded
  301. * and passed to the script being called. Objects are not allowed,
  302. * as they do not json_decode gracefully.
  303. * 'backend-options' - Options that control the operation of the backend invoke
  304. * - OR -
  305. * An array of commands to execute. These commands already need to be properly escaped.
  306. * In this case, post-options will default to empty, and a default output label will
  307. * be generated.
  308. * @param data
  309. * An associative array that will be JSON encoded and passed to the script being called.
  310. * Objects are not allowed, as they do not json_decode gracefully.
  311. *
  312. * @return
  313. * False if the command could not be executed, or did not return any output.
  314. * If it executed successfully, it returns an associative array containing the command
  315. * called, the output of the command, and the error code of the command.
  316. */
  317. function _drush_backend_proc_open($cmds, $process_limit, $context = NULL) {
  318. $descriptorspec = array(
  319. 0 => array("pipe", "r"), // stdin is a pipe that the child will read from
  320. 1 => array("pipe", "w"), // stdout is a pipe that the child will write to
  321. );
  322. $open_processes = array();
  323. $bucket = array();
  324. $process_limit = max($process_limit, 1);
  325. $is_windows = drush_is_windows();
  326. // Loop through processes until they all close, having a nap as needed.
  327. $nap_time = 0;
  328. while (count($open_processes) || count($cmds)) {
  329. $nap_time++;
  330. if (count($cmds) && (count($open_processes) < $process_limit)) {
  331. // Pop the site and command (key / value) from the cmds array
  332. end($cmds);
  333. list($site, $cmd) = each($cmds);
  334. unset($cmds[$site]);
  335. if (is_array($cmd)) {
  336. $c = $cmd['cmd'];
  337. $post_options = $cmd['post-options'];
  338. $backend_options = $cmd['backend-options'];
  339. }
  340. else {
  341. $c = $cmd;
  342. $post_options = array();
  343. $backend_options = array();
  344. }
  345. $backend_options += array(
  346. '#output-label' => '',
  347. '#process-read-size' => 4096,
  348. );
  349. $process = array();
  350. drush_log($backend_options['#output-label'] . $c);
  351. $process['process'] = proc_open($c, $descriptorspec, $process['pipes'], null, null, array('context' => $context));
  352. if (is_resource($process['process'])) {
  353. if ($post_options) {
  354. fwrite($process['pipes'][0], json_encode($post_options)); // pass the data array in a JSON encoded string
  355. }
  356. // If we do not close stdin here, then we cause a deadlock;
  357. // see: http://drupal.org/node/766080#comment-4309936
  358. // If we reimplement interactive commands to also use
  359. // _drush_proc_open, then clearly we would need to keep
  360. // this open longer.
  361. fclose($process['pipes'][0]);
  362. $process['info'] = stream_get_meta_data($process['pipes'][1]);
  363. stream_set_blocking($process['pipes'][1], FALSE);
  364. stream_set_timeout($process['pipes'][1], 1);
  365. $bucket[$site]['cmd'] = $c;
  366. $bucket[$site]['output'] = '';
  367. $bucket[$site]['remainder'] = '';
  368. $bucket[$site]['backend-options'] = $backend_options;
  369. $bucket[$site]['end_of_output'] = FALSE;
  370. $bucket[$site]['outputted'] = FALSE;
  371. $open_processes[$site] = $process;
  372. }
  373. // Reset the $nap_time variable as there might be output to process next
  374. // time around:
  375. $nap_time = 0;
  376. }
  377. // Set up to call stream_select(). See:
  378. // http://php.net/manual/en/function.stream-select.php
  379. // We can't use stream_select on Windows, because it doesn't work for
  380. // streams returned by proc_open.
  381. if (!$is_windows) {
  382. $ss_result = 0;
  383. $read_streams = array();
  384. $write_streams = array();
  385. $except_streams = array();
  386. foreach ($open_processes as $site => &$current_process) {
  387. if (isset($current_process['pipes'][1])) {
  388. $read_streams[] = $current_process['pipes'][1];
  389. }
  390. }
  391. // Wait up to 2s for data to become ready on one of the read streams.
  392. if (count($read_streams)) {
  393. $ss_result = stream_select($read_streams, $write_streams, $except_streams, 2);
  394. // If stream_select returns a error, then fallback to using $nap_time.
  395. if ($ss_result !== FALSE) {
  396. $nap_time = 0;
  397. }
  398. }
  399. }
  400. foreach ($open_processes as $site => &$current_process) {
  401. if (isset($current_process['pipes'][1])) {
  402. // Collect output from stdout
  403. $bucket[$site][1] = '';
  404. $info = stream_get_meta_data($current_process['pipes'][1]);
  405. if (!feof($current_process['pipes'][1]) && !$info['timed_out']) {
  406. $string = $bucket[$site]['remainder'] . fread($current_process['pipes'][1], $backend_options['#process-read-size']);
  407. $bucket[$site]['remainder'] = '';
  408. $output_end_pos = strpos($string, DRUSH_BACKEND_OUTPUT_START);
  409. if ($output_end_pos !== FALSE) {
  410. $trailing_string = substr($string, 0, $output_end_pos);
  411. $trailing_remainder = '';
  412. // If there is any data in the trailing string (characters prior
  413. // to the backend output start), then process any backend packets
  414. // embedded inside.
  415. if (strlen($trailing_string) > 0) {
  416. drush_backend_parse_packets($trailing_string, $trailing_remainder, $bucket[$site]['backend-options']);
  417. }
  418. // If there is any data remaining in the trailing string after
  419. // the backend packets are removed, then print it.
  420. if (strlen($trailing_string) > 0) {
  421. _drush_backend_print_output($trailing_string . $trailing_remainder, $bucket[$site]['backend-options']);
  422. $bucket[$site]['outputted'] = TRUE;
  423. }
  424. $bucket[$site]['end_of_output'] = TRUE;
  425. }
  426. if (!$bucket[$site]['end_of_output']) {
  427. drush_backend_parse_packets($string, $bucket[$site]['remainder'], $bucket[$site]['backend-options']);
  428. // Pass output through.
  429. _drush_backend_print_output($string, $bucket[$site]['backend-options']);
  430. if (strlen($string) > 0) {
  431. $bucket[$site]['outputted'] = TRUE;
  432. }
  433. }
  434. $bucket[$site][1] .= $string;
  435. $bucket[$site]['output'] .= $string;
  436. $info = stream_get_meta_data($current_process['pipes'][1]);
  437. flush();
  438. // Reset the $nap_time variable as there might be output to process
  439. // next time around:
  440. if (strlen($string) > 0) {
  441. $nap_time = 0;
  442. }
  443. }
  444. else {
  445. fclose($current_process['pipes'][1]);
  446. unset($current_process['pipes'][1]);
  447. // close the pipe , set a marker
  448. // Reset the $nap_time variable as there might be output to process
  449. // next time around:
  450. $nap_time = 0;
  451. }
  452. }
  453. else {
  454. // if both pipes are closed for the process, remove it from active loop and add a new process to open.
  455. $bucket[$site]['code'] = proc_close($current_process['process']);
  456. unset($open_processes[$site]);
  457. // Reset the $nap_time variable as there might be output to process next
  458. // time around:
  459. $nap_time = 0;
  460. }
  461. }
  462. // We should sleep for a bit if we need to, up to a maximum of 1/10 of a
  463. // second.
  464. if ($nap_time > 0) {
  465. usleep(max($nap_time * 500, 100000));
  466. }
  467. }
  468. return $bucket;
  469. // TODO: Handle bad proc handles
  470. //}
  471. //return FALSE;
  472. }
  473. /**
  474. * Print the output received from a call to backend invoke,
  475. * adding the label to the head of each line if necessary.
  476. */
  477. function _drush_backend_print_output($output_string, $backend_options) {
  478. if ($backend_options['output'] && !empty($output_string)) {
  479. $output_label = array_key_exists('#output-label', $backend_options) ? $backend_options['#output-label'] : FALSE;
  480. if (!empty($output_label)) {
  481. // Remove one, and only one newline from the end of the
  482. // string. Else we'll get an extra 'empty' line.
  483. foreach (explode("\n", preg_replace('/\\n$/', '', $output_string)) as $line) {
  484. fwrite(STDOUT, $output_label . rtrim($line) . "\n");
  485. }
  486. }
  487. else {
  488. fwrite(STDOUT, $output_string);
  489. }
  490. }
  491. }
  492. /**
  493. * Parse out and remove backend packet from the supplied string and
  494. * invoke the commands.
  495. */
  496. function drush_backend_parse_packets(&$string, &$remainder, $backend_options) {
  497. $remainder = '';
  498. $packet_regex = strtr(sprintf(DRUSH_BACKEND_PACKET_PATTERN, "([^\0]*)"), array("\0" => "\\0"));
  499. $packet_regex = str_replace("\n", "", $packet_regex);
  500. if (preg_match_all("/$packet_regex/s", $string, $match, PREG_PATTERN_ORDER)) {
  501. drush_set_context('DRUSH_RECEIVED_BACKEND_PACKETS', TRUE);
  502. foreach ($match[1] as $packet_data) {
  503. $entry = (array) json_decode($packet_data);
  504. if (is_array($entry) && isset($entry['packet'])) {
  505. $function = 'drush_backend_packet_' . $entry['packet'];
  506. if (function_exists($function)) {
  507. $function($entry, $backend_options);
  508. }
  509. else {
  510. drush_log(dt("Unknown backend packet @packet", array('@packet' => $entry['packet'])), 'notice');
  511. }
  512. }
  513. else {
  514. drush_log(dt("Malformed backend packet"), 'error');
  515. drush_log(dt("Bad packet: @packet", array('@packet' => print_r($entry, TRUE))), 'debug');
  516. drush_log(dt("String is: @str", array('@str' => $packet_data), 'debug'));
  517. }
  518. }
  519. $string = preg_replace("/$packet_regex/s", '', $string);
  520. }
  521. // Check to see if there is potentially a partial packet remaining.
  522. // We only care about the last null; if there are any nulls prior
  523. // to the last one, they would have been removed above if they were
  524. // valid drush packets.
  525. $embedded_null = strrpos($string, "\0");
  526. if ($embedded_null !== FALSE) {
  527. // We will consider everything after $embedded_null to be part of
  528. // the $remainder string if:
  529. // - the embedded null is less than strlen(DRUSH_BACKEND_OUTPUT_START)
  530. // from the end of $string (that is, there might be a truncated
  531. // backend packet header, or the truncated backend output start
  532. // after the null)
  533. // OR
  534. // - the embedded null is followed by DRUSH_BACKEND_PACKET_START
  535. // (that is, the terminating null for that packet has not been
  536. // read into our buffer yet)
  537. if (($embedded_null + strlen(DRUSH_BACKEND_OUTPUT_START) >= strlen($string)) || (substr($string, $embedded_null + 1, strlen(DRUSH_BACKEND_PACKET_START)) == DRUSH_BACKEND_PACKET_START)) {
  538. $remainder = substr($string, $embedded_null);
  539. $string = substr($string, 0, $embedded_null);
  540. }
  541. }
  542. }
  543. /**
  544. * Backend command for setting errors.
  545. */
  546. function drush_backend_packet_set_error($data, $backend_options) {
  547. if (!$backend_options['integrate']) {
  548. return;
  549. }
  550. $output_label = "";
  551. if (array_key_exists('#output-label', $backend_options)) {
  552. $output_label = $backend_options['#output-label'];
  553. }
  554. drush_set_error($data['error'], $data['message'], $output_label);
  555. }
  556. /**
  557. * Default options for backend_invoke commands.
  558. */
  559. function _drush_backend_adjust_options($site_record, $command, $command_options, $backend_options) {
  560. // By default, if the caller does not specify a value for 'output', but does
  561. // specify 'integrate' === FALSE, then we will set output to FALSE. Otherwise we
  562. // will allow it to default to TRUE.
  563. if ((array_key_exists('integrate', $backend_options)) && ($backend_options['integrate'] === FALSE) && (!array_key_exists('output', $backend_options))) {
  564. $backend_options['output'] = FALSE;
  565. }
  566. $has_site_specification = array_key_exists('root', $site_record) || array_key_exists('uri', $site_record);
  567. $result = $backend_options + array(
  568. 'method' => 'GET',
  569. 'output' => TRUE,
  570. 'log' => TRUE,
  571. 'integrate' => TRUE,
  572. 'backend' => TRUE,
  573. 'dispatch-using-alias' => !$has_site_specification,
  574. );
  575. // Convert '#integrate' et. al. into backend options
  576. foreach ($command_options as $key => $value) {
  577. if (substr($key,0,1) === '#') {
  578. $result[substr($key,1)] = $value;
  579. }
  580. }
  581. return $result;
  582. }
  583. /**
  584. * Execute a new local or remote command in a new process.
  585. *
  586. * n.b. Prefer drush_invoke_process() to this function.
  587. *
  588. * @param invocations
  589. * An array of command records to exacute. Each record should contain:
  590. * 'site':
  591. * An array containing information used to generate the command.
  592. * 'remote-host'
  593. * Optional. A remote host to execute the drush command on.
  594. * 'remote-user'
  595. * Optional. Defaults to the current user. If you specify this, you can choose which module to send.
  596. * 'ssh-options'
  597. * Optional. Defaults to "-o PasswordAuthentication=no"
  598. * 'path-aliases'
  599. * Optional; contains paths to folders and executables useful to the command.
  600. * '%drush-script'
  601. * Optional. Defaults to the current drush.php file on the local machine, and
  602. * to simply 'drush' (the drush script in the current PATH) on remote servers.
  603. * You may also specify a different drush.php script explicitly. You will need
  604. * to set this when calling drush on a remote server if 'drush' is not in the
  605. * PATH on that machine.
  606. * 'command':
  607. * A defined drush command such as 'cron', 'status' or any of the available ones such as 'drush pm'.
  608. * 'args':
  609. * An array of arguments for the command.
  610. * 'options'
  611. * Optional. An array containing options to pass to the remote script.
  612. * Array items with a numeric key are treated as optional arguments to the
  613. * command.
  614. * 'backend-options':
  615. * Optional. Additional parameters that control the operation of the invoke.
  616. * 'method'
  617. * Optional. Defaults to 'GET'.
  618. * If this parameter is set to 'POST', the $data array will be passed
  619. * to the script being called as a JSON encoded string over the STDIN
  620. * pipe of that process. This is preferable if you have to pass
  621. * sensitive data such as passwords and the like.
  622. * For any other value, the $data array will be collapsed down into a
  623. * set of command line options to the script.
  624. * 'integrate'
  625. * Optional. Defaults to TRUE.
  626. * If TRUE, any error statuses will be integrated into the current
  627. * process. This might not be what you want, if you are writing a
  628. * command that operates on multiple sites.
  629. * 'log'
  630. * Optional. Defaults to TRUE.
  631. * If TRUE, any log messages will be integrated into the current
  632. * process.
  633. * 'output'
  634. * Optional. Defaults to TRUE.
  635. * If TRUE, output from the command will be synchronously printed to
  636. * stdout.
  637. * 'drush-script'
  638. * Optional. Defaults to the current drush.php file on the local
  639. * machine, and to simply 'drush' (the drush script in the current
  640. * PATH) on remote servers. You may also specify a different drush.php
  641. * script explicitly. You will need to set this when calling drush on
  642. * a remote server if 'drush' is not in the PATH on that machine.
  643. * 'dispatch-using-alias'
  644. * Optional. Defaults to FALSE.
  645. * If specified as a non-empty value the drush command will be
  646. * dispatched using the alias name on the command line, instead of
  647. * the options from the alias being added to the command line
  648. * automatically.
  649. * @param common_options
  650. * Optional. Merged in with the options for each invocation.
  651. * @param backend_options
  652. * Optional. Merged in with the backend options for each invocation.
  653. * @param default_command
  654. * Optional. Used as the 'command' for any invocation that does not
  655. * define a command explicitly.
  656. * @param default_site
  657. * Optional. Used as the 'site' for any invocation that does not
  658. * define a site explicitly.
  659. * @param context
  660. * Optional. Passed in to proc_open if provided.
  661. *
  662. * @return
  663. * If the command could not be completed successfully, FALSE.
  664. * If the command was completed, this will return an associative array containing the data from drush_backend_output().
  665. */
  666. function drush_backend_invoke_concurrent($invocations, $common_options = array(), $common_backend_options = array(), $default_command = NULL, $default_site = NULL, $context = NULL) {
  667. $index = 0;
  668. // Slice and dice our options in preparation to build a command string
  669. $invocation_options = array();
  670. foreach ($invocations as $invocation) {
  671. $site_record = isset($invocation['site']) ? $invocation['site'] : $default_site;
  672. // NULL is a synonym to '@self', although the latter is preferred.
  673. if (!isset($site_record)) {
  674. $site_record = '@self';
  675. }
  676. // If the first parameter is not a site alias record,
  677. // then presume it is an alias name, and try to look up
  678. // the alias record.
  679. if (!is_array($site_record)) {
  680. $site_record = drush_sitealias_get_record($site_record);
  681. }
  682. $command = isset($invocation['command']) ? $invocation['command'] : $default_command;
  683. $args = isset($invocation['args']) ? $invocation['args'] : array();
  684. $command_options = isset($invocation['options']) ? $invocation['options'] : array();
  685. $backend_options = isset($invocation['backend-options']) ? $invocation['backend-options'] : array();
  686. // If $backend_options is passed in as a bool, interpret that as the value for 'integrate'
  687. if (!is_array($common_backend_options)) {
  688. $integrate = (bool)$common_backend_options;
  689. $common_backend_options = array('integrate' => $integrate);
  690. }
  691. $command_options += $common_options;
  692. $backend_options += $common_backend_options;
  693. $backend_options = _drush_backend_adjust_options($site_record, $command, $command_options, $backend_options);
  694. // Insure that contexts such as DRUSH_SIMULATE and NO_COLOR are included.
  695. $command_options += _drush_backend_get_global_contexts($site_record);
  696. // Add in command-specific options as well
  697. $command_options += drush_command_get_command_specific_options($site_record, $command);
  698. // If the caller has requested it, don't pull the options from the alias
  699. // into the command line, but use the alias name for dispatching.
  700. if (!empty($backend_options['dispatch-using-alias']) && isset($site_record['#name'])) {
  701. list($post_options, $commandline_options, $drush_global_options) = _drush_backend_classify_options(array(), $command_options, $backend_options);
  702. $site_record_to_dispatch = '@' . ltrim($site_record['#name'], '@');
  703. }
  704. else {
  705. list($post_options, $commandline_options, $drush_global_options) = _drush_backend_classify_options($site_record, $command_options, $backend_options);
  706. $site_record_to_dispatch = '';
  707. }
  708. $site_record += array('path-aliases' => array());
  709. $site_record['path-aliases'] += array(
  710. '%drush-script' => NULL,
  711. );
  712. $site = (array_key_exists('#name', $site_record) && !array_key_exists($site_record['#name'], $invocation_options)) ? $site_record['#name'] : $index++;
  713. $invocation_options[$site] = array(
  714. 'site-record' => $site_record,
  715. 'site-record-to-dispatch' => $site_record_to_dispatch,
  716. 'command' => $command,
  717. 'args' => $args,
  718. 'post-options' => $post_options,
  719. 'drush-global-options' => $drush_global_options,
  720. 'commandline-options' => $commandline_options,
  721. 'command-options' => $command_options,
  722. 'backend-options' => $backend_options,
  723. );
  724. }
  725. // Calculate the length of the longest output label
  726. $max_name_length = 0;
  727. $label_separator = '';
  728. if (!array_key_exists('no-label', $common_options) && (count($invocation_options) > 1)) {
  729. $label_separator = array_key_exists('label-separator', $common_options) ? $common_options['label-separator'] : ' >> ';
  730. foreach ($invocation_options as $site => $item) {
  731. $backend_options = $item['backend-options'];
  732. if (!array_key_exists('#output-label', $backend_options)) {
  733. if (is_numeric($site)) {
  734. $backend_options['#output-label'] = ' * [@self.' . $site;
  735. $label_separator = '] ';
  736. }
  737. else {
  738. $backend_options['#output-label'] = $site;
  739. }
  740. $invocation_options[$site]['backend-options']['#output-label'] = $backend_options['#output-label'];
  741. }
  742. $name_len = strlen($backend_options['#output-label']);
  743. if ($name_len > $max_name_length) {
  744. $max_name_length = $name_len;
  745. }
  746. if (array_key_exists('#label-separator', $backend_options)) {
  747. $label_separator = $backend_options['#label-separator'];
  748. }
  749. }
  750. }
  751. // Now pad out the output labels and add the label separator.
  752. $reserve_margin = $max_name_length + strlen($label_separator);
  753. foreach ($invocation_options as $site => $item) {
  754. $backend_options = $item['backend-options'] + array('#output-label' => '');
  755. $invocation_options[$site]['backend-options']['#output-label'] = str_pad($backend_options['#output-label'], $max_name_length, " ") . $label_separator;
  756. if ($reserve_margin) {
  757. $invocation_options[$site]['drush-global-options']['reserve-margin'] = $reserve_margin;
  758. }
  759. }
  760. // Now take our prepared options and generate the command strings
  761. $cmds = array();
  762. foreach ($invocation_options as $site => $item) {
  763. $site_record = $item['site-record'];
  764. $site_record_to_dispatch = $item['site-record-to-dispatch'];
  765. $command = $item['command'];
  766. $args = $item['args'];
  767. $post_options = $item['post-options'];
  768. $commandline_options = $item['commandline-options'];
  769. $command_options = $item['command-options'];
  770. $drush_global_options = $item['drush-global-options'];
  771. $backend_options = $item['backend-options'];
  772. $os = drush_os($site_record);
  773. // If the caller did not pass in a specific path to drush, then we will
  774. // use a default value. For commands that are being executed on the same
  775. // machine, we will use DRUSH_COMMAND, which is the path to the drush.php
  776. // that is running right now. For remote commands, we will run a wrapper
  777. // script instead of drush.php -- drush.bat on Windows, or drush on Linux.
  778. $drush_path = $site_record['path-aliases']['%drush-script'];
  779. $php = array_key_exists('php', $site_record) ? $site_record['php'] : (array_key_exists('php', $command_options) ? $command_options['php'] : NULL);
  780. $drush_command_path = drush_build_drush_command($drush_path, $php, $os, array_key_exists('remote-host', $site_record));
  781. $cmd = _drush_backend_generate_command($site_record, $drush_command_path . " " . _drush_backend_argument_string($drush_global_options, $os) . " " . $site_record_to_dispatch . " " . $command, $args, $commandline_options, $backend_options) . ' 2>&1';
  782. $cmds[$site] = array(
  783. 'cmd' => $cmd,
  784. 'post-options' => $post_options,
  785. 'backend-options' => $backend_options,
  786. );
  787. }
  788. return _drush_backend_invoke($cmds, $common_backend_options, $context);
  789. }
  790. /**
  791. * Find all of the drush contexts that are used to cache global values and
  792. * return them in an associative array.
  793. */
  794. function _drush_backend_get_global_contexts($site_record) {
  795. $result = array();
  796. $global_option_list = drush_get_global_options(FALSE);
  797. foreach ($global_option_list as $global_key => $global_metadata) {
  798. if (is_array($global_metadata)) {
  799. $value = '';
  800. if (!array_key_exists('never-propagate', $global_metadata)) {
  801. if ((array_key_exists('propagate-cli-value', $global_metadata))) {
  802. $value = drush_get_option($global_key, '', 'cli');
  803. }
  804. elseif ((array_key_exists('context', $global_metadata))) {
  805. // If the context is declared to be a 'local-context-only',
  806. // then only put it in if this is a local dispatch.
  807. if (!array_key_exists('local-context-only', $global_metadata) || !array_key_exists('remote-host', $site_record)) {
  808. $value = drush_get_context($global_metadata['context'], array());
  809. }
  810. }
  811. if (!empty($value)) {
  812. $result[$global_key] = $value;
  813. }
  814. }
  815. }
  816. }
  817. return $result;
  818. }
  819. /**
  820. * Take all of the values in the $command_options array, and place each of
  821. * them into one of the following result arrays:
  822. *
  823. * - $post_options: options to be encoded as JSON and written to the
  824. * standard input of the drush subprocess being executed.
  825. * - $commandline_options: options to be placed on the command line of the drush
  826. * subprocess.
  827. * - $drush_global_options: the drush global options also go on the command
  828. * line, but appear before the drush command name rather than after it.
  829. *
  830. * Also, this function may modify $backend_options.
  831. */
  832. function _drush_backend_classify_options($site_record, $command_options, &$backend_options) {
  833. // In 'POST' mode (the default, remove everything (except the items marked 'never-post'
  834. // in the global option list) from the commandline options and put them into the post options.
  835. // The post options will be json-encoded and sent to the command via stdin
  836. $global_option_list = drush_get_global_options(FALSE); // These should be in the command line.
  837. $additional_global_options = array();
  838. if (array_key_exists('additional-global-options', $backend_options)) {
  839. $additional_global_options = $backend_options['additional-global-options'];
  840. $command_options += $additional_global_options;
  841. }
  842. $method_post = ((!array_key_exists('method', $backend_options)) || ($backend_options['method'] == 'POST'));
  843. $post_options = array();
  844. $commandline_options = array();
  845. $drush_global_options = array();
  846. $drush_local_options = array();
  847. $additional_backend_options = array();
  848. foreach ($site_record as $key => $value) {
  849. if (!in_array($key, drush_sitealias_site_selection_keys())) {
  850. if ($key[0] == '#') {
  851. $backend_options[$key] = $value;
  852. }
  853. if (!isset($command_options[$key])) {
  854. if (array_key_exists($key, $global_option_list)) {
  855. $command_options[$key] = $value;
  856. }
  857. }
  858. }
  859. }
  860. if (array_key_exists('drush-local-options', $backend_options)) {
  861. $drush_local_options = $backend_options['drush-local-options'];
  862. $command_options += $drush_local_options;
  863. }
  864. if (!empty($backend_options['backend']) && empty($backend_options['interactive']) && empty($backend_options['fork'])) {
  865. $drush_global_options['backend'] = '2';
  866. }
  867. foreach ($command_options as $key => $value) {
  868. $global = array_key_exists($key, $global_option_list);
  869. $propagate = TRUE;
  870. $special = FALSE;
  871. if ($global) {
  872. $propagate = (!array_key_exists('never-propagate', $global_option_list[$key]));
  873. $special = (array_key_exists('never-post', $global_option_list[$key]));
  874. if ($propagate) {
  875. // We will allow 'merge-pathlist' contexts to be propogated. Right now
  876. // these are all 'local-context-only' options; if we allowed them to
  877. // propogate remotely, then we would need to get the right path separator
  878. // for the remote machine.
  879. if (is_array($value) && array_key_exists('merge-pathlist', $global_option_list[$key])) {
  880. $value = implode(PATH_SEPARATOR, $value);
  881. }
  882. }
  883. }
  884. // Just remove options that are designated as non-propagating
  885. if ($propagate === TRUE) {
  886. // In METHOD POST, move command options to post options
  887. if ($method_post && ($special === FALSE)) {
  888. $post_options[$key] = $value;
  889. }
  890. // In METHOD GET, ignore options with array values
  891. elseif (!is_array($value)) {
  892. if ($global || array_key_exists($key, $additional_global_options)) {
  893. $drush_global_options[$key] = $value;
  894. }
  895. else {
  896. $commandline_options[$key] = $value;
  897. }
  898. }
  899. }
  900. }
  901. return array($post_options, $commandline_options, $drush_global_options, $additional_backend_options);
  902. }
  903. /**
  904. * Create a new pipe with proc_open, and attempt to parse the output.
  905. *
  906. * We use proc_open instead of exec or others because proc_open is best
  907. * for doing bi-directional pipes, and we need to pass data over STDIN
  908. * to the remote script.
  909. *
  910. * Exec also seems to exhibit some strangeness in keeping the returned
  911. * data intact, in that it modifies the newline characters.
  912. *
  913. * @param cmd
  914. * The complete command line call to use.
  915. * @param post_options
  916. * An associative array to json-encode and pass to the remote script on stdin.
  917. * @param backend_options
  918. * Options for the invocation.
  919. *
  920. * @return
  921. * If the command could not be completed successfully, FALSE.
  922. * If one command was executed, this will return an associative array containing
  923. * the data from drush_backend_output().
  924. * If multiple commands were executed, this will return an associative array
  925. * containing one item, 'concurrent', which will contain a list of the different
  926. * backend invoke results from each concurrent command.
  927. */
  928. function _drush_backend_invoke($cmds, $common_backend_options = array(), $context = NULL) {
  929. if (drush_get_context('DRUSH_SIMULATE') && !array_key_exists('override-simulated', $common_backend_options)) {
  930. foreach ($cmds as $cmd) {
  931. drush_print(dt('Simulating backend invoke: !cmd', array('!cmd' => $cmd['cmd'])));
  932. }
  933. return FALSE;
  934. }
  935. foreach ($cmds as $cmd) {
  936. drush_log(dt('Backend invoke: !cmd', array('!cmd' => $cmd['cmd'])), 'command');
  937. }
  938. if (array_key_exists('interactive', $common_backend_options) || array_key_exists('fork', $common_backend_options)) {
  939. foreach ($cmds as $cmd) {
  940. $exec_cmd = $cmd['cmd'];
  941. if (array_key_exists('fork', $common_backend_options)) {
  942. $exec_cmd .= ' --quiet &';
  943. }
  944. $ret = drush_shell_proc_open($exec_cmd);
  945. }
  946. return $ret;
  947. }
  948. else {
  949. $process_limit = drush_get_option_override($common_backend_options, 'concurrency', 1);
  950. $procs = _drush_backend_proc_open($cmds, $process_limit, $context);
  951. $procs = is_array($procs) ? $procs : array($procs);
  952. $ret = array();
  953. foreach ($procs as $site => $proc) {
  954. if (($proc['code'] == DRUSH_APPLICATION_ERROR) && isset($common_backend_options['integrate'])) {
  955. drush_set_error('DRUSH_APPLICATION_ERROR', dt("The external command could not be executed due to an application error."));
  956. }
  957. if ($proc['output']) {
  958. $values = drush_backend_parse_output($proc['output'], $proc['backend-options'], $proc['outputted']);
  959. $values['site'] = $site;
  960. if (is_array($values)) {
  961. if (empty($ret)) {
  962. $ret = $values;
  963. }
  964. elseif (!array_key_exists('concurrent', $ret)) {
  965. $ret = array('concurrent' => array($ret, $values));
  966. }
  967. else {
  968. $ret['concurrent'][] = $values;
  969. }
  970. }
  971. else {
  972. $ret = drush_set_error('DRUSH_FRAMEWORK_ERROR', dt("The command could not be executed successfully (returned: !return, code: !code)", array("!return" => $proc['output'], "!code" => $proc['code'])));
  973. }
  974. }
  975. }
  976. }
  977. return empty($ret) ? FALSE : $ret;
  978. }
  979. /**
  980. * Helper function that generates an anonymous site alias specification for
  981. * the given parameters.
  982. */
  983. function drush_backend_generate_sitealias($backend_options) {
  984. // Ensure default values.
  985. $backend_options += array(
  986. 'remote-host' => NULL,
  987. 'remote-user' => NULL,
  988. 'ssh-options' => NULL,
  989. 'drush-script' => NULL,
  990. );
  991. return array(
  992. 'remote-host' => $backend_options['remote-host'],
  993. 'remote-user' => $backend_options['remote-user'],
  994. 'ssh-options' => $backend_options['ssh-options'],
  995. 'path-aliases' => array(
  996. '%drush-script' => $backend_options['drush-script'],
  997. ),
  998. );
  999. }
  1000. /**
  1001. * Generate a command to execute.
  1002. *
  1003. * @param site_record
  1004. * An array containing information used to generate the command.
  1005. * 'remote-host'
  1006. * Optional. A remote host to execute the drush command on.
  1007. * 'remote-user'
  1008. * Optional. Defaults to the current user. If you specify this, you can choose which module to send.
  1009. * 'ssh-options'
  1010. * Optional. Defaults to "-o PasswordAuthentication=no"
  1011. * 'path-aliases'
  1012. * Optional; contains paths to folders and executables useful to the command.
  1013. * '%drush-script'
  1014. * Optional. Defaults to the current drush.php file on the local machine, and
  1015. * to simply 'drush' (the drush script in the current PATH) on remote servers.
  1016. * You may also specify a different drush.php script explicitly. You will need
  1017. * to set this when calling drush on a remote server if 'drush' is not in the
  1018. * PATH on that machine.
  1019. * @param command
  1020. * A defined drush command such as 'cron', 'status' or any of the available ones such as 'drush pm'.
  1021. * @param args
  1022. * An array of arguments for the command.
  1023. * @param command_options
  1024. * Optional. An array containing options to pass to the remote script.
  1025. * Array items with a numeric key are treated as optional arguments to the
  1026. * command. This parameter is a reference, as any options that have been
  1027. * represented as either an option, or an argument will be removed. This
  1028. * allows you to pass the left over options as a JSON encoded string,
  1029. * without duplicating data.
  1030. * @param backend_options
  1031. * Optional. An array of options for the invocation.
  1032. * @see drush_backend_invoke for documentation.
  1033. *
  1034. * @return
  1035. * A text string representing a fully escaped command.
  1036. */
  1037. function _drush_backend_generate_command($site_record, $command, $args = array(), $command_options = array(), $backend_options = array()) {
  1038. $site_record += array(
  1039. 'remote-host' => NULL,
  1040. 'remote-user' => NULL,
  1041. 'ssh-options' => NULL,
  1042. 'path-aliases' => array(),
  1043. );
  1044. $hostname = $site_record['remote-host'];
  1045. $username = $site_record['remote-user'];
  1046. $ssh_options = $site_record['ssh-options'];
  1047. $os = drush_os($site_record);
  1048. if (drush_is_local_host($hostname)) {
  1049. $hostname = null;
  1050. }
  1051. foreach ($command_options as $key => $arg) {
  1052. if (is_numeric($key)) {
  1053. $args[] = $arg;
  1054. unset($command_options[$key]);
  1055. }
  1056. }
  1057. $cmd[] = $command;
  1058. foreach ($args as $arg) {
  1059. $cmd[] = drush_escapeshellarg($arg, $os);
  1060. }
  1061. $option_str = _drush_backend_argument_string($command_options, $os);
  1062. if (!empty($option_str)) {
  1063. $cmd[] = " " . $option_str;
  1064. }
  1065. $command = implode(' ', array_filter($cmd, 'strlen'));
  1066. if (isset($hostname)) {
  1067. if (drush_is_windows($os)) {
  1068. if (isset($username)) {
  1069. $username = " -u:" . drush_escapeshellarg($username, "LOCAL");
  1070. if (array_key_exists('winrs-password', $site_record)) {
  1071. $username .= " -p:" . drush_escapeshellarg($site_record['winrs-password'], "LOCAL");
  1072. }
  1073. }
  1074. $command = "winrs" . $username . " -r:" . drush_escapeshellarg($hostname, "LOCAL") . " " . drush_escapeshellarg($command, "LOCAL");
  1075. }
  1076. else {
  1077. $username = (isset($username)) ? drush_escapeshellarg($username, "LOCAL") . "@" : '';
  1078. $ssh_options = $site_record['ssh-options'];
  1079. $ssh_options = (isset($ssh_options)) ? $ssh_options : drush_get_option('ssh-options', "-o PasswordAuthentication=no");
  1080. $ssh_cmd[] = "ssh";
  1081. $ssh_cmd[] = $ssh_options;
  1082. $ssh_cmd[] = $username . drush_escapeshellarg($hostname, "LOCAL");
  1083. $ssh_cmd[] = drush_escapeshellarg($command . ' 2>&1', "LOCAL");
  1084. // Remove NULLs and separate with spaces
  1085. $command = implode(' ', array_filter($ssh_cmd, 'strlen'));
  1086. }
  1087. }
  1088. return $command;
  1089. }
  1090. /**
  1091. * Map the options to a string containing all the possible arguments and options.
  1092. *
  1093. * @param data
  1094. * Optional. An array containing options to pass to the remote script.
  1095. * Array items with a numeric key are treated as optional arguments to the command.
  1096. * This parameter is a reference, as any options that have been represented as either an option, or an argument will be removed.
  1097. * This allows you to pass the left over options as a JSON encoded string, without duplicating data.
  1098. * @param method
  1099. * Optional. Defaults to 'GET'.
  1100. * If this parameter is set to 'POST', the $data array will be passed to the script being called as a JSON encoded string over
  1101. * the STDIN pipe of that process. This is preferable if you have to pass sensitive data such as passwords and the like.
  1102. * For any other value, the $data array will be collapsed down into a set of command line options to the script.
  1103. * @return
  1104. * A properly formatted and escaped set of arguments and options to append to the drush.php shell command.
  1105. */
  1106. function _drush_backend_argument_string($data, $os = NULL) {
  1107. $options = array();
  1108. foreach ($data as $key => $value) {
  1109. if (!is_array($value) && !is_object($value) && isset($value)) {
  1110. if (substr($key,0,1) != '#') {
  1111. $options[$key] = $value;
  1112. }
  1113. }
  1114. }
  1115. $option_str = '';
  1116. foreach ($options as $key => $value) {
  1117. $option_str .= _drush_escape_option($key, $value, $os);
  1118. }
  1119. return $option_str;
  1120. }
  1121. /**
  1122. * Return a properly formatted and escaped command line option
  1123. *
  1124. * @param key
  1125. * The name of the option.
  1126. * @param value
  1127. * The value of the option.
  1128. *
  1129. * @return
  1130. * If the value is set to TRUE, this function will return " --key"
  1131. * In other cases it will return " --key='value'"
  1132. */
  1133. function _drush_escape_option($key, $value = TRUE, $os = NULL) {
  1134. if ($value !== TRUE) {
  1135. $option_str = " --$key=" . drush_escapeshellarg($value, $os);
  1136. }
  1137. else {
  1138. $option_str = " --$key";
  1139. }
  1140. return $option_str;
  1141. }
  1142. /**
  1143. * Read options fron STDIN during POST requests.
  1144. *
  1145. * This function will read any text from the STDIN pipe,
  1146. * and attempts to generate an associative array if valid
  1147. * JSON was received.
  1148. *
  1149. * @return
  1150. * An associative array of options, if successfull. Otherwise FALSE.
  1151. */
  1152. function _drush_backend_get_stdin() {
  1153. $fp = fopen('php://stdin', 'r');
  1154. // Windows workaround: we cannot count on stream_get_contents to
  1155. // return if STDIN is reading from the keyboard. We will therefore
  1156. // check to see if there are already characters waiting on the
  1157. // stream (as there always should be, if this is a backend call),
  1158. // and if there are not, then we will exit.
  1159. // This code prevents drush from hanging forever when called with
  1160. // --backend from the commandline; however, overall it is still
  1161. // a futile effort, as it does not seem that backend invoke can
  1162. // successfully write data to that this function can read,
  1163. // so the argument list and command always come out empty. :(
  1164. // Perhaps stream_get_contents is the problem, and we should use
  1165. // the technique described here:
  1166. // http://bugs.php.net/bug.php?id=30154
  1167. // n.b. the code in that issue passes '0' for the timeout in stream_select
  1168. // in a loop, which is not recommended.
  1169. // Note that the following DOES work:
  1170. // drush ev 'print(json_encode(array("test" => "XYZZY")));' | drush status --backend
  1171. // So, redirecting input is okay, it is just the proc_open that is a problem.
  1172. if (drush_is_windows()) {
  1173. // Note that stream_select uses reference parameters, so we need variables (can't pass a constant NULL)
  1174. $read = array($fp);
  1175. $write = NULL;
  1176. $except = NULL;
  1177. // Question: might we need to wait a bit for STDIN to be ready,
  1178. // even if the process that called us immediately writes our parameters?
  1179. // Passing '100' for the timeout here causes us to hang indefinitely
  1180. // when called from the shell.
  1181. $changed_streams = stream_select($read, $write, $except, 0);
  1182. // Return on error (FALSE) or no changed streams (0).
  1183. // Oh, according to http://php.net/manual/en/function.stream-select.php,
  1184. // stream_select will return FALSE for streams returned by proc_open.
  1185. // That is not applicable to us, is it? Our stream is connected to a stream
  1186. // created by proc_open, but is not a stream returned by proc_open.
  1187. if ($changed_streams < 1) {
  1188. return FALSE;
  1189. }
  1190. }
  1191. stream_set_blocking($fp, FALSE);
  1192. $string = stream_get_contents($fp);
  1193. fclose($fp);
  1194. if (trim($string)) {
  1195. return json_decode($string, TRUE);
  1196. }
  1197. return FALSE;
  1198. }