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.
11 * $gen = new AutoloadGenerator( __DIR__ );
12 * $gen->readDir( __DIR__ . '/includes' );
13 * $gen->readFile( __DIR__ . '/foo.php' )
14 * $gen->getAutoload();
16 class AutoloadGenerator
{
17 const FILETYPE_JSON
= 'json';
18 const FILETYPE_PHP
= 'php';
21 * @var string Root path of the project being scanned for classes
26 * @var ClassCollector Helper class extracts class names from php files
31 * @var array Map of file shortpath to list of FQCN detected within file
33 protected $classes = [];
36 * @var string The global variable to write output to
38 protected $variableName = 'wgAutoloadClasses';
41 * @var array Map of FQCN to relative path(from self::$basepath)
43 protected $overrides = [];
46 * Directories that should be excluded
50 protected $excludePaths = [];
53 * Configured PSR4 namespaces
55 * @var string[] namespace => path
57 protected $psr4Namespaces = [];
60 * @param string $basepath Root path of the project being scanned for classes
61 * @param array|string $flags
63 * local - If this flag is set $wgAutoloadLocalClasses will be build instead
64 * of $wgAutoloadClasses
66 public function __construct( $basepath, $flags = [] ) {
67 if ( !is_array( $flags ) ) {
70 $this->basepath
= self
::normalizePathSeparator( realpath( $basepath ) );
71 $this->collector
= new ClassCollector
;
72 if ( in_array( 'local', $flags ) ) {
73 $this->variableName
= 'wgAutoloadLocalClasses';
78 * Directories that should be excluded
81 * @param string[] $paths
83 public function setExcludePaths( array $paths ) {
84 foreach ( $paths as $path ) {
85 $this->excludePaths
[] = self
::normalizePathSeparator( $path );
92 * Unlike self::setExcludePaths(), this will only skip outputting the
93 * autoloader entry when the namespace matches the path.
96 * @param string[] $namespaces Associative array mapping namespace to path
98 public function setPsr4Namespaces( array $namespaces ) {
99 foreach ( $namespaces as $ns => $path ) {
100 $ns = rtrim( $ns, '\\' ) . '\\';
101 $this->psr4Namespaces
[$ns] = rtrim( self
::normalizePathSeparator( $path ), '/' );
106 * Whether the file should be excluded
108 * @param string $path File path
111 private function shouldExclude( $path ) {
112 foreach ( $this->excludePaths
as $dir ) {
113 if ( strpos( $path, $dir ) === 0 ) {
122 * Force a class to be autoloaded from a specific path, regardless of where
123 * or if it was detected.
125 * @param string $fqcn FQCN to force the location of
126 * @param string $inputPath Full path to the file containing the class
129 public function forceClassPath( $fqcn, $inputPath ) {
130 $path = self
::normalizePathSeparator( realpath( $inputPath ) );
132 throw new \
Exception( "Invalid path: $inputPath" );
134 $len = strlen( $this->basepath
);
135 if ( substr( $path, 0, $len ) !== $this->basepath
) {
136 throw new \
Exception( "Path is not within basepath: $inputPath" );
138 $shortpath = substr( $path, $len );
139 $this->overrides
[$fqcn] = $shortpath;
143 * @param string $inputPath Path to a php file to find classes within
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" );
155 if ( $this->shouldExclude( $inputPath ) ) {
158 $result = $this->collector
->getClasses(
159 file_get_contents( $inputPath )
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 ) )
171 if ( $inputPath === $expectedPath ) {
181 $shortpath = substr( $inputPath, $len );
182 $this->classes
[$shortpath] = $result;
187 * @param string $dir Path to a directory to recursively search
188 * for php files with either .php or .inc extensions
190 public function readDir( $dir ) {
191 $it = new RecursiveDirectoryIterator(
192 self
::normalizePathSeparator( realpath( $dir ) ) );
193 $it = new RecursiveIteratorIterator( $it );
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 );
205 * Updates the AutoloadClasses field at the given
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
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 );
224 foreach ( $this->overrides
as $path => $fqcn ) {
225 // Using substr to remove the leading '/'
226 $json[$key][$fqcn] = substr( $path, 1 );
229 // Sorting the list of autoload classes.
230 ksort( $json[$key] );
232 // Return the whole JSON file
233 return FormatJson
::encode( $json, "\t", FormatJson
::ALL_OK
) . "\n";
237 * Generates a PHP file setting up autoload information.
239 * @param string $commandName Command name to include in comment
240 * @param string $filename of PHP file to put autoload information in.
243 protected function generatePHPAutoload( $commandName, $filename ) {
244 // No existing JSON file found; update/generate PHP file
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(
255 var_export( $fqcn, true ),
261 foreach ( $this->overrides
as $fqcn => $path ) {
262 $content[$fqcn] = sprintf(
264 var_export( $fqcn, true ),
265 var_export( $path, true )
269 // sort for stable output
272 // extensions using this generator are appending to the existing
274 if ( $this->variableName
=== 'wgAutoloadClasses' ) {
280 $output = implode( "\n\t", $content );
283 // This file is generated by $commandName, do not adjust manually
284 // phpcs:disable Generic.Files.LineLength
285 global \${$this->variableName};
287 \${$this->variableName} {$op} [
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)
298 * @param string $commandName Value used in file comment to direct
299 * developers towards the appropriate way to update the autoload.
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.
306 $fileinfo = $this->getTargetFileinfo();
308 if ( $fileinfo['type'] === self
::FILETYPE_JSON
) {
309 return $this->generateJsonAutoload( $fileinfo['filename'] );
311 return $this->generatePHPAutoload( $commandName, $fileinfo['filename'] );
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.
323 public function getTargetFileinfo() {
325 'filename' => $this->basepath
. '/autoload.php',
326 'type' => self
::FILETYPE_PHP
328 if ( file_exists( $this->basepath
. '/extension.json' ) ) {
330 'filename' => $this->basepath
. '/extension.json',
331 'type' => self
::FILETYPE_JSON
333 } elseif ( file_exists( $this->basepath
. '/skin.json' ) ) {
335 'filename' => $this->basepath
. '/skin.json',
336 'type' => self
::FILETYPE_JSON
344 * Ensure that Unix-style path separators ("/") are used in the path.
346 * @param string $path
349 protected static function normalizePathSeparator( $path ) {
350 return str_replace( '\\', '/', $path );
354 * Initialize the source files and directories which are used for the MediaWiki default
355 * autoloader in {mw-base-dir}/autoload.php including:
362 public function initMediaWikiDefault() {
363 foreach ( [ 'includes', 'languages', 'maintenance', 'mw-config' ] as $dir ) {
364 $this->readDir( $this->basepath
. '/' . $dir );
366 foreach ( glob( $this->basepath
. '/*.php' ) as $file ) {
367 $this->readFile( $file );
373 * Reads PHP code and returns the FQCN of every class defined within it.
375 class ClassCollector
{
378 * @var string Current namespace
380 protected $namespace = '';
383 * @var array List of FQCN detected in this pass
388 * @var array Token from token_get_all() that started an expect sequence
390 protected $startToken;
393 * @var array List of tokens that are members of the current expect sequence
398 * @var array Class alias with target/name fields
403 * @param string $code PHP code (including <?php) to detect class names from
404 * @return array List of FQCN detected within the tokens
406 public function getClasses( $code ) {
407 $this->namespace = '';
409 $this->startToken
= null;
413 foreach ( token_get_all( $code ) as $token ) {
414 if ( $this->startToken
=== null ) {
415 $this->tryBeginExpect( $token );
417 $this->tryEndExpect( $token );
421 return $this->classes
;
425 * Determine if $token begins the next expect sequence.
427 * @param array $token
429 protected function tryBeginExpect( $token ) {
430 if ( is_string( $token ) ) {
433 // Note: When changing class name discovery logic,
434 // AutoLoaderStructureTest.php may also need to be updated.
435 switch ( $token[0] ) {
442 $this->startToken
= $token;
445 if ( $token[1] === 'class_alias' ) {
446 $this->startToken
= $token;
453 * Accepts the next token in an expect sequence
455 * @param array $token
457 protected function tryEndExpect( $token ) {
458 switch ( $this->startToken
[0] ) {
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;
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;
471 if ( $token === ';' ||
$token === '{' ) {
472 $this->namespace = $this->implodeTokens() . '\\';
474 $this->tokens
[] = $token;
479 if ( $this->alias
!== null ) {
480 // Flow 1 - Two string literals:
481 // - T_STRING class_alias
483 // - T_CONSTANT_ENCAPSED_STRING 'TargetClass'
486 // - T_CONSTANT_ENCAPSED_STRING 'AliasName'
488 // Flow 2 - Use of ::class syntax for first parameter
489 // - T_STRING class_alias
491 // - T_STRING TargetClass
492 // - T_DOUBLE_COLON ::
496 // - T_CONSTANT_ENCAPSED_STRING 'AliasName'
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;
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 );
512 } elseif ( $token === ')' ) {
513 // End of function call
514 $this->classes
[] = $this->alias
['name'];
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
523 // Ignore this call to class_alias() - compat/Timestamp.php
525 $this->startToken
= null;
533 $this->tokens
[] = $token;
534 if ( is_array( $token ) && $token[0] === T_STRING
) {
535 $this->classes
[] = $this->namespace . $this->implodeTokens();
541 * Returns the string representation of the tokens within the
542 * current expect sequence and resets the sequence.
546 protected function implodeTokens() {
548 foreach ( $this->tokens
as $token ) {
549 $content[] = is_string( $token ) ?
$token : $token[1];
553 $this->startToken
= null;
555 return trim( implode( '', $content ), " \n\t" );