drush/includes/context.inc

<?php
// $Id: context.inc,v 1.11 2009/10/27 16:26:37 weitzman Exp $
/**
 * @file
 * The Drush context API implementation.
 *
 * This API acts as a storage mechanism for all options,
 * arguments and configuration settings that are loaded into drush.
 *
 * This API also acts as an IPC mechanism between the different drush
 * commands, and provides protection from accidentally overriding
 * settings that are needed by other parts of the system.
 *
 * It also avoids the necessity to pass references through
 * the command chain and allows the scripts to keep track
 * of whether any settings have changed since the previous
 * execution.
 *
 * This API defines several contexts that are used by default.
 *
 * Argument contexts :
 *   These contexts are used by Drush to store information on the command.
 *   They have their own access functions in the forms of @drush_set_arguments,
 *   @drush_get_arguments, @drush_set_command, @drush_get_command.
 *
 *     command : The drush command being executed.
 *     arguments : Any additional arguments that were specified.
 *
 * Setting contexts :
 *   These contexts store options that have been passed to the drush.php
 *   script, either through the use of any of the config files, directly
 *   from the command line through --option='value' or through a JSON
 *   encoded string passed through the STDIN pipe.
 *
 *   These contexts are accessible through the @drush_get_option and @drush_set_option
 *   functions.
 *
 *   These contexts are evaluated in a certain order, and the highest priority value
 *   is returned by default from drush_get_option. This allows scripts to check whether
 *   an option was different before the current execution.
 *
 *    Specified by the script itself : 
 *      process  : Generated in the current process.
 *      options  : Passed as --option=value to the command line.
 *      stdin    : Passed as a JSON encoded string through stdin.
 *
 *    Specified by config files : 
 *      custom   : Loaded from the config file specified by --config or -c
 *      site     : Loaded from the drushrc.php file in the Drupal sites directory.
 *      drupal   : Loaded from the drushrc.php file in the Drupal root directory.
 *      user     : Loaded from the drushrc.php file in the user's home directory.
 *      system   : Loaded from the drushrc.php file in the system's $PREFIX/etc/drush directory.
 *      drush    : Loaded from the drushrc.php file in the same directory as drush.php.
 *
 *    Specified by the script, but has the lowest priority :
 *      default  : The script might provide some sensible defaults during init.
 *
 *   Drush commands may also choose to save settings for a specific context to the matching configuration
 *   file through the drush_save_config() function.
 */


/**
 * Return a list of possible drushrc file locations.
 *
 * @return
 *   An associative array containing possible config files to load
 *   The keys are the 'context' of the files, the values are the file
 *   system locations.
 */
function _drush_config_file($context) {
  $configs = array();

  // Did the user explicitly specify a config file?
  if ($config = drush_get_option(array('c', 'config'))) {
    $configs['custom'] = $config;
  }

  if ($site_path = drush_get_context('DRUSH_DRUPAL_SITE_ROOT')) {
    $configs['site'] = $site_path . "/drushrc.php";
  }

  if ($drupal_root = drush_get_context('DRUSH_DRUPAL_ROOT')) {
    $configs['drupal'] = $drupal_root . '/drushrc.php';
  }

  // in the user home directory
  // $_SERVER['HOME'] isn't set on windows and generates a Notice.
  if(isset($_SERVER['HOME'])){
    $configs['user'] = $_SERVER['HOME'] . '/.drushrc.php';
  }
  else{
    // home on windows
    $configs['user'] = $_SERVER['HOMEDRIVE'] . $_SERVER['HOMEPATH'] . '/.drushrc.php';
  }


  // In the system wide configuration folder.
  $configs['system'] = drush_get_context('ETC_PREFIX', '') . '/etc/drush/drushrc.php';

  // in the drush installation folder
  $configs['drush'] = dirname(__FILE__) . '/../drushrc.php';

  return empty($configs[$context]) ? '' : $configs[$context];
}


/**
 * Load drushrc files (if available) from several possible locations.
 */
