diff --git a/appendices/migration52.xml b/appendices/migration52.xml new file mode 100644 index 0000000000..93934d91cb --- /dev/null +++ b/appendices/migration52.xml @@ -0,0 +1,1838 @@ + + + + Migrating from PHP 5.1.x to PHP 5.2.x + +
+ What has changed in PHP 5.2.x + + Most improvements in PHP 5.2.x have no impact on existing code. There are + a few incompatibilities + and new error messages + that should be considered, and code should be tested before switching PHP + versions in production environments. + + + If the system is being upgraded from PHP 5.0.x, the text titled + Upgrade Notes for PHP 5.1.x + should also be read. + + + Similarly, if the system is being upgraded from PHP 4, the manual section + titled Migrating from PHP 4 to PHP 5 + should be read as well. + +
+ +
+ Backward Incompatible Changes + + Although most existing PHP 5 code should work without changes, you should + pay attention to the following backward incompatible changes: + + + + + getrusage returns &null; when passed + incompatible arguments as of PHP 5.2.1. + + + + + ZipArchive::setCommentName + returns &true; on success as of PHP 5.2.1. + + + + + ZipArchive::setCommentIndex + returns &true; on success as of PHP 5.2.1. + + + + + SplFileObject::getFilename returns + the filename, not relative/path/to/file, as of PHP 5.2.1. + + + + + Changed priority of PHPRC environment variable on Win32 + + + The PHPRC environment variable now takes priority over the path stored + in the Windows registry. + + + + + CLI SAPI no longer checks cwd for &php.ini; or the php-cli.ini file + + + In PHP 5.1.x an undocumented feature was added that made the CLI binary check + the current working directory for a PHP configuration file, potentially + leading to unpredictable behavior if an unexpected configuration file were + read. This functionality was removed in 5.2.0, and PHP will no longer search + CWD for the presence of &php.ini; or php-cli.ini files. + See also the command line section + of the manual. + + + + + Added a warning when performing modulus 0 operations + + + In earlier versions of PHP, performing integer % 0 did not emit any + warning messages, instead returning an unexpected return value of &false;. + As of PHP 5.2.0, this operation will emit an E_WARNING, + as is the case in all other instances where division by zero is performed. + + + + +]]> + + + + + + Changed __toString to be called wherever + applicable. + + + The magic method __toString will now be called + in a string context, that is, anywhere an object is used as a + string. + + + The fallback of returning a string that contains the + object identifier was dropped in PHP 5.2.0. It became + problematic because an object identifier cannot be considered + unique. This change will mean that your application is flawed if you + have relied on the object identifier as a return value. An attempt + to use that value as a string will now result in a catchable fatal + error. + + + + +]]> + + + + Even with __toString, objects cannot be used as + array indices or keys. We may add built-in hash support for this at + a later date, but as of PHP 5.2.x you will need to either provide your + own hashing or use the new SPL function + spl_object_hash. + + + Exceptions can not be thrown from from + __toString methods. + + + + +]]> + + + + + + Dropped abstract static class functions. + + + Due to an oversight, PHP 5.0.x and 5.1.x allowed abstract static + functions in classes. As of PHP 5.2.x, only interfaces can have them. + + + + +]]> + + + + + + Added RFC2397 (data: stream) support. + + + The introduction of the 'data' URL scheme has the potential to lead to a + change of behavior under Windows. If you are working with a NTFS + file system and making use of meta streams in your application, and if you + just happen to be using a file with the name 'data:' that is accessed without + any path information - it won't work any more. The fix is to use the 'file:' + protocol when accessing it. + + + See also RFC 2397 + + + + +]]> + + + + +
+ +
+ New Error Messages + + Below are the new error messages that have not been discussed + elsewhere in this document. + + + + In PHP Core + + +]]> + + + + + + <link linkend="language.oop5">Object Oriented Code</link> in PHP Core + +bar; + } +} + +$foo = new foo; +$bar =& $foo->prop; +/* Notice: Indirect modification of overloaded property + foo::$prop has no effect in filename on line n */ + + +class foo implements iterator { + public function current() { + } + public function next() { + } + public function key() { + } + public function valid() { + } + public function rewind() { + } +} + +$foo = new foo(); +foreach($foo as &$ref) {} +/* Fatal error: An iterator cannot be used with foreach + by reference in filename on line n */ + + +class foo { + private function __construct() { + } +} +class bar extends foo { + public function __construct() { + parent::__construct(); + /* Fatal error: Cannot call private + foo::__construct() in filename on line n */ + } +} +new bar; + + +stream_filter_register("", "class"); +/* Warning: stream_filter_register(): Filter name + cannot be empty in filename on line n */ + + +stream_filter_register("filter", ""); +/* Warning: stream_filter_register(): Class name + cannot be empty in filename on line n */ +]]> + + + + + + In the <link linkend="ref.bzip2">bzip2</link> Extension + + +]]> + + + + + + In the <link linkend="ref.datetime">datetime</link> Extension + + +]]> + + + + + + In the <link linkend="ref.dbase">dBase</link> Extension + + +]]> + + + + + + In the <link linkend="ref.mcrypt">mcrypt</link> Extension + + +]]> + + + + + + In the <link linkend="ref.oci8">oci8</link> Extension + + +]]> + + + + + + In the <link linkend="ref.spl">SPL</link> Extension + +fgetcsv("foo"); +/* Warning: SplFileObject::fgetcsv(): delimiter must + be a character in filename on line n */ + +$obj->fgetcsv(",", "foo"); +/* Warning: SplFileObject::fgetcsv(): enclosure must + be a character in filename on line n */ +?> +]]> + + + + + + In the <link linkend="ref.sem">Semaphore</link> (sysvmsg) extension + + +]]> + + + + + + A 5.2.1+ <link linkend="ref.zip">Zip</link> Example + +open('archive.zip'); +$obj->setCommentName('', 'comment'); +/* Notice: ZipArchive::setCommentName(): Empty string + as entry name in filename on line n */ + +/* As of PHP 5.2.1 */ +$obj->getCommentName(''); +/* Notice: ZipArchive::getCommentName(): Empty string + as entry name in filename on line n */ +?> +]]> + + + +
+ +
+ Changes in PHP <link linkend="ref.datetime">datetime</link> + support + + + Since PHP 5.1.0, there has been an extension named date + in the PHP core. This is the new implementation of PHP's datetime support. + Although it will attempt to guess your system's timezone setting, you + should set the timezone manually. You can do this in any of three ways: + + + + + in your &php.ini; using the + date.timezone INI directive + + + + + on your system using the TZ environmental variable + + + + + from your script using the convenience function + date_default_timezone_set + + + + + All supported timezones are listed + in the PHP Manual. + + + With the advent of PHP 5.2.x, there are object representations of the + date and timezone, named DateTime and DateTimeZone respectively. + The methods map to existing procedural date functions. + +
+ +
+ New Parameters + + Some functions were given new parameters in PHP 5.2.x: + + + PHP Core: + + + + base64_decode + - added strict + + + + + setcookie + - added httponly + + + + + setrawcookie + - added httponly + + + + + session_set_cookie_params + - added httponly + + + + + memory_get_usage + - added real_usage + + + + + curl: + + + + curl_multi_info_read + - added msgs_in_queue + + + + + imap: + + + + imap_open + - added n_retries + + + + + imap_reopen + - added n_retries + + + + + mbstring: + + + + mb_strrpos + - added offset + + + + The offset parameter was put in the position + the encoding parameter used to be. + Backward compatibility has been + provided by allowing encoding to be specified + as the third parameter. Using this backward compatibility mode is + not recommended because it will be removed in a future release of PHP. + + + + + + ming: + + + + swfmovie::streamMP3 + - added skip in PHP 5.2.1 + + + + + openssl: + + + + openssl_verify + - added signature_algo + + + + + pgsql: + + + + pg_escape_bytea + - added connection + + + + + pg_escape_string + - added connection + + + + + simplexml: + + + + SimpleXMLElement::__construct + - added is_prefix + + + + + SimpleXMLElement::attributes + - added is_prefix + + + + + SimpleXMLElement::children + - added is_prefix + + + + + simplexml_load_file + - added is_prefix + + + + + simplexml_load_string + - added is_prefix + + + + + spl: + + + + array iterator_to_array(Traversable it [, bool use_keys = true]) + - added use_keys in PHP 5.2.1 + + + + + xmlreader: + + + + XMLReader::open + - added encoding + and options + + + + + XMLReader::XML + - added encoding + and options + + + +
+ +
+ New Functions + + PHP 5.2.x introduced some new functions: + + + PHP Core: + + + + array_fill_keys + - Create an array using the elements of the first parameter as keys, + each initialized to val + + + + + error_get_last + - Get the last occurred error as associative array. Returns &null; + if there hasn't been an error yet + + + + + image_type_to_extension + - Get file extension for image-type returned by getimagesize, + exif_read_data, exif_thumbnail, exif_imagetype + + + + + memory_get_peak_usage + - Returns the peak allocated by PHP memory + + + + + timezone_abbreviations_list + - Returns associative array containing DST, offset and the timezone name + + + + + timezone_identifiers_list + - Returns numerically indexed array with all timezone identifiers + + + + + timezone_name_from_abbr + - Returns the timezone name from abbreviation + + + + + stream_socket_shutdown + - Causes all or part of a full-duplex connection on the socket + associated with stream to be shut down. As of PHP 5.2.1. + + + + + mbstring: + + + + mb_list_encodings_alias_names + - Returns an array of all supported entity encodings + + + + + mb_list_mime_names + - Returns an array or string of all supported mime names + + + + + mb_stripos + - Finds position of first occurrence of a string within another, + case insensitive + + + + + mb_stristr + - Finds first occurrence of a string within another, case insensitive + + + + + mb_strrchr + - Finds the last occurrence of a character in a string within another + + + + + mb_strrichr + - Finds the last occurrence of a character in a string within another, + case insensitive + + + + + mb_strripos + - Finds position of last occurrence of a string within another, + case insensitive + + + + + mb_strstr + - Finds first occurrence of a string within another + + + + + ming (As of PHP 5.2.1): + + + + void ming_setSWFCompression(int num) + - Sets output compression + + + + + void swfmovie::namedanchor(string name) + - Creates anchor + + + + + void swfmovie::protect([string pasword]) + - Protects + + + + + openssl: + + + + openssl_csr_get_public_key + - Extracts public key from a CERT and prepares it for use + + + + + openssl_csr_get_subject + - Returns the subject of a CERT + + + + + openssl_pkey_get_details + - Returns an array with the key details (bits, pkey, type) + + + + + spl: + + + + spl_object_hash + - Return hash id for given object + + + + + int iterator_apply(Traversable it, mixed function [, mixed params]) + - Calls a function for every element in an iterator + + + + + pcre: + + + + preg_last_error + - Returns the error code of the last regex execution + + + + + pgsql: + + + + pg_field_table + - Returns the name of the table field belongs to, or table's oid + if oid_only is true + + + + + posix: + + + + bool posix_initgroups(string name, int base_group_id) + - Calculate the group access list for the user specified in name + + + + + gmp: + + + + gmp_nextprime + - Finds next prime of a + + + + + xmlwriter: + + + + xmlwriter_full_end_element + - End current element - returns FALSE on error + + + + + xmlwriter_write_raw + - Write text - returns FALSE on error + + + + + xmlwriter_start_dtd_entity + - Create start DTD Entity - returns FALSE on error + + + + + xmlwriter_end_dtd_entity + - End current DTD Entity - returns FALSE on error + + + + + xmlwriter_write_dtd_entity + - Write full DTD Entity tag - returns FALSE on error + + + +
+ +
+ New Methods + + New methods were introduced in 5.2.0: + + + dom: + + + + DOMDocument::registerNodeClass + - Register extended class used to create base node type + + + + + DOMElement::setIDAttribute + - Declares the attribute specified by name to be of type ID + + + + + DOMElement::setIDAttributeNode + - Declares the attribute specified by node to be of type ID + + + + + DOMElement::setIDAttributeNS + - Declares the attribute specified by local name and namespace URI to be + of type ID + + + + + DOMNode::C14N([bool exclusive [, bool with_comments [, array xpath [, array ns_prefixes]]]]) + - Canonicalize nodes to a string + + + + + DOMNode::C14NFile(string uri [, bool exclusive [, bool with_comments [, array xpath [, array ns_prefixes]]]]) + - Canonicalize nodes to a file + + + + + DOMNode::getNodePath() + - Gets an xpath for a node + + + + + soap: + + + + SoapServer::setObject(object obj) + - Sets object which will handle SOAP requests + + + + + spl: + + + + int ArrayObject::asort(void) + - Sort the entries by values + + + + + int ArrayObject::ksort(void) + - Sort the entries by key + + + + + int ArrayObject::natcasesort(void) + - Sort the entries by key using case insensitive + "natural order" algorithm. + + + + + int ArrayObject::natsort(void) + - Sort the entries by values using "natural order" algorithm. + + + + + int ArrayObject::uasort(callback cmp_function) + - Sort the entries by values user defined function + + + + + int ArrayObject::uksort(callback cmp_function) + - Sort the entries by key using user defined function. + + + + + ArrayIterator AppendIterator::getArrayIterator() + - Get access to inner ArrayIterator + + + + + int AppendIterator::getIteratorIndex() + - Get index of iterator + + + + + bool CachingIterator::getCache() + - Return the cache + + + + + int CachingIterator::getFlags() + - Return the internal flags + + + + + bool CachingIterator::offsetExists(mixed index) + - Return whether the requested index exists + + + + + string CachingIterator::offsetGet(mixed index) + - Return the internal cache if used + + + + + void CachingIterator::offsetSet(mixed index, mixed newval) + - Set given index in cache + + + + + void CachingIterator::offsetUnset(mixed index) + - Unset given index in cache + + + + + void CachingIterator::setFlags() + - Set the internal flags + + + + + array("delimiter" =>, "enclosure" =>) SplFileObject::getCsvControl(void) + - Get the delimiter and enclosure character used in fgetcsv + + + + + void SplFileObject::setCsvControl([string delimiter = ',' [, string enclosure = '"']]) + - Set the delimiter and enclosure character used in fgetcsv + + + + + boolean XMLReader::setSchema(string filename) + - Use W3C XSD schema to validate the document as it is processed. Activation is only possible before the first Read() + + + + + zip: + + + + bool ZipArchive::addEmptyDir(string dirname) + - Creates an empty directory in the archive + + + +
+ +
+ Removed Extensions + + These extensions have been moved to PECL and are no longer + part of the PHP distribution. The PECL package version of + these extensions will be created according to user demand. + + + + + filePro + + + + + Hyperwave API + + + +
+ +
+ New Extensions + + The following are new extensions added (by default) as of PHP 5.2.0: + + + + + Filter + - validates and filters data, and is designed for use with insecure + data such as user input. This extension is enabled by default; the + default mode RAW does not impact input data in any way. + + + + + JSON + - implements the JavaScript Object Notation (JSON) + data interchange format. This extension is enabled by default. + + + + + Zip + - enables you to transparently read or write ZIP + compressed archives and the files inside them. + + + +
+ +
+ New Classes + + The following classes were introduced in PHP 5.2.0: + + + + + DateTime + + + + + DateTimeZone + + + + + + RegexIterator - extends FilterIterator; implements Iterator, + Traversable, OuterIterator + + + Constants: + + + + + RegexIterator::ALL_MATCHES + + + + + RegexIterator::GET_MATCH + + + + + RegexIterator::MATCH + + + + + RegexIterator::REPLACE + + + + + RegexIterator::SPLIT + + + + + RegexIterator::USE_KEY + + + + + Properties: + + + + + public replacement + + + + + Methods: + + + + + RegexIterator::__construct(Iterator it, string regex [, int mode [, int flags [, int preg_flags]]]) + - Create an RegexIterator from another iterator and a regular expression + + + + + bool RegexIterator::accept() + - Match (string)current() against regular expression + + + + + bool RegexIterator::getFlags() + - Returns current operation flags + + + + + bool RegexIterator::getMode() + - Returns current operation mode + + + + + bool RegexIterator::getPregFlags() + - Returns current PREG flags (if in use or &null;) + + + + + bool RegexIterator::setFlags(int new_flags) + - Set operation flags + + + + + bool RegexIterator::setMode(int new_mode) + - Set new operation mode + + + + + bool RegexIterator::setPregFlags(int new_flags) + - Set PREG flags + + + + + + + + RecursiveRegexIterator + + + Constants: + + + + + RecursiveRegexIterator::ALL_MATCHES + + + + + RecursiveRegexIterator::GET_MATCH + + + + + RecursiveRegexIterator::MATCH + + + + + RecursiveRegexIterator::REPLACE + + + + + RecursiveRegexIterator::SPLIT + + + + + RecursiveRegexIterator::USE_KEY + + + + + Methods: + + + + + RecursiveRegexIterator::__construct(RecursiveIterator it, string regex [, int mode [, int flags [, int preg_flags]]]) + - Create an RecursiveRegexIterator from another recursive iterator and + a regular expression + + + + + RecursiveRegexIterator RecursiveRegexIterator::getChildren() + - Return the inner iterator's children contained in a + RecursiveRegexIterator + + + + + bool RecursiveRegexIterator::hasChildren() + - Check whether the inner iterator's current element has children + + + + + +
+ +
+ New Global Constants + + PHP Core: + + + + M_EULER + + + + + M_LNPI + + + + + M_SQRT3 + + + + + M_SQRTPI + + + + + PATHINFO_FILENAME + + + + + PREG_BACKTRACK_LIMIT_ERROR + + + + + PREG_BAD_UTF8_ERROR + + + + + PREG_INTERNAL_ERROR + + + + + PREG_NO_ERROR + + + + + PREG_RECURSION_LIMIT_ERROR + + + + + UPLOAD_ERR_EXTENSION + + + + + STREAM_SHUT_RD + + + + + STREAM_SHUT_WR + + + + + STREAM_SHUT_RDWR + + + + + curl: + + + + CURLE_FILESIZE_EXCEEDED + + + + + CURLE_FTP_SSL_FAILED + + + + + CURLE_LDAP_INVALID_URL + + + + + CURLFTPAUTH_DEFAULT + + + + + CURLFTPAUTH_SSL + + + + + CURLFTPAUTH_TLS + + + + + CURLFTPSSL_ALL + + + + + CURLFTPSSL_CONTROL + + + + + CURLFTPSSL_NONE + + + + + CURLFTPSSL_TRY + + + + + CURLOPT_FTP_SSL + + + + + CURLOPT_FTPSSLAUTH + + + + + ming: + + + + SWFTEXTFIELD_USEFONT + + + + + SWFTEXTFIELD_AUTOSIZE + + + + + SWF_SOUND_NOT_COMPRESSED + + + + + SWF_SOUND_ADPCM_COMPRESSED + + + + + SWF_SOUND_MP3_COMPRESSED + + + + + SWF_SOUND_NOT_COMPRESSED_LE + + + + + SWF_SOUND_NELLY_COMPRESSED + + + + + SWF_SOUND_5KHZ + + + + + SWF_SOUND_11KHZ + + + + + SWF_SOUND_22KHZ + + + + + SWF_SOUND_44KHZ + + + + + SWF_SOUND_8BITS + + + + + SWF_SOUND_16BITS + + + + + SWF_SOUND_MONO + + + + + SWF_SOUND_STEREO + + + + + openssl: + + + + OPENSSL_VERSION_NUMBER + + + + + OPENSSL_VERSION_TEXT + + + + + snmp: + + + + SNMP_OID_OUTPUT_FULL + + + + + SNMP_OID_OUTPUT_NUMERIC + + + + + Semaphore: + + + + MSG_EAGAIN + + + + + MSG_ENOMSG + + + +
+ +
+ New Class Constants + + pdo: + + + + PDO::ATTR_DEFAULT_FETCH_MODE + + + + + PDO::FETCH_PROPS_LATE + + + + + spl: + + + + CachingIterator::FULL_CACHE + + + + + CachingIterator::TOSTRING_USE_INNER + + + + + SplFileObject::READ_AHEAD + + + + + SplFileObject::READ_CSV + + + + + SplFileObject::SKIP_EMPTY + + + +
+ +
+ New INI Configuration Directives + + New &php.ini; directives introduced in PHP 5.2.0: + + + + + allow_url_include + + + This useful option makes it possible to differentiate between + standard file operations on remote files, and the inclusion of + remote files. While the former is usually desirable, the latter can + be a security risk if used naively. Starting with PHP 5.2.0, you can + allow remote file operations while disallowing the inclusion of + remote files in local scripts. In fact, this is the default + configuration. + + + + + pcre.backtrack_limit + + + + + pcre.recursion_limit + + + + + session.cookie_httponly + + + +
+ +
+ Error Reporting + + Some of the existing E_ERROR conditions have been + converted to something that you can catch with a user-defined error + handler. If an E_RECOVERABLE_ERROR + is not handled, it will behave in the same way as + E_ERROR behaves in all versions of PHP. Errors of + this type are logged as Catchable fatal error. + + + This change means that the value of the E_ALL + error_reporting constant is + now 6143, where the previous value was 2047. Because PHP constants have + no meaning outside of PHP, in some cases the integer value is used + instead so these will need to be adjusted. So for example if you are + setting the error_reporting mode from either the + httpd.conf or the + .htaccess files, you will need to adjust the value + accordingly. The same applies if you use the numeric value rather than the + constant in your PHP scripts. + + + As a side-effect of a change made to prevent duplicate error messages when + track_errors is + On, it is now necessary to return &false; from your + error handler in order to populate + $php_errormsg. This + provides you fine-grain control over the levels of messages stored. + +
+ +
+ Other Enhancements + + + + Improved memory manager and increased default memory limit. + + + The new memory manager allocates less memory and works faster than the + previous incarnation. It allocates memory from the system in large blocks, + and then manages the heap by itself. The memory_limit value in &php.ini; is + checked, not for each emalloc() call (as before), but for actual blocks + requested from the system. This means that memory_limit is far more + accurate than it used to be, since the old memory manager didn't calculate + all the memory overhead used by the malloc library. + + + Thanks to this new-found accuracy memory usage may appear to have increased, + although actually it has not. To accommodate this apparent increase, the + default memory_limit setting was also increased - from 8 to 16 megabytes. + + + + + Added support for constructors in interfaces to force constructor signature + checks in implementations. + + + Starting with PHP 5.2.0, interfaces can have constructors. However, if you choose + to declare a constructor in an interface, each class implementing that interface + MUST include a constructor with a signature matching that of the base interface + constructor. By 'signature' we mean the parameter and return type definitions, + including any type hints and including whether the data is passed by reference + or by value. + + + +
+ + +