includes/utils/AutoloadGenerator.php

   1 <?php
   2
   3 /**
   4  * Accepts a list of files and directories to search for
   5  * php files and generates $wgAutoloadLocalClasses or $wgAutoloadClasses
   6  * lines for all detected classes. These lines are written out
   7  * to an autoload.php file in the projects provided basedir.
   8  *
   9  * Usage:
  10  *
  11  *     $gen = new AutoloadGenerator( __DIR__ );
  12  *     $gen->readDir( __DIR__ . '/includes' );
  13  *     $gen->readFile( __DIR__ . '/foo.php' )
  14  *     $gen->getAutoload();
  15  */
  16 class AutoloadGenerator {
  17         const FILETYPE_JSON = 'json';
  18         const FILETYPE_PHP = 'php';
  19
  20         /**
  21          * @var string Root path of the project being scanned for classes
  22          */
  23         protected $basepath;
  24
  25         /**
  26          * @var ClassCollector Helper class extracts class names from php files
  27          */
  28         protected $collector;
  29
  30         /**
  31          * @var array Map of file shortpath to list of FQCN detected within file
  32          */
  33         protected $classes = [];
  34
  35         /**
  36          * @var string The global variable to write output to
  37          */
  38         protected $variableName = 'wgAutoloadClasses';
  39
  40         /**
  41          * @var array Map of FQCN to relative path(from self::$basepath)
  42          */
  43         protected $overrides = [];
  44
  45         /**
  46          * Directories that should be excluded
  47          *
  48          * @var string[]
  49          */
  50         protected $excludePaths = [];
  51
  52         /**
  53          * @param string $basepath Root path of the project being scanned for classes
  54          * @param array|string $flags
  55          *
  56          *  local - If this flag is set $wgAutoloadLocalClasses will be build instead
  57          *          of $wgAutoloadClasses
  58          */
  59         public function __construct( $basepath, $flags = [] ) {
  60                 if ( !is_array( $flags ) ) {
  61                         $flags = [ $flags ];
  62                 }
  63                 $this->basepath = self::normalizePathSeparator( realpath( $basepath ) );
  64                 $this->collector = new ClassCollector;
  65                 if ( in_array( 'local', $flags ) ) {
  66                         $this->variableName = 'wgAutoloadLocalClasses';
  67                 }
  68         }
  69
  70         /**
  71          * Directories that should be excluded
  72          *
  73          * @since 1.31
  74          * @param string[] $paths
  75          */
  76         public function setExcludePaths( array $paths ) {
  77                 foreach ( $paths as $path ) {
  78                         $this->excludePaths[] = self::normalizePathSeparator( $path );
  79                 }
  80         }
  81
  82         /**
  83          * Whether the file should be excluded
  84          *
  85          * @param string $path File path
  86          * @return bool
  87          */
  88         private function shouldExclude( $path ) {
  89                 foreach ( $this->excludePaths as $dir ) {
  90                         if ( strpos( $path, $dir ) === 0 ) {
  91                                 return true;
  92                         }
  93                 }
  94
  95                 return false;
  96         }
  97
  98         /**
  99          * Force a class to be autoloaded from a specific path, regardless of where
 100          * or if it was detected.
 101          *
 102          * @param string $fqcn FQCN to force the location of
 103          * @param string $inputPath Full path to the file containing the class
 104          * @throws Exception
 105          */
 106         public function forceClassPath( $fqcn, $inputPath ) {
 107                 $path = self::normalizePathSeparator( realpath( $inputPath ) );
 108                 if ( !$path ) {
 109                         throw new \Exception( "Invalid path: $inputPath" );
 110                 }
 111                 $len = strlen( $this->basepath );
 112                 if ( substr( $path, 0, $len ) !== $this->basepath ) {
 113                         throw new \Exception( "Path is not within basepath: $inputPath" );
 114                 }
 115                 $shortpath = substr( $path, $len );
 116                 $this->overrides[$fqcn] = $shortpath;
 117         }
 118
 119         /**
 120          * @param string $inputPath Path to a php file to find classes within
 121          * @throws Exception
 122          */
 123         public function readFile( $inputPath ) {
 124                 // NOTE: do NOT expand $inputPath using realpath(). It is perfectly
 125                 // reasonable for LocalSettings.php and similiar files to be symlinks
 126                 // to files that are outside of $this->basepath.
 127                 $inputPath = self::normalizePathSeparator( $inputPath );
 128                 $len = strlen( $this->basepath );
 129                 if ( substr( $inputPath, 0, $len ) !== $this->basepath ) {
 130                         throw new \Exception( "Path is not within basepath: $inputPath" );
 131                 }
 132                 if ( $this->shouldExclude( $inputPath ) ) {
 133                         return;
 134                 }
 135                 $result = $this->collector->getClasses(
 136                         file_get_contents( $inputPath )
 137                 );
 138                 if ( $result ) {
 139                         $shortpath = substr( $inputPath, $len );
 140                         $this->classes[$shortpath] = $result;
 141                 }
 142         }
 143
 144         /**
 145          * @param string $dir Path to a directory to recursively search
 146          *  for php files with either .php or .inc extensions
 147          */
 148         public function readDir( $dir ) {
 149                 $it = new RecursiveDirectoryIterator(
 150                         self::normalizePathSeparator( realpath( $dir ) ) );
 151                 $it = new RecursiveIteratorIterator( $it );
 152
 153                 foreach ( $it as $path => $file ) {
 154                         $ext = pathinfo( $path, PATHINFO_EXTENSION );
 155                         // some older files in mw use .inc
 156                         if ( $ext === 'php' || $ext === 'inc' ) {
 157                                 $this->readFile( $path );
 158                         }
 159                 }
 160         }
 161
 162         /**
 163          * Updates the AutoloadClasses field at the given
 164          * filename.
 165          *
 166          * @param string $filename Filename of JSON
 167          *  extension/skin registration file
 168          * @return string Updated Json of the file given as the $filename parameter
 169          */
 170         protected function generateJsonAutoload( $filename ) {
 171                 $key = 'AutoloadClasses';
 172                 $json = FormatJson::decode( file_get_contents( $filename ), true );
 173                 unset( $json[$key] );
 174                 // Inverting the key-value pairs so that they become of the
 175                 // format class-name : path when they get converted into json.
 176                 foreach ( $this->classes as $path => $contained ) {
 177                         foreach ( $contained as $fqcn ) {
 178                                 // Using substr to remove the leading '/'
 179                                 $json[$key][$fqcn] = substr( $path, 1 );
 180                         }
 181                 }
 182                 foreach ( $this->overrides as $path => $fqcn ) {
 183                         // Using substr to remove the leading '/'
 184                         $json[$key][$fqcn] = substr( $path, 1 );
 185                 }
 186
 187                 // Sorting the list of autoload classes.
 188                 ksort( $json[$key] );
 189
 190                 // Return the whole JSON file
 191                 return FormatJson::encode( $json, "\t", FormatJson::ALL_OK ) . "\n";
 192         }
 193
 194         /**
 195          * Generates a PHP file setting up autoload information.
 196          *
 197          * @param string $commandName Command name to include in comment
 198          * @param string $filename of PHP file to put autoload information in.
 199          * @return string
 200          */
 201         protected function generatePHPAutoload( $commandName, $filename ) {
 202                 // No existing JSON file found; update/generate PHP file
 203                 $content = [];
 204
 205                 // We need to generate a line each rather than exporting the
 206                 // full array so __DIR__ can be prepended to all the paths
 207                 $format = "%s => __DIR__ . %s,";
 208                 foreach ( $this->classes as $path => $contained ) {
 209                         $exportedPath = var_export( $path, true );
 210                         foreach ( $contained as $fqcn ) {
 211                                 $content[$fqcn] = sprintf(
 212                                         $format,
 213                                         var_export( $fqcn, true ),
 214                                         $exportedPath
 215                                 );
 216                         }
 217                 }
 218
 219                 foreach ( $this->overrides as $fqcn => $path ) {
 220                         $content[$fqcn] = sprintf(
 221                                 $format,
 222                                 var_export( $fqcn, true ),
 223                                 var_export( $path, true )
 224                         );
 225                 }
 226
 227                 // sort for stable output
 228                 ksort( $content );
 229
 230                 // extensions using this generator are appending to the existing
 231                 // autoload.
 232                 if ( $this->variableName === 'wgAutoloadClasses' ) {
 233                         $op = '+=';
 234                 } else {
 235                         $op = '=';
 236                 }
 237
 238                 $output = implode( "\n\t", $content );
 239                 return
 240                         <<<EOD
 241 <?php
 242 // This file is generated by $commandName, do not adjust manually
 243 // @codingStandardsIgnoreFile
 244 global \${$this->variableName};
 245
 246 \${$this->variableName} {$op} [
 247         {$output}
 248 ];
 249
 250 EOD;
 251         }
 252
 253         /**
 254          * Returns all known classes as a string, which can be used to put into a target
 255          * file (e.g. extension.json, skin.json or autoload.php)
 256          *
 257          * @param string $commandName Value used in file comment to direct
 258          *  developers towards the appropriate way to update the autoload.
 259          * @return string
 260          */
 261         public function getAutoload( $commandName = 'AutoloadGenerator' ) {
 262                 // We need to check whether an extenson.json or skin.json exists or not, and
 263                 // incase it doesn't, update the autoload.php file.
 264
 265                 $fileinfo = $this->getTargetFileinfo();
 266
 267                 if ( $fileinfo['type'] === self::FILETYPE_JSON ) {
 268                         return $this->generateJsonAutoload( $fileinfo['filename'] );
 269                 } else {
 270                         return $this->generatePHPAutoload( $commandName, $fileinfo['filename'] );
 271                 }
 272         }
 273
 274         /**
 275          * Returns the filename of the extension.json of skin.json, if there's any, or
 276          * otherwise the path to the autoload.php file in an array as the "filename"
 277          * key and with the type (AutoloadGenerator::FILETYPE_JSON or AutoloadGenerator::FILETYPE_PHP)
 278          * of the file as the "type" key.
 279          *
 280          * @return array
 281          */
 282         public function getTargetFileinfo() {
 283                 $fileinfo = [
 284                         'filename' => $this->basepath . '/autoload.php',
 285                         'type' => self::FILETYPE_PHP
 286                 ];
 287                 if ( file_exists( $this->basepath . '/extension.json' ) ) {
 288                         $fileinfo = [
 289                                 'filename' => $this->basepath . '/extension.json',
 290                                 'type' => self::FILETYPE_JSON
 291                         ];
 292                 } elseif ( file_exists( $this->basepath . '/skin.json' ) ) {
 293                         $fileinfo = [
 294                                 'filename' => $this->basepath . '/skin.json',
 295                                 'type' => self::FILETYPE_JSON
 296                         ];
 297                 }
 298
 299                 return $fileinfo;
 300         }
 301
 302         /**
 303          * Ensure that Unix-style path separators ("/") are used in the path.
 304          *
 305          * @param string $path
 306          * @return string
 307          */
 308         protected static function normalizePathSeparator( $path ) {
 309                 return str_replace( '\\', '/', $path );
 310         }
 311
 312         /**
 313          * Initialize the source files and directories which are used for the MediaWiki default
 314          * autoloader in {mw-base-dir}/autoload.php including:
 315          *  * includes/
 316          *  * languages/
 317          *  * maintenance/
 318          *  * mw-config/
 319          *  * /*.php
 320          */
 321         public function initMediaWikiDefault() {
 322                 foreach ( [ 'includes', 'languages', 'maintenance', 'mw-config' ] as $dir ) {
 323                         $this->readDir( $this->basepath . '/' . $dir );
 324                 }
 325                 foreach ( glob( $this->basepath . '/*.php' ) as $file ) {
 326                         $this->readFile( $file );
 327                 }
 328         }
 329 }
 330
 331 /**
 332  * Reads PHP code and returns the FQCN of every class defined within it.
 333  */
 334 class ClassCollector {
 335
 336         /**
 337          * @var string Current namespace
 338          */
 339         protected $namespace = '';
 340
 341         /**
 342          * @var array List of FQCN detected in this pass
 343          */
 344         protected $classes;
 345
 346         /**
 347          * @var array Token from token_get_all() that started an expect sequence
 348          */
 349         protected $startToken;
 350
 351         /**
 352          * @var array List of tokens that are members of the current expect sequence
 353          */
 354         protected $tokens;
 355
 356         /**
 357          * @var array Class alias with target/name fields
 358          */
 359         protected $alias;
 360
 361         /**
 362          * @param string $code PHP code (including <?php) to detect class names from
 363          * @return array List of FQCN detected within the tokens
 364          */
 365         public function getClasses( $code ) {
 366                 $this->namespace = '';
 367                 $this->classes = [];
 368                 $this->startToken = null;
 369                 $this->alias = null;
 370                 $this->tokens = [];
 371
 372                 foreach ( token_get_all( $code ) as $token ) {
 373                         if ( $this->startToken === null ) {
 374                                 $this->tryBeginExpect( $token );
 375                         } else {
 376                                 $this->tryEndExpect( $token );
 377                         }
 378                 }
 379
 380                 return $this->classes;
 381         }
 382
 383         /**
 384          * Determine if $token begins the next expect sequence.
 385          *
 386          * @param array $token
 387          */
 388         protected function tryBeginExpect( $token ) {
 389                 if ( is_string( $token ) ) {
 390                         return;
 391                 }
 392                 // Note: When changing class name discovery logic,
 393                 // AutoLoaderTest.php may also need to be updated.
 394                 switch ( $token[0] ) {
 395                         case T_NAMESPACE:
 396                         case T_CLASS:
 397                         case T_INTERFACE:
 398                         case T_TRAIT:
 399                         case T_DOUBLE_COLON:
 400                                 $this->startToken = $token;
 401                                 break;
 402                         case T_STRING:
 403                                 if ( $token[1] === 'class_alias' ) {
 404                                         $this->startToken = $token;
 405                                         $this->alias = [];
 406                                 }
 407                 }
 408         }
 409
 410         /**
 411          * Accepts the next token in an expect sequence
 412          *
 413          * @param array $token
 414          */
 415         protected function tryEndExpect( $token ) {
 416                 switch ( $this->startToken[0] ) {
 417                         case T_DOUBLE_COLON:
 418                                 // Skip over T_CLASS after T_DOUBLE_COLON because this is something like
 419                                 // "self::static" which accesses the class name. It doens't define a new class.
 420                                 $this->startToken = null;
 421                                 break;
 422                         case T_NAMESPACE:
 423                                 if ( $token === ';' || $token === '{' ) {
 424                                         $this->namespace = $this->implodeTokens() . '\\';
 425                                 } else {
 426                                         $this->tokens[] = $token;
 427                                 }
 428                                 break;
 429
 430                         case T_STRING:
 431                                 if ( $this->alias !== null ) {
 432                                         // Flow 1 - Two string literals:
 433                                         // - T_STRING  class_alias
 434                                         // - '('
 435                                         // - T_CONSTANT_ENCAPSED_STRING 'TargetClass'
 436                                         // - ','
 437                                         // - T_WHITESPACE
 438                                         // - T_CONSTANT_ENCAPSED_STRING 'AliasName'
 439                                         // - ')'
 440                                         // Flow 2 - Use of ::class syntax for first parameter
 441                                         // - T_STRING  class_alias
 442                                         // - '('
 443                                         // - T_STRING TargetClass
 444                                         // - T_DOUBLE_COLON ::
 445                                         // - T_CLASS class
 446                                         // - ','
 447                                         // - T_WHITESPACE
 448                                         // - T_CONSTANT_ENCAPSED_STRING 'AliasName'
 449                                         // - ')'
 450                                         if ( $token === '(' ) {
 451                                                 // Start of a function call to class_alias()
 452                                                 $this->alias = [ 'target' => false, 'name' => false ];
 453                                         } elseif ( $token === ',' ) {
 454                                                 // Record that we're past the first parameter
 455                                                 if ( $this->alias['target'] === false ) {
 456                                                         $this->alias['target'] = true;
 457                                                 }
 458                                         } elseif ( is_array( $token ) && $token[0] === T_CONSTANT_ENCAPSED_STRING ) {
 459                                                 if ( $this->alias['target'] === true ) {
 460                                                         // We already saw a first argument, this must be the second.
 461                                                         // Strip quotes from the string literal.
 462                                                         $this->alias['name'] = substr( $token[1], 1, -1 );
 463                                                 }
 464                                         } elseif ( $token === ')' ) {
 465                                                 // End of function call
 466                                                 $this->classes[] = $this->alias['name'];
 467                                                 $this->alias = null;
 468                                                 $this->startToken = null;
 469                                         } elseif ( !is_array( $token ) || (
 470                                                 $token[0] !== T_STRING &&
 471                                                 $token[0] !== T_DOUBLE_COLON &&
 472                                                 $token[0] !== T_CLASS &&
 473                                                 $token[0] !== T_WHITESPACE
 474                                         ) ) {
 475                                                 // Ignore this call to class_alias() - compat/Timestamp.php
 476                                                 $this->alias = null;
 477                                                 $this->startToken = null;
 478                                         }
 479                                 }
 480                                 break;
 481
 482                         case T_CLASS:
 483                         case T_INTERFACE:
 484                         case T_TRAIT:
 485                                 $this->tokens[] = $token;
 486                                 if ( is_array( $token ) && $token[0] === T_STRING ) {
 487                                         $this->classes[] = $this->namespace . $this->implodeTokens();
 488                                 }
 489                 }
 490         }
 491
 492         /**
 493          * Returns the string representation of the tokens within the
 494          * current expect sequence and resets the sequence.
 495          *
 496          * @return string
 497          */
 498         protected function implodeTokens() {
 499                 $content = [];
 500                 foreach ( $this->tokens as $token ) {
 501                         $content[] = is_string( $token ) ? $token : $token[1];
 502                 }
 503
 504                 $this->tokens = [];
 505                 $this->startToken = null;
 506
 507                 return trim( implode( '', $content ), " \n\t" );
 508         }
 509 }