php-doc-en/appendices/migration80/new-features.xml

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

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

 <sect2 xml:id="migration80.new-features.core">
  <title>PHP Core</title>

  <sect3 xml:id="migration80.new-features.core.named-arguments">
   <title>Named Arguments</title>

   <para>
    <!-- RFC: https://wiki.php.net/rfc/named_params -->
    Support for <link linkend="functions.named-arguments">Named Arguments</link> has been added.
   </para>
  </sect3>

  <sect3 xml:id="migration80.new-features.core.attributes">
   <title>Attributes</title>

   <para>
    Support for <link linkend="language.attributes">Attributes</link> has been added.
    <!-- RFC: https://wiki.php.net/rfc/attributes_v2 -->
    <!-- RFC: https://wiki.php.net/rfc/attribute_amendments -->
    <!-- RFC: https://wiki.php.net/rfc/shorter_attribute_syntax -->
    <!-- RFC: https://wiki.php.net/rfc/shorter_attribute_syntax_change -->
   </para>
  </sect3>

  <sect3 xml:id="migration80.new-features.core.property-promotion">
   <title>Constructor Property Promotion</title>

   <para>
    Support for <link linkend="language.oop5.decon.constructor.promotion">constructor property promotion</link> (declaring properties in the constructor signature)
    has been added.
    <!-- RFC: https://wiki.php.net/rfc/constructor_promotion -->
   </para>
  </sect3>

  <sect3 xml:id="migration80.new-features.core.union-types">
   <title>Union Types</title>

   <para>
    Support for <link linkend="language.types.declarations.composite.union">union types</link> has been added.
    <!-- RFC: https://wiki.php.net/rfc/union_types_v2 -->
   </para> 
  </sect3>

  <sect3 xml:id="migration80.new-features.core.match">
   <title>Match Expression</title>

   <para>
    Support for <link linkend="control-structures.match"><literal>match</literal> expressions</link> has been added.
    <!-- RFC: https://wiki.php.net/rfc/match_expression_v2 -->
   </para>
  </sect3>

  <sect3 xml:id="migration80.new-features.core.nullsafe-operator">
   <title>Nullsafe Operator</title>

   <para>
    Support for the <link linkend="language.oop5.basic.nullsafe">nullsafe operator</link> (<literal>?-></literal>) has been added.
    <!-- RFC: https://wiki.php.net/rfc/nullsafe_operator -->
   </para>
  </sect3>

  <sect3 xml:id="migration80.new-features.core.others">
   <title>Other new Features</title>

   <itemizedlist>
    <listitem>
     <para>
      The <link linkend="class.weakmap">WeakMap</link> class has been added.
      <!-- RFC: https://wiki.php.net/rfc/weak_maps -->
     </para>
    </listitem>
    <listitem>
     <para>
      The <classname>ValueError</classname> class has been added.
     </para>
    </listitem>
    <listitem>
     <para>
      Any number of function parameters may now be replaced by a variadic argument, as long as the
      types are compatible. For example, the following code is now allowed:
     </para>
     <para>
      <programlisting role="php">
<![CDATA[
<?php
class A {
     public function method(int $many, string $parameters, $here) {}
}
class B extends A {
     public function method(...$everything) {}
}
?>
]]>
      </programlisting>
     </para>
    </listitem>
    <listitem>
     <para>
      <type>static</type> (as in "late static binding") can now be used as a return type:
     </para>
     <para>
      <programlisting role="php">
