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

namespace yii\build\controllers;

use yii\console\Controller;
use yii\helpers\Console;
12
use yii\helpers\FileHelper;
13 14 15

/**
 * PhpDocController is there to help maintaining PHPDoc annotation in class files
16
 *
17 18 19 20 21 22
 * @author Carsten Brandt <mail@cebe.cc>
 * @author Alexander Makarov <sam@rmcreative.ru>
 * @since 2.0
 */
class PhpDocController extends Controller
{
23 24 25 26 27 28 29 30
	public $defaultAction = 'property';

	/**
	 * @var bool whether to update class docs directly. Setting this to false will just output docs
	 * for copy and paste.
	 */
	public $updateFiles = true;

31 32 33
	/**
	 * Generates @property annotations in class files from getters and setters
	 *
34 35 36 37 38 39
	 * Property description will be taken from getter or setter or from an @property annotation
	 * in the getters docblock if there is one defined.
	 *
	 * See https://github.com/yiisoft/yii2/wiki/Core-framework-code-style#documentation for details.
	 *
	 * @param null $root the directory to parse files from. Defaults to YII_PATH.
40
	 */
41
	public function actionProperty($root=null)
42
	{
43 44
		if ($root === null) {
			$root = YII_PATH;
45
		}
46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67
		$root = FileHelper::normalizePath($root);
		$options = array(
			'filter' => function ($path) {
				if (is_file($path)) {
					$file = basename($path);
					if ($file[0] < 'A' || $file[0] > 'Z') {
						return false;
					}
				}
				return null;
			},
			'only' => array('.php'),
			'except' => array(
				'YiiBase.php',
				'Yii.php',
				'/debug/views/',
				'/requirements/',
				'/gii/views/',
				'/gii/generators/',
			),
		);
		$files = FileHelper::findFiles($root, $options);
68
		$nFilesTotal = 0;
69
		$nFilesUpdated = 0;
70 71 72 73
		foreach ($files as $file) {
			$result = $this->generateClassPropertyDocs($file);
			if ($result !== false) {
				list($className, $phpdoc) = $result;
74
				if ($this->updateFiles) {
75 76 77 78 79 80 81 82 83 84
					if ($this->updateClassPropertyDocs($file, $className, $phpdoc)) {
						$nFilesUpdated++;
					}
				} elseif (!empty($phpdoc)) {
					$this->stdout("\n[ " . $file . " ]\n\n", Console::BOLD);
					$this->stdout($phpdoc);
				}
			}
			$nFilesTotal++;
		}
85

86
		$this->stdout("\nParsed $nFilesTotal files.\n");
87
		$this->stdout("Updated $nFilesUpdated files.\n");
88 89
	}

90 91 92 93 94
	public function globalOptions()
	{
		return array_merge(parent::globalOptions(), array('updateFiles'));
	}

95
	protected function updateClassPropertyDocs($file, $className, $propertyDoc)
96
	{
97 98 99 100 101
		$ref = new \ReflectionClass($className);
		if ($ref->getFileName() != $file) {
			$this->stderr("[ERR] Unable to create ReflectionClass for class: $className loaded class is not from file: $file\n", Console::FG_RED);
		}

102
		if (!$ref->isSubclassOf('yii\base\Object') && $className != 'yii\base\Object') {
103
			$this->stderr("[INFO] Skipping class $className as it is not a subclass of yii\\base\\Object.\n", Console::FG_BLUE, Console::BOLD);
104 105 106
			return false;
		}

107 108 109 110 111 112
		$oldDoc = $ref->getDocComment();
		$newDoc = $this->cleanDocComment($this->updateDocComment($oldDoc, $propertyDoc));

		$seenSince = false;
		$seenAuthor = false;

113
		// TODO move these checks to different action
114
		$lines = explode("\n", $newDoc);
115 116 117
		if (trim($lines[1]) == '*' || substr(trim($lines[1]), 0, 3) == '* @') {
			$this->stderr("[WARN] Class $className has no short description.\n", Console::FG_YELLOW, Console::BOLD);
		}
118 119 120 121 122 123 124 125 126 127 128 129 130 131 132
		foreach($lines as $line) {
			if (substr(trim($line), 0, 9) == '* @since ') {
				$seenSince = true;
			} elseif (substr(trim($line), 0, 10) == '* @author ') {
				$seenAuthor = true;
			}
		}

		if (!$seenSince) {
			$this->stderr("[ERR] No @since found in class doc in file: $file\n", Console::FG_RED);
		}
		if (!$seenAuthor) {
			$this->stderr("[ERR] No @author found in class doc in file: $file\n", Console::FG_RED);
		}

133
		if (trim($oldDoc) != trim($newDoc)) {
134

135 136 137
			$fileContent = explode("\n", file_get_contents($file));
			$start = $ref->getStartLine() - 2;
			$docStart = $start - count(explode("\n", $oldDoc)) + 1;
138 139

			$newFileContent = array();
140 141
			$n = count($fileContent);
			for($i = 0; $i < $n; $i++) {
142
				if ($i > $start || $i < $docStart) {
143
					$newFileContent[] = $fileContent[$i];
144 145
				} else {
					$newFileContent[] = trim($newDoc);
146
					$i = $start;
147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194
				}
			}

			file_put_contents($file, implode("\n", $newFileContent));

			return true;
		}
		return false;
	}

