JuliusHaertl\PHPDocToRst\ApiDocBuilder

Complexity

Total Complexity

44

Size/Duplication

Total Lines	331
Duplicated Lines	0 %

Importance

Changes	6
Bugs	1	Features	0

16 Methods

Rating	Name	Duplication	Size	Complexity
A	__construct()	0	4	1
A	build()	0	6	1
A	parseFunctions()	0	10	4
A	log()	0	4	2
B	setupReflection()	0	48	7
A	addExtension()	0	4	1
A	parseTraits()	0	14	3
A	parseConstants()	0	10	4
A	createDirectoryStructure()	0	9	4
A	buildIndexes()	0	31	4
A	parseInterfaces()	0	14	3
A	parseFiles()	0	19	3
A	setDebugOutput()	0	3	1
A	debug()	0	4	2
A	parseClasses()	0	14	3
A	setVerboseOutput()	0	3	1

<?php
/**
 * @copyright Copyright (c) 2017 Julius Härtl <jus@bitgrid.net>
 * @author    Julius Härtl <jus@bitgrid.net>
 * @license   GNU AGPL version 3 or any later version
 *
 *  This program is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU Affero General Public License as
 *  published by the Free Software Foundation, either version 3 of the
 *  License, or (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU Affero General Public License for more details.
 *
 *  You should have received a copy of the GNU Affero General Public License
 *  along with this program. If not, see <http://www.gnu.org/licenses/>.
 */

namespace JuliusHaertl\PHPDocToRst;

use Exception;
use JuliusHaertl\PHPDocToRst\Builder\ClassFileBuilder;
use JuliusHaertl\PHPDocToRst\Builder\InterfaceFileBuilder;
use JuliusHaertl\PHPDocToRst\Builder\MainIndexBuilder;
use JuliusHaertl\PHPDocToRst\Builder\NamespaceIndexBuilder;
use JuliusHaertl\PHPDocToRst\Builder\PhpDomainBuilder;
use JuliusHaertl\PHPDocToRst\Builder\TraitFileBuilder;
use JuliusHaertl\PHPDocToRst\Extension\Extension;
use JuliusHaertl\PHPDocToRst\Middleware\ErrorHandlingMiddleware;
use phpDocumentor\Reflection\DocBlockFactory;
use phpDocumentor\Reflection\File\LocalFile;
use phpDocumentor\Reflection\Php\Factory;
use phpDocumentor\Reflection\Php\Namespace_;
use phpDocumentor\Reflection\Php\NodesFactory;
use phpDocumentor\Reflection\Php\Project;
use phpDocumentor\Reflection\Php\ProjectFactory;
use PhpParser\PrettyPrinter\Standard as PrettyPrinter;
use RecursiveDirectoryIterator;
use RecursiveIteratorIterator;

/**
 * This class is used to parse a project tree and generate rst files
 * for all of the containing PHP structures.
 *
 * Example usage is documented in examples/example.php
 */
final class ApiDocBuilder
{
    /** @var Project */
    private $project;

    /** @var array */
    private $docFiles = [];

    /** @var array */
    private $constants = [];

    /** @var array */
    private $functions = [];

    /** @var Extension[] */
    private $extensions = [];

    /** @var string[] */
    private $extensionNames = [];

    /** @var array[] */
    private $extensionArguments = [];

    /** @var string[] */
    private $srcDir = [];

    /** @var string */
    private $dstDir;

    /** @var bool */
    private $verboseOutput = false;

    /** @var bool */
    private $debugOutput = false;

    /**
     * ApiDocBuilder constructor.
     *
     * @param string[] $srcDir array of paths that should be analysed
     * @param string   $dstDir path where the output documentation should be stored
     */
    public function __construct($srcDir, $dstDir)
    {
        $this->dstDir = $dstDir;
        $this->srcDir = (array) $srcDir;
    }

    /**
     * Run this to build the documentation.
     */
    public function build()
    {
        $this->setupReflection();
        $this->createDirectoryStructure();
        $this->parseFiles();
        $this->buildIndexes();
    }

    /* hacky logging for cli */

