<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 332730 $ -->
<!--
 Based on UPGRADING from PHP-5.6 circa alpha 1. Work in progress!

 As we're still in alpha at the moment, I've only included relatively minimal
 information here, and haven't updated the rest of the manual for 5.6 features
 yet. Once we're well into betas/RCs and features are frozen, the information
 in this appendix should be expanded and the new functionality integrated into
 the rest of the manual.
-->

<appendix xml:id="migration56" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Migrating from PHP 5.5.x to PHP 5.6.x</title>
 <simpara>
  &manual.migration.seealso;
  <link linkend="migration5">5.0.x</link>,
  <link linkend="migration51">5.1.x</link>,
  <link linkend="migration52">5.2.x</link>,
  <link linkend="migration53">5.3.x</link>,
  <link linkend="migration54">5.4.x</link> and
  <link linkend="migration55">5.5.x</link>.
 </simpara>

 <sect1 xml:id="migration56.changes">
  <title>What has changed in PHP 5.6.x</title>
  <warning>
   <simpara>
    PHP 5.6 is currently being tested, and the features and changes noted in
    this section are subject to change before the final 5.6.0 release. Please
    double check this migration guide before deploying a stable 5.6 release to
    production.
   </simpara>
  </warning>
  <simpara>
   Most improvements in PHP 5.6.x have no impact on existing code. There are
   a <link linkend="migration56.incompatible">few incompatibilities</link>
   and <link linkend="migration56.new-features">new features</link> that should
   be considered, and code should be tested before switching PHP
   versions in production environments.
  </simpara>
  <simpara>
   For systems being upgraded from an older version of PHP, the relevant
   documentation is available at:
  </simpara>
  <itemizedlist>
   <listitem>
    <simpara>
     <link linkend="migration55">Upgrade Notes for PHP 5.5.x</link>.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <link linkend="migration54">Upgrade Notes for PHP 5.4.x</link>.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <link linkend="migration53">Upgrade Notes for PHP 5.3.x</link>.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <link linkend="migration52">Upgrade Notes for PHP 5.2.x</link>.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <link linkend="migration51">Upgrade Notes for PHP 5.1.x</link>.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <link linkend="migration5">Migrating from PHP 4 to PHP 5</link>.
    </simpara>
   </listitem>
  </itemizedlist>
 </sect1>

 <sect1 xml:id="migration56.incompatible">
  <title>Backward Incompatible Changes</title>
  <simpara>
   Although most existing PHP 5 code should work without changes, please take
   note of some backward incompatible changes:
  </simpara>

  <sect2 xml:id="migration56.incompatible.json-decode">
   <title><function>json_decode</function> strictness</title>

   <para>
    <function>json_decode</function> now rejects non-lowercase variants of the
    JSON literals <literal>true</literal>, <literal>false</literal> and
    <literal>null</literal> at all times, as per the JSON specification, and
    sets <function>json_last_error</function> accordingly. Previously, inputs
    to <function>json_decode</function> that consisted solely of one of these
    values in upper or mixed case were accepted.
   </para>

   <para>
    This change will only affect cases where invalid JSON was being passed to
    <function>json_decode</function>: valid JSON input is unaffected and will
    continue to be parsed normally.
   </para>
  </sect2>

  <sect2 xml:id="migration56.incompatible.gmp">
   <title><link linkend="book.gmp">GMP</link> resources are now objects</title>

   <para>
    <link linkend="book.gmp">GMP</link> resources are now objects. The
    functional API implemented in the GMP extension has not changed, and code
    should run modified unless it checks explicitly for a resource using
    <function>is_resource</function> or similar.
   </para>
  </sect2>
 </sect1>

 <sect1 xml:id="migration56.new-features">
  <title>New features</title>

  <sect2 xml:id="migration56.new-features.const-scalar-exprs">
   <title>Constant scalar expressions</title>

   <para>
    It is now possible to provide a scalar expression involving numeric and
    string literals and/or constants in contexts where PHP previously expected
    a static value, such as constant and property declarations and default
    function arguments.
   </para>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
const ONE = 1;
const TWO = ONE * 2;

class C {
    const THREE = TWO + 1;
    const ONE_THIRD = ONE / self::THREE;
    const SENTENCE = 'The value of THREE is '.self::THREE;

