Skip to content

[WIP] PHP 8.0 migration guide#164

Closed
cmb69 wants to merge 3974 commits intophp:masterfrom
cmb69:cmb/migration80
Closed

[WIP] PHP 8.0 migration guide#164
cmb69 wants to merge 3974 commits intophp:masterfrom
cmb69:cmb/migration80

Conversation

@cmb69
Copy link
Copy Markdown
Member

@cmb69 cmb69 commented Oct 25, 2020

This is a pretty straight forward conversion of UPGRADING (c97da0f819730c00905f9618aba0c54e8d592f74).

Some notes:

  • some entries may better be moved to other sections (also in UPGRADING); for instance, there are new classes listed as new features, although there is a new classes section, and resource to object conversions are sometimes listed in the incompatible changes section and sometimes in the other changes section.
  • some further sectioning seems appropriate (mainly for Core and Standard Library sections)
  • some new features are not described at all (e.g. union types, match expression, attributes; I've left all referrals to RFCs and PRs as comments, what may be helpful to flesh those sections out
  • probably a lot of minor issues

Any help welcome!

PS: to actually intregrate that to the manual, doc-base needs the following patch:

Index: manual.xml.in
===================================================================
--- manual.xml.in	(revision 350984)
+++ manual.xml.in	(working copy)
@@ -478,6 +478,7 @@
  <book xml:id="appendices">
   <title>&Appendices;</title>
   &appendices.history;
+  &appendices.migration80;
   &appendices.migration74;
   &appendices.migration73;
   &appendices.migration72;

Mikko Koppanen and others added 30 commits October 24, 2013 06:43
git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@332227 c90b9560-bf6c-de11-be94-00142212c4b1
Also renamed repairDatabase entity and created a new entity for batchSize documentation.


git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@332247 c90b9560-bf6c-de11-be94-00142212c4b1
git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@332346 c90b9560-bf6c-de11-be94-00142212c4b1
git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@332347 c90b9560-bf6c-de11-be94-00142212c4b1
git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@332499 c90b9560-bf6c-de11-be94-00142212c4b1
git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@332500 c90b9560-bf6c-de11-be94-00142212c4b1
git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@332614 c90b9560-bf6c-de11-be94-00142212c4b1
…e for ɑ1.

I've intentionally limited the scope of the changes to the new migration guide:
we shouldn't start documenting new features and changes in the main text of the
manual until after feature freeze, IMO. This is here mostly so that we have
something useful to link to in the news post.

Some of the examples are very, very ropey right now, particularly for new
features. I expect we'll improve them as we go.


git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@332637 c90b9560-bf6c-de11-be94-00142212c4b1
This isn't intended to be used directly in a manual; instead, open it in
Inkscape, translate the text into the language translation you're working on,
and then output it into a file in your translation and use it from there.


git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@332641 c90b9560-bf6c-de11-be94-00142212c4b1
 - multibyte fulltext search did not work.
 - index was garbled in Chinese Simplified locale.


git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@332729 c90b9560-bf6c-de11-be94-00142212c4b1
Fixes doc bug #66578 (Browscap URL needs updating).


git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@332734 c90b9560-bf6c-de11-be94-00142212c4b1
I'm still working on this, and expect to commit a bunch more changes tomorrow,
but I get nervous when I have changes sitting locally for too long.


git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@333035 c90b9560-bf6c-de11-be94-00142212c4b1
git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@333076 c90b9560-bf6c-de11-be94-00142212c4b1
-- 
Patch provided by anonymous 40766. Thank you, oh mysterious numerically-named contributor!

git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@333094 c90b9560-bf6c-de11-be94-00142212c4b1
alcaeus and others added 23 commits January 23, 2020 07:34
PHP Warning:  count(): Parameter must be an array or an object that implements Countable in /path/to/doc-base/scripts/revcheck.php on line 992



git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@349018 c90b9560-bf6c-de11-be94-00142212c4b1
…gs every time get_file_status() call.

git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@349019 c90b9560-bf6c-de11-be94-00142212c4b1
Just a WS change to test commit hooks

git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@349341 c90b9560-bf6c-de11-be94-00142212c4b1
Just another WS change to test commit hooks

git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@349344 c90b9560-bf6c-de11-be94-00142212c4b1
git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@349552 c90b9560-bf6c-de11-be94-00142212c4b1
git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@349572 c90b9560-bf6c-de11-be94-00142212c4b1
git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@350051 c90b9560-bf6c-de11-be94-00142212c4b1
This integrates user note 125156.


git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@350092 c90b9560-bf6c-de11-be94-00142212c4b1
We add support for return types and union types, and properly retrieve
the types via the `::getType()` and `::getReturnType()` methods,
repectively.


git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@350350 c90b9560-bf6c-de11-be94-00142212c4b1
This integrates user note 125323.

git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@350511 c90b9560-bf6c-de11-be94-00142212c4b1
DocBook 5.2 adds support to union and intersection types.
We only need union types, since that is all PHP currently supports.

Back port the syntax for union types to our older DocBook DTD.

Example:
    <type class="union"><type>string</type><type>int</type></type>

git-svn-id: https://svn.php.net/repository/phpdoc/doc-base/trunk@350738 c90b9560-bf6c-de11-be94-00142212c4b1
The program execution functions (<function>proc_open</function>, <function>exec</function>,
<function>popen</function> etc.) using the shell, now consistently execute <command>%comspec% /s
/c "$commandline"</command>, which has the same effect as executing
<command>$commandline</command> (without additional quotes).
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this change have any user-visible effect?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, see php/php-src#5102 for details. Most relevant is that proc_open() didn't add quotes, while all other exec funtions did. Also, behavior without /s flag is pretty contrived.

more uniform and ergonomic representation, while being more memory efficient and faster.
<!-- RFC: https://wiki.php.net/rfc/token_as_object -->
</para>
</sect2>
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We also have ReflectionUnionType, ReflectionAttribute and a whole slew of new resource->object classes. I'm not sure it makes sense to separately mention them like this though. We can integrate that into either new features or backwards incompatible changes as appropriate.

Generally I think that it would be better to split the migration guide into top level sections "new features", "backwards incompatible changes" and "other changes", and then add subsections where useful, e.g. we'll probably want to list all ValueError promotions on a separate page, and maybe also list all resource promotions on a separate page. The current distinction between new classes, functions, constants and "other features" doesn't seem particularly useful, especially if some pages are nearly empty (like the new constants).

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I mostly agree, but that is the structure we're using more or less for a long time (and it's somehow reflected in UPGRADING). The proper procedure here might be to write to the doc mailing list. Not sure if there'll be much feedback, though.

Also note that several new constants (not necessarily global constants, though), and also some new functions/methods are currently mentioned elsewhere.

]]>
</programlisting>
</para>
</listitem>
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be useful to mention that the usual resolution to this problem is to simply remove the default value, because it does not have any effect.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you mean something like the suggestion a few lines above?

</listitem>
<listitem>
<para>
The procedural API of Zip is deprecated. Use <classname>ZipArchive</classname> instead.
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should provide an example here of how to replace simple iteration using the procedural API with the OO API, as this question has already come up multiple times.

<itemizedlist>
<listitem>
<para>
Declaring a required parameter after an optional one is deprecated. As an exception, declaring a
Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Declaring a required parameter after an optional one is deprecated. As an exception, declaring a
Declaring a required parameter after an optional one is deprecated, because the optional parameter is not optional. As an exception, declaring a

@cmb69 cmb69 closed this Oct 28, 2020
@cmb69
Copy link
Copy Markdown
Member Author

cmb69 commented Oct 28, 2020

I screwed that up, and apparently can't fix it; I can't even reopen this PR. :(

@cmb69 cmb69 mentioned this pull request Oct 29, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.