Class yii\apidoc\templates\online\ApiRenderer
| Inheritance | yii\apidoc\templates\online\ApiRenderer » yii\apidoc\templates\html\ApiRenderer » yii\apidoc\renderers\ApiRenderer » yii\apidoc\renderers\BaseRenderer » yii\base\Component |
|---|---|
| Implements | yii\base\ViewContextInterface |
| Available since extension's version | 2.0 |
| Source Code | https://github.com/yiisoft/yii2-apidoc/blob/master/templates/online/ApiRenderer.php |
Public Properties
Public Methods
Protected Methods
| Method | Description | Defined By |
|---|---|---|
| generateFileName() | Generates file name for API page for a given type | yii\apidoc\templates\online\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 |
|---|---|---|---|
| PHPSTAN_TYPES_DOC_LINKS | [ 'general-arrays' => [ 'array', 'non-empty-array', ], 'lists' => [ 'list', 'non-empty-list', ], 'basic-types' => [ 'array-key', 'scalar', 'open-resource', 'closed-resource', ], 'class-string' => [ 'class-string', ], 'other-advanced-string-types' => [ 'callable-string', 'numeric-string', 'non-empty-string', 'non-falsy-string', 'truthy-string', 'literal-string', 'lowercase-string', ], 'integer-ranges' => [ 'int', 'positive-int', 'negative-int', 'non-positive-int', 'non-negative-int', 'non-zero-int', ], 'integer-masks' => [ 'int-mask', 'int-mask-of', ], 'bottom-type' => [ 'never-return', 'never-returns', 'no-return', ], 'key-and-value-types-of-arrays-and-iterables' => [ 'key-of', 'value-of', ], ] | yii\apidoc\renderers\BaseRenderer | |
| PHPSTAN_TYPE_BASE_URL | 'https://phpstan.org/writing-php-code/phpdoc-types#' | yii\apidoc\renderers\BaseRenderer | |
| PHP_CLASS_BASE_URL | 'https://www.php.net/class.' | yii\apidoc\renderers\BaseRenderer | |
| PHP_TYPES | [ 'callable', 'array', 'string', 'boolean', 'bool', 'integer', 'int', 'float', 'object', 'resource', 'null', 'false', 'true', 'iterable', 'mixed', 'never', 'void', ] | yii\apidoc\renderers\BaseRenderer | |
| PHP_TYPE_ALIASES | [ 'true' => 'boolean', 'false' => 'boolean', 'bool' => 'boolean', 'int' => 'integer', ] | yii\apidoc\renderers\BaseRenderer | |
| PHP_TYPE_BASE_URL | 'https://www.php.net/language.types.' | yii\apidoc\renderers\BaseRenderer | |
| PHP_TYPE_DISPLAY_ALIASES | [ 'bool' => 'boolean', 'int' => 'integer', ] | yii\apidoc\renderers\BaseRenderer | |
| PSALM_TYPES_DOC_LINKS | [ 'interface-string' => 'scalar_types/#class-string-interface-string', 'trait-string' => 'scalar_types/#trait-string', 'enum-string' => 'scalar_types/#enum-string', 'properties-of' => 'utility_types/#properties-oft', 'private-properties-of' => 'utility_types/#properties-oft', 'protected-properties-of' => 'utility_types/#properties-oft', 'public-properties-of' => 'utility_types/#properties-oft', 'callable-array' => 'array_types/#callable-arrays', ] | yii\apidoc\renderers\BaseRenderer | |
| PSALM_TYPE_BASE_URL | 'https://psalm.dev/docs/annotating_code/type_syntax/' | yii\apidoc\renderers\BaseRenderer |
Property Details
Method Details
Defined in: yii\apidoc\renderers\BaseRenderer::createSubjectLink()
Creates a link to a subject
| public string createSubjectLink ( yii\apidoc\models\BaseDoc|yii\apidoc\models\PseudoTypeDoc|yii\apidoc\models\PseudoTypeImportDoc $subject, string|null $title = null, array $options = [], yii\apidoc\models\TypeDoc|null $type = null ) | ||
| $subject | yii\apidoc\models\BaseDoc|yii\apidoc\models\PseudoTypeDoc|yii\apidoc\models\PseudoTypeImportDoc | |
| $title | string|null | |
| $options | array |
Additional HTML attributes for the link. |
| $type | yii\apidoc\models\TypeDoc|null | |
public function createSubjectLink($subject, $title = null, $options = [], $type = null)
{
if ($subject instanceof PseudoTypeDoc) {
$href = $this->generateApiUrl($subject->parent->name) . "#{$subject->type}-type-{$subject->name}";
return $this->generateLink($subject->name, $href, $options);
}
if ($subject instanceof PseudoTypeImportDoc) {
$typeParentFqsen = (string) $subject->typeParentFqsen;
$href = $this->generateApiUrl(ltrim($typeParentFqsen, '\\')) . "#{$subject->type}-type-{$subject->typeName}";
return $this->generateLink($subject->typeName, $href, $options);
}
if ($title === null) {
if ($subject instanceof MethodDoc) {
$title = $subject->name . '()';
} else {
$title = $subject->name;
}
}
if (!$type && property_exists($subject, 'definedBy')) {
$type = $this->apiContext->getType($subject->definedBy);
}
if (!$type) {
return $subject->name;
}
$link = $this->generateApiUrl($type->name) . '#' . $subject->name;
if ($subject instanceof MethodDoc) {
$link .= '()';
}
$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 ( yii\apidoc\models\BaseDoc|yii\apidoc\models\BaseDoc[]|\phpDocumentor\Reflection\Type|\phpDocumentor\Reflection\Type[]|string|string[]|null $types, yii\apidoc\models\BaseDoc|null $context = null, string|null $title = null, array $options = [], ?\yii\apidoc\models\TypeDoc $currentTypeDoc = null ) | ||
| $types | yii\apidoc\models\BaseDoc|yii\apidoc\models\BaseDoc[]|\phpDocumentor\Reflection\Type|\phpDocumentor\Reflection\Type[]|string|string[]|null | |
| $context | yii\apidoc\models\BaseDoc|null | |
| $title | string|null |
A title to be used for the link TODO check whether [[yii...|Class]] is supported |
| $options | array |
Additional HTML attributes for the link. |
| $currentTypeDoc | ?\yii\apidoc\models\TypeDoc | |
public function createTypeLink(
$types,
?BaseDoc $context = null,
?string $title = null,
array $options = [],
?TypeDoc $currentTypeDoc = null
) {
if ($types === null) {
return '';
}
if (!is_array($types)) {
$types = [$types];
} elseif (count($types) > 1) {
$title = null;
}
$links = [];
foreach ($types as $type) {
if (is_string($type)) {
if ($type !== '') {
$typeDoc = $this->getTypeDocByQualifiedClassName($type, $context);
if ($typeDoc !== null) {
$links[] = $this->createTypeLink($typeDoc, $context, $title, $options);
continue;
}
}
} elseif ($type instanceof Type) {
if ($type instanceof Compound) {
$innerTypes = TypeHelper::getTypesByAggregatedType($type);
$links[] = $this->createTypeLink($innerTypes, $context, $title, $options, $currentTypeDoc);
continue;
}
if ($type instanceof ConditionalForParameter || $type instanceof Conditional) {
$possibleTypes = TypeHelper::getPossibleTypesByConditionalType($type);
$links[] = $this->createTypeLink($possibleTypes, $context, $title, $options, $currentTypeDoc);
continue;
}
if ($type instanceof Intersection) {
$innerTypes = TypeHelper::getTypesByAggregatedType($type);
$innerTypesLinks = array_map(
fn(Type $innerType) => $this->createTypeLink($innerType, $context, $title, $options, $currentTypeDoc),
$innerTypes,
);
$links[] = implode('&', $innerTypesLinks);
continue;
}
if ($type instanceof OffsetAccess) {
$offsetAccessType = $type->getType();
if ($offsetAccessType instanceof Object_ && ($offsetAccessTypeFqsen = $offsetAccessType->getFqsen()) !== null) {
$templateType = $this->getTemplateType($offsetAccessTypeFqsen->getName(), $context);
if ($templateType instanceof Array_) {
$links[] = $this->createTypeLink(
$templateType->getValueType(),
$context,
$title,
$options,
$currentTypeDoc
);
continue;
}
}
$typeLink = $this->createTypeLink($offsetAccessType, $context, $title, $options);
$links[] = $typeLink . '[' . $type->getOffset() . ']';
continue;
}
if ($type instanceof Array_ && str_ends_with((string) $type, '[]')) {
$valueType = $type->getValueType();
if ($valueType instanceof Object_ && ($valueTypeFqsen = $valueType->getFqsen()) !== null) {
$templateType = $this->getTemplateType($valueTypeFqsen->getName(), $context);
if ($templateType !== null) {
$typeLink = $this->createTypeLink($templateType, $context, $title, $options, $currentTypeDoc);
$links[] = $this->generateLink('array', self::PHPSTAN_TYPE_BASE_URL . 'general-arrays', $options) . "<{$typeLink}>";
continue;
}
}
$links[] = $this->createTypeLink($valueType, $context, $title, $options, $currentTypeDoc) . '[]';
continue;
}
if ($type instanceof ListShape) {
$itemsLinks = $this->createLinksByShapeItems($type->getItems(), $context, $title, $options, $currentTypeDoc);
$mainTypeLink = $this->generateLink('list', self::PSALM_TYPE_BASE_URL . 'array_types/#list-shapes', $options);
$links[] = $mainTypeLink . '{' . implode(', ', $itemsLinks) . '}';
continue;
}
if ($type instanceof ArrayShape) {
$itemsLinks = $this->createLinksByShapeItems($type->getItems(), $context, $title, $options, $currentTypeDoc);
$mainTypeLink = $this->generateLink('array', self::PHPSTAN_TYPE_BASE_URL . 'array-shapes', $options);
$links[] = $mainTypeLink . '{' . implode(', ', $itemsLinks) . '}';
continue;
}
if ($type instanceof ObjectShape) {
$itemsLinks = $this->createLinksByShapeItems($type->getItems(), $context, $title, $options, $currentTypeDoc);
$mainTypeLink = $this->generateLink('object', self::PHPSTAN_TYPE_BASE_URL . 'object-shapes', $options);
$links[] = $mainTypeLink . '{' . implode(', ', $itemsLinks) . '}';
continue;
}
if ($type instanceof Callable_) {
$links[] = $this->createCallableTypeLink($type, $context, $title, $options, $currentTypeDoc);
continue;
}
if ($type instanceof This && $currentTypeDoc !== null) {
$links[] = $this->createTypeLink($currentTypeDoc, null, '$this', $options);
continue;
}
if ($type instanceof Static_ && !$type->getGenericTypes() && $currentTypeDoc !== null) {
$links[] = $this->createTypeLink($currentTypeDoc, null, null, $options);
continue;
}
if ($type instanceof Nullable) {
$links[] = $this->createTypeLink([$type->getActualType(), new Null_()]);
continue;
}
if (($link = $this->createLinkByTypeWithGenerics($type, $context, $title, $options, $currentTypeDoc)) !== null) {
$links[] = $link;
continue;
}
if ($type instanceof Object_ && ($typeFqsen = $type->getFqsen()) !== null) {
$typeName = $typeFqsen->getName();
if (($typeDoc = $this->getTypeDocByQualifiedClassName((string) $typeFqsen, $context)) !== null) {
$links[] = $this->createTypeLink($typeDoc, $context, $typeDoc->name, $options);
continue;
}
if (($templateType = $this->getTemplateType($typeName, $context)) !== null) {
$links[] = $this->createTypeLink($templateType, $context, $title, $options, $currentTypeDoc);
continue;
}
if (($phpStanType = $this->getPhpStanType($typeName, $context)) !== null) {
$links[] = $this->createSubjectLink($phpStanType);
continue;
}
if (($psalmType = $this->getPsalmType($typeName, $context)) !== null) {
$links[] = $this->createSubjectLink($psalmType);
continue;
}
if (($phpStanTypeImport = $this->getPhpStanTypeImport($typeName, $context)) !== null) {
$links[] = $this->createSubjectLink($phpStanTypeImport);
continue;
}
if (($psalmTypeImport = $this->getPsalmTypeImport($typeName, $context)) !== null) {
$links[] = $this->createSubjectLink($psalmTypeImport);
continue;
}
}
}
if (is_object($type) && method_exists($type, '__toString')) {
$type = (string) $type;
}
$link = $this->createTypeLinkByType($type, $title, $options);
if ($link !== null) {
$links[] = $link;
}
}
return implode('|', array_unique($links));
}
Generate an url to a type in apidocs
| public mixed generateApiUrl ( mixed $typeName ) | ||
| $typeName | mixed | |
public function generateApiUrl($typeName)
{
return strtolower(str_replace('\\', '-', $typeName));
}
Generates file name for API page for a given type
| protected string generateFileName ( mixed $typeName ) | ||
| $typeName | mixed | |
protected function generateFileName($typeName)
{
return $this->generateApiUrl($typeName) . '.html';
}
Defined in: yii\apidoc\renderers\BaseRenderer::generateGuideUrl()
Generate an url to a guide page
| public string generateGuideUrl ( string $file ) | ||
| $file | string | |
public function generateGuideUrl($file)
{
//skip parsing external url
if ((str_contains($file, 'https://')) || (str_contains($file, 'http://'))) {
return $file;
}
$hash = '';
if (($pos = strpos($file, '#')) !== false) {
$hash = substr($file, $pos);
$file = substr($file, 0, $pos);
}
return rtrim((string) $this->guideUrl, '/') . '/' . $this->guidePrefix . basename($file, '.md') . '.html' . $hash;
}
Defined in: yii\apidoc\templates\html\ApiRenderer::generateLink()
Generate link markup
| protected mixed generateLink ( mixed $text, mixed $href, mixed $options = [] ) | ||
| $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;
}
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 getViewPath ( ) |
public function getViewPath()
{
return Yii::getAlias('@yii/apidoc/templates/html/views');
}
Defined in: yii\apidoc\templates\html\ApiRenderer::init()
| public mixed 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 mixed render ( mixed $context, mixed $targetDir ) | ||
| $context | mixed |
The api documentation context to render. |
| $targetDir | mixed | |
public function render($context, $targetDir)
{
parent::render($context, $targetDir);
if ($this->controller !== null) {
$this->controller->stdout('writing packages file...');
}
$packages = [];
$notNamespaced = [];
foreach (array_merge($context->classes, $context->interfaces, $context->traits) as $type) {
/** @var TypeDoc $type */
if (empty($type->namespace)) {
$notNamespaced[] = str_replace('\\', '-', $type->name);
} else {
$packages[$type->namespace][] = str_replace('\\', '-', $type->name);
}
}
ksort($packages);
$packages = array_merge(['Not namespaced' => $notNamespaced], $packages);
foreach ($packages as $name => $classes) {
sort($packages[$name]);
}
file_put_contents($targetDir . '/packages.txt', serialize($packages));
if ($this->controller !== null) {
$this->controller->stdout('done.' . PHP_EOL, Console::FG_GREEN);
}
}
| public string renderClasses ( array $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 ( mixed $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',
];
return $specials[$value] ?? $value;
}
| public string renderInheritance ( yii\apidoc\models\ClassDoc $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 ( array $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 ( yii\apidoc\models\MethodDoc $method, ?\yii\apidoc\models\TypeDoc $context = null ) | ||
| $method | yii\apidoc\models\MethodDoc | |
| $context | ?\yii\apidoc\models\TypeDoc | |
public function renderMethodSignature(MethodDoc $method, ?TypeDoc $context = null): string
{
$params = [];
foreach ($method->params as $param) {
$params[] = '<span class="signature-type">' . $this->createTypeLink($param->type, $method) . '</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> '
. '<strong>' . $this->createSubjectLink($method, $method->name) . '</strong>'
. str_replace(' ', ' ', '( ' . implode(', ', $params) . ' )')
. ': <span class="signature-type">' . ($method->isReturnByReference ? '<b>&</b>' : '')
. $this->createTypeLink($method->returnType, $method, null, [], $context) . '</span>';
}
| public string renderPropertySignature ( yii\apidoc\models\PropertyDoc $property, mixed $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->type, $property) . '</span>'
. ' ' . $this->createSubjectLink($property, $property->name) . ' '
. ApiMarkdown::highlight('= ' . $this->renderDefaultValue($property->defaultValue), 'php');
}
| public string renderTraits ( array $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 ( string $viewFile, array $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;
}