DeprecationHelper.php

Go to the documentation of this file.

<?php
namespace MediaWiki\Debug;
 
use Error;
use ReflectionFunction;
use ReflectionProperty;
 
trait DeprecationHelper {
 
    protected static $deprecatedPublicProperties = [];
 
    private $dynamicPropertiesAccessDeprecated = false;
 
    protected function deprecatePublicProperty(
        $property,
        $version,
        $class = null,
        $component = null
    ) {
        if ( isset( self::$deprecatedPublicProperties[$property] ) ) {
            return;
        }
        self::$deprecatedPublicProperties[$property] = [
            $version,
            $class ?: __CLASS__,
            $component ?: false,
            null,
            null,
        ];
    }
 
    protected function deprecatePublicPropertyFallback(
        string $property,
        string $version,
        $getter,
        $setter = null,
        $class = null,
        $component = null
    ) {
        if ( isset( self::$deprecatedPublicProperties[$property] ) ) {
            return;
        }
        self::$deprecatedPublicProperties[$property] = [
            $version,
            $class ?: __CLASS__,
            $component ?: false,
            $getter,
            $setter,
        ];
    }
 
    protected function deprecateDynamicPropertiesAccess(
        string $version,
        ?string $class = null,
        ?string $component = null
    ) {
        $this->dynamicPropertiesAccessDeprecated = [ $version, $class ?: __CLASS__, $component ];
    }
 
    public function __isset( $name ) {
        // Overriding magic __isset is required not only for isset() and empty(),
        // but to correctly support null coalescing for dynamic properties,
        // e.g. $foo->bar ?? 'default'
        if ( isset( self::$deprecatedPublicProperties[$name] ) ) {
            [ $version, $class, $component, $getter ] = self::$deprecatedPublicProperties[$name];
            $qualifiedName = $class . '::$' . $name;
            wfDeprecated( $qualifiedName, $version, $component, 2 );
            if ( $getter ) {
                return $this->deprecationHelperCallGetter( $getter );
            }
            return true;
        }
 
        $ownerClass = $this->deprecationHelperGetPropertyOwner( $name );
        if ( $ownerClass ) {
            // Someone tried to access a normal non-public property. Try to behave like PHP would.
            return false;
        } else {
            if ( $this->dynamicPropertiesAccessDeprecated ) {
                [ $version, $class, $component ] = $this->dynamicPropertiesAccessDeprecated;
                $qualifiedName = $class . '::$' . $name;
                wfDeprecated( $qualifiedName, $version, $component, 2 );
            }
            return false;
        }
    }
 
    public function __get( $name ) {
        if ( get_object_vars( $this ) === [] ) {
            // Object is being destructed, all bets are off (T363492);
            // in particular, we can't check $this->dynamicPropertiesAccessDeprecated anymore.
            // Just get the property and hope for the best...
            return $this->$name;
        }
 
        if ( isset( self::$deprecatedPublicProperties[$name] ) ) {
            [ $version, $class, $component, $getter ] = self::$deprecatedPublicProperties[$name];
            $qualifiedName = $class . '::$' . $name;
            wfDeprecated( $qualifiedName, $version, $component, 2 );
            if ( $getter ) {
                return $this->deprecationHelperCallGetter( $getter );
            }
            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.
            throw new Error( "Cannot access non-public property $qualifiedName" );
        } elseif ( property_exists( $this, $name ) ) {
            // Normally __get method will not be even called if the property exists,
            // but in tests if we mock an object that uses DeprecationHelper,
            // __get and __set magic methods will be mocked as well, and called
            // regardless of the property existence. Support that use-case.
            return $this->$name;
        } 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 ( get_object_vars( $this ) === [] ) {
            // Object is being destructed, all bets are off (T363492);
            // in particular, we can't check $this->dynamicPropertiesAccessDeprecated anymore.
            // Just set the property and hope for the best...
            $this->$name = $value;
            return;
        }
 
        if ( isset( self::$deprecatedPublicProperties[$name] ) ) {
            [ $version, $class, $component, , $setter ] = self::$deprecatedPublicProperties[$name];
            $qualifiedName = $class . '::$' . $name;
            wfDeprecated( $qualifiedName, $version, $component, 2 );
            if ( $setter ) {
                $this->deprecationHelperCallSetter( $setter, $value );
            } elseif ( property_exists( $this, $name ) ) {
                $this->$name = $value;
            } else {
                throw new Error( "Cannot access non-public property $qualifiedName" );
            }
            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.
            throw new Error( "Cannot access non-public property $qualifiedName" );
        } else {
            if ( $this->dynamicPropertiesAccessDeprecated ) {
                [ $version, $class, $component ] = $this->dynamicPropertiesAccessDeprecated;
                $qualifiedName = $class . '::$' . $name;
                wfDeprecated( $qualifiedName, $version, $component, 2 );
            }
            // Non-existing property. Try to behave like PHP would.
            $this->$name = $value;
        }
    }
 
    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;
    }
 
    private function deprecationHelperCallGetter( $getter ) {
        if ( is_string( $getter ) ) {
            $getter = [ $this, $getter ];
        } elseif ( ( new ReflectionFunction( $getter ) )->getClosureThis() !== null ) {
            $getter = $getter->bindTo( $this );
        }
        return $getter();
    }
 
    private function deprecationHelperCallSetter( $setter, $value ) {
        if ( is_string( $setter ) ) {
            $setter = [ $this, $setter ];
        } elseif ( ( new ReflectionFunction( $setter ) )->getClosureThis() !== null ) {
            $setter = $setter->bindTo( $this );
        }
        $setter( $value );
    }
}
class_alias( DeprecationHelper::class, 'DeprecationHelper' );