Class yii\apidoc\helpers\ApiMarkdown

Inheritanceyii\apidoc\helpers\ApiMarkdown » cebe\markdown\GithubMarkdown
Uses Traitsyii\apidoc\helpers\ApiMarkdownTrait, yii\apidoc\helpers\MarkdownHighlightTrait
Available since version2.0
Source Code https://github.com/yiisoft/yii2-apidoc/blob/master/helpers/ApiMarkdown.php

A Markdown helper with support for class reference links.

Protected Properties

Hide inherited properties

Property Type Description Defined By

Property Details

Hide inherited properties

$blockTranslations public static property (available since version 2.0.5)

Translation for guide block types

public static array $blockTranslations = []
$headings protected property
protected $headings = []
$renderer public static property
$renderingContext protected property
protected $renderingContext null

Method Details

Hide inherited methods

applyToc() protected method (available since version 2.0.5)

protected void applyToc ( $content )
$content

                protected function applyToc($content)
{
    // generate TOC if there is more than one headline
    if (!empty($this->headings) && count($this->headings) > 1) {
        $toc = [];
        foreach ($this->headings as $heading) {
            $toc[] = '<li>' . Html::a(strip_tags($heading['title']), '#' . $heading['id']) . '</li>';
        }
        $toc = '<div class="toc"><ol>' . implode("\n", $toc) . "</ol></div>\n";
        $needle = '</h1>';
        $pos = strpos($content, $needle);
        if ($pos !== false) {
            $content = substr_replace($content, "$needle\n$toc", $pos, strlen($needle));
        } else {
            $content = $toc . $content;
        }
    }
    return $content;
}

            
consumeQuote() protected method

Defined in: yii\apidoc\helpers\ApiMarkdownTrait::consumeQuote()

Consume lines for a blockquote element

protected void consumeQuote ( $lines, $current )
$lines
$current

                protected function consumeQuote($lines, $current)
{
    $block = parent::consumeQuote($lines, $current);
    $blockTypes = [
        'warning',
        'note',
        'info',
        'tip',
    ];
    // check whether this is a special Info, Note, Warning, Tip block
    $content = $block[0]['content'];
    $first = reset($content);
    if (isset($first[0]) && $first[0] === 'paragraph') {
        $parfirst = reset($first['content']);
        if (isset($parfirst[0]) && $parfirst[0] === 'text') {
            foreach ($blockTypes as $type) {
                if (strncasecmp("$type: ", $parfirst[1], $len = strlen($type) + 2) === 0) {
                    // remove block indicator
                    $block[0]['content'][0]['content'][0][1] = substr($parfirst[1], $len);
                    // add translated block indicator as bold text
                    array_unshift($block[0]['content'][0]['content'], [
                        'strong',
                        [
                            ['text', $this->translateBlockType($type)],
                        ],
                    ]);
                    $block[0]['blocktype'] = $type;
                    break;
                }
            }
        }
    }
    return $block;
}

            
getHeadings() public method (available since version 2.0.5)

public array getHeadings ( )
return array

The headlines of this document

                public function getHeadings()
{
    return $this->headings;
}

            
highlight() public static method
public static string highlight ( $code, $language )
$code string

Code to highlight

$language string

Language of the code to highlight

return string

HTML of highlighted code

                public static function highlight($code, $language)
{
    if ($language !== 'php') {
        return htmlspecialchars($code, ENT_NOQUOTES | ENT_SUBSTITUTE);
    }
    if (strncmp($code, '<?php', 5) === 0) {
        $text = @highlight_string(trim($code), true);
    } else {
        $text = highlight_string("<?php " . trim($code), true);
        $text = str_replace('&lt;?php', '', $text);
        if (($pos = strpos($text, '&nbsp;')) !== false) {
            $text = substr($text, 0, $pos) . substr($text, $pos + 6);
        }
    }
    // remove <code><span style="color: #000000">\n and </span>tags added by php
    $text = substr(trim($text), 36, -16);
    return $text;
}

            
parse() public method

