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 * @link http://pear.php.net/package/PEAR
13 * @since File available since Release 1.4.0a1
16 * Error codes for task validation routines
18 define('PEAR_TASK_ERROR_NOATTRIBS', 1);
19 define('PEAR_TASK_ERROR_MISSING_ATTRIB', 2);
20 define('PEAR_TASK_ERROR_WRONG_ATTRIB_VALUE', 3);
21 define('PEAR_TASK_ERROR_INVALID', 4);
23 define('PEAR_TASK_PACKAGE', 1);
24 define('PEAR_TASK_INSTALL', 2);
25 define('PEAR_TASK_PACKAGEANDINSTALL', 3);
27 * A task is an operation that manipulates the contents of a file.
29 * Simple tasks operate on 1 file. Multiple tasks are executed after all files have been
30 * processed and installed, and are designed to operate on all files containing the task.
31 * The Post-install script task simply takes advantage of the fact that it will be run
32 * after installation, replace is a simple task.
34 * Combining tasks is possible, but ordering is significant.
36 * <file name="test.php" role="php">
37 * <tasks:replace from="@data-dir@" to="data_dir" type="pear-config"/>
38 * <tasks:postinstallscript/>
41 * This will first replace any instance of @data-dir@ in the test.php file
42 * with the path to the current data directory. Then, it will include the
43 * 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.10.1
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.
68 protected $type = 'simple';
70 * Determines which install phase this task is executed under
72 public $phase = PEAR_TASK_INSTALL;
88 protected $installphase;
93 function __construct(&$config, &$logger, $phase)
95 $this->config = &$config;
96 $this->registry = &$config->getRegistry();
97 $this->logger = &$logger;
98 $this->installphase = $phase;
99 if ($this->type == 'multiple') {
100 $GLOBALS['_PEAR_TASK_POSTINSTANCES'][get_class($this)][] = &$this;
105 * Validate the basic contents of a task tag.
107 * @param PEAR_PackageFile_v2
110 * @param array the entire parsed <file> tag
112 * @return true|array On error, return an array in format:
113 * array(PEAR_TASK_ERROR_???[, param1][, param2][, ...])
115 * For PEAR_TASK_ERROR_MISSING_ATTRIB, pass the attribute name in
116 * For PEAR_TASK_ERROR_WRONG_ATTRIB_VALUE, pass the attribute name and
117 * an array of legal values in
121 public static function validateXml($pkg, $xml, $config, $fileXml)
126 * Initialize a task instance with the parameters
128 * @param array raw, parsed xml
129 * @param array attributes from the <file> tag containing this task
130 * @param string|null last installed version of this package
133 public function init($xml, $fileAttributes, $lastVersion)
138 * Begin a task processing session. All multiple tasks will be processed
139 * after each file has been successfully installed, all simple tasks should
140 * perform their task here and return any errors using the custom
141 * throwError() method to allow forward compatibility
143 * This method MUST NOT write out any changes to disk
145 * @param PEAR_PackageFile_v2
146 * @param string file contents
147 * @param string the eventual final file location (informational only)
148 * @return string|false|PEAR_Error false to skip this file, PEAR_Error to fail
149 * (use $this->throwError), otherwise return the new contents
152 public function startSession($pkg, $contents, $dest)
157 * This method is used to process each of the tasks for a particular
158 * multiple class type. Simple tasks need not implement this method.
160 * @param array an array of tasks
163 public static function run($tasks)
170 public static function hasPostinstallTasks()
172 return isset($GLOBALS['_PEAR_TASK_POSTINSTANCES']);
178 public static function runPostinstallTasks()
180 foreach ($GLOBALS['_PEAR_TASK_POSTINSTANCES'] as $class => $tasks) {
181 $err = call_user_func(
182 array($class, 'run'),
183 $GLOBALS['_PEAR_TASK_POSTINSTANCES'][$class]
186 return PEAR_Task_Common::throwError($err);
189 unset($GLOBALS['_PEAR_TASK_POSTINSTANCES']);
193 * Determines whether a role is a script
196 public function isScript()
198 return $this->type == 'script';
201 public function throwError($msg, $code = -1)
203 include_once 'PEAR.php';
205 return PEAR::raiseError($msg, $code);