3 * PEAR_Task_Common, base class for installer tasks
9 * @author Greg Beaver <cellog@php.net>
10 * @copyright 1997-2009 The Authors
11 * @license http://opensource.org/licenses/bsd-license.php New BSD License
12 * @version CVS: $Id: Common.php 313023 2011-07-06 19:17:11Z dufuz $
13 * @link http://pear.php.net/package/PEAR
14 * @since File available since Release 1.4.0a1
17 * Error codes for task validation routines
19 define('PEAR_TASK_ERROR_NOATTRIBS', 1);
20 define('PEAR_TASK_ERROR_MISSING_ATTRIB', 2);
21 define('PEAR_TASK_ERROR_WRONG_ATTRIB_VALUE', 3);
22 define('PEAR_TASK_ERROR_INVALID', 4);
24 define('PEAR_TASK_PACKAGE', 1);
25 define('PEAR_TASK_INSTALL', 2);
26 define('PEAR_TASK_PACKAGEANDINSTALL', 3);
28 * A task is an operation that manipulates the contents of a file.
30 * Simple tasks operate on 1 file. Multiple tasks are executed after all files have been
31 * processed and installed, and are designed to operate on all files containing the task.
32 * The Post-install script task simply takes advantage of the fact that it will be run
33 * after installation, replace is a simple task.
35 * Combining tasks is possible, but ordering is significant.
37 * <file name="test.php" role="php">
38 * <tasks:replace from="@data-dir@" to="data_dir" type="pear-config"/>
39 * <tasks:postinstallscript/>
42 * This will first replace any instance of @data-dir@ in the test.php file
43 * with the path to the current data directory. Then, it will include the
44 * test.php file and run the script it contains to configure the package post-installation.
47 * @author Greg Beaver <cellog@php.net>
48 * @copyright 1997-2009 The Authors
49 * @license http://opensource.org/licenses/bsd-license.php New BSD License
50 * @version Release: 1.9.4
51 * @link http://pear.php.net/package/PEAR
52 * @since Class available since Release 1.4.0a1
55 class PEAR_Task_Common
58 * Valid types for this version are 'simple' and 'multiple'
60 * - simple tasks operate on the contents of a file and write out changes to disk
61 * - multiple tasks operate on the contents of many files and write out the
62 * changes directly to disk
64 * Child task classes must override this property.
69 * Determines which install phase this task is executed under
71 var $phase = PEAR_TASK_INSTALL;
92 function PEAR_Task_Common(&$config, &$logger, $phase)
94 $this->config = &$config;
95 $this->registry = &$config->getRegistry();
96 $this->logger = &$logger;
97 $this->installphase = $phase;
98 if ($this->type == 'multiple') {
99 $GLOBALS['_PEAR_TASK_POSTINSTANCES'][get_class($this)][] = &$this;
104 * Validate the basic contents of a task tag.
105 * @param PEAR_PackageFile_v2
108 * @param array the entire parsed <file> tag
109 * @return true|array On error, return an array in format:
110 * array(PEAR_TASK_ERROR_???[, param1][, param2][, ...])
112 * For PEAR_TASK_ERROR_MISSING_ATTRIB, pass the attribute name in
113 * For PEAR_TASK_ERROR_WRONG_ATTRIB_VALUE, pass the attribute name and an array
118 function validateXml($pkg, $xml, $config, $fileXml)
123 * Initialize a task instance with the parameters
124 * @param array raw, parsed xml
125 * @param array attributes from the <file> tag containing this task
126 * @param string|null last installed version of this package
129 function init($xml, $fileAttributes, $lastVersion)
134 * Begin a task processing session. All multiple tasks will be processed after each file
135 * has been successfully installed, all simple tasks should perform their task here and
136 * return any errors using the custom throwError() method to allow forward compatibility
138 * This method MUST NOT write out any changes to disk
139 * @param PEAR_PackageFile_v2
140 * @param string file contents
141 * @param string the eventual final file location (informational only)
142 * @return string|false|PEAR_Error false to skip this file, PEAR_Error to fail
143 * (use $this->throwError), otherwise return the new contents
146 function startSession($pkg, $contents, $dest)
151 * This method is used to process each of the tasks for a particular multiple class
152 * type. Simple tasks need not implement this method.
153 * @param array an array of tasks
166 function hasPostinstallTasks()
168 return isset($GLOBALS['_PEAR_TASK_POSTINSTANCES']);
175 function runPostinstallTasks()
177 foreach ($GLOBALS['_PEAR_TASK_POSTINSTANCES'] as $class => $tasks) {
178 $err = call_user_func(array($class, 'run'),
179 $GLOBALS['_PEAR_TASK_POSTINSTANCES'][$class]);
181 return PEAR_Task_Common::throwError($err);
184 unset($GLOBALS['_PEAR_TASK_POSTINSTANCES']);
188 * Determines whether a role is a script
193 return $this->type == 'script';
196 function throwError($msg, $code = -1)
198 include_once 'PEAR.php';
199 return PEAR::raiseError($msg, $code);