    /**
     * @throws Exception
     */
    private function setupReflection()
    {
        $interfaceList = [];
        $this->log('Start parsing files.');
        foreach ($this->srcDir as $srcDir) {
            $dir = new RecursiveDirectoryIterator($srcDir);
            $files = new RecursiveIteratorIterator($dir);

            foreach ($files as $file) {
                if ($file->isDir()) {
                    continue;
                }

                try {
                    $interfaceList[] = new LocalFile($file->getPathname());
                } catch (Exception $e) {
                    $this->log('Failed to load '.$file->getPathname().PHP_EOL);
                }
            }
        }

        $projectFactory = new ProjectFactory([
            new Factory\Argument(new PrettyPrinter()),
            new Factory\Class_(),
            new Factory\Define(new PrettyPrinter()),
            new Factory\GlobalConstant(new PrettyPrinter()),
            new Factory\ClassConstant(new PrettyPrinter()),
            new Factory\DocBlock(DocBlockFactory::createInstance()),
            new Factory\File(NodesFactory::createInstance(), [
                new ErrorHandlingMiddleware($this),
            ]),
            new Factory\Function_(),
            new Factory\Interface_(),
            new Factory\Method(),
            new Factory\Property(new PrettyPrinter()),
            new Factory\Trait_(),
        ]);
        $this->project = $projectFactory->create('MyProject', $interfaceList);
        $this->log('Successfully parsed files.');

        // load extensions
        foreach ($this->extensionNames as $extensionName) {
            $extension = new $extensionName($this->project, $this->extensionArguments[$extensionName]);
            if (!is_subclass_of($extension, Extension::class)) {
                $this->log('Failed to load extension '.$extensionName.'.');
            }
            $this->extensions[] = $extension;
            $this->log('Extension '.$extensionName.' loaded.');
        }
    }

    /**
     * Log a message.
     *
     * @param string $message Message to be logged
     */
    public function log($message)
    {
        if ($this->verboseOutput) {
            echo $message.PHP_EOL;
        }
    }

    /**
     * Create directory structure for the rst output.
     *
     * @throws WriteException
     */
    private function createDirectoryStructure()
    {
        foreach ($this->project->getNamespaces() as $namespace) {
            $namespaceDir = $this->dstDir.str_replace('\\', '/', $namespace->getFqsen());
            if (is_dir($namespaceDir)) {
                continue;
            }
            if (!mkdir($namespaceDir, 0755, true)) {
                throw new WriteException('Could not create directory '.$namespaceDir);
            }
        }
    }

    private function parseFiles()
    {
        /** @var Extension $extension */
        foreach ($this->extensions as $extension) {
            $extension->prepare();
        }

        $this->log('Start building files');

        foreach ($this->project->getFiles() as $file) {
            /*
             * Go though interfaces/classes/functions of files and build documentation
             */

            $this->parseInterfaces($file);
            $this->parseClasses($file);
            $this->parseTraits($file);
            $this->parseFunctions($file);
            $this->parseConstants($file);
        }
    }

    /**
     * Log a debug message.
     *
     * @param string $message Message to be logged
     */
    public function debug($message)
    {
        if ($this->debugOutput) {
            echo $message.PHP_EOL;
        }
    }

    private function buildIndexes()
    {
        $this->log('Build indexes.');
        $namespaces = $this->project->getNamespaces();
        $namespaces['\\'] = $this->project->getRootNamespace();
        usort($namespaces, function (Namespace_ $a, Namespace_ $b) {
            return strcmp($a->getFqsen(), $b->getFqsen());
        });
        /** @var Namespace_ $namespace */
        foreach ($namespaces as $namespace) {
            $fqsen = (string) $namespace->getFqsen();
            $this->debug('Build namespace index for '.$fqsen);
            $functions = [];
            $constants = [];
            if (array_key_exists($fqsen, $this->functions)) {
                $functions = $this->functions[$fqsen];
            }
            if (array_key_exists($fqsen, $this->constants)) {
                $constants = $this->constants[$fqsen];
            }
            $builder = new NamespaceIndexBuilder($this->extensions, $namespaces, $namespace, $functions, $constants);
            $builder->render();
            $path = $this->dstDir.str_replace('\\', '/', $fqsen).'/index.rst';
            file_put_contents($path, $builder->getContent());
        }

        $this->log('Build main index files.');
        $builder = new MainIndexBuilder($namespaces);
        $builder->render();
        $path = $this->dstDir.'/index-namespaces-all.rst';
        file_put_contents($path, $builder->getContent());
    }