    public function f($a = ONE + self::THREE) {
        return $a;
    }
}

echo (new C)->f()."\n";
echo C::SENTENCE;
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
4
The value of THREE is 3
]]>
    </screen>
   </informalexample>
  </sect2>

  <sect2 xml:id="migration56.new-features.variadics">
   <title>Variadic functions via <literal>...</literal></title>

   <para>
    <link linkend="functions.variable-arg-list">Variadic functions</link> can
    now be implemented using the <literal>...</literal> operator, instead of
    relying on <function>func_get_args</function>.
   </para>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
function f($req, $opt = null, ...$params) {
    // $params is an array containing the remaining arguments.
    printf('$req: %d; $opt: %d; number of params: %d'."\n",
           $req, $opt, count($params));
}

f(1);
f(1, 2);
f(1, 2, 3);
f(1, 2, 3, 4);
f(1, 2, 3, 4, 5);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
$req: 1; $opt: 0; number of params: 0
$req: 1; $opt: 2; number of params: 0
$req: 1; $opt: 2; number of params: 1
$req: 1; $opt: 2; number of params: 2
$req: 1; $opt: 2; number of params: 3
]]>
    </screen>
   </informalexample>
  </sect2>

  <sect2 xml:id="migration56.new-features.splat">
   <title>Argument unpacking via <literal>...</literal></title>

   <para>
    <link linkend="language.types.array">Arrays</link> and
    <interfacename>Traversable</interfacename> objects can be unpacked into
    argument lists when calling functions by using the <literal>...</literal>
    operator. This is also known as the splat operator in other languages,
    including Ruby.
   </para>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
function add($a, $b, $c) {
    return $a + $b + $c;
}

$operators = [2, 3];
echo add(1, ...$operators);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
6
]]>
    </screen>
   </informalexample>
  </sect2>

  <sect2 xml:id="migration56.new-features.use">
   <title><literal>use function</literal> and <literal>use const</literal></title>

   <para>
    The
    <link linkend="language.namespaces.importing"><literal>use</literal></link> 
    operator has been extended to support importing functions and constants in
    addition to classes. This is achieved via the
    <literal>use function</literal> and <literal>use const</literal>
    constructs, respectively.
   </para>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
namespace Name\Space {
    const FOO = 42;
    function f() { echo __FUNCTION__."\n"; }
}

namespace {
    use const Name\Space\FOO;
    use function Name\Space\f;

    echo FOO."\n";
    f();
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
42
Name\Space\f
]]>
    </screen>
   </informalexample>
  </sect2>

  <sect2 xml:id="migration56.new-features.phpdbg">
   <title>phpdbg</title>

   <para>
    PHP now includes an interactive debugger called phpdbg implemented as a
    SAPI module. For more information, please visit the
    <link xlink:href="&url.phpdbg.docs;">phpdbg documentation</link>.
   </para>
  </sect2>

  <sect2 xml:id="migration56.new-features.reusable-input">
   <title><link linkend="wrappers.php.input"><literal>php://input</literal></link> is reusable</title>

   <para>
    <link linkend="wrappers.php.input"><literal>php://input</literal></link>
    may now be reopened and read as many times as required. This work has also
    resulted in a major reduction in the amount of memory required to deal
    with POST data.
   </para>
  </sect2>

  <sect2 xml:id="migration56.new-features.large-file">
   <title>Large file uploads</title>

   <para>
    Files larger than 2 gigabytes in size are now accepted.
   </para>
  </sect2>

  <sect2 xml:id="migration56.new-features.gmp">
   <title><link linkend="book.gmp">GMP</link> supports operator overloading</title>

   <para>
    <link linkend="book.gmp">GMP</link> objects now support operator
    overloading and casting to scalar types. This allows for more expressive
    code using GMP:
   </para>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
$a = gmp_init(42);
$b = gmp_init(17);
 
// Pre-5.6 code:
var_dump(gmp_add($a, $b));
var_dump(gmp_add($a, 17));
var_dump(gmp_add(42, $b));

