php-doc-en/appendices/migration81/incompatible.xml
Juliette a6a4d6ad6e
PHP 8.1 | Other reserved words: add never
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.
2022-03-01 10:28:24 +01:00

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>&amp;#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>&amp;</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
-->