Refactor: Complete Project Overhaul for Quality, Testing, and DX #2
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
feat: Enhance HtmlTag and attribute handling - Complete HtmlTag::setName to preserve children. - Add boolean, data, and ARIA attribute helpers to Attributes trait. - Implement appendChild and prependChild in HtmlTag. - Add toggle method to HtmlClass. - Update HtmlTag::toDomNode for robust child and attribute handling. - Add AdvancedUsage example file. - Update README with new features and documentation.
This major update refactors the core rendering engine, introduces a full test suite, and sets up automated testing. - **Refactor**: The `HtmlTag` class is now decoupled from the `DOMElement` state. It uses internal, state-driven properties (`$tagName`, `$attributes`, `$values`), which simplifies logic and makes rendering more predictable. - **Test**: A comprehensive PHPUnit test suite has been added, providing coverage for all Node types (`HtmlTag`, `HtmlText`, `EscapedText`, `HtmlTagMulti`) and the `HtmlClass` utility. This ensures code stability and prevents future regressions. - **CI**: A new GitHub Actions workflow (`tests.yml`) has been set up to automatically run the test suite on every push and pull request, ensuring code quality is maintained. - **Docs**: Improved PHPDoc blocks across the source code for better readability and maintainability.
This major update refactors the entire PhpTagMaker library to improve code quality, enhance developer tooling, and increase overall robustness and reliability.
CODE QUALITY & ROBUSTNESS:
Implemented stricter typing across the entire codebase using list and specific array shapes, making the code more predictable and easier to analyze.
Resolved all issues identified by PHPStan at level 8, fixing potential bugs and type mismatches.
Added logic to prevent adding children to HTML void elements (e.g., <img>, <br>), throwing a LogicException to enforce correct usage.
Fully commented all classes and methods in English to improve readability and maintainability.
DEVELOPMENT & TESTING:
Enhanced composer.json with dedicated scripts for testing (test), coverage (test:coverage), static analysis (analyse), and code style (cs, cs-fix).
Updated the testing suite to be more reliable. Key tests now inspect the generated DOM structure directly instead of comparing brittle HTML strings, resolving XML parsing errors.
Configured PHP-CS-Fixer to run on newer PHP versions (8.4+).
Updated the GitHub Actions workflow (tests.yml) to run jobs on a matrix of PHP versions (8.0-8.3) and to include static analysis and code style checks.
DOCUMENTATION & CONFIGURATION:
Created a comprehensive README.md file with detailed installation instructions, API documentation, security guidelines, and a contribution guide.
Added a LICENSE file (GPL-3.0-only) to the project root.
Improved the .gitignore file to cover more common files and directories.
Simplified comments, added conditional Composer update for PHP <8.2, and improved static analysis to include tests directory. Workflow now runs more efficiently and checks code style and static analysis only on PHP 8.3.
The workflow matrix now starts from PHP 8.1, reflecting the minimum version required by PHPUnit 10. Composer dependencies are installed consistently using 'composer install' across all jobs, and additional comments were added for clarity.
Replaces inconsistent whitespace and blank lines in the HtmlTagTest.php test file to improve code formatting and readability.
Cleaned up formatting by deleting an extra blank line in the HtmlTagTest.php file.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This pull request introduces a comprehensive overhaul of the PhpTagMaker library, focusing on enhancing code quality, improving the development experience (DX), and ensuring the project is robust, reliable, and maintainable.
All CI checks are now passing, including unit tests, static analysis, and code style validation across multiple PHP versions.
Key Changes Implemented:
Code Quality & Robustness
Stricter Typing: Implemented stricter type hints across the entire codebase (e.g., list, array<key, value>) to improve code integrity and allow for better static analysis.
Error Handling: Added logic to prevent adding children to HTML void elements (e.g.,![]()
,
), which now throws a LogicException.
Bug Fixes: Resolved all issues identified by PHPStan (level 8), including potential null pointer exceptions, incorrect type hints, and inconsistent method signatures.
Code Readability: Added comprehensive English comments and PHPDoc blocks to all classes and methods.
Development Experience & CI/CD
Enhanced composer.json: Added dedicated scripts for test, test:coverage, analyse, and cs-fix.
CI Workflow (tests.yml):
Tooling Configuration:
Testing Suite
Reliable Assertions: Refactored critical tests in HtmlTagTest.php to inspect the generated DOM objects directly instead of comparing brittle HTML strings. This resolves all XML parsing errors and makes the tests more robust.
Full Coverage: All tests are now passing successfully, ensuring all core functionalities are working as expected.
Documentation
Comprehensive README.md: Created a new, detailed README.md with sections for installation, security guidelines, API documentation, and a full contributing guide.
LICENSE File: Added the GPL-3.0-only license file to the project root.
.gitignore: Updated the .gitignore file to be more comprehensive.
This PR brings the project to a production-ready state, making it easier to maintain and contribute to in the future.