Closes #5451: Replace @var annotations with assert()

[kevdevlu]

Description

#5451 : I can't find exactly what about PHPStan 2.1.45 caused the errors from the issue:

 ------ ------------------------------------------------------------------------------------------------------------------------------- 
  Line   web/profiles/custom/az_quickstart/modules/custom/az_accordion/src/Plugin/Field/FieldFormatter/AZAccordionDefaultFormatter.php  
 ------ ------------------------------------------------------------------------------------------------------------------------------- 
  98     PHPDoc tag @var with type Drupal\az_accordion\Plugin\Field\FieldType\AZAccordionItem is not subtype of native type             
         Drupal\Core\Field\FieldItemInterface.                                                                                          
         🪪  varTag.nativeType                                                                                                          
 ------ ------------------------------------------------------------------------------------------------------------------------------- 
* same error occurs also for AZRankingItem and AZCardItem

Even though AZAccordionItem, AZRankingItem, and AZCardItem all correctly extend FieldItemBase, it seems PHPStan 2.x couldn't confirm the relationship at analysis time. Either that or it became stricter against inline @var's OR on usage of its lie detector.

But in general it seems PHPStan 2.x discourages use of inline @var's:

PHPStan 2.0 validates the inline @var tag type against the native type of the assigned expression. It finds the lies spread around in @var tags:

I’d like the PHP community to use inline @var tags less and less over time. There are many great alternatives that promote good practices and code deduplication...

And here:

Casting a type using an inline @var PHPDocs should be used only as a last resort. It can be used in a variable assignment like this

It also says:

If you really need to use an inline @var, consider an alternative - an assert() call, which can throw an exception at runtime, so the code execution doesn’t continue if the requirements aren’t met.

Similar (though maybe not exact) issue here says they solved it using assert() statements: https://drupal.stackexchange.com/questions/321256/phpstan-2-vartag-type-phpdoc-tag-var-with-type-userbundle-is-not-subtype-of-ty#:~:text=Sorted%20by:,asserted%20or%20checked%20with%20instanceof%20.

So this PR changes them to assert() statements, but this means we need to make sure the paragraph types in question: az_card, az_ranking, az_accordion, and az_publication don't break at runtime. I've done the tests below on these paragraph types and have found no errors so far.

For this:

 ------ -------------------------------------------------------------------------------------------------------------------------------- 
  Line   web/profiles/custom/az_quickstart/modules/custom/az_publication/src/Plugin/Field/FieldWidget/AZEntityRoleInlineFormComplex.php  
 ------ -------------------------------------------------------------------------------------------------------------------------------- 
  97     Access to an undefined property Drupal\Core\Field\FieldItemInterface::$entity.                                                  
         🪪  property.notFound                                                                                                           
         💡  Learn more: https://phpstan.org/blog/solving-phpstan-access-to-undefined-property                                           
 ------ -------------------------------------------------------------------------------------------------------------------------------- 

assert($item instanceof AZEntityRoleReferenceItem); resolves the undefined property error because AZEntityRoleReferenceItem extends EntityReferenceItem and the phpstan-drupal stub for EntityReferenceItem declares
@property ?T $entity: https://github.com/mglaman/phpstan-drupal/blob/main/stubs/Drupal/Core/Field/Plugin/Field/FieldType/EntityReferenceItem.stub

Release notes

Related issues

How to test

Test by Running PHPStan

1. Clone fresh copy of az_quicsktart repo
2. Switch to this branch
3. Build locally with lando or ddev
4. Run lando phpstan or ddev phpstan
5. Confirm there are no errors

ALSO test az_accordion, az_card, az_ranking, az_publication:

az_accordion, az_card, az_ranking — all go through the same scenarios in their respective formatters:

1. View a page that renders the paragraph type - confirm it displays correctly
2. Create/edit a node with that paragraph - save and re-view it
3. If any items have optional fields (e.g. card with no image, accordion with no body) - verify empty/partial items render without errors

az_publication (AZEntityRolelnlineFormComplex) — the assert is in prepareFormState, which runs when the widget initializes:

1. Edit a publication that has existing contributors — confirm the inline entity form loads
2. Add a new contributor to a publication and save
3. Remove a contributor and save

How to check for failures:
If an assert () fails you'll see a PHP fatal AssertionError in the Drupal error log (/admin/reports/dblog). If pages render and forms save normally, the assertions are passing as expected.

Types of changes

Arizona Quickstart (install profile, custom modules, custom theme)

• Patch release changes
  • Bug fix
  • Accessibility, performance, or security improvement
  • Critical institutional link or brand change
  • Adding experimental module
  • Update experimental module
• Minor release changes
  • New feature
  • Breaking or visual change to existing behavior
  • Upgrade experimental module to stable
  • Enable existing module by default or database update
  • Non-critical brand change
  • New internal API or API improvement with backwards compatibility
  • Risky or disruptive cleanup to comply with coding standards
  • High-risk or disruptive change (requires upgrade path, risks regression, etc.)
• Other or unknown
  • Other or unknown

Drupal core

• Patch release changes
  • Security update
  • Patch level release (non-security bug-fix release)
  • Patch removal that's no longer necessary
• Minor release changes
  • Major or minor level update
• Other or unknown
  • Other or unknown

Drupal contrib projects

• Patch release changes
  • Security update
  • Patch or minor level update
  • Add new module
  • Patch removal that's no longer necessary
• Minor release changes
  • Major level update
• Other or unknown
  • Other or unknown

Checklist

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• All new and existing tests passed.
• My change requires release notes.

[az-digital-bot]

Tugboat has finished building the preview for this pull request!

Link:

• https://pr5464-m6twpwxu6muhkv9so6qtt0k76syggdiv.tugboatqa.com

Dashboard:

• https://dashboard.tugboatqa.com/69d03c90d5d87f969e1b80e7

[joeparsons]

I think my only concern would be exceptions / warnings getting triggered by assert() but I guess that is not likely since these formatters are tied to specific field types.