php/yii2
1
0
Fork 0
mirror of https://github.com/yiisoft/yii2.git synced 2025-10-28 04:25:53 +08:00
Code Issues Packages Projects Releases Wiki Activity

Remove invalid @property annotations and fix property descriptions (#20510)

Browse Source
This commit is contained in:
Maksim Spirkov
2025-09-05 02:33:39 +05:00
committed by GitHub
parent f39a2ec1f9
commit f914cda51e
7 changed files with 93 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
build/controllers/PhpDocController.php
View File

@ -8,11 +8,17 @@
namespace yii\build\controllers;
use Yii;
use yii\base\Model;
use yii\base\Module;
use yii\console\Controller;
use yii\db\QueryBuilder;
use yii\helpers\Console;
use yii\helpers\FileHelper;
use yii\helpers\Json;
use yii\log\Dispatcher;
use yii\log\Target;
use yii\web\Controller as WebController;
use yii\web\Request as WebRequest;
/**
* PhpDocController is there to help to maintain PHPDoc annotation in class files.
@ -24,7 +30,7 @@ use yii\web\Controller as WebController;
class PhpDocController extends Controller
{
/**
* Manually added PHPDoc properties that do not need to be removed.
* Manually added PHPDoc properties that do not need to be removed or changed.
*
* @phpstan-var array<class-string, string[]>
*/
@ -34,8 +40,29 @@ class PhpDocController extends Controller
'response',
'view',
],
Model::class => [
'errors',
],
Module::class => [
'aliases',
],
Dispatcher::class => [
'flushInterval',
'logger',
],
Target::class => [
'enabled',
],
WebRequest::class => [
'hostInfo',
],
QueryBuilder::class => [
'conditionClasses',
],
];
private const PROPERTIES_ENCLOSURE = " *\n";
/**
* {@inheritdoc}
*/
@ -634,6 +661,9 @@ class PhpDocController extends Controller
$lines = explode("\n", $doc);
$propertyPart = false;
$propertyPosition = false;
$lastPropertyName = null;
$hasManuallyAddedProperties = false;
foreach ($lines as $i => $line) {
$line = trim($line);
if (strncmp($line, '* @property', 11) === 0) {
@ -647,21 +677,44 @@ class PhpDocController extends Controller
$propertyPart = false;
}
if ($propertyPart) {
preg_match('/@property\s+\w+\s+\$([a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*)/', $line, $matches);
if (!isset($matches[1]) || !in_array($matches[1], $manuallyAddedProperties)) {
preg_match(
'/@property(?:-read|-write)?\s+([\\\\\w\|\[\]]+)\s+\$([a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*)/',
$line,
$matches
);
if (isset($matches[2])) {
$lastPropertyName = $matches[2];
}
if (in_array($lastPropertyName, $manuallyAddedProperties)) {
$hasManuallyAddedProperties = true;
} else {
unset($lines[$i]);
}
}
}
if ($properties === '') {
return implode("\n", $lines);
}
// if no properties or other tags were present add properties at the end
if ($propertyPosition === false) {
$propertyPosition = \count($lines) - 2;
}
// if there are properties that were added manually, remove start enclosure
if ($hasManuallyAddedProperties) {
$properties = substr($properties, strlen(self::PROPERTIES_ENCLOSURE));
}
$finalDoc = '';
foreach ($lines as $i => $line) {
$finalDoc .= $line . "\n";
if (!$hasManuallyAddedProperties || $i !== $propertyPosition) {
$finalDoc .= $line . "\n";
}
if ($i == $propertyPosition) {
$finalDoc .= $properties;
}
@ -724,16 +777,17 @@ class PhpDocController extends Controller
'#\* @param (?<type>[\w\\|\\\\\\[\\]]+) \$\w+(?: (?<comment>(?:(?!\*/|\* @).)+?)(?:(?!\*/).)+|[\s\n]*)\*/' .
'[\s\n]{2,}(\#\[\\\\*.+\])*[\s\n]{2,}public function (?<kind>set)(?<name>\w+)\(\$\w+(?:, ?\$\w+ ?= ?[^,]+)*\)#',
$class['content'], true);
// check for @property annotations in getter and setter
$properties = $this->match(
'#\* @(?<kind>property) (?<type>[\w\\|\\\\\\[\\]]+)(?: (?<comment>(?:(?!\*/|\* @).)+?)(?:(?!\*/).)+|[\s\n]*)\*/' .
'[\s\n]{2,}(\#\[\\\\*.+\])*[\s\n]{2,}public function [g|s]et(?<name>\w+)\(((?:,? ?\$\w+ ?= ?[^,]+)*|\$\w+(?:, ?\$\w+ ?= ?[^,]+)*)\)#',
$class['content']);
$acrs = array_merge($properties, $gets, $sets);
$acrs = array_merge($gets, $sets);
$manuallyAddedProperties = self::MANUALLY_ADDED_PROPERTIES[$className] ?? [];
$props = [];
foreach ($acrs as &$acr) {
$acr['name'] = lcfirst($acr['name']);
if (in_array($acr['name'], $manuallyAddedProperties)) {
continue;
}
$acr['comment'] = trim(preg_replace('#(^|\n)\s+\*\s?#', '$1 * ', $acr['comment']));
$props[$acr['name']][$acr['kind']] = [
'type' => $acr['type'],
@ -747,7 +801,6 @@ class PhpDocController extends Controller
ksort($props);
$phpdoc .= " *\n";
foreach ($props as $propName => &$prop) {
$docLine = ' * @property';
$note = '';
@ -777,7 +830,10 @@ class PhpDocController extends Controller
$phpdoc .= $docLine;
}
$phpdoc .= " *\n";
}
if ($phpdoc !== '') {
$phpdoc = self::PROPERTIES_ENCLOSURE . $phpdoc . self::PROPERTIES_ENCLOSURE;
}
return [$className, $phpdoc];

21
framework/base/Model.php
View File

@ -37,13 +37,25 @@ use yii\validators\Validator;
*
* For more details and usage information on Model, see the [guide article on models](guide:structure-models).
*
* @property-read array $errors Errors for all attributes. This is a two-dimensional
* array of errors for all attributes, similar to the following:
*
* ```php
* [
* 'username' => [
* 'Username is required.',
* 'Username must contain only word characters.',
* ],
* 'email' => [
* 'Email address is invalid.',
* ]
* ]
* ```
*
* Empty array if no errors.
* @property-read \yii\validators\Validator[] $activeValidators The validators applicable to the current
* [[scenario]].
* @property array $attributes Attribute values (name => value).
* @property-read array $errors Errors for all attributes or the specified attribute. Empty array is returned
* if no error. See [[getErrors()]] for detailed description. Note that when returning errors for all attributes,
* the result is a two-dimensional array, like the following: ```php [ 'username' => [ 'Username is required.',
* 'Username must contain only word characters.', ], 'email' => [ 'Email address is invalid.', ] ] ```.
* @property-read array $firstErrors The first errors. The array keys are the attribute names, and the array
* values are the corresponding error messages. An empty array will be returned if there is no error.
* @property-read ArrayIterator $iterator An iterator for traversing the items in the list.
@ -585,7 +597,6 @@ class Model extends Component implements StaticInstanceInterface, IteratorAggreg
* Returns the errors for all attributes or a single attribute.
* @param string|null $attribute attribute name. Use null to retrieve errors for all attributes.
* @return array errors for all attributes or the specified attribute. Empty array is returned if no error.
* See [[getErrors()]] for detailed description.
* Note that when returning errors for all attributes, the result is a two-dimensional array, like the following:
*
* ```php

3
framework/base/Module.php
View File

@ -381,9 +381,6 @@ class Module extends ServiceLocator
* Defines path aliases.
* This method calls [[Yii::setAlias()]] to register the path aliases.
* This method is provided so that you can define path aliases when configuring a module.
* @property array list of path aliases to be defined. The array keys are alias names
* (must start with `@`) and the array values are the corresponding paths or aliases.
* See [[setAliases()]] for an example.
* @param array $aliases list of path aliases to be defined. The array keys are alias names
* (must start with `@`) and the array values are the corresponding paths or aliases.
* For example,

5
framework/db/QueryBuilder.php
View File

@ -23,7 +23,10 @@ use yii\helpers\StringHelper;
* For more details and usage information on QueryBuilder, see the [guide article on query builders](guide:db-query-builder).
*
* @property-write string[] $conditionClasses Map of condition aliases to condition classes. For example:
* ```php ['LIKE' => yii\db\condition\LikeCondition::class] ```.
*
* ```php
* ['LIKE' => yii\db\condition\LikeCondition::class]
* ```
* @property-write string[] $expressionBuilders Array of builders that should be merged with the pre-defined
* ones in [[expressionBuilders]] property.
*

5
framework/log/Dispatcher.php
View File

@ -50,8 +50,8 @@ use yii\base\ErrorHandler;
* Yii::$app->log->targets['file']->enabled = false;
* ```
*
* @property int $flushInterval How many messages should be logged before they are sent to targets. This
* method returns the value of [[Logger::flushInterval]].
* @property int $flushInterval How many messages should be logged before they are sent to targets. See
* [[getFlushInterval()]] and [[setFlushInterval()]] for details.
* @property Logger $logger The logger. If not set, [[Yii::getLogger()]] will be used. Note that the type of
* this property differs in getter and setter. See [[getLogger()]] and [[setLogger()]] for details.
* @property int $traceLevel How many application call stacks should be logged together with each message.
@ -107,7 +107,6 @@ class Dispatcher extends Component
/**
* Gets the connected logger.
* If not set, [[Yii::getLogger()]] will be used.
* @property Logger the logger. If not set, [[Yii::getLogger()]] will be used.
* @return Logger the logger.
*/
public function getLogger()

1
framework/log/Target.php
View File

@ -381,7 +381,6 @@ abstract class Target extends Component
/**
* Check whether the log target is enabled.
* @property bool Indicates whether this log target is enabled. Defaults to true.
* @return bool A value indicating whether this log target is enabled.
*/
public function getEnabled()

9
framework/web/Request.php
View File

@ -23,6 +23,9 @@ use yii\validators\IpValidator;
*
* For more details and usage information on Request, see the [guide article on requests](guide:runtime-requests).
*
* @property string|null $hostInfo Schema and hostname part (with port number if needed) of the request URL
* (e.g. `https://www.yiiframework.com`), null if can't be obtained from `$_SERVER` and wasn't set. See
* [[getHostInfo()]] for security related notes on this property.
* @property-read string $absoluteUrl The currently requested absolute URL.
* @property array $acceptableContentTypes The content types ordered by the quality score. Types with the
* highest scores will be returned first. The array keys are the content types, while the array values are the
@ -47,9 +50,6 @@ use yii\validators\IpValidator;
* returned if no such header is sent.
* @property-read array $eTags The entity tags.
* @property-read HeaderCollection $headers The header collection.
* @property string|null $hostInfo Schema and hostname part (with port number if needed) of the request URL
* (e.g. `https://www.yiiframework.com`), null if can't be obtained from `$_SERVER` and wasn't set. See
* [[getHostInfo()]] for security related notes on this property.
* @property-read string|null $hostName Hostname part of the request URL (e.g. `www.yiiframework.com`).
* @property-read bool $isAjax Whether this is an AJAX (XMLHttpRequest) request.
* @property-read bool $isDelete Whether this is a DELETE request.
@ -776,9 +776,6 @@ class Request extends \yii\base\Request
* > If you don't have access to the server configuration, you can setup [[\yii\filters\HostControl]] filter at
* > application level in order to protect against such kind of attack.
*
* @property string|null schema and hostname part (with port number if needed) of the request URL
* (e.g. `https://www.yiiframework.com`), null if can't be obtained from `$_SERVER` and wasn't set.
* See [[getHostInfo()]] for security related notes on this property.
* @return string|null schema and hostname part (with port number if needed) of the request URL
* (e.g. `https://www.yiiframework.com`), null if can't be obtained from `$_SERVER` and wasn't set.
* @see setHostInfo()