xref: /PHP-5.3/UPGRADING (revision f5d8b638)
1$Id$
2
3UPGRADE NOTES - PHP 5.3
4
51. Reserved words and classes
62. Changes made to existing functions
73. Changes made to existing methods
84. Changes made to existing classes
95. Deprecated
106. Undeprecated
117. Extensions:
12     a. moved out to PECL and actively maintained there
13     b. no longer maintained
14     c. with changed behaviour
15     d. no longer possible to disable
168. Changes in SAPI support
179. Changes in INI directives
1810. Syntax additions
1911. Windows support
2012. New in PHP 5.3:
21     a. New libraries
22     b. New extensions
23     c. New stream wrappers
24     d. New stream filters
25     e. New functions
26     f. New global constants
27     g. New classes
28     h. New methods
29     i. New class constants
30
31=============================
321. Reserved words and classes
33=============================
34
35- **namespace** and **goto** are now reserved keywords.
36
37- **Closure** is now a reserved class. (Used by lambda and closure.)
38
39=====================================
402. Changes made to existing functions
41=====================================
42
43- Paths containing NULL (like /some/path\0foo.txt) are now considered invalid.
44  See http://news.php.net/php.internals/50191
45
46- The HTTP stream wrapper now considers all status codes from 200 to 399 to be
47  successful.
48
49- The array functions natsort(), natcasesort(), usort(), uasort(), uksort(),
50  array_flip(), and array_unique() no longer accept objects passed as arguments.
51  If you need to use them to access an object's properties, you must cast the
52  object to an array first.
53
54- var_dump() output now includes private object members.
55
56- session_start() now returns FALSE when the session startup fails.
57
58- property_exists() now checks the existence of a property independent of
59  accessibility (like method_exists()).
60
61- The $initial parameter for array_reduce can now be of any type.
62
63- clearstatcache() no longer clears the realpath cache by default.
64
65- realpath() is no longer system-dependent and works identically on all
66  platforms.
67
68- call_user_func() now propagates $this even if the callee is the parent class.
69
70- The filesystem functions opendir(), scandir(), and dir() now use the default
71  context if no context argument is passed.
72
73- The behaviour of functions with by-reference parameters called by value has
74  changed. Where previously the function would accept the by-value argument, a
75  warning is now emitted and all by-ref parameters are set to NULL.
76
77- There is now native support for the following math functions: asinh(),
78  acosh(), atanh(), log1p(), and expm1().
79
80- In the GD extension, there is now pixelation support available through
81  the imagefilter() function.
82
83- crypt() now has Blowfish and extended DES support, and crypt() features are
84  now 100% portable. PHP has its own internal crypt implementation which drops
85  into place when system support for crypt or crypt_r() is not found.
86
87- get_cfg_var() is now able to return "array" INI options.
88
89- Stream wrappers can now be used by the include_path INI directive.
90
91- These functions now take new parameters:
92     clearstatcache(): $clear_realpath_cache and $filename.
93     copy(): $context
94     fgetcsv(): $escape
95     ini_get_all(): $details
96     json_encode(): $options
97     json_decode(): $depth
98     nl2br(): $is_xhtml
99     parse_ini_file(): $scanner_mode
100     round(): $mode
101     stream_context_create(): $params
102     strstr(), stristr(): $before_needle
103     sybase_connect(): $new
104
105- And new mode option for fopen: 'n' (O_NONBLOCK)
106
107- The new mysqlnd library necessitates using MySQL's newer 41-byte password
108  format. Continued use of the old 16 byte passwords will cause mysql_connect()
109  and other related functions to produce the following error message:
110  "mysqlnd cannot connect to MySQL 4.1+ using old authentication"
111
112- The dl() function is now disabled by default, and only available under the
113  cli, cgi, and embed SAPIs.
114
115- mail() now supports the logging of sent mail.
116
117- stream_select(), stream_set_blocking(), stream_set_timeout(), and
118  stream_set_write_buffer() now work with user-space stream wrappers.
119
120- getopt() accepts "long options" now on all platforms.
121  Optional values and using = as a separator for short options are now
122  supported.
123
124
125===================================
1263. Changes made to existing methods
127===================================
128
129- The magic methods __get(), __set(), __isset(), __unset(), and __call() should
130  always be public and can no longer be static. Method signatures are enforced.
131
132- The __call() magic method is now invoked on access to private and protected
133  methods.
134
135- The __toString() magic method can no longer accept arguments.
136
137- There is a new magic method, __callStatic().
138
139- Internal count() vs. count_elements() handler resolution rules have changed.
140  (This could potentially break custom PHP extensions.)
141
142- The trailing / has been removed from SplFileInfo and other related directory
143  classes.
144
145- SplFileInfo::getpathinfo() now returns information about the path name.
146
147- There are new parameters in:
148     Exception::__construct(): $previous
149
150===================================
1514. Changes made to existing classes
152===================================
153
154- SplObjectStorage now has ArrayAccess support. It is also now possible to
155  store associative information with objects in SplObjectStorage.
156
157=====================
1584.1 New in PHP 5.3.9
159=====================
160
161- Write operations within XSLT (for example with the extension sax:output) are
162  disabled by default. You can define what is forbidden with the INI option
163  xsl.security_prefs. This option will be marked as deprecated in 5.4 again.
164  Use the method XsltProcess::setSecurityPrefs($options) there.
165
166- the following new directives were added
167
168  - max_input_vars - specifies how many GET/POST/COOKIE input variables may be
169    accepted. default value 1000.
170
171=============
1725. Deprecated
173=============
174
175- define_syslog_variables() is deprecated.
176
177- set_socket_blocking() is deprecated.
178
179- call_user_method() and call_user_method_array() are now deprecated. Use
180  call_user_func() and call_user_func_array() instead.
181
182- dl() is deprecated.
183
184- The set_magic_quotes_runtime() function is now deprecated.
185
186- mysql_listtables(), mysql_dropdb(), mysql_createdb(), mysql_list_tables(),
187  mysql_drop_db(), and mysql_create_db() are now deprecated.
188
189- All ereg functions are now deprecated and emit E_DEPRECATED errors:
190  sql_regcase(), spliti(), split(), ereg_replace(), eregi(),
191  ereg_replace(), and ereg().
192  Use the PCRE family of functions (preg_*()) instead.
193
194- mcrypt_generic_end() is deprecated.
195
196- mysql_db_query() is deprecated.
197
198- mysql_escape_string() is deprecated.
199
200- session_register(), session_unregister(), and session_is_registered() are now
201  deprecated. Use the $_SESSION superglobal array instead.
202
203- Comments starting with '#' are now deprecated in .INI files.
204
205- The following INI directives will now emit an E_DEPRECATED warning
206  upon startup if they are activated:
207
208        - define_syslog_variables
209        - register_globals
210        - register_long_arrays
211        - safe_mode
212        - magic_quotes_gpc
213        - magic_quotes_runtime
214        - magic_quotes_sybase
215
216- The is_dst parameter to mktime() is deprecated.
217
218- Assigning the return value of "new" by reference is deprecated
219
220- Call-time pass-by-reference has been deprecated
221
222- Usage of {} to access string offsets is deprecated
223
224- Passing locale category name as string to setlocale() is deprecated.
225
226===============
2276. Undeprecated
228===============
229
230- By popular request, is_a() is no longer deprecated.
231
232==============
2337. Extensions:
234==============
235
236     a. moved out to PECL and actively maintained there
237
238        - fdf
239        - ming
240        - ncurses
241
242     b. no longer maintained
243
244        - dbase
245        - fbsql
246        - msql
247        - sybase (use sybase_ct, which is still in PHP core)
248        - mhash (hash has full BC layer)
249        - mime_magic (use fileinfo, has full BC layer)
250
251     c. with changed behaviour
252
253        - dns: dns_check_record() will now return an extra "entries" index,
254          containing the TXT elements.
255
256        - datetime: date/time functions will no longer use the TZ environment
257          variable to guess which timezone should be used.
258
259        - cURL now supports SSH
260
261        - hash: The SHA-224 and salsa hash algorithms are now supported.
262
263        - mbstring: Now supports CP850 encoding.
264
265        - oci8: Database Resident Connection Pooling (DRCP) and Fast Application
266          Notification (FAN) are now supported.
267
268          Oracle External Authentication is now supported (except on Windows).
269
270          The oci8 function oci_bind_by_name() now supports SQLT_AFC (aka the
271          CHAR datatype).
272
273          Calling oci_close() on a persistent connection, or when the variable
274          that references a persistent connection goes out of scope, will now
275          trigger a roll back of an uncommitted transaction. To avoid unexpected
276          behavior explicitly issue a commit or roll back as needed. The old
277          behavior can be enabled with the INI directive
278          oci8.old_oci_close_semantics.
279
280        - openssl: OpenSSL digest and cipher functions are now supported.
281          It is also now possible to access the internal values of DSA, RSA and
282          DH keys.
283
284        - session: Sessions will no longer store session-files in "/tmp" when
285          open_basedir restrictions apply, unless "/tmp" is explicitly added to
286          the list of allowed paths.
287
288        - SOAP: Now supports sending user-supplied HTTP headers.
289
290        - MySQLi: Now supports persistent connections by prepending the hostname
291          with "p:".
292
293        - imagepstext now rejects invalid antialiasing steps and raises a warning.
294
295     d. no longer possible to disable
296
297        - PCRE
298        - Reflection
299        - SPL
300
301==========================
3028. Changes in SAPI support
303==========================
304
305- A new "litespeed" SAPI is now available.
306
307- FastCGI is now always enabled and can not be disabled. See sapi/cgi/CHANGES
308  for more details.
309
310- A new CGI SAPI option, -T, can be used to measure execution time of a script
311  repeated several times.
312
313- CGI/FastCGI now has support for .htaccess style user-defined php.ini files.
314  See the new user_ini.filename and user_ini.cache_ttl INI directives.
315
316============================
3179. Changes in INI directives
318============================
319
320- zend_extension_debug and zend_extension_ts have been removed. Always use the
321  zend_extension directive to load Zend Extensions.
322
323- zend.ze1_compatibility_mode has been removed. If this INI directive is set to
324  on, then an E_ERROR is emitted at startup.
325
326- There is now support for special sections: [PATH=/opt/httpd/www.example.com/]
327  and [HOST=www.example.com]. Directives set in these sections cannot be
328  overridden by user-defined INI files or at runtime.
329
330- Added mbstring.http_output_conv_mimetype. This directive specifies the
331  regex pattern of content types for which mb_output_handler() is activated.
332
333- It is now possible to use the full path to load modules using the "extension"
334  directive.
335
336- "INI variables" can now be used almost anywhere in a php.ini file.
337
338- It is now possible to use alphanumeric or variable indices in INI option
339  arrays.
340
341- open_basedir is now PHP_INI_ALL
342
343- Runtime tightening of open_basedir restrictions is now possible.
344
345- The default value of session.use_only_cookies has changed to "1".
346
347- The default value of oci8.default_prefetch has been changed from 10 to 100.
348
349- A new directive, request_order, controls the behavior of $_REQUEST
350  independently of variables_order.
351- A new directive, called windows.show_crt_warning, has been introduced.
352  This directive shows the CRT warnings when enabled. These warnings were
353  displayed by default until now. It is disabled by default.
354
355- New INI directives:
356  - mail.add_x_header
357  - user_ini.filename
358  - user_ini.cache_ttl
359  - exit_on_timeout
360  - mysqli.allow_persistent
361  - mysqli.default_host
362  - mysqli.default_socket
363  - mysqli.allow_local_infile
364  - mysqli.cache_size
365  - oci8.connection_class
366  - oci8.events
367  - pdo_mysql.default_socket
368  - pdo_mysql.cache_size
369  - sqlite3.extension_dir
370  - mysql.default_socket
371  - mysql.allow_local_infile
372  - mysql.cache_size
373  - mysqlnd.collect_statistics
374  - mysqlnd.collect_memory_statistics
375  - mysqlnd.net_cmd_buffer_size
376  - mysqlnd.net_read_buffer_size
377  - mysqlnd.log_mask
378
379
380====================
38110. Syntax additions
382====================
383
384- NOWDOC: Similar to HEREDOC, but with single quotes:
385
386      <<<'LABEL' ...
387
388  Static HEREDOCs can be used to initialize static variables and class members
389  or constants:
390
391      static $foo = <<<LABEL
392      No variables here...
393      LABEL;
394
395- HEREDOC now supports wrapping the identifier with double-quotes, to complement
396  the NOWDOC syntax:
397
398      <<<"LABEL" ...
399
400- The ?: operator has been introduced:
401
402      var_dump(0 ?: 'Hello!');
403
404- Namespaces were added:
405
406      namespace my\name;
407      $obj = new \my\name\MyClass;
408
409- Dynamic access to static methods is now possible:
410
411      $foo::myFunc();
412
413- Exceptions can now be nested:
414
415      class MyCustomException extends Exception {}
416      try {
417          throw new MyCustomException("Something happend", 112);
418      } catch(Exception $e) {
419          throw new InvalidArgumentException("You are doing it wrong!", 911, $e);
420      }
421
422- Exceptions can now be handled in destructors.
423
424- A garbage collector has been added and is enabled by default.
425
426===================
42711. Windows support
428===================
429
430- The minimum Windows version is now Windows 2000. (Windows 98, ME and NT4 are
431  no longer supported).
432
433- PHP Windows binaries target i586 or later. i386 and i486 are not supported.
434
435- Support for the IIS SAPI has been dropped. Use the FastCGI SAPI instead
436  (available for IIS5 and later)). FastCGI is the recommended way to use PHP
437  with IIS (see http://php.iis.net/).
438
439- A new build is available based on the latest Visual C++ Compiler (VC9).
440  Its use is recommended with FastCGI or CLI. Apache's Windows binaries are not
441  compatible with VC9; however, you can use Apache Lounge's build
442  (http://apachelounge.com).
443
444- The x64 binaries are for experimental usage only. They are not meant to be
445  used in production.
446
447- A new site is available to download Windows releases as well as Windows-only
448  releases: http://windows.php.net. Windows-specific releases will be made to
449  fix security issues in the bundled libraries (libpng, openssl, etc.). Please
450  note that this site does not replace the main PHP site as a source of PHP
451  news, resources, or documentation.
452
453- Windows support has been added for the following functions: getopt(),
454  imagecolorclosesthwb(), mcrypt_create_iv(), inet_ntop(), inet_pton(),
455  getmxrr(), checkdnsrr(), dns_get_record(), linkinfo(), readlink(),
456  symlink(), link(), fnmatch(), stream_socket_pair(), time_nanosleep(),
457  time_sleep_until(), and socket_create_pair().
458
459- Crypt supports now all available algorithms on Windows (blowfish included).
460
461- Improved portability of stat(), touch(), filemtime(), filesize() and related
462  functions (100% portable for the available data).
463
464- It is now possible to create hard links on Windows using the link() function,
465  and symbolic links using the symlink() function. Hard links are available
466  as of Windows 2000 and symbolic links as of Windows Vista.
467
468- The PDO_OCI php_pdo_oci8.dll library (for use with Oracle version 8 client
469  libraries) is no longer being built. Instead, use php_pdo_oci.dll (note no
470  '8') with Oracle 10 or 11 client libraries. Connection to other database
471  versions is still supported.
472
473- For the OCI8 extension, a new library php_oci8_11g.dll is available in
474  addition to php_oci8.dll. Only one can be enabled at any time. Use
475  php_oci8.dll with Oracle 10.2 client libraries. Use php_oci8_11g.dll with
476  Oracle 11 client libraries. Connection to other database versions is still
477  supported.
478
479- Firebird and SNMP support are no longer available on Windows. Firebird support
480  may be reintroduced in the future.
481
482- As of PHP 5.3.15 and above the COM extension isn't compiled statically in PHP
483  anymore but shared. It'll still be delivered with the standard PHP release but
484  must be activated manually with the "extension = php_com_dotnet.dll" directive
485  in php.ini.
486
487- Apache 2.4 handler is supported as of PHP 5.3.20
488
489=====================
49011.1 New in PHP 5.3.4
491=====================
492
493- open_basedir supports now symbolic links (checks the target).
494- is_link and SplFileInfo symbolic links related method are now fully supported
495  (on Windows Vista or later).
496
497===================
49812. New in PHP 5.3:
499===================
500
501     a. New libraries
502
503       - mysqlnd is a new core library shipped with PHP. It is a PHP-specific
504         replacement for libmysql and is recommended for all installations for
505         increased performance.
506
507     b. New extensions
508
509       - enchant
510       - fileinfo (replaces mime_magic)
511       - intl
512       - Phar
513       - SQLite3
514
515     c. New stream wrappers
516
517       - glob:// stream wrapper
518       - phar:// stream wrapper for accessing phar archives
519
520     d. New stream filters
521
522       - "dechunk" (HTTP/1.1 chunked transfer encoding)
523       - The bz2.decompress filter now supports concatenation
524
525     e. New functions
526
527       - Core:    gc_collect_cycles()
528                  gc_enabled()
529                  gc_enable()
530                  gc_disable()
531                  class_alias()
532                  get_called_class()
533                  forward_static_call()
534                  forward_static_call_array()
535                  str_getcsv()
536                  quoted_printable_encode()
537                  lcfirst()
538       - Array:   array_replace()
539                  array_replace_recursive()
540       - Date:    date_add()
541                  date_sub()
542                  date_diff()
543                  date_parse_from_format()
544                  date_create_from_format()
545                  date_get_last_errors()
546                  timezone_version_get()
547       - INI:     parse_ini_string()
548       - GMP:     gmp_testbit()
549       - Hash:    hash_copy()
550       - IMAP:    imap_gc()
551                  imap_utf8_to_mutf7()
552                  imap_mutf7_to_utf8()
553       - JSON:    json_last_error()
554       - libxml:  libxml_disable_entity_loader
555       - MySQLi:  mysqli_fetch_all()
556                  mysqli_get_connection_stats()
557                  mysqli_poll()
558                  mysqli_reap_async_query()
559       - Network: gethostname()
560                  header_remove()
561       - OpenSSL: openssl_random_pseudo_bytes()
562       - PCNTL:   pcntl_signal_dispatch()
563                  pcntl_sigprocmask()
564                  pcntl_sigwaitinfo()
565                  pcntl_sigtimedwait()
566       - PCRE:    preg_filter()
567       - SHM:     msg_queue_exists()
568                  shm_has_var()
569       - Streams: stream_supports_lock()
570                  stream_context_set_default()
571                  stream_context_get_params()
572       - Userspace stream wrappers:
573                  stream_cast()
574                  stream_set_options()
575
576     f. New global constants
577
578       - Core:    E_DEPRECATED
579                  E_USER_DEPRECATED
580                  __DIR__
581                  __NAMESPACE__
582                  PHP_MAXPATHLEN
583                  PHP_WINDOWS_VERSION_MAJOR
584                  PHP_WINDOWS_VERSION_MINOR
585                  PHP_WINDOWS_VERSION_BUILD
586                  PHP_WINDOWS_VERSION_PLATFORM
587                  PHP_WINDOWS_VERSION_SP_MAJOR
588                  PHP_WINDOWS_VERSION_SP_MINOR
589                  PHP_WINDOWS_VERSION_SUITEMASK
590                  PHP_WINDOWS_VERSION_PRODUCTTYPE
591                  PHP_WINDOWS_NT_DOMAIN_CONTROLLER
592                  PHP_WINDOWS_NT_SERVER
593                  PHP_WINDOWS_NT_WORKSTATION
594       - INI:     INI_SCANNER_NORMAL
595                  INI_SCANNER_RAW
596       - cURL     CURLOPT_PROGRESSFUNCTION
597       - GD:      IMG_FILTER_PIXELATE
598       - JSON:    JSON_ERROR_NONE
599                  JSON_ERROR_DEPTH
600                  JSON_ERROR_STATE_MISMATCH
601                  JSON_ERROR_CTRL_CHAR
602                  JSON_ERROR_SYNTAX
603                  JSON_FORCE_OBJECT
604                  JSON_HEX_TAG
605                  JSON_HEX_AMP
606                  JSON_HEX_APOS
607                  JSON_HEX_QUOT
608       - LDAP:    LDAP_OPT_NETWORK_TIMEOUT
609       - libxml:  LIBXML_LOADED_VERSION
610       - PCRE:    PREG_BAD_UTF8_OFFSET_ERROR
611       - PCNTL:   SIG_BLOCK
612                  SIG_UNBLOCK
613                  SIG_SETMASK
614                  SI_USER
615                  SI_NOINFO
616                  SI_KERNEL
617                  SI_QUEUE
618                  SI_TIMER
619                  SI_MESGQ
620                  SI_ASYNCIO
621                  SI_SIGIO
622                  SI_TKILL
623                  CLD_EXITED
624                  CLD_KILLED
625                  CLD_DUMPED
626                  CLD_TRAPPED
627                  CLD_STOPPED
628                  CLD_CONTINUED
629                  TRAP_BRKPT
630                  TRAP_TRACE
631                  POLL_IN
632                  POLL_OUT
633                  POLL_MSG
634                  POLL_ERR
635                  POLL_PRI
636                  POLL_HUP
637                  ILL_ILLOPC
638                  ILL_ILLOPN
639                  ILL_ILLADR
640                  ILL_ILLTRP
641                  ILL_PRVOPC
642                  ILL_PRVREG
643                  ILL_COPROC
644                  ILL_BADSTK
645                  FPE_INTDIV
646                  FPE_INTOVF
647                  FPE_FLTDIV
648                  FPE_FLTOVF
649                  FPE_FLTUND
650                  FPE_FLTRES
651                  FPE_FLTINV
652                  FPE_FLTSUB
653                  SEGV_MAPERR
654                  SEGV_ACCERR
655                  BUS_ADRALN
656                  BUS_ADRERR
657                  BUS_OBJERR
658
659     g. New classes
660
661       - Date:    DateInterval
662                  DatePeriod
663       - Phar:    Phar
664                  PharData
665                  PharFileInfo
666                  PharException
667       - SPL      SplDoublyLinkedList
668                  SplStack
669                  SplQueue
670                  SplHeap
671                  SplMinHeap
672                  SplMaxHeap
673                  SplPriorityQueue
674                  SplFixedArray
675                  FilesystemIterator
676                  GlobIterator
677                  RecursiveTreeIterator
678                  MultipleIterator
679
680     h. New methods
681
682       - Date:         DateTime::diff()
683                       DateTime::add()
684                       DateTime::sub()
685                       DateTime::createFromFormat()
686                       DateTime::getLastErrors()
687       - DOM:          DOMNode::getLineNo()
688       - Exception:    Exception::getPrevious()
689       - PDO_Firebird: PDO::setAttribute()
690       - Reflection:   ReflectionProperty::setAccessible()
691                       ReflectionFunction::inNamespace()
692                       ReflectionFunction::getNamespaceName()
693                       ReflectionFunction::getShortName()
694                       ReflectionClass::inNamespace()
695                       ReflectionClass::getNamespaceName()
696                       ReflectionClass::getShortName()
697       - SPL:          DirectoryIterator::getExtension()
698                       SplFileInfo::getExtension()
699                       SplObjectStorage::addAll()
700                       SplObjectStorage::removeAll()
701       - XSL:          XSLTProcessor::setProfiling()
702
703     i. New class constants
704
705       - PDO_Firebird: PDO::FB_ATTR_DATE_FORMAT
706                       PDO::FB_ATTR_TIME_FORMAT
707                       PDO::FB_ATTR_TIMESTAMP_FORMAT
708