function drush_load_config($context) {
  global $drush_conf_override;
  
  $drush_conf_override = array();

  $config = _drush_config_file($context);
  if (file_exists($config)) {
    drush_log(dt('Loading drushrc "!config" into "!context" scope.', array('!config' => realpath($config), '!context' => $context)), 'bootstrap');
    require_once($config);
    
    // If site aliases are defined in multiple drush configuration files,
    // the normal mechanism would cause the highest priority 'site-aliases'
    // array to mask all of the other aliases defined in different contexts.
    // To allow all of the aliases defined in every context to be used together,
    // we merge them all into the 'drush' context as they are encountered.
    if (($context != 'drush') && (array_key_exists('site-aliases', $options))) {
      $cache =& drush_get_context('drush');
      if (array_key_exists('site-aliases', $cache)) {
        $cache['site-aliases'] = array_merge($cache['site-aliases'], $options['site-aliases']);
      }
      else {
        $cache['site-aliases'] = $options['site-aliases'];
      }
      unset($options['site-aliases']);
    }
    
    drush_set_context($context, $options);
    
    // Instruct core not to queries since we are not outputting them.
    // This can be overridden by a command or a drushrc file if needed.
    if (!isset($drush_conf_override['dev_query'])) {
      $drush_conf_override['dev_query'] = FALSE;
    }

    /**
     * Allow the drushrc.php file to override $conf settings.
     * This is a separate variable because the $conf array gets
     * initialized to an empty array, in the drupal bootstrap process,
     * and changes in settings.php would wipe out the drushrc.php settings.
     */
    if (!empty($override)) {
      $drush_conf_override = array_merge($drush_conf_override, $override);
    }
  }
}

/**
 * Set a specific context.
 *
 * @param context
 *   Any of the default defined contexts.
 * @param value 
 *   The value to store in the context
 * 
 * @return
 *   An associative array of the settings specified in the request context.
 */
function drush_set_context($context, $value) {
  $cache =& drush_get_context($context);
  $cache = $value;
  return $value;
}


/**
 * Return a specific context, or the whole context cache
 *
 * This function provides a storage mechanism for any information
 * the currently running process might need to communicate.
 *
 * This avoids the use of globals, and constants.
 *
 * Functions that operate on the context cache, can retrieve a reference
 * to the context cache using :
 *     $cache = &drush_get_context($context);
 *
 * This is a private function, because it is meant as an internal 
 * generalized API for writing static cache functions, not as a general
 * purpose function to be used inside commands.
 * 
 * Code that modifies the reference directly might have unexpected consequences,
 * such as modifying the arguments after they have already been parsed and dispatched
 * to the callbacks.
 *
 * @param context
 *   Optional. Any of the default defined contexts. 
 @
 * @return 
 *   If context is not supplied, the entire context cache will be returned.
 *   Otherwise only the requested context will be returned.
 *   If the context does not exist yet, it will be initialied to an empty array.
 */
function &drush_get_context($context = null, $default = null) {
  static $cache = array();
  if (!is_null($context)) {
    if (!isset($cache[$context])) {
      $default = !is_null($default) ? $default : array();
      $cache[$context] = $default;
    }
    return $cache[$context];
  }
  return $cache;
}

/**
 * Set the arguments passed to the drush.php script.
 *
 * This function will set the 'arguments' context of the current running script.
 *
 * When initially called by drush_parse_options, the entire list of arguments will
 * be populated, once the command is dispatched, this will be set to only the remaining
 * arguments to the command.
 *
 * @param arguments
 *   Command line arguments, as an array. 
 */
function drush_set_arguments($arguments) {
  drush_set_context('arguments', $arguments);
}

/**
 * Get the arguments passed to the drush.php script.
 *
 * When drush_set_arguments is initially called by drush_parse_options, 
 * the entire list of arguments will be populated.
 * Once the command has been dispatched, this will be return only the remaining
 * arguments to the command.
 */
function drush_get_arguments() {
  return drush_get_context('arguments');
}

/**
 * Set the command being executed.
 *
 * Drush_dispatch will set the correct command based on it's
 * matching of the script arguments retrieved from drush_get_arguments
 * to the implemented commands specified by drush_get_commands.
 *
 * @param
 *   A numerically indexed array of command components.
 */
function drush_set_command($command) {
  drush_set_context('command', $command);
}

/**
 * Return the command being executed.
 *
 * 
 */
function drush_get_command() {
  return drush_get_context('command');
}
/**
 * Get the value for an option.
 *
 * If the first argument is an array, then it checks whether one of the options
 * exists and return the value of the first one found. Useful for allowing both
 * -h and --host-name
 *
 * @param option
 *   The name of the option to get
 * @param default
 *   Optional. The value to return if the option has not been set
 * @param context
 *   Optional. The context to check for the option. If this is set, only this context will be searched.
 */
