<?xml version="1.0" encoding="utf-8"?>
<sect1 xml:id="migration84.new-features">
 <title>New Features</title>

 <!-- TODO: Core features for 8.4 -->
 <sect2 xml:id="migration84.new-features.core">
  <title>PHP Core</title>

  <!-- RFC: https://wiki.php.net/rfc/property-hooks -->
  <sect3 xml:id="migration84.new-features.core.property-hooks">
   <title>Property Hooks</title>

   <simpara>
    Object properties may now have additional logic associated with their
    <literal>get</literal> and <literal>set</literal> operations.
    Depending on the usage, that may or may not make the property virtual,
    that is, it has no backing value at all.
   </simpara>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
class Person
{
    // A "virtual" property.  It may not be set explicitly.
    public string $fullName {
        get => $this->firstName . ' ' . $this->lastName;
    }

    // All write operations go through this hook, and the result is what is written.
    // Read access happens normally.
    public string $firstName {
        set => ucfirst(strtolower($value));
    }

    // All write operations go through this hook, which has to write to the backing value itself.
    // Read access happens normally.
    public string $lastName {
        set {
            if (strlen($value) < 2) {
                throw new \InvalidArgumentException('Too short');
            }
            $this->lastName = $value;
        }
    }
}

$p = new Person();

$p->firstName = 'peter';
print $p->firstName; // Prints "Peter"
$p->lastName = 'Peterson';
print $p->fullName; // Prints "Peter Peterson"
]]>
    </programlisting>
   </informalexample>
  </sect3>

  <!-- RFC: https://wiki.php.net/rfc/asymmetric-visibility-v2 -->
  <sect3 xml:id="migration84.new-features.core.asymmetric-property-visibility">
   <title>Asymmetric Property Visibility</title>

   <simpara>
    Object properties may now have their <literal>set</literal> visibility
    controlled separately from the <literal>get</literal> visibility.
   </simpara>
   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
class Example
{
    // The first visibility modifier controls the get-visibility, and the second modifier
    // controls the set-visibility. The get-visibility must not be narrower than set-visibility.
    public protected(set) string $name;

    public function __construct(string $name)
    {
        $this->name = $name;
    }
}
]]>
    </programlisting>
   </informalexample>
  </sect3>

  <!-- RFC: https://wiki.php.net/rfc/lazy-objects -->
  <sect3 xml:id="migration84.new-features.core.lazy-objects">
   <title>Lazy Objects</title>
   <simpara>
    It is now possible to create objects whose initialization is deferred until
    they are accessed. Libraries and frameworks can leverage these lazy objects
    to defer fetching data or dependencies required for initialization.
   </simpara>
   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
class Example
{
    public function __construct(private int $data)
    {
    }

    // ...
}

$initializer = static function (Example $ghost): void {
    // Fetch data or dependencies
    $data = ...;
    // Initialize
    $ghost->__construct($data);
};