	/**
	 * remove multi empty lines and trim trailing whitespace
	 *
	 * @param $doc
	 * @return string
	 */
	protected function cleanDocComment($doc)
	{
		$lines = explode("\n", $doc);
		$n = count($lines);
		for($i = 0; $i < $n; $i++) {
			$lines[$i] = rtrim($lines[$i]);
			if (trim($lines[$i]) == '*' && trim($lines[$i + 1]) == '*') {
				unset($lines[$i]);
			}
		}
		return implode("\n", $lines);
	}

	/**
	 * replace property annotations in doc comment
	 * @param $doc
	 * @param $properties
	 * @return string
	 */
	protected function updateDocComment($doc, $properties)
	{
		$lines = explode("\n", $doc);
		$propertyPart = false;
		$propertyPosition = false;
		foreach($lines as $i => $line) {
			if (substr(trim($line), 0, 12) == '* @property ') {
				$propertyPart = true;
			} elseif ($propertyPart && trim($line) == '*') {
				$propertyPosition = $i;
				$propertyPart = false;
			}
			if (substr(trim($line), 0, 10) == '* @author ' && $propertyPosition === false) {
195
				$propertyPosition = $i - 1;
196 197 198 199 200 201 202 203 204 205 206 207 208 209
				$propertyPart = false;
			}
			if ($propertyPart) {
				unset($lines[$i]);
			}
		}
		$finalDoc = '';
		foreach($lines as $i => $line) {
			$finalDoc .= $line . "\n";
			if ($i == $propertyPosition) {
				$finalDoc .= $properties;
			}
		}
		return $finalDoc;
210 211 212 213
	}

