feat: add option to include class name in DocBlock generation

[jackd248]

Summary by CodeRabbit

• New Features

  • Added an option to include the class name in generated PHP DocBlock headers when enabled in configuration.

• Documentation

  • Updated documentation to reflect the new configuration option for adding the class name to DocBlock headers.

• Tests

  • Extended and added tests to ensure correct handling and output of class names in DocBlock headers when the new option is enabled.

[coderabbitai]

Walkthrough

A new feature was introduced to support including the class name in generated PHP DocBlock headers. This involved adding a boolean configuration option (add_class_name) to both the code and documentation, updating the generator and fixer logic to handle class names, and extending the test suites to verify the new behavior and configuration.

Changes

Cohort / File(s)	Change Summary
Documentation Update README.md	Updated configuration examples to document the new add_class_name option, showing its use in both array and object-oriented forms. Corrected the namespace for an enum reference.
DocBlockHeader Generator src/Generators/DocBlockHeader.php	Added a readonly addClassName property to the DocBlockHeader class, updated the constructor and static create method to accept this property, and modified the __toArray method to include the add_class_name key.
DocBlockHeader Fixer src/Rules/DocBlockHeaderFixer.php	Introduced the add_class_name configuration option, updated the control flow to extract the class name after each class keyword, and modified all relevant methods to accept and use the class name when building the DocBlock if the option is enabled. Added a private method for extracting class names from tokens.
DocBlockHeader Generator Tests tests/src/Generators/DocBlockHeaderTest.php	Extended tests to cover the new addClassName property: updated existing tests to expect the new array key, and added tests for creation and serialization with addClassName set to true.
DocBlockHeader Fixer Tests tests/src/Rules/DocBlockHeaderFixerTest.php	Updated all invocations of private methods to include the class name argument. Added comprehensive new tests for building doc blocks with/without class names, extracting class names from tokens, and verifying the fixer’s behavior with the new configuration, including edge cases and multiple classes. Also updated configuration definition tests to expect the new option.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant PHP-CS-Fixer
    participant DocBlockHeaderFixer
    participant DocBlockHeader

    User->>PHP-CS-Fixer: Runs fixer with 'add_class_name' option
    PHP-CS-Fixer->>DocBlockHeaderFixer: applyFix(file, tokens)
    DocBlockHeaderFixer->>DocBlockHeaderFixer: getClassName(tokens, classIndex)
    DocBlockHeaderFixer->>DocBlockHeader: buildDocBlock(annotations, className)
    DocBlockHeader-->>DocBlockHeaderFixer: Returns DocBlock string (with class name if enabled)
    DocBlockHeaderFixer-->>PHP-CS-Fixer: Updates tokens with new DocBlock
    PHP-CS-Fixer-->>User: Outputs fixed file

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

In codey fields where classes hop,
A header blooms atop each crop.
Now with a name, so clear and bright,
Each DocBlock shines in morning light.
The tests all cheer, the docs align—
A bunny’s touch in every line!
🐇✨

Note

⚡️ Unit Test Generation is now available in beta!

Learn more here, or try it out under "Finishing Touches" below.

---

📜 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 fe26f8a and 1cb2cbd.

📒 Files selected for processing (5)

• README.md (2 hunks)
• src/Generators/DocBlockHeader.php (3 hunks)
• src/Rules/DocBlockHeaderFixer.php (5 hunks)
• tests/src/Generators/DocBlockHeaderTest.php (3 hunks)
• tests/src/Rules/DocBlockHeaderFixerTest.php (18 hunks)

🔇 Additional comments (13)

README.md (1)

78-78: LGTM! Documentation correctly reflects the new feature.

The README updates properly document the new add_class_name configuration option in both array and object-oriented styles, and fix the namespace reference for Separate::None.

Also applies to: 102-103

src/Generators/DocBlockHeader.php (1)

38-38: LGTM! Clean implementation of the new addClassName property.

The changes properly add the new boolean property with appropriate defaults, maintain backward compatibility, and follow the existing code patterns.

Also applies to: 48-48, 52-52, 65-65

tests/src/Generators/DocBlockHeaderTest.php (2)

94-94: LGTM! Existing tests updated correctly for new array structure.

The tests properly expect the new add_class_name key with default value of false.

Also applies to: 113-113

---

274-312: LGTM! Comprehensive test coverage for the new addClassName feature.

The new tests verify both the property setting via the factory method and its presence in the array representation, providing good coverage for the feature.

tests/src/Rules/DocBlockHeaderFixerTest.php (3)

76-76: LGTM! Existing test calls updated correctly for new method signatures.

All calls to buildDocBlock and related methods have been properly updated to include the className parameter.

Also applies to: 86-86, 101-101, 118-118, 132-132, 146-146, 163-163

---

181-181: LGTM! Configuration definition tests updated for new option.

The option count and expected option names correctly reflect the addition of add_class_name.

Also applies to: 187-187

---

514-645: LGTM! Excellent comprehensive test coverage for the new className feature.

The new tests thoroughly cover:

• Building DocBlocks with and without class names
• Class name extraction logic including edge cases
• Integration with existing DocBlock processing methods
• Multiple classes scenario

The edge case tests for token parsing demonstrate thorough understanding of the implementation.

src/Rules/DocBlockHeaderFixer.php (6)

84-87: LGTM! New configuration option properly defined.

The add_class_name option is correctly configured with appropriate type checking and default value.

---

110-111: LGTM! Class name extraction and passing integrated cleanly.

The class name is extracted for each class and properly passed to the processing method.

---

118-131: LGTM! Method signature and calls updated consistently.

All method signatures and calls have been properly updated to include the className parameter throughout the call chain.

---

134-154: LGTM! Robust class name extraction implementation.

The getClassName method correctly:

• Skips whitespace tokens after the class keyword
• Returns the first T_STRING token content as the class name
• Handles edge cases by breaking on non-string tokens
• Returns empty string when no class name is found

---

181-224: LGTM! DocBlock processing methods updated correctly.

All private methods (mergeWithExistingDocBlock, replaceDocBlock, insertNewDocBlock) properly accept and pass the className parameter to buildDocBlock.

---

285-320: LGTM! DocBlock building logic well-implemented.

The buildDocBlock method correctly:

• Checks the add_class_name configuration option
• Prepends class name with dot when enabled and class name is not empty
• Adds proper spacing (blank line) between class name and annotations
• Maintains existing logic for empty annotations case

✨ Finishing Touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch class-name

---

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

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Explain this complex logic.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai explain this code block.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and explain its main purpose.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR.
• @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
• @coderabbitai generate unit tests to generate unit tests for this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coveralls]

Pull Request Test Coverage Report for Build 16812193506

Details

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

---

Totals
Change from base Build 16810155041:	0.0%
Covered Lines:	161
Relevant Lines:	161

---

💛 - Coveralls