test: improve coverage and CI setup

[davebarnwell]

This PR refreshes the project in three connected areas: automated quality checks, test coverage, and developer-facing documentation. The original problem was not just that the test suite was thin, but that the repository also lacked a modern pull request workflow story and the public docs no longer presented the package as clearly as they should.

From a maintenance perspective, the effect was that important behavior in the base model class was either untested or only lightly exercised, one of the existing tests depended on state left behind by earlier tests, and the repository landing page still pointed at older build tooling rather than the actual GitHub Actions workflow. That combination made the package harder to trust for contributors and less compelling for new users evaluating it.

The root causes were straightforward: the codebase had not been revisited in a while, so the tests had not kept pace with the model surface area, PHPUnit coverage configuration had not been modernized, and the documentation had gradually mixed package messaging with contribution workflow details. The result was a repository that worked, but did not advertise or verify itself as strongly as it should.

The testing changes stabilize the suite by resetting table state before each test and expand coverage around model state helpers, magic accessors, delete flows, snake_case and CamelCase dynamic finder variants, explicit primary-key inserts, and utility helpers. The branch also adds the PHPUnit source filter so coverage reporting works with current PHPUnit versions, and corrects the find() docblock signature plus the test-model annotations required for clean static analysis.

The CI changes update the existing GitHub Actions workflow rather than replacing it outright. Static analysis and formatting now run once in a dedicated quality job, while database-backed PHPUnit runs continue in a matrix across PHP 8.3 and 8.4 with MySQL and PostgreSQL. Service health checks and explicit readiness failures were added so database startup problems fail clearly instead of producing less useful downstream test errors.

The documentation changes are broader than a simple badge update. The README is now more package-facing and promotional, with a cleaner explanation of what the ORM offers, a tighter quick-start path, and clearer feature framing. Contributor process material has been moved into a dedicated CONTRIBUTING.md with setup instructions, validation commands, pull request expectations, and standard contribution terms. A new EXAMPLE.md has also been added and linked from the README so users can jump straight from overview to example-led usage for common model flows.

Validation was done locally against PostgreSQL. The updated suite now runs as 15 tests and 76 assertions, and with Xdebug enabled it reports 81.53% line coverage and 73.08% method coverage for src/Model/Model.php. I also reran PHPStan and the PHP-CS-Fixer dry run successfully. The MySQL path was not rerun locally because the MariaDB container on this machine is not publishing port 3306 to the host, so the MySQL validation for this branch is expected to come from the GitHub Actions matrix.

[Copilot]

Pull request overview

This PR improves the repository's automated quality checks, test coverage, and developer-facing documentation for the Freshsauce\Model\Model ORM package.

Changes:

• Tests & coverage: Adds setUp() to truncate the table before each test (ensuring isolation), introduces a createCategory() helper, and adds 8 new test methods covering model state helpers, magic accessors, record lifecycle, snake_case/CamelCase dynamic finders, explicit PK inserts, utility helpers, and unknown method dispatch.
• CI & tooling: Adds a dedicated quality job for static analysis and formatting, adds service-level health checks for both MySQL and PostgreSQL, adds explicit failure messages when databases don't start, and adds coverage: none to the test job.
• Documentation: Rewrites README.md as a package-facing landing page, adds EXAMPLE.md with end-to-end usage snippets, and expands CONTRIBUTING.md with structured setup instructions and contribution terms. Also corrects the find() docblock's @param type and adds PHPDoc method annotations to the test Category model.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/Model/CategoryTest.php	Adds setUp() for test isolation, helper method, and 8 new test methods covering expanded model surface area
test-src/Model/Category.php	Adds PHPDoc @method annotations for snake_case dynamic finders
src/Model/Model.php	Corrects find() docblock @param from string to int|string
phpunit.xml.dist	Adds <source> filter pointing at src/ to enable modern PHPUnit coverage reporting
README.md	Rewrites as a promotional, package-facing page with quick start, feature overview, and links
EXAMPLE.md	New file with example-led usage for all common model flows
CONTRIBUTING.md	Expands contributor guide with structured setup, validation commands, and contribution terms
.github/workflows/ci.yml	Adds quality job, service-level DB health checks, and explicit readiness failure messages

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.