annotate vendor/consolidation/annotated-command/src/CommandFileDiscovery.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 129ea1e6d783
children
rev   line source
Chris@0 1 <?php
Chris@0 2 namespace Consolidation\AnnotatedCommand;
Chris@0 3
Chris@0 4 use Symfony\Component\Finder\Finder;
Chris@0 5
Chris@0 6 /**
Chris@0 7 * Do discovery presuming that the namespace of the command will
Chris@0 8 * contain the last component of the path. This is the convention
Chris@0 9 * that should be used when searching for command files that are
Chris@0 10 * bundled with the modules of a framework. The convention used
Chris@0 11 * is that the namespace for a module in a framework should start with
Chris@0 12 * the framework name followed by the module name.
Chris@0 13 *
Chris@0 14 * For example, if base namespace is "Drupal", then a command file in
Chris@0 15 * modules/default_content/src/CliTools/ExampleCommands.cpp
Chris@0 16 * will be in the namespace Drupal\default_content\CliTools.
Chris@0 17 *
Chris@0 18 * For global locations, the middle component of the namespace is
Chris@0 19 * omitted. For example, if the base namespace is "Drupal", then
Chris@0 20 * a command file in __DRUPAL_ROOT__/CliTools/ExampleCommands.cpp
Chris@0 21 * will be in the namespace Drupal\CliTools.
Chris@0 22 *
Chris@0 23 * To discover namespaced commands in modules:
Chris@0 24 *
Chris@0 25 * $commandFiles = $discovery->discoverNamespaced($moduleList, '\Drupal');
Chris@0 26 *
Chris@0 27 * To discover global commands:
Chris@0 28 *
Chris@0 29 * $commandFiles = $discovery->discover($drupalRoot, '\Drupal');
Chris@17 30 *
Chris@17 31 * WARNING:
Chris@17 32 *
Chris@17 33 * This class is deprecated. Commandfile discovery is complicated, and does
Chris@17 34 * not work from within phar files. It is recommended to instead use a static
Chris@17 35 * list of command classes as shown in https://github.com/g1a/starter/blob/master/example
Chris@17 36 *
Chris@17 37 * For a better alternative when implementing a plugin mechanism, see
Chris@17 38 * https://robo.li/extending/#register-command-files-via-psr-4-autoloading
Chris@0 39 */
Chris@0 40 class CommandFileDiscovery
Chris@0 41 {
Chris@0 42 /** @var string[] */
Chris@0 43 protected $excludeList;
Chris@0 44 /** @var string[] */
Chris@0 45 protected $searchLocations;
Chris@0 46 /** @var string */
Chris@0 47 protected $searchPattern = '*Commands.php';
Chris@0 48 /** @var boolean */
Chris@0 49 protected $includeFilesAtBase = true;
Chris@0 50 /** @var integer */
Chris@0 51 protected $searchDepth = 2;
Chris@0 52 /** @var bool */
Chris@0 53 protected $followLinks = false;
Chris@17 54 /** @var string[] */
Chris@17 55 protected $strippedNamespaces;
Chris@0 56
Chris@0 57 public function __construct()
Chris@0 58 {
Chris@0 59 $this->excludeList = ['Exclude'];
Chris@0 60 $this->searchLocations = [
Chris@0 61 'Command',
Chris@0 62 'CliTools', // TODO: Maybe remove
Chris@0 63 ];
Chris@0 64 }
Chris@0 65
Chris@0 66 /**
Chris@0 67 * Specify whether to search for files at the base directory
Chris@0 68 * ($directoryList parameter to discover and discoverNamespaced
Chris@0 69 * methods), or only in the directories listed in the search paths.
Chris@0 70 *
Chris@0 71 * @param boolean $includeFilesAtBase
Chris@0 72 */
Chris@0 73 public function setIncludeFilesAtBase($includeFilesAtBase)
Chris@0 74 {
Chris@0 75 $this->includeFilesAtBase = $includeFilesAtBase;
Chris@0 76 return $this;
Chris@0 77 }
Chris@0 78
Chris@0 79 /**
Chris@0 80 * Set the list of excludes to add to the finder, replacing
Chris@0 81 * whatever was there before.
Chris@0 82 *
Chris@0 83 * @param array $excludeList The list of directory names to skip when
Chris@0 84 * searching for command files.
Chris@0 85 */
Chris@0 86 public function setExcludeList($excludeList)
Chris@0 87 {
Chris@0 88 $this->excludeList = $excludeList;
Chris@0 89 return $this;
Chris@0 90 }
Chris@0 91
Chris@0 92 /**
Chris@0 93 * Add one more location to the exclude list.
Chris@0 94 *
Chris@0 95 * @param string $exclude One directory name to skip when searching
Chris@0 96 * for command files.
Chris@0 97 */
Chris@0 98 public function addExclude($exclude)
Chris@0 99 {
Chris@0 100 $this->excludeList[] = $exclude;
Chris@0 101 return $this;
Chris@0 102 }
Chris@0 103
Chris@0 104 /**
Chris@0 105 * Set the search depth. By default, fills immediately in the
Chris@0 106 * base directory are searched, plus all of the search locations
Chris@0 107 * to this specified depth. If the search locations is set to
Chris@0 108 * an empty array, then the base directory is searched to this
Chris@0 109 * depth.
Chris@0 110 */
Chris@0 111 public function setSearchDepth($searchDepth)
Chris@0 112 {
Chris@0 113 $this->searchDepth = $searchDepth;
Chris@0 114 return $this;
Chris@0 115 }
Chris@0 116
Chris@0 117 /**
Chris@0 118 * Specify that the discovery object should follow symlinks. By
Chris@0 119 * default, symlinks are not followed.
Chris@0 120 */
Chris@0 121 public function followLinks($followLinks = true)
Chris@0 122 {
Chris@0 123 $this->followLinks = $followLinks;
Chris@0 124 return $this;
Chris@0 125 }
Chris@0 126
Chris@0 127 /**
Chris@0 128 * Set the list of search locations to examine in each directory where
Chris@0 129 * command files may be found. This replaces whatever was there before.
Chris@0 130 *
Chris@0 131 * @param array $searchLocations The list of locations to search for command files.
Chris@0 132 */
Chris@0 133 public function setSearchLocations($searchLocations)
Chris@0 134 {
Chris@0 135 $this->searchLocations = $searchLocations;
Chris@0 136 return $this;
Chris@0 137 }
Chris@0 138
Chris@0 139 /**
Chris@17 140 * Set a particular namespace part to ignore. This is useful in plugin
Chris@17 141 * mechanisms where the plugin is placed by Composer.
Chris@17 142 *
Chris@17 143 * For example, Drush extensions are placed in `./drush/Commands`.
Chris@17 144 * If the Composer installer path is `"drush/Commands/contrib/{$name}": ["type:drupal-drush"]`,
Chris@17 145 * then Composer will place the command files in `drush/Commands/contrib`.
Chris@17 146 * The namespace should not be any different in this instance than if
Chris@17 147 * the extension were placed in `drush/Commands`, though, so Drush therefore
Chris@17 148 * calls `ignoreNamespacePart('contrib', 'Commands')`. This causes the
Chris@17 149 * `contrib` component to be removed from the namespace if it follows
Chris@17 150 * the namespace `Commands`. If the '$base' parameter is not specified, then
Chris@17 151 * the ignored portion of the namespace may appear anywhere in the path.
Chris@17 152 */
Chris@17 153 public function ignoreNamespacePart($ignore, $base = '')
Chris@17 154 {
Chris@17 155 $replacementPart = '\\';
Chris@17 156 if (!empty($base)) {
Chris@17 157 $replacementPart .= $base . '\\';
Chris@17 158 }
Chris@17 159 $ignoredPart = $replacementPart . $ignore . '\\';
Chris@17 160 $this->strippedNamespaces[$ignoredPart] = $replacementPart;
Chris@17 161
Chris@17 162 return $this;
Chris@17 163 }
Chris@17 164
Chris@17 165 /**
Chris@0 166 * Add one more location to the search location list.
Chris@0 167 *
Chris@0 168 * @param string $location One more relative path to search
Chris@0 169 * for command files.
Chris@0 170 */
Chris@0 171 public function addSearchLocation($location)
Chris@0 172 {
Chris@0 173 $this->searchLocations[] = $location;
Chris@0 174 return $this;
Chris@0 175 }
Chris@0 176
Chris@0 177 /**
Chris@0 178 * Specify the pattern / regex used by the finder to search for
Chris@0 179 * command files.
Chris@0 180 */
Chris@0 181 public function setSearchPattern($searchPattern)
Chris@0 182 {
Chris@0 183 $this->searchPattern = $searchPattern;
Chris@0 184 return $this;
Chris@0 185 }
Chris@0 186
Chris@0 187 /**
Chris@0 188 * Given a list of directories, e.g. Drupal modules like:
Chris@0 189 *
Chris@0 190 * core/modules/block
Chris@0 191 * core/modules/dblog
Chris@0 192 * modules/default_content
Chris@0 193 *
Chris@0 194 * Discover command files in any of these locations.
Chris@0 195 *
Chris@0 196 * @param string|string[] $directoryList Places to search for commands.
Chris@0 197 *
Chris@0 198 * @return array
Chris@0 199 */
Chris@0 200 public function discoverNamespaced($directoryList, $baseNamespace = '')
Chris@0 201 {
Chris@0 202 return $this->discover($this->convertToNamespacedList((array)$directoryList), $baseNamespace);
Chris@0 203 }
Chris@0 204
Chris@0 205 /**
Chris@0 206 * Given a simple list containing paths to directories, where
Chris@0 207 * the last component of the path should appear in the namespace,
Chris@0 208 * after the base namespace, this function will return an
Chris@0 209 * associative array mapping the path's basename (e.g. the module
Chris@0 210 * name) to the directory path.
Chris@0 211 *
Chris@0 212 * Module names must be unique.
Chris@0 213 *
Chris@0 214 * @param string[] $directoryList A list of module locations
Chris@0 215 *
Chris@0 216 * @return array
Chris@0 217 */
Chris@0 218 public function convertToNamespacedList($directoryList)
Chris@0 219 {
Chris@0 220 $namespacedArray = [];
Chris@0 221 foreach ((array)$directoryList as $directory) {
Chris@0 222 $namespacedArray[basename($directory)] = $directory;
Chris@0 223 }
Chris@0 224 return $namespacedArray;
Chris@0 225 }
Chris@0 226
Chris@0 227 /**
Chris@0 228 * Search for command files in the specified locations. This is the function that
Chris@0 229 * should be used for all locations that are NOT modules of a framework.
Chris@0 230 *
Chris@0 231 * @param string|string[] $directoryList Places to search for commands.
Chris@0 232 * @return array
Chris@0 233 */
Chris@0 234 public function discover($directoryList, $baseNamespace = '')
Chris@0 235 {
Chris@0 236 $commandFiles = [];
Chris@0 237 foreach ((array)$directoryList as $key => $directory) {
Chris@0 238 $itemsNamespace = $this->joinNamespace([$baseNamespace, $key]);
Chris@0 239 $commandFiles = array_merge(
Chris@0 240 $commandFiles,
Chris@0 241 $this->discoverCommandFiles($directory, $itemsNamespace),
Chris@0 242 $this->discoverCommandFiles("$directory/src", $itemsNamespace)
Chris@0 243 );
Chris@0 244 }
Chris@17 245 return $this->fixNamespaces($commandFiles);
Chris@17 246 }
Chris@17 247
Chris@17 248 /**
Chris@17 249 * fixNamespaces will alter the namespaces in the commandFiles
Chris@17 250 * result to remove the Composer placement directory, if any.
Chris@17 251 */
Chris@17 252 protected function fixNamespaces($commandFiles)
Chris@17 253 {
Chris@17 254 // Do nothing unless the client told us to remove some namespace components.
Chris@17 255 if (empty($this->strippedNamespaces)) {
Chris@17 256 return $commandFiles;
Chris@17 257 }
Chris@17 258
Chris@17 259 // Strip out any part of the namespace the client did not want.
Chris@17 260 // @see CommandFileDiscovery::ignoreNamespacePart
Chris@17 261 return array_map(
Chris@17 262 function ($fqcn) {
Chris@17 263 return str_replace(
Chris@17 264 array_keys($this->strippedNamespaces),
Chris@17 265 array_values($this->strippedNamespaces),
Chris@17 266 $fqcn
Chris@17 267 );
Chris@17 268 },
Chris@17 269 $commandFiles
Chris@17 270 );
Chris@0 271 }
Chris@0 272
Chris@0 273 /**
Chris@0 274 * Search for command files in specific locations within a single directory.
Chris@0 275 *
Chris@0 276 * In each location, we will accept only a few places where command files
Chris@0 277 * can be found. This will reduce the need to search through many unrelated
Chris@0 278 * files.
Chris@0 279 *
Chris@0 280 * The default search locations include:
Chris@0 281 *
Chris@0 282 * .
Chris@0 283 * CliTools
Chris@0 284 * src/CliTools
Chris@0 285 *
Chris@0 286 * The pattern we will look for is any file whose name ends in 'Commands.php'.
Chris@0 287 * A list of paths to found files will be returned.
Chris@0 288 */
Chris@0 289 protected function discoverCommandFiles($directory, $baseNamespace)
Chris@0 290 {
Chris@0 291 $commandFiles = [];
Chris@0 292 // In the search location itself, we will search for command files
Chris@0 293 // immediately inside the directory only.
Chris@0 294 if ($this->includeFilesAtBase) {
Chris@0 295 $commandFiles = $this->discoverCommandFilesInLocation(
Chris@0 296 $directory,
Chris@0 297 $this->getBaseDirectorySearchDepth(),
Chris@0 298 $baseNamespace
Chris@0 299 );
Chris@0 300 }
Chris@0 301
Chris@0 302 // In the other search locations,
Chris@0 303 foreach ($this->searchLocations as $location) {
Chris@0 304 $itemsNamespace = $this->joinNamespace([$baseNamespace, $location]);
Chris@0 305 $commandFiles = array_merge(
Chris@0 306 $commandFiles,
Chris@0 307 $this->discoverCommandFilesInLocation(
Chris@0 308 "$directory/$location",
Chris@0 309 $this->getSearchDepth(),
Chris@0 310 $itemsNamespace
Chris@0 311 )
Chris@0 312 );
Chris@0 313 }
Chris@0 314 return $commandFiles;
Chris@0 315 }
Chris@0 316
Chris@0 317 /**
Chris@0 318 * Return a Finder search depth appropriate for our selected search depth.
Chris@0 319 *
Chris@0 320 * @return string
Chris@0 321 */
Chris@0 322 protected function getSearchDepth()
Chris@0 323 {
Chris@0 324 return $this->searchDepth <= 0 ? '== 0' : '<= ' . $this->searchDepth;
Chris@0 325 }
Chris@0 326
Chris@0 327 /**
Chris@0 328 * Return a Finder search depth for the base directory. If the
Chris@0 329 * searchLocations array has been populated, then we will only search
Chris@0 330 * for files immediately inside the base directory; no traversal into
Chris@0 331 * deeper directories will be done, as that would conflict with the
Chris@0 332 * specification provided by the search locations. If there is no
Chris@0 333 * search location, then we will search to whatever depth was specified
Chris@0 334 * by the client.
Chris@0 335 *
Chris@0 336 * @return string
Chris@0 337 */
Chris@0 338 protected function getBaseDirectorySearchDepth()
Chris@0 339 {
Chris@0 340 if (!empty($this->searchLocations)) {
Chris@0 341 return '== 0';
Chris@0 342 }
Chris@0 343 return $this->getSearchDepth();
Chris@0 344 }
Chris@0 345
Chris@0 346 /**
Chris@0 347 * Search for command files in just one particular location. Returns
Chris@0 348 * an associative array mapping from the pathname of the file to the
Chris@0 349 * classname that it contains. The pathname may be ignored if the search
Chris@0 350 * location is included in the autoloader.
Chris@0 351 *
Chris@0 352 * @param string $directory The location to search
Chris@0 353 * @param string $depth How deep to search (e.g. '== 0' or '< 2')
Chris@0 354 * @param string $baseNamespace Namespace to prepend to each classname
Chris@0 355 *
Chris@0 356 * @return array
Chris@0 357 */
Chris@0 358 protected function discoverCommandFilesInLocation($directory, $depth, $baseNamespace)
Chris@0 359 {
Chris@0 360 if (!is_dir($directory)) {
Chris@0 361 return [];
Chris@0 362 }
Chris@0 363 $finder = $this->createFinder($directory, $depth);
Chris@0 364
Chris@0 365 $commands = [];
Chris@0 366 foreach ($finder as $file) {
Chris@0 367 $relativePathName = $file->getRelativePathname();
Chris@0 368 $relativeNamespaceAndClassname = str_replace(
Chris@17 369 ['/', '-', '.php'],
Chris@17 370 ['\\', '_', ''],
Chris@0 371 $relativePathName
Chris@0 372 );
Chris@0 373 $classname = $this->joinNamespace([$baseNamespace, $relativeNamespaceAndClassname]);
Chris@0 374 $commandFilePath = $this->joinPaths([$directory, $relativePathName]);
Chris@0 375 $commands[$commandFilePath] = $classname;
Chris@0 376 }
Chris@0 377
Chris@0 378 return $commands;
Chris@0 379 }
Chris@0 380
Chris@0 381 /**
Chris@0 382 * Create a Finder object for use in searching a particular directory
Chris@0 383 * location.
Chris@0 384 *
Chris@0 385 * @param string $directory The location to search
Chris@0 386 * @param string $depth The depth limitation
Chris@0 387 *
Chris@0 388 * @return Finder
Chris@0 389 */
Chris@0 390 protected function createFinder($directory, $depth)
Chris@0 391 {
Chris@0 392 $finder = new Finder();
Chris@0 393 $finder->files()
Chris@0 394 ->name($this->searchPattern)
Chris@0 395 ->in($directory)
Chris@0 396 ->depth($depth);
Chris@0 397
Chris@0 398 foreach ($this->excludeList as $item) {
Chris@0 399 $finder->exclude($item);
Chris@0 400 }
Chris@0 401
Chris@0 402 if ($this->followLinks) {
Chris@0 403 $finder->followLinks();
Chris@0 404 }
Chris@0 405
Chris@0 406 return $finder;
Chris@0 407 }
Chris@0 408
Chris@0 409 /**
Chris@0 410 * Combine the items of the provied array into a backslash-separated
Chris@0 411 * namespace string. Empty and numeric items are omitted.
Chris@0 412 *
Chris@0 413 * @param array $namespaceParts List of components of a namespace
Chris@0 414 *
Chris@0 415 * @return string
Chris@0 416 */
Chris@0 417 protected function joinNamespace(array $namespaceParts)
Chris@0 418 {
Chris@0 419 return $this->joinParts(
Chris@0 420 '\\',
Chris@0 421 $namespaceParts,
Chris@0 422 function ($item) {
Chris@0 423 return !is_numeric($item) && !empty($item);
Chris@0 424 }
Chris@0 425 );
Chris@0 426 }
Chris@0 427
Chris@0 428 /**
Chris@0 429 * Combine the items of the provied array into a slash-separated
Chris@0 430 * pathname. Empty items are omitted.
Chris@0 431 *
Chris@0 432 * @param array $pathParts List of components of a path
Chris@0 433 *
Chris@0 434 * @return string
Chris@0 435 */
Chris@0 436 protected function joinPaths(array $pathParts)
Chris@0 437 {
Chris@0 438 $path = $this->joinParts(
Chris@0 439 '/',
Chris@0 440 $pathParts,
Chris@0 441 function ($item) {
Chris@0 442 return !empty($item);
Chris@0 443 }
Chris@0 444 );
Chris@0 445 return str_replace(DIRECTORY_SEPARATOR, '/', $path);
Chris@0 446 }
Chris@0 447
Chris@0 448 /**
Chris@0 449 * Simple wrapper around implode and array_filter.
Chris@0 450 *
Chris@0 451 * @param string $delimiter
Chris@0 452 * @param array $parts
Chris@0 453 * @param callable $filterFunction
Chris@0 454 */
Chris@0 455 protected function joinParts($delimiter, $parts, $filterFunction)
Chris@0 456 {
Chris@0 457 $parts = array_map(
Chris@0 458 function ($item) use ($delimiter) {
Chris@0 459 return rtrim($item, $delimiter);
Chris@0 460 },
Chris@0 461 $parts
Chris@0 462 );
Chris@0 463 return implode(
Chris@0 464 $delimiter,
Chris@0 465 array_filter($parts, $filterFunction)
Chris@0 466 );
Chris@0 467 }
Chris@0 468 }