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