Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Opt in deprecations docs #3123

Merged
merged 2 commits into from
May 2, 2018
Merged

Opt in deprecations docs #3123

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
633fa7b
Make executables executable
greg0ire May 1, 2018
041a769
Add page about upgrading
greg0ire May 1, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Empty file modified docs/bin/generate-docs.sh
100644 → 100755
View file
Open in desktop
Empty file.
Empty file modified docs/bin/install-dependencies.sh
100644 → 100755
View file
Open in desktop
Empty file.
1 change: 1 addition & 0 deletions docs/en/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ Contents:
reference/portability
reference/caching
reference/known-vendor-issues
reference/upgrading

Indices and tables
==================
Expand Down
51 changes: 51 additions & 0 deletions docs/en/reference/upgrading.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
Upgrading
=========

New versions of Doctrine come with an upgrade guide named UPGRADE.md.
This guide documents BC-breaks and deprecations.

Deprecations
------------

Deprecations are signaled by emitting a silenced ``E_USER_DEPRECATED``
error, like this:

.. code-block:: php

<?php

@trigger_error(
'QuantumDefraculator::__invoke() is deprecated.',
E_USER_DEPRECATED
);

Since this error is silenced, it will not produce any effect unless you
opt-in by setting up an error handler designed to ignore the silence
operator in that case. Such an error handler could look like this:

.. code-block:: php

<?php
set_error_handler(function (
Copy link
Contributor

Choose a reason for hiding this comment

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

Is it actually a good idea to overwrite handler for all messages like that? Can we maybe suggest this instead only for deprecations?

set_error_handler(
    function (int $code, string $message, string $file, int $line) : void {
        echo sprintf('Deprecation: "%s" in %s:%d', $message, $file, $line);
    },
    E_USER_DEPRECATED
);

https://3v4l.org/AFfPk

Copy link
Member Author

Choose a reason for hiding this comment

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

Fixed

int $errno,
string $errstr,
string $errfile,
int $errline,
array $errcontext
) : void {
if (error_reporting() === 0) {
/* "normal" error handlers would return in this case, but
this one will not */
}

echo "Hey there was a deprecation, here is what it says: $errstr";

}, E_USER_DEPRECATED);

This is of course overly simplified, and if you are looking for such an
error handler, consider the ``symfony/debug``, error handler that will
log deprecations. You may also be interested by the
``symfony/phpunit-bridge`` error handler that will catch deprecations
and nicely display them after running your test suites, and can even
make your build fail in that kind of case if you want to be strict about
that.