Sitelet https://web.archive.org/web/20200828233656/https://github.com/yiisoft/yii2/issues/16077
Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[PHPDoc] Tag @property-read @property-write usage #16077

Open
frontbear opened this issue Apr 10, 2018 · 2 comments
Open

[PHPDoc] Tag @property-read @property-write usage #16077

frontbear opened this issue Apr 10, 2018 · 2 comments

Comments

@frontbear
Copy link
Contributor

@frontbear frontbear commented Apr 10, 2018 •

According to http://manual.phpdoc.org/HTMLframesConverter/default/

@property shows a "magic" property variable that is found inside the class.

The property is presumed to be available for both read and write operations. If the property is read-only, you should use the @property-read tag instead. If the property is write-only, use @property-write.

Example:

/**
 * show off @property, @property-read, @property-write
 *
 * @property mixed $regular regular read/write property
 * @property-read int $foo the foo prop
 * @property-write string $bar the bar prop
 */
class Magician
{
    private $_thingy;
    private $_bar;
 
    function __get($var)
    {
        switch ($var) {
            case 'foo' :
                return 45;
            case 'regular' :
                return $this->_thingy;
        }}
 
    function __set($var, $val)
    {
        switch ($var) {
            case 'bar' :
                $this->_bar = $val;
                break;
            case 'regular' :
                if (is_string($val)) {
                    $this->_thingy = $val;
                }}}
}

For Yii usage:

Before:

/**
 * Application is the base class for all application classes.
 *
 * @property \yii\i18n\Formatter $formatter The formatter application component. This property is read-only.
 * @property \yii\i18n\I18N $i18n The internationalization application component. This property is read-only.
 * @property \yii\log\Dispatcher $log The log dispatcher application component. This property is read-only.
 * @property array $container Values given in terms of name-value pairs. This property is write-only.
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @since 2.0
 */
abstract class Application extends Module
{
 ...
}

After:

/**
 * Application is the base class for all application classes.
 *
 * @property-read \yii\i18n\Formatter $formatter The formatter application component.
 * @property-read \yii\i18n\I18N $i18n The internationalization application component.
 * @property-read \yii\log\Dispatcher $log The log dispatcher application component.
 * @property-write array $container Values given in terms of name-value pairs.
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @since 2.0
 */
abstract class Application extends Module
{
 ...
}
@rob006
Copy link
Member

@rob006 rob006 commented Apr 10, 2018

#10989

@cebe
Copy link
Member

@cebe cebe commented Apr 10, 2018 •

#10989 (comment) ;)

We had this already. The reason we changed it was missing IDE support. So we need to find out if situation has changed.

@samdark samdark assigned samdark and unassigned samdark Apr 12, 2018
@samdark samdark added this to the infrastructure milestone Apr 12, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
4 participants
You can’t perform that action at this time.