Linter Laravel Package

Technical Evaluation

Architecture Fit

• Opinionated and Non-Laravel-Native: The package is designed for Memio’s model system, which is incompatible with Laravel’s Eloquent/Repository patterns. Laravel’s native model layer (e.g., Eloquent) does not align with Memio’s contract-based or object-oriented constraints (e.g., ContractMethodsCanOnlyBePublic). This creates a fundamental architectural mismatch unless the team is already using Memio’s ecosystem.
• Static Analysis Complementarity: While the linter’s constraints (e.g., abstract method validation, argument type checks) could theoretically complement Laravel’s PHPStan or Psalm, the implementation is tied to Memio’s validator and model structures. Reusing constraints would require rewriting them to work with Laravel’s reflection system or custom model layers.
• Build-Time Validation Focus: The package is optimized for build-time validation (via Memio’s code generation pipeline). Laravel’s CI/CD typically relies on runtime validation (e.g., Eloquent rules, Form Requests) or static analysis tools like PHPStan. Integrating this would require shifting validation left in the pipeline, which may not align with existing workflows.

Integration Feasibility

• Memio Dependency: The package requires Memio’s validator and model layers to function. Without adopting Memio, the linter’s constraints are inapplicable to Laravel’s models. Even if constraints were ported, they would need to be reimplemented for Laravel’s context (e.g., Eloquent relationships, accessors).
• Constraint Portability: Individual constraints (e.g., MethodCannotBeAbstractAndHaveBody) could be extracted and adapted, but this would involve:
  • Rewriting constraints to use Laravel’s reflection utilities or custom model traits.
  • Validating against Laravel’s base model classes (e.g., Illuminate\Database\Eloquent\Model) rather than Memio’s Model interface.
  • Potentially duplicating effort if similar checks already exist in PHPStan/Psalm.
• Tooling Overhead: The package introduces dependencies like Docker, PHPStan, Rector, and phpspec, which may be overkill for a Laravel project. Laravel teams typically use simpler toolchains (e.g., phpstan:baseline, pint, laravel-pint).

Technical Risk

• High Coupling Risk: The package’s design assumes Memio’s internal structures (e.g., ContractValidator, ObjectValidator), making it non-plug-and-play for Laravel. Risk of breaking changes if Memio’s API evolves, which could block Laravel integrations.
• PHP Version and Tooling Lock: Requires PHP 7.2+ (compatible with Laravel 8+) but introduces additional tooling (e.g., Docker for local development). This could increase onboarding friction for developers unfamiliar with Memio’s ecosystem.
• False Positives/Negatives: Constraints like CollectionCannotHaveNameDuplicates may not apply to Laravel’s collections (e.g., Eloquent hasMany relationships), leading to irrelevant validation errors or missed issues.
• CI/CD Complexity: Integrating the linter into Laravel’s CI/CD pipeline would require custom scripts to bridge Memio’s validation system with Laravel’s workflows (e.g., GitHub Actions, GitLab CI). This adds maintenance overhead.

Key Questions

1. Is Memio’s model system already in use, or is there a plan to adopt it?
   • If no, integration is not feasible without significant refactoring.
2. Are there specific model-related syntax errors (e.g., abstract methods, argument types) that PHPStan/Psalm are not catching?
   • If yes, could these be addressed with existing tools (e.g., custom PHPStan rules)?
3. Would the team benefit from build-time validation for custom model layers (e.g., DTOs, API resources) beyond Eloquent?
   • If yes, constraints could be adapted, but this requires effort.
4. Is the team willing to adopt Memio’s tooling (e.g., Docker, phpspec) for this package?
   • If no, the integration may be too cumbersome.
5. What is the alternative cost of implementing similar constraints in Laravel?
   • Example: Rewriting MethodCannotBeAbstractAndHaveBody as a custom PHPStan rule or Laravel trait.

Integration Approach

Stack Fit

• Laravel-Native Alternatives Exist: Laravel already provides built-in validation (e.g., Eloquent rules, Form Requests) and static analysis tools (e.g., PHPStan, Psalm). The linter’s constraints could overlap or duplicate functionality already covered by these tools.
  • PHPStan: Can enforce method modifiers, argument types, and abstract method rules via custom rules.
  • Psalm: Offers similar static analysis capabilities with Laravel plugins.
  • Laravel’s make:model: Generates Eloquent models with built-in validation patterns.
• Custom Model Layers: If the Laravel app uses non-Eloquent models (e.g., DTOs, API resources, domain models), the linter’s constraints could be adapted via:
  • Traits: Implementing constraints as reusable traits (e.g., EnsuresNoAbstractMethodsWithBodies).
  • Custom Validators: Extending Laravel’s validator system to include Memio-like constraints.
• Memio Ecosystem: If the team is fully committed to Memio, the linter could be integrated as a complementary tool for validating Memio-generated models alongside Laravel’s Eloquent layer.

Migration Path

1. Assess Current Validation Stack:
   • Audit existing static analysis tools (PHPStan, Psalm) to identify gaps the linter could fill.
   • Example: If PHPStan misses specific abstract method conflicts, consider custom rules instead of Memio’s linter.
2. Pilot Integration (If Using Memio):
   • Step 1: Set up Memio’s linter in a local development environment (Docker required).
   • Step 2: Run the linter on a subset of Memio-generated models to validate constraints.
   • Step 3: Integrate into CI/CD (e.g., GitHub Actions) as a pre-commit or pre-deploy step.
   • Example GitHub Actions workflow:

     - name: Run Memio Linter
       run: |
         docker-compose up -d memio
         vendor/bin/memio linter validate app/Models/MemioGenerated/
     

3. Adapt Constraints for Laravel (If Not Using Memio):
   • Step 1: Extract constraints (e.g., MethodCannotBeAbstractAndHaveBody) and rewrite them using Laravel’s reflection or custom traits.
   • Step 2: Integrate into PHPStan as custom rules or Laravel’s validator as traits.
   • Step 3: Test on non-Eloquent models (e.g., DTOs) to ensure compatibility.
4. Fallback to Existing Tools:
   • If constraints are already covered by PHPStan/Psalm, skip integration and focus on optimizing existing static analysis.

Compatibility

• Laravel Eloquent: Incompatible without Memio. Constraints like ContractMethodsCanOnlyBePublic do not apply to Eloquent’s Model class.
• Custom Models: Partially compatible if constraints are adapted. Example:

  // Custom trait to replicate a Memio constraint
  trait EnsuresNoAbstractMethodsWithBodies {
      public static function validate(): void {
          foreach (get_class_methods(static::class) as $method) {
              $reflection = new ReflectionMethod(static::class, $method);
              if ($reflection->isAbstract() && $reflection->getBody()) {
                  throw new \RuntimeException("Method {$method} cannot be abstract and have a body.");
              }
          }
      }
  }
  

• CI/CD Pipelines: Requires custom scripting to bridge Memio’s linter with Laravel’s workflows. Example:
  • Use Docker to run Memio’s linter in CI.
  • Parse output and fail builds on violations.

Sequencing

1. Phase 1: Evaluation (2-4 weeks)
   • Goal: Determine if Memio’s linter adds unique value beyond PHPStan/Psalm.
   • Tasks:
     • Run Memio’s linter on a sample of models (if using Memio).
     • Compare findings with PHPStan/Psalm reports.
     • Assess tooling overhead (Docker, phpspec).
2. Phase 2: Pilot Integration (3-6 weeks)
   • Goal: Test integration in a non-production environment.
   • Tasks:
     • Set up local development (Docker, Makefile).
     • Integrate into CI/CD (GitHub Actions).