yii2/extensions/apidoc/commands/ApiController.php

<?php
/**
 * @link http://www.yiiframework.com/
 * @copyright Copyright (c) 2008 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */

namespace yii\apidoc\commands;

use yii\apidoc\components\BaseController;
use yii\apidoc\models\Context;
use yii\apidoc\renderers\ApiRenderer;
use yii\apidoc\renderers\BaseRenderer;
use yii\helpers\ArrayHelper;
use yii\helpers\Console;
use yii\helpers\FileHelper;

/**
 * Generate class API documentation.
 *
 * @author Carsten Brandt <mail@cebe.cc>
 * @since 2.0
 */
class ApiController extends BaseController
{
    /**
     * @var string url to where the guide files are located
     */
    public $guide;

    // TODO add force update option

    /**
     * Renders API documentation files
     * @param array $sourceDirs
     * @param string $targetDir
     * @return int
     */
    public function actionIndex(array $sourceDirs, $targetDir)
    {
        $renderer = $this->findRenderer($this->template);
        $targetDir = $this->normalizeTargetDir($targetDir);
        if ($targetDir === false || $renderer === false) {
            return 1;
        }

        $renderer->apiUrl = './';

        // setup reference to guide
        if ($this->guide !== null) {
            $guideUrl = $this->guide;
            $referenceFile = $guideUrl . '/' . BaseRenderer::GUIDE_PREFIX . 'references.txt';
        } else {
            $guideUrl = './';
            $referenceFile = $targetDir . '/' . BaseRenderer::GUIDE_PREFIX . 'references.txt';
        }
        if (file_exists($referenceFile)) {
            $renderer->guideUrl = $guideUrl;
            $renderer->guideReferences = [];
            foreach (explode("\n", file_get_contents($referenceFile)) as $reference) {
                $renderer->guideReferences[BaseRenderer::GUIDE_PREFIX . $reference]['url'] = $renderer->generateGuideUrl($reference);
            }
        }

        // search for files to process
        if (($files = $this->searchFiles($sourceDirs)) === false) {
            return 1;
        }

        // load context from cache
        $context = $this->loadContext($targetDir);
        $this->stdout('Checking for updated files... ');
        foreach ($context->files as $file => $sha) {
            if (!file_exists($file)) {
                $this->stdout('At least one file has been removed. Rebuilding the context...');
                $context = new Context();
                if (($files = $this->searchFiles($sourceDirs)) === false) {
                    return 1;
                }
                break;
            }
            if (sha1_file($file) === $sha) {
                unset($files[$file]);
            }
        }
        $this->stdout('done.' . PHP_EOL, Console::FG_GREEN);

        // process files
        $fileCount = count($files);
        $this->stdout($fileCount . ' file' . ($fileCount == 1 ? '' : 's') . ' to update.' . PHP_EOL);
        Console::startProgress(0, $fileCount, 'Processing files... ', false);
        $done = 0;
        foreach ($files as $file) {
            $context->addFile($file);
            Console::updateProgress(++$done, $fileCount);
        }
        Console::endProgress(true);
        $this->stdout('done.' . PHP_EOL, Console::FG_GREEN);

        // save processed data to cache
        $this->storeContext($context, $targetDir);

        $this->updateContext($context);

        // render models
        $renderer->controller = $this;
        $renderer->render($context, $targetDir);

        if (!empty($context->errors)) {
            ArrayHelper::multisort($context->errors, 'file');
            file_put_contents($targetDir . '/errors.txt', print_r($context->errors, true));
            $this->stdout(count($context->errors) . " errors have been logged to $targetDir/errors.txt\n", Console::FG_RED, Console::BOLD);
        }
    }

    /**
     * @inheritdoc
     */
    protected function findFiles($path, $except = [])
    {
        if (empty($except)) {
            $except = ['vendor/', 'tests/'];
        }
        $path = FileHelper::normalizePath($path);
        $options = [
            'filter' => function ($path) {
                    if (is_file($path)) {
                        $file = basename($path);
                        if ($file[0] < 'A' || $file[0] > 'Z') {
                            return false;
                        }
                    }

                    return null;
                },
            'only' => ['*.php'],
            'except' => $except,
        ];

        return FileHelper::findFiles($path, $options);
    }

    /**
     * @inheritdoc
     * @return ApiRenderer
     */
    protected function findRenderer($template)
    {
        $rendererClass = 'yii\\apidoc\\templates\\' . $template . '\\ApiRenderer';
        if (!class_exists($rendererClass)) {
            $this->stderr('Renderer not found.' . PHP_EOL);

            return false;
        }

        return new $rendererClass();
    }

    /**
     * @inheritdoc
     */
    public function options($actionId)
    {
        return array_merge(parent::options($actionId), ['template', 'guide']);
    }
}