includes/debug/DeprecationHelper.php

   1 <?php
   2 /**
   3  * Trait for issuing warnings on deprecated access.
   4  *
   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.
   9  *
  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.
  14  *
  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
  19  *
  20  * @file
  21  */
  22
  23 /**
  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.
  28  *
  29  * Example usage:
  30  *     class Foo {
  31  *         use DeprecationHelper;
  32  *         protected $bar;
  33  *         public function __construct() {
  34  *             $this->deprecatePublicProperty( 'bar', '1.21', __CLASS__ );
  35  *         }
  36  *     }
  37  *
  38  *     $foo = new Foo;
  39  *     $foo->bar; // works but logs a warning
  40  *
  41  * Cannot be used with classes that have their own __get/__set methods.
  42  *
  43  * @since 1.32
  44  */
  45 trait DeprecationHelper {
  46
  47         /**
  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 ]
  53          * @var string[][]
  54          */
  55         protected $deprecatedPublicProperties = [];
  56
  57         /**
  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
  66          * @see wfDeprecated()
  67          */
  68         protected function deprecatePublicProperty(
  69                 $property, $version, $class = null, $component = null
  70         ) {
  71                 $this->deprecatedPublicProperties[$property] = [ $version, $class ?: __CLASS__, $component ];
  72         }
  73
  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 );
  79                         return $this->$name;
  80                 }
  81
  82                 $qualifiedName = __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 );
  86                 } else {
  87                         // Non-existing property. Try to behave like PHP would.
  88                         trigger_error( "Undefined property: $qualifiedName", E_USER_NOTICE );
  89                 }
  90                 return null;
  91         }
  92
  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;
  99                         return;
 100                 }
 101
 102                 $qualifiedName = __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 );
 106                 } else {
 107                         // Non-existing property. Try to behave like PHP would.
 108                         $this->$name = $value;
 109                 }
 110         }
 111
 112         /**
 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.
 117          */
 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.
 124                         return __CLASS__;
 125                 }
 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
 128                 // between engines).
 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__;
 141                                 }
 142                                 return $classname;
 143                         }
 144                 }
 145                 return false;
 146         }
 147
 148 }