<![CDATA[
<?php
class Test {
     public function create(): static {
          return new static();
     }
}
?>
]]>
      </programlisting>
      <!-- RFC: https://wiki.php.net/rfc/static_return_type -->
     </para>
    </listitem>
    <listitem>
     <para>
      It is now possible to fetch the class name of an object using
      <code>$object::class</code>. The result is the same as <code>get_class($object)</code>.
      <!-- RFC: https://wiki.php.net/rfc/class_name_literal_on_object -->
     </para>
    </listitem>
    <listitem>
     <para>
      &new; and &instanceof; can now be used with arbitrary expressions,
      using <code>new (expression)(...$args)</code> and <code>$obj instanceof (expression)</code>.
      <!-- RFC: https://wiki.php.net/rfc/variable_syntax_tweaks -->
     </para>
    </listitem>
    <listitem>
     <para>
      Some consistency fixes to variable syntax have been applied, for example writing
      <code>Foo::BAR::$baz</code> is now allowed.
      <!-- RFC: https://wiki.php.net/rfc/variable_syntax_tweaks -->
     </para>
    </listitem>
    <listitem>
     <para>
      Added <interfacename>Stringable</interfacename> interface, which is automatically implemented if
      a class defines a <link linkend="object.tostring">__toString()</link> method.
      <!-- RFC: https://wiki.php.net/rfc/stringable -->
     </para>
    </listitem>
    <listitem>
     <para>
      Traits can now define abstract private methods.
      Such methods must be implemented by the class using the trait.
      <!-- RFC: https://wiki.php.net/rfc/abstract_trait_method_validation -->
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>throw</literal> can now be used as an expression.
      That allows usages like:
      <programlisting role="php">
<![CDATA[
<?php
$fn = fn() => throw new Exception('Exception in arrow function');
$user = $session->user ?? throw new Exception('Must have user');
]]>
      </programlisting>
      <!-- RFC: https://wiki.php.net/rfc/throw_expression -->
     </para>
    </listitem>
    <listitem>
     <para>
      An optional trailing comma is now allowed in parameter lists.
      <programlisting role="php">
<![CDATA[
<?php
function functionWithLongSignature(
    Type1 $parameter1,
    Type2 $parameter2, // <-- This comma is now allowed.
) {
}
]]>
      </programlisting>
      <!-- RFC: https://wiki.php.net/rfc/trailing_comma_in_parameter_list -->
     </para>
    </listitem>
    <listitem>
     <para>
      It is now possible to write <code>catch (Exception)</code> to catch an exception without storing
      it in a variable.
      <!-- RFC: https://wiki.php.net/rfc/non-capturing_catches -->
     </para>
    </listitem>
    <listitem>
     <para>
      Support for <type>mixed</type> type has been added.
      <!-- RFC: https://wiki.php.net/rfc/mixed_type_v2 -->
     </para>
    </listitem>
    <listitem>
     <para>
      Private methods declared on a parent class no longer enforce any inheritance rules on the methods
      of a child class (with the exception of final private constructors).
      The following example illustrates which restrictions have been removed:
      <programlisting role="php">
<![CDATA[
<?php
class ParentClass {
    private function method1() {}
    private function method2() {}
    private static function method3() {}
    // Throws a warning, as "final" no longer has an effect:
    private final function method4() {}
}
class ChildClass extends ParentClass {
    // All of the following are now allowed, even though the modifiers aren't
    // the same as for the private methods in the parent class.
    public abstract function method1() {}
    public static function method2() {}
    public function method3() {}
    public function method4() {}
}
?>
]]>
      </programlisting>
      <!-- RFC: https://wiki.php.net/rfc/inheritance_private_methods -->
     </para>
    </listitem>
    <listitem>
     <para>
      <function>get_resource_id</function> has been added, which returns the same value as
      <code>(int) $resource</code>. It provides the same functionality under a clearer API.
     </para>
    </listitem>
   </itemizedlist>
  </sect3>
 </sect2>

 <sect2 xml:id="migration80.new-features.date">
  <title>Date and Time</title>
  
  <itemizedlist>
   <listitem>
    <para>
     <methodname>DateTime::createFromInterface</methodname> and
     <methodname>DateTimeImmutable::createFromInterface</methodname> have been added.
    </para>
   </listitem>
   <listitem>
    <para>
     The DateTime format specifier <literal>p</literal> has been added, which is the same as
     <literal>P</literal> but returns <literal>Z</literal> rather than <literal>+00:00</literal>
     for UTC.
    </para>
   </listitem>
  </itemizedlist>
 </sect2>

 <sect2 xml:id="migration80.new-features.dom">
  <title>DOM</title>

  <para>
   <interfacename>DOMParentNode</interfacename> and <interfacename>DOMChildNode</interfacename> with
   new traversal and manipulation APIs have been added.
   <!-- RFC: https://wiki.php.net/rfc/dom_living_standard_api-->
  </para>
 </sect2>

 <sect2 xml:id="migration80.new-features.filter">
  <title>Filter</title>

  <para>
   <constant>FILTER_VALIDATE_BOOL</constant> has been added as an alias for
   <constant>FILTER_VALIDATE_BOOLEAN</constant>. The new name is preferred, as it uses the canonical
   type name.
  </para>
 </sect2>

 <sect2 xml:id="migration80.new-features.enchant">
  <title>Enchant</title>

  <para>
   <function>enchant_dict_add</function>, <function>enchant_dict_is_added</function>, and
   <constant>LIBENCHANT_VERSION</constant> have been added.
  </para>
 </sect2>

 <sect2 xml:id="migration80.new-features.fpm">
  <title>FPM</title>

  <para>
   Added a new option <literal>pm.status_listen</literal> that allows getting the status from
   different endpoint (e.g. port or UDS file) which is useful for getting the status when all
   children are busy with serving long running requests.
  </para>
 </sect2>

 <sect2 xml:id="migration80.new-features.hash">
  <title>Hash</title>

  <para>
   <classname>HashContext</classname> objects can now be serialized.
  </para>
 </sect2>

 <sect2 xml:id="migration80.new-features.intl">
  <title>Internationalization Functions</title>

  <para>
   The <constant>IntlDateFormatter::RELATIVE_FULL</constant>,
   <constant>IntlDateFormatter::RELATIVE_LONG</constant>,
   <constant>IntlDateFormatter::RELATIVE_MEDIUM</constant>, and
   <constant>IntlDateFormatter::RELATIVE_SHORT</constant>
   constants have been added.
  </para>
 </sect2>

 <sect2 xml:id="migration80.new-features.ldap">
  <title>LDAP</title>

  <para>
   <function>ldap_count_references</function> has been added, which returns the number
   of reference messages in a search result.
  </para>
 </sect2>
 <sect2 xml:id="migration80.new-features.opcache">
  <title>OPcache</title>

  <para>
   If the <!--<link linkend="ini.opcache.record-warnings">-->opcache.record_warnings<!--</link>--> ini setting is
   enabled, OPcache will record compile-time warnings and replay them on the next include, even if
   it is served from cache.
  </para>
 </sect2>

 <sect2 xml:id="migration80.new-features.openssl">
  <title>OpenSSL</title>

  <para>
   Added Cryptographic Message Syntax (CMS) (<link xlink:href="&url.rfc;5652">RFC 5652</link>)
   support composed of functions for encryption, decryption, signing, verifying and reading. The API
   is similar to the API for PKCS #7 functions with an addition of new encoding constants:
   <constant>OPENSSL_ENCODING_DER</constant>, <constant>OPENSSL_ENCODING_SMIME</constant>
   and <constant>OPENSSL_ENCODING_PEM</constant>:
   <simplelist>
    <member>
     <function>openssl_cms_encrypt</function> encrypts the message in the file with the certificates
     and outputs the result to the supplied file.
    </member>
    <member>
     <function>openssl_cms_decrypt</function> that decrypts the S/MIME message in the file and outputs
     the results to the supplied file.
    </member>
    <member>
     <function>openssl_cms_read</function> that exports the CMS file to an array of PEM certificates.
    </member>
    <member>
     <function>openssl_cms_sign</function> that signs the MIME message in the file with a cert and key
     and output the result to the supplied file.
    </member>
    <member>
     <function>openssl_cms_verify</function> that verifies that the data block is intact, the signer
     is who they say they are, and returns the certs of the signers.
    </member>
   </simplelist>
  </para>
 </sect2>

 <sect2 xml:id="migration80.new-features.pcre">
  <title>Regular Expressions (Perl-Compatible)</title>

  <para>
   <function>preg_last_error_msg</function> has been added, which returns a human-readable message for the last
   PCRE error. It complements <function>preg_last_error</function>, which returns an integer enum value
   instead.
  </para>
 </sect2>

 <sect2 xml:id="migration80.new-features.reflection">
  <title>Reflection</title>

  <itemizedlist>
   <listitem>
    <para>
     The following methods can now return information about default values of
     parameters of internal functions:
    </para>
    <para>
     <simplelist>
      <member><methodname>ReflectionParameter::isDefaultValueAvailable</methodname></member>
      <member><methodname>ReflectionParameter::getDefaultValue</methodname></member>
      <member><methodname>ReflectionParameter::isDefaultValueConstant</methodname></member>
      <member><methodname>ReflectionParameter::getDefaultValueConstantName</methodname></member>
     </simplelist>
    </para>
   </listitem>
  </itemizedlist>
 </sect2>

 <sect2 xml:id="migration80.new-features.sqlite3">
  <title>SQLite3</title>

  <para>
   <methodname>SQLite3::setAuthorizer</methodname> and respective class constants have been added
   to set a userland callback that will be used to authorize or not an action on the database.
   <!-- PR: https://github.com/php/php-src/pull/4797 -->
  </para>
 </sect2>

 <sect2 xml:id="migration80.new-features.standard">
  <title>Standard Library</title>

  <itemizedlist>
   <listitem>
    <para>
     <function>str_contains</function>, <function>str_starts_with</function> and
     <function>str_ends_with</function> have been added, which check whether <parameter>haystack</parameter> contains,
     starts with or ends with <parameter>needle</parameter>, respectively.
     <!-- RFC: https://wiki.php.net/rfc/str_contains -->
     <!-- RFC: https://wiki.php.net/rfc/add_str_starts_with_and_ends_with_functions -->
    </para>
   </listitem>
   <listitem>
    <para>
     <function>fdiv</function> has been added, which performs a floating-point division under IEEE 754 semantics.
     Division by zero is considered well-defined and will return one of <literal>Inf</literal>,
     <literal>-Inf</literal> or <literal>NaN</literal>.
    </para>
   </listitem>
   <listitem>
    <para>
     <function>get_debug_type</function> has been added, which returns a type useful for error messages. Unlike
     <function>gettype</function>, it uses canonical type names, returns class names for objects, and
     indicates the resource type for resources.
     <!-- RFC: https://wiki.php.net/rfc/get_debug_type -->
    </para>
   </listitem>
   <listitem>
    <para>
     <function>printf</function> and friends now support the <literal>%h</literal> and
     <literal>%H</literal> format specifiers. These are the same as <literal>%g</literal> and
     <literal>%G</literal>, but always use <literal>"."</literal> as the decimal separator, rather
     than determining it through the <constant>LC_NUMERIC</constant> locale.
    </para>
   </listitem>
   <listitem>
    <para>
     <function>printf</function> and friends now support using <literal>"*"</literal> as width or
     precision, in which case the width/precision is passed as an argument to printf. This also allows
     using precision <literal>-1</literal> with <literal>%g</literal>, <literal>%G</literal>,
     <literal>%h</literal> and <literal>%H</literal>. For example, the following code can be used to
     reproduce PHP's default floating point formatting:
    </para>
    <para>
     <programlisting role="php">
<![CDATA[
<?php
printf("%.*H", (int) ini_get("precision"), $float);
printf("%.*H", (int) ini_get("serialize_precision"), $float);
?>
]]>
     </programlisting>
    </para>
   </listitem>
   <listitem>
    <para>
     <function>proc_open</function> now supports pseudo-terminal (PTY) descriptors. The following
     attaches <literal>stdin</literal>, <literal>stdout</literal> and <literal>stderr</literal> to the
     same PTY:
    </para>
    <para>
     <programlisting role="php">
<![CDATA[
<?php
$proc = proc_open($command, [['pty'], ['pty'], ['pty']], $pipes);
?>
]]>
     </programlisting>
    </para>
   </listitem>
   <listitem>
    <para>
     <function>proc_open</function> now supports socket pair descriptors. The following attaches a
     distinct socket pair to <literal>stdin</literal>, <literal>stdout</literal> and
     <literal>stderr</literal>:
    </para>
    <para>
     <programlisting role="php">
<![CDATA[
<?php
$proc = proc_open($command, [['socket'], ['socket'], ['socket']], $pipes);
?>
]]>
     </programlisting>
    </para>
    <para>
     Unlike pipes, sockets do not suffer from blocking I/O issues on Windows. However, not all
     programs may work correctly with stdio sockets.
    </para>
   </listitem>
   <listitem>
    <para>
     Sorting functions are now stable, which means that equal-comparing elements will retain their
     original order.
     <!-- RFC: https://wiki.php.net/rfc/stable_sorting -->
    </para>
   </listitem>
   <listitem>
    <para>
     <function>array_diff</function>, <function>array_intersect</function> and their variations can
     now be used with a single array as argument. This means that usages like the following are now
     possible:
    </para>
    <para>
     <programlisting role="php">