	protected function generateClassPropertyDocs($fileName)
	{
214 215
		$phpdoc = "";
		$file = str_replace("\r", "", str_replace("\t", " ", file_get_contents($fileName, true)));
216 217 218
		$ns = $this->match('#\nnamespace (?<name>[\w\\\\]+);\n#', $file);
		$namespace = reset($ns);
		$namespace = $namespace['name'];
219
		$classes = $this->match('#\n(?:abstract )?class (?<name>\w+)( |\n)(extends )?.+\{(?<content>.*)\n\}(\n|$)#', $file);
220 221 222 223 224 225

		if (count($classes) > 1) {
			$this->stderr("[ERR] There should be only one class in a file: $fileName\n", Console::FG_RED);
			return false;
		}
		if (count($classes) < 1) {
226 227 228 229 230 231 232 233
			$interfaces = $this->match('#\ninterface (?<name>\w+)\n\{(?<content>.+)\n\}(\n|$)#', $file);
			if (count($interfaces) == 1) {
				return false;
			} elseif (count($interfaces) > 1) {
				$this->stderr("[ERR] There should be only one interface in a file: $fileName\n", Console::FG_RED);
			} else {
				$this->stderr("[ERR] No class in file: $fileName\n", Console::FG_RED);
			}
234 235 236 237
			return false;
		}

		$className = null;
238
		foreach ($classes as &$class) {
239

240
			$className = $namespace . '\\' . $class['name'];
241

242
			$gets = $this->match(
243
				'#\* @return (?<type>[\w\\|\\\\\\[\\]]+)(?: (?<comment>(?:(?!\*/|\* @).)+?)(?:(?!\*/).)+|[\s\n]*)\*/' .
244 245 246
				'[\s\n]{2,}public function (?<kind>get)(?<name>\w+)\((?:,? ?\$\w+ ?= ?[^,]+)*\)#',
				$class['content']);
			$sets = $this->match(
247
				'#\* @param (?<type>[\w\\|\\\\\\[\\]]+) \$\w+(?: (?<comment>(?:(?!\*/|\* @).)+?)(?:(?!\*/).)+|[\s\n]*)\*/' .
248 249
				'[\s\n]{2,}public function (?<kind>set)(?<name>\w+)\(\$\w+(?:, ?\$\w+ ?= ?[^,]+)*\)#',
				$class['content']);
250 251 252 253 254 255
			// check for @property annotations in getter and setter
			$properties = $this->match(
				'#\* @(?<kind>property) (?<type>[\w\\|\\\\\\[\\]]+)(?: (?<comment>(?:(?!\*/|\* @).)+?)(?:(?!\*/).)+|[\s\n]*)\*/' .
				'[\s\n]{2,}public function [g|s]et(?<name>\w+)\(((?:,? ?\$\w+ ?= ?[^,]+)*|\$\w+(?:, ?\$\w+ ?= ?[^,]+)*)\)#',
				$class['content']);
			$acrs = array_merge($properties, $gets, $sets);
256
			//print_r($acrs); continue;
257

258 259 260 261 262 263 264 265 266 267 268
			$props = array();
			foreach ($acrs as &$acr) {
				$acr['name'] = lcfirst($acr['name']);
				$acr['comment'] = trim(preg_replace('#(^|\n)\s+\*\s?#', '$1 * ', $acr['comment']));
				$props[$acr['name']][$acr['kind']] = array(
					'type' => $acr['type'],
					'comment' => $this->fixSentence($acr['comment']),
				);
			}

			ksort($props);
269

270 271 272
			if (count($props) > 0) {
				$phpdoc .= " *\n";
				foreach ($props as $propName => &$prop) {
273 274
					$docline = ' * @';
					$docline .= 'property'; // Do not use property-read and property-write as few IDEs support complex syntax.
275
					$note = '';
276
					if (isset($prop['get']) && isset($prop['set'])) {
277 278 279 280
						if ($prop['get']['type'] != $prop['set']['type']) {
							$note = ' Note that the type of this property differs in getter and setter.'
								  . ' See [[get'.ucfirst($propName).'()]] and [[set'.ucfirst($propName).'()]] for details.';
						}
281 282 283 284 285 286
					} elseif (isset($prop['get'])) {
						$note = ' This property is read-only.';
//						$docline .= '-read';
					} elseif (isset($prop['set'])) {
						$note = ' This property is write-only.';
//						$docline .= '-write';
287 288
					} else {
						continue;
289 290 291 292 293 294 295 296 297
					}
					$docline .= ' ' . $this->getPropParam($prop, 'type') . " $$propName ";
					$comment = explode("\n", $this->getPropParam($prop, 'comment') . $note);
					foreach ($comment as &$cline) {
						$cline = ltrim($cline, '* ');
					}
					$docline = wordwrap($docline . implode(' ', $comment), 110, "\n * ") . "\n";

					$phpdoc .= $docline;
298 299 300 301 302
				}
				$phpdoc .= " *\n";
			}
		}
		return array($className, $phpdoc);
303 304 305 306
	}

	protected function match($pattern, $subject)
	{
307 308 309 310 311 312 313
		$sets = array();
		preg_match_all($pattern . 'suU', $subject, $sets, PREG_SET_ORDER);
		foreach ($sets as &$set)
			foreach ($set as $i => $match)
				if (is_numeric($i) /*&& $i != 0*/)
					unset($set[$i]);
		return $sets;
314 315 316 317 318
	}

	protected function fixSentence($str)
	{
		// TODO fix word wrap
319 320 321
		if ($str == '')
			return '';
		return strtoupper(substr($str, 0, 1)) . substr($str, 1) . ($str[strlen($str) - 1] != '.' ? '.' : '');
322 323 324 325
	}

	protected function getPropParam($prop, $param)
	{
326
		return isset($prop['property']) ? $prop['property'][$param] : (isset($prop['get']) ? $prop['get'][$param] : $prop['set'][$param]);
327 328
	}
}