From f036018ad0ac68e856f3b16d74a55c7155a61c26 Mon Sep 17 00:00:00 2001 From: Hannes Magnusson Date: Wed, 23 May 2007 18:44:28 +0000 Subject: [PATCH] Docbookified README_UPGRADE_51.php git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@236188 c90b9560-bf6c-de11-be94-00142212c4b1 --- appendices/migration51.xml | 878 +++++++++++++++++++++++++++++++++++++ 1 file changed, 878 insertions(+) create mode 100644 appendices/migration51.xml diff --git a/appendices/migration51.xml b/appendices/migration51.xml new file mode 100644 index 0000000000..48768e5d70 --- /dev/null +++ b/appendices/migration51.xml @@ -0,0 +1,878 @@ + + + + Migrating from PHP 5.0.x to PHP 5.1.x + +
+ Key PHP 5.1.x features + + Some of the key features of PHP 5.1.x include: + + + + + A complete rewrite of date handling code, with improved timezone support. + + + + + Significant performance improvements compared to PHP 5.0.X. + + + + + PDO extension is now enabled by default. + + + + + Over 30 new functions in various extensions and built-in functionality. + + + + + Over 400 various bug fixes. + + + +
+ +
+ Changes in reference handling + + + + Overview + + + + + Code that worked under PHP + 4.3.x, but now fails + + + + + Code that worked under PHP + 4.3.x, but now throws an error + + + + + Code that failed under PHP + 4.3.x, but now works + + + + + Code that + should have worked under PHP 5.0.x + + + + + Warnings that came and + went + + + + +
+ Overview + + From the PHP script writer's point of view, the change most likely to + impact legacy code is in the way that references are handled in all PHP + versions post-dating the PHP 4.4.0 release. + + + Until and including PHP 4.3, it was possible to send, assign or return + variables by reference that should really be returned by value, such as + a constant, a temporary value (e.g. the result of an expression), or the + result of a function that had itself been returned by value, as here: + + + + +]]> + + + + Although this code would usually work as expected under PHP 4.3, in the + general case the result is undefined. The Zend Engine could not act + correctly on these values as references. This bug could and did lead to + various hard-to-reproduce memory corruption problems, particularly + where the code base was large. + + + In PHP 4.4.0, PHP 5.0.4 and all subsequent PHP releases, the Engine was + fixed to 'know' when the reference operation is being used on a value + that should not be referenced. The actual value is now used in such + cases, and a warning is emitted. The warning takes the form of an + E_NOTICE in PHP 4.4.0 and up, and E_STRICT in PHP 5.0.4 and up. + + + Code that could potentially produce memory corruption can no longer do + so. However, some legacy code might work differently as a result. + +
+ +
+ Code that worked under PHP 4.3, but now fails + + + +<]]> + + + Running the above script under any version of PHP that pre-dates the + reference fix would produce this output: + + + + &string(1) "a" + [1]=> + &string(1) "b" + [2]=> + &string(1) "c" +} +]]> + + + Following the reference fix, the same code would result in: + + + + &string(1) "c" + [1]=> + &string(1) "c" + [2]=> + &string(1) "c" +} +]]> + + + + This is because, following the changes, func() assigns by value. The value + of $y is re-assigned, and reference-binding is preserved from $z. Prior to + the fix, the value was assigned by reference, leading $y to be re-bound on + each assignment. The attempt to bind to a temporary value by reference was + the cause of the memory corruption. + + + Such code can be made to work identically in both the pre-fix and the + post-fix PHP versions. The signature of func() can be altered to return by + reference, or the reference assignment can be removed from the result of + func(). + + + + +]]> + + + + In PHP 4.3 $x would be 'original value', whereas after the changes it + would be 'function return' - remember that where the function does not + return by reference, the reference assignment is converted to a regular + assignment. Again, this can be brought to a common base, either by forcing + func() to return by reference or by eliminating the by-reference + assignment. + +
+ +
+ Code that worked under PHP 4.3.x, but now throws an error + + +getThis(); + } +} + +$bar = new Foo(); +$bar->destroyThis(); +var_dump($bar); +?> +]]> + + + + In PHP 5.0.3, $bar evaluated to NULL instead of returning an object. That + happened because getThis() returns by value, but the value here is + assigned by reference. Although it now works in the expected way, this is + actually invalid code which will throw an E_NOTICE under PHP 4.4 or an + E_STRICT under PHP 5.0.4 and up. + +
+ +
+ Code that failed under PHP 4.3.x, but now works + + + +]]> + + + In PHP 4.3 the third call to var_dump produces NULL, due to the memory + corruption caused by returning an uninitialized value by reference. This + is valid code in PHP 5.0.4 and up, but threw errors in earlier releases + of PHP. + + + + + array('alfa' => 'ok')); +$arr =& $arr['a1']; +echo '-'.$arr['alfa']."-\n"; +?> +]]> + + + Until PHP 5.0.5, it wasn't possible to assign an array element by + reference in this way. It now is. + + +
+ +
+ Code that <literal>should have worked</literal> under PHP 5.0.x + + There are a couple of instances of bugs reported under PHP 5.0 prior to + the reference fixes which now 'work'. However, in both cases errors are + thrown by PHP 5.1.x, because the code was invalid in the first place. + Returning values by reference using self:: now works in the general case + but throws an E_STRICT warning, and although your mileage may vary when + assigning by reference to an overloaded object, you will still see an + E_ERROR when you try it, even where the assignment itself appears to work. + +
+ +
+ Warnings that came and went + + Nested calls to functions returning by reference are valid code under both + PHP 4.3.x and PHP 5.1.x, but threw an unwarranted E_NOTICE or E_STRICT under + the intervening PHP releases. + + + + +]]> + + +
+
+
+ Reading [] + + +test_ref($ar[]); + var_dump($ar); + $this->test($ar[]); + } +} + +$o = new XmlTest(); +$o->run(); +?> +]]> + + + + This should always have thrown a fatal E_ERROR, because [] cannot be used + for reading in PHP. It is invalid code in PHP 4.4.2 and PHP 5.0.5 upward. + +
+ +
+ Integer values in function parameters + + With the advent of PHP 5.0.x, a new parameter parsing API was introduced + which is used by a large number of PHP functions. In all versions of PHP + between 5.0.x and 5.1.x, the handling of integer values was very strict and + would reject non-well formed numeric values when a PHP function expected an + integer. These checks have now been relaxed to support non-well formed + numeric strings such as " 123" and "123 ", and will no longer fail as they + did under PHP 5.0.x. However, to promote code safety and input validation, + PHP functions will now emit an E_NOTICE when such strings are passed as + integers. + +
+ +
+ Class and object changes + + + + instanceof, is_a(), + is_subclass_of() and catch + + + + + Abstract private methods + + + + + Access modifiers in + interfaces + + + + + Changes in inheritance + rules + + + + + Class constants + + + + +
+ instanceof, is_a(), is_subclass_of() and catch + + In PHP 5.0, is_a() was deprecated and replaced by the "instanceof" + operator. There were some issues with the initial implementation of + "instanceof", which relied on __autoload() to search for missing classes. + If the class was not present, "instanceof" would throw a fatal E_ERROR due + to the failure of __autoload() to discover that class. The same behaviour + occurred in the "catch" operator and the is_subclass_of() function, for + the same reason. + + + None of these functions or operators call __autoload() in PHP 5.1.x, and the + class_exists() workarounds used in code written for PHP 5.0.x, while not + problematic in any way, are no longer necessary. + +
+ +
+ Abstract private methods + + Abstract private methods were supported between PHP 5.0.0 and PHP 5.0.4, + but were then disallowed on the grounds that the behaviours of 'private' + and 'abstract' are mutually exclusive. + +
+ +
+ Access modifiers in interfaces + + Under PHP 5.0, function declarations in interfaces were treated in exactly + the same way as function declarations in classes. This has not been the + case since October 2004, at which point only the 'public' access modifier + was allowed in interface function declarations. Since April 2005 - which + pre-dates the PHP 5.0b1 release - the 'static' modifier has also been + allowed. However, the 'protected' and 'private' modifiers will now throw + an E_ERROR, as will 'abstract'. Note that this change should not affect + your existing code, as none of these modifiers makes sense in the context + of interfaces anyway. + +
+ +
+ Changes in inheritance rules + + Under PHP 5.0, it was possible to have a function declaration in a derived + class that did not match the declaration of the same function in the base + class, e.g. + + + + This code will cause an E_STRICT error to be emitted under PHP 5.1.x. + + + +]]> + + +
+ +
+ Class constants + + Under PHP 5.1.x, redefinition of a class constant will throw a fatal + E_ERROR. + + + + Under PHP 5.1.x, redefinition of a class constant will throw a fatal + E_ERROR. + + + +]]> + + +
+
+ +
+ Extensions + + + + Extensions that are gone + from the PHP core + + + + + Class constants in new + PHP 5.1.x extensions + + + + +
+ Extensions that are gone from the PHP core + + One of the first things you're likely to notice when you download PHP 5.1.x + is that several of the older extensions have disappeared. Those extensions + that are still actively maintained are available in the PHP Extension + Community Library (PECL), at + &url.pecl;. Windows binaries are + built regularly, and you can obtain the binaries for PECL extensions built + against PHP 5.1.x from + &url.pecl.win;. + + + Removed extensions + + + + Extension + Alternative/Status + + + + + ext/cpdf + pecl/pdflib + + + ext/dbx + pecl/dbx + + + ext/dio + pecl/dio + + + ext/fam + Not actively maintained + + + ext/ingres_ii + pecl/ingres + + + ext/ircg + Not actively maintained + + + ext/mcve + pecl/mcve + + + ext/mnogosearch + Not actively maintained + + + ext/oracle + + ext/oci8 or + ext/pdo_oci + + + + ext/ovrimos + Not actively maintained + + + ext/pfpro + Not actively maintained + + + ext/w32api + pecl/ffi + + + ext/yp + Not actively maintained + + + ext/activescript + + pecl/activescript + + + + +
+ + Modules in PECL that are not actively maintained (i.e. have not been + supported for some time, have no active maintainer working on them + currently, and do not have any PECL package releases), are still available + in CVS at &url.php.cvs;pecl. + However, unreleased PHP modules are by their nature unsupported, and your + mileage may vary when attempting to install or use them. + +
+ +
+ Class constants in new PHP 5.1.x extensions + + The Zend Engine 2.1 API allows extension developers to declare class + constants in object oriented extensions. New extensions written for PHP + 5.1.x, including SPL, + PDO, + XMLReader and + date, have their constants in + the format PDO::CLASS_CONSTANT rather than in the C + format PDO_CLASS_CONSTANT in order to minimise + pollution of the global namespace in PHP. + +
+
+ +
+ Date/time support + + Date/time support has been fully rewritten in PHP 5.1.x, and no longer uses + the system settings to 'know' the timezone in operation. It will instead + utilize, in the following order: + + + + + The timezone set using the date_default_timezone_set + function (if any) + + + + + The TZ environment variable (if non empty) + + + + + "magical" guess (if the operating system supports it) + + + + + If none of the above options succeeds, UTC + + + + + + To ensure accuracy (and avoid an E_STRICT warning), you will need to define + your timezone in your php.ini using the following format: + + + date.timezone = Europe/London + + + + The supported timezones are listed, in this format, in the + timezones appendix. + + + Also note that strtotime now returns &false; on failure, instead of -1. + +
+ +
+ Changes in database support + + + + PDO overview + + + + + Changes in MySQL support + + + + + Changes in SQLite support + + + + +
+ PDO overview + + PHP Data Objects (PDO) were introduced as a + PECL extension under PHP 5.0, and became part of the core PHP distribution + in PHP 5.1.x. The PDO extension provides a consistent interface for database + access, and is used alongside database-specific PDO drivers. Each driver + may also have database-specific functions of its own, but basic data + access functionality such as issuing queries and fetching data is covered + by PDO functions, using the driver named in + PDO::__construct(). + + + Note that the PDO extension, and its drivers, are intended to be built as + shared extensions. This will enable straightforward driver upgrades from + PECL, without forcing you to rebuild all of PHP. + + + At the point of the PHP 5.1.x release, PDO is more than ready for widespread + testing and could be adopted in most situations. However, it is important + to understand that PDO and its drivers are comparatively young and may be + missing certain database-specific features; evaluate PDO carefully before + you use it in new projects. + + + Legacy code will generally rely on the pre-existing database extensions, + which are still maintained. + +
+ +
+ Changes in MySQL support + + In PHP 4, MySQL 3 support was built-in. With the release of PHP 5.0 there + were two MySQL extensions, named 'mysql' and 'mysqli', which were designed + to support MySQL < 4.1 and MySQL 4.1 and up, respectively. With the + introduction of PDO, which provides a very fast interface to all the + database APIs supported by PHP, the PDO_MYSQL driver can support any of + the current versions (MySQL 3, 4 or 5) in PHP code written for PDO, + depending on the MySQL library version used during compilation. The older + MySQL extensions remain in place for reasons of back compatibility, but + are not enabled by default. + +
+ +
+ Changes in SQLite support + + In PHP 5.0.x, SQLite 2 support was provided by the built-in sqlite + extension, which was also available as a PECL extension in PHP 4.3 and PHP + 4.4. With the introduction of PDO, the sqlite extension doubles up to act + as a 'sqlite2' driver for PDO; it is due to this that the sqlite extension + in PHP 5.1.x has a dependency upon the PDO extension. + + + PHP 5.1.x ships with a number of alternative interfaces to sqlite: + + + The sqlite extension provides the "classic" sqlite procedural/OO API that + you may have used in prior versions of PHP. It also provides the PDO + 'sqlite2' driver, which allows you to access legacy SQLite 2 databases + using the PDO API. + + + PDO_SQLITE provides the 'sqlite' version 3 driver. SQLite version 3 is + vastly superior to SQLite version 2, but the file formats of the two + versions are not compatible. + + + If your SQLite-based project is already written and working against + earlier PHP versions, then you can continue to use ext/sqlite without + problems, but will need to explicitly enable both PDO and sqlite. New + projects should use PDO and the 'sqlite' (version 3) driver, as this is + faster than SQLite 2, has improved locking concurrency, and supports both + prepared statements and binary columns natively. + + + You must enable PDO to use the SQLite extension. If you want to build the + PDO extension as a shared extension, then the SQLite extension must also + be built shared. The same holds true for any extension that provides a PDO + driver + +
+
+ +
+ Checking for <literal>E_STRICT</literal> + + + If you only have a single script to check, you can pick up E_STRICT errors + using PHP's commandline lint facility: + + + php -d error_reporting=4095 -l script_to_check.php + + + For larger projects, the shell script below will achieve the same task: + + + /dev/null; then + if test -f $FILE; then + check_file "$FILE" + fi + fi + done +done +]]> + + +
+ + + + +