public void parse ( $text )
$text

                public function parse($text)
{
    $markup = parent::parse($text);
    $markup = $this->applyToc($markup);
    return $markup;
}

            
parseApiLinkForContext() protected method (available since version 2.1.3)

Defined in: yii\apidoc\helpers\ApiMarkdownTrait::parseApiLinkForContext()

Attempts to parse an API link for the given context.

protected array parseApiLinkForContext ( $offset, $object, $title, $context )
$offset integer
$object string
$title string|null
$context yii\apidoc\models\TypeDoc|null
throws yii\apidoc\helpers\BrokenLinkException

if the object can't be resolved

                protected function parseApiLinkForContext($offset, $object, $title, $context)
{
    if (($pos = strpos($object, '::')) !== false) {
        $typeName = substr($object, 0, $pos);
        $subjectName = substr($object, $pos + 2);
        if ($context !== null) {
            if (!$context->phpDocContext) {
                throw new BrokenLinkException($object, $context);
            }
            if (isset($context->phpDocContext->getNamespaceAliases()[$typeName])) {
                $typeName = $context->phpDocContext->getNamespaceAliases()[$typeName];
            } else {
                $typeName = $context->phpDocContext->getNamespace() . '\\' . $typeName;
            }
        }
        /** @var $type TypeDoc */
        $type = static::$renderer->apiContext->getType($typeName);
        if ($type === null || $subjectName === '') {
            throw new BrokenLinkException($typeName . '::' . $subjectName, $context);
        }
        if (($subject = $type->findSubject($subjectName)) === null) {
            throw new BrokenLinkException($type->name . '::' . $subjectName, $context);
        }
        if ($title === null) {
            $title = $type->name . '::' . $subject->name;
            if ($subject instanceof MethodDoc) {
                $title .= '()';
            }
        }
        return [
            ['apiLink', static::$renderer->createSubjectLink($subject, $title)],
            $offset
        ];
    }
    if ($context !== null) {
        if (($subject = $context->findSubject($object)) !== null) {
            return [
                ['apiLink', static::$renderer->createSubjectLink($subject, $title)],
                $offset
            ];
        }
        if (!$context->phpDocContext) {
            throw new BrokenLinkException($object, $context);
        }
        if (isset($context->phpDocContext->getNamespaceAliases()[$object])) {
            $object = $context->phpDocContext->getNamespaceAliases()[$object];
        } else {
            $object = $context->phpDocContext->getNamespace() . '\\' . $object;
        }
    }
    if (($type = static::$renderer->apiContext->getType($object)) !== null) {
        return [
            ['apiLink', static::$renderer->createTypeLink($type, null, $title)],
            $offset
        ];
    }
    if (strpos($typeLink = static::$renderer->createTypeLink($object, null, $title), '<a href') !== false) {
        return [
            ['apiLink', $typeLink],
            $offset
        ];
    }
    throw new BrokenLinkException($object, $context);
}

            
parseApiLinks() protected method
protected void parseApiLinks ( $text )
$text

prepare() protected method

protected void prepare ( )

                protected function prepare()
{
    parent::prepare();
    $this->headings = [];
}

            
process() public static method

Converts markdown into HTML

public static string process ( $content, $context null, $paragraph false )
$content string
$context yii\apidoc\models\TypeDoc
$paragraph boolean

                public static function process($content, $context = null, $paragraph = false)
{
    if (!isset(Markdown::$flavors['api'])) {
        Markdown::$flavors['api'] = new static;
    }
    if (is_string($context)) {
        $context = static::$renderer->apiContext->getType($context);
    }
    Markdown::$flavors['api']->renderingContext = $context;
    if ($paragraph) {
        return Markdown::processParagraph($content, 'api');
    } else {
        return Markdown::process($content, 'api');
    }
}

            
renderApiLink() protected method
protected string renderApiLink ( $block )
$block array

