Stubs Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment (Updated): The atoum/stubs package (v2.7.0) remains a niche tool with no direct Laravel integration, but this release introduces critical updates that may influence adoption decisions:

  • PHP 8.4 Compatibility: Resolves deprecations, making it viable for modern PHP stacks. This reduces technical risk for teams evaluating atoum in PHP 8.4+ environments.
  • Namespace Refactor: Stub classes now reside under @toxicity1985's namespace (\atoum\stubs → \toxicity1985\stubs), which is a breaking change for existing adopters. This aligns with modern PHP practices but introduces migration friction.
  • No Laravel-Specific Features: Still incompatible with Laravel’s testing ecosystem (PHPUnit/PestPHP). Use case remains limited to legacy PHP projects or teams intentionally adopting atoum.

• Fit for Laravel Projects (Unchanged):

  • Indirect Use Cases: Only relevant if atoum is chosen for legacy codebases or domain-specific testing (e.g., non-Laravel PHP services).
  • Opportunity: If atoum is adopted, this package could streamline stub generation, but no Laravel-native benefits exist.

Integration Feasibility (Updated)

• Dependencies (Updated):

  • PHP 8.4 Support: Critical deprecations resolved, eliminating a blocker for modern PHP adoption.
  • Breaking Namespace Change: Existing code using atoum\stubs must update to \toxicity1985\stubs. This is a high-effort migration for adopters with legacy atoum test suites.
  • Atoum Core Dependency: Still requires atoum/atoum (≥5.0.0), which remains the primary integration hurdle for Laravel projects.

• Conflict Risks (Updated):

  • Testing Framework Duplication: Laravel’s ecosystem (PHPUnit/PestPHP) is incompatible with atoum. The namespace change does not resolve this.
  • Tooling Gaps: No IDE/Laravel-specific tooling improvements. The new namespace may complicate IDE autocompletion temporarily.
  • Breaking Change Risk: The namespace refactor is backward-incompatible, requiring manual updates in all test files.

Technical Risk (Updated)

Key Questions for TPM (Updated)

1. Why Atoum? (Unchanged)
   • What pain points justify adopting atoum over PHPUnit/PestPHP?
2. Scope of Adoption (Unchanged)
   • Will atoum be used for all tests or specific modules?
3. Long-Term Viability (Updated)
   • With new contributors and PHP 8.4 support, is atoum now more stable? Monitor activity post-release.
   • Are there Laravel-specific atoum extensions or community plugins? (Still none.)
4. Team Readiness (Updated)
   • Does the team have atoum experience? What’s the ramp-up cost for namespace migration?
5. Alternatives (Unchanged)
   • Could PestPHP or custom stub generators achieve similar goals with lower risk?
6. Namespace Migration Strategy (New)
   • How will the team handle the breaking namespace change in existing tests?
     • Automated search/replace?
     • Gradual migration per test file?
7. PHP Version Support (Updated)
   • Does the team use PHP 8.4+? If so, this release removes a technical barrier.
8. Backward Compatibility (New)
   • If adopting atoum, how will the team handle future breaking changes in stubs?

Integration Approach

Stack Fit (Unchanged)

• Current Laravel Stack: PHPUnit/PestPHP + Laravel Testing helpers.
• Atoum/Stubs Fit:
  • Partial Fit: Atoum can run in Laravel but lacks native integration.
  • Gaps: No Laravel service container support, database testing helpers, or HTTP testing utilities.
• Updates:
  • PHP 8.4 Support: Removes a technical barrier for modern PHP stacks.
  • Namespace Changes: Introduces a breaking change requiring global refactoring in atoum test suites.

Migration Path (Updated)

1. Assessment Phase (Updated)
   • Audit tests for atoum compatibility and namespace usage.
   • Benchmark atoum vs. PHPUnit for a sample suite.
   • Plan namespace migration strategy (automated vs. manual).
2. Pilot Integration (Updated)
   • Namespace Update: Before migrating, replace all atoum\stubs imports with \toxicity1985\stubs in a sandbox.
     • Use sed/Rector for automated updates (if safe).
     • Validate stub functionality post-migration.
   • Option A (Isolated): Create tests/atoum directory with updated namespace imports.
   • Option B (Hybrid): Migrate legacy tests to atoum incrementally, handling namespace changes per file.
3. Tooling Setup (Updated)
   • Add atoum to composer.json (with PHP 8.4 support):

     "require-dev": {
         "atoum/atoum": "^5.0",
         "toxicity1985/stubs": "^2.7.0"  // Updated package name
     }
     

   • Configure CI to run atoum tests with new namespace:

     - run: vendor/bin/atoum -d tests/atoum --namespace "toxicity1985\\stubs"
     

4. Laravel-Specific Workarounds (Unchanged)
   • Custom extensions for Laravel services (e.g., MockEloquentModel) remain necessary.

Compatibility (Updated)

Sequencing (Updated)

1. Phase 1: Proof of Concept (2 weeks) (Updated)
   • Set up atoum in a sandbox with PHP 8.4 and the new namespace.
   • Rewrite 1–2 PHPUnit tests using toxicity1985/stubs v2.7.0.
   • Validate namespace migration effort (automated vs. manual).
   • Assess performance and breaking change impact.
2. Phase 2: Namespace Migration (2 weeks) (New)
   • Update all existing atoum test files to use \toxicity1985\stubs.
   • Automate where possible (e.g., Rector for import updates).
   • Test migrated stubs for functionality.
3. Phase 3: Pilot (4 weeks) (Unchanged)
   • Migrate a non-critical module’s tests to atoum, handling namespace updates.
4. Phase 4: Full Adoption (Unchanged)
   • Gradually replace PHP