/**
* Export this tag to the given DocBlock.
*
* @param \DOMElement $parent Element to
* augment.
* @param \phpDocumentor\Reflection\DocBlock\Tag $tag The tag to
* export.
* @param \phpDocumentor\Reflection\BaseReflector $element Element to
* log from.
*
* @return void
*/
public function export(\DOMElement $parent, $tag, $element)
{
$child = new \DOMElement('tag');
$parent->appendChild($child);
$child->setAttribute('line', $parent->getAttribute('line'));
if (class_exists('phpDocumentor\\Plugin\\EventDispatcher')) {
\phpDocumentor\Plugin\EventDispatcher::getInstance()->dispatch('reflection.docblock.tag.export', \phpDocumentor\Reflection\Events\ExportDocBlockTagEvent::createInstance($element)->setObject($tag)->setXml(simplexml_import_dom($child)));
}
}
/**
* This method combines the structure.xml and the given target template
* and creates a static html page at the artifact location.
*
* @param \DOMDocument $structure XML source.
* @param \phpDocumentor\Transformer\Transformation $transformation Transformation.
*
* @throws \Exception
*
* @return void
*/
public function transform(\DOMDocument $structure, \phpDocumentor\Transformer\Transformation $transformation)
{
if (!class_exists('XSLTProcessor')) {
throw new \phpDocumentor\Plugin\Core\Exception('The XSL writer was unable to find your XSLTProcessor; ' . 'please check if you have installed the PHP XSL extension');
}
$artifact = $transformation->getTransformer()->getTarget() . DIRECTORY_SEPARATOR . $transformation->getArtifact();
$xsl = new \DOMDocument();
$xsl->load($transformation->getSourceAsPath());
$proc = new \XSLTProcessor();
$proc->importStyleSheet($xsl);
if (empty($structure->documentElement)) {
throw new \phpDocumentor\Plugin\Core\Exception('Specified DOMDocument lacks documentElement, cannot transform');
}
$proc->setParameter('', 'title', $structure->documentElement->getAttribute('title'));
$proc->setParameter('', 'root', str_repeat('../', substr_count($transformation->getArtifact(), '/')));
$proc->setParameter('', 'search_template', $transformation->getParameter('search', 'none'));
$proc->setParameter('', 'version', \phpDocumentor\Application::VERSION);
$proc->setParameter('', 'generated_datetime', date('r'));
// check parameters for variables and add them when found
$this->setProcessorParameters($transformation, $proc);
// if a query is given, then apply a transformation to the artifact
// location by replacing ($<var>} with the sluggified node-value of the
// search result
if ($transformation->getQuery() !== '') {
$xpath = new \DOMXPath($transformation->getTransformer()->getSource());
/** @var \DOMNodeList $qry */
$qry = $xpath->query($transformation->getQuery());
$count = $qry->length;
foreach ($qry as $key => $element) {
\phpDocumentor\Plugin\EventDispatcher::getInstance()->dispatch('transformer.writer.xsl.pre', \phpDocumentor\Transformer\Events\PreXslWriterEvent::createInstance($this)->setElement($element)->setProgress(array($key + 1, $count)));
$proc->setParameter('', $element->nodeName, $element->nodeValue);
$file_name = $transformation->getTransformer()->generateFilename($element->nodeValue);
$filename = str_replace('{$' . $element->nodeName . '}', $file_name, $artifact);
$this->log('Processing the file: ' . $element->nodeValue . ' as ' . $filename);
if (!file_exists(dirname($filename))) {
mkdir(dirname($filename), 0755, true);
}
$proc->transformToURI($structure, $this->getXsltUriFromFilename($filename));
}
} else {
if (substr($transformation->getArtifact(), 0, 1) == '$') {
// not a file, it must become a variable!
$variable_name = substr($transformation->getArtifact(), 1);
$this->xsl_variables[$variable_name] = $proc->transformToXml($structure);
} else {
if (!file_exists(dirname($artifact))) {
mkdir(dirname($artifact), 0755, true);
}
$proc->transformToURI($structure, $this->getXsltUriFromFilename($artifact));
}
}
}
/**
* Returns the parsed DocBlock.
*
* @return \phpDocumentor\Reflection\DocBlock|null
*/
public function getDocBlock()
{
$doc_block = null;
$comment = $this->constant->getDocComment();
if ($comment) {
try {
$doc_block = new \phpDocumentor\Reflection\DocBlock((string) $comment, $this->getNamespace(), $this->getNamespaceAliases());
$doc_block->line_number = $comment->getLine();
} catch (\Exception $e) {
$this->log($e->getMessage(), 2);
}
}
\phpDocumentor\Plugin\EventDispatcher::getInstance()->dispatch('reflection.docblock-extraction.post', \phpDocumentor\Reflection\Events\PostDocBlockExtractionEvent::createInstance($this)->setDocblock($doc_block));
return $doc_block;
}
/**
* Executes each transformation.
*
* @return void
*/
public function execute()
{
$source = $this->getSource();
if (!$source) {
throw new Exception('Unable to process transformations; the source was not set ' . 'correctly');
}
// invoke pre-transform actions (i.e. enhance source file with additional
// meta-data)
\phpDocumentor\Plugin\EventDispatcher::getInstance()->dispatch('transformer.transform.pre', \phpDocumentor\Transformer\Events\PreTransformEvent::createInstance($this)->setSource($source));
foreach ($this->getTransformations() as $transformation) {
\phpDocumentor\Plugin\EventDispatcher::getInstance()->dispatch('transformer.transformation.pre', \phpDocumentor\Transformer\Events\PreTransformationEvent::createInstance($this)->setSource($source));
$this->log('Applying transformation' . ($transformation->getQuery() ? ' query "' . $transformation->getQuery() . '"' : '') . ' using writer ' . get_class($transformation->getWriter()) . ' on ' . $transformation->getArtifact());
$transformation->execute($source);
\phpDocumentor\Plugin\EventDispatcher::getInstance()->dispatch('transformer.transformation.post', \phpDocumentor\Transformer\Events\PostTransformationEvent::createInstance($this)->setSource($source));
}
\phpDocumentor\Plugin\EventDispatcher::getInstance()->dispatch('transformer.transform.post', \phpDocumentor\Transformer\Events\PostTransformEvent::createInstance($this)->setSource($source));
}
public function beforeTraverse(array $nodes)
{
$node = null;
$key = 0;
foreach ($nodes as $k => $n) {
if (!$n instanceof \PHPParser_Node_Stmt_InlineHTML) {
$node = $n;
$key = $k;
break;
}
}
if ($node) {
$comments = (array) $node->getAttribute('comments');
// remove non-DocBlock comments
$comments = array_values(array_filter($comments, function ($comment) {
return $comment instanceof \PHPParser_Comment_Doc;
}));
if (!empty($comments)) {
$docblock = new \phpDocumentor\Reflection\DocBlock((string) $comments[0]);
// the first DocBlock in a file documents the file if
// * it precedes another DocBlock or
// * it contains a @package tag and doesn't precede a class
// declaration or
// * it precedes a non-documentable element (thus no include,
// require, class, function, define, const)
if (count($comments) > 1 || !$node instanceof \PHPParser_Node_Stmt_Class && $docblock->hasTag('package') || !$this->isNodeDocumentable($node)) {
$docblock->line_number = $comments[0]->getLine();
$this->doc_block = $docblock;
// remove the file level DocBlock from the node's comments
$comments = array_slice($comments, 1);
}
}
// always update the comments attribute so that standard comments
// do not stop DocBlock from being attached to an element
$node->setAttribute('comments', $comments);
$nodes[$key] = $node;
}
\phpDocumentor\Plugin\EventDispatcher::getInstance()->dispatch('reflection.docblock-extraction.post', \phpDocumentor\Reflection\Events\PostDocBlockExtractionEvent::createInstance($this)->setDocblock($this->doc_block));
return $nodes;
}
/**
* Dispatches a logging request to log a debug message.
*
* @param string $message The message to log.
*
* @return void
*/
public function debug($message)
{
\phpDocumentor\Plugin\EventDispatcher::getInstance()->dispatch('system.debug', \phpDocumentor\Events\DebugEvent::createInstance($this)->setMessage($message));
}
/**
* Iterates through the given files and builds the structure.xml file.
*
* @param \phpDocumentor\Fileset\Collection $files A files container
* to parse.
* @param bool $include_source whether to include
* the source in the generated output..
*
* @api
*
* @return bool|string
*/
public function parseFiles(\phpDocumentor\Fileset\Collection $files, $include_source = false)
{
$timer = microtime(true);
$this->exporter = new \phpDocumentor\Parser\Exporter\Xml\Xml($this);
$this->exporter->initialize();
$paths = $files->getFilenames();
$this->log('Starting to process ' . count($paths) . ' files');
$this->log(' Project root is: ' . $files->getProjectRoot());
$this->log(' Ignore paths are: ' . implode(', ', $files->getIgnorePatterns()->getArrayCopy()));
if (count($paths) < 1) {
throw new Exception('No files were found', Exception::NO_FILES_FOUND);
}
$file_count = count($paths);
foreach ($paths as $key => $file) {
\phpDocumentor\Plugin\EventDispatcher::getInstance()->dispatch('parser.file.pre', \phpDocumentor\Parser\Events\PreFileEvent::createInstance($this)->setFile($file));
$this->parseFile($file, $include_source);
}
$this->exporter->finalize();
$this->log('--');
$this->log('Elapsed time to parse all files: ' . round(microtime(true) - $timer, 2) . 's');
$this->log('Peak memory usage: ' . round(memory_get_peak_usage() / 1024 / 1024, 2) . 'M');
return $this->exporter->getContents();
}
/**
* Adds the event dispatcher to phpDocumentor's container.
*
* @return void
*/
protected function addEventDispatcher()
{
$this['event_dispatcher'] = $this->share(function () {
return Plugin\EventDispatcher::getInstance();
});
}