Foundry Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • Test Data Generation: Aligns perfectly with Laravel’s testing ecosystem (PHPUnit, Pest) by providing a declarative, expressive way to define and generate test fixtures. Reduces boilerplate in create()/factory() methods.
  • Symfony/Doctrine Compatibility: Leverages Symfony’s StatefulInterface and Doctrine’s ORM, making it a natural fit for Laravel applications using Eloquent (which is Doctrine-based under the hood).
  • Auto-Completion: Reduces manual fixture setup by auto-generating related models (e.g., User → Post → Comment chains) with minimal configuration.
  • State Management: Supports stateful fixtures (e.g., hasPublishedPost(), hasDraftPost()), improving test isolation and readability.
  • Performance: Optimized for on-demand fixture generation, avoiding global state pollution (unlike traditional Factory classes that may cache or seed globally).

• Potential Gaps:

  • Laravel-Specific Features: While Doctrine-compatible, some Laravel-specific traits (e.g., HasFactory, Faker integration) may require customization or wrappers.
  • Migration Testing: Limited built-in support for database migrations (e.g., testing schema changes). May need integration with tools like laravel-shift/database.
  • Non-Doctrine Models: If the app uses non-Doctrine models (e.g., custom collections, non-ORM entities), Foundry’s auto-completion may not apply.

Integration Feasibility

• High: Foundry is designed for PHP/Symfony/Doctrine ecosystems, and Laravel’s Eloquent is a subset of Doctrine. Integration points include:
  • Replacing or extending Laravel’s built-in Factory classes (e.g., User::factory()).
  • Using Foundry’s Loader to register fixtures in tests/TestCase or a dedicated FixtureServiceProvider.
  • Leveraging Foundry’s State system for complex test scenarios (e.g., user roles, soft-deleted records).
• Customization Needs:
  • Wrap Foundry’s Factory in a Laravel-friendly facade or trait (e.g., HasFoundry).
  • Adapt Foundry’s State to Laravel’s testing conventions (e.g., createWithStates() helper).
  • Handle potential conflicts with Laravel’s DatabaseMigrations or RefreshDatabase traits.

Technical Risk

• Low to Medium:
  • Dependency Risk: Foundry is MIT-licensed and actively maintained (last release 2026). Risk of breaking changes is mitigated by its focus on stability.
  • Learning Curve: Developers familiar with Laravel’s Factory will adapt quickly, but Foundry’s stateful approach may require rethinking test organization.
  • Performance: Auto-completion could introduce overhead if overused (e.g., deep nested fixtures). Benchmark against existing solutions.
  • Tooling: Limited IDE support (e.g., autocompletion for states) compared to Laravel’s native factories. May require custom PHPDoc annotations.

Key Questions

1. Fixture Scope: Will Foundry replace all Laravel factories, or coexist with them (e.g., hybrid approach)?
2. State Management: How will stateful fixtures integrate with Laravel’s RefreshDatabase or MigrateFresh?
3. Non-Doctrine Models: Are there non-Eloquent models that need fixture support? If so, how will Foundry’s auto-completion be adapted?
4. Testing Workflow: Will Foundry’s Loader replace Laravel’s create() helpers, or will a wrapper layer be needed?
5. Performance: Are there critical paths where auto-completion could slow down test suites? (e.g., 1000+ fixture generations).
6. Migration Testing: How will Foundry integrate with migration testing (e.g., verifying schema changes)?
7. Team Adoption: What training or documentation will be needed to onboard developers to Foundry’s stateful paradigm?

Integration Approach

Stack Fit

• Core Stack:
  • PHP/Laravel: Foundry’s PHP 8.1+ support aligns with Laravel’s LTS versions (10.x+). No major language-level conflicts.
  • Doctrine/Eloquent: Foundry’s ORM-agnostic design works seamlessly with Eloquent, though some Laravel-specific features (e.g., Faker seeds) may need bridging.
  • Testing Frameworks: Native integration with PHPUnit/Pest via Foundry’s Loader or custom test traits.
