7a174c47c2a034ac3718cf364cde66569d72b0d7
[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 gost-crypto (CryptoPro S-box) hash algorithm.
93
94 - Stream wrappers verify peer certificates and host names by default in
95   encrypted client streams.
96
97 - Added openssl certificate fingerprint support (inclusive stream context
98   option).
99
100 - Added support for SAN x509 extension matching when verifing host names in
101   encrypted streams.
102
103 - Added a range of new SSL context options for improved encrypted stream
104   server security (https://wiki.php.net/rfc/improved-tls-defaults):
105
106     . "honor_cipher_order" allows servers to prioritize cipher suites of their
107       choosing when negotiating SSL/TLS handshakes.
108     . "single_ecdh_use" and "single_dh_use" allow for improved forward
109       secrecy in encrypted stream servers.
110     . "dh_param" allows specification of pre-generated key generation
111        parameters when negotiating ephemeral DHE ciphers in stream servers.
112     . "ecdh_curve" allows stream servers to specify which curve to use when
113        negotiating ephemeral ECDHE ciphers (defaults to NIST P-256).
114     . "rsa_key_size" SSL context option gives stream servers control
115       over the key size (in bits) used when negotiating RSA ciphers.
116     . "capture_session_meta" if specified stores an array of data describing
117       the TLS session's protocol/cipher in the "session_meta" SSL context key.
118
119 - Added automatic mitigation against client-initated TLS renegotiation DoS
120   attacks in encrypted server streams. Renegotiation limiting may be
121   customized via three new SSL context options:
122
123     . "reneg_limit" (number of allowed renegotiations per time window)
124     . "reneg_window" (renegotiation time window in seconds)
125     . "reneg_limit_callback" (optional notification callback on limiting)
126
127 - Encrypted TLS servers now support the server name indication (SNI) TLS
128   extension via the new "SNI_server_certs" SSL context option.
129
130 - Added "crypto_method" SSL context option for use in encrypted streams.
131
132 - Added "peer_name" SSL context option to better reflect peer certificate
133   name matching using SAN extension (replaces deprecated "CN_match").
134
135 - Added stream wrapper support when specifying "cafile" SSL context paths.
136
137 - Independent peer cert and peer name validation is now available via a new
138   boolean "verify_peer_name" SSL context option. This option is enabled by
139   default in encrypted client streams.
140
141 - Added protocol-specific tlsv1.0://, tlsv1.1:// and tlsv1.2:// encryption
142   stream wrappers. tls:// wrapper now supports TLSv1.1 and TLSv1.2 (previously
143   only supported TLSv1).
144
145 - Stream crypto method specification now accepts flags instead of values
146   allowing support for multiple discrete protocols in a given stream.
147
148 - PostgreSQL database connections may now be established asynchronously using
149   new constants and polling functions in ext/pgsql.
150
151 - Non-blocking read/write query behavior now optionally available in database
152   operations using the ext/pgsql extension.
153
154 ========================================
155 3. Changes in SAPI modules
156 ========================================
157
158 - Added phpdbg SAPI.
159   (https://wiki.php.net/rfc/phpdbg)
160
161 - Support for FPM workers changing the apparmor profile through the pool configuration.
162   (https://wiki.php.net/rfc/fpm_change_hat)
163
164 - Support for several XML MIME types in the built-in CLI server. For static
165   files with extensions .xml, .xsl, .xsd the Content-Type header
166   application/xml is now sent automatically.
167
168 ========================================
169 4. Deprecated Functionality
170 ========================================
171
172 - Incompatible context calls:
173   Instance calls from an incompatible context are now deprecated and issue
174   E_DEPRECATED instead of E_STRICT. See https://wiki.php.net/rfc/incompat_ctx
175
176 - The "CN_match" and "SNI_server_name" SSL context options are deprecated in
177   favor of the new "peer_name" option. Name verification now checks certificate
178   SAN names as well as the CN field and the specific name fields are deprecated
179   to avoid confusion. Their use triggers E_DEPRECATED but continues to work as
180   before. If specified, the specific values take precedence over the general
181   "peer_name" value.
182
183 - Deprecated PDO::PGSQL_ATTR_DISABLE_NATIVE_PREPARED_STATEMENT, an
184   undocument constant effectively equivalent to PDO::ATTR_EMULATE_PREPARES.
185
186 - Deprecated INIs: Following INIs are deprecated in favour of new
187   internal_encoding/input_encoding/output_encoding. Refer to "Changes to
188   encodings in PHP 5.6" in "11. Other Changes" section for more details.
189
190     iconv.input_encoding
191     iconv.output_encoding
192     iconv.internal_encoding
193     mbstring.http_input
194     mbstring.http_output
195     mbstring.internal_encoding
196
197 ========================================
198 5. Changed Functions
199 ========================================
200
201 - cURL:
202   CURLOPT_SAFE_UPLOAD is now turned on by default and uploads with @file 
203   do not work unless it is explicitly set to false.
204
205   curl_setopt() now supports the following nullable settings (>= 5.5.11): 
206     . CURLOPT_CUSTOMREQUEST
207     . CURLOPT_FTPPORT
208     . CURLOPT_RANGE
209     . CURLOPT_FTP_ACCOUNT
210     . CURLOPT_RTSP_SESSION_ID
211     . CURLOPT_KRBLEVEL
212     . CURLOPT_KRB4LEVEL
213
214 - Strings:
215   substr_compare() now allows $length to be zero.
216
217 - Crypt:
218   crypt() will now raise an E_NOTICE error if the salt parameter is omitted.
219   See: https://wiki.php.net/rfc/crypt_function_salt
220
221 - Mcrypt:
222   The $source parameter of mcrypt_create_iv() now defaults to
223   MCRYPT_DEV_URANDOM instead of MCRYPT_DEV_RANDOM.
224
225 - OpenSSL:
226   The $crypto_type parameter is now optional in stream_socket_enable_crypto()
227   if the stream's SSL context specifies the new "crypto_type" option. The
228   crypto method from the context is used as a fallback if no crypto method is
229   specified at call-time.
230
231 - XMLReader:
232   XMLReader::getAttributeNs and XMLReader::getAttributeNo now return NULL if
233   the attribute could not be found, just like XMLReader::getAttribute.
234
235 - Pgsql:
236   pg_insert()/pg_select()/pg_update()/pg_delete() are no longer EXPERIMENTAL.
237   The following functions no longer block until query write completion if the
238   socket stream underlying a database connection is set to non-blocking mode:
239     . pg_send_execute()
240     . pg_send_prepare()
241     . pg_send_query()
242     . pg_send_query_params()
243
244 - unserialize:
245   Manipulated serialization strings for objects implementing Serializable by
246   replacing "C:" with "O:" at the start will now produce an error.
247
248 ========================================
249 6. New Functions
250 ========================================
251
252 - GMP:
253   Added gmp_root($a, $nth) and gmp_rootrem($a, $nth) for calculating nth roots.
254
255 - Hash
256   Added hash_equals($known_string, $user_string)
257
258 - OpenSSL:
259   Added string openssl_x509_fingerprint($x509, $type, $binary).
260   Added string openssl_spki_new($private_key, $challenge, $algorithm)
261   Added bool openssl_spki_verify($spkac)
262   Added string openssl_spki_export($spkac)
263   Added string openssl_spki_export_challenge($spkac)
264   Added array openssl_get_cert_locations()
265
266 - LDAP:
267   Added ldap_escape($value, $ignore = "", $flags = 0).
268   Added ldap_modify_batch($link_identifier, $dn, $modifications) described in 
269   https://wiki.php.net/rfc/ldap_modify_batch.
270
271 - Pgsql:
272   Added pg_socket($connection) to allow async connections and non-blocking IO
273   Added pg_connect_poll($connection) for establishing async connections
274   Added pg_consume_input($connection) for non-blocking query result consumption
275   Added pg_flush($connection) for non-blocking query write completion
276
277 - PDO_pgsql
278   Added PDO::pgsqlGetNotify($result_type = PDO::FETCH_USE_DEFAULT, $ms_timeout = 0)
279   Added PDO::pgsqlGetPid()
280
281 - Zip:
282   Added ZipArchive::setPassword($password)
283
284 - SPL
285   Added SplFileObject::fread($length) to complement fwrite() method (>= 5.5.11)
286
287 ========================================
288 7. New Classes and Interfaces
289 ========================================
290
291
292 ========================================
293 8. Removed Extensions
294 ========================================
295
296
297 ========================================
298 9. Other Changes to Extensions
299 ========================================
300
301 - cURL:
302   - The following constants have been removed as they are now marked "obsolete"
303     in the underlying library and never had any effect to begin with:
304       . CURLOPT_CLOSEPOLICY
305       . CURLCLOSEPOLICY_CALLBACK
306       . CURLCLOSEPOLICY_LEAST_RECENTLY_USED
307       . CURLCLOSEPOLICY_LEAST_TRAFFIC
308       . CURLCLOSEPOLICY_OLDEST
309       . CURLCLOSEPOLICY_SLOWEST
310
311 - GMP:
312   The GMP extension now uses objects as the underlying data structure, rather
313   than resources. GMP instances now support dumping, serialization, cloning,
314   casts to primitive types and have overloaded operators.
315   (RFC: https://wiki.php.net/rfc/operator_overloading_gmp)
316
317 - OCI8:
318   - Added Implicit Result Set support for Oracle Database 12c with a
319     new oci_get_implicit_resultset() function.
320   - Using 'oci_execute($s, OCI_NO_AUTO_COMMIT)' for a SELECT no longer
321     unnecessarily initiates an internal ROLLBACK during connection
322     close.
323   - Multi-row OCI_RETURN_LOB queries require fewer "round trips" to the database.
324   - Added DTrace probes enabled with PHP's generic --enable-dtrace
325   - The oci_internal_debug() function is now a no-op.
326   - The phpinfo() output format for OCI8 has changed.
327
328 - OpenSSL:
329   - The "SNI_enabled" SSL stream context option is now set to TRUE by default
330     if supported by the underlying openssl library.
331
332 - PCRE:
333   - The information collected by the (*MARK) backtracking control verb is now
334     collected into the "MARK" index of the $matches array for preg_match(),
335     preg_match_all() and preg_replace_callback().
336
337 - Pgsql:
338   - pg_insert()/pg_select()/pg_update()/pg_delete()/pg_meta_data()/pg_convert()
339     are no longer EXPERIMENTAL
340   - Added PGSQL_DML_ESCAPE option for pg_insert()/pg_select()/pg_update()/pg_delete()
341     that simply escapes all supplied parameters. These functions can be as fast as
342     native query. Unvalidated data(Unknown data types) is passed as string.
343     JSON/Array/etc are supported both PGSQL_DML_ESCAPE and pg_convert() as string.
344   - pg_select() returns PostgreSQL query resource when query is executed.
345   - Added extended flag parameter for pg_meta_data(). pg_meta_data() always
346     returns "is enum" attribute.
347   - The new pg_socket() function returns a socket stream with no behavior other
348     than to allow IO-readiness polling on a DB connection socket. Calling
349     stream_set_blocking() on its result enables non-blocking behavior.
350   - Passing the new PGSQL_CONNECT_ASYNC flag to pg_connect() allows applications
351     to poll for IO readiness via pg_connect_poll() and establish connections
352     asynchronously.
353
354 - PDO_pgsql:
355   - Added PDO::PGSQL_ATTR_DISABLE_PREPARES constant to execute the queries
356     without preparing them, while still passing parameters separately from
357     the command text using PQexecParams.
358   - Added LISTEN/NOTIFY support via PDO::pgsqlGetNotify / PDO::pgsqlGetPid()
359     as described in https://bugs.php.net/bug.php?id=42614.
360
361 ========================================
362 10. New Global Constants
363 ========================================
364
365 - LDAP:
366   LDAP_ESCAPE_FILTER int(1)
367   LDAP_ESCAPE_DN     int(2)
368
369 - Pgsql:
370   PGSQL_DML_ESCAPE   int(4096)
371   PGSQL_CONNECT_ASYNC
372   PGSQL_CONNECTION_STARTED
373   PGSQL_CONNECTION_MADE
374   PGSQL_CONNECTION_AWAITING_RESPONSE
375   PGSQL_CONNECTION_AUTH_OK
376   PGSQL_CONNECTION_SSL_STARTUP
377   PGSQL_CONNECTION_SETENV
378   PGSQL_POLLING_FAILED
379   PGSQL_POLLING_READING
380   PGSQL_POLLING_WRITING
381   PGSQL_POLLING_OK
382   PGSQL_POLLING_ACTIVE
383
384 - OpenSSL:
385   STREAM_CRYPTO_METHOD_TLSv1_0_CLIENT   int(9)
386   STREAM_CRYPTO_METHOD_TLSv1_1_CLIENT   int(17)
387   STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT   int(33)
388   STREAM_CRYPTO_METHOD_ANY_CLIENT       int(63)
389   STREAM_CRYPTO_METHOD_TLSv1_0_SERVER   int(8)
390   STREAM_CRYPTO_METHOD_TLSv1_1_SERVER   int(16)
391   STREAM_CRYPTO_METHOD_TLSv1_2_SERVER   int(32)
392   STREAM_CRYPTO_METHOD_ANY_SERVER       int(62)
393   OPENSSL_DEFAULT_STREAM_CIPHERS        string
394
395 ========================================
396 11. Changes to INI File Handling
397 ========================================
398
399 - Core:
400   Changed always_populate_raw_post_data to throw a deprecation warning when
401   enabled and to recognize the value -1 for never populating the global 
402   $HTTP_RAW_POST_DATA variable, which will be default in future PHP versions.
403
404   default_charset is set to UTF-8. It was empty previously. default_charset
405   is used where it is applicable. Iconv/Mbstring/htmlentities/htmlspecialchars/
406   html_entity_decode use default_charset as default encoding.
407
408   internal_encoding/input_encoding/output_encoding is added for encoding
409   handling modules. Refer to "Changes to encodings in PHP 5.6" in "11. Other Changes"
410   section for more details.
411
412 - cURL:
413   If the new openssl.cafile ini directive is specified ext/curl will give the
414   openssl path precedence over its own curl.cainfo directive.
415
416 - OpenSSL:
417   openssl.cafile and openssl.capath ini directives have been added to allow
418   global CA default specification as necessary.
419
420 ========================================
421 12. Other Changes
422 ========================================
423
424 - File upload:
425   Uploads equal or greater than 2GB in size are now accepted.
426
427 - HTTP stream wrapper:
428   HTTP 1.1 requests now include a Connection: close header unless explicitly
429   overridden by setting a Connection header via the header context option.
430
431 - PDO_pgsql
432   A libpq version providing PQexecParams, PQprepare, PQescapeStringConn,
433   PQescapeByteaConn is now required. According to the release notes that means
434   8.0.8+ or 8.1.4+. 
435
436 - Zip:
437   New --with-libzip option allow to use system libzip. Version > 0.11 required,
438   Version >= 0.11.2 recommended for all features.
439
440 - Changes to encodings in PHP 5.6
441   The default value of default_charset is now UTF-8 when it is not
442   explicitly set in php.ini
443
444   The following php.ini parameters were added:
445     internal_encoding
446     input_encoding
447     output_encoding
448
449   The values of the following php.ini parameters have become empty in
450   PHP 5.6 (previously they were all ISO-8859-1)
451
452     iconv.input_encoding
453     iconv.output_encoding
454     iconv.internal_encoding
455
456   Changes were made to character set handling in:
457    - the iconv and mbstring extensions,
458    - and htmlentities(), htmlspecialchars(), html_entity_decode() functions
459
460   The precedence for these is now:
461
462    default_charset < internal/input/output_encoding < (mbstring.* || iconv.*) < function parameter
463
464   For example, the easiest way to use the UTF-8 encoding is to set
465   default_charset=UTF-8 and leave the following php.ini parameters
466
467   empty:
468
469     iconv.input_encoding
470     iconv.output_encoding
471     iconv.internal_encoding
472     mbstring.http_input
473     mbstring.http_output
474     mbstring.internal_encoding
475     internal_encoding
476     input_encoding
477     output_encoding
478
479   The mb_regex_encoding() default setting is changed from EUC-JP to UTF-8.
480