// New code:
var_dump($a + $b);
var_dump($a + 17);
var_dump(42 + $b);
?>
]]>
    </programlisting>
   </informalexample>
  </sect2>

  <sect2 xml:id="migration56.new-features.gost">
   <title>gost-crypto hash algorithm</title>

   <para>
    The <literal>gost-crypto</literal> hash algorithm has been added. This
    implements the GOST hash function using the CryptoPro S-box tables as
    specified by
    <link xlink:href="&url.rfc;4357">RFC 4357, section 11.2</link>.
   </para>
  </sect2>

  <sect2 xml:id="migration56.new-features.openssl">
   <title>SSL/TLS improvements</title>

   <para>
    The <link linkend="book.openssl">OpenSSL</link> extension has been
    extended to include support for extracting and verifying certificate
    fingerprints. <function>openssl_x509_fingerprint</function> has been added
    to extract a fingerprint from an X.509 certificate, and two
    <link linkend="context.ssl">SSL stream context</link> options have been
    added: <literal>capture_peer_cert</literal> to capture the peer's X.509
    certificate, and <literal>peer_fingerprint</literal> to assert that the
    peer's certificate should match the given fingerprint.
   </para>

   <para>
    Additionally, a specific crypto method such as SSLv3 or TLS may now be
    selected by setting the <literal>crypto_method</literal>
    <link linkend="context.ssl">SSL stream context</link> option. Possible
    options include <constant>STREAM_CRYPTO_METHOD_SSLv2_CLIENT</constant>,
    <constant>STREAM_CRYPTO_METHOD_SSLv3_CLIENT</constant>,
    <constant>STREAM_CRYPTO_METHOD_SSLv23_CLIENT</constant> (the default), or
    <constant>STREAM_CRYPTO_METHOD_TLS_CLIENT</constant>.
   </para>
  </sect2>
 </sect1>

 <sect1 xml:id="migration56.deprecated">
  <title>Deprecated features in PHP 5.6.x</title>

  <sect2 xml:id="migration56.deprecated.incompatible-context">
   <title>Calls from incompatible context</title>

   <para>
    Methods called from an incompatible context are now deprecated, and will
    generate <constant>E_DEPRECATED</constant> errors when invoked instead of
    <constant>E_STRICT</constant>. Support for these calls will be removed in
    a future version of PHP.
   </para>

   <para>
    An example of such a call is:
   </para>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
class A {
    function f() { echo get_class($this); }
}

class B {
    function f() { A::f(); }
}

