From e90e9ce9c8475b8d9b38837a210c1fe5d2ccfb98 Mon Sep 17 00:00:00 2001
From: Peter Cowburn <salathe@php.net>
Date: Thu, 12 Sep 2019 06:53:54 +0000
Subject: [PATCH] wip - migration74 appendix

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@347981 c90b9560-bf6c-de11-be94-00142212c4b1
---
 appendices/migration74.xml                 |  53 +++
 appendices/migration74/constants.xml       |  32 ++
 appendices/migration74/deprecated.xml      |  32 ++
 appendices/migration74/incompatible.xml    |  32 ++
 appendices/migration74/new-features.xml    | 398 +++++++++++++++++++++
 appendices/migration74/new-functions.xml   |  32 ++
 appendices/migration74/other-changes.xml   |  32 ++
 appendices/migration74/windows-support.xml |  32 ++
 8 files changed, 643 insertions(+)
 create mode 100644 appendices/migration74.xml
 create mode 100644 appendices/migration74/constants.xml
 create mode 100644 appendices/migration74/deprecated.xml
 create mode 100644 appendices/migration74/incompatible.xml
 create mode 100644 appendices/migration74/new-features.xml
 create mode 100644 appendices/migration74/new-functions.xml
 create mode 100644 appendices/migration74/other-changes.xml
 create mode 100644 appendices/migration74/windows-support.xml

