Renderer.php 9.14 KB
Newer Older
1 2
<?php
/**
3 4 5
 * @link http://www.yiiframework.com/
 * @copyright Copyright (c) 2008 Yii Software LLC
 * @license http://www.yiiframework.com/license/
6 7
 */

8
namespace yii\apidoc\templates\html;
9

10
use yii\apidoc\helpers\ApiMarkdown;
11
use yii\apidoc\models\BaseDoc;
12 13 14 15
use yii\apidoc\models\ConstDoc;
use yii\apidoc\models\EventDoc;
use yii\apidoc\models\MethodDoc;
use yii\apidoc\models\PropertyDoc;
16
use yii\apidoc\models\TypeDoc;
17 18 19 20 21
use yii\apidoc\models\ClassDoc;
use yii\apidoc\models\Context;
use yii\apidoc\models\InterfaceDoc;
use yii\apidoc\models\TraitDoc;
use yii\apidoc\templates\BaseRenderer;
22 23 24 25 26
use yii\base\ViewContextInterface;
use yii\console\Controller;
use yii\helpers\Console;
use yii\helpers\Html;
use Yii;
27 28
use yii\web\AssetManager;
use yii\web\View;
29

30 31 32
/**
 * The base class for HTML API documentation renderers.
 *
33 34
 * @property View $view The view instance. This property is read-only.
 *
35 36 37 38
 * @author Carsten Brandt <mail@cebe.cc>
 * @since 2.0
 */
