config = $config; } /** * {@inheritdoc} */ protected function configure(): void { $this ->setName('doc') ->setAliases(['rtfm', 'man']) ->setDefinition([ new InputOption('all', 'a', InputOption::VALUE_NONE, 'Show documentation for superclasses as well as the current class.'), new InputOption('update-manual', null, InputOption::VALUE_OPTIONAL, 'Download and install the latest PHP manual (optional language code)', false), new CodeArgument('target', CodeArgument::OPTIONAL, 'Function, class, instance, constant, method or property to document.'), ]) ->setDescription('Read the documentation for an object, class, constant, method or property.') ->setHelp( <<>>> doc preg_replace >>> doc Psy\Shell >>> doc Psy\Shell::debug >>> \$s = new Psy\Shell >>> doc \$s->run >>> doc --update-manual >>> doc --update-manual=fr HELP ); } /** * {@inheritdoc} * * @return int 0 if everything went fine, or an exit code */ protected function execute(InputInterface $input, OutputInterface $output): int { $shellOutput = $this->shellOutput($output); if ($input->getOption('update-manual') !== false) { return $this->handleUpdateManual($input, $output); } $value = $input->getArgument('target'); if (!$value) { throw new RuntimeException('Not enough arguments (missing: "target").'); } if (ReflectionLanguageConstruct::isLanguageConstruct($value)) { $reflector = new ReflectionLanguageConstruct($value); $doc = $this->getManualDocById($value); } else { list($target, $reflector) = $this->getTargetAndReflector($value, $output); $doc = $this->getManualDoc($reflector) ?: DocblockFormatter::format($reflector); } $hasManual = $this->getShell()->getManual() !== null; $shellOutput->startPaging(); // Maybe include the declaring class if ($reflector instanceof \ReflectionMethod || $reflector instanceof \ReflectionProperty) { $output->writeln(SignatureFormatter::format($reflector->getDeclaringClass())); } $output->writeln(SignatureFormatter::format($reflector)); $output->writeln(''); if (empty($doc) && !$hasManual) { $output->writeln('PHP manual not found'); $output->writeln(' To document core PHP functionality, download the PHP reference manual:'); $output->writeln(' https://github.com/bobthecow/psysh/wiki/PHP-manual'); } elseif ($doc !== null) { $output->writeln($doc); } // Implicit --all if the original docblock has an {@inheritdoc} tag. if ($input->getOption('all') || ($doc && \stripos($doc, self::INHERIT_DOC_TAG) !== false)) { $parent = $reflector; foreach ($this->getParentReflectors($reflector) as $parent) { $output->writeln(''); $output->writeln('---'); $output->writeln(''); // Maybe include the declaring class if ($parent instanceof \ReflectionMethod || $parent instanceof \ReflectionProperty) { $output->writeln(SignatureFormatter::format($parent->getDeclaringClass())); } $output->writeln(SignatureFormatter::format($parent)); $output->writeln(''); if ($doc = $this->getManualDoc($parent) ?: DocblockFormatter::format($parent)) { $output->writeln($doc); } } } $shellOutput->stopPaging(); // Set some magic local variables $this->setCommandScopeVariables($reflector); return 0; } /** * Handle the manual update operation. * * @param InputInterface $input * @param OutputInterface $output * * @return int 0 if everything went fine, or an exit code */ private function handleUpdateManual(InputInterface $input, OutputInterface $output): int { if (!$this->config) { $output->writeln('Configuration not available for manual updates.'); return 1; } // Create a synthetic input with the update-manual option $definition = new InputDefinition([ new InputOption('update-manual', null, InputOption::VALUE_OPTIONAL, '', false), ]); // Get the language value: if true (no value), use null to preserve current language $lang = $input->getOption('update-manual'); $updateValue = ($lang === true) ? null : $lang; $updateInput = new ArrayInput(['--update-manual' => $updateValue], $definition); $updateInput->setInteractive($input->isInteractive()); try { $manualUpdate = ManualUpdate::fromConfig($this->config, $updateInput, $output); $result = $manualUpdate->run($updateInput, $output); if ($result === 0) { $output->writeln(''); $output->writeln('Restart PsySH to use the updated manual.'); } return $result; } catch (\RuntimeException $e) { $output->writeln(\sprintf('%s', $e->getMessage())); return 1; } } private function getManualDoc($reflector) { switch (\get_class($reflector)) { case \ReflectionClass::class: case \ReflectionObject::class: case \ReflectionFunction::class: $id = $reflector->name; break; case \ReflectionMethod::class: $id = $reflector->class.'::'.$reflector->name; break; case \ReflectionProperty::class: $id = $reflector->class.'::$'.$reflector->name; break; case \ReflectionClassConstant::class: // @todo this is going to collide with ReflectionMethod ids // someday... start running the query by id + type if the DB // supports it. $id = $reflector->class.'::'.$reflector->name; break; case ReflectionConstant::class: $id = $reflector->name; break; default: return false; } return $this->getManualDocById($id); } /** * Get all all parent Reflectors for a given Reflector. * * For example, passing a Class, Object or TraitReflector will yield all * traits and parent classes. Passing a Method or PropertyReflector will * yield Reflectors for the same-named method or property on all traits and * parent classes. * * @return \Generator a whole bunch of \Reflector instances */ private function getParentReflectors($reflector): \Generator { $seenClasses = []; switch (\get_class($reflector)) { case \ReflectionClass::class: case \ReflectionObject::class: foreach ($reflector->getTraits() as $trait) { if (!\in_array($trait->getName(), $seenClasses)) { $seenClasses[] = $trait->getName(); yield $trait; } } foreach ($reflector->getInterfaces() as $interface) { if (!\in_array($interface->getName(), $seenClasses)) { $seenClasses[] = $interface->getName(); yield $interface; } } while ($reflector = $reflector->getParentClass()) { yield $reflector; foreach ($reflector->getTraits() as $trait) { if (!\in_array($trait->getName(), $seenClasses)) { $seenClasses[] = $trait->getName(); yield $trait; } } foreach ($reflector->getInterfaces() as $interface) { if (!\in_array($interface->getName(), $seenClasses)) { $seenClasses[] = $interface->getName(); yield $interface; } } } return; case \ReflectionMethod::class: foreach ($this->getParentReflectors($reflector->getDeclaringClass()) as $parent) { if ($parent->hasMethod($reflector->getName())) { $parentMethod = $parent->getMethod($reflector->getName()); if (!\in_array($parentMethod->getDeclaringClass()->getName(), $seenClasses)) { $seenClasses[] = $parentMethod->getDeclaringClass()->getName(); yield $parentMethod; } } } return; case \ReflectionProperty::class: foreach ($this->getParentReflectors($reflector->getDeclaringClass()) as $parent) { if ($parent->hasProperty($reflector->getName())) { $parentProperty = $parent->getProperty($reflector->getName()); if (!\in_array($parentProperty->getDeclaringClass()->getName(), $seenClasses)) { $seenClasses[] = $parentProperty->getDeclaringClass()->getName(); yield $parentProperty; } } } break; } } private function getManualDocById($id) { if ($manual = $this->getShell()->getManual()) { switch ($manual->getVersion()) { case 2: // v2 manual docs are pre-formatted and should be rendered as-is return $manual->get($id); case 3: if ($doc = $manual->get($id)) { $width = Tty::getWidth(); $formatter = new ManualFormatter($width, $manual); return $formatter->format($doc); } break; } } return null; } }