function drush_get_option($option, $default = NULL, $context = NULL) {
  $value = null;

  if ($context) {
    // We have a definite context to check for the presence of an option.
    $value = _drush_get_option($option, drush_get_context($context));
  }
  else {
    // We are not checking a specific context, so check them in a predefined order of precedence.
    static $contexts = array(
      'process', 'options', 'stdin', 'alias',
      'custom', 'site', 'drupal', 'user', 'system', 
      'drush', 'default');

    foreach ($contexts as $context) {
      $value = _drush_get_option($option, drush_get_context($context));

      if ($value !== null) {
        return $value;
      }
    }
  }

  if ($value !== null) {
    return $value;
  }

  return $default;
}

/**
 * Retrieves a collapsed list of all options
 */
function drush_get_merged_options() {
  static $contexts = array(
      'process', 'options', 'stdin', 'alias', 
      'custom', 'site', 'drupal', 'user', 'system',
      'drush', 'default');
  $cache = drush_get_context();
  $result = array();
  foreach (array_reverse($contexts) as $context) {
    if (array_key_exists($context, $cache)) {
      $result = array_merge($result, $cache[$context]);
    }
  }

  return $result;
}

/**
 * Helper function to recurse through possible option names
 */
function _drush_get_option($option, $context) {
  if (is_array($option)) {
    foreach ($option as $current) {
      if (array_key_exists($current, $context)) {
        return $context[$current];
      }
    }
  }
  elseif (array_key_exists($option, $context)) {
    return $context[$option];
  }

  return null;
}

/**
 * Set an option in one of the option contexts.
 * 
 * @param option
 *   The option to set.
 * @param value
 *   The value to set it to.
 * @param context
 *   Optional. Which context to set it in.
 * @return
 *   The value parameter. This allows for neater code such as 
 *     $myvalue = drush_set_option('http_host', $_SERVER['HTTP_HOST']);
 *   Without having to constantly type out the value parameter.
 */
function drush_set_option($option, $value, $context = 'process') {
  $cache =& drush_get_context($context);
  $cache[$option] = $value;
  return $value;
}

/**
 * A small helper function to set the value in the default context
 */
function drush_set_default($option, $value) {
  return drush_set_option($option, $value, 'default');
}

/**
 * Remove a setting from a specific context.
 *
 * @param
 *   Option to be unset
 * @param
 *   Context in which to unset the value in.
 */
function drush_unset_option($option, $context) {
  $cache =& drush_get_context($context);
  if (array_key_exists($option, $cache)) {
    unset($cache[$option]);
  }
}

/**
 * Save the settings in a specific context to the applicable configuration file
 * This is useful is you want certain settings to be available automatically the next time a command is executed.
 *
 * @param $context
 *   The context to save
 */
function drush_save_config($context) {
  $filename = _drush_config_file($context);

  if ($filename) {
    $cache = drush_get_context($context);

    $fp = fopen($filename, "w+");
    if (!$fp) {
      return drush_set_error('DRUSH_PERM_ERROR', dt('Drushrc (!filename) could not be written', array('!filename' => $filename)));
    }
    else {
      fwrite($fp, "<?php\n");
      $timestamp = mktime();
      foreach ($cache as $key => $value) {
        $line = "\n\$options['$key'] = ". var_export($value, TRUE) .';';
        fwrite($fp, $line);  
      }
      fwrite($fp, "\n");
      fclose($fp);
      drush_log(dt('Drushrc file (!filename) was written successfully', array('!filename' => $filename)));
      return true;
    }

  }
  return false;
}
1	<?php
2	// $Id: context.inc,v 1.11 2009/10/27 16:26:37 weitzman Exp $
3	/**
4	* @file
5	* The Drush context API implementation.
6	*
7	* This API acts as a storage mechanism for all options,
8	* arguments and configuration settings that are loaded into drush.
9	*
10	* This API also acts as an IPC mechanism between the different drush
11	* commands, and provides protection from accidentally overriding
12	* settings that are needed by other parts of the system.
13	*
14	* It also avoids the necessity to pass references through
15	* the command chain and allows the scripts to keep track
16	* of whether any settings have changed since the previous
17	* execution.
18	*
19	* This API defines several contexts that are used by default.
20	*
21	* Argument contexts :
22	* These contexts are used by Drush to store information on the command.
23	* They have their own access functions in the forms of @drush_set_arguments,
24	* @drush_get_arguments, @drush_set_command, @drush_get_command.
25	*
26	* command : The drush command being executed.
27	* arguments : Any additional arguments that were specified.
28	*
29	* Setting contexts :
30	* These contexts store options that have been passed to the drush.php
31	* script, either through the use of any of the config files, directly
32	* from the command line through --option='value' or through a JSON
33	* encoded string passed through the STDIN pipe.
34	*
35	* These contexts are accessible through the @drush_get_option and @drush_set_option
36	* functions.
37	*
38	* These contexts are evaluated in a certain order, and the highest priority value
39	* is returned by default from drush_get_option. This allows scripts to check whether
40	* an option was different before the current execution.
41	*
42	* Specified by the script itself :
43	* process : Generated in the current process.
44	* options : Passed as --option=value to the command line.
45	* stdin : Passed as a JSON encoded string through stdin.
46	*
47	* Specified by config files :
48	* custom : Loaded from the config file specified by --config or -c
49	* site : Loaded from the drushrc.php file in the Drupal sites directory.
50	* drupal : Loaded from the drushrc.php file in the Drupal root directory.
51	* user : Loaded from the drushrc.php file in the user's home directory.
52	* system : Loaded from the drushrc.php file in the system's $PREFIX/etc/drush directory.
53	* drush : Loaded from the drushrc.php file in the same directory as drush.php.
54	*
55	* Specified by the script, but has the lowest priority :
56	* default : The script might provide some sensible defaults during init.
57	*
58	* Drush commands may also choose to save settings for a specific context to the matching configuration
59	* file through the drush_save_config() function.
60	*/
61
62
63	/**
64	* Return a list of possible drushrc file locations.
65	*
66	* @return
67	* An associative array containing possible config files to load
68	* The keys are the 'context' of the files, the values are the file
69	* system locations.
70	*/
71	function _drush_config_file($context) {
72	$configs = array();
73
74	// Did the user explicitly specify a config file?
75	if ($config = drush_get_option(array('c', 'config'))) {
76	$configs['custom'] = $config;
77	}
78
79	if ($site_path = drush_get_context('DRUSH_DRUPAL_SITE_ROOT')) {
80	$configs['site'] = $site_path . "/drushrc.php";
81	}
82
83	if ($drupal_root = drush_get_context('DRUSH_DRUPAL_ROOT')) {
84	$configs['drupal'] = $drupal_root . '/drushrc.php';
85	}
86
87	// in the user home directory
88	// $_SERVER['HOME'] isn't set on windows and generates a Notice.
89	if(isset($_SERVER['HOME'])){
90	$configs['user'] = $_SERVER['HOME'] . '/.drushrc.php';
91	}
92	else{
93	// home on windows
94	$configs['user'] = $_SERVER['HOMEDRIVE'] . $_SERVER['HOMEPATH'] . '/.drushrc.php';
95	}
96
97
98	// In the system wide configuration folder.
99	$configs['system'] = drush_get_context('ETC_PREFIX', '') . '/etc/drush/drushrc.php';
100
101	// in the drush installation folder
102	$configs['drush'] = dirname(__FILE__) . '/../drushrc.php';
103
104	return empty($configs[$context]) ? '' : $configs[$context];
105	}
106
107
108	/**
109	* Load drushrc files (if available) from several possible locations.
110	*/
111	function drush_load_config($context) {
112	global $drush_conf_override;
113
114	$drush_conf_override = array();
115
116	$config = _drush_config_file($context);
117	if (file_exists($config)) {
118	drush_log(dt('Loading drushrc "!config" into "!context" scope.', array('!config' => realpath($config), '!context' => $context)), 'bootstrap');
119	require_once($config);
120
121	// If site aliases are defined in multiple drush configuration files,
122	// the normal mechanism would cause the highest priority 'site-aliases'
123	// array to mask all of the other aliases defined in different contexts.
124	// To allow all of the aliases defined in every context to be used together,
125	// we merge them all into the 'drush' context as they are encountered.
126	if (($context != 'drush') && (array_key_exists('site-aliases', $options))) {
127	$cache =& drush_get_context('drush');
128	if (array_key_exists('site-aliases', $cache)) {
129	$cache['site-aliases'] = array_merge($cache['site-aliases'], $options['site-aliases']);
130	}
131	else {
132	$cache['site-aliases'] = $options['site-aliases'];
133	}
134	unset($options['site-aliases']);
135	}
136
137	drush_set_context($context, $options);
138
139	// Instruct core not to queries since we are not outputting them.
140	// This can be overridden by a command or a drushrc file if needed.
141	if (!isset($drush_conf_override['dev_query'])) {
142	$drush_conf_override['dev_query'] = FALSE;
143	}
144
145	/**
146	* Allow the drushrc.php file to override $conf settings.
147	* This is a separate variable because the $conf array gets
148	* initialized to an empty array, in the drupal bootstrap process,
149	* and changes in settings.php would wipe out the drushrc.php settings.
150	*/
151	if (!empty($override)) {
152	$drush_conf_override = array_merge($drush_conf_override, $override);
153	}
154	}
155	}
156
157	/**
158	* Set a specific context.
159	*
160	* @param context
161	* Any of the default defined contexts.
162	* @param value
163	* The value to store in the context
164	*
165	* @return
166	* An associative array of the settings specified in the request context.
167	*/
168	function drush_set_context($context, $value) {
169	$cache =& drush_get_context($context);
170	$cache = $value;
171	return $value;
172	}
173
174
175	/**
176	* Return a specific context, or the whole context cache
177	*
178	* This function provides a storage mechanism for any information
179	* the currently running process might need to communicate.
180	*
181	* This avoids the use of globals, and constants.
182	*
183	* Functions that operate on the context cache, can retrieve a reference
184	* to the context cache using :
185	* $cache = &drush_get_context($context);
186	*
187	* This is a private function, because it is meant as an internal
188	* generalized API for writing static cache functions, not as a general
189	* purpose function to be used inside commands.
190	*
191	* Code that modifies the reference directly might have unexpected consequences,
192	* such as modifying the arguments after they have already been parsed and dispatched
193	* to the callbacks.
194	*
195	* @param context
196	* Optional. Any of the default defined contexts.
197	@
198	* @return
199	* If context is not supplied, the entire context cache will be returned.
200	* Otherwise only the requested context will be returned.
201	* If the context does not exist yet, it will be initialied to an empty array.
202	*/
203	function &drush_get_context($context = null, $default = null) {
204	static $cache = array();
205	if (!is_null($context)) {
206	if (!isset($cache[$context])) {
207	$default = !is_null($default) ? $default : array();
208	$cache[$context] = $default;
209	}
210	return $cache[$context];
211	}
212	return $cache;
213	}
214
215	/**
216	* Set the arguments passed to the drush.php script.
217	*
218	* This function will set the 'arguments' context of the current running script.
219	*
220	* When initially called by drush_parse_options, the entire list of arguments will
221	* be populated, once the command is dispatched, this will be set to only the remaining
222	* arguments to the command.
223	*
224	* @param arguments
225	* Command line arguments, as an array.
226	*/
227	function drush_set_arguments($arguments) {
228	drush_set_context('arguments', $arguments);
229	}
230
231	/**
232	* Get the arguments passed to the drush.php script.
233	*
234	* When drush_set_arguments is initially called by drush_parse_options,
235	* the entire list of arguments will be populated.
236	* Once the command has been dispatched, this will be return only the remaining
237	* arguments to the command.
238	*/
239	function drush_get_arguments() {
240	return drush_get_context('arguments');
241	}
242
243	/**
244	* Set the command being executed.
245	*
246	* Drush_dispatch will set the correct command based on it's
247	* matching of the script arguments retrieved from drush_get_arguments
248	* to the implemented commands specified by drush_get_commands.
249	*
250	* @param
251	* A numerically indexed array of command components.
252	*/
253	function drush_set_command($command) {
254	drush_set_context('command', $command);
255	}
256
257	/**
258	* Return the command being executed.
259	*
260	*
261	*/
262	function drush_get_command() {
263	return drush_get_context('command');
264	}
265	/**
266	* Get the value for an option.
267	*
268	* If the first argument is an array, then it checks whether one of the options
269	* exists and return the value of the first one found. Useful for allowing both
270	* -h and --host-name
271	*
272	* @param option
273	* The name of the option to get
274	* @param default
275	* Optional. The value to return if the option has not been set
276	* @param context
277	* Optional. The context to check for the option. If this is set, only this context will be searched.
278	*/
279	function drush_get_option($option, $default = NULL, $context = NULL) {
280	$value = null;
281
282	if ($context) {
283	// We have a definite context to check for the presence of an option.
284	$value = _drush_get_option($option, drush_get_context($context));
285	}
286	else {
287	// We are not checking a specific context, so check them in a predefined order of precedence.
288	static $contexts = array(
289	'process', 'options', 'stdin', 'alias',
290	'custom', 'site', 'drupal', 'user', 'system',
291	'drush', 'default');
292
293	foreach ($contexts as $context) {
294	$value = _drush_get_option($option, drush_get_context($context));
295
296	if ($value !== null) {
297	return $value;
298	}
299	}
300	}
301
302	if ($value !== null) {
303	return $value;
304	}
305
306	return $default;
307	}
308
309	/**
310	* Retrieves a collapsed list of all options
311	*/
312	function drush_get_merged_options() {
313	static $contexts = array(
314	'process', 'options', 'stdin', 'alias',
315	'custom', 'site', 'drupal', 'user', 'system',
316	'drush', 'default');
317	$cache = drush_get_context();
318	$result = array();
319	foreach (array_reverse($contexts) as $context) {
320	if (array_key_exists($context, $cache)) {
321	$result = array_merge($result, $cache[$context]);
322	}
323	}
324
325	return $result;
326	}
327
328	/**
329	* Helper function to recurse through possible option names
330	*/
331	function _drush_get_option($option, $context) {
332	if (is_array($option)) {
333	foreach ($option as $current) {
334	if (array_key_exists($current, $context)) {
335	return $context[$current];
336	}
337	}
338	}
339	elseif (array_key_exists($option, $context)) {
340	return $context[$option];
341	}
342
343	return null;
344	}
345
346	/**
347	* Set an option in one of the option contexts.
348	*
349	* @param option
350	* The option to set.
351	* @param value
352	* The value to set it to.
353	* @param context
354	* Optional. Which context to set it in.
355	* @return
356	* The value parameter. This allows for neater code such as
357	* $myvalue = drush_set_option('http_host', $_SERVER['HTTP_HOST']);
358	* Without having to constantly type out the value parameter.
359	*/
360	function drush_set_option($option, $value, $context = 'process') {
361	$cache =& drush_get_context($context);
362	$cache[$option] = $value;
363	return $value;
364	}
365
366	/**
367	* A small helper function to set the value in the default context
368	*/
369	function drush_set_default($option, $value) {
370	return drush_set_option($option, $value, 'default');
371	}
372
373	/**
374	* Remove a setting from a specific context.
375	*
376	* @param
377	* Option to be unset
378	* @param
379	* Context in which to unset the value in.
380	*/
381	function drush_unset_option($option, $context) {
382	$cache =& drush_get_context($context);
383	if (array_key_exists($option, $cache)) {
384	unset($cache[$option]);
385	}
386	}
387
388	/**
389	* Save the settings in a specific context to the applicable configuration file
390	* This is useful is you want certain settings to be available automatically the next time a command is executed.
391	*
392	* @param $context
393	* The context to save
394	*/
395	function drush_save_config($context) {
396	$filename = _drush_config_file($context);
397
398	if ($filename) {
399	$cache = drush_get_context($context);
400
401	$fp = fopen($filename, "w+");
402	if (!$fp) {
403	return drush_set_error('DRUSH_PERM_ERROR', dt('Drushrc (!filename) could not be written', array('!filename' => $filename)));
404	}
405	else {
406	fwrite($fp, "<?php\n");
407	$timestamp = mktime();
408	foreach ($cache as $key => $value) {
409	$line = "\n\$options['$key'] = ". var_export($value, TRUE) .';';
410	fwrite($fp, $line);
411	}
412	fwrite($fp, "\n");
413	fclose($fp);
414	drush_log(dt('Drushrc file (!filename) was written successfully', array('!filename' => $filename)));
415	return true;
416	}
417
418	}
419	return false;
420	}