fix: enhance DocBlock handling for attributes in DocBlockHeaderFixer

[jackd248]

Summary by CodeRabbit

• Bug Fixes

  • Improved handling of documentation blocks when PHP 8+ attributes are present. DocBlocks are now correctly positioned before attributes rather than between attributes and class declarations, ensuring proper document structure.

• Tests

  • Added comprehensive test coverage for documentation block positioning with PHP 8+ attributes, including scenarios with parameterized attributes, multiple attribute declarations, and existing documentation blocks.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

Introduced backward-scanning logic to DocBlockHeaderFixer that correctly handles PHP 8+ attributes when locating existing DocBlocks and determining insertion points. The change adds attribute context tracking to skip attribute content during backward traversal and removes attribute tokens from structural modifier checks.

Changes

Cohort / File(s)	Summary
Attribute-aware DocBlock scanning src/Rules/DocBlockHeaderFixer.php	Modified backward-scanning logic in findExistingDocBlock() and findInsertPosition() to track and skip PHP attribute blocks (delimited by ] and T_ATTRIBUTE tokens). Removed ATTRIBUTE token from structural modifier keyword checks.
Attribute-related test coverage tests/src/Rules/DocBlockHeaderFixerTest.php	Added five new test methods covering parameterized attributes, multiple attributes, and interactions between DocBlocks and attributes: testFindInsertPositionWithAttributeWithParameters, testApplyFixAddsDocBlockBeforeAttribute, testFindInsertPositionWithMultipleAttributes, testFindExistingDocBlockWithAttributesBetween, testFindExistingDocBlockBetweenAttributes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20–30 minutes

• Focus areas:
  • Attribute context state management logic in backward scanning (ensure proper enter/exit via ] and T_ATTRIBUTE tokens)
  • Verify that existing DocBlock detection still works correctly when attributes are present between DocBlock and class
  • Confirm attribute content is properly excluded from structural modifier checks
  • Validate test coverage for edge cases (parameterized attributes, multiple attributes, attribute-DocBlock interactions)

Possibly related PRs

• test: add unit tests for Separate enum and DocBlockHeader generator #2: Directly addresses attribute handling behaviors in findInsertPosition() and findExistingDocBlock(), with corresponding test methods in the same PR.

Poem

🐰 Attributes once tangled the scanner's delight,
But backward we'd skip them, now parsing feels right!
With ] and T_ATTRIBUTE in tracking's embrace,
DocBlocks find their true place, no more attribute trace. 🎯

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch attribute-fix

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 639fd98 and 4be76f5.

📒 Files selected for processing (2)

• src/Rules/DocBlockHeaderFixer.php (3 hunks)
• tests/src/Rules/DocBlockHeaderFixerTest.php (1 hunks)

---

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.}

[coveralls]

Pull Request Test Coverage Report for Build 19901930390

Details

• 21 of 21 (100.0%) changed or added relevant lines in 1 file are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 100.0%

---

Totals
Change from base Build 19881431372:	0.0%
Covered Lines:	283
Relevant Lines:	283

---

💛 - Coveralls