9428add450971fec8038eeb3386c95b404ae1ec9
[pkg-php/php.git] / UPGRADING
1 $Id$
2
3 PHP 5.6 UPGRADE NOTES
4
5 1. Backward Incompatible Changes
6 2. New Features
7 3. Changes in SAPI modules
8 4. Deprecated Functionality
9 5. Changed Functions
10 6. New Functions
11 7. New Classes and Interfaces
12 8. Removed Extensions
13 9. Other Changes to Extensions
14 10. New Global Constants
15 11. Changes to INI File Handling
16 12. Other Changes
17
18
19 ========================================
20 1. Backward Incompatible Changes
21 ========================================
22
23 - Core:
24   By fixing bug #66015 it is no longer possible to overwrite keys in static scalar
25   arrays. Quick example to illustrate:
26   class Test {
27        const FIRST = 1;
28        public $array = array(
29            self::FIRST => 'first',
30            'second',
31            'third'
32        );
33   }
34   Test::$array will have as expected three array keys (1, 2, 3) and no longer
35   two (0, 1). self::FIRST will no longer overwrite 'third' having key 1 then,
36   but will mark the beginning of indexing. 
37
38 - JSON:
39   json_decode() no longer accepts non-lowercase variants of lone JSON true,
40   false or null values. For example, True or FALSE will now cause json_decode to
41   return NULL and set an error value you can fetch with json_last_error().
42   This affects JSON texts consisting solely of true, false or null. Text
43   containing non-lowercase values inside JSON arrays or objects has never been
44   accepted.
45
46 - OpenSSL:
47   To prevent man-in-the-middle attacks against encrypted transfers client
48   streams now verify peer certificates by default. Previous versions
49   required users to manually enable peer verification. As a result of this
50   change, existing code using ssl:// or tls:// stream wrappers (e.g.
51   file_get_contents(), fsockopen(), stream_socket_client()) may no longer
52   connect successfully without manually disabling peer verification via the
53   stream context's "verify_peer" setting. Encrypted transfers delegate to
54   operating system certificate stores by default if not overridden via the
55   new openssl.cafile and openssl.cafile ini directives or via call-time SSL
56   context options, so most users should be unaffected by this transparent
57   security enhancement. (https://wiki.php.net/rfc/tls-peer-verification)
58
59 - Mcrypt:
60   The mcrypt_encrypt(), mcrypt_decrypt() and mcrypt_{MODE}() functions no
61   longer accept keys or IVs with incorrect sizes. Furthermore an IV is now
62   required if the used block cipher mode requires it.
63
64 ========================================
65 2. New Features
66 ========================================
67
68 - Added constant scalar expressions syntax.
69   (https://wiki.php.net/rfc/const_scalar_exprs)
70
71 - Added dedicated syntax for variadic functions.
72   (https://wiki.php.net/rfc/variadics)
73
74 - Added support for argument unpacking to complement the variadic syntax.
75   (https://wiki.php.net/rfc/argument_unpacking)
76
77 - Added an exponentiation operator (**).
78   (https://wiki.php.net/rfc/pow-operator)
79
80 - Added unified default encoding. default_charset=UTF-8 and functions/extensions
81   use encoding settings honor default_charset.
82
83 - The php://input stream is now re-usable and can be used concurrently with
84   enable_post_data_reading=0.
85
86 - Added use function and use const.
87   (https://wiki.php.net/rfc/use_function)
88
89 - Added a function for timing attack safe string comparison
90   (https://wiki.php.net/rfc/timing_attack)
91
92 - Added the __debugInfo() magic method to allow userland classes to implement
93   the get_debug_info API previously available only to extensions.
94   (https://wiki.php.net/rfc/debug-info)
95
96 - Added gost-crypto (CryptoPro S-box) hash algorithm.
97
98 - Stream wrappers verify peer certificates and host names by default in
99   encrypted client streams.
100
101 - Added openssl certificate fingerprint support (inclusive stream context
102   option).
103
104 - Added support for SAN x509 extension matching when verifing host names in
105   encrypted streams.
106
107 - Added a range of new SSL context options for improved encrypted stream
108   server security (https://wiki.php.net/rfc/improved-tls-defaults):
109
110     . "honor_cipher_order" allows servers to prioritize cipher suites of their
111       choosing when negotiating SSL/TLS handshakes.
112     . "single_ecdh_use" and "single_dh_use" allow for improved forward
113       secrecy in encrypted stream servers.
114     . "dh_param" allows specification of pre-generated key generation
115        parameters when negotiating ephemeral DHE ciphers in stream servers.
116     . "ecdh_curve" allows stream servers to specify which curve to use when
117        negotiating ephemeral ECDHE ciphers (defaults to NIST P-256).
118     . "rsa_key_size" SSL context option gives stream servers control
119       over the key size (in bits) used when negotiating RSA ciphers.
120     . "capture_session_meta" if specified stores an array of data describing
121       the TLS session's protocol/cipher in the "session_meta" SSL context key.
122
123 - Added automatic mitigation against client-initated TLS renegotiation DoS
124   attacks in encrypted server streams. Renegotiation limiting may be
125   customized via three new SSL context options:
126
127     . "reneg_limit" (number of allowed renegotiations per time window)
128     . "reneg_window" (renegotiation time window in seconds)
129     . "reneg_limit_callback" (optional notification callback on limiting)
130
131 - Encrypted TLS servers now support the server name indication (SNI) TLS
132   extension via the new "SNI_server_certs" SSL context option.
133
134 - Added "crypto_method" SSL context option for use in encrypted streams.
135
136 - Added "peer_name" SSL context option to better reflect peer certificate
137   name matching using SAN extension (replaces deprecated "CN_match").
138
139 - Added stream wrapper support when specifying "cafile" SSL context paths.
140
141 - Independent peer cert and peer name validation is now available via a new
142   boolean "verify_peer_name" SSL context option. This option is enabled by
143   default in encrypted client streams.
144
145 - Added protocol-specific tlsv1.0://, tlsv1.1:// and tlsv1.2:// encryption
146   stream wrappers. tls:// wrapper now supports TLSv1.1 and TLSv1.2 (previously
147   only supported TLSv1).
148
149 - Stream crypto method specification now accepts flags instead of values
150   allowing support for multiple discrete protocols in a given stream.
151
152 - PostgreSQL database connections may now be established asynchronously using
153   new constants and polling functions in ext/pgsql.
154
155 - Non-blocking read/write query behavior now optionally available in database
156   operations using the ext/pgsql extension.
157
158 ========================================
159 3. Changes in SAPI modules
160 ========================================
161
162 - Added phpdbg SAPI.
163   (https://wiki.php.net/rfc/phpdbg)
164
165 - Support for FPM workers changing the apparmor profile through the pool configuration.
166   (https://wiki.php.net/rfc/fpm_change_hat)
167
168 - Support for several XML MIME types in the built-in CLI server. For static
169   files with extensions .xml, .xsl, .xsd the Content-Type header
170   application/xml is now sent automatically.
171
172 ========================================
173 4. Deprecated Functionality
174 ========================================
175
176 - Incompatible context calls:
177   Instance calls from an incompatible context are now deprecated and issue
178   E_DEPRECATED instead of E_STRICT. See https://wiki.php.net/rfc/incompat_ctx
179
180 - The "CN_match" and "SNI_server_name" SSL context options are deprecated in
181   favor of the new "peer_name" option. Name verification now checks certificate
182   SAN names as well as the CN field and the specific name fields are deprecated
183   to avoid confusion. Their use triggers E_DEPRECATED but continues to work as
184   before. If specified, the specific values take precedence over the general
185   "peer_name" value.
186
187 - Deprecated PDO::PGSQL_ATTR_DISABLE_NATIVE_PREPARED_STATEMENT, an
188   undocument constant effectively equivalent to PDO::ATTR_EMULATE_PREPARES.
189
190 - Deprecated INIs: Following INIs are deprecated in favour of new
191   internal_encoding/input_encoding/output_encoding. Refer to "Changes to
192   encodings in PHP 5.6" in "11. Other Changes" section for more details.
193
194     iconv.input_encoding
195     iconv.output_encoding
196     iconv.internal_encoding
197     mbstring.http_input
198     mbstring.http_output
199     mbstring.internal_encoding
200
201 ========================================
202 5. Changed Functions
203 ========================================
204
205 - cURL:
206   CURLOPT_SAFE_UPLOAD is now turned on by default and uploads with @file 
207   do not work unless it is explicitly set to false.
208
209   curl_setopt() now supports the following nullable settings (>= 5.5.11): 
210     . CURLOPT_CUSTOMREQUEST
211     . CURLOPT_FTPPORT
212     . CURLOPT_RANGE
213     . CURLOPT_FTP_ACCOUNT
214     . CURLOPT_RTSP_SESSION_ID
215     . CURLOPT_KRBLEVEL
216     . CURLOPT_KRB4LEVEL
217
218 - Strings:
219   substr_compare() now allows $length to be zero.
220   pack() and unpack() now support 64-bit format specifiers: q, Q, J and P.
221
222 - Crypt:
223   crypt() will now raise an E_NOTICE error if the salt parameter is omitted.
224   See: https://wiki.php.net/rfc/crypt_function_salt
225
226 - Mcrypt:
227   The $source parameter of mcrypt_create_iv() now defaults to
228   MCRYPT_DEV_URANDOM instead of MCRYPT_DEV_RANDOM.
229
230 - OpenSSL:
231   The $crypto_type parameter is now optional in stream_socket_enable_crypto()
232   if the stream's SSL context specifies the new "crypto_type" option. The
233   crypto method from the context is used as a fallback if no crypto method is
234   specified at call-time.
235
236 - Reflection:
237   ReflectionClass::newInstanceWithoutConstructor previously didn't allow the
238   instantiation of any internal class which used custom object storage
239   (overriding the default create_object handler), this was changed to only
240   reject the instantiation of such classes if the class is also marked as
241   final.
242
243 - XMLReader:
244   XMLReader::getAttributeNs and XMLReader::getAttributeNo now return NULL if
245   the attribute could not be found, just like XMLReader::getAttribute.
246
247 - Pgsql:
248   pg_insert()/pg_select()/pg_update()/pg_delete() are no longer EXPERIMENTAL.
249   The following functions no longer block until query write completion if the
250   socket stream underlying a database connection is set to non-blocking mode:
251     . pg_send_execute()
252     . pg_send_prepare()
253     . pg_send_query()
254     . pg_send_query_params()
255
256 - unserialize:
257   Manipulated serialization strings for objects implementing Serializable by
258   replacing "C:" with "O:" at the start will now produce an error.
259
260 - parse_ini_file():
261 - parse_ini_string():
262   Added scanner mode INI_SCANNER_TYPED to yield typed .ini values. 
263   For PHP >= 5.6.1
264
265 - JSON:
266   Added JSON_PRESERVE_ZERO_FRACTION option (PHP >= 5.6.5)
267
268 ========================================
269 6. New Functions
270 ========================================
271
272 - Datetime:
273   Added DatePeriod::getStartDate(), DatePeriod::getEndDate(), DatePeriod::getDateInterval() in 5.6.5.
274
275 - GMP:
276   Added gmp_root($a, $nth) and gmp_rootrem($a, $nth) for calculating nth roots.
277   Added gmp_import($data, $word_size = 1, $options = GMP_MSW_FIRST | GMP_NATIVE_ENDIAN) in PHP 5.6.1.
278   Added gmp_export($gmpnumber, $word_size = 1, $options = GMP_MSW_FIRST | GMP_NATIVE_ENDIAN) in PHP 5.6.1.
279   Added gmp_random_range() and gmp_random_bits() in PHP 5.6.3.
280
281 - Hash
282   Added hash_equals($known_string, $user_string)
283
284 - OpenSSL:
285   Added string openssl_x509_fingerprint($x509, $type, $binary).
286   Added string openssl_spki_new($private_key, $challenge, $algorithm)
287   Added bool openssl_spki_verify($spkac)
288   Added string openssl_spki_export($spkac)
289   Added string openssl_spki_export_challenge($spkac)
290   Added array openssl_get_cert_locations()
291
292 - LDAP:
293   Added ldap_escape($value, $ignore = "", $flags = 0).
294   Added ldap_modify_batch($link_identifier, $dn, $modifications) described in 
295   https://wiki.php.net/rfc/ldap_modify_batch.
296
297 - Pgsql:
298   Added pg_socket($connection) to allow async connections and non-blocking IO
299   Added pg_connect_poll($connection) for establishing async connections
300   Added pg_consume_input($connection) for non-blocking query result consumption
301   Added pg_flush($connection) for non-blocking query write completion
302
303 - PDO_pgsql
304   Added PDO::pgsqlGetNotify($result_type = PDO::FETCH_USE_DEFAULT, $ms_timeout = 0)
305   Added PDO::pgsqlGetPid()
306
307 - Reflection
308   Added ReflectionFunction::isVariadic() and ReflectionParameter::isVariadic().
309
310 - SPL
311   Added SplFileObject::fread($length) to complement fwrite() method (>= 5.5.11)
312
313 - Zip:
314   Added ZipArchive::setPassword($password)
315
316 ========================================
317 7. New Classes and Interfaces
318 ========================================
319
320
321 ========================================
322 8. Removed Extensions
323 ========================================
324
325
326 ========================================
327 9. Other Changes to Extensions
328 ========================================
329
330 - cURL:
331   - The following constants have been removed as they are now marked "obsolete"
332     in the underlying library and never had any effect to begin with:
333       . CURLOPT_CLOSEPOLICY
334       . CURLCLOSEPOLICY_CALLBACK
335       . CURLCLOSEPOLICY_LEAST_RECENTLY_USED
336       . CURLCLOSEPOLICY_LEAST_TRAFFIC
337       . CURLCLOSEPOLICY_OLDEST
338       . CURLCLOSEPOLICY_SLOWEST
339
340 - GMP:
341   The GMP extension now uses objects as the underlying data structure, rather
342   than resources. GMP instances now support dumping, serialization, cloning,
343   casts to primitive types and have overloaded operators.
344   (RFC: https://wiki.php.net/rfc/operator_overloading_gmp)
345
346 - OCI8:
347   - Added Implicit Result Set support for Oracle Database 12c with a
348     new oci_get_implicit_resultset() function.
349   - Using 'oci_execute($s, OCI_NO_AUTO_COMMIT)' for a SELECT no longer
350     unnecessarily initiates an internal ROLLBACK during connection
351     close.
352   - Multi-row OCI_RETURN_LOB queries require fewer "round trips" to the database.
353   - Added DTrace probes enabled with PHP's generic --enable-dtrace
354   - The oci_internal_debug() function is now a no-op.
355   - The phpinfo() output format for OCI8 has changed.
356
357 - OpenSSL:
358   - The "SNI_enabled" SSL stream context option is now set to TRUE by default
359     if supported by the underlying openssl library.
360
361 - PCRE:
362   - The information collected by the (*MARK) backtracking control verb is now
363     collected into the "MARK" index of the $matches array for preg_match(),
364     preg_match_all() and preg_replace_callback().
365
366 - Pgsql:
367   - pg_insert()/pg_select()/pg_update()/pg_delete()/pg_meta_data()/pg_convert()
368     are no longer EXPERIMENTAL
369   - Added PGSQL_DML_ESCAPE option for pg_insert()/pg_select()/pg_update()/pg_delete()
370     that simply escapes all supplied parameters. These functions can be as fast as
371     native query. Unvalidated data(Unknown data types) is passed as string.
372     JSON/Array/etc are supported both PGSQL_DML_ESCAPE and pg_convert() as string.
373   - pg_select() returns PostgreSQL query resource when query is executed.
374   - Added extended flag parameter for pg_meta_data(). pg_meta_data() always
375     returns "is enum" attribute.
376   - The new pg_socket() function returns a socket stream with no behavior other
377     than to allow IO-readiness polling on a DB connection socket. Calling
378     stream_set_blocking() on its result enables non-blocking behavior.
379   - Passing the new PGSQL_CONNECT_ASYNC flag to pg_connect() allows applications
380     to poll for IO readiness via pg_connect_poll() and establish connections
381     asynchronously.
382
383 - PDO_pgsql:
384   - Added PDO::PGSQL_ATTR_DISABLE_PREPARES constant to execute the queries
385     without preparing them, while still passing parameters separately from
386     the command text using PQexecParams.
387   - Added LISTEN/NOTIFY support via PDO::pgsqlGetNotify / PDO::pgsqlGetPid()
388     as described in https://bugs.php.net/bug.php?id=42614.
389
390 - DOM:
391   - DOMNode::textContent is now a writeable property. (>= 5.6.1)
392
393 ========================================
394 10. New Global Constants
395 ========================================
396
397 - LDAP:
398   LDAP_ESCAPE_FILTER int(1)
399   LDAP_ESCAPE_DN     int(2)
400
401 - Pgsql:
402   PGSQL_DML_ESCAPE   int(4096)
403   PGSQL_CONNECT_ASYNC
404   PGSQL_CONNECTION_STARTED
405   PGSQL_CONNECTION_MADE
406   PGSQL_CONNECTION_AWAITING_RESPONSE
407   PGSQL_CONNECTION_AUTH_OK
408   PGSQL_CONNECTION_SSL_STARTUP
409   PGSQL_CONNECTION_SETENV
410   PGSQL_POLLING_FAILED
411   PGSQL_POLLING_READING
412   PGSQL_POLLING_WRITING
413   PGSQL_POLLING_OK
414   PGSQL_POLLING_ACTIVE
415
416 - OpenSSL:
417   STREAM_CRYPTO_METHOD_TLSv1_0_CLIENT   int(9)
418   STREAM_CRYPTO_METHOD_TLSv1_1_CLIENT   int(17)
419   STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT   int(33)
420   STREAM_CRYPTO_METHOD_ANY_CLIENT       int(63)
421   STREAM_CRYPTO_METHOD_TLSv1_0_SERVER   int(8)
422   STREAM_CRYPTO_METHOD_TLSv1_1_SERVER   int(16)
423   STREAM_CRYPTO_METHOD_TLSv1_2_SERVER   int(32)
424   STREAM_CRYPTO_METHOD_ANY_SERVER       int(62)
425   OPENSSL_DEFAULT_STREAM_CIPHERS        string
426
427 ========================================
428 11. Changes to INI File Handling
429 ========================================
430
431 - Core:
432   Changed always_populate_raw_post_data to throw a deprecation warning when
433   enabled and to recognize the value -1 for never populating the global 
434   $HTTP_RAW_POST_DATA variable, which will be default in future PHP versions.
435
436   default_charset is set to UTF-8. It was empty previously. default_charset
437   is used where it is applicable. Iconv/Mbstring/htmlentities/htmlspecialchars/
438   html_entity_decode use default_charset as default encoding.
439
440   internal_encoding/input_encoding/output_encoding is added for encoding
441   handling modules. Refer to "Changes to encodings in PHP 5.6" in "11. Other Changes"
442   section for more details.
443
444 - cURL:
445   If the new openssl.cafile ini directive is specified ext/curl will give the
446   openssl path precedence over its own curl.cainfo directive.
447
448 - OpenSSL:
449   openssl.cafile and openssl.capath ini directives have been added to allow
450   global CA default specification as necessary.
451
452 ========================================
453 12. Other Changes
454 ========================================
455
456 - File upload:
457   Uploads equal or greater than 2GB in size are now accepted.
458
459 - HTTP stream wrapper:
460   HTTP 1.1 requests now include a Connection: close header unless explicitly
461   overridden by setting a Connection header via the header context option.
462
463 - PDO_pgsql
464   A libpq version providing PQexecParams, PQprepare, PQescapeStringConn,
465   PQescapeByteaConn is now required. According to the release notes that means
466   8.0.8+ or 8.1.4+. 
467
468 - Zip:
469   New --with-libzip option allow to use system libzip. Version > 0.11 required,
470   Version >= 0.11.2 recommended for all features.
471
472 - Changes to encodings in PHP 5.6
473   The default value of default_charset is now UTF-8 when it is not
474   explicitly set in php.ini
475
476   The following php.ini parameters were added:
477     internal_encoding
478     input_encoding
479     output_encoding
480
481   The values of the following php.ini parameters have become empty in
482   PHP 5.6 (previously they were all ISO-8859-1)
483
484     iconv.input_encoding
485     iconv.output_encoding
486     iconv.internal_encoding
487
488   Changes were made to character set handling in:
489    - the iconv and mbstring extensions,
490    - and htmlentities(), htmlspecialchars(), html_entity_decode() functions
491
492   The precedence for these is now:
493
494    default_charset < internal/input/output_encoding < (mbstring.* || iconv.*) < function parameter
495
496   For example, the easiest way to use the UTF-8 encoding is to set
497   default_charset=UTF-8 and leave the following php.ini parameters
498
499   empty:
500
501     iconv.input_encoding
502     iconv.output_encoding
503     iconv.internal_encoding
504     mbstring.http_input
505     mbstring.http_output
506     mbstring.internal_encoding
507     internal_encoding
508     input_encoding
509     output_encoding
510
511   The mb_regex_encoding() default setting is changed from EUC-JP to UTF-8.
512