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