Introducing PHP 5's Standard Library * - Iterators in PHP5 * - Advanced OOP with SPL in PHP 5 * - The Standard PHP Library, Part 1 * - The Standard PHP Library, Part 2 * - SPL on PHP Wiki * - Die Standard PHP Library (SPL) [german] * * Talks on SPL: * - SPL for the masses [pps], [pdf] * - Debug session 1 [pps], [pdf] * - Debug session 2 [pps], [pdf] * - From engine overloading to SPL [pps], [pdf] * * You can download this documentation as a chm file * here. * * (c) Marcus Boerger, 2003 - 2005 */ /** @defgroup ZendEngine Zend engine classes * * The classes and interfaces in this group are contained in the c-code of * PHP's Zend engine. */ /** @defgroup SPL Internal classes * * The classes and interfaces in this group are contained in the c-code of * ext/SPL. */ /** @defgroup Examples Example classes * * The classes and interfaces in this group are contained as PHP code in the * examples subdirectory of ext/SPL. Sooner or later they will be moved to * c-code. */ /** @ingroup ZendEngine * @brief Basic Exception class. * @since PHP 5.0 */ class Exception { /** The exception message */ protected $message; /** The string represenations as generated during construction */ private $string; /** The code passed to the constructor */ protected $code; /** The file name where the exception was instantiated */ protected $file; /** The line number where the exception was instantiated */ protected $line; /** The stack trace */ private $trace; /** Prevent clone */ final private function __clone() {} /** Construct an exception * * @param $message Some text describing the exception * @param $code Some code describing the exception */ function __construct($message = NULL, $code = 0) { if (func_num_args()) { $this->message = $message; } $this->code = $code; $this->file = __FILE__; // of throw clause $this->line = __LINE__; // of throw clause $this->trace = debug_backtrace(); $this->string = StringFormat($this); } /** @return the message passed to the constructor */ final public function getMessage() { return $this->message; } /** @return the code passed to the constructor */ final public function getCode() { return $this->code; } /** @return the name of the file where the exception was thrown */ final public function getFile() { return $this->file; } /** @return the line number where the exception was thrown */ final public function getLine() { return $this->line; } /** @return the stack trace as array */ final public function getTrace() { return $this->trace; } /** @return the stack trace as string */ final public function getTraceAsString() { } /** @return string represenation of exception */ public function __toString() { return $this->string; } } /** @ingroup SPL * @brief Exception that represents error in the program logic. * @since PHP 5.1 * * This kind of exceptions should directly leed to a fix in your code. */ class LogicException extends Exception { } /** @ingroup SPL * @brief Exception thrown when a function call was illegal. * @since PHP 5.1 */ class BadFunctionCallException extends LogicException { } /** @ingroup SPL * @brief Exception thrown when a method call was illegal. * @since PHP 5.1 */ class BadMethodCallException extends BadFunctionCallException { } /** @ingroup SPL * @brief Exception that denotes a value not in the valid domain was used. * @since PHP 5.1 * * This kind of exception should be used to inform about domain erors in * mathematical sense. * * @see RangeException */ class DomainException extends LogicException { } /** @ingroup SPL * @brief Exception that denotes invalid arguments were passed. * @since PHP 5.1 * * @see UnexpectedValueException */ class InvalidArgumentException extends LogicException { } /** @ingroup SPL * @brief Exception thrown when a parameter exceeds the allowed length. * @since PHP 5.1 * * This can be used for strings length, array size, file size, number of * elements read from an Iterator and so on. */ class LengthException extends LogicException { } /** @ingroup SPL * @brief Exception thrown when an illegal index was requested. * @since PHP 5.1 * * This represents errors that should be detected at compile time. * * @see OutOfBoundsException */ class OutOfRangeException extends LogicException { } /** @ingroup SPL * @brief Exception thrown for errors that are only detectable at runtime. * @since PHP 5.1 */ class RuntimeException extends Exception { } /** @ingroup SPL * @brief Exception thrown when an illegal index was requested. * @since PHP 5.1 * * This represents errors that cannot be detected at compile time. * * @see OutOfRangeException */ class OutOfBoundsException extends RuntimeException { } /** @ingroup SPL * @brief Exception thrown to indicate arithmetic/buffer overflow. * @since PHP 5.1 */ class OverflowException extends RuntimeException { } /** @ingroup SPL * @brief Exception thrown to indicate range errors during program execution. * @since PHP 5.1 * * Normally this means there was an arithmetic error other than under/overflow. * This is the runtime version of DomainException. * * @see DomainException */ class RangeException extends RuntimeException { } /** @ingroup SPL * @brief Exception thrown to indicate arithmetic/buffer underflow. * @since PHP 5.1 */ class UnderflowException extends RuntimeException { } /** @ingroup SPL * @brief Exception thrown to indicate an unexpected value. * @since PHP 5.1 * * Typically this happens when a function calls another function and espects * the return value to be of a certain type or value not including arithmetic * or buffer related errors. * * @see InvalidArgumentException */ class UnexpectedValueException extends RuntimeException { } /** @ingroup ZendEngine * @brief Interface to override array access of objects. * @since PHP 5.0 */ interface ArrayAccess { /** @param $offset to modify * @param $value new value */ function offsetSet($offset, $value); /** @param $offset to retrieve * @return value at given offset */ function offsetGet($offset); /** @param $offset to delete */ function offsetUnset($offset); /** @param $offset to check * @return whether the offset exists. */ function offsetExists($offset); } /** @ingroup ZendEngine * @brief Interface to detect a class is traversable using foreach. * @since PHP 5.0 * * Abstract base interface that cannot be implemented alone. Instead it * must be implemented by either IteratorAggregate or Iterator. * * @note Internal classes that implement this interface can be used in a * foreach construct and do not need to implement IteratorAggregate or * Iterator. * * @note This is an engine internal interface which cannot be implemented * in PHP scripts. Either IteratorAggregate or Iterator must be used * instead. */ interface Traversable { } /** @ingroup ZendEngine * @brief Interface to create an external Iterator. * @since PHP 5.0 * * @note This is an engine internal interface. */ interface IteratorAggregate extends Traversable { /** @return an Iterator for the implementing object. */ function getIterator(); } /** @ingroup ZendEngine * @brief Basic iterator * @since PHP 5.0 * * Interface for external iterators or objects that can be iterated * themselves internally. * * @note This is an engine internal interface. */ interface Iterator extends Traversable { /** Rewind the Iterator to the first element. */ function rewind(); /** Return the current element. */ function current(); /** Return the key of the current element. */ function key(); /** Move forward to next element. */ function next(); /** Check if there is a current element after calls to rewind() or next(). */ function valid(); } /** @ingroup SPL * @brief This Interface allows to hook into the global count() function. * @since PHP 5.1 */ interface Countable { /** @return the number the global function count() should show */ function count(); } /** @ingroup ZendEngine * @brief Interface for customized serializing * @since 5.1 * * Classes that implement this interface no longer support __sleep() and * __wakeup(). The method serialized is called whenever an instance needs to * be serialized. This does not invoke __destruct() or has any other side * effect unless programmed inside the method. When the data is unserialized * the class is known and the appropriate unserialize() method is called as a * constructor instead of calling __construct(). If you need to execute the * standard constructor you may do so in the method. */ interface Serializeable { /** * @return string representation of the instance */ function serialize(); /** * @note This is a constructor * * @param $serialized data read from stream to construct the instance */ function unserialize($serialized); } /** @ingroup SPL * @brief An Array wrapper * @since PHP 5.0 * @version 1.1 * * This array wrapper allows to recursively iterate over Arrays and public * Object properties. * * @see ArrayIterator */ class ArrayObject implements IteratorAggregate, ArrayAccess, Countable { /** Properties of the object have their normal functionality * when accessed as list (var_dump, foreach, etc.) */ const STD_PROP_LIST = 0x00000001; /** Array indices can be accessed as properties in read/write */ const ARRAY_AS_PROPS = 0x00000002; /** Construct a new array iterator from anything that has a hash table. * That is any Array or Object. * * @param $array the array to use. * @param $flags see setFlags(). */ function __construct($array, $flags = 0); /** Set behavior flags. * * @param $flags bitmask as follows: * 0 set: properties of the object have their normal functionality * when accessed as list (var_dump, foreach, etc.) * 1 set: array indices can be accessed as properties in read/write */ function setFlags($flags); /** * @ return current flags */ function getFlags(); /** * @param $array new array or object */ function exchangeArray($array); /** @return the iterator which is an ArrayIterator object connected to * this object. */ function getIterator(); /** @param $index offset to inspect * @return whetehr offset $index esists */ function offsetExists($index); /** @param $index offset to return value for * @return value at offset $index */ function offsetGet($index); /** @param $index index to set * @param $newval new value to store at offset $index */ function offsetSet($index, $newval); /** @param $index offset to unset */ function offsetUnset($index); /** @param $value is appended as last element * @warning this method cannot be called when the ArrayObject refers to * an object. */ function append($value); /** @return a \b copy of the array * @note when the ArrayObject refers to an object then this method * returns an array of the public properties. */ function getArrayCopy(); /** @return the number of elements in the array or the number of public * properties in the object. */ function count(); } /** @ingroup SPL * @brief An Array iterator * @since PHP 5.0 * @version 1.1 * * This iterator allows to unset and modify values and keys while iterating * over Arrays and Objects. * * When you want to iterate over the same array multiple times you need to * instanciate ArrayObject and let it create ArrayIterator instances that * refer to it either by using foreach or by calling its getIterator() * method manually. */ class ArrayIterator implements SeekableIterator, ArrayAccess, Countable { /** Properties of the object have their normal functionality * when accessed as list (var_dump, foreach, etc.) */ const STD_PROP_LIST = 0x00000001; /** Array indices can be accessed as properties in read/write */ const ARRAY_AS_PROPS = 0x00000002; /** Construct a new array iterator from anything that has a hash table. * That is any Array or Object. * * @param $array the array to use. * @param $flags see setFlags(). */ function __construct($array, $flags = 0); /** Set behavior flags. * * @param $flags bitmask as follows: * 0 set: properties of the object have their normal functionality * when accessed as list (var_dump, foreach, etc.) * 1 set: array indices can be accessed as properties in read/write */ function setFlags($flags); /** * @ return current flags */ function getFlags(); /** @param $index offset to inspect * @return whetehr offset $index esists */ function offsetExists($index); /** @param $index offset to return value for * @return value at offset $index */ function offsetGet($index); /** @param $index index to set * @param $newval new value to store at offset $index */ function offsetSet($index, $newval); /** @param $index offset to unset */ function offsetUnset($index); /** @param $value is appended as last element * @warning this method cannot be called when the ArrayIterator refers to * an object. */ function append($value); /** @return a \b copy of the array * @note when the ArrayIterator refers to an object then this method * returns an array of the public properties. */ function getArrayCopy(); /** @param $position offset to seek to * @throw OutOfBoundsException if $position is invalid */ function seek($position); /** @return the number of elements in the array or the number of public * properties in the object. */ function count(); } /** @ingroup SPL * @brief Directory iterator * @since PHP 5.0 */ class DirectoryIterator implements Iterator { /** Construct a directory iterator from a path-string. * * @param $path directory to iterate. */ function __construct($path); /** @return The opened path. */ function getPath(); /** @return The current file name. */ function getFilename(); /** @return The current entries path and file name. */ function getPathname(); /** @return The current entry's permissions. */ function getPerms(); /** @return The current entry's inode. */ function getInode(); /** @return The current entry's size in bytes . */ function getSize(); /** @return The current entry's owner name. */ function getOwner(); /** @return The current entry's group name. */ function getGroup(); /** @return The current entry's last access time. */ function getATime(); /** @return The current entry's last modification time. */ function getMTime(); /** @return The current entry's last change time. */ function getCTime(); /** @return The current entry's size in bytes . */ function getType(); /** @return Whether the current entry is writeable. */ function isWritable(); /** @return Whether the current entry is readable. */ function isReadable(); /** @return Whether the current entry is executable. */ function isExecutable(); /** @return Whether the current entry is . */ function isFile(); /** @return Whether the current entry is a directory. */ function isDir(); /** @return Whether the current entry is either '.' or '..'. */ function isDot(); /** @return whether the current entry is a link. */ function isLink(); /** @return getFilename() */ function __toString(); /** Open the current file as a SplFileObject instance * * @param mode open mode * @param use_include_path whether to search include paths (don't use) * @param context resource context to pased to open function * @throw RuntimeException if file cannot be opened (e.g. insufficient * access rights). * @return The opened file as a SplFileObject instance * * @see SplFileObject * @see file() */ function DirectoryIterator::openFile($mode = 'r', $use_include_path = false, $context = NULL); } /** @ingroup SPL * @brief recursive directory iterator * @since PHP 5.0 */ class RecursiveDirectoryIterator extends DirectoryIterator implements RecursiveIterator { /** @return whether the current is a directory (not '.' or '..'). */ function hasChildren(); /** @return a RecursiveDirectoryIterator for the current entry. */ function getChildren(); } /** @ingroup SPL * @brief recursive SimpleXML_Element iterator * @since PHP 5.0 * * The SimpleXMLIterator implements the RecursiveIterator interface. This * allows iteration over all elements using foreach or an appropriate while * construct, just like SimpleXMLElement does. When using the foreach construct, * you will also iterate over the subelements. For every element which * has subelements, hasChildren() returns true. This will trigger a call to * getChildren() which returns the iterator for that sub element. */ class SimpleXMLIterator extends SimpleXMLElement implements RecursiveIterator { /** @return whether the current node has sub nodes. */ function hasChildren(); /** @return a SimpleXMLIterator for the current node. */ function getChildren(); } /** @ingroup SPL * @brief observer of the observer pattern * @since PHP 5.1 * * For a detailed explanation see Observer pattern in * * Gamma, Helm, Johnson, Vlissides
* Design Patterns *
*/ interface Observer { /** Called from the subject (i.e. when it's value has changed). * @param $subject the callee */ function update(Subject $subject); } /** @ingroup SPL * @brief ubject to the observer pattern * @since PHP 5.1 * @see Observer */ interface Subject { /** @param $observer new observer to attach */ function attach(Observer $observer); /** @param $observer existing observer to detach * @note a non attached observer shouldn't result in a warning or similar */ function detach(Observer $observer); /** Notify all observers */ function notify(); } ?>