1: <?php
2: /**
3: * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
4: * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
5: *
6: * Licensed under The MIT License
7: * For full copyright and license information, please see the LICENSE.txt
8: * Redistributions of files must retain the above copyright notice.
9: *
10: * @copyright Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
11: * @link http://cakephp.org CakePHP(tm) Project
12: * @since 3.5.0
13: * @license http://www.opensource.org/licenses/mit-license.php MIT License
14: */
15: namespace Cake\Console;
16:
17: use Cake\Command\HelpCommand;
18: use Cake\Command\VersionCommand;
19: use Cake\Console\Exception\StopException;
20: use Cake\Core\ConsoleApplicationInterface;
21: use Cake\Core\HttpApplicationInterface;
22: use Cake\Core\PluginApplicationInterface;
23: use Cake\Event\EventDispatcherInterface;
24: use Cake\Event\EventDispatcherTrait;
25: use Cake\Event\EventManager;
26: use Cake\Routing\Router;
27: use Cake\Utility\Inflector;
28: use InvalidArgumentException;
29: use RuntimeException;
30:
31: /**
32: * Run CLI commands for the provided application.
33: */
34: class CommandRunner implements EventDispatcherInterface
35: {
36: /**
37: * Alias methods away so we can implement proxying methods.
38: */
39: use EventDispatcherTrait {
40: eventManager as private _eventManager;
41: getEventManager as private _getEventManager;
42: setEventManager as private _setEventManager;
43: }
44:
45: /**
46: * The application console commands are being run for.
47: *
48: * @var \Cake\Core\ConsoleApplicationInterface
49: */
50: protected $app;
51:
52: /**
53: * The application console commands are being run for.
54: *
55: * @var \Cake\Console\CommandFactoryInterface
56: */
57: protected $factory;
58:
59: /**
60: * The root command name. Defaults to `cake`.
61: *
62: * @var string
63: */
64: protected $root;
65:
66: /**
67: * Alias mappings.
68: *
69: * @var array
70: */
71: protected $aliases = [];
72:
73: /**
74: * Constructor
75: *
76: * @param \Cake\Core\ConsoleApplicationInterface $app The application to run CLI commands for.
77: * @param string $root The root command name to be removed from argv.
78: * @param \Cake\Console\CommandFactoryInterface|null $factory Command factory instance.
79: */
80: public function __construct(ConsoleApplicationInterface $app, $root = 'cake', CommandFactoryInterface $factory = null)
81: {
82: $this->app = $app;
83: $this->root = $root;
84: $this->factory = $factory ?: new CommandFactory();
85: $this->aliases = [
86: '--version' => 'version',
87: '--help' => 'help',
88: '-h' => 'help',
89: ];
90: }
91:
92: /**
93: * Replace the entire alias map for a runner.
94: *
95: * Aliases allow you to define alternate names for commands
96: * in the collection. This can be useful to add top level switches
97: * like `--version` or `-h`
98: *
99: * ### Usage
100: *
101: * ```
102: * $runner->setAliases(['--version' => 'version']);
103: * ```
104: *
105: * @param string[] $aliases The map of aliases to replace.
106: * @return $this
107: */
108: public function setAliases(array $aliases)
109: {
110: $this->aliases = $aliases;
111:
112: return $this;
113: }
114:
115: /**
116: * Run the command contained in $argv.
117: *
118: * Use the application to do the following:
119: *
120: * - Bootstrap the application
121: * - Create the CommandCollection using the console() hook on the application.
122: * - Trigger the `Console.buildCommands` event of auto-wiring plugins.
123: * - Run the requested command.
124: *
125: * @param array $argv The arguments from the CLI environment.
126: * @param \Cake\Console\ConsoleIo $io The ConsoleIo instance. Used primarily for testing.
127: * @return int The exit code of the command.
128: * @throws \RuntimeException
129: */
130: public function run(array $argv, ConsoleIo $io = null)
131: {
132: $this->bootstrap();
133:
134: $commands = new CommandCollection([
135: 'version' => VersionCommand::class,
136: 'help' => HelpCommand::class,
137: ]);
138: $commands = $this->app->console($commands);
139: $this->checkCollection($commands, 'console');
140:
141: if ($this->app instanceof PluginApplicationInterface) {
142: $commands = $this->app->pluginConsole($commands);
143: }
144: $this->checkCollection($commands, 'pluginConsole');
145: $this->dispatchEvent('Console.buildCommands', ['commands' => $commands]);
146: $this->loadRoutes();
147:
148: if (empty($argv)) {
149: throw new RuntimeException("Cannot run any commands. No arguments received.");
150: }
151: // Remove the root executable segment
152: array_shift($argv);
153:
154: $io = $io ?: new ConsoleIo();
155:
156: list($name, $argv) = $this->longestCommandName($commands, $argv);
157: $name = $this->resolveName($commands, $io, $name);
158:
159: $result = Command::CODE_ERROR;
160: $shell = $this->getShell($io, $commands, $name);
161: if ($shell instanceof Shell) {
162: $result = $this->runShell($shell, $argv);
163: }
164: if ($shell instanceof Command) {
165: $result = $this->runCommand($shell, $argv, $io);
166: }
167:
168: if ($result === null || $result === true) {
169: return Command::CODE_SUCCESS;
170: }
171: if (is_int($result) && $result >= 0 && $result <= 255) {
172: return $result;
173: }
174:
175: return Command::CODE_ERROR;
176: }
177:
178: /**
179: * Application bootstrap wrapper.
180: *
181: * Calls `bootstrap()` and `events()` if application implements `EventApplicationInterface`.
182: * After the application is bootstrapped and events are attached, plugins are bootstrapped
183: * and have their events attached.
184: *
185: * @return void
186: */
187: protected function bootstrap()
188: {
189: $this->app->bootstrap();
190: if ($this->app instanceof PluginApplicationInterface) {
191: $this->app->pluginBootstrap();
192: }
193: }
194:
195: /**
196: * Check the created CommandCollection
197: *
198: * @param mixed $commands The CommandCollection to check, could be anything though.
199: * @param string $method The method that was used.
200: * @return void
201: * @throws \RuntimeException
202: * @deprecated 3.6.0 This method should be replaced with return types in 4.x
203: */
204: protected function checkCollection($commands, $method)
205: {
206: if (!($commands instanceof CommandCollection)) {
207: $type = getTypeName($commands);
208: throw new RuntimeException(
209: "The application's `{$method}` method did not return a CommandCollection." .
210: " Got '{$type}' instead."
211: );
212: }
213: }
214:
215: /**
216: * Get the application's event manager or the global one.
217: *
218: * @return \Cake\Event\EventManagerInterface
219: */
220: public function getEventManager()
221: {
222: if ($this->app instanceof PluginApplicationInterface) {
223: return $this->app->getEventManager();
224: }
225:
226: return EventManager::instance();
227: }
228:
229: /**
230: * Get/set the application's event manager.
231: *
232: * If the application does not support events and this method is used as
233: * a setter, an exception will be raised.
234: *
235: * @param \Cake\Event\EventManager|null $events The event manager to set.
236: * @return \Cake\Event\EventManager|$this
237: * @deprecated 3.6.0 Will be removed in 4.0
238: */
239: public function eventManager(EventManager $events = null)
240: {
241: deprecationWarning('eventManager() is deprecated. Use getEventManager()/setEventManager() instead.');
242: if ($events === null) {
243: return $this->getEventManager();
244: }
245:
246: return $this->setEventManager($events);
247: }
248:
249: /**
250: * Get/set the application's event manager.
251: *
252: * If the application does not support events and this method is used as
253: * a setter, an exception will be raised.
254: *
255: * @param \Cake\Event\EventManager $events The event manager to set.
256: * @return $this
257: */
258: public function setEventManager(EventManager $events)
259: {
260: if ($this->app instanceof PluginApplicationInterface) {
261: $this->app->setEventManager($events);
262:
263: return $this;
264: }
265:
266: throw new InvalidArgumentException('Cannot set the event manager, the application does not support events.');
267: }
268:
269: /**
270: * Get the shell instance for a given command name
271: *
272: * @param \Cake\Console\ConsoleIo $io The IO wrapper for the created shell class.
273: * @param \Cake\Console\CommandCollection $commands The command collection to find the shell in.
274: * @param string $name The command name to find
275: * @return \Cake\Console\Shell|\Cake\Console\Command
276: */
277: protected function getShell(ConsoleIo $io, CommandCollection $commands, $name)
278: {
279: $instance = $commands->get($name);
280: if (is_string($instance)) {
281: $instance = $this->createShell($instance, $io);
282: }
283: if ($instance instanceof Shell) {
284: $instance->setRootName($this->root);
285: }
286: if ($instance instanceof Command) {
287: $instance->setName("{$this->root} {$name}");
288: }
289: if ($instance instanceof CommandCollectionAwareInterface) {
290: $instance->setCommandCollection($commands);
291: }
292:
293: return $instance;
294: }
295:
296: /**
297: * Build the longest command name that exists in the collection
298: *
299: * Build the longest command name that matches a
300: * defined command. This will traverse a maximum of 3 tokens.
301: *
302: * @param \Cake\Console\CommandCollection $commands The command collection to check.
303: * @param array $argv The CLI arguments.
304: * @return array An array of the resolved name and modified argv.
305: */
306: protected function longestCommandName($commands, $argv)
307: {
308: for ($i = 3; $i > 1; $i--) {
309: $parts = array_slice($argv, 0, $i);
310: $name = implode(' ', $parts);
311: if ($commands->has($name)) {
312: return [$name, array_slice($argv, $i)];
313: }
314: }
315: $name = array_shift($argv);
316:
317: return [$name, $argv];
318: }
319:
320: /**
321: * Resolve the command name into a name that exists in the collection.
322: *
323: * Apply backwards compatible inflections and aliases.
324: * Will step forward up to 3 tokens in $argv to generate
325: * a command name in the CommandCollection. More specific
326: * command names take precedence over less specific ones.
327: *
328: * @param \Cake\Console\CommandCollection $commands The command collection to check.
329: * @param \Cake\Console\ConsoleIo $io ConsoleIo object for errors.
330: * @param string $name The name
331: * @return string The resolved class name
332: * @throws \RuntimeException
333: */
334: protected function resolveName($commands, $io, $name)
335: {
336: if (!$name) {
337: $io->err('<error>No command provided. Choose one of the available commands.</error>', 2);
338: $name = 'help';
339: }
340: if (isset($this->aliases[$name])) {
341: $name = $this->aliases[$name];
342: }
343: if (!$commands->has($name)) {
344: $name = Inflector::underscore($name);
345: }
346: if (!$commands->has($name)) {
347: throw new RuntimeException(
348: "Unknown command `{$this->root} {$name}`." .
349: " Run `{$this->root} --help` to get the list of valid commands."
350: );
351: }
352:
353: return $name;
354: }
355:
356: /**
357: * Execute a Command class.
358: *
359: * @param \Cake\Console\Command $command The command to run.
360: * @param array $argv The CLI arguments to invoke.
361: * @param \Cake\Console\ConsoleIo $io The console io
362: * @return int Exit code
363: */
364: protected function runCommand(Command $command, array $argv, ConsoleIo $io)
365: {
366: try {
367: return $command->run($argv, $io);
368: } catch (StopException $e) {
369: return $e->getCode();
370: }
371: }
372:
373: /**
374: * Execute a Shell class.
375: *
376: * @param \Cake\Console\Shell $shell The shell to run.
377: * @param array $argv The CLI arguments to invoke.
378: * @return int Exit code
379: */
380: protected function runShell(Shell $shell, array $argv)
381: {
382: try {
383: $shell->initialize();
384:
385: return $shell->runCommand($argv, true);
386: } catch (StopException $e) {
387: return $e->getCode();
388: }
389: }
390:
391: /**
392: * The wrapper for creating shell instances.
393: *
394: * @param string $className Shell class name.
395: * @param \Cake\Console\ConsoleIo $io The IO wrapper for the created shell class.
396: * @return \Cake\Console\Shell|\Cake\Console\Command
397: */
398: protected function createShell($className, ConsoleIo $io)
399: {
400: $shell = $this->factory->create($className);
401: if ($shell instanceof Shell) {
402: $shell->setIo($io);
403: }
404:
405: return $shell;
406: }
407:
408: /**
409: * Ensure that the application's routes are loaded.
410: *
411: * Console commands and shells often need to generate URLs.
412: *
413: * @return void
414: */
415: protected function loadRoutes()
416: {
417: $builder = Router::createRouteBuilder('/');
418:
419: if ($this->app instanceof HttpApplicationInterface) {
420: $this->app->routes($builder);
421: }
422: if ($this->app instanceof PluginApplicationInterface) {
423: $this->app->pluginRoutes($builder);
424: }
425: }
426: }
427: