2 namespace Consolidation\AnnotatedCommand;
4 use Symfony\Component\Finder\Finder;
7 * Do discovery presuming that the namespace of the command will
8 * contain the last component of the path. This is the convention
9 * that should be used when searching for command files that are
10 * bundled with the modules of a framework. The convention used
11 * is that the namespace for a module in a framework should start with
12 * the framework name followed by the module name.
14 * For example, if base namespace is "Drupal", then a command file in
15 * modules/default_content/src/CliTools/ExampleCommands.cpp
16 * will be in the namespace Drupal\default_content\CliTools.
18 * For global locations, the middle component of the namespace is
19 * omitted. For example, if the base namespace is "Drupal", then
20 * a command file in __DRUPAL_ROOT__/CliTools/ExampleCommands.cpp
21 * will be in the namespace Drupal\CliTools.
23 * To discover namespaced commands in modules:
25 * $commandFiles = $discovery->discoverNamespaced($moduleList, '\Drupal');
27 * To discover global commands:
29 * $commandFiles = $discovery->discover($drupalRoot, '\Drupal');
31 class CommandFileDiscovery
34 protected $excludeList;
36 protected $searchLocations;
38 protected $searchPattern = '*Commands.php';
40 protected $includeFilesAtBase = true;
42 protected $searchDepth = 2;
44 protected $followLinks = false;
46 public function __construct()
48 $this->excludeList = ['Exclude'];
49 $this->searchLocations = [
51 'CliTools', // TODO: Maybe remove
56 * Specify whether to search for files at the base directory
57 * ($directoryList parameter to discover and discoverNamespaced
58 * methods), or only in the directories listed in the search paths.
60 * @param boolean $includeFilesAtBase
62 public function setIncludeFilesAtBase($includeFilesAtBase)
64 $this->includeFilesAtBase = $includeFilesAtBase;
69 * Set the list of excludes to add to the finder, replacing
70 * whatever was there before.
72 * @param array $excludeList The list of directory names to skip when
73 * searching for command files.
75 public function setExcludeList($excludeList)
77 $this->excludeList = $excludeList;
82 * Add one more location to the exclude list.
84 * @param string $exclude One directory name to skip when searching
87 public function addExclude($exclude)
89 $this->excludeList[] = $exclude;
94 * Set the search depth. By default, fills immediately in the
95 * base directory are searched, plus all of the search locations
96 * to this specified depth. If the search locations is set to
97 * an empty array, then the base directory is searched to this
100 public function setSearchDepth($searchDepth)
102 $this->searchDepth = $searchDepth;
107 * Specify that the discovery object should follow symlinks. By
108 * default, symlinks are not followed.
110 public function followLinks($followLinks = true)
112 $this->followLinks = $followLinks;
117 * Set the list of search locations to examine in each directory where
118 * command files may be found. This replaces whatever was there before.
120 * @param array $searchLocations The list of locations to search for command files.
122 public function setSearchLocations($searchLocations)
124 $this->searchLocations = $searchLocations;
129 * Add one more location to the search location list.
131 * @param string $location One more relative path to search
134 public function addSearchLocation($location)
136 $this->searchLocations[] = $location;
141 * Specify the pattern / regex used by the finder to search for
144 public function setSearchPattern($searchPattern)
146 $this->searchPattern = $searchPattern;
151 * Given a list of directories, e.g. Drupal modules like:
155 * modules/default_content
157 * Discover command files in any of these locations.
159 * @param string|string[] $directoryList Places to search for commands.
163 public function discoverNamespaced($directoryList, $baseNamespace = '')
165 return $this->discover($this->convertToNamespacedList((array)$directoryList), $baseNamespace);
169 * Given a simple list containing paths to directories, where
170 * the last component of the path should appear in the namespace,
171 * after the base namespace, this function will return an
172 * associative array mapping the path's basename (e.g. the module
173 * name) to the directory path.
175 * Module names must be unique.
177 * @param string[] $directoryList A list of module locations
181 public function convertToNamespacedList($directoryList)
183 $namespacedArray = [];
184 foreach ((array)$directoryList as $directory) {
185 $namespacedArray[basename($directory)] = $directory;
187 return $namespacedArray;
191 * Search for command files in the specified locations. This is the function that
192 * should be used for all locations that are NOT modules of a framework.
194 * @param string|string[] $directoryList Places to search for commands.
197 public function discover($directoryList, $baseNamespace = '')
200 foreach ((array)$directoryList as $key => $directory) {
201 $itemsNamespace = $this->joinNamespace([$baseNamespace, $key]);
202 $commandFiles = array_merge(
204 $this->discoverCommandFiles($directory, $itemsNamespace),
205 $this->discoverCommandFiles("$directory/src", $itemsNamespace)
208 return $commandFiles;
212 * Search for command files in specific locations within a single directory.
214 * In each location, we will accept only a few places where command files
215 * can be found. This will reduce the need to search through many unrelated
218 * The default search locations include:
224 * The pattern we will look for is any file whose name ends in 'Commands.php'.
225 * A list of paths to found files will be returned.
227 protected function discoverCommandFiles($directory, $baseNamespace)
230 // In the search location itself, we will search for command files
231 // immediately inside the directory only.
232 if ($this->includeFilesAtBase) {
233 $commandFiles = $this->discoverCommandFilesInLocation(
235 $this->getBaseDirectorySearchDepth(),
240 // In the other search locations,
241 foreach ($this->searchLocations as $location) {
242 $itemsNamespace = $this->joinNamespace([$baseNamespace, $location]);
243 $commandFiles = array_merge(
245 $this->discoverCommandFilesInLocation(
246 "$directory/$location",
247 $this->getSearchDepth(),
252 return $commandFiles;
256 * Return a Finder search depth appropriate for our selected search depth.
260 protected function getSearchDepth()
262 return $this->searchDepth <= 0 ? '== 0' : '<= ' . $this->searchDepth;
266 * Return a Finder search depth for the base directory. If the
267 * searchLocations array has been populated, then we will only search
268 * for files immediately inside the base directory; no traversal into
269 * deeper directories will be done, as that would conflict with the
270 * specification provided by the search locations. If there is no
271 * search location, then we will search to whatever depth was specified
276 protected function getBaseDirectorySearchDepth()
278 if (!empty($this->searchLocations)) {
281 return $this->getSearchDepth();
285 * Search for command files in just one particular location. Returns
286 * an associative array mapping from the pathname of the file to the
287 * classname that it contains. The pathname may be ignored if the search
288 * location is included in the autoloader.
290 * @param string $directory The location to search
291 * @param string $depth How deep to search (e.g. '== 0' or '< 2')
292 * @param string $baseNamespace Namespace to prepend to each classname
296 protected function discoverCommandFilesInLocation($directory, $depth, $baseNamespace)
298 if (!is_dir($directory)) {
301 $finder = $this->createFinder($directory, $depth);
304 foreach ($finder as $file) {
305 $relativePathName = $file->getRelativePathname();
306 $relativeNamespaceAndClassname = str_replace(
311 $classname = $this->joinNamespace([$baseNamespace, $relativeNamespaceAndClassname]);
312 $commandFilePath = $this->joinPaths([$directory, $relativePathName]);
313 $commands[$commandFilePath] = $classname;
320 * Create a Finder object for use in searching a particular directory
323 * @param string $directory The location to search
324 * @param string $depth The depth limitation
328 protected function createFinder($directory, $depth)
330 $finder = new Finder();
332 ->name($this->searchPattern)
336 foreach ($this->excludeList as $item) {
337 $finder->exclude($item);
340 if ($this->followLinks) {
341 $finder->followLinks();
348 * Combine the items of the provied array into a backslash-separated
349 * namespace string. Empty and numeric items are omitted.
351 * @param array $namespaceParts List of components of a namespace
355 protected function joinNamespace(array $namespaceParts)
357 return $this->joinParts(
361 return !is_numeric($item) && !empty($item);
367 * Combine the items of the provied array into a slash-separated
368 * pathname. Empty items are omitted.
370 * @param array $pathParts List of components of a path
374 protected function joinPaths(array $pathParts)
376 $path = $this->joinParts(
380 return !empty($item);
383 return str_replace(DIRECTORY_SEPARATOR, '/', $path);
387 * Simple wrapper around implode and array_filter.
389 * @param string $delimiter
390 * @param array $parts
391 * @param callable $filterFunction
393 protected function joinParts($delimiter, $parts, $filterFunction)
396 function ($item) use ($delimiter) {
397 return rtrim($item, $delimiter);
403 array_filter($parts, $filterFunction)