From 4c2f1fb2fd702edf75910b30ac8da7fe13d74322 Mon Sep 17 00:00:00 2001 From: Javier Spagnoletti Date: Mon, 26 Oct 2015 13:51:29 -0300 Subject: [PATCH] [Contributing] [Standards] Add note about `trigger_error()` and deprecation messages | Q | A | ------------- | --- | Doc fix? | no | New docs? | no | Applies to | 2.3+ | Fixed tickets | Add note and example on how to trigger proper deprecation messages. --- contributing/code/standards.rst | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/contributing/code/standards.rst b/contributing/code/standards.rst index c6030ba3ee1..4acceb31a05 100644 --- a/contributing/code/standards.rst +++ b/contributing/code/standards.rst @@ -50,6 +50,18 @@ example containing most features described below: $this->fooBar = $this->transformText($dummy); } + /** + * @return string + * + * @deprecated + */ + public function someDeprecatedMethod() + { + @trigger_error(sprintf('The %s() method is deprecated since version 2.8 and will be removed in 3.0. Use Acme\Baz::someMethod() instead.', __METHOD__), E_USER_DEPRECATED); + + return Baz::someMethod(); + } + /** * Transforms the input given as first argument. * @@ -151,7 +163,11 @@ Structure * Use parentheses when instantiating classes regardless of the number of arguments the constructor has; -* Exception message strings should be concatenated using :phpfunction:`sprintf`. +* Exception and error message strings should be concatenated using :phpfunction:`sprintf`. + +* Calls to :phpfunction:`trigger_error` with type ``E_USER_DEPRECATED`` should be + switched to opt-in via ``@`` operator. + Read more at :ref:`contributing-code-conventions-deprecations`; Naming Conventions ------------------