1: <?php
  2: 
  3: /*
  4:  * This file is part of the Symfony package.
  5:  *
  6:  * (c) Fabien Potencier <fabien@symfony.com>
  7:  *
  8:  * For the full copyright and license information, please view the LICENSE
  9:  * file that was distributed with this source code.
 10:  */
 11: 
 12: namespace Symfony\Component\Console\Command;
 13: 
 14: use Symfony\Component\Console\Input\InputDefinition;
 15: use Symfony\Component\Console\Input\InputOption;
 16: use Symfony\Component\Console\Input\InputArgument;
 17: use Symfony\Component\Console\Input\InputInterface;
 18: use Symfony\Component\Console\Output\OutputInterface;
 19: use Symfony\Component\Console\Application;
 20: use Symfony\Component\Console\Helper\HelperSet;
 21: 
 22: /**
 23:  * Base class for all commands.
 24:  *
 25:  * @author Fabien Potencier <fabien@symfony.com>
 26:  *
 27:  * @api
 28:  */
 29: class Command
 30: {
 31:     private $application;
 32:     private $name;
 33:     private $aliases;
 34:     private $definition;
 35:     private $help;
 36:     private $description;
 37:     private $ignoreValidationErrors;
 38:     private $applicationDefinitionMerged;
 39:     private $code;
 40:     private $synopsis;
 41:     private $helperSet;
 42: 
 43:     /**
 44:      * Constructor.
 45:      *
 46:      * @param string $name The name of the command
 47:      *
 48:      * @throws \LogicException When the command name is empty
 49:      *
 50:      * @api
 51:      */
 52:     public function __construct($name = null)
 53:     {
 54:         $this->definition = new InputDefinition();
 55:         $this->ignoreValidationErrors = false;
 56:         $this->applicationDefinitionMerged = false;
 57:         $this->aliases = array();
 58: 
 59:         if (null !== $name) {
 60:             $this->setName($name);
 61:         }
 62: 
 63:         $this->configure();
 64: 
 65:         if (!$this->name) {
 66:             throw new \LogicException('The command name cannot be empty.');
 67:         }
 68:     }
 69: 
 70:     /**
 71:      * Ignores validation errors.
 72:      *
 73:      * This is mainly useful for the help command.
 74:      */
 75:     public function ignoreValidationErrors()
 76:     {
 77:         $this->ignoreValidationErrors = true;
 78:     }
 79: 
 80:     /**
 81:      * Sets the application instance for this command.
 82:      *
 83:      * @param Application $application An Application instance
 84:      *
 85:      * @api
 86:      */
 87:     public function setApplication(Application $application = null)
 88:     {
 89:         $this->application = $application;
 90:         if ($application) {
 91:             $this->setHelperSet($application->getHelperSet());
 92:         } else {
 93:             $this->helperSet = null;
 94:         }
 95:     }
 96: 
 97:     /**
 98:      * Sets the helper set.
 99:      *
100:      * @param HelperSet $helperSet A HelperSet instance
101:      */
102:     public function setHelperSet(HelperSet $helperSet)
103:     {
104:         $this->helperSet = $helperSet;
105:     }
106: 
107:     /**
108:      * Gets the helper set.
109:      *
110:      * @return HelperSet A HelperSet instance
111:      */
112:     public function getHelperSet()
113:     {
114:         return $this->helperSet;
115:     }
116: 
117:     /**
118:      * Gets the application instance for this command.
119:      *
120:      * @return Application An Application instance
121:      *
122:      * @api
123:      */
124:     public function getApplication()
125:     {
126:         return $this->application;
127:     }
128: 
129:     /**
130:      * Checks whether the command is enabled or not in the current environment
131:      *
132:      * Override this to check for x or y and return false if the command can not
133:      * run properly under the current conditions.
134:      *
135:      * @return Boolean
136:      */
137:     public function isEnabled()
138:     {
139:         return true;
140:     }
141: 
142:     /**
143:      * Configures the current command.
144:      */
145:     protected function configure()
146:     {
147:     }
148: 
149:     /**
150:      * Executes the current command.
151:      *
152:      * This method is not abstract because you can use this class
153:      * as a concrete class. In this case, instead of defining the
154:      * execute() method, you set the code to execute by passing
155:      * a Closure to the setCode() method.
156:      *
157:      * @param InputInterface  $input  An InputInterface instance
158:      * @param OutputInterface $output An OutputInterface instance
159:      *
160:      * @return integer 0 if everything went fine, or an error code
161:      *
162:      * @throws \LogicException When this abstract method is not implemented
163:      * @see    setCode()
164:      */
165:     protected function execute(InputInterface $input, OutputInterface $output)
166:     {
167:         throw new \LogicException('You must override the execute() method in the concrete command class.');
168:     }
169: 
170:     /**
171:      * Interacts with the user.
172:      *
173:      * @param InputInterface  $input  An InputInterface instance
174:      * @param OutputInterface $output An OutputInterface instance
175:      */
176:     protected function interact(InputInterface $input, OutputInterface $output)
177:     {
178:     }
179: 
180:     /**
181:      * Initializes the command just after the input has been validated.
182:      *
183:      * This is mainly useful when a lot of commands extends one main command
184:      * where some things need to be initialized based on the input arguments and options.
185:      *
186:      * @param InputInterface  $input  An InputInterface instance
187:      * @param OutputInterface $output An OutputInterface instance
188:      */
189:     protected function initialize(InputInterface $input, OutputInterface $output)
190:     {
191:     }
192: 
193:     /**
194:      * Runs the command.
195:      *
196:      * The code to execute is either defined directly with the
197:      * setCode() method or by overriding the execute() method
198:      * in a sub-class.
199:      *
200:      * @param InputInterface  $input  An InputInterface instance
201:      * @param OutputInterface $output An OutputInterface instance
202:      *
203:      * @see setCode()
204:      * @see execute()
205:      *
206:      * @api
207:      */
208:     public function run(InputInterface $input, OutputInterface $output)
209:     {
210:         // force the creation of the synopsis before the merge with the app definition
211:         $this->getSynopsis();
212: 
213:         // add the application arguments and options
214:         $this->mergeApplicationDefinition();
215: 
216:         // bind the input against the command specific arguments/options
217:         try {
218:             $input->bind($this->definition);
219:         } catch (\Exception $e) {
220:             if (!$this->ignoreValidationErrors) {
221:                 throw $e;
222:             }
223:         }
224: 
225:         $this->initialize($input, $output);
226: 
227:         if ($input->isInteractive()) {
228:             $this->interact($input, $output);
229:         }
230: 
231:         $input->validate();
232: 
233:         if ($this->code) {
234:             return call_user_func($this->code, $input, $output);
235:         }
236: 
237:         return $this->execute($input, $output);
238:     }
239: 
240:     /**
241:      * Sets the code to execute when running this command.
242:      *
243:      * If this method is used, it overrides the code defined
244:      * in the execute() method.
245:      *
246:      * @param \Closure $code A \Closure
247:      *
248:      * @return Command The current instance
249:      *
250:      * @see execute()
251:      *
252:      * @api
253:      */
254:     public function setCode(\Closure $code)
255:     {
256:         $this->code = $code;
257: 
258:         return $this;
259:     }
260: 
261:     /**
262:      * Merges the application definition with the command definition.
263:      */
264:     private function mergeApplicationDefinition()
265:     {
266:         if (null === $this->application || true === $this->applicationDefinitionMerged) {
267:             return;
268:         }
269: 
270:         $currentArguments = $this->definition->getArguments();
271:         $this->definition->setArguments($this->application->getDefinition()->getArguments());
272:         $this->definition->addArguments($currentArguments);
273: 
274:         $this->definition->addOptions($this->application->getDefinition()->getOptions());
275: 
276:         $this->applicationDefinitionMerged = true;
277:     }
278: 
279:     /**
280:      * Sets an array of argument and option instances.
281:      *
282:      * @param array|InputDefinition $definition An array of argument and option instances or a definition instance
283:      *
284:      * @return Command The current instance
285:      *
286:      * @api
287:      */
288:     public function setDefinition($definition)
289:     {
290:         if ($definition instanceof InputDefinition) {
291:             $this->definition = $definition;
292:         } else {
293:             $this->definition->setDefinition($definition);
294:         }
295: 
296:         $this->applicationDefinitionMerged = false;
297: 
298:         return $this;
299:     }
300: 
301:     /**
302:      * Gets the InputDefinition attached to this Command.
303:      *
304:      * @return InputDefinition An InputDefinition instance
305:      *
306:      * @api
307:      */
308:     public function getDefinition()
309:     {
310:         return $this->definition;
311:     }
312: 
313:     /**
314:      * Gets the InputDefinition to be used to create XML and Text representations of this Command.
315:      *
316:      * Can be overridden to provide the original command representation when it would otherwise
317:      * be changed by merging with the application InputDefinition.
318:      *
319:      * @return InputDefinition An InputDefinition instance
320:      */
321:     protected function getNativeDefinition()
322:     {
323:         return $this->getDefinition();
324:     }
325: 
326:     /**
327:      * Adds an argument.
328:      *
329:      * @param string  $name        The argument name
330:      * @param integer $mode        The argument mode: InputArgument::REQUIRED or InputArgument::OPTIONAL
331:      * @param string  $description A description text
332:      * @param mixed   $default     The default value (for InputArgument::OPTIONAL mode only)
333:      *
334:      * @return Command The current instance
335:      *
336:      * @api
337:      */
338:     public function addArgument($name, $mode = null, $description = '', $default = null)
339:     {
340:         $this->definition->addArgument(new InputArgument($name, $mode, $description, $default));
341: 
342:         return $this;
343:     }
344: 
345:     /**
346:      * Adds an option.
347:      *
348:      * @param string  $name        The option name
349:      * @param string  $shortcut    The shortcut (can be null)
350:      * @param integer $mode        The option mode: One of the InputOption::VALUE_* constants
351:      * @param string  $description A description text
352:      * @param mixed   $default     The default value (must be null for InputOption::VALUE_REQUIRED or InputOption::VALUE_NONE)
353:      *
354:      * @return Command The current instance
355:      *
356:      * @api
357:      */
358:     public function addOption($name, $shortcut = null, $mode = null, $description = '', $default = null)
359:     {
360:         $this->definition->addOption(new InputOption($name, $shortcut, $mode, $description, $default));
361: 
362:         return $this;
363:     }
364: 
365:     /**
366:      * Sets the name of the command.
367:      *
368:      * This method can set both the namespace and the name if
369:      * you separate them by a colon (:)
370:      *
371:      *     $command->setName('foo:bar');
372:      *
373:      * @param string $name The command name
374:      *
375:      * @return Command The current instance
376:      *
377:      * @throws \InvalidArgumentException When command name given is empty
378:      *
379:      * @api
380:      */
381:     public function setName($name)
382:     {
383:         $this->validateName($name);
384: 
385:         $this->name = $name;
386: 
387:         return $this;
388:     }
389: 
390:     /**
391:      * Returns the command name.
392:      *
393:      * @return string The command name
394:      *
395:      * @api
396:      */
397:     public function getName()
398:     {
399:         return $this->name;
400:     }
401: 
402:     /**
403:      * Sets the description for the command.
404:      *
405:      * @param string $description The description for the command
406:      *
407:      * @return Command The current instance
408:      *
409:      * @api
410:      */
411:     public function setDescription($description)
412:     {
413:         $this->description = $description;
414: 
415:         return $this;
416:     }
417: 
418:     /**
419:      * Returns the description for the command.
420:      *
421:      * @return string The description for the command
422:      *
423:      * @api
424:      */
425:     public function getDescription()
426:     {
427:         return $this->description;
428:     }
429: 
430:     /**
431:      * Sets the help for the command.
432:      *
433:      * @param string $help The help for the command
434:      *
435:      * @return Command The current instance
436:      *
437:      * @api
438:      */
439:     public function setHelp($help)
440:     {
441:         $this->help = $help;
442: 
443:         return $this;
444:     }
445: 
446:     /**
447:      * Returns the help for the command.
448:      *
449:      * @return string The help for the command
450:      *
451:      * @api
452:      */
453:     public function getHelp()
454:     {
455:         return $this->help;
456:     }
457: 
458:     /**
459:      * Returns the processed help for the command replacing the %command.name% and
460:      * %command.full_name% patterns with the real values dynamically.
461:      *
462:      * @return string  The processed help for the command
463:      */
464:     public function getProcessedHelp()
465:     {
466:         $name = $this->name;
467: 
468:         $placeholders = array(
469:             '%command.name%',
470:             '%command.full_name%'
471:         );
472:         $replacements = array(
473:             $name,
474:             $_SERVER['PHP_SELF'].' '.$name
475:         );
476: 
477:         return str_replace($placeholders, $replacements, $this->getHelp());
478:     }
479: 
480:     /**
481:      * Sets the aliases for the command.
482:      *
483:      * @param array $aliases An array of aliases for the command
484:      *
485:      * @return Command The current instance
486:      *
487:      * @api
488:      */
489:     public function setAliases($aliases)
490:     {
491:         foreach ($aliases as $alias) {
492:             $this->validateName($alias);
493:         }
494: 
495:         $this->aliases = $aliases;
496: 
497:         return $this;
498:     }
499: 
500:     /**
501:      * Returns the aliases for the command.
502:      *
503:      * @return array An array of aliases for the command
504:      *
505:      * @api
506:      */
507:     public function getAliases()
508:     {
509:         return $this->aliases;
510:     }
511: 
512:     /**
513:      * Returns the synopsis for the command.
514:      *
515:      * @return string The synopsis
516:      */
517:     public function getSynopsis()
518:     {
519:         if (null === $this->synopsis) {
520:             $this->synopsis = trim(sprintf('%s %s', $this->name, $this->definition->getSynopsis()));
521:         }
522: 
523:         return $this->synopsis;
524:     }
525: 
526:     /**
527:      * Gets a helper instance by name.
528:      *
529:      * @param string $name The helper name
530:      *
531:      * @return mixed The helper value
532:      *
533:      * @throws \InvalidArgumentException if the helper is not defined
534:      *
535:      * @api
536:      */
537:     public function getHelper($name)
538:     {
539:         return $this->helperSet->get($name);
540:     }
541: 
542:     /**
543:      * Returns a text representation of the command.
544:      *
545:      * @return string A string representing the command
546:      */
547:     public function asText()
548:     {
549:         $messages = array(
550:             '<comment>Usage:</comment>',
551:             ' '.$this->getSynopsis(),
552:             '',
553:         );
554: 
555:         if ($this->getAliases()) {
556:             $messages[] = '<comment>Aliases:</comment> <info>'.implode(', ', $this->getAliases()).'</info>';
557:         }
558: 
559:         $messages[] = $this->getNativeDefinition()->asText();
560: 
561:         if ($help = $this->getProcessedHelp()) {
562:             $messages[] = '<comment>Help:</comment>';
563:             $messages[] = ' '.str_replace("\n", "\n ", $help)."\n";
564:         }
565: 
566:         return implode("\n", $messages);
567:     }
568: 
569:     /**
570:      * Returns an XML representation of the command.
571:      *
572:      * @param Boolean $asDom Whether to return a DOM or an XML string
573:      *
574:      * @return string|DOMDocument An XML string representing the command
575:      */
576:     public function asXml($asDom = false)
577:     {
578:         $dom = new \DOMDocument('1.0', 'UTF-8');
579:         $dom->formatOutput = true;
580:         $dom->appendChild($commandXML = $dom->createElement('command'));
581:         $commandXML->setAttribute('id', $this->name);
582:         $commandXML->setAttribute('name', $this->name);
583: 
584:         $commandXML->appendChild($usageXML = $dom->createElement('usage'));
585:         $usageXML->appendChild($dom->createTextNode(sprintf($this->getSynopsis(), '')));
586: 
587:         $commandXML->appendChild($descriptionXML = $dom->createElement('description'));
588:         $descriptionXML->appendChild($dom->createTextNode(str_replace("\n", "\n ", $this->getDescription())));
589: 
590:         $commandXML->appendChild($helpXML = $dom->createElement('help'));
591:         $helpXML->appendChild($dom->createTextNode(str_replace("\n", "\n ", $this->getProcessedHelp())));
592: 
593:         $commandXML->appendChild($aliasesXML = $dom->createElement('aliases'));
594:         foreach ($this->getAliases() as $alias) {
595:             $aliasesXML->appendChild($aliasXML = $dom->createElement('alias'));
596:             $aliasXML->appendChild($dom->createTextNode($alias));
597:         }
598: 
599:         $definition = $this->getNativeDefinition()->asXml(true);
600:         $commandXML->appendChild($dom->importNode($definition->getElementsByTagName('arguments')->item(0), true));
601:         $commandXML->appendChild($dom->importNode($definition->getElementsByTagName('options')->item(0), true));
602: 
603:         return $asDom ? $dom : $dom->saveXml();
604:     }
605: 
606:     private function validateName($name)
607:     {
608:         if (!preg_match('/^[^\:]+(\:[^\:]+)*$/', $name)) {
609:             throw new \InvalidArgumentException(sprintf('Command name "%s" is invalid.', $name));
610:         }
611:     }
612: }
613: