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