1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
<?php
/**
* Trait for issuing warnings on deprecated access.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License along
* with this program; if not, write to the Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
* http://www.gnu.org/copyleft/gpl.html
*
* @file
*/
/**
* Use this trait in classes which have properties for which public access
* is deprecated. Set the list of properties in $deprecatedPublicProperties
* and make the properties non-public. The trait will preserve public access
* but issue deprecation warnings when it is needed.
*
* Example usage:
* class Foo {
* use DeprecationHelper;
* protected $bar;
* public function __construct() {
* $this->deprecatePublicProperty( 'bar', '1.21', __CLASS__ );
* }
* }
*
* $foo = new Foo;
* $foo->bar; // works but logs a warning
*
* Cannot be used with classes that have their own __get/__set methods.
*
* @since 1.32
*/
trait DeprecationHelper {
/**
* List of deprecated properties, in <property name> => [<version>, <class>, <component>] format
* where <version> is the MediaWiki version where the property got deprecated, <class> is the
* the name of the class defining the property, <component> is the MediaWiki component
* (extension, skin etc.) for use in the deprecation warning) or null if it is MediaWiki.
* E.g. [ 'mNewRev' => [ '1.32', 'DifferenceEngine', null ]
* @var string[][]
*/
protected $deprecatedPublicProperties = [];
/**
* Mark a property as deprecated. Only use this for properties that used to be public and only
* call it in the constructor.
* @param string $property The name of the property.
* @param string $version MediaWiki version where the property became deprecated.
* @param string|null $class The class which has the deprecated property. This can usually be
* guessed, but PHP can get confused when both the parent class and the subclass use the
* trait, so it should be specified in classes meant for subclassing.
* @param string|null $component
* @see wfDeprecated()
*/
protected function deprecatePublicProperty(
$property, $version, $class = null, $component = null
) {
$this->deprecatedPublicProperties[$property] = [ $version, $class ?: __CLASS__, $component ];
}
public function __get( $name ) {
if ( isset( $this->deprecatedPublicProperties[$name] ) ) {
list( $version, $class, $component ) = $this->deprecatedPublicProperties[$name];
$qualifiedName = $class . '::$' . $name;
wfDeprecated( $qualifiedName, $version, $component, 3 );
return $this->$name;
}
$ownerClass = $this->deprecationHelperGetPropertyOwner( $name );
$qualifiedName = ( $ownerClass ?: get_class( $this ) ) . '::$' . $name;
if ( $ownerClass ) {
// Someone tried to access a normal non-public property. Try to behave like PHP would.
trigger_error( "Cannot access non-public property $qualifiedName", E_USER_ERROR );
} else {
// Non-existing property. Try to behave like PHP would.
trigger_error( "Undefined property: $qualifiedName", E_USER_NOTICE );
}
return null;
}
public function __set( $name, $value ) {
if ( isset( $this->deprecatedPublicProperties[$name] ) ) {
list( $version, $class, $component ) = $this->deprecatedPublicProperties[$name];
$qualifiedName = $class . '::$' . $name;
wfDeprecated( $qualifiedName, $version, $component, 3 );
$this->$name = $value;
return;
}
$ownerClass = $this->deprecationHelperGetPropertyOwner( $name );
$qualifiedName = ( $ownerClass ?: get_class( $this ) ) . '::$' . $name;
if ( $ownerClass ) {
// Someone tried to access a normal non-public property. Try to behave like PHP would.
trigger_error( "Cannot access non-public property $qualifiedName", E_USER_ERROR );
} else {
// Non-existing property. Try to behave like PHP would.
$this->$name = $value;
}
}
/**
* Like property_exists but also check for non-visible private properties and returns which
* class in the inheritance chain declared the property.
* @param string $property
* @return string|bool Best guess for the class in which the property is defined. False if
* the object does not have such a property.
*/
private function deprecationHelperGetPropertyOwner( $property ) {
// Returning false is a non-error path and should avoid slow checks like reflection.
// Use array cast hack instead.
$obfuscatedProps = array_keys( (array)$this );
$obfuscatedPropTail = "\0$property";
foreach ( $obfuscatedProps as $obfuscatedProp ) {
// private props are in the form \0<classname>\0<propname>
if ( strpos( $obfuscatedProp, $obfuscatedPropTail, 1 ) !== false ) {
$classname = substr( $obfuscatedProp, 1, -strlen( $obfuscatedPropTail ) );
if ( $classname === '*' ) {
// protected property; we didn't get the name, but we are on an error path
// now so it's fine to use reflection
return ( new ReflectionProperty( $this, $property ) )->getDeclaringClass()->getName();
}
return $classname;
}
}
return false;
}
}
|
