<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<sect1 xml:id="migration56.new-features" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>New features</title>

 <sect2 xml:id="migration56.new-features.const-scalar-exprs">
  <title>Constant 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>

  <para>
   It is also now possible to define a constant <type>array</type> using the
   <literal>const</literal> keyword:
  </para>

  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
const ARR = ['a', 'b'];

echo ARR[0];
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
a
]]>
   </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.exponentiation">
  <title>Exponentiation via <literal>**</literal></title>

  <para>
   A right associative <literal>**</literal> operator has been added to
   support exponentiation, along with a <literal>**=</literal> shorthand
   assignment operator.
  </para>

  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
printf("2 ** 3 ==      %d\n", 2 ** 3);
printf("2 ** 3 ** 2 == %d\n", 2 ** 3 ** 2);

$a = 2;
$a **= 3;
printf("a ==           %d\n", $a);
?>
]]>
   </programlisting>
  &example.outputs;
  <screen>
<![CDATA[
2 ** 3 ==      8
2 ** 3 ** 2 == 512
a ==           8
]]>
  </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 linkend="book.phpdbg">phpdbg documentation</link>.
  </para>
 </sect2>

 <sect2 xml:id="migration56.new-features.default-encoding">
  <title>Default character encoding</title>

  <para>
   <link linkend="ini.default-charset">default_charset</link> is now used as
   the default character set for the <function>htmlentities</function>,
   <function>html_entity_decode</function> and
   <function>htmlspecialchars</function> functions. Note that if the (now
   deprecated) iconv and mbstring encoding settings are set, they will take
   precedence over default_charset for iconv and mbstring functions,
   respectively.
  </para>

  <para>
   The default value for this setting is <literal>UTF-8</literal>.
  </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);

if (version_compare(PHP_VERSION, '5.6', '<')) {
    echo gmp_intval(gmp_add($a, $b)), PHP_EOL;
    echo gmp_intval(gmp_add($a, 17)), PHP_EOL;
    echo gmp_intval(gmp_add(42, $b)), PHP_EOL;
} else {
    echo $a + $b, PHP_EOL;
    echo $a + 17, PHP_EOL;
    echo 42 + $b, PHP_EOL;
}
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
59
59
59
]]>
   </screen>
  </informalexample>
 </sect2>

 <sect2 xml:id="migration56.new-features.hash-equals">
  <title><function>hash_equals</function> for timing attack safe string comparison</title>

  <para>
   The <function>hash_equals</function> function has been added to compare
   two strings in constant time. This should be used to mitigate timing
   attacks; for instance, when testing <function>crypt</function> password
   hashes (assuming that you are unable to use
   <function>password_hash</function> and
   <function>password_verify</function>, which aren't susceptible to timing
   attacks).
  </para>

  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$expected  = crypt('12345', '$2a$07$usesomesillystringforsalt$');
$correct   = crypt('12345', '$2a$07$usesomesillystringforsalt$');
$incorrect = crypt('1234',  '$2a$07$usesomesillystringforsalt$');

var_dump(hash_equals($expected, $correct));
var_dump(hash_equals($expected, $incorrect));
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
bool(true)
bool(false)
]]>
   </screen>
  </informalexample>
 </sect2>

 <sect2 xml:id="migration56.new-features.debuginfo">
  <title><literal>__debugInfo()</literal></title>

  <para>
   The <link linkend="language.oop5.magic.debuginfo">__debugInfo()</link>
   magic method has been added to allow objects to change the properties and
   values that are shown when the object is output using
   <function>var_dump</function>.
  </para>

  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
class C {
    private $prop;

    public function __construct($val) {
        $this->prop = $val;
    }

    public function __debugInfo() {
        return [
            'propSquared' => $this->prop ** 2,
        ];
    }
}

var_dump(new C(42));
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
object(C)#1 (1) {
  ["propSquared"]=>
  int(1764)
}
]]>
   </screen>
  </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>
   A wide range of improvements have been made to the SSL/TLS support in PHP
   5.6. These include
   <link linkend="migration56.incompatible.peer-verification">enabling peer verification by default</link>,
   supporting certificate fingerprint matching, mitigating against TLS
   renegotiation attacks, and many new
   <link linkend="context.ssl">SSL context options</link> to allow more fine
   grained control over protocol and verification settings when using
   encrypted streams.
  </para>

  <para>
   These changes are described in more detail in the
   <link linkend="migration56.openssl">OpenSSL changes in PHP 5.6.x</link>
   section of this migration guide.
  </para>
 </sect2>

 <sect2 xml:id="migration56.new-features.postgresql">
  <title><link linkend="book.pgsql">pgsql</link> async support</title>

  <para>
   The <link linkend="book.pgsql">pgsql</link> extension now supports
   asynchronous connections and queries, thereby enabling non-blocking
   behaviour when interacting with PostgreSQL databases. Asynchronous
   connections may be established via the
   <constant>PGSQL_CONNECT_ASYNC</constant> constant, and the new
   <function>pg_connect_poll</function>, <function>pg_socket</function>,
   <function>pg_consume_input</function> and <function>pg_flush</function>
   functions may be used to handle asynchronous connections and queries.
  </para>
 </sect2>
</sect1>

<!-- 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
-->