feat(helper): Add generic PHPStan annotations to Reflector for typed attribute inference in consumers.

[terabytesoftw]

Pull Request

Q	A
Is bugfix?	❌
New feature?	✔️
Breaks BC?	❌

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f67f5f5 and 5804e9f.

📒 Files selected for processing (1)

• CHANGELOG.md

📜 Recent review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: composer-require-checker / PHP 8.5-ubuntu-latest
• GitHub Check: linter / Super Linter
• GitHub Check: linter / Super Linter

🧰 Additional context used

🧠 Learnings (1)

📓 Common learnings

Learnt from: terabytesoftw
Repo: php-forge/helper PR: 9
File: tests/ReflectorTest.php:289-323
Timestamp: 2026-03-03T13:45:26.874Z
Learning: In the php-forge/helper repository, the Reflector helper's `propertyTypeNames()` method returns type names in a specific order, and tests intentionally use `assertSame` (rather than order-independent assertions) to verify this exact order is preserved for DNF, union, and intersection type declarations.

Learnt from: terabytesoftw
Repo: php-forge/foxy PR: 115
File: tests/Fallback/AssetFallbackTest.php:158-189
Timestamp: 2026-01-23T11:22:07.261Z
Learning: User terabytesoftw prefers not to use aliases when importing classes in PHP. They are comfortable with either fully-qualified class names or direct imports without aliases.

Learnt from: terabytesoftw
Repo: php-forge/support PR: 12
File: src/TestSupport.php:0-0
Timestamp: 2025-08-18T20:13:33.518Z
Learning: User terabytesoftw prefers clean trait-based designs over maintaining backward compatibility wrappers when refactoring utility classes in the php-forge/support project.

Learnt from: terabytesoftw
Repo: php-forge/actions PR: 65
File: .github/workflows/composer-require-checker.yml:80-83
Timestamp: 2025-09-28T15:12:48.345Z
Learning: The user terabytesoftw prefers using floating tags like v1 for third-party actions in GitHub workflows instead of pinning to specific commit SHAs, even when it's a security best practice to pin to immutable commits.

🔇 Additional comments (1)

CHANGELOG.md (1)

3-5: Looks good — changelog versioning and entry are consistent.

0.2.2 Under development correctly avoids the previously duplicated released version, and the new enhancement note is clear and aligned with existing changelog style.

---

📝 Walkthrough

Summary by CodeRabbit

• Enhancements
  • Improved static-analysis/generic annotations for attribute handling to provide better typed attribute inference and IDE support.
• Changelog
  • Updated release heading to 0.2.2 and added an entry describing the new generic annotations.

Walkthrough

Added PHPStan generic annotations to Reflector docblocks (introducing template parameter TAttribute and conditional return shapes) and updated the changelog; no runtime signatures or behavior were changed.

Changes

Cohort / File(s)	Summary
Changelog CHANGELOG.md	Bumped release header to 0.2.2 and added entry: "Enh #10: Add generic PHPStan annotations to Reflector for typed attribute inference".
Reflector docblocks src/Reflector.php	Expanded PHPDoc/PHPStan generics: introduced @template TAttribute, refined parameter types to `class-string

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

🐰
I hopped through docblocks, neat and spry,
Tucked templates where attributes lie,
Static eyes now see with cheer,
Runtime stays the same — no fear!

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding generic PHPStan annotations to the Reflector class for typed attribute inference.
Description check	✅ Passed	The description is related to the changeset, clearly indicating this is a new feature that adds PHPStan annotations without breaking backward compatibility.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature_2

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@CHANGELOG.md`:
- Around line 3-7: Update the duplicate version header in the changelog: change
the "## 0.2.1 Under development" header to a new in-development version (e.g.,
"## 0.2.2 Under development") so it no longer conflicts with the released "##
0.2.1 March 3, 2026" entry; locate the string "## 0.2.1 Under development" in
CHANGELOG.md and edit it to the next appropriate version.

---

ℹ️ Review info

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f4e0d59 and f67f5f5.

📒 Files selected for processing (2)

• CHANGELOG.md
• src/Reflector.php

📜 Review details

🧰 Additional context used

🧠 Learnings (2)

📓 Common learnings

Learnt from: terabytesoftw
Repo: php-forge/helper PR: 9
File: tests/ReflectorTest.php:289-323
Timestamp: 2026-03-03T13:45:26.874Z
Learning: In the php-forge/helper repository, the Reflector helper's `propertyTypeNames()` method returns type names in a specific order, and tests intentionally use `assertSame` (rather than order-independent assertions) to verify this exact order is preserved for DNF, union, and intersection type declarations.

Learnt from: terabytesoftw
Repo: php-forge/foxy PR: 115
File: tests/Fallback/AssetFallbackTest.php:158-189
Timestamp: 2026-01-23T11:22:07.261Z
Learning: User terabytesoftw prefers not to use aliases when importing classes in PHP. They are comfortable with either fully-qualified class names or direct imports without aliases.

Learnt from: terabytesoftw
Repo: php-forge/support PR: 12
File: src/TestSupport.php:0-0
Timestamp: 2025-08-18T20:13:33.518Z
Learning: User terabytesoftw prefers clean trait-based designs over maintaining backward compatibility wrappers when refactoring utility classes in the php-forge/support project.

Learnt from: terabytesoftw
Repo: php-forge/actions PR: 65
File: .github/workflows/composer-require-checker.yml:80-83
Timestamp: 2025-09-28T15:12:48.345Z
Learning: The user terabytesoftw prefers using floating tags like v1 for third-party actions in GitHub workflows instead of pinning to specific commit SHAs, even when it's a security best practice to pin to immutable commits.

📚 Learning: 2026-03-03T13:45:26.874Z

Learnt from: terabytesoftw
Repo: php-forge/helper PR: 9
File: tests/ReflectorTest.php:289-323
Timestamp: 2026-03-03T13:45:26.874Z
Learning: In the php-forge/helper repository, the Reflector helper's `propertyTypeNames()` method returns type names in a specific order, and tests intentionally use `assertSame` (rather than order-independent assertions) to verify this exact order is preserved for DNF, union, and intersection type declarations.

Applied to files:

• src/Reflector.php

🔇 Additional comments (4)

src/Reflector.php (4)

74-77: Well-structured PHPStan generic annotations.

The conditional return type correctly describes the typed behavior based on whether $attribute is provided. This enables proper type inference for consumers.

---

116-120: Correct generic annotation for typed attribute retrieval.

The return type TAttribute|null accurately reflects the method behavior, enabling consumers to get proper type inference when retrieving specific attribute instances.

---

214-217: Appropriate conditional return type for instantiated attributes.

The annotation correctly differentiates between returning list<object> when unfiltered and list<TAttribute> when a specific attribute class is provided.

---

247-250: Consistent annotation pattern with classAttributes.

The PHPStan annotation follows the same conditional type pattern, providing symmetric behavior for property-level attribute retrieval.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (fed86d5) to head (5804e9f).
⚠️ Report is 2 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@             Coverage Diff             @@
##                main       #10   +/-   ##
===========================================
  Coverage     100.00%   100.00%           
  Complexity        63        63           
===========================================
  Files              5         5           
  Lines            164       164           
===========================================
  Hits             164       164           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.