(new B)->f();
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Deprecated: Non-static method A::f() should not be called statically, assuming $this from incompatible context in - on line 7
B
]]>
    </screen>
   </informalexample>
  </sect2>

  <sect2 xml:id="migration56.deprecated.raw-post-data">
   <title><varname>$HTTP_RAW_POST_DATA</varname> and <link linkend="ini.always-populate-raw-post-data">always_populate_raw_post_data</link></title>

   <para>
    <link linkend="ini.always-populate-raw-post-data">always_populate_raw_post_data</link>
    will now generate an <constant>E_DEPRECATED</constant> error when enabled.
    New code should use
    <link linkend="wrappers.php.input"><literal>php://input</literal></link>
    instead of <varname>$HTTP_RAW_POST_DATA</varname>, which will be removed
    in a future release. You can opt in for the new behaviour (in which
    <varname>$HTTP_RAW_POST_DATA</varname> is never defined) by setting
    <link linkend="ini.always-populate-raw-post-data">always_populate_raw_post_data</link>
    to <literal>-1</literal>.
   </para>
  </sect2>
 </sect1>

 <sect1 xml:id="migration56.changed-functions">
  <title>Changed Functions</title>

  <sect2 xml:id="migration56.changed-functions.core">
   <title>PHP Core</title>

   <itemizedlist>
    <listitem>
     <simpara>
      <function>crypt</function> will now raise an
      <constant>E_NOTICE</constant> error if the <parameter>salt</parameter>
      parameter is omitted.
     </simpara>
    </listitem>
   </itemizedlist>
  </sect2>

  <sect2 xml:id="migration56.changed-functions.curl">
   <title><link linkend="book.curl">cURL</link></title>

   <itemizedlist>
    <listitem>
     <simpara>
      Uploads using the <literal>@file</literal> syntax are now only supported
      if the <constant>CURLOPT_SAFE_UPLOAD</constant> option is set to
      &false;. <classname>CURLFile</classname> should be used instead.
     </simpara>
    </listitem>
   </itemizedlist>
  </sect2>

  <sect2 xml:id="migration56.changed-functions.xmlreader">
   <title><link linkend="book.xmlreader">XMLReader</link></title>

   <itemizedlist>
    <listitem>
     <simpara>
      <methodname>XMLReader::getAttributeNs</methodname> and
      <methodname>XMLReader::getAttributeNo</methodname> now return &null; if
      the attribute could not be found, like
      <methodname>XMLReader::getAttribute</methodname>.
     </simpara>
    </listitem>
   </itemizedlist>
  </sect2>
 </sect1>

 <sect1 xml:id="migration56.new-functions">
  <title>New Functions</title>

  <sect2 xml:id="migration56.new-functions.gmp">
   <title><link linkend="book.gmp">GMP</link></title>

   <itemizedlist>
    <listitem>
     <simpara>
      <function>gmp_root</function>
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <function>gmp_rootrem</function>
     </simpara>
    </listitem>
   </itemizedlist>
  </sect2>

  <sect2 xml:id="migration56.new-functions.ldap">
   <title><link linkend="book.ldap">LDAP</link></title>

   <itemizedlist>
    <listitem>
     <simpara>
      <function>ldap_escape</function>
     </simpara>
    </listitem>
   </itemizedlist>
  </sect2>

  <sect2 xml:id="migration56.new-functions.oci8">
   <title><link linkend="book.oci8">OCI8</link></title>

   <itemizedlist>
    <listitem>
     <simpara>
      <function>oci_get_implicit_resultset</function>
     </simpara>
    </listitem>
   </itemizedlist>
  </sect2>

  <sect2 xml:id="migration56.new-functions.openssl">
   <title><link linkend="book.openssl">OpenSSL</link></title>

   <itemizedlist>
    <listitem>
     <simpara>
      <function>openssl_x509_fingerprint</function>
     </simpara>
    </listitem>
   </itemizedlist>
  </sect2>

  <sect2 xml:id="migration56.new-functions.zip">
   <title><link linkend="book.zip">Zip</link></title>

   <itemizedlist>
    <listitem>
     <simpara>
      <methodname>ZipArchive::setPassword</methodname>
     </simpara>
    </listitem>
   </itemizedlist>
  </sect2>
 </sect1>

 <sect1 xml:id="migration56.extensions-other">
  <title>Other changes to extensions</title>

  <sect2 xml:id="migration56.extensions-other.oci8">
   <title><link linkend="book.oci8">OCI8</link></title>

   <itemizedlist>
    <listitem>
     <simpara>
      Support for implicit result sets for Oracle Database 12c has been added
      via the new <function>oci_get_implicit_resultset</function> function.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Using <literal>oci_execute($s, OCI_NO_AUTO_COMMIT)</literal> for a
      SELECT no longer unnecessarily initiates an internal ROLLBACK during
      connection close.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Added DTrace probes controlled by the <literal>--enable-dtrace</literal>
      configure option.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <function>oci_internal_debug</function> is now a no-op.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      The <function>phpinfo</function> output format for OCI8 has changed.
     </simpara>
    </listitem>
   </itemizedlist>
  </sect2>

  <sect2 xml:id="migration56.extensions-other.zip">
   <title><link linkend="book.zip">Zip</link></title>

   <para>
    A <literal>--with-libzip</literal> configure option has been added to use
    a system libzip installation. libzip version 0.11 is required, with 0.11.2
    or later recommended.
   </para>
  </sect2>
 </sect1>

 <sect1 xml:id="migration56.global-constants">
  <title>New Global Constants</title>

  <sect2 xml:id="migration56.global-constants.ldap">
   <title><link linkend="book.ldap">LDAP</link></title>

   <itemizedlist>
    <listitem>
     <simpara>
      <constant>LDAP_ESCAPE_DN</constant>
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <constant>LDAP_ESCAPE_FILTER</constant>
     </simpara>
    </listitem>
   </itemizedlist>
  </sect2>
 </sect1>
</appendix>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->