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 string createSubjectLink ( $subject, string $title = null, array $options = [] ) | ||
$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 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_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 mixed generateApiUrl ( $typeName ) | ||
$typeName |
public function generateApiUrl($typeName)
{
return $this->generateFileName($typeName);
}
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;
}
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)
{
return null;
}
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');
}
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)
{
$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 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);
}
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);
}
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;
}