Class yii\apidoc\templates\bootstrap\ApiRenderer
Inheritance | yii\apidoc\templates\bootstrap\ApiRenderer » yii\apidoc\templates\html\ApiRenderer » yii\apidoc\renderers\ApiRenderer » yii\apidoc\renderers\BaseRenderer » yii\base\Component |
---|---|
Implements | yii\base\ViewContextInterface |
Uses Traits | yii\apidoc\templates\bootstrap\RendererTrait |
Available since extension's version | 2.0 |
Source Code | https://github.com/yiisoft/yii2-apidoc/blob/master/templates/bootstrap/ApiRenderer.php |
Public Properties
Property | Type | Description | Defined By |
---|---|---|---|
$apiContext | yii\apidoc\models\Context | The yii\apidoc\models\Context currently being rendered. | yii\apidoc\renderers\BaseRenderer |
$apiUrl | yii\apidoc\renderers\BaseRenderer | ||
$controller | \yii\console\Controller | The apidoc controller instance. | yii\apidoc\renderers\BaseRenderer |
$extensions | array | Official Yii extensions | yii\apidoc\templates\bootstrap\RendererTrait |
$guidePrefix | yii\apidoc\renderers\BaseRenderer | ||
$guideUrl | yii\apidoc\renderers\BaseRenderer | ||
$indexView | yii\apidoc\templates\bootstrap\ApiRenderer | ||
$layout | yii\apidoc\templates\bootstrap\ApiRenderer | ||
$pageTitle | string | String to use as the title of the generated page. | yii\apidoc\renderers\BaseRenderer |
$typeView | string | Path or alias of the view file to use for rendering types (classes, interfaces, traits). | yii\apidoc\templates\html\ApiRenderer |
$view | \yii\web\View | The view instance. | yii\apidoc\templates\html\ApiRenderer |
Public Methods
Protected Methods
Method | Description | Defined By |
---|---|---|
filterTypes() | Returns types of a given class | yii\apidoc\templates\bootstrap\RendererTrait |
generateFileName() | Generates file name for API page for a given type | yii\apidoc\templates\html\ApiRenderer |
generateLink() | Generate link markup | yii\apidoc\templates\html\ApiRenderer |
getTypeCategory() | Returns category of TypeDoc | yii\apidoc\templates\bootstrap\RendererTrait |
renderWithLayout() | Renders file applying layout | yii\apidoc\templates\html\ApiRenderer |
Constants
Constant | Value | Description | Defined By |
---|---|---|---|
GUIDE_PREFIX | 'guide-' | Deprecated since 2.0.1 use $guidePrefix instead which allows configuring this options | yii\apidoc\renderers\BaseRenderer |
Property Details
Method Details
Defined in: yii\apidoc\renderers\BaseRenderer::createSubjectLink()
Creates a link to a subject
public string createSubjectLink ( $subject, $title = null, $options = [] ) | ||
$subject | yii\apidoc\models\PropertyDoc|yii\apidoc\models\MethodDoc|yii\apidoc\models\ConstDoc|yii\apidoc\models\EventDoc | |
$title | string | |
$options | array |
Additional HTML attributes for the link. |
public function createSubjectLink($subject, $title = null, $options = [])
{
if ($title === null) {
if ($subject instanceof MethodDoc) {
$title = $subject->name . '()';
} else {
$title = $subject->name;
}
}
if (($type = $this->apiContext->getType($subject->definedBy)) === null) {
return $subject->name;
} else {
$link = $this->generateApiUrl($type->name);
if ($subject instanceof MethodDoc) {
$link .= '#' . $subject->name . '()';
} else {
$link .= '#' . $subject->name;
}
$link .= '-detail';
return $this->generateLink($title, $link, $options);
}
}
Defined in: yii\apidoc\renderers\BaseRenderer::createTypeLink()
Creates a link to a type (class, interface or trait)
public string createTypeLink ( $types, $context = null, $title = null, $options = [] ) | ||
$types | yii\apidoc\models\ClassDoc|yii\apidoc\models\InterfaceDoc|yii\apidoc\models\TraitDoc|yii\apidoc\models\ClassDoc[]|yii\apidoc\models\InterfaceDoc[]|yii\apidoc\models\TraitDoc[]|string|string[] | |
$context | yii\apidoc\models\BaseDoc | |
$title | string |
A title to be used for the link TODO check whether [[yii...|Class]] is supported |
$options | array |
Additional HTML attributes for the link. |
public function createTypeLink($types, $context = null, $title = null, $options = [])
{
if (!is_array($types)) {
$types = [$types];
}
if (count($types) > 1) {
$title = null;
}
$links = [];
foreach ($types as $type) {
$postfix = '';
if (is_string($type)) {
if (!empty($type) && substr_compare($type, '[]', -2, 2) === 0) {
$postfix = '[]';
$type = substr($type, 0, -2);
}
if ($type === '$this' && $context instanceof TypeDoc) {
$title = '$this';
$type = $context;
} elseif (($t = $this->apiContext->getType(ltrim($type, '\\'))) !== null) {
$type = $t;
} elseif (!empty($type) && $type[0] !== '\\' && ($t = $this->apiContext->getType($this->resolveNamespace($context) . '\\' . ltrim($type, '\\'))) !== null) {
$type = $t;
} else {
ltrim($type, '\\');
}
}
if (is_string($type)) {
$linkText = ltrim($type, '\\');
if ($title !== null) {
$linkText = $title;
$title = null;
}
$phpTypes = [
'callable',
'array',
'string',
'boolean',
'bool',
'integer',
'int',
'float',
'object',
'resource',
'null',
'false',
'true',
];
$phpTypeAliases = [
'true' => 'boolean',
'false' => 'boolean',
'bool' => 'boolean',
'int' => 'integer',
];
$phpTypeDisplayAliases = [
'bool' => 'boolean',
'int' => 'integer',
];
// check if it is PHP internal class
if (((class_exists($type, false) || interface_exists($type, false) || trait_exists($type, false)) &&
($reflection = new \ReflectionClass($type)) && $reflection->isInternal())) {
$links[] = $this->generateLink($linkText, 'https://www.php.net/class.' . strtolower(ltrim($type, '\\')), $options) . $postfix;
} elseif (in_array($type, $phpTypes)) {
if (isset($phpTypeDisplayAliases[$type])) {
$linkText = $phpTypeDisplayAliases[$type];
}
if (isset($phpTypeAliases[$type])) {
$type = $phpTypeAliases[$type];
}
$links[] = $this->generateLink($linkText, 'https://www.php.net/language.types.' . strtolower(ltrim($type, '\\')), $options) . $postfix;
} else {
$links[] = $type . $postfix;
}
} elseif ($type instanceof BaseDoc) {
$linkText = $type->name;
if ($title !== null) {
$linkText = $title;
$title = null;
}
$links[] = $this->generateLink($linkText, $this->generateApiUrl($type->name), $options) . $postfix;
}
}
return implode('|', $links);
}
Defined in: yii\apidoc\templates\bootstrap\RendererTrait::filterTypes()
Returns types of a given class
protected array filterTypes ( $types, $navClasses ) | ||
$types | yii\apidoc\models\TypeDoc[] | |
$navClasses | string |
protected function filterTypes($types, $navClasses)
{
switch ($navClasses) {
case 'app':
$types = array_filter($types, function ($val) {
return strncmp($val->name, 'yii\\', 4) !== 0;
});
break;
case 'yii':
$self = $this;
$types = array_filter($types, function ($val) use ($self) {
if ($val->name == 'Yii' || $val->name == 'YiiRequirementChecker') {
return true;
}
if (strlen($val->name) < 5) {
return false;
}
$subName = substr($val->name, 4, strpos($val->name, '\\', 5) - 4);
return strncmp($val->name, 'yii\\', 4) === 0 && !in_array($subName, $self->extensions);
});
break;
default:
$types = array_filter($types, function ($val) use ($navClasses) {
return strncmp($val->name, "yii\\$navClasses\\", strlen("yii\\$navClasses\\")) === 0;
});
}
return $types;
}
Defined in: yii\apidoc\templates\html\ApiRenderer::generateApiUrl()
Generate an url to a type in apidocs
public mixed generateApiUrl ( $typeName ) | ||
$typeName |
public function generateApiUrl($typeName)
{
return $this->generateFileName($typeName);
}
Defined in: yii\apidoc\templates\html\ApiRenderer::generateFileName()
Generates file name for API page for a given type
protected string generateFileName ( $typeName ) | ||
$typeName | string |
protected function generateFileName($typeName)
{
return strtolower(str_replace('\\', '-', $typeName)) . '.html';
}
Defined in: yii\apidoc\renderers\BaseRenderer::generateGuideUrl()
Generate an url to a guide page
public string generateGuideUrl ( $file ) | ||
$file | string |
public function generateGuideUrl($file)
{
//skip parsing external url
if ( (strpos($file, 'https://') !== false) || (strpos($file, 'http://') !== false) ) {
return $file;
}
$hash = '';
if (($pos = strpos($file, '#')) !== false) {
$hash = substr($file, $pos);
$file = substr($file, 0, $pos);
}
return rtrim($this->guideUrl, '/') . '/' . $this->guidePrefix . basename($file, '.md') . '.html' . $hash;
}
Defined in: yii\apidoc\templates\html\ApiRenderer::generateLink()
Generate link markup
protected mixed generateLink ( $text, $href, $options = [] ) | ||
$text | ||
$href | ||
$options | array |
Additional HTML attributes for the link. |
protected function generateLink($text, $href, $options = [])
{
$options['href'] = $href;
return Html::a($text, null, $options);
}
public void getSourceUrl ( $type, $line = null ) | ||
$type | ||
$line |
public function getSourceUrl($type, $line = null)
{
if (is_string($type)) {
$type = $this->apiContext->getType($type);
}
switch ($this->getTypeCategory($type)) {
case 'yii':
$baseUrl = 'https://github.com/yiisoft/yii2/blob/master';
if ($type->name == 'Yii') {
$url = "$baseUrl/framework/Yii.php";
} else {
$url = "$baseUrl/framework/" . str_replace('\\', '/', substr($type->name, 4)) . '.php';
}
break;
case 'app':
return null;
default:
$parts = explode('\\', substr($type->name, 4));
$ext = $parts[0];
unset($parts[0]);
$url = "https://github.com/yiisoft/yii2-$ext/blob/master/" . implode('/', $parts) . '.php';
break;
}
if ($line === null) {
return $url;
}
return $url . '#L' . $line;
}
Defined in: yii\apidoc\templates\bootstrap\RendererTrait::getTypeCategory()
Returns category of TypeDoc
protected string getTypeCategory ( $type ) | ||
$type | yii\apidoc\models\TypeDoc |
protected function getTypeCategory($type)
{
$extensions = $this->extensions;
$navClasses = 'app';
if (isset($type)) {
if ($type->name == 'Yii' || $type->name == 'YiiRequirementChecker') {
$navClasses = 'yii';
} elseif (strncmp($type->name, 'yii\\', 4) == 0) {
$navClasses = 'yii';
$subName = substr($type->name, 4);
if (($pos = strpos($subName, '\\')) !== false) {
$subNamespace = substr($subName, 0, $pos);
if (in_array($subNamespace, $extensions)) {
$navClasses = $subNamespace;
}
}
}
}
return $navClasses;
}
Defined in: yii\apidoc\templates\html\ApiRenderer::getView()
public \yii\web\View getView ( ) | ||
return | \yii\web\View |
The view instance |
---|
public function getView()
{
if ($this->_view === null) {
$this->_view = new View();
$assetPath = Yii::getAlias($this->_targetDir) . '/assets';
if (!is_dir($assetPath)) {
mkdir($assetPath);
}
$this->_view->assetManager = new AssetManager([
'basePath' => $assetPath,
'baseUrl' => './assets',
]);
}
return $this->_view;
}
public void getViewPath ( ) |
public function getViewPath()
{
return Yii::getAlias('@yii/apidoc/templates/html/views');
}
Defined in: yii\apidoc\templates\html\ApiRenderer::init()
public void init ( ) |
public function init()
{
parent::init();
if ($this->pageTitle === null) {
$this->pageTitle = 'Yii Framework 2.0 API Documentation';
}
}
Renders a given yii\apidoc\models\Context.
public void render ( $context, $targetDir ) | ||
$context | yii\apidoc\models\Context |
The api documentation context to render. |
$targetDir | string |
public function render($context, $targetDir)
{
$types = array_merge($context->classes, $context->interfaces, $context->traits);
$extTypes = [];
foreach ($this->extensions as $k => $ext) {
$extType = $this->filterTypes($types, $ext);
if (empty($extType)) {
unset($this->extensions[$k]);
continue;
}
$extTypes[$ext] = $extType;
}
// render view files
parent::render($context, $targetDir);
if ($this->controller !== null) {
$this->controller->stdout('generating extension index files...');
}
foreach ($extTypes as $ext => $extType) {
$readme = @file_get_contents("https://raw.github.com/yiisoft/yii2-$ext/master/README.md");
$indexFileContent = $this->renderWithLayout($this->indexView, [
'docContext' => $context,
'types' => $extType,
'readme' => $readme ?: null,
]);
file_put_contents($targetDir . "/ext-{$ext}-index.html", $indexFileContent);
}
$yiiTypes = $this->filterTypes($types, 'yii');
if (empty($yiiTypes)) {
//$readme = @file_get_contents("https://raw.github.com/yiisoft/yii2-framework/master/README.md");
$indexFileContent = $this->renderWithLayout($this->indexView, [
'docContext' => $context,
'types' => $this->filterTypes($types, 'app'),
'readme' => null,
]);
} else {
$readme = @file_get_contents("https://raw.github.com/yiisoft/yii2-framework/master/README.md");
$indexFileContent = $this->renderWithLayout($this->indexView, [
'docContext' => $context,
'types' => $yiiTypes,
'readme' => $readme ?: null,
]);
}
file_put_contents($targetDir . '/index.html', $indexFileContent);
if ($this->controller !== null) {
$this->controller->stdout('done.' . PHP_EOL, Console::FG_GREEN);
$this->controller->stdout('generating search index...');
}
$indexer = new ApiIndexer();
$indexer->indexFiles(FileHelper::findFiles($targetDir, ['only' => ['*.html']]), $targetDir);
$js = $indexer->exportJs();
file_put_contents($targetDir . '/jssearch.index.js', $js);
if ($this->controller !== null) {
$this->controller->stdout('done.' . PHP_EOL, Console::FG_GREEN);
}
}
public string renderClasses ( $names ) | ||
$names | array |
public function renderClasses($names)
{
$classes = [];
sort($names, SORT_STRING);
foreach ($names as $class) {
if (isset($this->apiContext->classes[$class])) {
$classes[] = $this->createTypeLink($this->apiContext->classes[$class]);
} else {
$classes[] = $this->createTypeLink($class);
}
}
return implode(', ', $classes);
}
Defined in: yii\apidoc\templates\html\ApiRenderer::renderDefaultValue()
Renders the default value.
public string renderDefaultValue ( $value ) | ||
$value | mixed |
public function renderDefaultValue($value)
{
if ($value === null) {
return 'null';
}
// special numbers which are usually used in octal or hex notation
static $specials = [
// file permissions
'420' => '0644',
'436' => '0664',
'438' => '0666',
'493' => '0755',
'509' => '0775',
'511' => '0777',
// colors used in yii\captcha\CaptchaAction
'2113696' => '0x2040A0',
'16777215' => '0xFFFFFF',
];
if (isset($specials[$value])) {
return $specials[$value];
}
return $value;
}
public string renderInheritance ( $class ) | ||
$class | yii\apidoc\models\ClassDoc |
public function renderInheritance($class)
{
$parents = [];
$parents[] = $this->createTypeLink($class);
while ($class->parentClass !== null) {
if (isset($this->apiContext->classes[$class->parentClass])) {
$class = $this->apiContext->classes[$class->parentClass];
$parents[] = $this->createTypeLink($class);
} else {
$parents[] = $this->createTypeLink($class->parentClass);
break;
}
}
return implode(" »\n", $parents);
}
public string renderInterfaces ( $names ) | ||
$names | array |
public function renderInterfaces($names)
{
$interfaces = [];
sort($names, SORT_STRING);
foreach ($names as $interface) {
if (isset($this->apiContext->interfaces[$interface])) {
$interfaces[] = $this->createTypeLink($this->apiContext->interfaces[$interface]);
} else {
$interfaces[] = $this->createTypeLink($interface);
}
}
return implode(', ', $interfaces);
}
public string renderMethodSignature ( $method, $context = null ) | ||
$method | yii\apidoc\models\MethodDoc | |
$context |
public function renderMethodSignature($method, $context = null)
{
$params = [];
foreach ($method->params as $param) {
$params[] = (empty($param->typeHint) ? '' : '<span class="signature-type">' . $this->createTypeLink($param->typeHint, $context) . '</span> ')
. ($param->isPassedByReference ? '<b>&</b>' : '')
. ApiMarkdown::highlight(
$param->name
. ($param->isOptional ? ' = ' . $this->renderDefaultValue($param->defaultValue) : ''),
'php'
);
}
$definition = [];
$definition[] = $method->visibility;
if ($method->isAbstract) {
$definition[] = 'abstract';
}
if ($method->isStatic) {
$definition[] = 'static';
}
return '<span class="signature-defs">' . implode(' ', $definition) . '</span> '
. '<span class="signature-type">' . ($method->isReturnByReference ? '<b>&</b>' : '')
. ($method->returnType === null ? 'void' : $this->createTypeLink($method->returnTypes, $context)) . '</span> '
. '<strong>' . $this->createSubjectLink($method, $method->name) . '</strong>'
. str_replace(' ', ' ', ' ( ' . implode(', ', $params) . ' )');
}
public string renderPropertySignature ( $property, $context = null ) | ||
$property | yii\apidoc\models\PropertyDoc | |
$context | mixed |
public function renderPropertySignature($property, $context = null)
{
if ($property->getter !== null || $property->setter !== null) {
$sig = [];
if ($property->getter !== null) {
$sig[] = $this->renderMethodSignature($property->getter, $context);
}
if ($property->setter !== null) {
$sig[] = $this->renderMethodSignature($property->setter, $context);
}
return implode('<br />', $sig);
}
$definition = [];
$definition[] = $property->visibility;
if ($property->isStatic) {
$definition[] = 'static';
}
return '<span class="signature-defs">' . implode(' ', $definition) . '</span> '
. '<span class="signature-type">' . $this->createTypeLink($property->types, $context) . '</span>'
. ' ' . $this->createSubjectLink($property, $property->name) . ' '
. ApiMarkdown::highlight('= ' . $this->renderDefaultValue($property->defaultValue), 'php');
}
public string renderTraits ( $names ) | ||
$names | array |
public function renderTraits($names)
{
$traits = [];
sort($names, SORT_STRING);
foreach ($names as $trait) {
if (isset($this->apiContext->traits[$trait])) {
$traits[] = $this->createTypeLink($this->apiContext->traits[$trait]);
} else {
$traits[] = $this->createTypeLink($trait);
}
}
return implode(', ', $traits);
}
Defined in: yii\apidoc\templates\html\ApiRenderer::renderWithLayout()
Renders file applying layout
protected string renderWithLayout ( $viewFile, $params ) | ||
$viewFile | string |
The view name |
$params | array |
The parameters (name-value pairs) that will be extracted and made available in the view file. |
protected function renderWithLayout($viewFile, $params)
{
$output = $this->getView()->render($viewFile, $params, $this);
if ($this->layout !== false) {
$params['content'] = $output;
return $this->getView()->renderFile($this->layout, $params, $this);
}
return $output;
}