Problem/Motivation

Seven typed data docblocks describe a value that can be "the name of the property or the delta of the list item", but type it as a string only:

  • TypedDataManagerInterface::getPropertyInstance(), $property_name: string
  • TypedDataManagerInterface::create(), $name: string
  • TypedDataInterface::createInstance(), $name: string|null
  • TypedDataInterface::setContext(), $name: string|null
  • TraversableTypedDataInterface::onChange(), $name: string
  • TypedData::__construct(), $name: string
  • TypedData::$name: string

PHPStan reports them but core's baseline ignores them.

Steps to reproduce

NA

Proposed resolution

Update types to account for int

Remaining tasks

Review

User interface changes

NA

Introduced terminology

NA

API changes

NA

Data model changes

NA

Release notes snippet

NA

Issue fork drupal-3640003

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

Comments

dries created an issue. See original summary.

dries’s picture

Issue summary: View changes
Status: Active » Needs review
Issue tags: +Documentation

The MR adds int to the seven types and removes both baseline entries from .phpstan-baseline.php.

smustgrave’s picture

Issue summary: View changes

Question on core/lib/Drupal/Core/TypedData/TypedData.php would an int in $name for getPropertyPath be a delta?

dries’s picture

@smustgrave Yes. When the data is an item of a list, its $name is the item's delta, which is an integer.

This is documented in lines 107 to 115 of TypedDataInterface.php: "If the data is an item of a list, the name is the numeric position of the item in the list, starting with 0."

The MR brings the other docblocks in line with that one.

smustgrave’s picture

Status: Needs review » Reviewed & tested by the community
Issue tags: +Needs Review Queue Initiative

I see thanks for clarifying!

dries’s picture

Thanks for the review and RTBC.

To be honest, this part of the typed data API feels a bit off to me.

Today, every piece of typed data carries a $name that basically means different things depending on what holds the item. In a map it's a property name, a string. In a list it's a position, an int. Hence why the type has to be string|int. And anything that uses $name has to know which case it's in. I ran into this when working on #3627328: ListNormalizer does not provide a JSON Schema for lists, which let me to open this issue.

This design comes with some strange workarounds or overhead. For example, when an item is removed from a list, every item after it has to move up one place. ItemList::rekey() exists to "repair" the list after removeItem(). See lines 158-166 of ItemList.php. setContext() in that snippet updates $name.

I feel a better and more standard approach would be to let the container own the keys. A map should know the names of its properties, and a list should know the position of each of its items. Then a map would return a string and a list an integer, each with a single type, and removing an item from a list would not require re-numbering.

Needless to say, that is beyond the scope of this issue. :-) I'm guessing, but it's probably not that hard to change technically. The hardest part would be managing the BC, but it might still be doable. If people think it's worth it, we could give it a shot.

Until then, this MR corrects the docblocks.

smustgrave’s picture

I’m the worst judge but maybe something to aim for before 13?