Class yii\apidoc\templates\html\ApiRenderer
| Inheritance | yii\apidoc\templates\html\ApiRenderer » yii\apidoc\renderers\ApiRenderer » yii\apidoc\renderers\BaseRenderer » yii\base\Component |
|---|---|
| Implements | yii\base\ViewContextInterface |
| Subclasses | yii\apidoc\templates\bootstrap\ApiRenderer, yii\apidoc\templates\online\ApiRenderer |
| Available since extension's version | 2.0 |
| Source Code | https://github.com/yiisoft/yii2-apidoc/blob/master/templates/html/ApiRenderer.php |
The base class for HTML API documentation renderers.
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 |
| $guidePrefix | yii\apidoc\renderers\BaseRenderer | ||
| $guideUrl | yii\apidoc\renderers\BaseRenderer | ||
| $indexView | string | Path or alias of the view file to use for rendering the index page. | yii\apidoc\templates\html\ApiRenderer |
| $layout | string | Path or alias of the layout file to use. | yii\apidoc\templates\html\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 |
|---|---|---|
| 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 |
| 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
Path or alias of the view file to use for rendering the index page.
Path or alias of the view file to use for rendering types (classes, interfaces, traits).
The view instance. This property is read-only.
Method Details
Defined in: yii\apidoc\renderers\BaseRenderer::createSubjectLink()
Creates a link to a subject
| public createSubjectLink( yii\apidoc\models\PropertyDoc|yii\apidoc\models\MethodDoc|yii\apidoc\models\ConstDoc|yii\apidoc\models\EventDoc $subject, string|null $title = null, array $options = [] ): string | ||
| $subject | yii\apidoc\models\PropertyDoc|yii\apidoc\models\MethodDoc|yii\apidoc\models\ConstDoc|yii\apidoc\models\EventDoc | |
| $title | string|null | |
| $options | array |
Additional HTML attributes for the link. |
public function createSubjectLink($subject, string $title = null, array $options = []): string
{
if ($title === null) {
$title = $subject->shortName;
}
if (($type = $this->apiContext->getType($subject->definedBy)) === null) {
return $subject->shortName;
}
$link = $this->generateApiUrl($type->name) . '#' . $subject->shortName . '-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 createTypeLink( 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[] $types, yii\apidoc\models\BaseDoc $context = null, string $title = null, array $options = [] ): string | ||
| $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_object($type) && \method_exists($type, '__toString')) {
$type = (string)$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);
}
Generate an url to a type in apidocs
| public generateApiUrl( mixed $typeName ): mixed | ||
| $typeName | mixed | |
public function generateApiUrl($typeName)
{
return $this->generateFileName($typeName);
}
Generates file name for API page for a given type
| protected generateFileName( string $typeName ): string | ||
| $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 generateGuideUrl( string $file ): string | ||
| $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;
}
Generate link markup
| protected generateLink( mixed $text, mixed $href, mixed $options = [] ): mixed | ||
| $text | mixed | |
| $href | mixed | |
| $options | mixed |
Additional HTML attributes for the link. |
protected function generateLink($text, $href, $options = [])
{
$options['href'] = $href;
return Html::a($text, null, $options);
}
| public getSourceUrl( mixed $type, mixed $line = null ): | ||
| $type | mixed | |
| $line | mixed | |
public function getSourceUrl($type, $line = null)
{
return null;
}
| public getView( ): \yii\web\View | ||
| 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 getViewPath( ): |
public function getViewPath()
{
return Yii::getAlias('@yii/apidoc/templates/html/views');
}
| public init( ): mixed |
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 render( yii\apidoc\models\Context $context, string $targetDir ): mixed | ||
| $context | yii\apidoc\models\Context |
The api documentation context to render. |
| $targetDir | string | |
public function render($context, $targetDir)
{
$this->apiContext = $context;
$this->_targetDir = $targetDir;
$types = array_merge($context->classes, $context->interfaces, $context->traits);
$typeCount = count($types) + 1;
if ($this->controller !== null) {
Console::startProgress(0, $typeCount, 'Rendering files: ', false);
}
$done = 0;
foreach ($types as $type) {
$fileContent = $this->renderWithLayout($this->typeView, [
'type' => $type,
'apiContext' => $context,
'types' => $types,
]);
file_put_contents($targetDir . '/' . $this->generateFileName($type->name), $fileContent);
if ($this->controller !== null) {
Console::updateProgress(++$done, $typeCount);
}
}
$indexFileContent = $this->renderWithLayout($this->indexView, [
'apiContext' => $context,
'types' => $types,
]);
file_put_contents($targetDir . '/index.html', $indexFileContent);
if ($this->controller !== null) {
Console::updateProgress(++$done, $typeCount);
Console::endProgress(true);
$this->controller->stdout('done.' . PHP_EOL, Console::FG_GREEN);
}
}
| public renderClasses( array $names ): string | ||
| $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);
}
Renders the default value.
| public renderDefaultValue( mixed $value ): string | ||
| $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 renderInheritance( yii\apidoc\models\ClassDoc $class ): string | ||
| $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 renderInterfaces( array $names ): string | ||
| $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 renderMethodSignature( yii\apidoc\models\MethodDoc $method, mixed $context = null ): string | ||
| $method | yii\apidoc\models\MethodDoc | |
| $context | mixed | |
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 renderPropertySignature( yii\apidoc\models\PropertyDoc $property, mixed $context = null ): string | ||
| $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 renderTraits( array $names ): string | ||
| $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);
}
Renders file applying layout
| protected renderWithLayout( string $viewFile, array $params ): string | ||
| $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;
}