abstract class Renderer extends BaseRenderer implements ViewContextInterface
39
{
40 41 42
	/**
	 * @var string directory to use for output of html files. Can be a path alias.
	 */
43
	public $targetDir;
44 45 46
	/**
	 * @var string string to use as the title of the generated page.
	 */
47 48
	public $pageTitle = 'Yii Framework 2.0 API Documentation';
	/**
49 50
	 * @var string path or alias of the layout file to use.
	 */
51
	public $apiLayout;
52 53 54 55 56 57 58 59 60 61 62 63 64
	/**
	 * @var string path or alias of the view file to use for rendering types (classes, interfaces, traits).
	 */
	public $typeView = '@yii/apidoc/templates/html/views/type.php';
	/**
	 * @var string path or alias of the view file to use for rendering the index page.
	 */
	public $indexView = '@yii/apidoc/templates/html/views/index.php';
	/**
	 * @var View
	 */
	private $_view;

65 66 67

	public function init()
	{
68
		ApiMarkdown::$renderer = $this;
69 70
	}

71 72 73 74 75 76 77 78 79 80 81 82 83
	/**
	 * @return 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,
Carsten Brandt committed
84
				'baseUrl' => './assets',
85 86 87 88
			]);
		}
		return $this->_view;
	}
89 90

	/**
91 92 93 94
	 * Renders a given [[Context]].
	 *
	 * @param Context $context the api documentation context to render.
	 * @param Controller $controller the apidoc controller instance. Can be used to control output.
95
	 */
96
	public function renderApi($context, $controller)
97 98 99 100
	{
		$this->context = $context;
		$dir = Yii::getAlias($this->targetDir);
		if (!is_dir($dir)) {
101
			mkdir($dir, 0777, true);
102 103
		}

Carsten Brandt committed
104 105 106
		$types = array_merge($context->classes, $context->interfaces, $context->traits);
		$typeCount = count($types) + 1;
		Console::startProgress(0, $typeCount, 'Rendering files: ', false);
107
		$done = 0;
Carsten Brandt committed
108 109 110
		foreach($types as $type) {
			$fileContent = $this->renderWithLayout($this->typeView, [
				'type' => $type,
111
				'docContext' => $context,
112
				'types' => $types,
113
			]);
Carsten Brandt committed
114 115
			file_put_contents($dir . '/' . $this->generateFileName($type->name), $fileContent);
			Console::updateProgress(++$done, $typeCount);
116 117 118
		}
		$indexFileContent = $this->renderWithLayout($this->indexView, [
			'docContext' => $context,
Carsten Brandt committed
119
			'types' => $types,
120 121
		]);
		file_put_contents($dir . '/index.html', $indexFileContent);
Carsten Brandt committed
122
		Console::updateProgress(++$done, $typeCount);
123 124 125 126 127 128 129
		Console::endProgress(true);
		$controller->stdout('done.' . PHP_EOL, Console::FG_GREEN);
	}

	protected function renderWithLayout($viewFile, $params)
	{
		$output = $this->getView()->render($viewFile, $params, $this);
130
		if ($this->apiLayout !== false) {
131
			$params['content'] = $output;
132
			return $this->getView()->renderFile($this->apiLayout, $params, $this);
133 134 135 136 137 138
		} else {
			return $output;
		}
	}

	/**
139 140
	 * creates a link to a type (class, interface or trait)
	 * @param ClassDoc|InterfaceDoc|TraitDoc $types
141
	 * @param BaseDoc $context
142 143
	 * @return string
	 */
144
	public function typeLink($types, $context = null)
145 146 147 148 149 150
	{
		if (!is_array($types)) {
			$types = [$types];
		}
		$links = [];
		foreach($types as $type) {
151 152 153 154 155 156 157 158 159 160 161 162 163 164
			$postfix = '';
			if (!is_object($type)) {
				if (substr($type, -2, 2) == '[]') {
					$postfix = '[]';
					$type = substr($type, 0, -2);
				}

				if (($t = $this->context->getType(ltrim($type, '\\'))) !== null) {
					$type = $t;
				} elseif ($type[0] !== '\\' && ($t = $this->context->getType($this->resolveNamespace($context) . '\\' . ltrim($type, '\\'))) !== null) {
					$type = $t;
				} else {
					ltrim($type, '\\');
				}
165 166 167 168 169
			}
			if (!is_object($type)) {
				$links[] = $type;
			} else {
				$links[] = Html::a(
170
					$type->name,
171
					null,
172
					['href' => $this->generateUrl($type->name)]
173
				) . $postfix;
174 175 176 177 178 179 180 181 182 183 184 185
			}
		}
		return implode('|', $links);
	}

	/**
	 * creates a link to a subject
	 * @param PropertyDoc|MethodDoc|ConstDoc|EventDoc $subject
	 * @param string $title
	 * @return string
	 */
	public function subjectLink($subject, $title = null)
186 187
	{
		if ($title === null) {
188 189 190 191 192
			if ($subject instanceof MethodDoc) {
				$title = $subject->name . '()';
			} else {
				$title = $subject->name;
			}
193 194 195 196
		}
		if (($type = $this->context->getType($subject->definedBy)) === null) {
			return $subject->name;
		} else {
197
			$link = $this->generateUrl($type->name);
198 199 200 201 202 203 204 205 206 207 208 209 210 211 212
			if ($subject instanceof MethodDoc) {
				$link .= '#' . $subject->name . '()';
			} else {
				$link .= '#' . $subject->name;
			}
			$link .= '-detail';
			return Html::a($title, null, ['href' => $link]);
		}
	}

	/**
	 * @param BaseDoc $context
	 */
	private function resolveNamespace($context)
	{
213
		// TODO use phpdoc Context for this
214 215 216 217 218
		if ($context === null) {
			return '';
		}
		if ($context instanceof TypeDoc) {
			return $context->namespace;
219
		}
220 221 222 223 224 225 226
		if ($context->hasProperty('definedBy')) {
			$type = $this->context->getType($context);
			if ($type !== null) {
				return $type->namespace;
			}
		}
		return '';
227 228 229 230 231 232 233 234
	}

	/**
	 * @param ClassDoc $class
	 * @return string
	 */
	public function renderInheritance($class)
	{
235
		$parents[] = $this->typeLink($class);
236 237 238
		while ($class->parentClass !== null) {
			if(isset($this->context->classes[$class->parentClass])) {
				$class = $this->context->classes[$class->parentClass];
239
				$parents[] = $this->typeLink($class);
240 241 242 243 244
			} else {
				$parents[] = $class->parentClass; // TODO link to php.net
				break;
			}
		}
Luciano Baraglia committed
245
		return implode(" &raquo;\n", $parents);
246 247 248
	}

	/**
249
	 * @param array $names
250 251
	 * @return string
	 */
252
	public function renderInterfaces($names)
253 254
	{
		$interfaces = [];
255 256
		sort($names, SORT_STRING);
		foreach($names as $interface) {
257
			if(isset($this->context->interfaces[$interface])) {
258
				$interfaces[] = $this->typeLink($this->context->interfaces[$interface]);
259 260 261 262
			} else {
				$interfaces[] = $interface; // TODO link to php.net
			}
		}
Luciano Baraglia committed
263
		return implode(', ', $interfaces);
264 265 266
	}

	/**
267
	 * @param array $names
268 269
	 * @return string
	 */
270
	public function renderTraits($names)
271 272
	{
		$traits = [];
273 274
		sort($names, SORT_STRING);
		foreach($names as $trait) {
275
			if(isset($this->context->traits[$trait])) {
276
				$traits[] = $this->typeLink($this->context->traits[$trait]);
277 278 279 280
			} else {
				$traits[] = $trait; // TODO link to php.net
			}
		}
Luciano Baraglia committed
281
		return implode(', ', $traits);
282 283
	}

284 285 286 287 288
	/**
	 * @param array $names
	 * @return string
	 */
	public function renderClasses($names)
289
	{
290 291 292 293 294
		$classes = [];
		sort($names, SORT_STRING);
		foreach($names as $class) {
			if(isset($this->context->classes[$class])) {
				$classes[] = $this->typeLink($this->context->classes[$class]);
295
			} else {
296
				$classes[] = $class; // TODO link to php.net
297 298
			}
		}
Luciano Baraglia committed
299
		return implode(', ', $classes);
300 301
	}

302 303 304 305 306 307
	/**
	 * @param PropertyDoc $property
	 * @return string
	 */
	public function renderPropertySignature($property)
	{
308 309 310 311 312 313 314 315 316
		if ($property->getter !== null || $property->setter !== null) {
			$sig = [];
			if ($property->getter !== null) {
				$sig[] = $this->renderMethodSignature($property->getter);
			}
			if ($property->setter !== null) {
				$sig[] = $this->renderMethodSignature($property->setter);
			}
			return implode('<br />', $sig);
317
		}
318
		return $this->typeLink($property->types) . ' ' . $property->name . ' = ' . ($property->defaultValue === null ? 'null' : $property->defaultValue);
319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336
	}

	/**
	 * @param MethodDoc $method
	 * @return string
	 */
	public function renderMethodSignature($method)
	{
		$params = [];
		foreach($method->params as $param) {
			$params[] = (empty($param->typeHint) ? '' : $param->typeHint . ' ')
				. ($param->isPassedByReference ? '<b>&</b>' : '')
				. $param->name
				. ($param->isOptional ? ' = ' . $param->defaultValue : '');
		}

		return ($method->isReturnByReference ? '<b>&</b>' : '')
			. ($method->returnType === null ? 'void' : $this->typeLink($method->returnTypes))
337
			. ' ' . $this->subjectLink($method, $method->name) . '( '
338 339 340
			. implode(', ', $params)
			. ' )';
	}
341

342
	public function generateUrl($typeName)
343 344 345 346
	{
		return $this->generateFileName($typeName);
	}

347
	protected function generateFileName($typeName)
348
	{
Carsten Brandt committed
349
		return strtolower(str_replace('\\', '_', $typeName)) . '.html';
350 351 352 353 354 355 356 357 358
	}

	/**
	 * Finds the view file corresponding to the specified relative view name.
	 * @param string $view a relative view name. The name does NOT start with a slash.
	 * @return string the view file path. Note that the file may not exist.
	 */
	public function findViewFile($view)
	{
359
		return Yii::getAlias('@yii/apidoc/templates/html/views/' . $view);
360
	}
Luciano Baraglia committed
361
}