• Compatibility:
  • Pros:
    • Replaces Laravel’s Factory classes with less boilerplate.
    • Supports Laravel’s HasFactory trait via custom trait or macro.
    • Works with Laravel’s DatabaseTransactions or RefreshDatabase.
  • Cons:
    • Laravel’s Faker integration may require Foundry’s Faker adapter or custom state definitions.
    • Some Laravel-specific testing helpers (e.g., actingAs()) may need Foundry-compatible wrappers.

Migration Path

1. Phase 1: Pilot Fixtures
   • Replace 1–2 critical factory classes (e.g., User, Post) with Foundry equivalents.
   • Validate auto-completion and state management in existing tests.
   • Example:

     // Before (Laravel Factory)
     User::factory()->hasPosts(3)->create();
     
     // After (Foundry)
     User::new()->hasPosts(3)->create();
     

2. Phase 2: Full Replacement
   • Create a FoundryServiceProvider to register all factories via Foundry’s Loader.
   • Deprecate old Factory classes (use Laravel’s macro() to warn or redirect).
   • Example:

     // config/foundry.php
     'factories' => [
         \App\Models\User::class,
         \App\Models\Post::class,
     ],
     

3. Phase 3: Advanced Features
   • Implement stateful test scenarios (e.g., User::new()->asAdmin()->withPublishedPosts()).
   • Integrate with Laravel’s RefreshDatabase via Foundry’s Loader::load() in setUp().
   • Add custom macros for Laravel-specific needs (e.g., actingAs() compatibility).

Compatibility

• Laravel-Specific Adjustments:
  • Faker Integration: Extend Foundry’s Faker support to match Laravel’s Faker seeds.
  • Macros: Create Foundry-compatible macros for Laravel’s Factory methods (e.g., afterCreating()).
  • Testing Helpers: Wrap Foundry in a trait for Laravel’s test case methods (e.g., createModel(), create()).
• Tooling:
  • IDE Support: Add PHPDoc annotations for Foundry’s State methods to enable autocompletion.
  • CI/CD: Update test pipelines to use Foundry’s Loader (e.g., php artisan foundry:load).
• Database:
  • Ensure Foundry’s auto-completion respects Laravel’s morphMap or polymorphic relationships.

Sequencing

1. Pre-Integration:
   • Audit existing factories for complexity (e.g., deeply nested or conditional logic).
   • Identify fixtures that rely on Laravel-specific features (e.g., Faker seeds, custom create() logic).
2. Integration:
   • Start with stateless fixtures, then introduce states for complex scenarios.
   • Gradually replace Factory calls in tests with Foundry equivalents.
3. Post-Integration:
   • Deprecate old factories (use Laravel’s macro() to log deprecation warnings).
   • Optimize slow fixtures (e.g., limit auto-completion depth for performance).
   • Document Foundry-specific patterns (e.g., state naming conventions).

Operational Impact

Maintenance

• Pros:
  • Reduced Boilerplate: Foundry’s declarative syntax cuts maintenance overhead for fixture updates.
  • Centralized Definitions: Fixtures are defined in one place (e.g., config/foundry.php), reducing duplication.
  • State Reusability: Stateful fixtures encourage DRY test scenarios (e.g., shared user roles).
• Cons:
  • Learning Curve: Developers must learn Foundry’s State system and auto-completion rules.
  • Tooling Gaps: Limited Laravel-specific tooling (e.g., no tinker support for Foundry fixtures).
  • Migration Debt: Replacing factories may require updating tests or CI scripts (e.g., seeders, migrations).

Support

• Developer Onboarding:
  • Provide a Foundry-specific testing guide with examples for common Laravel patterns (e.g., polymorphic relationships, soft deletes).
  • Create a cheat sheet for migrating from Laravel factories to Foundry.
• Debugging:
  • Foundry’s auto-completion may obscure issues (e.g., circular dependencies). Add logging for failed fixture generation.
  • Example:

    Foundry::debug(true); // Logs auto-completion steps
    

• Community:
  • Leverage Foundry’s Symfony ecosystem for support (e.g., Doctrine/ORM issues).
  • Contribute Laravel-specific fixes back to the Foundry