mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 08:28:54 +00:00

Similar to PR 938 for the PHP 8.0 `mixed` reserved word, this commit adds the new reserved word `never` to the list of "Other reserved words" and adds a mention of this to the Backward Incompatible Changes page in the migration guide. Co-authored-by: jrfnl <jrfnl@users.noreply.github.com> Closes GH-1434.
410 lines
13 KiB
XML
410 lines
13 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<sect1 xml:id="migration81.incompatible" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<title>Backward Incompatible Changes</title>
|
|
|
|
<sect2 xml:id="migration81.incompatible.core">
|
|
<title>PHP Core</title>
|
|
|
|
<sect3 xml:id="migration81.incompatible.core.globals-access">
|
|
<title>$GLOBALS Access Restrictions</title>
|
|
|
|
<para>
|
|
Access to the <varname>$GLOBALS</varname> array is now subject to
|
|
a number of restrictions.
|
|
Read and write access to individual array elements like
|
|
<code>$GLOBALS['var']</code> continues to work as-is.
|
|
Read-only access to the entire <varname>$GLOBALS</varname> array also
|
|
continues to be supported.
|
|
However, write access to the entire <varname>$GLOBALS</varname> array
|
|
is no longer supported. For example, <code>array_pop($GLOBALS)</code>
|
|
will result in an error.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="migration81.incompatible.core.static-variable-inheritance">
|
|
<title>
|
|
Usage of <modifier>static</modifier> Variables in Inherited Methods
|
|
</title>
|
|
|
|
<para>
|
|
When a method using static variables is inherited (but not overridden), the
|
|
inherited method will now share static variables with the parent method.
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
class A {
|
|
public static function counter() {
|
|
static $counter = 0;
|
|
$counter++;
|
|
return $counter;
|
|
}
|
|
}
|
|
class B extends A {}
|
|
var_dump(A::counter()); // int(1)
|
|
var_dump(A::counter()); // int(2)
|
|
var_dump(B::counter()); // int(3), previously int(1)
|
|
var_dump(B::counter()); // int(4), previously int(2)
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
|
|
This means that static variables in methods now behave the same way as
|
|
static properties.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="migration81.incompatible.core.optional-before-required">
|
|
<title>Optional parameters specified before required parameters</title>
|
|
|
|
<para>
|
|
An <link linkend="functions.arguments.default">optional parameter</link>
|
|
specified before required parameters is now always treated as required,
|
|
even when called using
|
|
<link linkend="functions.named-arguments">named arguments</link>.
|
|
As of PHP 8.0.0, but prior to PHP 8.1.0, the below emits a deprecation notice
|
|
on the definition, but runs successfully when called. As of PHP 8.1.0, an error
|
|
of class <classname>ArgumentCountError</classname> is thrown, as it would be when
|
|
called with positional arguments.
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
function makeyogurt($container = "bowl", $flavour)
|
|
{
|
|
return "Making a $container of $flavour yogurt.\n";
|
|
}
|
|
try
|
|
{
|
|
echo makeyogurt(flavour: "raspberry");
|
|
}
|
|
catch (Error $e)
|
|
{
|
|
echo get_class($e), ' - ', $e->getMessage(), "\n";
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs.80;
|
|
<screen>
|
|
<![CDATA[
|
|
Deprecated: Required parameter $flavour follows optional parameter $container
|
|
in example.php on line 3
|
|
Making a bowl of raspberry yogurt.
|
|
]]>
|
|
</screen>
|
|
&example.outputs.81;
|
|
<screen>
|
|
<![CDATA[
|
|
Deprecated: Optional parameter $container declared before required parameter
|
|
$flavour is implicitly treated as a required parameter in example.php on line 3
|
|
ArgumentCountError - makeyogurt(): Argument #1 ($container) not passed
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
Note that a default value of &null; can be used before required parameters to
|
|
specify a <link linkend="language.types.declarations.nullable">nullable type</link>,
|
|
but the parameter will still be required.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="migration81.incompatible.core.type-compatibility-internal">
|
|
<title>Return Type Compatibility with Internal Classes</title>
|
|
|
|
<para>
|
|
Most non-final internal methods now require overriding methods to declare
|
|
a compatible return type, otherwise a deprecated notice is emitted during
|
|
inheritance validation.
|
|
In case the return type cannot be declared for an overriding method due to
|
|
PHP cross-version compatibility concerns,
|
|
a <code>#[ReturnTypeWillChange]</code> attribute can be added to silence
|
|
the deprecation notice.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="migration81.incompatible.core.new-keywords">
|
|
<title>New Keywords</title>
|
|
<para>
|
|
<literal>readonly</literal> is a keyword now. However, it still may be used
|
|
as function name.
|
|
</para>
|
|
<para>
|
|
<literal>never</literal> is now a reserved word, so it cannot be used to name a class,
|
|
interface or trait, and is also prohibited from being used in namespaces.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration81.incompatible.resource2object">
|
|
<title>Resource to Object Migration</title>
|
|
|
|
<para>
|
|
Several &resource;s have been migrated to &object;s.
|
|
Return value checks using <function>is_resource</function> should be replaced with checks for &false;.
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
The <link linkend="book.fileinfo">FileInfo</link> functions now accept and return
|
|
<classname>finfo</classname> objects instead of
|
|
<literal>fileinfo</literal> &resource;s.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The <link linkend="book.ftp">FTP</link> functions now accept and return
|
|
<classname>FTP\Connection</classname> objects instead of
|
|
<literal>ftp</literal> &resource;s.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The <link linkend="book.imap">IMAP</link> functions now accept and return
|
|
<classname>IMAP\Connection</classname> objects instead of
|
|
<literal>imap</literal> &resource;s.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The <link linkend="book.ldap">LDAP</link> functions now accept and return
|
|
<classname>LDAP\Connection</classname> objects instead of
|
|
<literal>ldap link</literal> &resource;s.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The <link linkend="book.ldap">LDAP</link> functions now accept and return
|
|
<classname>LDAP\Result</classname> objects instead of
|
|
<literal>ldap result</literal> &resource;s.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The <link linkend="book.ldap">LDAP</link> functions now accept and return
|
|
<classname>LDAP\ResultEntry</classname> objects instead of
|
|
<literal>ldap result entry</literal> &resource;s.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The <link linkend="book.pgsql">PgSQL</link> functions now accept and return
|
|
<classname>PgSql\Connection</classname> objects instead of
|
|
<literal>pgsql link</literal> &resource;s.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The <link linkend="book.pgsql">PgSQL</link> functions now accept and return
|
|
<classname>PgSql\Result</classname> objects instead of
|
|
<literal>pgsql result</literal> &resource;s.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The <link linkend="book.pgsql">PgSQL</link> functions now accept and return
|
|
<classname>PgSql\Lob</classname> objects instead of
|
|
<literal>pgsql large object</literal> &resource;s.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The <link linkend="book.pspell">PSpell</link> functions now accept and return
|
|
<classname>PSpell\Dictionary</classname> objects instead of
|
|
<literal>pspell</literal> &resource;s.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The <link linkend="book.pspell">PSpell</link> functions now accept and return
|
|
<classname>PSpell\Config</classname> objects instead of
|
|
<literal>pspell config</literal> &resource;s.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration81.incompatible.mysqli">
|
|
<title>MySQLi</title>
|
|
|
|
<para>
|
|
<function>mysqli_fetch_fields</function>, and
|
|
<function>mysqli_fetch_field_direct</function> will now always return
|
|
<literal>0</literal> for the <property>max_length</property>.
|
|
This information can be computed by iterating over the result set,
|
|
and taking the maximum length. This is what PHP was doing
|
|
internally previously.
|
|
</para>
|
|
|
|
<para>
|
|
The <constant>MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH</constant>
|
|
option no longer has any effect.
|
|
</para>
|
|
|
|
<para>
|
|
The <constant>MYSQLI_STORE_RESULT_COPY_DATA</constant>
|
|
option no longer has any effect. Passing any value to the
|
|
<parameter>mode</parameter> parameter of
|
|
<methodname>mysqli::store_result</methodname> no longer has any effect.
|
|
</para>
|
|
|
|
<para>
|
|
<methodname>mysqli::connect</methodname> now returns &true; instead of &null; on success.
|
|
</para>
|
|
|
|
<para>
|
|
The default error handling mode has been changed from "silent" to "exceptions"
|
|
See the <link linkend="mysqli-driver.report-mode">MySQLi reporting mode</link>
|
|
page for more details on what this entails,
|
|
and how to explicitly set this attribute.
|
|
To restore the previous behaviour use:
|
|
<code>mysqli_report(MYSQLI_REPORT_OFF);</code>
|
|
</para>
|
|
|
|
<para>
|
|
Classes extending <methodname>mysqli_stmt::execute</methodname>
|
|
are now required to specify the additional optional parameter.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration81.incompatible.mysqlnd">
|
|
<title>MySQLnd</title>
|
|
|
|
<para>
|
|
The <link linkend="ini.mysqlnd.fetch_data_copy">mysqlnd.fetch_data_copy</link>
|
|
INI directive has been removed.
|
|
This should not result in user-visible behavior changes.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration81.incompatible.openssl">
|
|
<title>OpenSSL</title>
|
|
|
|
<para>
|
|
EC private keys will now be exported in PKCS#8 format rather than
|
|
traditional format, just like all other keys.
|
|
</para>
|
|
<para>
|
|
<function>openssl_pkcs7_encrypt</function> and
|
|
<function>openssl_cms_encrypt</function> will now to default using
|
|
AES-128-CBC rather than RC2-40. The RC2-40 cipher is considered
|
|
insecure and not enabled by default by OpenSSL 3.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration81.incompatible.pdo">
|
|
<title>PHP Data Objects</title>
|
|
|
|
<para>
|
|
<constant>PDO::ATTR_STRINGIFY_FETCHES</constant> now stringifies values
|
|
of type &boolean; to <literal>"0"</literal> or
|
|
<literal>"1"</literal>. Previously &boolean;s were not stringified.
|
|
</para>
|
|
<para>
|
|
Calling <methodname>PDOStatement::bindColumn</methodname> with
|
|
<constant>PDO::PARAM_LOB</constant> will now constantly bind a stream
|
|
result when <constant>PDO::ATTR_STRINGIFY_FETCHES</constant> is not enabled.
|
|
Previously, the result would either be a stream or a string depending on
|
|
the used database driver and the time the binding is performed.
|
|
</para>
|
|
|
|
<sect3 xml:id="migration81.incompatible.pdo.mysql">
|
|
<title>MySQL Driver</title>
|
|
|
|
<para>
|
|
Integers and floats in result sets will now be returned using native
|
|
PHP types instead of &string;s when using emulated prepared statements.
|
|
This matches the behavior of native prepared statements.
|
|
The previous behaviour can be restored by enabling the
|
|
<constant>PDO::ATTR_STRINGIFY_FETCHES</constant> option.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="migration81.incompatible.pdo.sqlite">
|
|
<title>SQLite Driver</title>
|
|
|
|
<para>
|
|
Integers and floats in results sets will now be returned using native
|
|
PHP types.
|
|
The previous behaviour can be restored by enabling the
|
|
<constant>PDO::ATTR_STRINGIFY_FETCHES</constant> option.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration81.incompatible.phar">
|
|
<title>Phar</title>
|
|
|
|
<para>
|
|
To comply with the <interfacename>ArrayAccess</interfacename> interface,
|
|
<methodname>Phar::offsetUnset</methodname> and
|
|
<methodname>PharData::offsetUnset</methodname> no longer return a &boolean;.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration81.incompatible.standard">
|
|
<title>Standard</title>
|
|
|
|
<para>
|
|
<function>version_compare</function> no longer accepts undocumented operator abbreviations.
|
|
</para>
|
|
|
|
<para>
|
|
<function>htmlspecialchars</function>,
|
|
<function>htmlentities</function>,
|
|
<function>htmlspecialchars_decode</function>,
|
|
<function>html_entity_decode</function>,
|
|
and <function>get_html_translation_table</function>
|
|
now use <literal>ENT_QUOTES | ENT_SUBSTITUTE</literal> rather than
|
|
<constant>ENT_COMPAT</constant> by default.
|
|
This means that <literal>'</literal> is escaped to
|
|
<literal>&#039;</literal> while previously nothing was done.
|
|
Additionally, malformed UTF-8 will be replaced by a Unicode substitution
|
|
character, instead of resulting in an empty string.
|
|
</para>
|
|
|
|
<para>
|
|
<function>debug_zval_dump</function> now prints the refcount of a reference
|
|
wrappers with their refcount, instead of only prepending
|
|
<literal>&</literal> to the value.
|
|
This more accurately models reference representation since PHP 7.0.
|
|
</para>
|
|
|
|
<para>
|
|
<function>debug_zval_dump</function> now prints <literal>interned</literal>
|
|
instead of a dummy refcount for interned strings and immutable arrays.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration81.incompatible.spl">
|
|
<title>Standard PHP Library (SPL)</title>
|
|
|
|
<para>
|
|
<classname>SplFixedArray</classname>, will now be JSON encoded like an &array;
|
|
</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
|
|
-->
|