PEAR

Base class for other PEAR classes.

Defined (1)

The class is defined in the following location(s).

/inc/pear/pear.php  
  1. class PEAR 
  2. // {{{ properties 
  3.  
  4. /** 
  5. * Whether to enable internal debug messages. 
  6. * @var bool 
  7. * @access private 
  8. */ 
  9. var $_debug = false; 
  10.  
  11. /** 
  12. * Default error mode for this object. 
  13. * @var int 
  14. * @access private 
  15. */ 
  16. var $_default_error_mode = null; 
  17.  
  18. /** 
  19. * Default error options used for this object when error mode 
  20. * is PEAR_ERROR_TRIGGER. 
  21. * @var int 
  22. * @access private 
  23. */ 
  24. var $_default_error_options = null; 
  25.  
  26. /** 
  27. * Default error handler (callback) for this object, if error mode is 
  28. * PEAR_ERROR_CALLBACK. 
  29. * @var string 
  30. * @access private 
  31. */ 
  32. var $_default_error_handler = ''; 
  33.  
  34. /** 
  35. * Which class to use for error objects. 
  36. * @var string 
  37. * @access private 
  38. */ 
  39. var $_error_class = 'PEAR_Error'; 
  40.  
  41. /** 
  42. * An array of expected errors. 
  43. * @var array 
  44. * @access private 
  45. */ 
  46. var $_expected_errors = array(); 
  47.  
  48. // }}} 
  49.  
  50. // {{{ constructor 
  51.  
  52. /** 
  53. * Constructor. Registers this object in 
  54. * $_PEAR_destructor_object_list for destructor emulation if a 
  55. * destructor object exists. 
  56. * @param string $error_class (optional) which class to use for 
  57. * error objects, defaults to PEAR_Error. 
  58. * @access public 
  59. * @return void 
  60. */ 
  61. function PEAR($error_class = null) 
  62. $classname = strtolower(get_class($this)); 
  63. if ($this->_debug) { 
  64. print "PEAR constructor called, class=$classname\n"; 
  65. if ($error_class !== null) { 
  66. $this->_error_class = $error_class; 
  67. while ($classname && strcasecmp($classname, "pear")) { 
  68. $destructor = "_$classname"; 
  69. if (method_exists($this, $destructor)) { 
  70. global $_PEAR_destructor_object_list; 
  71. $_PEAR_destructor_object_list[] = &$this; 
  72. if (!isset($GLOBALS['_PEAR_SHUTDOWN_REGISTERED'])) { 
  73. register_shutdown_function("_PEAR_call_destructors"); 
  74. $GLOBALS['_PEAR_SHUTDOWN_REGISTERED'] = true; 
  75. break; 
  76. } else { 
  77. $classname = get_parent_class($classname); 
  78.  
  79. // }}} 
  80. // {{{ destructor 
  81.  
  82. /** 
  83. * Destructor (the emulated type of...). Does nothing right now,  
  84. * but is included for forward compatibility, so subclass 
  85. * destructors should always call it. 
  86. * See the note in the class desciption about output from 
  87. * destructors. 
  88. * @access public 
  89. * @return void 
  90. */ 
  91. function _PEAR() { 
  92. if ($this->_debug) { 
  93. printf("PEAR destructor called, class=%s\n", strtolower(get_class($this))); 
  94.  
  95. // }}} 
  96. // {{{ getStaticProperty() 
  97.  
  98. /** 
  99. * If you have a class that's mostly/entirely static, and you need static 
  100. * properties, you can use this method to simulate them. Eg. in your method(s) 
  101. * do this: $myVar = &PEAR::getStaticProperty('myclass', 'myVar'); 
  102. * You MUST use a reference, or they will not persist! 
  103. * @access public 
  104. * @param string $class The calling classname, to prevent clashes 
  105. * @param string $var The variable to retrieve. 
  106. * @return mixed A reference to the variable. If not set it will be 
  107. * auto initialised to NULL. 
  108. */ 
  109. function &getStaticProperty($class, $var) 
  110. static $properties; 
  111. return $properties[$class][$var]; 
  112.  
  113. // }}} 
  114. // {{{ registerShutdownFunc() 
  115.  
  116. /** 
  117. * Use this function to register a shutdown method for static 
  118. * classes. 
  119. * @access public 
  120. * @param mixed $func The function name (or array of class/method) to call 
  121. * @param mixed $args The arguments to pass to the function 
  122. * @return void 
  123. */ 
  124. function registerShutdownFunc($func, $args = array()) 
  125. // if we are called statically, there is a potential 
  126. // that no shutdown func is registered. Bug #6445 
  127. if (!isset($GLOBALS['_PEAR_SHUTDOWN_REGISTERED'])) { 
  128. register_shutdown_function("_PEAR_call_destructors"); 
  129. $GLOBALS['_PEAR_SHUTDOWN_REGISTERED'] = true; 
  130. $GLOBALS['_PEAR_shutdown_funcs'][] = array($func, $args); 
  131.  
  132. // }}} 
  133. // {{{ isError() 
  134.  
  135. /** 
  136. * Tell whether a value is a PEAR error. 
  137. * @param mixed $data the value to test 
  138. * @param int $code if $data is an error object, return true 
  139. * only if $code is a string and 
  140. * $obj->getMessage() == $code or 
  141. * $code is an integer and $obj->getCode() == $code 
  142. * @access public 
  143. * @return bool true if parameter is an error 
  144. */ 
  145. function isError($data, $code = null) 
  146. if (is_a($data, 'PEAR_Error')) { 
  147. if (is_null($code)) { 
  148. return true; 
  149. } elseif (is_string($code)) { 
  150. return $data->getMessage() == $code; 
  151. } else { 
  152. return $data->getCode() == $code; 
  153. return false; 
  154.  
  155. // }}} 
  156. // {{{ setErrorHandling() 
  157.  
  158. /** 
  159. * Sets how errors generated by this object should be handled. 
  160. * Can be invoked both in objects and statically. If called 
  161. * statically, setErrorHandling sets the default behaviour for all 
  162. * PEAR objects. If called in an object, setErrorHandling sets 
  163. * the default behaviour for that object. 
  164. * @param int $mode 
  165. * One of PEAR_ERROR_RETURN, PEAR_ERROR_PRINT,  
  166. * PEAR_ERROR_TRIGGER, PEAR_ERROR_DIE,  
  167. * PEAR_ERROR_CALLBACK or PEAR_ERROR_EXCEPTION. 
  168. * @param mixed $options 
  169. * When $mode is PEAR_ERROR_TRIGGER, this is the error level (one 
  170. * of E_USER_NOTICE, E_USER_WARNING or E_USER_ERROR). 
  171. * When $mode is PEAR_ERROR_CALLBACK, this parameter is expected 
  172. * to be the callback function or method. A callback 
  173. * function is a string with the name of the function, a 
  174. * callback method is an array of two elements: the element 
  175. * at index 0 is the object, and the element at index 1 is 
  176. * the name of the method to call in the object. 
  177. * When $mode is PEAR_ERROR_PRINT or PEAR_ERROR_DIE, this is 
  178. * a printf format string used when printing the error 
  179. * message. 
  180. * @access public 
  181. * @return void 
  182. * @see PEAR_ERROR_RETURN 
  183. * @see PEAR_ERROR_PRINT 
  184. * @see PEAR_ERROR_TRIGGER 
  185. * @see PEAR_ERROR_DIE 
  186. * @see PEAR_ERROR_CALLBACK 
  187. * @see PEAR_ERROR_EXCEPTION 
  188. * @since PHP 4.0.5 
  189. */ 
  190.  
  191. function setErrorHandling($mode = null, $options = null) 
  192. if (isset($this) && is_a($this, 'PEAR')) { 
  193. $setmode = &$this->_default_error_mode; 
  194. $setoptions = &$this->_default_error_options; 
  195. } else { 
  196. $setmode = &$GLOBALS['_PEAR_default_error_mode']; 
  197. $setoptions = &$GLOBALS['_PEAR_default_error_options']; 
  198.  
  199. switch ($mode) { 
  200. case PEAR_ERROR_EXCEPTION: 
  201. case PEAR_ERROR_RETURN: 
  202. case PEAR_ERROR_PRINT: 
  203. case PEAR_ERROR_TRIGGER: 
  204. case PEAR_ERROR_DIE: 
  205. case null: 
  206. $setmode = $mode; 
  207. $setoptions = $options; 
  208. break; 
  209.  
  210. case PEAR_ERROR_CALLBACK: 
  211. $setmode = $mode; 
  212. // class/object method callback 
  213. if (is_callable($options)) { 
  214. $setoptions = $options; 
  215. } else { 
  216. trigger_error("invalid error callback", E_USER_WARNING); 
  217. break; 
  218.  
  219. default: 
  220. trigger_error("invalid error mode", E_USER_WARNING); 
  221. break; 
  222.  
  223. // }}} 
  224. // {{{ expectError() 
  225.  
  226. /** 
  227. * This method is used to tell which errors you expect to get. 
  228. * Expected errors are always returned with error mode 
  229. * PEAR_ERROR_RETURN. Expected error codes are stored in a stack,  
  230. * and this method pushes a new element onto it. The list of 
  231. * expected errors are in effect until they are popped off the 
  232. * stack with the popExpect() method. 
  233. * Note that this method can not be called statically 
  234. * @param mixed $code a single error code or an array of error codes to expect 
  235. * @return int the new depth of the "expected errors" stack 
  236. * @access public 
  237. */ 
  238. function expectError($code = '*') 
  239. if (is_array($code)) { 
  240. array_push($this->_expected_errors, $code); 
  241. } else { 
  242. array_push($this->_expected_errors, array($code)); 
  243. return sizeof($this->_expected_errors); 
  244.  
  245. // }}} 
  246. // {{{ popExpect() 
  247.  
  248. /** 
  249. * This method pops one element off the expected error codes 
  250. * stack. 
  251. * @return array the list of error codes that were popped 
  252. */ 
  253. function popExpect() 
  254. return array_pop($this->_expected_errors); 
  255.  
  256. // }}} 
  257. // {{{ _checkDelExpect() 
  258.  
  259. /** 
  260. * This method checks unsets an error code if available 
  261. * @param mixed error code 
  262. * @return bool true if the error code was unset, false otherwise 
  263. * @access private 
  264. * @since PHP 4.3.0 
  265. */ 
  266. function _checkDelExpect($error_code) 
  267. $deleted = false; 
  268.  
  269. foreach ($this->_expected_errors AS $key => $error_array) { 
  270. if (in_array($error_code, $error_array)) { 
  271. unset($this->_expected_errors[$key][array_search($error_code, $error_array)]); 
  272. $deleted = true; 
  273.  
  274. // clean up empty arrays 
  275. if (0 == count($this->_expected_errors[$key])) { 
  276. unset($this->_expected_errors[$key]); 
  277. return $deleted; 
  278.  
  279. // }}} 
  280. // {{{ delExpect() 
  281.  
  282. /** 
  283. * This method deletes all occurences of the specified element from 
  284. * the expected error codes stack. 
  285. * @param mixed $error_code error code that should be deleted 
  286. * @return mixed list of error codes that were deleted or error 
  287. * @access public 
  288. * @since PHP 4.3.0 
  289. */ 
  290. function delExpect($error_code) 
  291. $deleted = false; 
  292.  
  293. if ((is_array($error_code) && (0 != count($error_code)))) { 
  294. // $error_code is a non-empty array here; 
  295. // we walk through it trying to unset all 
  296. // values 
  297. foreach($error_code as $key => $error) { 
  298. if ($this->_checkDelExpect($error)) { 
  299. $deleted = true; 
  300. } else { 
  301. $deleted = false; 
  302. return $deleted ? true : PEAR::raiseError("The expected error you submitted does not exist"); // IMPROVE ME 
  303. } elseif (!empty($error_code)) { 
  304. // $error_code comes alone, trying to unset it 
  305. if ($this->_checkDelExpect($error_code)) { 
  306. return true; 
  307. } else { 
  308. return PEAR::raiseError("The expected error you submitted does not exist"); // IMPROVE ME 
  309. } else { 
  310. // $error_code is empty 
  311. return PEAR::raiseError("The expected error you submitted is empty"); // IMPROVE ME 
  312.  
  313. // }}} 
  314. // {{{ raiseError() 
  315.  
  316. /** 
  317. * This method is a wrapper that returns an instance of the 
  318. * configured error class with this object's default error 
  319. * handling applied. If the $mode and $options parameters are not 
  320. * specified, the object's defaults are used. 
  321. * @param mixed $message a text error message or a PEAR error object 
  322. * @param int $code a numeric error code (it is up to your class 
  323. * to define these if you want to use codes) 
  324. * @param int $mode One of PEAR_ERROR_RETURN, PEAR_ERROR_PRINT,  
  325. * PEAR_ERROR_TRIGGER, PEAR_ERROR_DIE,  
  326. * PEAR_ERROR_CALLBACK, PEAR_ERROR_EXCEPTION. 
  327. * @param mixed $options If $mode is PEAR_ERROR_TRIGGER, this parameter 
  328. * specifies the PHP-internal error level (one of 
  329. * E_USER_NOTICE, E_USER_WARNING or E_USER_ERROR). 
  330. * If $mode is PEAR_ERROR_CALLBACK, this 
  331. * parameter specifies the callback function or 
  332. * method. In other error modes this parameter 
  333. * is ignored. 
  334. * @param string $userinfo If you need to pass along for example debug 
  335. * information, this parameter is meant for that. 
  336. * @param string $error_class The returned error object will be 
  337. * instantiated from this class, if specified. 
  338. * @param bool $skipmsg If true, raiseError will only pass error codes,  
  339. * the error message parameter will be dropped. 
  340. * @access public 
  341. * @return object a PEAR error object 
  342. * @see PEAR::setErrorHandling 
  343. * @since PHP 4.0.5 
  344. */ 
  345. function &raiseError($message = null,  
  346. $code = null,  
  347. $mode = null,  
  348. $options = null,  
  349. $userinfo = null,  
  350. $error_class = null,  
  351. $skipmsg = false) 
  352. // The error is yet a PEAR error object 
  353. if (is_object($message)) { 
  354. $code = $message->getCode(); 
  355. $userinfo = $message->getUserInfo(); 
  356. $error_class = $message->getType(); 
  357. $message->error_message_prefix = ''; 
  358. $message = $message->getMessage(); 
  359.  
  360. if (isset($this) && isset($this->_expected_errors) && sizeof($this->_expected_errors) > 0 && sizeof($exp = end($this->_expected_errors))) { 
  361. if ($exp[0] == "*" || 
  362. (is_int(reset($exp)) && in_array($code, $exp)) || 
  363. (is_string(reset($exp)) && in_array($message, $exp))) { 
  364. $mode = PEAR_ERROR_RETURN; 
  365. // No mode given, try global ones 
  366. if ($mode === null) { 
  367. // Class error handler 
  368. if (isset($this) && isset($this->_default_error_mode)) { 
  369. $mode = $this->_default_error_mode; 
  370. $options = $this->_default_error_options; 
  371. // Global error handler 
  372. } elseif (isset($GLOBALS['_PEAR_default_error_mode'])) { 
  373. $mode = $GLOBALS['_PEAR_default_error_mode']; 
  374. $options = $GLOBALS['_PEAR_default_error_options']; 
  375.  
  376. if ($error_class !== null) { 
  377. $ec = $error_class; 
  378. } elseif (isset($this) && isset($this->_error_class)) { 
  379. $ec = $this->_error_class; 
  380. } else { 
  381. $ec = 'PEAR_Error'; 
  382. if ($skipmsg) { 
  383. $a = new $ec($code, $mode, $options, $userinfo); 
  384. return $a; 
  385. } else { 
  386. $a = new $ec($message, $code, $mode, $options, $userinfo); 
  387. return $a; 
  388.  
  389. // }}} 
  390. // {{{ throwError() 
  391.  
  392. /** 
  393. * Simpler form of raiseError with fewer options. In most cases 
  394. * message, code and userinfo are enough. 
  395. * @param string $message 
  396. */ 
  397. function &throwError($message = null,  
  398. $code = null,  
  399. $userinfo = null) 
  400. if (isset($this) && is_a($this, 'PEAR')) { 
  401. $a = &$this->raiseError($message, $code, null, null, $userinfo); 
  402. return $a; 
  403. } else { 
  404. $a = &PEAR::raiseError($message, $code, null, null, $userinfo); 
  405. return $a; 
  406.  
  407. // }}} 
  408. function staticPushErrorHandling($mode, $options = null) 
  409. $stack = &$GLOBALS['_PEAR_error_handler_stack']; 
  410. $def_mode = &$GLOBALS['_PEAR_default_error_mode']; 
  411. $def_options = &$GLOBALS['_PEAR_default_error_options']; 
  412. $stack[] = array($def_mode, $def_options); 
  413. switch ($mode) { 
  414. case PEAR_ERROR_EXCEPTION: 
  415. case PEAR_ERROR_RETURN: 
  416. case PEAR_ERROR_PRINT: 
  417. case PEAR_ERROR_TRIGGER: 
  418. case PEAR_ERROR_DIE: 
  419. case null: 
  420. $def_mode = $mode; 
  421. $def_options = $options; 
  422. break; 
  423.  
  424. case PEAR_ERROR_CALLBACK: 
  425. $def_mode = $mode; 
  426. // class/object method callback 
  427. if (is_callable($options)) { 
  428. $def_options = $options; 
  429. } else { 
  430. trigger_error("invalid error callback", E_USER_WARNING); 
  431. break; 
  432.  
  433. default: 
  434. trigger_error("invalid error mode", E_USER_WARNING); 
  435. break; 
  436. $stack[] = array($mode, $options); 
  437. return true; 
  438.  
  439. function staticPopErrorHandling() 
  440. $stack = &$GLOBALS['_PEAR_error_handler_stack']; 
  441. $setmode = &$GLOBALS['_PEAR_default_error_mode']; 
  442. $setoptions = &$GLOBALS['_PEAR_default_error_options']; 
  443. array_pop($stack); 
  444. list($mode, $options) = $stack[sizeof($stack) - 1]; 
  445. array_pop($stack); 
  446. switch ($mode) { 
  447. case PEAR_ERROR_EXCEPTION: 
  448. case PEAR_ERROR_RETURN: 
  449. case PEAR_ERROR_PRINT: 
  450. case PEAR_ERROR_TRIGGER: 
  451. case PEAR_ERROR_DIE: 
  452. case null: 
  453. $setmode = $mode; 
  454. $setoptions = $options; 
  455. break; 
  456.  
  457. case PEAR_ERROR_CALLBACK: 
  458. $setmode = $mode; 
  459. // class/object method callback 
  460. if (is_callable($options)) { 
  461. $setoptions = $options; 
  462. } else { 
  463. trigger_error("invalid error callback", E_USER_WARNING); 
  464. break; 
  465.  
  466. default: 
  467. trigger_error("invalid error mode", E_USER_WARNING); 
  468. break; 
  469. return true; 
  470.  
  471. // {{{ pushErrorHandling() 
  472.  
  473. /** 
  474. * Push a new error handler on top of the error handler options stack. With this 
  475. * you can easily override the actual error handler for some code and restore 
  476. * it later with popErrorHandling. 
  477. * @param mixed $mode (same as setErrorHandling) 
  478. * @param mixed $options (same as setErrorHandling) 
  479. * @return bool Always true 
  480. * @see PEAR::setErrorHandling 
  481. */ 
  482. function pushErrorHandling($mode, $options = null) 
  483. $stack = &$GLOBALS['_PEAR_error_handler_stack']; 
  484. if (isset($this) && is_a($this, 'PEAR')) { 
  485. $def_mode = &$this->_default_error_mode; 
  486. $def_options = &$this->_default_error_options; 
  487. } else { 
  488. $def_mode = &$GLOBALS['_PEAR_default_error_mode']; 
  489. $def_options = &$GLOBALS['_PEAR_default_error_options']; 
  490. $stack[] = array($def_mode, $def_options); 
  491.  
  492. if (isset($this) && is_a($this, 'PEAR')) { 
  493. $this->setErrorHandling($mode, $options); 
  494. } else { 
  495. PEAR::setErrorHandling($mode, $options); 
  496. $stack[] = array($mode, $options); 
  497. return true; 
  498.  
  499. // }}} 
  500. // {{{ popErrorHandling() 
  501.  
  502. /** 
  503. * Pop the last error handler used 
  504. * @return bool Always true 
  505. * @see PEAR::pushErrorHandling 
  506. */ 
  507. function popErrorHandling() 
  508. $stack = &$GLOBALS['_PEAR_error_handler_stack']; 
  509. array_pop($stack); 
  510. list($mode, $options) = $stack[sizeof($stack) - 1]; 
  511. array_pop($stack); 
  512. if (isset($this) && is_a($this, 'PEAR')) { 
  513. $this->setErrorHandling($mode, $options); 
  514. } else { 
  515. PEAR::setErrorHandling($mode, $options); 
  516. return true; 
  517.  
  518. // }}} 
  519. // {{{ loadExtension() 
  520.  
  521. /** 
  522. * OS independant PHP extension load. Remember to take care 
  523. * on the correct extension name for case sensitive OSes. 
  524. * @param string $ext The extension name 
  525. * @return bool Success or not on the dl() call 
  526. */ 
  527. function loadExtension($ext) 
  528. if (!extension_loaded($ext)) { 
  529. // if either returns true dl() will produce a FATAL error, stop that 
  530. if ((ini_get('enable_dl') != 1) || (ini_get('safe_mode') == 1)) { 
  531. return false; 
  532. if (OS_WINDOWS) { 
  533. $suffix = '.dll'; 
  534. } elseif (PHP_OS == 'HP-UX') { 
  535. $suffix = '.sl'; 
  536. } elseif (PHP_OS == 'AIX') { 
  537. $suffix = '.a'; 
  538. } elseif (PHP_OS == 'OSX') { 
  539. $suffix = '.bundle'; 
  540. } else { 
  541. $suffix = '.so'; 
  542. return @dl('php_'.$ext.$suffix) || @dl($ext.$suffix); 
  543. return true; 
  544.  
  545. // }}}