|
|
|
<?php
|
|
|
|
/**
|
|
|
|
* @link http://www.yiiframework.com/
|
|
|
|
* @copyright Copyright (c) 2008 Yii Software LLC
|
|
|
|
* @license http://www.yiiframework.com/license/
|
|
|
|
*/
|
|
|
|
|
|
|
|
namespace yii\apidoc\helpers;
|
|
|
|
|
|
|
|
use cebe\markdown\GithubMarkdown;
|
|
|
|
use phpDocumentor\Reflection\DocBlock\Type\Collection;
|
|
|
|
use yii\apidoc\models\MethodDoc;
|
|
|
|
use yii\apidoc\models\TypeDoc;
|
|
|
|
use yii\apidoc\renderers\BaseRenderer;
|
|
|
|
use yii\helpers\Inflector;
|
|
|
|
use yii\helpers\Markdown;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* A Markdown helper with support for class reference links.
|
|
|
|
*
|
|
|
|
* @author Carsten Brandt <mail@cebe.cc>
|
|
|
|
* @since 2.0
|
|
|
|
*/
|
|
|
|
class ApiMarkdown extends GithubMarkdown
|
|
|
|
{
|
|
|
|
/**
|
|
|
|
* @var BaseRenderer
|
|
|
|
*/
|
|
|
|
public static $renderer;
|
|
|
|
|
|
|
|
protected $context;
|
|
|
|
|
|
|
|
public function prepare()
|
|
|
|
{
|
|
|
|
parent::prepare();
|
|
|
|
|
|
|
|
// add references to guide pages
|
|
|
|
$this->references = array_merge($this->references, static::$renderer->guideReferences);
|
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @inheritDoc
|
|
|
|
*/
|
|
|
|
protected function identifyLine($lines, $current)
|
|
|
|
{
|
|
|
|
if (strncmp($lines[$current], '~~~', 3) === 0) {
|
|
|
|
return 'fencedCode';
|
|
|
|
}
|
|
|
|
|
|
|
|
return parent::identifyLine($lines, $current);
|
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Consume lines for a fenced code block
|
|
|
|
*/
|
|
|
|
protected function consumeFencedCode($lines, $current)
|
|
|
|
{
|
|
|
|
// consume until ```
|
|
|
|
$block = [
|
|
|
|
'type' => 'code',
|
|
|
|
'content' => [],
|
|
|
|
];
|
|
|
|
$line = rtrim($lines[$current]);
|
|
|
|
if (strncmp($lines[$current], '~~~', 3) === 0) {
|
|
|
|
$fence = '~~~';
|
|
|
|
$language = 'php';
|
|
|
|
} else {
|
|
|
|
$fence = substr($line, 0, $pos = strrpos($line, '`') + 1);
|
|
|
|
$language = substr($line, $pos);
|
|
|
|
}
|
|
|
|
if (!empty($language)) {
|
|
|
|
$block['language'] = $language;
|
|
|
|
}
|
|
|
|
for ($i = $current + 1, $count = count($lines); $i < $count; $i++) {
|
|
|
|
if (rtrim($line = $lines[$i]) !== $fence) {
|
|
|
|
$block['content'][] = $line;
|
|
|
|
} else {
|
|
|
|
break;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
return [$block, $i];
|
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Renders a code block
|
|
|
|
*/
|
|
|
|
protected function renderCode($block)
|
|
|
|
{
|
|
|
|
if (isset($block['language'])) {
|
|
|
|
$class = isset($block['language']) ? ' class="language-' . $block['language'] . '"' : '';
|
|
|
|
|
|
|
|
return "<pre><code$class>" . $this->highlight(implode("\n", $block['content']) . "\n", $block['language']) . '</code></pre>';
|
|
|
|
} else {
|
|
|
|
return parent::renderCode($block);
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
public static function highlight($code, $language)
|
|
|
|
{
|
|
|
|
if ($language !== 'php') {
|
|
|
|
return htmlspecialchars($code, ENT_NOQUOTES, 'UTF-8');
|
|
|
|
}
|
|
|
|
|
|
|
|
// TODO improve code highlighting
|
|
|
|
if (strncmp($code, '<?php', 5) === 0) {
|
|
|
|
$text = @highlight_string(trim($code), true);
|
|
|
|
} else {
|
|
|
|
$text = highlight_string("<?php ".trim($code), true);
|
|
|
|
$text = str_replace('<?php', '', $text);
|
|
|
|
if (($pos = strpos($text, ' ')) !== 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;
|
|
|
|
}
|
|
|
|
|
|
|
|
protected function inlineMarkers()
|
|
|
|
{
|
|
|
|
return array_merge(parent::inlineMarkers(), [
|
|
|
|
'[[' => 'parseApiLinks',
|
|
|
|
]);
|
|
|
|
}
|
|
|
|
|
|
|
|
protected function parseApiLinks($text)
|
|
|
|
{
|
|
|
|
$context = $this->context;
|
|
|
|
|
|
|
|
if (preg_match('/^\[\[([\w\d\\\\\(\):$]+)(\|[^\]]*)?\]\]/', $text, $matches)) {
|
|
|
|
|
|
|
|
$offset = strlen($matches[0]);
|
|
|
|
|
|
|
|
$object = $matches[1];
|
|
|
|
$title = (empty($matches[2]) || $matches[2] == '|') ? null : substr($matches[2], 1);
|
|
|
|
|
|
|
|
if (($pos = strpos($object, '::')) !== false) {
|
|
|
|
$typeName = substr($object, 0, $pos);
|
|
|
|
$subjectName = substr($object, $pos + 2);
|
|
|
|
if ($context !== null) {
|
|
|
|
// Collection resolves relative types
|
|
|
|
$typeName = (new Collection([$typeName], $context->phpDocContext))->__toString();
|
|
|
|
}
|
|
|
|
$type = static::$renderer->apiContext->getType($typeName);
|
|
|
|
if ($type === null) {
|
|
|
|
static::$renderer->apiContext->errors[] = [
|
|
|
|
'file' => ($context !== null) ? $context->sourceFile : null,
|
|
|
|
'message' => 'broken link to ' . $typeName . '::' . $subjectName . (($context !== null) ? ' in ' . $context->name : ''),
|
|
|
|
];
|
|
|
|
|
|
|
|
return [
|
|
|
|
'<span style="background: #f00;">' . $typeName . '::' . $subjectName . '</span>',
|
|
|
|
$offset
|
|
|
|
];
|
|
|
|
} else {
|
|
|
|
if (($subject = $type->findSubject($subjectName)) !== null) {
|
|
|
|
if ($title === null) {
|
|
|
|
$title = $type->name . '::' . $subject->name;
|
|
|
|
if ($subject instanceof MethodDoc) {
|
|
|
|
$title .= '()';
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
return [
|
|
|
|
static::$renderer->createSubjectLink($subject, $title),
|
|
|
|
$offset
|
|
|
|
];
|
|
|
|
} else {
|
|
|
|
static::$renderer->apiContext->errors[] = [
|
|
|
|
'file' => ($context !== null) ? $context->sourceFile : null,
|
|
|
|
'message' => 'broken link to ' . $type->name . '::' . $subjectName . (($context !== null) ? ' in ' . $context->name : ''),
|
|
|
|
];
|
|
|
|
|
|
|
|
return [
|
|
|
|
'<span style="background: #ff0;">' . $type->name . '</span><span style="background: #f00;">::' . $subjectName . '</span>',
|
|
|
|
$offset
|
|
|
|
];
|
|
|
|
}
|
|
|
|
}
|
|
|
|
} elseif ($context !== null && ($subject = $context->findSubject($object)) !== null) {
|
|
|
|
return [
|
|
|
|
static::$renderer->createSubjectLink($subject, $title),
|
|
|
|
$offset
|
|
|
|
];
|
|
|
|
}
|
|
|
|
|
|
|
|
if ($context !== null) {
|
|
|
|
// Collection resolves relative types
|
|
|
|
$object = (new Collection([$object], $context->phpDocContext))->__toString();
|
|
|
|
}
|
|
|
|
if (($type = static::$renderer->apiContext->getType($object)) !== null) {
|
|
|
|
return [
|
|
|
|
static::$renderer->createTypeLink($type, null, $title),
|
|
|
|
$offset
|
|
|
|
];
|
|
|
|
} elseif (strpos($typeLink = static::$renderer->createTypeLink($object, null, $title), '<a href') !== false) {
|
|
|
|
return [
|
|
|
|
$typeLink,
|
|
|
|
$offset
|
|
|
|
];
|
|
|
|
}
|
|
|
|
static::$renderer->apiContext->errors[] = [
|
|
|
|
'file' => ($context !== null) ? $context->sourceFile : null,
|
|
|
|
'message' => 'broken link to ' . $object . (($context !== null) ? ' in ' . $context->name : ''),
|
|
|
|
];
|
|
|
|
|
|
|
|
return [
|
|
|
|
'<span style="background: #f00;">' . $object . '</span>',
|
|
|
|
$offset
|
|
|
|
];
|
|
|
|
}
|
|
|
|
|
|
|
|
return ['[[', 2];
|
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @inheritDoc
|
|
|
|
*/
|
|
|
|
protected function renderHeadline($block)
|
|
|
|
{
|
|
|
|
$content = $this->parseInline($block['content']);
|
|
|
|
$hash = Inflector::slug(strip_tags($content));
|
|
|
|
$hashLink = "<a href=\"#$hash\" name=\"$hash\">¶</a>";
|
|
|
|
$tag = 'h' . $block['level'];
|
|
|
|
|
|
|
|
return "<$tag>$content $hashLink</$tag>";
|
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Converts markdown into HTML
|
|
|
|
*
|
|
|
|
* @param string $content
|
|
|
|
* @param TypeDoc $context
|
|
|
|
* @param boolean $paragraph
|
|
|
|
* @return string
|
|
|
|
*/
|
|
|
|
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']->context = $context;
|
|
|
|
|
|
|
|
if ($paragraph) {
|
|
|
|
return Markdown::processParagraph($content, 'api');
|
|
|
|
} else {
|
|
|
|
return Markdown::process($content, 'api');
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|