Allow usage of stdclass instead of object where it makes sense

This has now been implemented in Coder in ✨ stdclass is auto-corrected to object but it should not be Fixed .

Raising priority to major as now the documented coding standards are not in sync with Coder.

Next step: define the wording and necessary changes to coding standards documentation pages in the issue summary.

use the coding standard template

The next step here is to complete the proposed resolution section.

So yeah, we'd need to update this: https://www.drupal.org/docs/develop/standards/php/api-documentation-and-... →

To deal with this:

object (NOT "stdClass")

Adding link to current text and the current text.

Anyone know what 'stdClass' was excluded?

A bit more accurate title

I think I would rather disallow type-hinting with \stdClass at all to resolve this, then it not being allowed in the PhpDoc would not be a problem. Type-hinting on \stdClass seems like bad practice to me and it should be discouraged if it isn’t yet in our standards.

Anyone know what 'stdClass' was excluded?

Seems like this was written in a time when Drupal mostly used anonymous objects and we just wanted to document those as object in the PhpDoc, not as \stdClass. Actual type hints were not allowed in PHP at that time, so the question of a discrepancy between PhpDoc and in-code type hint never arose.
And we probably couldn’t think of a good reason to actually require a \stdClass object instead of any object with the required (public) properties – same as I do now.

I think I would rather disallow type-hinting with \stdClass at all to resolve this, then it not being allowed in the PhpDoc would not be a problem.

I agree, most places where you would need a stdClass to be typehinted should ideally probably be value objects instead, so I think this moves us away from that.

I searched Drupal core for instances of "@.*stdclass" and found 3.

2. https://git.drupalcode.org/project/drupal/-/blob/11.x/core/modules/views...
3. https://git.drupalcode.org/project/drupal/-/blob/11.x/core/modules/image...
4. https://git.drupalcode.org/project/drupal/-/blob/11.x/core/modules/edito...

No consensus on this yet.

Moving to critical because of the discrepancy between what Code does and the standard.

I do not see any reason to type-hint a variable to \stdClass; it seems rather too specific. Using object would allow to change the used class and be backward compatible.

So the difference is the \stdClass is one case where dynamic properties are allowed. I don't think there is a way to typehint the #[AllowDynamicProperties] attribute, however.

https://php.watch/versions/8.2/dynamic-properties-deprecated

The following code does not throw any deprecation warning, on PHP 8.3.

<?php

declare(strict_types=1);

function add_title(object $node, string $title='') {
    $node->title = $title;
    $node->changed = time();
}

error_reporting(E_ALL | E_DEPRECATED);

$node = new stdClass();
$node->nid = 10;

add_title($node, "This is my new node");

The following code will throw deprecation warnings.

<?php

declare(strict_types=1);

class Node {}

function add_title(object $node, string $title='') {
    $node->title = $title;
    $node->changed = time();
}

error_reporting(E_ALL | E_DEPRECATED);

$node = new Node();
$node->nid = 10;

add_title($node, "This is my new node");

PHP Deprecated: Creation of dynamic property Node::$nid is deprecated in /home/avpaderno/.test/test_hinting.php on line 15
PHP Deprecated: Creation of dynamic property Node::$title is deprecated in /home/avpaderno/.test/test_hinting.php on line 8
PHP Deprecated: Creation of dynamic property Node::$changed is deprecated in /home/avpaderno/.test/test_hinting.php on line 9

Pretty sure "object NOT stdClass" is very, very old and was just an attempt to standardise documentation - from when nodes and many other things were stdClass. The intention was not to prevent people using stdClass itself just to refer to things one way.

So it seems reasonable to loosen this if there are use-cases for specifically referencing stdClass.

I guess that \stdClass should be used when the parameter is effectively always an instance of \stdClass.
Now that parameter type-hinting has been completely implemented in PHP, we should use with @param what PHP makes possible to use as parameter type-hinting.