Artisan Schematics Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Aligns with Laravel’s Eloquent ORM, reducing duplication between backend (PHP) and frontend (TypeScript/Dart/Kotlin) schemas.
  • Supports deep relationship resolution, eliminating manual syncing of nested model structures.
  • Extensible design allows custom generators (e.g., for GraphQL schemas, OpenAPI specs, or domain-specific languages).
  • Zero-config autoloading ensures generated files are discoverable without manual imports.
  • Type safety bridges PHP enums and Laravel casts to frontend types, improving DX.

• Cons:

  • Tight coupling to Eloquent: Limited utility for non-Eloquent models (e.g., custom repositories, query builders).
  • Frontend language support is fixed (TS/Dart/Kotlin/Swift); adding new languages requires custom generators.
  • No built-in versioning for generated schemas (risk of breaking changes during model updates).

Integration Feasibility

• Low-risk for Laravel monorepos:
  • Dev dependency (--dev) isolates it from production.
  • Artisan command integration (php artisan schematics:generate) fits Laravel’s CLI ecosystem.
• CI/CD compatibility:
  • Can be triggered post-migration or pre-deploy to sync schemas.
  • Output can be versioned (e.g., via Git) or deployed alongside frontend code.
• Database-agnostic:
  • Relies on Eloquent models, not raw SQL, so works with MySQL, PostgreSQL, SQLite, etc.

Technical Risk

• Schema drift:
  • Frontend schemas may lag if generation isn’t automated (e.g., forgotten pre-deploy step).
  • Mitigation: Hook into post-deploy or use Git hooks to auto-generate.
• Performance:
  • Recursive dependency resolution could slow down large applications with circular references.
  • Mitigation: Test with a sample of 100+ models; cache generated files if needed.
• Custom logic:
  • Complex model logic (e.g., accessors, mutators) may not translate cleanly to frontend types.
  • Mitigation: Document unsupported features; use comments in generated files to flag edge cases.

Key Questions

1. Frontend adoption:
   • How will frontend teams consume these schemas? (e.g., copied to a shared repo, imported via npm, or fetched at runtime?)
2. Versioning strategy:
   • Will schemas be versioned independently of backend code? If so, how will conflicts be resolved?
3. Customization needs:
   • Are there language-specific quirks (e.g., Kotlin’s data class vs. TypeScript interfaces) that require generator overrides?
4. Testing coverage:
   • Does the package handle edge cases like polymorphic relationships or custom casts? (Verify with the test suite.)
5. Long-term maintenance:
   • Who will own updates if the package evolves (e.g., new Laravel versions, language support)?

Integration Approach

Stack Fit

• Ideal for:
  • Full-stack Laravel apps with frontend frameworks (React, Angular, Flutter, SwiftUI) needing type-safe backend models.
  • Microservices where backend models are shared across multiple frontend clients.
  • Teams using shared design systems where model shapes must align across platforms.
• Less ideal for:
  • Projects using non-Eloquent data layers (e.g., raw SQL, custom repositories).
  • Frontend-heavy apps with minimal Laravel backend logic.

Migration Path

1. Pilot phase:
   • Start with 1–2 critical models (e.g., User, Product) to validate output quality.
   • Compare generated TypeScript/Dart against manually written schemas.
2. Incremental rollout:
   • Add models in batches, prioritizing those with complex relationships.
   • Gradually replace manual schema definitions with generated files.
3. Automation:
   • Integrate into CI/CD:

     # Example GitHub Actions step
     - name: Generate Schematics
       run: php artisan schematics:generate --lang=typescript --output=./frontend/src/generated
     

   • Use post-update-cmd in composer.json for local development:

     "scripts": {
       "post-update-cmd": "php artisan schematics:generate --lang=typescript --output=../frontend/src/generated"
     }
     

Compatibility

• Laravel versions:
  • Tested with Laravel 10+ (check composer.json constraints). May need adjustments for older versions.
• PHP versions:
  • Requires PHP 8.1+ (verify with php -v).
• Frontend frameworks:
  • Works with any framework that supports TypeScript/Dart/Kotlin (e.g., React, Flutter, iOS/Swift).
  • For runtime usage (e.g., fetching schemas via API), ensure CORS and API endpoints are configured.

Sequencing

1. Pre-requisites:
   • Ensure Eloquent models are fully defined (relationships, casts, enums).
   • Set up output directories in the frontend repo (e.g., frontend/src/generated).
2. Initial setup:
   • Install package: composer require saher/artisan-schematics --dev.
   • Publish config (if needed): php artisan vendor:publish --provider="Saher\Schematics\SchematicsServiceProvider".
3. Configuration:
   • Customize config/schematics.php for:
     • Default languages (typescript, dart, etc.).
     • Output paths.
     • Excluded models (e.g., Model::exclude(['AdminPanelModel'])).
4. Testing:
   • Run php artisan schematics:generate manually to verify output.
   • Test frontend imports (e.g., import type { User } from './generated/user').
5. Automation:
   • Add to CI/CD pipeline (e.g., GitHub Actions, GitLab CI).
   • Explore caching (e.g., schematics:generate --cache=60 for dev environments).

Operational Impact

Maintenance

• Pros:
  • Reduced boilerplate: Eliminates manual schema updates when models change.
  • Single source of truth: Backend models define frontend types, reducing sync errors.
  • Extensible: Custom generators can handle domain-specific needs (e.g., GraphQL input types).
• Cons:
  • Dependency on package updates:
    • Monitor for breaking changes (e.g., Laravel 11 compatibility).
    • Fork if critical features are missing (MIT license allows this).
  • Debugging complexity:
    • Issues may span PHP (model logic) and frontend (type usage). Requires cross-team coordination.

Support

• Internal:
  • Frontend teams: Train on consuming generated files (e.g., how to extend types without breaking updates).
  • Backend teams: Document model conventions (e.g., "avoid dynamic casts for generated schemas").
• External:
  • Limited community (0 stars/dependents); rely on:
    • GitHub issues for bugs.
    • Package documentation (readme, tests).
    • Laravel Discord/Forums for similar use cases.
• SLA considerations:
  • Define a process for schema-breaking changes (e.g., major model refactors).

Scaling

• Performance:
  • Large codebases: Test with 500+ models to validate recursion performance.
  • Mitigations:
    • Exclude rarely used models from generation.
    • Use --depth flag to limit relationship traversal.
• Team scaling:
  • Onboarding: New developers get schemas "for free" by running the generator.
  • Cross-team sync: Schemas act as a contract between backend and frontend teams.
• Multi-repo setups:
  • If backend and frontend are separate repos, use:
    • Git submodules for shared output.
    • API endpoints to fetch schemas dynamically (less ideal for type safety).

Failure Modes

Ramp-Up

• For TPMs:
  • Stakeholder alignment:
    • Convince frontend teams to adopt generated schemas (show ROI in reduced manual work).
    • Align with data teams if using custom casts/enums.
  • Pilot metrics:
    • Measure time saved per model update (e.g., "reduced from 30 mins to 5 mins").
  • Risk mitigation:
    • Start with non-critical models; phase in high-impact ones (e.g., Order, User).
• **For