Add initial version of the PHP 8.2 migration guide #1799

Girgias · 2022-09-06T16:34:14Z

Will need a doc-base change to be added to the live version.

This covers the UPGRADING file.

I think it is best to merge this ASAP and handle adding examples and links in other PRs as needed.

appendices/migration82/deprecated.xml

appendices/migration82/new-features.xml

appendices/migration82/other-changes.xml

cmb69

Thank you very much!

Partial review done; I'll try to review the rest ASAP.

appendices/migration82/constants.xml

appendices/migration82/deprecated.xml

appendices/migration82/other-changes.xml

cmb69

(more review to come :)

appendices/migration82/incompatible.xml

cmb69 · 2022-09-07T10:49:38Z

appendices/migration82/incompatible.xml

+
+  <para>
+   <function>glob</function>  returns empty array if all paths are restricted by open_basedir.
+   Previously the error was returned but that behavior was not consistent and


The error was returned? What does that mean?

@bukka can you clarify?
As I just copy pasted the wording from UPGRADING

Previously if all paths were restricted by open_basedir, false was returned and typical open basedir restriction warning was emitted. The consistency note means that there was no warning if just some paths were restricted.

appendices/migration82/incompatible.xml

appendices/migration82/new-features.xml

appendices/migration82/new-functions.xml

appendices/migration82/other-changes.xml

cmb69 · 2022-09-08T14:56:51Z

appendices/migration82/other-changes.xml

+   <para>
+    <function>dba_open</function> and <function>dba_popen</function>
+    now have the following enforced signature:
+    <methodsynopsis>
+     <type class="union"><type>resource</type><type>false</type></type><methodname>dba_open</methodname>
+     <methodparam><type>string</type><parameter>path</parameter></methodparam>
+     <methodparam><type>string</type><parameter>mode</parameter></methodparam>
+     <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>handler</parameter><initializer>&null;</initializer></methodparam>
+     <methodparam choice="opt"><type>int</type><parameter>permission</parameter><initializer>0644</initializer></methodparam>
+     <methodparam choice="opt"><type>int</type><parameter>map_size</parameter><initializer>0</initializer></methodparam>
+     <methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>flags</parameter><initializer>&null;</initializer></methodparam>
+    </methodsynopsis>
+   </para>
+   <para>
+    <function>dba_fetch</function>'s optional skip argument is now at the end
+    in line with PHP userland semantics. Its signature is now:
+    <methodsynopsis>
+     <type class="union"><type>string</type><type>false</type></type><methodname>dba_fetch</methodname>
+     <methodparam><type class="union"><type>string</type><type>array</type></type><parameter>key</parameter></methodparam>
+     <methodparam><type>resource</type><parameter>handle</parameter></methodparam>
+     <methodparam><type>int</type><parameter>skip</parameter></methodparam>
+    </methodsynopsis>
+
+    The overloaded signature:
+    <methodsynopsis>
+     <type class="union"><type>string</type><type>false</type></type><methodname>dba_fetch</methodname>
+     <methodparam><type class="union"><type>string</type><type>array</type></type><parameter>key</parameter></methodparam>
+     <methodparam><type>int</type><parameter>skip</parameter></methodparam>
+     <methodparam><type>resource</type><parameter>handle</parameter></methodparam>
+    </methodsynopsis>
+    is still accepted, but it is recommended to use the new standard variant.
+   </para>


I'm not sure that we want to be that explicit in the migration guide. Maybe telling users about the signature changes, and then detailing on the respective pages is preferable to avoid duplication.

I think it's better to have it in the migration guide, but maybe that's because I haven't gotten round to writing the doc changes for DBA.

Okay, maybe put it in the migration guide, and later consider to move the details to the actual docs.

appendices/migration82/other-changes.xml

appendices/migration82/windows-support.xml

appendices/migration82/other-changes.xml

Girgias · 2022-09-24T11:26:00Z

I think it's now finally ready.

cmb69

I think some minor issues could be addressed, but overall this looks good to me. Thank you very much!

appendices/migration82/new-features.xml

appendices/migration82/incompatible.xml

cmb69 · 2022-09-24T12:48:58Z

appendices/migration82/incompatible.xml

+  <para>
+   <methodname>SplFileObject::getChildren</methodname> now has a tentative
+   return type of <type>null</type>, previously it was
+   <type class="union"><type>RecursiveIterator</type><type>null</type></type>.


That may render badly, e.g.

Not sure if we should do something about that in the actual docs (might be something we want to improve in PhD).

cmb69 · 2022-09-24T12:53:13Z

appendices/migration82/deprecated.xml

+   <para>
+    The creation of dynamic properties is deprecated, unless the class opts in by
+    using the <code>#[\AllowDynamicProperties]</code> attribute.
+    <classname>stdClass</classname> allows dynamic properties.


Hmm, I guess we should either have a dedicated page for stdClass, or not to use the <classname> markup, but rather link to its documentation (whereever that is).

Opened #1846 to track this issue.

cmb69 · 2022-09-24T12:55:45Z

appendices/migration82/deprecated.xml

+  <para>
+   Usage of the <literal>QPrint</literal>, <literal>Base64</literal>,
+   <literal>Uuencode</literal>, and <literal>HTML-ENTITIES</literal>
+   'text encodings' is deprecated for all Mbstring functions.


All occurences of "MBString"/"Mbstring" should likely have the same case; I think the former is favorable.

cmb69 · 2022-09-24T13:03:18Z

