php-src/UPGRADING

$Id$

UPGRADE NOTES - PHP 5.3

1. Reserved words and classes
2. Changes made to existing functions
3. Changes made to existing methods
4. Changes made to existing classes
5. Deprecated
6. Undeprecated
7. Extensions:
     a. moved out to PECL and actively maintained there
     b. no longer maintained
     c. with changed behaviour
     d. no longer possible to disable
8. Changes in SAPI support
9. Changes in INI directives
10. Syntax additions
11. Windows support
12. New in PHP 5.3:
     a. New libraries
     b. New extensions
     c. New stream wrappers
     d. New functions
     e. New global constants
     f. New classes
     g. New methods
     h. New class constants

=============================
1. Reserved words and classes
=============================

- **namespace** and **goto** are now reserved keywords.

- **Closure** is now a reserved class. (Used by lambda and closure.)

=====================================
2. Changes made to existing functions
=====================================

- The array functions natsort(), natcasesort(), usort(), uasort(), uksort(),
  array_flip() and array_unique(), no longer accept objects passed as arguments.
  If you need to access their properties using an object, you will need to cast
  the objects to arrays first.

- var_dump() output now includes private object members.

- session_start() now returns FALSE when the session startup fails.

- clearstatcache() no longer clears the realpath cache by default.

- call_user_func() now propagates $this even if the callee is the parent class.

- The filesystem functions opendir(), scandir() and dir() now use the default
  context if no context is passed as an argument to them.

- The behaviour of functions with by-reference parameters called by value has
  changed. Where previously the function would accept the by-value argument, a
  warning is now emitted and all by-ref parameters are set to NULL.

- There is now native support for the following math functions: asinh(), acosh(),
  atanh(), log1p() and expm1().

- In the GD extension, there is now pixelation support available through
  the imagefilter() function.

- crypt() now has Blowfish and extended DES support, and crypt() features are now
  100% portable. PHP has its own internal crypt implementation which drops into
  place when support for crypt or crypt_r() is not found.

- get_cfg_var() is now able to return "array" INI options.

- Stream wrappers can now be used by include_path().

- There are new parameters in:
     clearstatcache(): clear_realpath_cache and filename.
     copy(): context.
     fgetcsv(): escape.
     ini_get_all(): details.
     json_encode(): options.
     nl2br(): is_xhtml.
     parse_ini_file(): scanner_mode.
     round(): mode.
     stream_context_create(): params.
     strstr(), stristr(): before_needle.

- The new mysqlnd library necessitates using MySQL's newer 41 byte password format.
  Continued use of the old 16 byte passwords will cause mysql_connect() to produce
  the following error message: "mysqlnd cannot connect to MySQL 4.1+ using old
  authentication"

===================================
3. Changes made to existing methods
===================================

- The magic methods __get(), __set(), __isset(), __unset() and __call() should
  always be public and can no longer be static. Method signatures are enforced.

- The __toString() magic method can no longer accept arguments.

- There is a new magic method, __callStatic().

- count() vs count_elements() handler resolution rules have changed. (This could
  potentially break custom PHP extensions.)

- The trailing / has been removed from SplFileInfo and other related directory
  classes.

- SplFileInfo::getpathinfo() now returns information about the path name.

- There are new parameters in:
     Exception::__construct(): previous.

===================================
4. Changes made to existing classes
===================================

- SplObjectStorage now has ArrayAccess support. It is also now possible to
  store associative information with objects in SplObjectStorage.

=============
5. Deprecated
=============

- define_syslog_variables() is deprecated.

- All ereg functions are deprecated and emit E_DEPRECATED errors.
  Use PCRE (preg_*()) instead.

- The following ini directives will now emit an E_DEPRECATED warning 
  upon startup if they are activated:

        - define_syslog_variables
        - register_globals
        - register_long_arrays
        - safe_mode
        - magic_quotes_gpc
        - magic_quotes_runtime
        - magic_quotes_sybase

===============
6. Undeprecated
===============

- By popular request, is_a() is no longer marked deprecated.

==============
7. Extensions:
==============

     a. moved out to PECL and actively maintained there

        - fdf
        - ming
        - ncurses

     b. no longer maintained

        - dbase
        - fbsql
        - msql
        - sybase (use sybase_ct, which is still in PHP core)

     c. with changed behaviour

        - datetime: date/timefunctions will no longer use the TZ environment
          variable to guess which timezone should be used.

        - hash: The SHA-224 hash algorithm is now supported.

        - oci8: Calling oci_close() on a persistent connection, or on a variable
          that references a persistent connection going out of scope, will now
          roll back any uncommitted transaction. You should explicitly commit or
          rollback as needed.
          Setting oci8.old_oci_close_semantics=On in php.ini gives the old
          behaviour.

        - openssl: There is now support for OpenSSL digest and cipher functions.
          It is also now possible to access the internal values of DSA, RSA and
          DH keys.

        - session: Sessions will no longer store session-files in "/tmp" where
          open_basedir restrictions apply, unless "/tmp" is explicitly added to
          the list of allowed paths.

     d. no longer possible to disable

        - PCRE
        - Reflection
        - SPL