    /**
     * Enable verbose logging output.
     *
     * @param bool $v Set to true to enable
     */
    public function setVerboseOutput($v)
    {
        $this->verboseOutput = $v;
    }

    /**
     * Enable debug logging output.
     *
     * @param bool $v Set to true to enable
     */
    public function setDebugOutput($v)
    {
        $this->debugOutput = $v;
    }

    /**
     * @param string $class name of the extension class
     *
     * @throws Exception
     */
    public function addExtension($class, $arguments = [])
    {
        $this->extensionNames[] = $class;
        $this->extensionArguments[$class] = $arguments;
    }

    /**
     * @param \phpDocumentor\Reflection\Php\File $file
     */
    private function parseInterfaces(\phpDocumentor\Reflection\Php\File $file): void
    {
        foreach ($file->getInterfaces() as $interface) {
            $fqsen = $interface->getFqsen();
            $builder = new InterfaceFileBuilder($file, $interface, $this->extensions);
            $filename = $this->dstDir.str_replace('\\', '/', $fqsen).'.rst';
            file_put_contents($filename, $builder->getContent());
            $this->docFiles[(string) $interface->getFqsen()] = str_replace('\\', '/', $fqsen);

            // also build root namespace in indexes
            if (strpos((string) substr($fqsen, 1), '\\') === false) {
                $this->project->getRootNamespace()->addInterface($fqsen);
            }
            $this->debug('Written interface documentation to '.$filename);
        }
    }

    /**
     * @param \phpDocumentor\Reflection\Php\File $file
     */
    private function parseClasses(\phpDocumentor\Reflection\Php\File $file): void
    {
        foreach ($file->getClasses() as $class) {
            $fqsen = $class->getFqsen();
            $builder = new ClassFileBuilder($file, $class, $this->extensions);
            $filename = $this->dstDir.str_replace('\\', '/', $fqsen).'.rst';
            file_put_contents($filename, $builder->getContent());
            $this->docFiles[(string) $class->getFqsen()] = str_replace('\\', '/', $fqsen);

            // also build root namespace in indexes
            if (strpos((string) substr($class->getFqsen(), 1), '\\') === false) {
                $this->project->getRootNamespace()->addClass($fqsen);
            }
            $this->debug('Written class documentation to '.$filename);
        }
    }

    /**
     * @param \phpDocumentor\Reflection\Php\File $file
     */
    private function parseTraits(\phpDocumentor\Reflection\Php\File $file): void
    {
        foreach ($file->getTraits() as $trait) {
            $fqsen = $trait->getFqsen();
            $builder = new TraitFileBuilder($file, $trait, $this->extensions);
            $filename = $this->dstDir.str_replace('\\', '/', $fqsen).'.rst';
            file_put_contents($filename, $builder->getContent());
            $this->docFiles[(string) $trait->getFqsen()] = str_replace('\\', '/', $fqsen);

            // also build root namespace in indexes
            if (strpos((string) substr($fqsen, 1), '\\') === false) {
                $this->project->getRootNamespace()->addTrait($fqsen);
            }
            $this->debug('Written trait documentation to '.$filename);
        }
    }

    /**
     * @param \phpDocumentor\Reflection\Php\File $file
     */
    private function parseFunctions(\phpDocumentor\Reflection\Php\File $file): void
    {
        // build array of functions per namespace
        foreach ($file->getFunctions() as $function) {
            $namespace = substr(PhpDomainBuilder::getNamespace($function), 0, -2);
            $namespace = $namespace === '' ? '\\' : $namespace;
            if (!array_key_exists($namespace, $this->functions)) {
                $this->functions[$namespace] = [];
            }
            $this->functions[$namespace][] = $function;
        }
    }

    /**
     * @param \phpDocumentor\Reflection\Php\File $file
     */
    private function parseConstants(\phpDocumentor\Reflection\Php\File $file): void
    {
        // build array of constants per namespace
        foreach ($file->getConstants() as $constant) {
            $namespace = PhpDomainBuilder::getNamespace($constant);
            $namespace = $namespace === '' ? '\\' : $namespace;
            if (!array_key_exists($namespace, $this->constants)) {
                $this->constants[$namespace] = [];
            }
            $this->constants[$namespace][] = $constant;
        }
    }
}