apie/phpunit-matrix-data-provider
PHPUnit data provider that generates a matrix of test cases across multiple PHP and Laravel versions in one go. Configure your supported version combinations and let it fan tests out automatically, keeping compatibility suites DRY and every run clearly labeled by environment.
Architecture fit. The package is a narrow, dev-only utility: it supplies PHPUnit data providers that generate the Cartesian product of input arrays so a single test method can be exercised against every combination of parameters. It occupies the same layer as PHPUnit itself — it does not touch runtime application code, service providers, config, or the HTTP kernel. For a Laravel codebase this means it is architecturally inert: zero production surface, zero coupling to framework internals, and no bootstrapping concerns. It fits where teams already have parameterised tests for pricing rules, validation matrices, permission/role/tenant permutations, feature-flag combinations, or multi-tenant configuration — the classic Laravel cases where hand-written provider arrays become unmaintainable.
Integration feasibility. Integration is a single composer require --dev plus imports in test classes. There is no Laravel service provider, no publishable config, no migration. The practical work is not installation but adoption discipline: deciding which test suites should use combinatorial providers, enforcing caps on the generated row count, and ensuring named data sets (so PHPUnit failure output stays readable). Feasibility is high technically and low organisationally — it requires no platform team involvement.
Technical risk. The dominant risk is project health, not code quality. 0 stars, 0 dependents, and a single-maintainer profile mean abandonment risk is material and effectively unmitigated by community scrutiny. The second risk is PHPUnit's data-provider API churn: PHPUnit 10 deprecated annotation-based providers in favour of attributes, and the DataProvider interface plus static-provider requirements have shifted repeatedly across 10/11/12. A provider-composition helper is directly in the blast radius of those changes. Third, Pest-based suites (increasingly common in Laravel) use PHPUnit providers under the hood but with different ergonomics; compatibility should be verified, not assumed. Fourth, combinatorial explosion is a self-inflicted DoS on CI: five arrays of six values is ~7,800 cases, each potentially booting a Laravel application in a feature test.
Key questions.
#[DataProvider]) and static provider methods required by PHPUnit 10+?RefreshDatabase / DB transactions at the claimed case volumes?Stack fit. Requires require-dev only — never require. It sits alongside phpunit/phpunit, mockery, laravel/pint, and pestphp/pest if present. Confirm the installed PHPUnit constraint is satisfied before adding; if the project is on PHPUnit 10+ and the package predates attribute support, treat this as a blocker rather than a workaround.
Migration path. There is nothing to migrate. Existing hand-written @dataProvider / #[DataProvider] methods stay as they are; adoption is incremental and per-test. Recommended path: (1) add as a dev dependency in a throwaway branch, (2) convert one or two high-value, low-cardinality providers (e.g. a validation rule matrix), (3) measure suite runtime delta, (4) establish a written convention before broad rollout. If the package proves unmaintained, the fallback is a ~30-line internal helper that does the same nested-loop product — this should be the explicit exit plan, and the internal helper is a credible first choice if the team is risk-averse.
Compatibility. Verify three axes: PHPUnit major version, PHP version, and test runner (PHPUnit vs Pest). Also verify interaction with Laravel's database concerns — RefreshDatabase and DatabaseTransactions interact poorly with thousands of cases, so matrix-generated tests should be biased toward unit tests and pure-function feature tests rather than full HTTP/DB journeys.
Sequencing. Dev dependency and compatibility spike first (half a day); single-team pilot on one test file second; convention and cardinality guardrails third; broader adoption last. Do not gate a release on this package, and do not add it in the same change set as a PHPUnit upgrade — separate the variables.
Maintenance. Low ongoing effort if adopted narrowly: the package is a thin abstraction with no runtime footprint, so there is no patching treadmill beyond keeping it aligned with PHPUnit upgrades. The real maintenance cost is ownership ambiguity — with 0 stars and 0 dependents there is no community to absorb fixes, so the using team effectively owns it. Budget a fork-or-replace decision at each PHPUnit major upgrade.
Support. No meaningful support channel. Escalation is "read the source," which is viable only because the surface is small. Document this expectation up front so no one files an issue and waits.
Scaling. Scales well in expressiveness and poorly in runtime. The Cartesian product grows multiplicatively; a modest change to one input array can triple CI minutes without any visible diff in the test file. Mitigate with an explicit per-provider row cap, pairing strategies (all-pairs) for large dimensions, and keeping matrix tests in fast unit suites. Team-wide, the scaling constraint is cognitive: matrix providers make it easy to generate thousands of cases nobody has reasoned about, which trades debugging cost for authoring convenience.
Failure modes. (a) Silent abandonment — package stops working after a PHPUnit major bump, blocking suite upgrades at the worst moment; (b) CI time blow-up from an innocuous input addition; (c) unreadable failures when generated cases lack descriptive names, turning a red build into a manual bisect; (d) false confidence — combinatorial coverage is not equivalence-class coverage, and teams may mistake volume for rigor; (e) Pest or attribute-syntax incompatibility discovered late. All are cheap to detect with a pilot and a naming convention, expensive to discover in a release crunch.
Ramp-up. Very low for individual engineers — the concept is one paragraph and the API is a function call. The non-obvious part is judgement: knowing when a matrix is the right tool versus equivalence classes or a handful of hand-picked cases. That is a short internal write-up plus one worked example, not training. Realistic estimate: an hour for a developer to be productive, half a day for a team to standardise.
Overall recommendation. Adopt only as a require-dev convenience in a pilot, behind an explicit fork-if-abandoned contingency, with row caps and named cases mandated by convention. The technical risk is negligible; the supply-chain and CI-runtime risks are the ones worth managing. If the team already has a lightweight internal data-provider helper, the marginal value here is close to zero — this package's honest competition is thirty lines of code the team owns outright.
How can I help you explore Laravel packages today?