==========================
8. Changes in SAPI support
==========================

- FastCGI is now always enabled and can not be disabled. See sapi/cgi/CHANGES
  for more details.

- A new CGI SAPI option, -T, can be used to measure execution time of a script
  repeated several times.
 
- CGI/FastCGI now has support for .htaccess style user-defined php.ini files.

============================
9. Changes in INI directives
============================

- zend_extension_debug and zend_extension_ts have been removed.
  Instead use the zend_extension directive to load all Zend Extensions.

- zend.ze1_compatibility_mode has been removed. If this ini directive is set 
  to on, then an E_ERROR is emitted at startup.

- A new user initialization mechanism and config variables have been added:
  user_ini.filename and user_ini.cache_ttl

- There is now support for special sections: [PATH=/opt/httpd/www.example.com/]
  and [HOST=www.example.com]. Directives set in these sections cannot be
  overridden by user-defined INI files or at runtime.

- Added mbstring.http_output_conv_mimetype. This directive specifies the
  regex pattern of content types for which mb_output_handler() is activated.

- It is now possible to use the full path to load modules using the "extension"
  directive.

- "ini-variables" can now be used almost anywhere in a php.ini file.

- It is now possible to use alphanumeric or variable indices in ini option
  arrays.

- Runtime tightening of open_basedir restrictions is now possible.

- The default value of session.use_only_cookies has changed to "1"

====================
10. Syntax additions
====================

- NOWDOC is like HEREDOC but with single quotes:

      <<<'LABEL' ...

  Static HEREDOCs can be used to initialize static variables and class members
  or constants:

      static $foo = <<<LABEL
      No variables here...
      LABEL;

- The ?: operator has been introduced:

      var_dump(0 ?: 'Hello!');

- Namespaces were added:

      namespace my\name;
      $obj = new \my\name\MyClass;

===================
11. Windows support
===================

- The minimum Windows version is now Windows 2000. (Windows 98, ME and NT4 are
  no longer supported).

- PHP Windows binaries target i586 or later. i386 and i486 are not supported.

- Windows support has been added for the following functions: getopt(),
  imagecolorclosesthwb(), mcrypt_create_iv(), inet_ntop(), inet_pton(), 
  getmxrr(), checkdnsrr(), dns_get_record(), linkinfo(), readlink(), 
  symlink(), link(), fnmatch(), stream_socket_pair(), time_nanosleep(), 
  time_sleep_until() and socket_create_pair().

- Improved portability of stat(), touch(), filemtime(), filesize() and related
  functions (100% portable for the available data)

- The PDO_OCI php_pdo_oci8.dll library (for use with Oracle version 8 client
  libraries) is no longer being built. Instead, use php_pdo_oci.dll (note no '8')
  with Oracle 10 or 11 client libraries. Connection to other database versions
  is supported.

- For the OCI8 extension, a new library php_oci8_11g.dll is available in addition to
  php_oci8.dll. Only one can be enabled at any time. Use php_oci8.dll with Oracle 10.2
  client libraries. Use php_oci8_11g.dll with Oracle 11 client libraries. Connection
  to other database versions is supported.

- It's now possible to use hardlinks on Windows using the link() function, 
  and symbolic links via the symlink() function. Hardlinks are available 
  as of Windows 2000 and symbolic links as of Windows Vista.