renderApiLinkText() protected method
protected null|string renderApiLinkText ( $title )
$title null|string

                protected function renderApiLinkText($title)
{
    if (!$title) {
        return $title;
    }
    $title = Markdown::process($title);
    $title = mb_convert_encoding($title, 'HTML-ENTITIES', 'UTF-8');
    $doc = new DOMDocument();
    $doc->loadHTML($title);
    return $doc->getElementsByTagName('p')[0]->childNodes[0]->c14n();
}

            
renderBrokenApiLink() protected method

Defined in: yii\apidoc\helpers\ApiMarkdownTrait::renderBrokenApiLink()

Renders API link that is broken i.e. points nowhere

protected string renderBrokenApiLink ( $block )
$block array

renderCode() protected method
protected void renderCode ( $block )
$block

                protected function renderCode($block)
{
    if (self::$highlighter === null) {
        self::$highlighter = new Highlighter();
        self::$highlighter->setAutodetectLanguages([
            'apache', 'nginx',
            'bash', 'dockerfile', 'http',
            'css', 'less', 'scss',
            'javascript', 'json', 'markdown',
            'php', 'sql', 'twig', 'xml',
        ]);
    }
    try {
        if (isset($block['language'])) {
            if ($block['language'] === 'php' && strpos($block['content'], '<?=') !== false) {
                $block['language'] = 'html';
            }
            $result = self::$highlighter->highlight($block['language'], $block['content'] . "\n");
            return "<pre><code class=\"hljs {$result->language} language-{$block['language']}\">{$result->value}</code></pre>\n";
        } else {
            $result = self::$highlighter->highlightAuto($block['content'] . "\n");
            return "<pre><code class=\"hljs {$result->language}\">{$result->value}</code></pre>\n";
        }
    } catch (DomainException $e) {
        return parent::renderCode($block);
    }
}

            
renderHeadline() protected method

protected void renderHeadline ( $block )
$block

                protected function renderHeadline($block)
{
    $content = $this->renderAbsy($block['content']);
    if (preg_match('~<span id="(.*?)"></span>~', $content, $matches)) {
        $hash = $matches[1];
        $content = preg_replace('~<span id=".*?"></span>~', '', $content);
    } else {
        $hash = Inflector::slug(strip_tags($content));
    }
    $hashLink = "<span id=\"$hash\"></span><a href=\"#$hash\" class=\"hashlink\">&para;</a>";
    if ($block['level'] == 2) {
        $this->headings[] = [
            'title' => trim($content),
            'id' => $hash,
        ];
    } elseif ($block['level'] > 2) {
        if (end($this->headings)) {
            $this->headings[key($this->headings)]['sub'][] = [
                'title' => trim($content),
                'id' => $hash,
            ];
        }
    }
    $tag = 'h' . $block['level'];
    return "<$tag>$content $hashLink</$tag>";
}

            
renderLink() protected method

protected void renderLink ( $block )
$block

renderQuote() protected method

Defined in: yii\apidoc\helpers\ApiMarkdownTrait::renderQuote()

Renders a blockquote

protected void renderQuote ( $block )
$block

                protected function renderQuote($block)
{
    $class = '';
    if (isset($block['blocktype'])) {
        $class = ' class="' . $block['blocktype'] . '"';
    }
    return "<blockquote{$class}>" . $this->renderAbsy($block['content']) . "</blockquote>\n";
}

            
renderTable() public method

Add bootstrap classes to tables.

public void renderTable ( $block )
$block

                public function renderTable($block)
{
    return str_replace('<table>', '<table class="table table-bordered table-striped">', parent::renderTable($block));
}

            
translateBlockType() protected method (available since version 2.0.5)

protected void translateBlockType ( $type )
$type

                protected function translateBlockType($type)
{
    $key = ucfirst($type) . ':';
    if (isset(static::$blockTranslations[$key])) {
        $translation = static::$blockTranslations[$key];
    } else {
        $translation = $key;
    }
    return "$translation ";
}