MediaWiki  master
DeprecationHelper.php File Reference

Trait for issuing warnings on deprecated access. More...

Go to the source code of this file.

Functions

 __get ( $name)
 
 __isset ( $name)
 
 __set ( $name, $value)
 
 deprecateDynamicPropertiesAccess (string $version, string $class=null, string $component=null)
 Emit deprecation warnings when dynamic and unknown properties are accessed. More...
 
 deprecatePublicProperty ( $property, $version, $class=null, $component=null)
 Mark a property as deprecated. More...
 
 deprecatePublicPropertyFallback (string $property, string $version, callable $getter, ?callable $setter=null, $class=null, $component=null)
 Mark a removed public property as deprecated and provide fallback getter and setter callables. More...
 
 deprecationHelperGetPropertyOwner ( $property)
 Like property_exists but also check for non-visible private properties and returns which class in the inheritance chain declared the property. More...
 

Variables

bool array $dynamicPropertiesAccessDeprecated = false
 Whether to emit a deprecation warning when unknown properties are accessed. More...
 
trait DeprecationHelper
 Use this trait in classes which have properties for which public access is deprecated or implementation has been move to another class. More...
 

Detailed Description

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

Definition in file DeprecationHelper.php.

Function Documentation

◆ __get()

__get (   $name)

Definition at line 185 of file DeprecationHelper.php.

References deprecationHelperGetPropertyOwner(), and wfDeprecated().

◆ __isset()

__isset (   $name)

◆ __set()

__set (   $name,
  $value 
)

◆ deprecateDynamicPropertiesAccess()

deprecateDynamicPropertiesAccess ( string  $version,
string  $class = null,
string  $component = null 
)
protected

Emit deprecation warnings when dynamic and unknown properties are accessed.

Parameters
string$versionMediaWiki version where the property became deprecated.
string | null$classThe class which has the deprecated property.
string | null$component

Definition at line 149 of file DeprecationHelper.php.

◆ deprecatePublicProperty()

deprecatePublicProperty (   $property,
  $version,
  $class = null,
  $component = null 
)
protected

Mark a property as deprecated.

Only use this for properties that used to be public and only call it in the constructor.

Note
Providing callbacks makes it not serializable
Parameters
string$propertyThe name of the property.
string$versionMediaWiki version where the property became deprecated.
string | null$classThe 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.
string | null$component
See also
wfDeprecated()

Definition at line 94 of file DeprecationHelper.php.

Referenced by DifferenceEngine\__construct(), LanguageConverter\__construct(), Title\__construct(), and EditPage\__construct().

◆ deprecatePublicPropertyFallback()

deprecatePublicPropertyFallback ( string  $property,
string  $version,
callable  $getter,
?callable  $setter = null,
  $class = null,
  $component = null 
)
protected

Mark a removed public property as deprecated and provide fallback getter and setter callables.

Only use this for properties that used to be public and only call it in the constructor.

Parameters
string$propertyThe name of the property.
string$versionMediaWiki version where the property became deprecated.
callable$getterA user provided getter that implements a get logic for the property.
callable | null$setterA user provided setter that implements a set logic for the property.
string | null$classThe class which has the deprecated property.
string | null$component
Since
1.36
See also
wfDeprecated()

Definition at line 123 of file DeprecationHelper.php.

Referenced by LanguageConverter\__construct(), RecentChange\__construct(), Title\__construct(), RevisionListBase\__construct(), and CategoryViewer\__construct().

◆ deprecationHelperGetPropertyOwner()

deprecationHelperGetPropertyOwner (   $property)
private

Like property_exists but also check for non-visible private properties and returns which class in the inheritance chain declared the property.

Parameters
string$property
Returns
string|bool Best guess for the class in which the property is defined. False if the object does not have such a property.

Definition at line 252 of file DeprecationHelper.php.

Referenced by __get(), __isset(), and __set().

Variable Documentation

◆ $dynamicPropertiesAccessDeprecated

bool array $dynamicPropertiesAccessDeprecated = false
private

Whether to emit a deprecation warning when unknown properties are accessed.

Definition at line 78 of file DeprecationHelper.php.

Referenced by __isset(), and __set().

◆ DeprecationHelper

trait DeprecationHelper
Initial value:
{
protected string[][] $deprecatedPublicProperties = []

Use this trait in classes which have properties for which public access is deprecated or implementation has been move to another class.

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 ); $this->deprecatePublicPropertyFallback( 'movedValue', '1.35', function () { return MediawikiServices()::getInstance() ->getNewImplementationService()->getValue(); }, function ( $value ) { MediawikiServices()::getInstance() ->getNewImplementationService()->setValue( $value ); } ); } }

$foo = new Foo; $foo->bar; // works but logs a warning $foo->movedValue = 10; // works but logs a warning $movedValue = $foo->movedValue; // also works

Cannot be used with classes that have their own __get/__set methods.

Since
1.32

Definition at line 60 of file DeprecationHelper.php.