===================
12. New in PHP 5.3:
===================

     a. New libraries

       - mysqlnd is a new core library shipped with PHP. It is a PHP-specific
         replacement for libmysql.

     b. New extensions

       - fileinfo
       - intl
       - Phar
       - SQLite3

     c. New stream wrappers

       - glob:// stream wrapper
       - phar:// stream wrapper for accessing phar archives

     d. New functions

       - Core:    gc_collect_cycles()
                  gc_enabled()
                  gc_enable()
                  gc_disable()
                  class_alias()
                  get_called_class()
                  forward_static_call()
                  forward_static_call_array()
                  str_getcsv()
                  quoted_printable_encode()
                  lcfirst()
       - Array:   array_replace()
                  array_replace_recursive()
       - Date:    date_add()
                  date_sub()
                  date_diff()
                  date_parse_from_format()
                  date_create_from_format()
                  date_get_last_errors()
                  timezone_version_get()
       - INI:     parse_ini_string()
       - GMP:     gmp_testbit()
       - Hash:    hash_copy()
       - JSON:    json_last_error()
       - libxml:  libxml_disable_entity_loader
       - MySQLi:  mysqli_fetch_all()
                  mysqli_get_connection_stats()
                  mysqli_poll()
                  mysqli_reap_async_query()
       - Network: gethostname()
                  header_remove()
       - OpenSSL: openssl_random_pseudo_bytes()
       - PCNTL:   pcntl_signal_dispatch()
                  pcntl_sigprocmask()
                  pcntl_sigwaitinfo()
                  pcntl_sigtimedwait()
       - PCRE:    preg_filter()
       - SHM:     msg_queue_exists()
       - Streams: stream_supports_lock()
                  stream_context_set_default()

     e. New global constants

       - Core:    E_DEPRECATED
                  E_USER_DEPRECATED
                  __DIR__
                  __NAMESPACE__
                  PHP_WINDOWS_VERSION_MAJOR
                  PHP_WINDOWS_VERSION_MINOR
                  PHP_WINDOWS_VERSION_BUILD
                  PHP_WINDOWS_VERSION_PLATFORM
                  PHP_WINDOWS_VERSION_SP_MAJOR
                  PHP_WINDOWS_VERSION_SP_MINOR
                  PHP_WINDOWS_VERSION_SUITEMASK
                  PHP_WINDOWS_VERSION_PRODUCTTYPE
                  PHP_WINDOWS_NT_DOMAIN_CONTROLLER
                  PHP_WINDOWS_NT_SERVER
                  PHP_WINDOWS_NT_WORKSTATION
       - INI:     INI_SCANNER_NORMAL
                  INI_SCANNER_RAW
       - GD:      IMG_FILTER_PIXELATE
       - JSON:    JSON_ERROR_NONE
                  JSON_ERROR_DEPTH
                  JSON_ERROR_STATE_MISMATCH
                  JSON_ERROR_CTRL_CHAR
                  JSON_ERROR_SYNTAX
                  JSON_FORCE_OBJECT
                  JSON_HEX_TAG
                  JSON_HEX_AMP
                  JSON_HEX_APOS
                  JSON_HEX_QUOT
       - LDAP:    LDAP_OPT_NETWORK_TIMEOUT
       - PCRE:    PREG_BAD_UTF8_OFFSET_ERROR
       - PCNTL:   SIG_BLOCK
                  SIG_UNBLOCK
                  SIG_SETMASK
                  SI_USER
                  SI_NOINFO
                  SI_KERNEL
                  SI_QUEUE
                  SI_TIMER
                  SI_MESGQ
                  SI_ASYNCIO
                  SI_SIGIO
                  SI_TKILL
                  CLD_EXITED
                  CLD_KILLED
                  CLD_DUMPED
                  CLD_TRAPPED
                  CLD_STOPPED
                  CLD_CONTINUED
                  TRAP_BRKPT
                  TRAP_TRACE
                  POLL_IN
                  POLL_OUT
                  POLL_MSG
                  POLL_ERR
                  POLL_PRI
                  POLL_HUP
                  ILL_ILLOPC
                  ILL_ILLOPN
                  ILL_ILLADR
                  ILL_ILLTRP
                  ILL_PRVOPC
                  ILL_PRVREG
                  ILL_COPROC
                  ILL_BADSTK
                  FPE_INTDIV
                  FPE_INTOVF
                  FPE_FLTDIV
                  FPE_FLTOVF
                  FPE_FLTUND
                  FPE_FLTRES
                  FPE_FLTINV
                  FPE_FLTSUB
                  SEGV_MAPERR
                  SEGV_ACCERR
                  BUS_ADRALN
                  BUS_ADRERR
                  BUS_OBJERR

     f. New classes

       - Date:    DateInterval
                  DatePeriod
       - Phar:    Phar
                  PharData
                  PharFileInfo
                  PharException
       - SPL      SplDoublyLinkedList
                  SplStack
                  SplQueue
                  SplHeap
                  SplMinHeap
                  SplMaxHeap
                  SplPriorityQueue
                  SplFixedArray
                  FilesystemIterator
                  GlobIterator
                  RecursiveTreeIterator
                  MultipleIterator

     g. New methods

       - Date:         DateTime::diff()
                       DateTime::add()
                       DateTime::sub()
                       DateTime::createFromFormat()
                       DateTime::getLastErrors()
       - PDO_Firebird: PDO::setAttribute()
       - Reflection:   ReflectionProperty::setAccessible()
                       ReflectionFunction::inNamespace()
                       ReflectionFunction::getNamespaceName()
                       ReflectionFunction::getShortName()
                       ReflectionClass::inNamespace()
                       ReflectionClass::getNamespaceName()
                       ReflectionClass::getShortName()
       - XSL:          XSLTProcessor::setProfiling()

     h. New class constants

       - PDO_Firebird: PDO::FB_ATTR_DATE_FORMAT
                       PDO::FB_ATTR_TIME_FORMAT
                       PDO::FB_ATTR_TIMESTAMP_FORMAT