includes/StubObject.php

   1 <?php
   2
   3 // phpcs:disable MediaWiki.Commenting.FunctionComment.ObjectTypeHintReturn
   4 // phpcs:disable MediaWiki.Commenting.FunctionComment.ObjectTypeHintParam
   5
   6 /**
   7  * Delayed loading of global objects.
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License as published by
  11  * the Free Software Foundation; either version 2 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License along
  20  * with this program; if not, write to the Free Software Foundation, Inc.,
  21  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  22  * http://www.gnu.org/copyleft/gpl.html
  23  *
  24  * @file
  25  */
  26 use Wikimedia\ObjectFactory\ObjectFactory;
  27
  28 /**
  29  * Class to implement stub globals, which are globals that delay loading the
  30  * their associated module code by deferring initialisation until the first
  31  * method call.
  32  *
  33  * Note on reference parameters:
  34  *
  35  * If the called method takes any parameters by reference, the __call magic
  36  * here won't work correctly. The solution is to unstub the object before
  37  * calling the method.
  38  *
  39  * Note on unstub loops:
  40  *
  41  * Unstub loops (infinite recursion) sometimes occur when a constructor calls
  42  * another function, and the other function calls some method of the stub. The
  43  * best way to avoid this is to make constructors as lightweight as possible,
  44  * deferring any initialisation which depends on other modules. As a last
  45  * resort, you can use StubObject::isRealObject() to break the loop, but as a
  46  * general rule, the stub object mechanism should be transparent, and code
  47  * which refers to it should be kept to a minimum.
  48  *
  49  * @newable
  50  */
  51 class StubObject {
  52         /** @var null|string */
  53         protected $global;
  54
  55         /** @var null|string */
  56         protected $class;
  57
  58         /** @var null|callable */
  59         protected $factory;
  60
  61         /** @var array */
  62         protected $params;
  63
  64         /**
  65          * @stable to call
  66          *
  67          * @param string|null $global Name of the global variable.
  68          * @param string|callable|null $class Name of the class of the real object
  69          *                               or a factory function to call
  70          * @param array $params Parameters to pass to constructor of the real object.
  71          */
  72         public function __construct( $global = null, $class = null, $params = [] ) {
  73                 $this->global = $global;
  74                 if ( is_callable( $class ) ) {
  75                         $this->factory = $class;
  76                 } else {
  77                         $this->class = $class;
  78                 }
  79                 $this->params = $params;
  80         }
  81
  82         /**
  83          * Returns a bool value whenever $obj is a stub object. Can be used to break
  84          * a infinite loop when unstubbing an object.
  85          *
  86          * @param object $obj Object to check.
  87          * @return bool True if $obj is not an instance of StubObject class.
  88          */
  89         public static function isRealObject( $obj ) {
  90                 return is_object( $obj ) && !$obj instanceof self;
  91         }
  92
  93         /**
  94          * Unstubs an object, if it is a stub object. Can be used to break a
  95          * infinite loop when unstubbing an object or to avoid reference parameter
  96          * breakage.
  97          *
  98          * @param object &$obj Object to check.
  99          * @return void
 100          */
 101         public static function unstub( &$obj ) {
 102                 if ( $obj instanceof self ) {
 103                         $obj = $obj->_unstub( 'unstub', 3 );
 104                 }
 105         }
 106
 107         /**
 108          * Function called if any function exists with that name in this object.
 109          * It is used to unstub the object. Only used internally, PHP will call
 110          * self::__call() function and that function will call this function.
 111          * This function will also call the function with the same name in the real
 112          * object.
 113          *
 114          * @param string $name Name of the function called
 115          * @param array $args Arguments
 116          * @return mixed
 117          */
 118         public function _call( $name, $args ) {
 119                 $this->_unstub( $name, 5 );
 120                 return call_user_func_array( [ $GLOBALS[$this->global], $name ], $args );
 121         }
 122
 123         /**
 124          * Create a new object to replace this stub object.
 125          * @return object
 126          */
 127         public function _newObject() {
 128                 $params = $this->factory
 129                         ? [ 'factory' => $this->factory ]
 130                         : [ 'class' => $this->class ];
 131
 132                 // ObjectFactory::getObjectFromSpec accepts an array, not just a callable (phan bug)
 133                 // @phan-suppress-next-line PhanTypeInvalidCallableArraySize
 134                 return ObjectFactory::getObjectFromSpec( $params + [
 135                         'args' => $this->params,
 136                         'closure_expansion' => false,
 137                 ] );
 138         }
 139
 140         /**
 141          * Function called by PHP if no function with that name exists in this
 142          * object.
 143          *
 144          * @param string $name Name of the function called
 145          * @param array $args Arguments
 146          * @return mixed
 147          */
 148         public function __call( $name, $args ) {
 149                 return $this->_call( $name, $args );
 150         }
 151
 152         /**
 153          * Wrapper for __get(), similar to _call() above
 154          *
 155          * @param string $name Name of the property to get
 156          * @return mixed
 157          */
 158         public function _get( $name ) {
 159                 $this->_unstub( "__get($name)", 5 );
 160                 return $GLOBALS[$this->global]->$name;
 161         }
 162
 163         /**
 164          * Function called by PHP if no property with that name exists in this
 165          * object.
 166          *
 167          * @param string $name Name of the property to get
 168          * @return mixed
 169          */
 170         public function __get( $name ) {
 171                 return $this->_get( $name );
 172         }
 173
 174         /**
 175          * Wrapper for __set(), similar to _call() above
 176          *
 177          * @param string $name Name of the property to set
 178          * @param mixed $value New property value
 179          */
 180         public function _set( $name, $value ) {
 181                 $this->_unstub( "__set($name)", 5 );
 182                 $GLOBALS[$this->global]->$name = $value;
 183         }
 184
 185         /**
 186          * Function called by PHP if no property with that name exists in this
 187          * object.
 188          *
 189          * @param string $name Name of the property to set
 190          * @param mixed $value New property value
 191          */
 192         public function __set( $name, $value ) {
 193                 $this->_set( $name, $value );
 194         }
 195
 196         /**
 197          * This function creates a new object of the real class and replace it in
 198          * the global variable.
 199          * This is public, for the convenience of external callers wishing to access
 200          * properties, e.g. eval.php
 201          *
 202          * @param string $name Name of the method called in this object.
 203          * @param int $level Level to go in the stack trace to get the function
 204          *   who called this function.
 205          * @return object The unstubbed version of itself
 206          * @throws MWException
 207          */
 208         public function _unstub( $name = '_unstub', $level = 2 ) {
 209                 static $recursionLevel = 0;
 210
 211                 if ( !$GLOBALS[$this->global] instanceof self ) {
 212                         return $GLOBALS[$this->global]; // already unstubbed.
 213                 }
 214
 215                 if ( get_class( $GLOBALS[$this->global] ) != $this->class ) {
 216                         $caller = wfGetCaller( $level );
 217                         if ( ++$recursionLevel > 2 ) {
 218                                 throw new MWException( "Unstub loop detected on call of "
 219                                         . "\${$this->global}->$name from $caller\n" );
 220                         }
 221                         wfDebug( "Unstubbing \${$this->global} on call of "
 222                                 . "\${$this->global}::$name from $caller" );
 223                         $GLOBALS[$this->global] = $this->_newObject();
 224                         --$recursionLevel;
 225                         return $GLOBALS[$this->global];
 226                 }
 227         }
 228 }