Phpunit Extras Laravel Package

Technical Evaluation

Architecture Fit

• Specialized for Tarantool: The package remains tightly coupled to the Tarantool PHP client and is best suited to teams using Tarantool as a database, cache, or real-time processing layer. v0.3.0 modernizes the test API by replacing annotation-based Lua/SQL/version requirements with PHP attributes, aligning better with PHP 8.2+ codebases.
• Modular Design: Traits such as TestDoubleClient, RequestExpectations, and related expectation helpers still support incremental adoption. Teams can extend Tarantool\PhpUnit\TestCase or selectively use traits for mocking and request assertions.
• Attribute-Driven: The move from annotations to PHP attributes is the most significant architectural change. It improves native PHP metadata support but creates a migration burden for existing suites that use @lua, @sql, or @requires TarantoolVersion.

Integration Feasibility

• Platform Prerequisites Are Stricter: v0.3.0 requires PHP 8.2+ and PHPUnit 10. Projects on PHP 8.0/8.1 or PHPUnit 9 cannot adopt v0.3.0 without a platform upgrade or must remain on the older v0.2.x line.
• Configuration Changes Required: PHPUnit 10 configuration and extension registration must be updated. Teams should revalidate DSN/environment-variable wiring and confirm the current extension class/arguments against v0.3.0 documentation.
• Dependency Alignment: The release updates dependencies, so teams must verify compatibility with their existing tarantool/php client version, ext-msgpack, and Tarantool server version. This is a dev-only Composer dependency, so runtime impact should be limited to test environments.

Technical Risk

• Breaking Upgrade: v0.3.0 is a meaningful breaking release. Annotation-based Lua/SQL setup and version requirements must be converted to PHP attributes; PHPUnit 10 and PHP 8.2 upgrades may also surface unrelated test-suite issues.
• Reduced Staleness Risk, Still Niche: A new release is a positive maintenance signal and lowers the previous stale-maintenance concern, but adoption remains low. Validate fit and be prepared to maintain internally if edge cases arise.
• Tarantool Version Lock-in: Version constraints for Tarantool server/client compatibility remain a risk, especially after dependency updates. Test against the exact Tarantool versions used in CI and production-like environments.
• Mocking Complexity and Performance Overhead: Advanced request mocking still requires familiarity with the package’s expectation builders. Attribute-driven Lua/SQL setup can also slow suites if run before many tests.

Key Questions

1. Platform Readiness: Is the project already on PHP 8.2+ and PHPUnit 10? If not, what is the upgrade timeline?
2. Test Migration Scope: How many tests use annotation-based @lua, @sql, or @requires TarantoolVersion? Who owns the conversion to attributes?
3. Dependency Compatibility: Do the updated package dependencies align with our tarantool/php client, ext-msgpack, and Tarantool server versions?
4. Upgrade vs. Pin: Should we upgrade to v0.3.0, or pin v0.2.x until the PHP/PHPUnit platform upgrade is complete?
5. CI Configuration: Does our CI PHP image, PHPUnit 10 config, and Tarantool service setup match the new requirements?

Integration Approach

Stack Fit

• Primary Use Case: PHP 8.2+ applications using the Tarantool PHP client for database, cache, or real-time interactions.
• Required Tooling: PHP 8.2+, PHPUnit 10, Composer, ext-msgpack, and a compatible Tarantool server for attribute-driven Lua/SQL tests.
• Anti-Patterns: Not appropriate for non-Tarantool test suites or teams unable to move to PHPUnit 10. For simple unit tests, the package adds unnecessary Tarantool-specific setup.

Migration Path

1. Upgrade Platform First: Move test/runtime environments to PHP 8.2+ and PHPUnit 10. Resolve PHPUnit 10 configuration and compatibility issues before adding package changes.
2. Audit Existing Usage: Inventory current @lua, @sql, and @requires TarantoolVersion annotations, plus any AnnotationExtension configuration.
3. Upgrade Package and Config: Require tarantool/phpunit-extras:^0.3 and update PHPUnit 10 extension registration and DSN/environment-variable configuration per v0.3.0 docs.
4. Pilot Attribute Conversion: Convert a small Tarantool test suite from annotations to the new PHP attributes. Validate exact attribute classes and syntax against package documentation.
5. Expand Incrementally: Migrate remaining tests by risk and usage. Use TestDoubleClient/request expectations for isolated tests and attribute-based Lua/SQL setup only where server interaction is required.

Compatibility

• PHP: Requires PHP 8.2+; incompatible with PHP 8.0/8.1.
• PHPUnit: Requires PHPUnit 10; incompatible with PHPUnit 9.
• Tarantool Client: Verify updated tarantool/php constraints against the project’s dependency graph.
• Extensions: Confirm ext-msgpack is installed in all CI and developer environments.
• Tarantool Server: Validate server compatibility with the updated dependency set and any version requirements in tests.
• Backward Compatibility: v0.3.0 is not backward compatible with annotation-based test metadata.

Sequencing

1. Upgrade PHP, PHPUnit, and related Composer dependencies.
2. Update PHPUnit 10 configuration and package extension registration.
3. Pilot-convert annotations to attributes in one Tarantool-focused suite.
4. Run local and CI validation, including Tarantool version checks and ext-msgpack.
5. Migrate remaining tests and document attribute-based patterns.
6. If platform upgrade is blocked, pin v0.2.x temporarily and track the upgrade as technical debt.

Operational Impact

Maintenance

• Coordinated Upgrade Required: v0.3.0 should be treated as a breaking test-infrastructure change, not a drop-in patch. Plan maintenance windows for PHP/PHPUnit upgrade and annotation-to-attribute conversion.
• Dependency Monitoring: Watch for changes in the Tarantool PHP client and PHPUnit 10 ecosystem. The new release reduces stale-maintenance risk but does not eliminate it given low adoption.
• Documentation Update: Internal testing docs must be revised to show PHP attributes, PHPUnit 10 configuration, and Tarantool version constraints.

Support

• Debugging Complexity: Failures may come from attribute syntax, PHPUnit 10 configuration, Tarantool server compatibility, or missing ext-msgpack. Teams need both PHPUnit and Tarantool troubleshooting skills.
• Community Support: Support remains limited. Use GitHub issues and Tarantool PHP community channels, and maintain manual fallbacks for critical tests.
• Fallback Strategy: Keep non-Tarantool or manual test paths for critical cases if CI Tarantool services are unavailable.

Scaling

• Test Suite Runtime: Attribute-driven Lua/SQL setup can slow large suites. Use mocks for non-critical tests and group server-dependent setup where possible.
• Mocking Volume: TestDoubleClient is lightweight for typical cases but may not scale well for high-volume request validation. Validate performance in CI.
• Environment Consistency: More teams will need consistent PHP 8.2+, PHPUnit 10, ext-msgpack, and Tarantool server versions across local and CI environments.

Failure Modes

• PHP or PHPUnit version mismatch blocks adoption.
• Unconverted annotations silently fail or stop providing expected setup.
• PHPUnit 10 extension registration misconfigured or DSN arguments incorrect.
• Tarantool server/client version incompatibility after dependency updates.
• Missing ext-msgpack in CI.
• Lua/SQL setup leaking state across tests or slowing suites materially.
• Request expectation assertions becoming brittle after attribute migration.

Ramp-up

• Teams need familiarity with PHP 8 attributes, PHPUnit 10 configuration, and the package’s Tarantool-specific test patterns.
• Start with a narrow pilot suite and document worked examples before broad migration.
• Budget explicit effort for converting existing annotation-based tests and updating CI images/configuration.