3 * Trait for issuing warnings on deprecated access.
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
24 * Use this trait in classes which have properties for which public access
25 * is deprecated. Set the list of properties in $deprecatedPublicProperties
26 * and make the properties non-public. The trait will preserve public access
27 * but issue deprecation warnings when it is needed.
31 * use DeprecationHelper;
33 * public function __construct() {
34 * $this->deprecatePublicProperty( 'bar', '1.21', __CLASS__ );
39 * $foo->bar; // works but logs a warning
41 * Cannot be used with classes that have their own __get/__set methods.
45 trait DeprecationHelper
{
48 * List of deprecated properties, in <property name> => [<version>, <class>, <component>] format
49 * where <version> is the MediaWiki version where the property got deprecated, <class> is the
50 * the name of the class defining the property, <component> is the MediaWiki component
51 * (extension, skin etc.) for use in the deprecation warning) or null if it is MediaWiki.
52 * E.g. [ 'mNewRev' => [ '1.32', 'DifferenceEngine', null ]
55 protected $deprecatedPublicProperties = [];
58 * Mark a property as deprecated. Only use this for properties that used to be public and only
59 * call it in the constructor.
60 * @param string $property The name of the property.
61 * @param string $version MediaWiki version where the property became deprecated.
62 * @param string|null $class The class which has the deprecated property. This can usually be
63 * guessed, but PHP can get confused when both the parent class and the subclass use the
64 * trait, so it should be specified in classes meant for subclassing.
65 * @param string|null $component
68 protected function deprecatePublicProperty(
69 $property, $version, $class = null, $component = null
71 $this->deprecatedPublicProperties
[$property] = [ $version, $class ?
: get_class(), $component ];
74 public function __get( $name ) {
75 if ( isset( $this->deprecatedPublicProperties
[$name] ) ) {
76 list( $version, $class, $component ) = $this->deprecatedPublicProperties
[$name];
77 $qualifiedName = $class . '::$' . $name;
78 wfDeprecated( $qualifiedName, $version, $component, 3 );
82 $qualifiedName = get_class() . '::$' . $name;
83 if ( $this->deprecationHelperGetPropertyOwner( $name ) ) {
84 // Someone tried to access a normal non-public property. Try to behave like PHP would.
85 trigger_error( "Cannot access non-public property $qualifiedName", E_USER_ERROR
);
87 // Non-existing property. Try to behave like PHP would.
88 trigger_error( "Undefined property: $qualifiedName", E_USER_NOTICE
);
93 public function __set( $name, $value ) {
94 if ( isset( $this->deprecatedPublicProperties
[$name] ) ) {
95 list( $version, $class, $component ) = $this->deprecatedPublicProperties
[$name];
96 $qualifiedName = $class . '::$' . $name;
97 wfDeprecated( $qualifiedName, $version, $component, 3 );
98 $this->$name = $value;
102 $qualifiedName = get_class() . '::$' . $name;
103 if ( $this->deprecationHelperGetPropertyOwner( $name ) ) {
104 // Someone tried to access a normal non-public property. Try to behave like PHP would.
105 trigger_error( "Cannot access non-public property $qualifiedName", E_USER_ERROR
);
107 // Non-existing property. Try to behave like PHP would.
108 $this->$name = $value;
113 * Like property_exists but also check for non-visible private properties and returns which
114 * class in the inheritance chain declared the property.
115 * @param string $property
116 * @return string|bool Best guess for the class in which the property is defined.
118 private function deprecationHelperGetPropertyOwner( $property ) {
119 // Easy branch: check for protected property / private property of the current class.
120 if ( property_exists( $this, $property ) ) {
121 // The class name is not necessarily correct here but getting the correct class
122 // name would be expensive, this will work most of the time and getting it
123 // wrong is not a big deal.
126 // property_exists() returns false when the property does exist but is private (and not
127 // defined by the current class, for some value of "current" that differs slightly
129 // Since PHP triggers an error on public access of non-public properties but happily
130 // allows public access to undefined properties, we need to detect this case as well.
131 // Reflection is slow so use array cast hack to check for that:
132 $obfuscatedProps = array_keys( (array)$this );
133 $obfuscatedPropTail = "\0$property";
134 foreach ( $obfuscatedProps as $obfuscatedProp ) {
135 // private props are in the form \0<classname>\0<propname>
136 if ( strpos( $obfuscatedProp, $obfuscatedPropTail, 1 ) !== false ) {
137 $classname = substr( $obfuscatedProp, 1, -strlen( $obfuscatedPropTail ) );
138 if ( $classname === '*' ) {
139 // sanity; this shouldn't be possible as protected properties were handled earlier
140 $classname = __CLASS__
;