Class yii\apidoc\commands\ApiController
Inheritance | yii\apidoc\commands\ApiController » yii\apidoc\components\BaseController » yii\console\Controller |
---|---|
Available since extension's version | 2.0 |
Source Code | https://github.com/yiisoft/yii2-apidoc/blob/master/commands/ApiController.php |
Generate class API documentation.
Public 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
Method | Description | Defined By |
---|---|---|
actionIndex() | Renders API documentation files | yii\apidoc\commands\ApiController |
options() | yii\apidoc\commands\ApiController |
Protected Methods
Method | Description | Defined By |
---|---|---|
findFiles() | Finds files | yii\apidoc\commands\ApiController |
findRenderer() | yii\apidoc\commands\ApiController | |
loadContext() | Loads context from cache | yii\apidoc\components\BaseController |
normalizeTargetDir() | Checks that target directory is valid. Asks questions in tricky cases. | yii\apidoc\components\BaseController |
searchFiles() | Finds files to process | yii\apidoc\components\BaseController |
storeContext() | Writes context into cache file | yii\apidoc\components\BaseController |
updateContext() | yii\apidoc\components\BaseController |
Property Details
Prefix to prepend to all guide file names.
Method Details
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->addFile($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);
// 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;
}
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);
}
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();
}
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;
}
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;
}
public void options ( $actionID ) | ||
$actionID |
public function options($actionID)
{
return array_merge(parent::options($actionID), ['guide', 'guidePrefix']);
}
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;
}
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));
}
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);
}