Oh, and don't forget to add the migration guide to doc-base/manual.xml.in after merging.

Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>

Co-authored-by: Tim Düsterhus <timwolla@googlemail.com>

Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>

Co-authored-by: Tim Düsterhus <timwolla@googlemail.com>

Those are a leftover from copy pasting the migration guide

Missed the new flags param

Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>

Not all are there as some turn out to be undocumented

Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>

Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de> Co-authored-by: Tim Düsterhus <timwolla@googlemail.com>

Girgias force-pushed the 8.2-changelog branch 2 times, most recently from cb25bac to a6a8199 Compare September 6, 2022 16:42

TimWolla reviewed Sep 6, 2022

View reviewed changes

appendices/migration82/deprecated.xml Outdated Show resolved Hide resolved

appendices/migration82/new-features.xml Outdated Show resolved Hide resolved

appendices/migration82/other-changes.xml Outdated Show resolved Hide resolved

cmb69 reviewed Sep 6, 2022

View reviewed changes

TimWolla reviewed Sep 6, 2022

View reviewed changes

appendices/migration82/deprecated.xml Outdated Show resolved Hide resolved

appendices/migration82/deprecated.xml Outdated Show resolved Hide resolved

Girgias commented Sep 7, 2022

View reviewed changes

appendices/migration82/other-changes.xml Outdated Show resolved Hide resolved

cmb69 reviewed Sep 7, 2022

View reviewed changes

Girgias mentioned this pull request Sep 7, 2022

PHP 8.2 documentation tracker #1803

Closed

cmb69 reviewed Sep 8, 2022

View reviewed changes

TimWolla mentioned this pull request Sep 9, 2022

PHP 8.2 Release page php/web-php#675

Merged

5 tasks

Girgias force-pushed the 8.2-changelog branch from e396a5d to 704bd15 Compare September 13, 2022 07:33

This was referenced Sep 13, 2022

unserialize_max_depth INI setting is undocumented #1822

Closed

Undocumented fiber.stack_size INI directive #1824

Closed

Girgias force-pushed the 8.2-changelog branch from e328f08 to 18c999e Compare September 24, 2022 11:25

Girgias requested a review from cmb69 September 24, 2022 11:25

cmb69 approved these changes Sep 24, 2022

View reviewed changes

Girgias and others added 12 commits September 26, 2022 10:38

Add initial version of the PHP 8.2 migration guide

aae149d

Use simplelist for Callable depraction

e20028c

Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>

cURL wording

ef3d5e5

Co-authored-by: Tim Düsterhus <timwolla@googlemail.com>

Use link for magic methods

792d62c

Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>

Use FQN

42f9f8a

Co-authored-by: Tim Düsterhus <timwolla@googlemail.com>

Wording for string interpolation deprecation

210cfaa

Remove socket constants which were added in 8.1

d26880a

Those are a leftover from copy pasting the migration guide

use a simplelist

5f3b8cd

More FQN

388b307

Fix dba_open() signature

577d2b3

Missed the new flags param

Add some function links

c0f90b7

Add INI link for mysqli.reconnect and asdd removal note

afa857c

Girgias and others added 24 commits September 26, 2022 10:38

Session SameSite INI link

c86964c

SQLite3.defensive INI setting link + note

20cc05c

Return type wording fix

21b06a8

Add links in advance

7a7e372

Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>

Use simplelist

380a2c2

Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>

Grammar + Markup changes

fafef3e

Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>

Link to new cURL constants

88f865b

Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>

Fix markup

1f56229

Add error_log_mode INI setting docs

f73706c

Cleanup binary string comp section

ca567fb

Add some INI links

b15cce4

Restructure libmysql removal

6e142fd

Use simplelist in new functions

51b9179

Use simplelist for Zip methods

49ffbf6

Restrcuture Tidy section

a69fae1

Convert INI list to simplelist

c45f503

Acronym tags

d637d3b

Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>

Phrasing + markup nits

1a68d2d

Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>

DNF acronym tag

3230f0d

Link to missing INI directives

87d435e

Not all are there as some turn out to be undocumented

Improve glob message

cc208e0

Fix wording for true type addition

cd8fca8

Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>

Add links

3767b5a

Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>

MBString casing fixes

c5b0601

Girgias force-pushed the 8.2-changelog branch from 4d4dd30 to c5b0601 Compare September 26, 2022 09:38

Girgias merged commit 65716f4 into php:master Sep 26, 2022

Girgias deleted the 8.2-changelog branch September 26, 2022 09:40

Girgias added this to the PHP 8.2 milestone Nov 12, 2022

tiffany-taylor pushed a commit to tiffany-taylor/doc-en that referenced this pull request Jan 16, 2023

Add initial version of the PHP 8.2 migration guide (php#1799)

3155282

Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de> Co-authored-by: Tim Düsterhus <timwolla@googlemail.com>

claudepache pushed a commit to claudepache/php-doc-en that referenced this pull request Jun 1, 2023

Add initial version of the PHP 8.2 migration guide (php#1799)

43ec890

Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de> Co-authored-by: Tim Düsterhus <timwolla@googlemail.com>

Add initial version of the PHP 8.2 migration guide #1799

Add initial version of the PHP 8.2 migration guide #1799

Uh oh!

Conversation

Girgias commented Sep 6, 2022

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cmb69 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cmb69 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Girgias commented Sep 24, 2022

Uh oh!

cmb69 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cmb69 commented Sep 24, 2022

Uh oh!

Uh oh!