Add stub for \Drupal\Core\Field\FormatterInterface

[Niklan]

With the PHPStan level 7 every field formatter starts to reports an error:

  XX     Method Drupal\foo\Plugin\Field\FieldFormatter\FooFormatter::viewElements() has parameter $items with generic interface Drupal\Core\Field\FieldItemListInterface but does not  
         specify its types: T                                                                                                                                                                                                   
         🪪  missingType.generics  

This PR adds a stub for the method that defines each element of $items as an instance of \Drupal\Core\Field\FieldItemInterface.

I'm not sure why the FieldItemListInterface doesn't handle this case. I'm not sure if my solution is the correct one in this case. Maybe it is possible to improve FieldItemListInterface.stub

[mglaman]

We have to do the same in FieldItemListInterface for get

[ceesgeene]

I don't think this PR is correct. Phpstan wants you to specify the generic type. Repeating the interface as a phpdoc param just hides/suppresses the phpstan finding/error.

So e.g. for a link filed formatter in your codebase, you could add:

  /**
    * {@inheritDoc}
    * 
    * @param \Drupal\Core\Field\FieldItemListInterface<\Drupal\link\Field\LinkItem> $items
    */
   public function viewElements(...

This way phpstan knows for example that $item->uri exists.

I think this PR should be reverted. We have serveral Drupal projects (with phpstan level 9) that use this but since this commit their phpstan starts reporting the following error (twice per encounter, not sure why):

Parameter #1 $items (Drupal\Core\Field\FieldItemListInterface<Drupal\***\Plugin\Field\FieldType\***Item>)  
of method Drupal\custom_***\Plugin\Field\FieldFormatter\***Formatter::viewElements()
should be compatible with parameter $items (Drupal\Core\Field\FieldItemListInterface<Drupal\Core\Field\FieldItemInterface>)
of method Drupal\Core\Field\FormatterInterface::viewElements()

This error is incorrect because they are compatible. I think this error is reported because the stub file incorrectly repeats the interface of the generic type.

[Niklan]

I've played more with PHPStan generics recently. I think @ceesgeene is right — it better be reverted. Sorry, I've just started to dig into PHPStan extending and might be doing something wrong. :(

But I still think we need that stub as a generic, so it forces other field formatters to specify their field item types. What do you think?

<?php

namespace Drupal\Core\Field;

/**
 * @template TFieldItemList of \Drupal\Core\Field\FieldItemListInterface
 */
interface FormatterInterface {

  /**
   * @param TFieldItemList $items
   * @param string $langcode
   *
   * @return array<int, array<int|string, mixed>>
   */
  public function viewElements(FieldItemListInterface $items, $langcode): array;

  /**
   * @param TFieldItemList $items
   * @param string $langcode
   *
   * @return array<int|string, mixed>
   */
  public function view(FieldItemListInterface $items, $langcode = NULL);

}

This way, field formatters must explicitly set types for field item lists:

/**
 * @implements FormatterInterface<StringItemList>
 */
class FooFormatter implements FormatterInterface {

But if the field is using another generic FieldItemList, they must be able to specify the type for an item:

/**
 * @implements FormatterInterface<FieldItemList<MyCustomItem>>
 */
class FooFormatter implements FormatterInterface {

If you folks think this should be done, I can prepare another issue/PR to discuss it.

[ceesgeene]

Yes, making the FormatterInterface generic would even be better.

[Niklan]

@mglaman and @ceesgeene

I've made PRs for both suggestions, which basically conflict with each other and depend on the decision of which way to go.

1. Revert FormatterInterface stub:
   • 1.x: Revert "Add stub for \Drupal\Core\Field\FormatterInterface (#822)" (1.x) #845
   • 2.x: Revert "Add stub for \Drupal\Core\Field\FormatterInterface (#822)" (2.x) #844
2. Convert FormatterInterface into a proper generic:
   • 1.x: Make FormatterInterface stub generic #847
   • 2.x: Make FormatterInterface stub generic #846

Personally, I think we should make it a proper generic. The stricter the code, the better, in my opinion. This generic will force formatters to declare their list item types and item types in some cases.

[ceesgeene]

I would revert first and then work on the generic part. The latest version of phpstan-drupal is reporting incorrectly now.