Unable to pass checks with @param using constructor property promotion and readonly parameters

[matthewhilton]

Apologies if this is not the correct place to raise this; It's related to moodlecheck/phpdoc but I can see there is an effort to migrate the moodlecheck/phpdoc checks to this plugin, so i'm logging it here.

I've recently added a class using constructor promotion https://www.php.net/manual/en/language.oop5.decon.php#language.oop5.decon.constructor.promotion and have set the param/property to protected readonly

But this spits out the error Phpdocs for function test::__construct has incomplete parameters list (error).
If you remove the readonly (but leave protected), it passes.

Example class:

<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Test class
 *
 * @package   core
 * @copyright 2024 Matthew Hilton <matthewhilton@catalyst-au.net>
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class test {
    /**
     * Construct
     *
     * @param int $test
     */
    public function __construct(protected readonly int $test) {
    }
}

It looks as though phpdoc says nothing about this either https://docs.phpdoc.org/latest/guide/references/phpdoc/tags/param.html

I tried various combinations e.g. @param-readonly, @property-read but no luck

[andrewnicols]

Hi @matthewhilton ,

As it happens I'm in the process of trying to fix this and related issues.

This particular issue comes from the sister project we're trying to wind down - https://github.com/moodlehq/moodle-local_moodlecheck

Over the next few weeks/months we're trying to move all sniffs from there to this project at which point this issue should go away.

I have also struggled to find an official way to document these, but the consensus I've come across seems to be:

class example {
    /**
     * Constructor.
     *
     * @param string $example The constructor argument
     */
    public function __construct(
        /** @var string The property description */
        public readonly string $example,
    ) {
    }
}

[andrewnicols]

Oh, and the {{@property-read}} class tag is for magic properties.

[andrewnicols]

And see moodlehq/moodle-local_moodlecheck#129 where there's a PR there too.

[andrewnicols]

Some references:

• PSR12/Squiz/PEAR standards all error on promoted properties with docblocks squizlabs/PHP_CodeSniffer#3342
• Parsing error with constructor property promotion and @var docblock phpmd/phpmd#896
• https://phpstan.org/r/a1cc67aa-fd2b-4002-90c3-484b75bffa30
• https://youtrack.jetbrains.com/issue/WI-67277/The-combination-of-PHPDoc-and-promoted-parameters-does-not-work

Note: This syntax does also work with the latest versions of phpdoc.

[stronk7]

I think that this can be safely closed now, as far as both the legacy tool (local_moodlecheck) and this (moodle-cs) are working ok with the readonly keyword.

Plus we already have the @var phpdocs to work with those promoted properties (read only or no) in moodle-cs.

So, proceeding. If there is anything else pending, don't hesitate to ping me here.

Ciao :-)