diff --git a/appendices/migration74.xml b/appendices/migration74.xml
new file mode 100644
index 0000000000..f434e979dc
--- /dev/null
+++ b/appendices/migration74.xml
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<appendix xml:id="migration74" xmlns="http://docbook.org/ns/docbook" xmlns:phd="http://www.php.net/ns/phd">
+ <title>Migrating from PHP 7.3.x to PHP 7.4.x</title>
+
+ &appendices.migration74.new-features;
+ &appendices.migration74.new-functions;
+ &appendices.migration74.constants;
+ &appendices.migration74.incompatible;
+ &appendices.migration74.deprecated;
+ &appendices.migration74.other-changes;
+ &appendices.migration74.windows-support;
+
+ <sect1 phd:chunk="false" xml:id="migration74.intro">
+  <para>
+   This new minor version brings with it a number of
+   <link linkend="migration74.new-features">new features</link> and a
+   <link linkend="migration74.incompatible">few incompatibilities</link>
+   that should be tested for before switching PHP versions in production
+   environments.
+  </para>
+
+  <para>
+   &manual.migration.seealso;
+   <link linkend="migration70">7.0.x</link>,
+   <link linkend="migration71">7.1.x</link>,
+   <link linkend="migration72">7.2.x</link> and
+   <link linkend="migration73">7.3.x</link>.
+  </para>
+ </sect1>
+</appendix>
+
+<!-- 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
+-->
diff --git a/appendices/migration74/constants.xml b/appendices/migration74/constants.xml
new file mode 100644
index 0000000000..612089b834
--- /dev/null
+++ b/appendices/migration74/constants.xml
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<sect1 xml:id="migration74.constants" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <title>New Global Constants</title>
+
+ <para>
+  <!-- TODO -->
+ </para>
+
+</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
+-->
diff --git a/appendices/migration74/deprecated.xml b/appendices/migration74/deprecated.xml
new file mode 100644
index 0000000000..d208de3e54
--- /dev/null
+++ b/appendices/migration74/deprecated.xml
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<sect1 xml:id="migration74.deprecated">
+ <title>Deprecated Features</title>
+
+ <para>
+  <!-- TODO -->
+ </para>
+
+</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
+-->
diff --git a/appendices/migration74/incompatible.xml b/appendices/migration74/incompatible.xml
new file mode 100644
index 0000000000..75e9b8d9be
--- /dev/null
+++ b/appendices/migration74/incompatible.xml
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<sect1 xml:id="migration74.incompatible" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <title>Backward Incompatible Changes</title>
+
+ <para>
+  <!-- TODO -->
+ </para>
+
+</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
+-->
diff --git a/appendices/migration74/new-features.xml b/appendices/migration74/new-features.xml
new file mode 100644
index 0000000000..9d23d3f9bf
--- /dev/null
+++ b/appendices/migration74/new-features.xml
@@ -0,0 +1,398 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<sect1 xml:id="migration74.new-features" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <title>New Features</title>
+
+ <sect2 xml:id="migration74.new-features.core">
+  <title>PHP Core</title>
+
+  <sect3 xml:id="migration74.new-features.core.typed-properties">
+   <title>Typed properties</title>
+
+   <para>
+    Class properties now support type declarations.
+    <informalexample>
+     <programlisting role="php">
+<![CDATA[
+<?php
+class User {
+    public int $id;
+    public string $name;
+}
+?>
+]]>
+     </programlisting>
+    </informalexample>
+    The above example will enforce that <literal>$user->id</literal> can only be
+    assigned <type>integer</type> values and <literal>$user->name</literal> can
+    only be assigned <type>string</type> values.
+   </para>
+  </sect3>
+
+  <sect3 xml:id="migration74.new-features.core.arrow-functions">
+   <title>Arrow functions</title>
+
+   <para>
+    Arrow functions provide a shorthand syntax for defining functions
+    with implicit by-value scope binding.
+
+    <informalexample>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$factor = 10;
+$nums = array_map(fn($n) => $n * $factor, [1, 2, 3, 4]);
+// $nums = array(10, 20, 30, 40);
+?>
+]]>
+     </programlisting>
+    </informalexample>
+   </para>
+  </sect3>
+
+  <sect3 xml:id="migration74.new-features.core.type-variance">
+   <title>Limited return type covariance and argument type contravariance</title>
+
+   <para>
+    The following code will now work:
+    <informalexample>
+     <programlisting role="php">
+<![CDATA[
+<?php
+class A {}
+class B extends A {}
+
+class Producer {
+    public function method(): A {}
+}
+class ChildProducer extends Producer {
+    public function method(): B {}
+}
+?>
+]]>
+     </programlisting>
+    </informalexample>
+    Full variance support is only available if autoloading is used. Inside a
+    single file only non-cyclic type references are possible, because all
+    classes need to be available before they are referenced.
+   </para>
+  </sect3>
+
+  <sect3 xml:id="migration74.new-features.core.null-coalescing-assignment-operator">
+   <title>Null coalescing assignment operator</title>
+
+   <para>
+    <informalexample>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$array['key'] ??= computeDefault();
+// is roughly equivalent to
+if (!isset($array['key'])) {
+    $array['key'] = computeDefault();
+}
+?>
+]]>
+     </programlisting>
+    </informalexample>
+   </para>
+  </sect3>
+
+  <sect3 xml:id="migration74.new-features.core.unpack-inside-array">
+   <title>Unpacking inside arrays</title>
+
+   <para>
+    <informalexample>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$parts = ['apple', 'pear'];
+$fruits = ['banana', 'orange', ...$parts, 'watermelon'];
+// ['banana', 'orange', 'apple', 'pear', 'watermelon'];
+?>
+]]>
+     </programlisting>
+    </informalexample>
+   </para>
+  </sect3>
+
+  <sect3 xml:id="migration74.new-features.core.numeric-literal-separator">
+   <title>Numeric literal separator</title>
+
+   <para>
+    Numeric literals can contain underscores between digits.
+    <informalexample>
+     <programlisting role="php">
+<![CDATA[
+<?php
+6.674_083e-11; // float
+299_792_458;   // decimal
+0xCAFE_F00D;   // hexadecimal
+0b0101_1111;   // binary
+?>
+]]>
+     </programlisting>
+    </informalexample>
+   </para>
+  </sect3>
+ 
+  <sect3 xml:id="migration74.new-features.core.weakreference">
+   <title>Weak references</title>
+
+   <para>
+    Weak references allow the programmer to retain a reference to an object
+    that does not prevent the object from being destroyed.
+   </para>
+  </sect3>
+
+  <sect3 xml:id="migration74.new-features.core.tostring-exceptions">
+   <title>Allow exceptions from __toString()</title>
+
+   <para>
+    Throwing exceptions from <link linkend="object.tostring">__toString()</link>
+    is now permitted. Previously this resulted in a fatal error. Existing
+    recoverable fatal errors in string conversions have been converted to
+    <classname>Error</classname> exceptions.
+   </para>
+  </sect3>
+
+ </sect2>
+
+ <sect2 xml:id="migration74.new-features.curl">
+  <title>CURL</title>
+  
+  <para>
+   <classname>CURLFile</classname> now supports stream wrappers in addition
+   to plain file names, if the extension has been built against libcurl &gt;= 7.56.0.
+  </para>
+ </sect2>
+
+ <sect2 xml:id="migration74.new-features.filter">
+  <title>Filter</title>
+  
+  <para>
+   The <constant>FILTER_VALIDATE_FLOAT</constant> filter now supports the
+   <literal>min_range</literal> and <literal>max_range</literal>
+   options, with the same semantics as <constant>FILTER_VALIDATE_INT</constant>.
+  </para>
+ </sect2>
+
+ <sect2 xml:id="migration74.new-features.ffi">
+  <title>FFI</title>
+
+  <para>
+   FFI is a new extension, which provides a simple way to call
+   native functions, access native variables, and create/access
+   data structures defined in C libraries.
+  </para>
+ </sect2>
+
+ <sect2 xml:id="migration74.new-features.gd">
+  <title>GD</title>
+
+  <para>
+   Added the <constant>IMG_FILTER_SCATTER</constant> image filter
+   to apply a scatter filter to images.
+  </para>
+ </sect2>
+
+ <sect2 xml:id="migration74.new-features.hash">
+  <title>Hash</title>
+
+  <para>
+   Added <literal>crc32c</literal> hash using Castagnoli's polynomial.
+   This crc32 variant is used by storage systems, such as
+   iSCSI, SCTP, Btrfs and ext4.
+  </para>
+ </sect2>
+
+ <sect2 xml:id="migration74.new-features.mbstring">
+  <title>Multibyte String Functions</title>
+
+  <para>
+   Added the <function>mb_str_split</function> function, which provides
+   the same functionality as <function>str_split</function>, but operating
+   on code points rather than bytes.
+  </para>
+ </sect2>
+
+ <sect2 xml:id="migration74.new-features.opcache">
+  <title>OPcache</title>
+
+  <para>
+   Support for preloading code has been added.
+  </para>
+ </sect2>
+
+ <sect2 xml:id="migration74.new-features.pcre">
+  <title>PCRE</title>
+
+  <para>
+   The <function>preg_replace_callback</function> and <function>preg_replace_callback_array</function>
+   functions now accept an additional <parameter>flags</parameter> argument, with support for the
+   <constant>PREG_OFFSET_CAPTURE</constant> and <constant>PREG_UNMATCHED_AS_NULL</constant> flags.
+   This influences the format of the matches array passed to to the callback function.
+  </para>
+ </sect2>
+
+ <sect2 xml:id="migration74.new-features.pdo">
+  <title>PDO</title>
+
+  <para>
+   The username and password can now be specified as part of the PDO DSN for
+   the mysql, mssql, sybase, dblib, firebird and oci drivers. Previously this
+   was only supported by the pgsql driver. If a username/password is specified
+   both in the constructor and the DSN, the constructor takes precedence.
+  </para>
+ </sect2>
+
+ <sect2 xml:id="migration74.new-features.pdo_oci">
+  <title>PDO_OCI</title>
+
+  <para>
+   <methodname>PDOStatement::getColumnMeta</methodname> is now available.
+  </para>
+ </sect2>
+
+ <sect2 xml:id="migration74.new-features.pdo_sqlite">
+  <title>PDO_SQLite</title>
+
+  <para>
+   <literal>PDOStatement::getAttribute(PDO::SQLITE_ATTR_READONLY_STATEMENT)</literal>
+   allows checking whether the statement is read-only, i.e. if it doesn't modify
+   the database.
+  </para>
+  <para>
+   <literal>PDO::setAttribute(PDO::SQLITE_ATTR_EXTENDED_RESULT_CODES, true)</literal>
+   enables the use of SQLite3 extended result codes in errorInfo().
+  </para>
+ </sect2>
+
+ <sect2 xml:id="migration74.new-features.sqlite3">
+  <title>SQLite3</title>
+
+  <para>
+   Added <methodname>SQLite3::lastExtendedErrorCode</methodname>
+   to fetch the last extended result code.
+  </para>
+  <para>
+   Added <literal>SQLite3::enableExtendedResultCodes($enable = true)</literal>,
+   which will make <methodname>SQLite3::lastErrorCode</methodname>
+   return extended result codes.
+  </para>
+ </sect2>
+
+ <sect2 xml:id="migration74.new-features.standard">
+  <title>Standard</title>
+
+  <sect3 xml:id="migration74.new-features.standard.strip-tags">
+   <title>strip_tags() with array of tag names</title>
+   <para>
+    <function>strip_tags</function> now also accepts an array of allowed tags:
+    instead of <literal>strip_tags($str, '&lt;a&gt;&lt;p&gt;')</literal>
+    you can now write <literal>strip_tags($str, ['a', 'p'])</literal>.
+   </para>
+  </sect3>
+
+  <sect3 xml:id="migration74.new-features.standard.magic-serialize">
+   <title>Custom object serialization</title>
+   <para>
+    A new mechanism for custom object serialization has been added, which
+    uses two new magic methods: <literal>__serialize</literal>
+    and <literal>__unserialize</literal>.
+    <informalexample>
+     <programlisting role="php">
+<![CDATA[
+<?php
+// Returns array containing all the necessary state of the object.
+public function __serialize(): array;
+
+// Restores the object state from the given data array.
+public function __unserialize(array $data): void;
+?>
+]]>
+     </programlisting>
+    </informalexample>
+    The new serialization mechanism supersedes the
+    <interfacename>Serializable</interfacename> interface,
+    which will be deprecated in the future.
+   </para>
+  </sect3>
+
+  <sect3 xml:id="migration74.new-features.standard.array-merge-no-args">
+   <title>Array merge functions without arguments</title>
+   <para>
+    <function>array_merge</function> and <function>array_merge_recursive</function>
+    may now be called without any arguments, in which case they will return an empty array.
+    This is useful in conjunction with the spread operator, e.g. <literal>array_merge(...$arrays)</literal>.
+   </para>
+  </sect3>
+
+  <sect3 xml:id="migration74.new-features.standard.proc-open">
+   <title>Array merge functions without arguments</title>
+   <para>
+    <function>proc_open</function> now accepts an array instead of a
+    string for the command. In this case the process will be opened
+    directly (without going through a shell) and PHP will take care of
+    any necessary argument escaping.
+    <informalexample>
+     <programlisting role="php">
+<![CDATA[
+<?php
+proc_open(['php', '-r', 'echo "Hello World\n";'], $descriptors, $pipes);
+?>
+]]>
+     </programlisting>
+    </informalexample>
+   </para>
+   <para>
+    <function>proc_open</function> now supports
+    <literal>redirect</literal> and <literal>null</literal> descriptors.
+    <informalexample>
+     <programlisting role="php">
+<![CDATA[
+<?php
+// Like 2>&1 on the shell
+proc_open($cmd, [1 => ['pipe', 'w'], 2 => ['redirect', 1]], $pipes);
+// Like 2>/dev/null or 2>nul on the shell
+proc_open($cmd, [1 => ['pipe', 'w'], 2 => ['null']], $pipes);
+?>
+]]>
+     </programlisting>
+    </informalexample>
+   </para>
+  </sect3>
+
+  <sect3 xml:id="migration74.new-features.standard.sodium-argon-hash">
+   <title>argon2i(d) without libargon</title>
+   <para>
+    <function>password_hash</function> now has the argon2i and argin2id implementations
+    from the sodium extension when PHP is built without libargon.
+   </para>
+  </sect3>
+
+ </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
+-->
diff --git a/appendices/migration74/new-functions.xml b/appendices/migration74/new-functions.xml
new file mode 100644
index 0000000000..77e732af99
--- /dev/null
+++ b/appendices/migration74/new-functions.xml
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<sect1 xml:id="migration74.new-functions">
+ <title>New Functions</title>
+
+ <para>
+  <!-- TODO -->
+ </para>
+
+</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
+-->
diff --git a/appendices/migration74/other-changes.xml b/appendices/migration74/other-changes.xml
new file mode 100644
index 0000000000..696caa81e9
--- /dev/null
+++ b/appendices/migration74/other-changes.xml
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<sect1 xml:id="migration74.other-changes" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <title>Other Changes</title>
+ 
+ <para>
+  <!-- TODO -->
+ </para>
+
+</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
+-->
diff --git a/appendices/migration74/windows-support.xml b/appendices/migration74/windows-support.xml
new file mode 100644
index 0000000000..bb9af8cfee
--- /dev/null
+++ b/appendices/migration74/windows-support.xml
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<sect1 xml:id="migration74.windows-support" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <title>Windows Support</title>
+
+ <para>
+  <!-- TODO -->
+ </para>
+
+</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
+-->