Abstract Class yii\apidoc\renderers\GuideRenderer

All Classes | Properties | Methods | Constants

Inheritance	yii\apidoc\renderers\GuideRenderer » yii\apidoc\renderers\BaseRenderer » yii\base\Component
Subclasses	yii\apidoc\templates\bootstrap\GuideRenderer, yii\apidoc\templates\html\GuideRenderer, yii\apidoc\templates\pdf\GuideRenderer, yii\apidoc\templates\project\GuideRenderer
Available since extension's version	2.0
Source Code	https://github.com/yiisoft/yii2-apidoc/blob/master/renderers/GuideRenderer.php

Base class for all Guide documentation renderers

Public Properties

Hide inherited properties

Property	Type	Description	Defined By
$apiContext	yii\apidoc\models\Context\|null	The yii\apidoc\models\Context currently being rendered.	yii\apidoc\renderers\BaseRenderer
$apiUrl	string\|null		yii\apidoc\renderers\BaseRenderer
$controller	\yii\console\Controller<\yii\console\Application>\|null	The apidoc controller instance.	yii\apidoc\renderers\BaseRenderer
$guidePrefix	string		yii\apidoc\renderers\BaseRenderer
$guideUrl	string\|null		yii\apidoc\renderers\BaseRenderer
$pageTitle	string\|null	String to use as the title of the generated page.	yii\apidoc\renderers\BaseRenderer
$readmeUrl	string\|null	URL for the README to use for the index of the guide.	yii\apidoc\renderers\BaseRenderer

Public Methods

Hide inherited methods

Method	Description	Defined By
createSubjectLink()	Creates a link to a subject	yii\apidoc\renderers\BaseRenderer
createTypeLink()	Creates a link to a type (class, interface or trait)	yii\apidoc\renderers\BaseRenderer
generateApiUrl()	Generate an url to a type in apidocs	yii\apidoc\renderers\BaseRenderer
generateGuideUrl()	Generate an url to a guide page	yii\apidoc\renderers\BaseRenderer
init()		yii\apidoc\renderers\BaseRenderer
render()	Render markdown files	yii\apidoc\renderers\GuideRenderer

Protected Methods

Hide inherited methods

Method	Description	Defined By
generateLink()	Generate link markup	yii\apidoc\renderers\BaseRenderer
loadGuideStructure()	Loads guide structure from a set of files	yii\apidoc\renderers\GuideRenderer

Constants

Hide inherited constants

Constant	Value	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

Method Details

Hide inherited methods

createSubjectLink() public method

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

Source code

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

createTypeLink() public method

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

Source code

                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('&amp;', $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) . "&lt;{$typeLink}&gt;";
                        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));
}

generateApiUrl() public abstract method

Defined in: yii\apidoc\renderers\BaseRenderer::generateApiUrl()

Generate an url to a type in apidocs

public abstract mixed generateApiUrl ( mixed $typeName )
$typeName	mixed

Source code

                abstract public function generateApiUrl($typeName);

generateGuideUrl() public method

Defined in: yii\apidoc\renderers\BaseRenderer::generateGuideUrl()

Generate an url to a guide page

public string generateGuideUrl ( string $file )
$file	string

Source code

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

generateLink() protected abstract method

Defined in: yii\apidoc\renderers\BaseRenderer::generateLink()

Generate link markup

protected abstract mixed generateLink ( mixed $text, mixed $href, array $options = [] )
$text	mixed
$href	mixed
$options	array	Additional HTML attributes for the link.

Source code

                abstract protected function generateLink($text, $href, $options = []);

init() public method

Defined in: yii\apidoc\renderers\BaseRenderer::init()

public mixed init ( )

Source code

                public function init()
{
    ApiMarkdown::$renderer = $this;
    ApiMarkdownLaTeX::$renderer = $this;
}

loadGuideStructure() protected method

Loads guide structure from a set of files

protected array loadGuideStructure ( array $files )
$files	array

Source code

                protected function loadGuideStructure($files)
{
    $chapters = [];
    foreach ($files as $file) {
        $contents = file_get_contents($file);
        if (basename((string) $file) == 'README.md') {
            $indexAnalyzer = new IndexFileAnalyzer();
            $chapters = $indexAnalyzer->analyze($contents);
            break;
        }
        if (preg_match("/^(.*)\n=+/", $contents, $matches)) {
            $headlines[$file] = $matches[1];
        } else {
            $headlines[$file] = basename((string) $file);
        }
    }
    return $chapters;
}

render() public abstract method

Render markdown files

public abstract mixed render ( array $files, mixed $targetDir )
$files	array	List of markdown files to render
$targetDir	mixed

Source code

                abstract public function render($files, $targetDir);