Class yii\apidoc\commands\ApiController

Inheritanceyii\apidoc\commands\ApiController » yii\apidoc\components\BaseController » yii\console\Controller
Available since extension's version2.0
Source Code https://github.com/yiisoft/yii2-apidoc/blob/master/commands/ApiController.php

Generate class API documentation.

Public Properties

Hide inherited properties

Property Type Description Defined By
$exclude string|array Files to exclude. yii\apidoc\components\BaseController
$guide string Url to where the guide files are located yii\apidoc\commands\ApiController
$guidePrefix string Prefix to prepend to all guide file names. yii\apidoc\commands\ApiController
$pageTitle string Page title yii\apidoc\components\BaseController
$template string Template to use for rendering yii\apidoc\components\BaseController

Public Methods

Hide inherited methods

Method Description Defined By
actionIndex() Renders API documentation files yii\apidoc\commands\ApiController
options() yii\apidoc\commands\ApiController

Property Details

Hide inherited properties

$guide public property

Url to where the guide files are located

public string $guide null
$guidePrefix public property

Prefix to prepend to all guide file names.

public string $guidePrefix 'guide-'

Method Details

Hide inherited methods

actionIndex() public method

Renders API documentation files

public integer actionIndex ( array $sourceDirs, $targetDir )
$sourceDirs array
$targetDir string
return integer

Status code.

                public function actionIndex(array $sourceDirs, $targetDir)
{
    $renderer = $this->findRenderer($this->template);
    $targetDir = $this->normalizeTargetDir($targetDir);
    if ($targetDir === false || $renderer === false) {
        return 1;
    }
    $renderer->apiUrl = './';
    $renderer->guidePrefix = $this->guidePrefix;
    if ($this->pageTitle !== null) {
        $renderer->pageTitle = $this->pageTitle;
    }
    // setup reference to guide
    if ($this->guide !== null) {
        $renderer->guideUrl = $guideUrl = $this->guide;
    } else {
        $guideUrl = './';
        $renderer->guideUrl = $targetDir;
        if (file_exists($renderer->generateGuideUrl('README.md'))) {
            $renderer->guideUrl = $guideUrl;
        } else {
            $renderer->guideUrl = null;
        }
    }
    // 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) {
        try {
            $context->addProjectFile($file);
        } catch (\Exception $e) {
            $context->errors[] = "Unable to process \"$file\": " . $e->getMessage();
        }
        Console::updateProgress(++$done, $fileCount);
    }
    Console::endProgress(true);
    $this->stdout('done.' . PHP_EOL, Console::FG_GREEN);
    $context->processFiles();
    // 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);
    }
    if (!empty($context->warnings)) {
        ArrayHelper::multisort($context->warnings, 'file');
        file_put_contents($targetDir . '/warnings.txt', print_r($context->warnings, true));
        $this->stdout(count($context->warnings) . " warnings have been logged to $targetDir/warnings.txt\n", Console::FG_YELLOW, Console::BOLD);
    }
    return 0;
}

            
findFiles() protected method

Finds files

protected array findFiles ( $path, $except = [] )
$path
$except array

List of names to exclude from search.

return array

Files found.

                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);
}

            
findRenderer() protected method

protected yii\apidoc\renderers\ApiRenderer findRenderer ( $template )
$template string

                protected function findRenderer($template)
{
    // find renderer by class name
    if (class_exists($template)) {
        return new $template();
    }
    $rendererClass = 'yii\\apidoc\\templates\\' . $template . '\\ApiRenderer';
    if (!class_exists($rendererClass)) {
        $this->stderr('Renderer not found.' . PHP_EOL);
        return false;
    }
    return new $rendererClass();
}

            
loadContext() protected method

Defined in: yii\apidoc\components\BaseController::loadContext()

Loads context from cache

protected yii\apidoc\models\Context loadContext ( $location )
$location string

                protected function loadContext($location)
{
    $context = new Context();
    $cacheFile = $location . '/cache/apidoc.data';
    $this->stdout('Loading apidoc data from cache... ');
    if (file_exists($cacheFile)) {
        $context = unserialize(file_get_contents($cacheFile));
        $this->stdout('done.' . PHP_EOL, Console::FG_GREEN);
    } else {
        $this->stdout('no data available.' . PHP_EOL, Console::FG_YELLOW);
    }
    return $context;
}

            
normalizeTargetDir() protected method

Defined in: yii\apidoc\components\BaseController::normalizeTargetDir()

Checks that target directory is valid. Asks questions in tricky cases.

protected boolean|string normalizeTargetDir ( $target )
$target string

                protected function normalizeTargetDir($target)
{
    $target = rtrim(Yii::getAlias($target), '\\/');
    if (file_exists($target)) {
        if (is_dir($target) && !$this->confirm('TargetDirectory already exists. Overwrite?', true)) {
            $this->stderr('User aborted.' . PHP_EOL);
            return false;
        }
        if (is_file($target)) {
            $this->stderr("Error: Target directory \"$target\" is a file!" . PHP_EOL);
            return false;
        }
    } else {
        mkdir($target, 0777, true);
    }
    return $target;
}

            
options() public method

public void options ( $actionID )
$actionID

                public function options($actionID)
{
    return array_merge(parent::options($actionID), ['guide', 'guidePrefix']);
}

            
searchFiles() protected method

Defined in: yii\apidoc\components\BaseController::searchFiles()

Finds files to process

protected array|boolean searchFiles ( $sourceDirs )
$sourceDirs array
return array|boolean

List of files to process or false on failure

                protected function searchFiles($sourceDirs)
{
    $this->stdout('Searching files to process... ');
    $files = [];
    if (is_array($this->exclude)) {
        $exclude = $this->exclude;
    } elseif (is_string($this->exclude)) {
        $exclude = explode(',', $this->exclude);
    } else {
        $exclude = [];
    }
    foreach ($sourceDirs as $source) {
        foreach ($this->findFiles($source, $exclude) as $fileName) {
            $files[$fileName] = $fileName;
        }
    }
    $this->stdout('done.' . PHP_EOL, Console::FG_GREEN);
    if (empty($files)) {
        $this->stderr('Error: No files found to process.' . PHP_EOL);
        return false;
    }
    return $files;
}

            
storeContext() protected method

Defined in: yii\apidoc\components\BaseController::storeContext()

Writes context into cache file

protected void storeContext ( $context, $location )
$context yii\apidoc\models\Context
$location string

                protected function storeContext($context, $location)
{
    $cacheFile = $location . '/cache/apidoc.data';
    if (!is_dir($dir = dirname($cacheFile))) {
        mkdir($dir, 0777, true);
    }
    file_put_contents($cacheFile, serialize($context));
}

            
updateContext() protected method
protected void updateContext ( $context )
$context yii\apidoc\models\Context

                protected function updateContext($context)
{
    $this->stdout('Updating cross references and backlinks... ');
    $context->updateReferences();
    $this->stdout('done.' . PHP_EOL, Console::FG_GREEN);
}