xref: /PHP-5.5/UPGRADING (revision 98b9dfae)
1$Id$
2
3PHP 5.5 UPGRADE NOTES
4
51.  Backward Incompatible Changes
62.  New Features
72.  Changes in SAPI modules
83.  Deprecated Functionality
94.  Changed Functions
10    a. unserialize() change
115.  New Functions
126.  New Classes and Interfaces
137.  Removed Extensions
148.  Other Changes to Extensions
159.  New Global Constants
1610. Changes to INI File Handling
1711. Windows Support
1812. Other Changes
19
20
21========================================
221. Backward Incompatible Changes
23========================================
24
25- Dropped Windows XP and 2003 support. (Pierre)
26
27- All internal case insensitivity handling for class, function and constant
28  names is done according to ASCII rules.  Current locale settings are ignored.
29
30- self, parent & static keywords now are always case-insensitive (see bug
31  #60833).
32
33- Removed Logo GUIDs: php_logo_guid(), php_egg_logo_guid(),
34  php_real_logo_guid() and zend_logo_guid()
35
36========================================
372. New Features
38========================================
39
40- Support list in foreach. (Laruence)
41  (http://php.net/foreach#control-structures.foreach.list,
42  http://wiki.php.net/rfc/foreachlist)
43
44- Support "finally" keyword. (Laruence)
45  (http://php.net/exceptions, http://wiki.php.net/rfc/finally)
46
47- Support constant array/string dereferencing. (Laruence)
48  (http://php.net/manual/en/language.types.array.php,
49   https://wiki.php.net/rfc/constdereference)
50
51- Add support for using empty() on the result of function calls and
52  other expressions. Thus it is now possible to write empty(getArray()),
53  for example. (http://php.net/manual/en/function.empty.php,
54  https://wiki.php.net/rfc/empty_isset_exprs)
55
56- Added generators.
57  (http://php.net/generators, https://wiki.php.net/rfc/generators)
58
59- ClassName::class syntax returning full class name for a class as a
60  string constant.  (http://php.net/oop5.basic,
61  https://wiki.php.net/rfc/class_name_scalars)
62
63- Added support for non-scalar Iterator keys in foreach.
64  (http://php.net/manual/en/control-structures.foreach.php,
65  https://wiki.php.net/rfc/foreach-non-scalar-keys).
66
67- Bundled Zend OPcache extension to improve performance
68  (http://php.net/manual/en/book.opcache.php,
69  https://wiki.php.net/rfc/optimizerplus)
70
71- Added a simplified password hashing API
72  (http://php.net/password, https://wiki.php.net/rfc/password_hash)
73
74========================================
752. Changes in SAPI modules
76========================================
77
78- Support for changing the process's title in CLI/CLI-Server
79  SAPIs. (Keyur)
80  (http://php.net/manual/en/function.cli-set-process-title.php,
81  http://php.net/manual/en/function.cli-get-process-title.php,
82  https://wiki.php.net/rfc/cli_process_title)
83
84- Support for systemd in php-fpm: Add --with-fpm-systemd option to
85  report health to systemd, and add systemd_interval option to
86  configure this. The service can now use Type=notify in the systemd
87  unit file. (Remi)
88
89- Support for several XML MIME types in the built-in CLI server. For static
90  files with extensions .xml, .xsl, .xsd the Content-Type header
91  application/xml is now sent automatically.
92
93========================================
943. Deprecated Functionality
95========================================
96
97- The original MySQL extension is now deprecated and will generate
98  deprecation warnings when connecting to a database through
99  mysql_connect(), mysql_pconnect() or by establishing an implicit
100  connection. Use MySQLi or PDO instead.
101
102- The preg_replace /e modifier is now deprecated.  Use
103  preg_replace_callback instead.
104  (https://wiki.php.net/rfc/remove_preg_replace_eval_modifier)
105
106- IntlDateFormatter::setTimeZoneID() and datefmt_set_timezone_id() are
107  deprecated. Use IntlDateFormatter::setTimeZone() or
108  datefmt_set_timezone() instead.
109
110- mcrypt_ecb(), mcrypt_cbc(), mcrypt_cfb() and mcrypt_ofb() now throw
111  E_DEPRECATED. Their use was already previously discouraged in the
112  documentation, but that predated the existence of E_DEPRECATED.
113
114========================================
1154. Changed Functions
116========================================
117
118- pack()/unpack() had the following changes, which bring it more in
119  line with Perl's behavior: - Implemented format character "Z": NULL
120  padded string, with trailing NULL bytes removed.  - Changed format
121  character "a": this no longer removes trailing NULL bytes.  -
122  Changed format character "A": all trailing ASCII whitespace is now
123  removed (defined as spaces, tabs, \r, \n and NULL).
124
125- MessageFormatter::format() and related functions now accepted named
126  arguments and mixed numeric/named arguments in ICU 4.8+.
127
128- MessageFormatter::format() and related functions now don't error out
129  when an insufficient argument count is provided. Instead, the
130  placeholders will remain unsubstituted.
131
132- MessageFormatter::parse() and MessageFormat::format() (and their
133  static equivalents) now don't throw away better than second
134  precision in the arguments.
135
136- IntlDateFormatter::__construct and datefmt_create() now accept for
137  the $timezone argument time zone identifiers, IntlTimeZone objects,
138  DateTimeZone objects and NULL. It used to accept only time zone
139  identifiers and NULL.  Invalid time zone identifiers are no longer
140  accepted. Empty strings are no longer accepted.
141
142- The default time zone used in IntlDateFormatter::__construct and
143  datefmt_create() (when the corresponding argument is not passed or
144  NULL is passed) is now the one given by date_default_timezone_get(),
145  not the default ICU time zone.
146
147- The time zone passed to the IntlDateFormatter is ignored if it is
148  NULL and if the calendar passed is an IntlCalendar object -- in this
149  case, the IntlCalendar's time zone will be used instead. Otherwise,
150  the time zone specified in the $timezone argument is used
151  instead. This does not affect old code, as IntlCalendar was
152  introduced in this version.
153
154- IntlDateFormatter::__construct and datefmt_create() now accept for
155  the $calendar argument also IntlCalendar objects.
156
157- IntlDateFormatter::getCalendar() and datefmt_get_calendar() return
158  false if the IntlDateFormatter was set up with an IntlCalendar
159  instead of the constants
160  IntlDateFormatter::GREGORIAN/TRADITIONAL. IntlCalendar did not exist
161  before this version.
162
163- IntlDateFormatter::setCalendar() and datefmt_set_calendar() now also
164  accept an IntlCalendar object, in which case its time zone is
165  taken. Passing a constant is still allowed, and still keeps the time
166  zone.
167
168- IntlDateFormatter::format() and datefmt_format() now also accept an
169  IntlCalendar object for formatting.
170
171- set_error_handler(NULL) can now be used to reset the error handler.
172  Furthermore both set_error_handler(NULL) and
173  set_exception_handler(NULL) will now return the previously defined
174  error/exception handler. Previously bool(true) was returned.
175
176- setcookie(), setrawcookie() and ext/session now send Max-Age headers
177  alongside Expires headers. (see
178  https://wiki.php.net/rfc/cookie_max-age)
179
180- curl_setopt now accepts new option CURLOPT_SAFE_UPLOAD and CURLFile
181  object for safer file uploads (see
182  https://wiki.php.net/rfc/curl-file-upload)
183
184- Functions in the socket extension now do not emit warnings when the
185  errno is EAGAIN, EWOULDBLOCK or EINPROGRESS.
186
187- Since 5.5.2, spl_autoload_functions() returns different names for
188  different lambda functions registered via spl_autoload_register().
189
190- Since 5.5.3, DOMDocument::schemaValidateSource() and
191  DOMDocument::schemaValidate() accept flag parameter. Only flag
192  available now is LIBXML_SCHEMA_CREATE. Default is 0.
193
194- Since 5.5.4, fputcsv() has fifth parameter escape_char, allowing to
195  specify escape char.
196
197- Since 5.5.38, getenv() has optional second parameter, making it only
198  consider local environment and not SAPI environment if true.
199
2004a. unserialize() change
201------------------------
202
203- Starting PHP 5.5.13, the bug fix for bug #67072 introduces a change to
204  unserialize() function, detailed below:
205
206    If the string looking like 'O:..:"ClassName":...' is unserialized, and
207    the class named is an internal class that declares custom unserializer
208    function, or extends such class, unserialize would fail.
209
210    Using O: for user classes not extending internal classes (including
211    those implementing Serializable) is still supported in 5.4, though
212    it is deprecated and may not be supported in 5.6 for classes that do not
213    originally serialize to O:. Same for using O: for internal classes
214    implementing Serializable (like ArrayObject) and classes that extend
215    them.
216
217    The reason for that is that O: format is meant to be used with classes
218    that do not define custom handlers, and was never intended for the use
219    with classes that do. When used with the class that relies on custom
220    unserializer, it can leave the object of such internal class in an
221    inconsistent state which has been observed to result in crashes and may
222    also lead to memory corruption and ultimately even arbitrary code
223    execution. This was never the intended use of unserializer, and mere
224    possibility of doing this constitutes a bug, since the data passed to
225    unserialize() is not a valid serialization of any object. Since there
226    are many applications applying unserialize() to untrusted data, this
227    presents a potential security vulnerability. Thus, keeping such bug in
228    the code base was considered too dangerous.
229
230    We are aware that some applications use O: format as a way to
231    instantiate classes. This was never the intended usage of serializer,
232    and ReflectionClass methods such as newInstance or
233    newInstanceWithoutConstructor can be used for that. We're working on
234    providing more comprehensive solution for such use cases in PHP 5.6 and
235    welcome the ideas in this area.
236
237    We note also that using unserialize() on any data that is not the result
238    of serialize() call continues to be an unsupported scenario and should
239    not be relied on to produce any specific result.
240
241========================================
2425. New Functions
243========================================
244
245- Core:
246  - array_column()
247  - boolval()
248  - password_get_info()
249  - password_hash()
250  - password_needs_rehash()
251  - password_verify()
252
253- cURL:
254  - curl_file_create
255
256- GD
257  - imageflip
258  - imagecrop
259  - imagecropauto
260  - imagesetinterpolation
261  - imageaffine
262  - imageaffinematrixget
263  - imageaffinematrixconcat
264  - imagescale
265
266- Hash:
267  - hash_pbkdf2()
268
269- Intl:
270  - datefmt_format_object()
271  - datefmt_get_calendar_object()
272  - datefmt_get_timezone()
273  - datefmt_set_timezone()
274  - datefmt_get_calendar_object()
275  - intlcal_create_instance()
276  - intlcal_get_keyword_values_for_locale()
277  - intlcal_get_now()
278  - intlcal_get_available_locales()
279  - intlcal_get()
280  - intlcal_get_time()
281  - intlcal_set_time()
282  - intlcal_add()
283  - intlcal_set_time_zone()
284  - intlcal_after()
285  - intlcal_before()
286  - intlcal_set()
287  - intlcal_roll()
288  - intlcal_clear()
289  - intlcal_field_difference()
290  - intlcal_get_actual_maximum()
291  - intlcal_get_actual_minimum()
292  - intlcal_get_day_of_week_type()
293  - intlcal_get_first_day_of_week()
294  - intlcal_get_greatest_minimum()
295  - intlcal_get_least_maximum()
296  - intlcal_get_locale()
297  - intlcal_get_maximum()
298  - intlcal_get_minimal_days_in_first_week()
299  - intlcal_get_minimum()
300  - intlcal_get_time_zone()
301  - intlcal_get_type()
302  - intlcal_get_weekend_transition()
303  - intlcal_in_daylight_time()
304  - intlcal_is_equivalent_to()
305  - intlcal_is_lenient()
306  - intlcal_is_set()
307  - intlcal_is_weekend()
308  - intlcal_set_first_day_of_week()
309  - intlcal_set_lenient()
310  - intlcal_equals()
311  - intlcal_get_repeated_wall_time_option()
312  - intlcal_get_skipped_wall_time_option()
313  - intlcal_set_repeated_wall_time_option()
314  - intlcal_set_skipped_wall_time_option()
315  - intlcal_from_date_time()
316  - intlcal_to_date_time()
317  - intlcal_get_error_code()
318  - intlcal_get_error_message()
319  - intlgregcal_create_instance()
320  - intlgregcal_set_gregorian_change()
321  - intlgregcal_get_gregorian_change()
322  - intlgregcal_is_leap_year()
323  - intltz_create_time_zone()
324  - intltz_create_default()
325  - intltz_get_id()
326  - intltz_get_gmt()
327  - intltz_get_unknown()
328  - intltz_create_enumeration()
329  - intltz_count_equivalent_ids()
330  - intltz_create_time_zone_id_enumeration()
331  - intltz_get_canonical_id()
332  - intltz_get_region()
333  - intltz_get_tz_data_version()
334  - intltz_get_equivalent_id()
335  - intltz_use_daylight_time()
336  - intltz_get_offset()
337  - intltz_get_raw_offset()
338  - intltz_has_same_rules()
339  - intltz_get_display_name()
340  - intltz_get_dst_savings()
341  - intltz_from_date_time_zone()
342  - intltz_to_date_time_zone()
343  - intltz_get_error_code()
344  - intltz_get_error_message()
345
346  - IntlDateFormatter::formatObject()
347  - IntlDateFormatter::getCalendarObject()
348  - IntlDateFormatter::getTimeZone()
349  - IntlDateFormatter::setTimeZone()
350
351- LDAP:
352  - ldap_modify_batch() (5.5.10)
353
354- SOAP:
355  - SoapClient::__getCookies() (5.5.14)
356
357- Sockets:
358  - socket_sendmsg()
359  - socket_recvmsg()
360  - socket_cmsg_space()
361
362- SPL:
363  - SplFixedArray::__wakeup()
364  - SplDoublyLinkedList::add()
365  - RecursiveTreeIterator::getPostfix() (5.5.2)
366  - RecursiveTreeIterator::setPostfix() (5.5.2)
367
368- Zend OPcache:
369 - opcache_get_configuration()
370 - opcache_get_status()
371 - opcache_reset()
372
373========================================
3746. New Classes and Interfaces
375========================================
376
377- Intl:
378  - IntlCalendar
379  - IntlGregorianCalendar
380  - IntlTimeZone
381  - IntlBreakIterator
382  - IntlRuleBasedBreakIterator
383  - IntlCodePointBreakIterator
384  - UConverter
385
386- cURL:
387  - CURLFile
388
389========================================
3907. Removed Extensions
391========================================
392
393None
394
395========================================
3968. Other Changes to Extensions
397========================================
398
399- Intl:
400  - This extension now requires ICU 4.0+.
401- Phar:
402  - Added ability of resolving alias created by Phar::map
403
404========================================
4059. New Global Constants
406========================================
407
408- mysqli:
409  - Added MYSQLI_SERVER_PUBLIC_KEY constant to be used with mysqli_options()
410
411- cURL:
412  - Added CURLOPT_SAFE_UPLOAD to be used with curl_setopt().
413  - Added CURL_WRAPPERS_ENABLED to reflect --with-curlwrappers.
414  - Added CURL_HTTP_VERSION_2_0 and CURL_VERSION_HTTP2 in 5.5.24+.
415
416- GD
417  - Added constants for imageflip:
418    . IMG_FLIP_HORIZONTAL
419    . IMG_FLIP_VERTICAL
420    . IMG_FLIP_BOTH
421  - Added constants for imagecrop
422    . IMG_CROP_DEFAULT
423    . IMG_CROP_TRANSPARENT
424    . IMG_CROP_BLACK
425    . IMG_CROP_WHITE
426    . IMG_CROP_SIDES
427    . IMG_CROP_THRESHOLD
428  - Added constants for imagesetinterpolation, used by imagescale
429    imagerotate and imageaffine:
430    . IMG_BELL
431    . IMG_BESSEL
432    . IMG_BILINEAR_FIXED
433    . IMG_BICUBIC
434    . IMG_BICUBIC_FIXED
435    . IMG_BLACKMAN
436    . IMG_BOX
437    . IMG_BSPLINE
438    . IMG_CATMULLROM
439    . IMG_GAUSSIAN
440    . IMG_GENERALIZED_CUBIC
441    . IMG_HERMITE
442    . IMG_HAMMING
443    . IMG_HANNING
444    . IMG_MITCHELL
445    . IMG_POWER
446    . IMG_QUADRATIC
447    . IMG_SINC
448    . IMG_NEAREST_NEIGHBOUR
449    . IMG_WEIGHTED4
450    . IMG_TRIANGLE
451  - Added constants for imageaffinematrixget
452    . IMG_AFFINE_TRANSLATE
453    . IMG_AFFINE_SCALE
454    . IMG_AFFINE_ROTATE
455    . IMG_AFFINE_SHEAR_HORIZONTAL
456    . IMG_AFFINE_SHEAR_VERTICAL
457
458========================================
45910. Changes to INI File Handling
460========================================
461
462- Core:
463  - Added sys_temp_dir INI directive, for specifying temporary
464    directory.
465
466- Intl:
467  - Added intl.use_exceptions INI directive, which controls what
468    happens when global errors are set together with intl.error_level.
469
470- MSSQL:
471  - mssql.compatability_mode renamed to mssql.compatibility_mode in 5.5.2,
472    old directive still supported for BC reasons.
473
474- mysqlnd:
475  - Added mysqlnd.sha256_server_public_key INI PERDIR setting that
476    affects all APIs which use(are built) for mysqlnd. This allows
477    ext/mysqli to be used with the new auth protocol, although at
478    coarser level.
479
480- Sessions:
481  - Added session.use_strict_mode in 5.5.3, which prevents session
482    fixation attacks and session collisions.
483    See also https://wiki.php.net/rfc/strict_sessions
484
485- Zend OPcache (See http://php.net/manual/en/book.opcache.php)
486  - Added the following directives:
487    - opcache.enable (default "1")
488    - opcache.memory_consumption (default "64")
489    - opcache.interned_strings_buffer (default "4")
490    - opcache.max_accelerated_files (default "2000")
491    - opcache.max_wasted_percentage (default "5")
492    - opcache.use_cwd (default "1")
493    - opcache.validate_timestamps (default "1")
494    - opcache.revalidate_freq (default "2")
495    - opcache.revalidate_path (default "0")
496    - opcache.save_comments (default "1")
497    - opcache.load_comments (default "1")
498    - opcache.fast_shutdown (default "0")
499    - opcache.enable_file_override (default "0")
500    - opcache.optimization_level (default "0xffffffff")
501    - opcache.inherited_hack (default "1")
502    - opcache.blacklist_filename (default "")
503    - opcache.max_file_size (default "0")
504    - opcache.consistency_checks (default "0")
505    - opcache.force_restart_timeout (default "180")
506    - opcache.error_log (default "" which means stderr)
507    - opcache.log_verbosity_level (default "1")
508    - opcache.preferred_memory_model (default "")
509    - opcache.protect_memory (default "0")
510    - opcache.mmap_base (Windows-only)
511
512========================================
51311. Windows Support
514========================================
515
516- The Apache 2.4 handler is supported as of PHP 5.5.0
517
518- OPcache: Errors like 'unable to reattach to base address' could
519  happen in many common setups.  It is due to some technical and
520  design restriction in the engine and could not be fixed easily
521  before 5.5.0 was released.
522
523  A possible fix is to tweak the opcache.mmap_base INI setting by
524  forcing the first address to be tried.
525
526  For x86 version, the following addreses can be tried:
527        .  0x20000000, 0x21000000, 0x30000000, 0x31000000, 0x50000000
528  and for x64 (still experimental):
529        . 0x0000100000000000, 0x0000200000000000, 0x0000300000000000, 0x0000700000000000
530
531========================================
53212. Other Changes
533========================================
534
535- If the APC or WinCache user cache APIs were used before, consider
536   these alternatives for PHP 5.5:
537
538  - APCu
539      - all supported OSes: http://pecl.php.net/package/APCu
540      - Windows: http://windows.php.net/downloads/pecl/releases/apcu/
541
542  - WinCache, Windows only: http://pecl.php.net/package/WinCache
543