Chris@13: <?php
Chris@13: 
Chris@13: /*
Chris@13:  * This file is part of Psy Shell.
Chris@13:  *
Chris@13:  * (c) 2012-2018 Justin Hileman
Chris@13:  *
Chris@13:  * For the full copyright and license information, please view the LICENSE
Chris@13:  * file that was distributed with this source code.
Chris@13:  */
Chris@13: 
Chris@13: namespace Psy\Command;
Chris@13: 
Chris@13: use Psy\Formatter\DocblockFormatter;
Chris@13: use Psy\Formatter\SignatureFormatter;
Chris@13: use Psy\Input\CodeArgument;
Chris@13: use Psy\Reflection\ReflectionLanguageConstruct;
Chris@13: use Symfony\Component\Console\Input\InputInterface;
Chris@13: use Symfony\Component\Console\Output\OutputInterface;
Chris@13: 
Chris@13: /**
Chris@13:  * Read the documentation for an object, class, constant, method or property.
Chris@13:  */
Chris@13: class DocCommand extends ReflectingCommand
Chris@13: {
Chris@13:     /**
Chris@13:      * {@inheritdoc}
Chris@13:      */
Chris@13:     protected function configure()
Chris@13:     {
Chris@13:         $this
Chris@13:             ->setName('doc')
Chris@13:             ->setAliases(['rtfm', 'man'])
Chris@13:             ->setDefinition([
Chris@13:                 new CodeArgument('target', CodeArgument::REQUIRED, 'Function, class, instance, constant, method or property to document.'),
Chris@13:             ])
Chris@13:             ->setDescription('Read the documentation for an object, class, constant, method or property.')
Chris@13:             ->setHelp(
Chris@13:                 <<<HELP
Chris@13: Read the documentation for an object, class, constant, method or property.
Chris@13: 
Chris@13: It's awesome for well-documented code, not quite as awesome for poorly documented code.
Chris@13: 
Chris@13: e.g.
Chris@13: <return>>>> doc preg_replace</return>
Chris@13: <return>>>> doc Psy\Shell</return>
Chris@13: <return>>>> doc Psy\Shell::debug</return>
Chris@13: <return>>>> \$s = new Psy\Shell</return>
Chris@13: <return>>>> doc \$s->run</return>
Chris@13: HELP
Chris@13:             );
Chris@13:     }
Chris@13: 
Chris@13:     /**
Chris@13:      * {@inheritdoc}
Chris@13:      */
Chris@13:     protected function execute(InputInterface $input, OutputInterface $output)
Chris@13:     {
Chris@13:         $value = $input->getArgument('target');
Chris@13:         if (ReflectionLanguageConstruct::isLanguageConstruct($value)) {
Chris@13:             $reflector = new ReflectionLanguageConstruct($value);
Chris@13:             $doc = $this->getManualDocById($value);
Chris@13:         } else {
Chris@13:             list($target, $reflector) = $this->getTargetAndReflector($value);
Chris@13:             $doc = $this->getManualDoc($reflector) ?: DocblockFormatter::format($reflector);
Chris@13:         }
Chris@13: 
Chris@13:         $db = $this->getApplication()->getManualDb();
Chris@13: 
Chris@13:         $output->page(function ($output) use ($reflector, $doc, $db) {
Chris@13:             $output->writeln(SignatureFormatter::format($reflector));
Chris@13:             $output->writeln('');
Chris@13: 
Chris@13:             if (empty($doc) && !$db) {
Chris@13:                 $output->writeln('<warning>PHP manual not found</warning>');
Chris@13:                 $output->writeln('    To document core PHP functionality, download the PHP reference manual:');
Chris@13:                 $output->writeln('    https://github.com/bobthecow/psysh/wiki/PHP-manual');
Chris@13:             } else {
Chris@13:                 $output->writeln($doc);
Chris@13:             }
Chris@13:         });
Chris@13: 
Chris@13:         // Set some magic local variables
Chris@13:         $this->setCommandScopeVariables($reflector);
Chris@13:     }
Chris@13: 
Chris@13:     private function getManualDoc($reflector)
Chris@13:     {
Chris@17:         switch (\get_class($reflector)) {
Chris@13:             case 'ReflectionClass':
Chris@13:             case 'ReflectionObject':
Chris@13:             case 'ReflectionFunction':
Chris@13:                 $id = $reflector->name;
Chris@13:                 break;
Chris@13: 
Chris@13:             case 'ReflectionMethod':
Chris@13:                 $id = $reflector->class . '::' . $reflector->name;
Chris@13:                 break;
Chris@13: 
Chris@13:             case 'ReflectionProperty':
Chris@13:                 $id = $reflector->class . '::$' . $reflector->name;
Chris@13:                 break;
Chris@13: 
Chris@16:             case 'ReflectionClassConstant':
Chris@16:             case 'Psy\Reflection\ReflectionClassConstant':
Chris@16:                 // @todo this is going to collide with ReflectionMethod ids
Chris@16:                 // someday... start running the query by id + type if the DB
Chris@16:                 // supports it.
Chris@16:                 $id = $reflector->class . '::' . $reflector->name;
Chris@16:                 break;
Chris@16: 
Chris@16:             case 'Psy\Reflection\ReflectionConstant_':
Chris@16:                 $id = $reflector->name;
Chris@16:                 break;
Chris@16: 
Chris@13:             default:
Chris@13:                 return false;
Chris@13:         }
Chris@13: 
Chris@13:         return $this->getManualDocById($id);
Chris@13:     }
Chris@13: 
Chris@13:     private function getManualDocById($id)
Chris@13:     {
Chris@13:         if ($db = $this->getApplication()->getManualDb()) {
Chris@13:             return $db
Chris@17:                 ->query(\sprintf('SELECT doc FROM php_manual WHERE id = %s', $db->quote($id)))
Chris@13:                 ->fetchColumn(0);
Chris@13:         }
Chris@13:     }
Chris@13: }