$reflector = new ReflectionClass(Example::class);
$object = $reflector->newLazyGhost($initializer);
]]>
    </programlisting>
   </informalexample>
  </sect3>

  <!-- RFC: https://wiki.php.net/rfc/deprecated_attribute -->
  <sect3 xml:id="migration84.new-features.core.deprecated-attribute">
   <title><code>#[\Deprecated]</code> attribute</title>

   <simpara>
    The new <classname>Deprecated</classname> attribute can be used to mark functions, methods,
    and class constants as deprecated. The behavior of functionality deprecated with this
    attribute matches the behavior of the existing deprecation mechanism for functionality
    provided by PHP itself. The only exception is that the emitted error code is
    <constant>E_USER_DEPRECATED</constant> instead of <constant>E_DEPRECATED</constant>.
   </simpara>

   <simpara>
    Existing deprecations in functionality provided by PHP itself have been updated to use
    the attribute, improving the emitted error messages by including a short explanation.
   </simpara>
  </sect3>

  <!-- RFC: https://wiki.php.net/rfc/rfc1867-non-post -->
  <sect3 xml:id="migration84.new-features.core.rfc1867">
   <title>Parsing RFC1867 (multipart) requests in non-POST HTTP requests</title>

   <!-- TODO: expand? -->
   <simpara>
    Added <function>request_parse_body</function> function that allows parsing
    RFC1867 (multipart) requests in non-POST HTTP requests.
   </simpara>
  </sect3>

  <!-- RFC: https://wiki.php.net/rfc/new_without_parentheses -->
  <sect3 xml:id="migration84.new-features.core.new-chaining">
   <title>Chaining &new; expressions without parentheses</title>

   <!-- TODO: expand and examples? -->
   <simpara>
    New expressions with constructor arguments are now dereferencable, meaning
    they allow chaining method calls, property accesses, etc. without enclosing
    the expression in parentheses.
   </simpara>
  </sect3>

  <sect3 xml:id="migration84.new-features.core.debug-weakref">
   <title>Improved Debugging Info for <classname>WeakReference</classname></title>

   <!-- TODO: expand and examples? -->
   <simpara>
    Getting the debug info for <classname>WeakReference</classname> will now
    also output the object it references, or &null; if the reference is no
    longer valid.
   </simpara>
  </sect3>

  <sect3 xml:id="migration84.new-features.core.debug-closure">
   <title>Improved Debugging Info for <classname>Closure</classname></title>

   <!-- TODO: expand and examples? -->
   <simpara>
    The output of <methodname>Closure::__debugInfo</methodname> now includes
    the name, file, and line of the <classname>Closure</classname>.
   </simpara>
  </sect3>

  <!-- Is this really a feature? Should this be moved to other changes? -->
  <sect3 xml:id="migration84.new-features.core.multiple-namespaces-symbols">
   <title>Defining Identical Symbols in Different Namespace Blocks</title>

   <!-- TODO: expand and examples? -->
   <simpara>
    Exiting a namespace now clears seen symbols.
    This allows using a symbol in a namespace block, even if a previous
    namespace block declared a symbol with the same name.
    <!-- See Zend/tests/use_function/ns_end_resets_seen_symbols_1.phpt. -->
   </simpara>
  </sect3>

 </sect2>

 <sect2 xml:id="migration84.new-features.curl">
  <title>cURL</title>

  <simpara>
   <function>curl_version</function> returns an additional
   <literal>feature_list</literal> value, which is an associative array
   of all known cURL features, and whether they are supported (&true;)
   or not (&false;).
  </simpara>

  <simpara>
   Added <constant>CURL_HTTP_VERSION_3</constant> and
   <constant>CURL_HTTP_VERSION_3ONLY</constant> constants (available
   since libcurl 7.66 and 7.88) as available options for
   <constant>CURLOPT_HTTP_VERSION</constant>.
  </simpara>

  <simpara>
   Added <constant>CURLOPT_PREREQFUNCTION</constant> as a cURL option that
   accepts a <type>callable</type> to be called after the connection is made,
   but before the request is sent.
   This callable must return either <constant>CURL_PREREQFUNC_OK</constant> or
   <constant>CURL_PREREQFUNC_ABORT</constant> to allow or abort the request.
  </simpara>

  <simpara>
   Added <constant>CURLOPT_SERVER_RESPONSE_TIMEOUT</constant>,
   which was formerly known as <constant>CURLOPT_FTP_RESPONSE_TIMEOUT</constant>.
   Both constants hold the same value.
  </simpara>

  <para>
   Added <constant>CURLOPT_DEBUGFUNCTION</constant> as a cURL option that
   accepts a <type>callable</type> that gets called during the request lifetime
   with the <classname>CurlHandle</classname> object,
   an integer containing the debug message type, and a string containing the
   debug message.
   The debug message type is one of the following constants:
   <simplelist>
    <member><constant>CURLINFO_TEXT</constant></member>
    <member><constant>CURLINFO_HEADER_IN</constant></member>
    <member><constant>CURLINFO_HEADER_OUT</constant></member>
    <member><constant>CURLINFO_DATA_IN</constant></member>
    <member><constant>CURLINFO_DATA_OUT</constant></member>
    <member><constant>CURLINFO_SSL_DATA_IN</constant></member>
    <member><constant>CURLINFO_SSL_DATA_OUT</constant></member>
   </simplelist>
   Once this option is set, <constant>CURLINFO_HEADER_OUT</constant>
   must not be set because it uses the same libcurl functionality.
  </para>

  <simpara>
   The <function>curl_getinfo</function> now returns an additional
   <literal>posttransfer_time_us</literal> key, containing the number of
   microseconds from the start until the last byte is sent.
   When a redirect is followed, the time from each request is added together.
   This value can also be retrieved by passing
   <constant>CURLINFO_POSTTRANSFER_TIME_T</constant> to the
   <function>curl_getinfo</function> <parameter>option</parameter> parameter.
   This requires libcurl 8.10.0 or later.
  </simpara>
 </sect2>

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

  <!-- RFC: https://wiki.php.net/rfc/domdocument_html5_parser -->
  <!-- RFC: https://wiki.php.net/rfc/opt_in_dom_spec_compliance -->
  <simpara>
   Added the <package>Dom</package> namespace with new classes as counterparts
   to the existing DOM classes (e.g. <classname>Dom\Node</classname> is the new
   <classname>DOMNode</classname>).
   These classes are compatible with HTML 5 and are WHATWG spec-compliant;
   solving long-standing bugs in the DOM extension.
   The old DOM classes remain available for backwards compatibility.
  </simpara>

  <para>
   Added the <methodname>DOMNode::compareDocumentPosition</methodname>
   with its associated constants:
   <simplelist>
    <member><constant>DOMNode::DOCUMENT_POSITION_DISCONNECTED</constant></member>
    <member><constant>DOMNode::DOCUMENT_POSITION_PRECEDING</constant></member>
    <member><constant>DOMNode::DOCUMENT_POSITION_FOLLOWING</constant></member>
    <member><constant>DOMNode::DOCUMENT_POSITION_CONTAINS</constant></member>
    <member><constant>DOMNode::DOCUMENT_POSITION_CONTAINED_BY</constant></member>
    <member><constant>DOMNode::DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC</constant></member>
   </simplelist>
  </para>

  <!-- RFC: https://wiki.php.net/rfc/improve_callbacks_dom_and_xsl -->
  <simpara>
   It is now possible to pass any callable to
   <methodname>DOMXPath::registerPhpFunctions</methodname>.

   Furthermore, with <methodname>DOMXPath::registerPhpFunctionNs</methodname>,
   callbacks can now be registered that will use native function call syntax
   rather than using <code>php:function('name')</code>.
  </simpara>
 </sect2>

 <sect2 xml:id="migration84.new-features.intl">
  <title>Intl</title>

  <simpara>
   Added the <constant>NumberFormatter::ROUND_HALFODD</constant> to
   complement the existing <constant>NumberFormatter::ROUND_HALFEVEN</constant>
   functionality.
  </simpara>
 </sect2>

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

  <simpara>
   Added support for Curve25519 + Curve448 based keys.
   Specifically x25519, ed25519, x448 and ed448 fields are supported in
   <function>openssl_pkey_new</function>,
   <function>openssl_pkey_get_details</function>,
   <function>openssl_sign</function>, and
   <function>openssl_verify</function> were extended to support those keys.
  </simpara>

  <simpara>
   Implement PASSWORD_ARGON2 password hashing.
   Requires OpenSSL 3.2 and NTS build.
  </simpara>
 </sect2>

 <sect2 xml:id="migration84.new-features.pcre">
  <title>PCRE</title>

  <simpara>
   The bundled pcre2lib has been updated to version 10.44.
   As a consequence, LoongArch JIT support has been added, spaces
   are now allowed between braces in Perl-compatible items, and
   variable-length lookbehind assertions are now supported.
  </simpara>

  <simpara>
   With pcre2lib version 10.44, the maximum length of named capture groups
   has changed from <literal>32</literal> to <literal>128</literal>.
  </simpara>

  <simpara>
   Added support for the <literal>r</literal> (PCRE2_EXTRA_CASELESS_RESTRICT)
   modifier, as well as the <literal>(?r)</literal> mode modifier.
   When enabled along with the case-insensitive modifier (<literal>i</literal>),
   the expression locks out mixing of ASCII and non-ASCII characters.
  </simpara>
 </sect2>

 <sect2 xml:id="migration84.new-features.pdo">
  <title>PDO</title>

  <!-- RFC: https://wiki.php.net/rfc/pdo_driver_specific_subclasses -->
  <simpara>
   Added support for driver-specific subclasses.
   This RFC adds subclasses for PDO in order to better support
   database-specific functionalities.
   The new classes are instantiatable either via calling the
   <methodname>PDO::connect</methodname> method or by instantiating an instance
   of the driver-specific subclass directly.
  </simpara>

  <!-- RFC: https://wiki.php.net/rfc/pdo_driver_specific_parsers -->
  <para>
   Added support for driver specific SQL parsers.
   The default parser supports:
   <simplelist>
    <member>
     single and double-quoted literals, with doubling as escaping mechanism
    </member>
    <member>
     two-dashes and non-nested C-style comments
    </member>
   </simplelist>
  </para>
 </sect2>

 <sect2 xml:id="migration84.new-features.pdo-mysql">
  <title>PDO_MYSQL</title>

  <!-- RFC: https://wiki.php.net/rfc/pdo_driver_specific_parsers -->
  <para>
   Added a custom parser supporting:
   <simplelist>
    <member>
     single and double-quoted literals, with doubling and backslash as escaping
     mechanism
    </member>
    <member>
     backtick literal identifiers and with doubling as escaping mechanism
    </member>
    <member>
     two dashes followed by at least 1 whitespace, non-nested C-style comments,
     and hash-comments
    </member>
   </simplelist>
  </para>
 </sect2>

 <sect2 xml:id="migration84.new-features.pdo-pgsql">
  <title>PDO_PGSQL</title>

  <!-- RFC: https://wiki.php.net/rfc/pdo_driver_specific_parsers -->
  <para>
   Added a custom parser supporting:
   <simplelist>
    <member>
     single and double-quoted literals, with doubling as escaping mechanism
    </member>
    <member>
     C-style "escape" string literals (<literal>E'string'</literal>)
    </member>
    <member>
     dollar-quoted string literals
    </member>
    <member>
     two-dashes and C-style comments (non-nested)
    </member>
    <member>
     support for <literal>??</literal> as escape sequence for the
     <literal>?</literal> operator
    </member>
   </simplelist>
  </para>
 </sect2>

 <sect2 xml:id="migration84.new-features.pdo-sqlite">
  <title>PDO_SQLITE</title>

  <!-- RFC: https://wiki.php.net/rfc/pdo_driver_specific_parsers -->
  <para>
   Added a custom parser supporting:
   <simplelist>
    <member>
     single, double-quoted, and backtick literals, with doubling as
     escaping mechanism
    </member>
    <member>
     square brackets quoting for identifiers
    </member>
    <member>
     two-dashes and C-style comments (non-nested)
    </member>
   </simplelist>
  </para>
 </sect2>

 <sect2 xml:id="migration84.new-features.phar">
  <title>Phar</title>

  <simpara>
   Added support for the Unix timestamp extension for Zip archives.
  </simpara>
 </sect2>

 <sect2 xml:id="migration84.new-features.readline">
  <title>Readline</title>

  <simpara>
   Added ability to change the <literal>.php_history</literal> path through
   the <envar>PHP_HISTFILE</envar> environment variable.
  </simpara>
 </sect2>

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

  <simpara>
   <classname>ReflectionAttribute</classname> now contains a
   <property>name</property> property to improve the debugging experience.
  </simpara>

  <simpara>
   <methodname>ReflectionClassConstant::__toString</methodname> and
   <methodname>ReflectionProperty::__toString</methodname> now returns the
   attached doc comments.
  </simpara>

  <!-- RFC: https://wiki.php.net/rfc/lazy-objects -->
  <para>
   Multiple new methods and constants which are related to the lazy objects
   feature have been added:

   <simplelist>
    <member>
     <methodname>ReflectionClass::newLazyGhost</methodname>
    </member>
    <member>
     <methodname>ReflectionClass::newLazyProxy</methodname>
    </member>
    <member>
     <methodname>ReflectionClass::resetAsLazyGhost</methodname>
    </member>
    <member>
     <methodname>ReflectionClass::resetAsLazyProxy</methodname>
    </member>
    <member>
     <methodname>ReflectionClass::isUninitializedLazyObject</methodname>
    </member>
    <member>
     <methodname>ReflectionClass::initializeLazyObject</methodname>
    </member>
    <member>
     <methodname>ReflectionClass::markLazyObjectAsInitialized</methodname>
    </member>
    <member>
     <methodname>ReflectionClass::getLazyInitializer</methodname>
    </member>
    <member>
     <methodname>ReflectionProperty::skipLazyInitialization</methodname>
    </member>
    <member>
     <methodname>ReflectionProperty::setRawValueWithoutLazyInitialization</methodname>
    </member>
    <member>
     <constant>ReflectionClass::SKIP_INITIALIZATION_ON_SERIALIZE</constant>
    </member>
    <member>
     <constant>ReflectionClass::SKIP_DESTRUCTOR</constant>
    </member>
   </simplelist>
  </para>
 </sect2>

 <sect2 xml:id="migration84.new-features.soap">
  <title>SOAP</title>

  <simpara>
   Added support for clark notation for namespaces in class map.
   It is now possible to specify entries in a class map with clark notation
   to resolve a type with a specific namespace to a specific class.
   For example: <code>'{http://example.com}foo' => 'FooClass'</code>.
  </simpara>

  <simpara>
   Instances of <interfacename>DateTimeInterface</interfacename> that are
   passed to <literal>xsd:datetime</literal> or similar elements are now
   serialized as such instead of being serialized as an empty string.
  </simpara>

  <simpara>
   Session persistence now works with a shared session module.
  </simpara>
 </sect2>

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

  <!-- RFC: https://wiki.php.net/rfc/correctly_name_the_rounding_mode_and_make_it_an_enum -->
  <simpara>
   <!-- Should this use <enumname> -->
   Added a new <classname>RoundingMode</classname> enum with clearer naming
   and improved discoverability compared to the
   <constant>PHP_ROUND_<replaceable>*</replaceable></constant> constants.
   Moreover, four new rounding modes were added which are only available via
   the new <classname>RoundingMode</classname> enum.
  </simpara>
 </sect2>

 <sect2 xml:id="migration84.new-features.xsl">
  <title>XSL</title>

  <simpara>
   It is now possible to use parameters that contain both single and double
   quotes.
  </simpara>

  <!-- RFC: https://wiki.php.net/rfc/improve_callbacks_dom_and_xsl -->
  <simpara>
   It is now possible to pass any callable to
   <methodname>XSLTProcessor::registerPhpFunctions</methodname>.
   <!-- TODO Mention XSLTProcessor::registerPHPFunctionNS ? -->
  </simpara>

  <simpara>
   Added <property>XSLTProcessor::$maxTemplateDepth</property> and
   <property>XSLTProcessor::$maxTemplateVars</property>
   to control the recursion depth of XSL template evaluation.
  </simpara>
 </sect2>

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

  <simpara>
   Added the <constant>ZipArchive::ER_TRUNCATED_ZIP</constant>
   constant, which was added in libzip 1.11.
  </simpara>
 </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
-->