<![CDATA[
<?php
// OK even if $excludes is empty:
array_diff($array, ...$excludes);
// OK even if $arrays only contains a single array:
array_intersect(...$arrays);
?>
]]>
     </programlisting>
    </para>
   </listitem>
   <listitem>
    <para>
     The <parameter>flag</parameter> parameter of <function>ob_implicit_flush</function> was changed
     to accept a <type>bool</type> rather than an <type>int</type>.
    </para>
   </listitem>
  </itemizedlist>
 </sect2>

 <sect2 xml:id="migration80.new-features.tokenizer">
  <title>Tokenizer</title>

  <para>
   <classname>PhpToken</classname> adds an object-based interface to the tokenizer. It provides a
   more uniform and ergonomic representation, while being more memory efficient and faster.
   <!--  RFC: https://wiki.php.net/rfc/token_as_object -->
  </para>
 </sect2>

 <sect2 xml:id="migration80.new-features.zip">
  <title>Zip</title>

  <itemizedlist>
   <listitem>
    <para>
     The Zip extension has been updated to version 1.19.1.
    </para>
   </listitem>
   <listitem>
    <para>
     New <methodname>ZipArchive::setMtimeName</methodname> and
     <methodname>ZipArchive::setMtimeIndex</methodname> to set the modification time of an entry.
    </para>
   </listitem>
   <listitem>
    <para>
     New <methodname>ZipArchive::registerProgressCallback</methodname> to provide updates during archive close.
    </para>
   </listitem>
   <listitem>
    <para>
     New <methodname>ZipArchive::registerCancelCallback</methodname> to allow cancellation during archive
     close.
    </para>
   </listitem>
   <listitem>
    <para>
     New <methodname>ZipArchive::replaceFile</methodname> to replace an entry content.
    </para>
   </listitem>
   <listitem>
    <para>
     New <methodname>ZipArchive::isCompressionMethodSupported</methodname> to check optional compression
     features.
    </para>
   </listitem>
   <listitem>
    <para>
     New <methodname>ZipArchive::isEncryptionMethodSupported</methodname> to check optional encryption
     features.
    </para>
   </listitem>
   <listitem>
    <para>
     The <varname>ZipArchive::lastId</varname> property to get the index value of
     the last added entry has been added.
    </para>
   </listitem>
   <listitem>
    <para>
     Errors can now be checked after an archive has been closed using the
     <varname>ZipArchive::status</varname> and
     <varname>ZipArchive::statusSys</varname> properties, or the
     <methodname>ZipArchive::getStatusString</methodname> method.
    </para>
   </listitem>
   <listitem>
    <para>
     The <literal>'remove_path'</literal> option of <methodname>ZipArchive::addGlob</methodname> and
     <methodname>ZipArchive::addPattern</methodname> is now treated as an arbitrary string prefix (for
     consistency with the <literal>'add_path'</literal> option), whereas formerly it was treated as a
     directory name.
    </para>
   </listitem>
   <listitem>
    <para>
     Optional compression / encryption features are now listed in phpinfo.
    </para>
   </listitem>
  </itemizedlist>
 </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
-->