Chris@0: <?php
Chris@0: namespace Consolidation\AnnotatedCommand;
Chris@0: 
Chris@0: use Symfony\Component\Finder\Finder;
Chris@0: 
Chris@0: /**
Chris@0:  * Do discovery presuming that the namespace of the command will
Chris@0:  * contain the last component of the path.  This is the convention
Chris@0:  * that should be used when searching for command files that are
Chris@0:  * bundled with the modules of a framework.  The convention used
Chris@0:  * is that the namespace for a module in a framework should start with
Chris@0:  * the framework name followed by the module name.
Chris@0:  *
Chris@0:  * For example, if base namespace is "Drupal", then a command file in
Chris@0:  * modules/default_content/src/CliTools/ExampleCommands.cpp
Chris@0:  * will be in the namespace Drupal\default_content\CliTools.
Chris@0:  *
Chris@0:  * For global locations, the middle component of the namespace is
Chris@0:  * omitted.  For example, if the base namespace is "Drupal", then
Chris@0:  * a command file in __DRUPAL_ROOT__/CliTools/ExampleCommands.cpp
Chris@0:  * will be in the namespace Drupal\CliTools.
Chris@0:  *
Chris@0:  * To discover namespaced commands in modules:
Chris@0:  *
Chris@0:  * $commandFiles = $discovery->discoverNamespaced($moduleList, '\Drupal');
Chris@0:  *
Chris@0:  * To discover global commands:
Chris@0:  *
Chris@0:  * $commandFiles = $discovery->discover($drupalRoot, '\Drupal');
Chris@17:  *
Chris@17:  * WARNING:
Chris@17:  *
Chris@17:  * This class is deprecated. Commandfile discovery is complicated, and does
Chris@17:  * not work from within phar files. It is recommended to instead use a static
Chris@17:  * list of command classes as shown in https://github.com/g1a/starter/blob/master/example
Chris@17:  *
Chris@17:  * For a better alternative when implementing a plugin mechanism, see
Chris@17:  * https://robo.li/extending/#register-command-files-via-psr-4-autoloading
Chris@0:  */
Chris@0: class CommandFileDiscovery
Chris@0: {
Chris@0:     /** @var string[] */
Chris@0:     protected $excludeList;
Chris@0:     /** @var string[] */
Chris@0:     protected $searchLocations;
Chris@0:     /** @var string */
Chris@0:     protected $searchPattern = '*Commands.php';
Chris@0:     /** @var boolean */
Chris@0:     protected $includeFilesAtBase = true;
Chris@0:     /** @var integer */
Chris@0:     protected $searchDepth = 2;
Chris@0:     /** @var bool */
Chris@0:     protected $followLinks = false;
Chris@17:     /** @var string[] */
Chris@17:     protected $strippedNamespaces;
Chris@0: 
Chris@0:     public function __construct()
Chris@0:     {
Chris@0:         $this->excludeList = ['Exclude'];
Chris@0:         $this->searchLocations = [
Chris@0:             'Command',
Chris@0:             'CliTools', // TODO: Maybe remove
Chris@0:         ];
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Specify whether to search for files at the base directory
Chris@0:      * ($directoryList parameter to discover and discoverNamespaced
Chris@0:      * methods), or only in the directories listed in the search paths.
Chris@0:      *
Chris@0:      * @param boolean $includeFilesAtBase
Chris@0:      */
Chris@0:     public function setIncludeFilesAtBase($includeFilesAtBase)
Chris@0:     {
Chris@0:         $this->includeFilesAtBase = $includeFilesAtBase;
Chris@0:         return $this;
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Set the list of excludes to add to the finder, replacing
Chris@0:      * whatever was there before.
Chris@0:      *
Chris@0:      * @param array $excludeList The list of directory names to skip when
Chris@0:      *   searching for command files.
Chris@0:      */
Chris@0:     public function setExcludeList($excludeList)
Chris@0:     {
Chris@0:         $this->excludeList = $excludeList;
Chris@0:         return $this;
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Add one more location to the exclude list.
Chris@0:      *
Chris@0:      * @param string $exclude One directory name to skip when searching
Chris@0:      *   for command files.
Chris@0:      */
Chris@0:     public function addExclude($exclude)
Chris@0:     {
Chris@0:         $this->excludeList[] = $exclude;
Chris@0:         return $this;
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Set the search depth.  By default, fills immediately in the
Chris@0:      * base directory are searched, plus all of the search locations
Chris@0:      * to this specified depth.  If the search locations is set to
Chris@0:      * an empty array, then the base directory is searched to this
Chris@0:      * depth.
Chris@0:      */
Chris@0:     public function setSearchDepth($searchDepth)
Chris@0:     {
Chris@0:         $this->searchDepth = $searchDepth;
Chris@0:         return $this;
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Specify that the discovery object should follow symlinks. By
Chris@0:      * default, symlinks are not followed.
Chris@0:      */
Chris@0:     public function followLinks($followLinks = true)
Chris@0:     {
Chris@0:         $this->followLinks = $followLinks;
Chris@0:         return $this;
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Set the list of search locations to examine in each directory where
Chris@0:      * command files may be found.  This replaces whatever was there before.
Chris@0:      *
Chris@0:      * @param array $searchLocations The list of locations to search for command files.
Chris@0:      */
Chris@0:     public function setSearchLocations($searchLocations)
Chris@0:     {
Chris@0:         $this->searchLocations = $searchLocations;
Chris@0:         return $this;
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@17:      * Set a particular namespace part to ignore. This is useful in plugin
Chris@17:      * mechanisms where the plugin is placed by Composer.
Chris@17:      *
Chris@17:      * For example, Drush extensions are placed in `./drush/Commands`.
Chris@17:      * If the Composer installer path is `"drush/Commands/contrib/{$name}": ["type:drupal-drush"]`,
Chris@17:      * then Composer will place the command files in `drush/Commands/contrib`.
Chris@17:      * The namespace should not be any different in this instance than if
Chris@17:      * the extension were placed in `drush/Commands`, though, so Drush therefore
Chris@17:      * calls `ignoreNamespacePart('contrib', 'Commands')`. This causes the
Chris@17:      * `contrib` component to be removed from the namespace if it follows
Chris@17:      * the namespace `Commands`. If the '$base' parameter is not specified, then
Chris@17:      * the ignored portion of the namespace may appear anywhere in the path.
Chris@17:      */
Chris@17:     public function ignoreNamespacePart($ignore, $base = '')
Chris@17:     {
Chris@17:         $replacementPart = '\\';
Chris@17:         if (!empty($base)) {
Chris@17:             $replacementPart .= $base . '\\';
Chris@17:         }
Chris@17:         $ignoredPart = $replacementPart . $ignore . '\\';
Chris@17:         $this->strippedNamespaces[$ignoredPart] = $replacementPart;
Chris@17: 
Chris@17:         return $this;
Chris@17:     }
Chris@17: 
Chris@17:     /**
Chris@0:      * Add one more location to the search location list.
Chris@0:      *
Chris@0:      * @param string $location One more relative path to search
Chris@0:      *   for command files.
Chris@0:      */
Chris@0:     public function addSearchLocation($location)
Chris@0:     {
Chris@0:         $this->searchLocations[] = $location;
Chris@0:         return $this;
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Specify the pattern / regex used by the finder to search for
Chris@0:      * command files.
Chris@0:      */
Chris@0:     public function setSearchPattern($searchPattern)
Chris@0:     {
Chris@0:         $this->searchPattern = $searchPattern;
Chris@0:         return $this;
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Given a list of directories, e.g. Drupal modules like:
Chris@0:      *
Chris@0:      *    core/modules/block
Chris@0:      *    core/modules/dblog
Chris@0:      *    modules/default_content
Chris@0:      *
Chris@0:      * Discover command files in any of these locations.
Chris@0:      *
Chris@0:      * @param string|string[] $directoryList Places to search for commands.
Chris@0:      *
Chris@0:      * @return array
Chris@0:      */
Chris@0:     public function discoverNamespaced($directoryList, $baseNamespace = '')
Chris@0:     {
Chris@0:         return $this->discover($this->convertToNamespacedList((array)$directoryList), $baseNamespace);
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Given a simple list containing paths to directories, where
Chris@0:      * the last component of the path should appear in the namespace,
Chris@0:      * after the base namespace, this function will return an
Chris@0:      * associative array mapping the path's basename (e.g. the module
Chris@0:      * name) to the directory path.
Chris@0:      *
Chris@0:      * Module names must be unique.
Chris@0:      *
Chris@0:      * @param string[] $directoryList A list of module locations
Chris@0:      *
Chris@0:      * @return array
Chris@0:      */
Chris@0:     public function convertToNamespacedList($directoryList)
Chris@0:     {
Chris@0:         $namespacedArray = [];
Chris@0:         foreach ((array)$directoryList as $directory) {
Chris@0:             $namespacedArray[basename($directory)] = $directory;
Chris@0:         }
Chris@0:         return $namespacedArray;
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Search for command files in the specified locations. This is the function that
Chris@0:      * should be used for all locations that are NOT modules of a framework.
Chris@0:      *
Chris@0:      * @param string|string[] $directoryList Places to search for commands.
Chris@0:      * @return array
Chris@0:      */
Chris@0:     public function discover($directoryList, $baseNamespace = '')
Chris@0:     {
Chris@0:         $commandFiles = [];
Chris@0:         foreach ((array)$directoryList as $key => $directory) {
Chris@0:             $itemsNamespace = $this->joinNamespace([$baseNamespace, $key]);
Chris@0:             $commandFiles = array_merge(
Chris@0:                 $commandFiles,
Chris@0:                 $this->discoverCommandFiles($directory, $itemsNamespace),
Chris@0:                 $this->discoverCommandFiles("$directory/src", $itemsNamespace)
Chris@0:             );
Chris@0:         }
Chris@17:         return $this->fixNamespaces($commandFiles);
Chris@17:     }
Chris@17: 
Chris@17:     /**
Chris@17:      * fixNamespaces will alter the namespaces in the commandFiles
Chris@17:      * result to remove the Composer placement directory, if any.
Chris@17:      */
Chris@17:     protected function fixNamespaces($commandFiles)
Chris@17:     {
Chris@17:         // Do nothing unless the client told us to remove some namespace components.
Chris@17:         if (empty($this->strippedNamespaces)) {
Chris@17:             return $commandFiles;
Chris@17:         }
Chris@17: 
Chris@17:         // Strip out any part of the namespace the client did not want.
Chris@17:         // @see CommandFileDiscovery::ignoreNamespacePart
Chris@17:         return array_map(
Chris@17:             function ($fqcn) {
Chris@17:                 return str_replace(
Chris@17:                     array_keys($this->strippedNamespaces),
Chris@17:                     array_values($this->strippedNamespaces),
Chris@17:                     $fqcn
Chris@17:                 );
Chris@17:             },
Chris@17:             $commandFiles
Chris@17:         );
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Search for command files in specific locations within a single directory.
Chris@0:      *
Chris@0:      * In each location, we will accept only a few places where command files
Chris@0:      * can be found. This will reduce the need to search through many unrelated
Chris@0:      * files.
Chris@0:      *
Chris@0:      * The default search locations include:
Chris@0:      *
Chris@0:      *    .
Chris@0:      *    CliTools
Chris@0:      *    src/CliTools
Chris@0:      *
Chris@0:      * The pattern we will look for is any file whose name ends in 'Commands.php'.
Chris@0:      * A list of paths to found files will be returned.
Chris@0:      */
Chris@0:     protected function discoverCommandFiles($directory, $baseNamespace)
Chris@0:     {
Chris@0:         $commandFiles = [];
Chris@0:         // In the search location itself, we will search for command files
Chris@0:         // immediately inside the directory only.
Chris@0:         if ($this->includeFilesAtBase) {
Chris@0:             $commandFiles = $this->discoverCommandFilesInLocation(
Chris@0:                 $directory,
Chris@0:                 $this->getBaseDirectorySearchDepth(),
Chris@0:                 $baseNamespace
Chris@0:             );
Chris@0:         }
Chris@0: 
Chris@0:         // In the other search locations,
Chris@0:         foreach ($this->searchLocations as $location) {
Chris@0:             $itemsNamespace = $this->joinNamespace([$baseNamespace, $location]);
Chris@0:             $commandFiles = array_merge(
Chris@0:                 $commandFiles,
Chris@0:                 $this->discoverCommandFilesInLocation(
Chris@0:                     "$directory/$location",
Chris@0:                     $this->getSearchDepth(),
Chris@0:                     $itemsNamespace
Chris@0:                 )
Chris@0:             );
Chris@0:         }
Chris@0:         return $commandFiles;
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Return a Finder search depth appropriate for our selected search depth.
Chris@0:      *
Chris@0:      * @return string
Chris@0:      */
Chris@0:     protected function getSearchDepth()
Chris@0:     {
Chris@0:         return $this->searchDepth <= 0 ? '== 0' : '<= ' . $this->searchDepth;
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Return a Finder search depth for the base directory.  If the
Chris@0:      * searchLocations array has been populated, then we will only search
Chris@0:      * for files immediately inside the base directory; no traversal into
Chris@0:      * deeper directories will be done, as that would conflict with the
Chris@0:      * specification provided by the search locations.  If there is no
Chris@0:      * search location, then we will search to whatever depth was specified
Chris@0:      * by the client.
Chris@0:      *
Chris@0:      * @return string
Chris@0:      */
Chris@0:     protected function getBaseDirectorySearchDepth()
Chris@0:     {
Chris@0:         if (!empty($this->searchLocations)) {
Chris@0:             return '== 0';
Chris@0:         }
Chris@0:         return $this->getSearchDepth();
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Search for command files in just one particular location.  Returns
Chris@0:      * an associative array mapping from the pathname of the file to the
Chris@0:      * classname that it contains.  The pathname may be ignored if the search
Chris@0:      * location is included in the autoloader.
Chris@0:      *
Chris@0:      * @param string $directory The location to search
Chris@0:      * @param string $depth How deep to search (e.g. '== 0' or '< 2')
Chris@0:      * @param string $baseNamespace Namespace to prepend to each classname
Chris@0:      *
Chris@0:      * @return array
Chris@0:      */
Chris@0:     protected function discoverCommandFilesInLocation($directory, $depth, $baseNamespace)
Chris@0:     {
Chris@0:         if (!is_dir($directory)) {
Chris@0:             return [];
Chris@0:         }
Chris@0:         $finder = $this->createFinder($directory, $depth);
Chris@0: 
Chris@0:         $commands = [];
Chris@0:         foreach ($finder as $file) {
Chris@0:             $relativePathName = $file->getRelativePathname();
Chris@0:             $relativeNamespaceAndClassname = str_replace(
Chris@17:                 ['/', '-', '.php'],
Chris@17:                 ['\\', '_', ''],
Chris@0:                 $relativePathName
Chris@0:             );
Chris@0:             $classname = $this->joinNamespace([$baseNamespace, $relativeNamespaceAndClassname]);
Chris@0:             $commandFilePath = $this->joinPaths([$directory, $relativePathName]);
Chris@0:             $commands[$commandFilePath] = $classname;
Chris@0:         }
Chris@0: 
Chris@0:         return $commands;
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Create a Finder object for use in searching a particular directory
Chris@0:      * location.
Chris@0:      *
Chris@0:      * @param string $directory The location to search
Chris@0:      * @param string $depth The depth limitation
Chris@0:      *
Chris@0:      * @return Finder
Chris@0:      */
Chris@0:     protected function createFinder($directory, $depth)
Chris@0:     {
Chris@0:         $finder = new Finder();
Chris@0:         $finder->files()
Chris@0:             ->name($this->searchPattern)
Chris@0:             ->in($directory)
Chris@0:             ->depth($depth);
Chris@0: 
Chris@0:         foreach ($this->excludeList as $item) {
Chris@0:             $finder->exclude($item);
Chris@0:         }
Chris@0: 
Chris@0:         if ($this->followLinks) {
Chris@0:             $finder->followLinks();
Chris@0:         }
Chris@0: 
Chris@0:         return $finder;
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Combine the items of the provied array into a backslash-separated
Chris@0:      * namespace string.  Empty and numeric items are omitted.
Chris@0:      *
Chris@0:      * @param array $namespaceParts List of components of a namespace
Chris@0:      *
Chris@0:      * @return string
Chris@0:      */
Chris@0:     protected function joinNamespace(array $namespaceParts)
Chris@0:     {
Chris@0:         return $this->joinParts(
Chris@0:             '\\',
Chris@0:             $namespaceParts,
Chris@0:             function ($item) {
Chris@0:                 return !is_numeric($item) && !empty($item);
Chris@0:             }
Chris@0:         );
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Combine the items of the provied array into a slash-separated
Chris@0:      * pathname.  Empty items are omitted.
Chris@0:      *
Chris@0:      * @param array $pathParts List of components of a path
Chris@0:      *
Chris@0:      * @return string
Chris@0:      */
Chris@0:     protected function joinPaths(array $pathParts)
Chris@0:     {
Chris@0:         $path = $this->joinParts(
Chris@0:             '/',
Chris@0:             $pathParts,
Chris@0:             function ($item) {
Chris@0:                 return !empty($item);
Chris@0:             }
Chris@0:         );
Chris@0:         return str_replace(DIRECTORY_SEPARATOR, '/', $path);
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Simple wrapper around implode and array_filter.
Chris@0:      *
Chris@0:      * @param string $delimiter
Chris@0:      * @param array $parts
Chris@0:      * @param callable $filterFunction
Chris@0:      */
Chris@0:     protected function joinParts($delimiter, $parts, $filterFunction)
Chris@0:     {
Chris@0:         $parts = array_map(
Chris@0:             function ($item) use ($delimiter) {
Chris@0:                 return rtrim($item, $delimiter);
Chris@0:             },
Chris@0:             $parts
Chris@0:         );
Chris@0:         return implode(
Chris@0:             $delimiter,
Chris@0:             array_filter($parts, $filterFunction)
Chris@0:         );
Chris@0:     }
Chris@0: }