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