Score:1

How do I document union type variables?

ru flag

My module has a class with a union type member variable

/**
 * This is a PHPv8 union type variable that can be a string OR null.
 *
 * @var string|null
 */
protected string|null $myVar;

However, when I run the code sniffer with phpcs --standard=Drupal,DrupalPractice ..., I'm always getting an error like

FILE: MyDummyClass.php
----------------------
FOUND 1 ERROR
----------------------
  46 | ERROR   | Missing member variable doc comment
----------------------

In this special case, I was able to use the nullable shorthand as a workaround

/**
 * This is a PHPv8 union type variable that can be a string OR null.
 *
 * @var string
 */
protected ?string $myVar;

But this workaround only works for one single nullable union. As soon as I use the union operator | in the @var line

/**
 * This is a PHPv8 union type variable that can be a string OR int OR null.
 *
 * @var string|int
 */
protected ?string|int $myVar;

I'm getting the phpcs error message again.

So how do I properly document union type variables, following Drupal practices?

Kevin avatar
in flag
That looks correct to me, is this a case of the linter rules not being updated?
No Sssweat avatar
ua flag
I think so, [according to PHP8](https://php.watch/versions/8.0/union-types) Doc comments aren't needed/necessary anymore.
ru flag
The code works as expected, it is just the phpcs "error" about the doc block. If I remove remove the either the complete docblock or only the `@var` line, the code sniffer throws an error when using Drupal standards.
Jaypan avatar
de flag
I believe all methods are able to be NULL, and therefore don't have that included in the docblock.
ru flag
OK, makes sense for `null`. But there is still the question how to get `string|int` (or any other combination using the pipe character) through the code sniffer.
id flag
Can you confirm the version of Coder in use?
ru flag
Should be the lastest: `PHP_CodeSniffer version 3.7.1 (stable)`, composer outdated doesn't list any available updates
id flag
I mean the Coder version, the thing which contains the rulesets.
Jaypan avatar
de flag
"But there is still the question how to get string|int (or any other combination using the pipe character) through the code sniffer" I'd argue this is a bad practice. Properties should either be empty (null) or contain the value of the type you are storing. If there are multiple types, I'd say you need to reconsider your architecture.
ru flag
Currently using v8.3.13 for coder. I see an update for 8.3.16, but version conflicts with dealerdirect/phpcodesniffer-composer-installer:^1.0 (which is set by drupal itself) prevents me from updating.
id flag
Union types support was added in 8.3.14 https://www.drupal.org/project/coder/releases/8.3.14
id flag
But that could be because Core is still supporting PHP 7.
ru flag
OK, so I'll just sit it out :-) I needed a solution for null, the rest was more kind of an academic question.
I sit in a Tesla and translated this thread with Ai:

mangohost

Post an answer

Most people don’t grasp that asking a lot of questions unlocks learning and improves interpersonal bonding. In Alison’s studies, for example, though people could accurately recall how many questions had been asked in their conversations, they didn’t intuit the link between questions and liking. Across four studies, in which participants were engaged in conversations themselves or read transcripts of others’ conversations, people tended not to realize that question asking would influence—or had influenced—the level of amity between the conversationalists.