Eloquent Schema Laravel Package

Technical Evaluation

Architecture Fit

• Seamless Laravel Integration: Designed specifically for Laravel 11/12 with Eloquent, leveraging Laravel’s service container, configuration system, and MCP (Model Command Protocol) ecosystem. The package extends Laravel Boost’s MCP tools, making it a natural fit for apps already using Boost or planning to adopt AI/ML integrations.
• Modular Design: Core functionality (model discovery, schema extraction) is decoupled from MCP tools, allowing adoption even in apps without MCP infrastructure. Programmatic APIs (ModelDiscoveryService, ModelSchemaService) enable flexible integration.
• Vendor Package Awareness: Unique support for third-party Eloquent models (e.g., Spatie, MediaLibrary) via discovery tools and deduplication logic, addressing a pain point in multi-package apps.

Integration Feasibility

• Low Friction: Installation requires a single Composer command and optional config publishing. Artisan commands (eloquent-schema:cache, eloquent-schema:discover) handle heavy lifting (e.g., model scanning, cache warming).
• Backward Compatibility: No breaking changes to existing Eloquent models or migrations. Schema extraction is non-intrusive, relying on reflection and introspection.
• Extensibility: Custom model paths, explicit includes/excludes, and MCP tool registration allow tailoring to app-specific needs (e.g., ignoring legacy models).

Technical Risk

• Performance Overhead:
  • Schema Discovery: Initial model scanning (especially for vendor packages) may be resource-intensive for large apps. Mitigated by caching and incremental discovery (--max-depth for relationships).
  • Memory Usage: Deep relationship introspection (max_depth > 1) can consume significant memory. Defaults (max_depth=2) balance completeness and safety.
• Cache Invalidation: Manual cache clearing (eloquent-schema:clear) is required after model changes. The package provides tools to automate this (e.g., post-migration hooks).
• MCP Dependency: Full feature set (MCP tools) requires Laravel Boost. However, core schema services work independently.
• Vendor Package Stability: Discovery relies on package autoloading. Unstable or frequently updated vendor packages may cause schema inconsistencies.

Key Questions

1. AI/ML Strategy:

   • Are we prioritizing AI integrations (e.g., Copilot, custom LLMs) that would leverage MCP tools? If not, the programmatic APIs may suffice.
   • How will schema exposure fit into our existing AI tooling (e.g., does it replace or complement manual documentation)?

2. Vendor Package Scope:

   • Which third-party packages (if any) are critical to include? Their stability and Eloquent model complexity will impact discovery reliability.
   • Should we whitelist/blacklist specific vendor models to avoid noise?

3. Performance Tradeoffs:

   • What’s the acceptable max_depth for relationship introspection? Depth 1 (shallow) is fastest but least informative; depth 3+ may be prohibitive.
   • How frequently will schemas change? Higher churn increases cache invalidation overhead.

4. Adoption Path:

   • Will teams use MCP tools directly, or prefer programmatic access (e.g., from CLI scripts, migrations)?
   • Should we integrate cache warming into deployment pipelines (e.g., eloquent-schema:cache post-migration)?

5. Long-Term Maintenance:

   • Who will own cache invalidation (e.g., ensuring eloquent-schema:clear runs after schema migrations)?
   • How will we handle breaking changes in Laravel 13+ or Eloquent updates?

Integration Approach

Stack Fit

• Laravel 11/12: Native support with zero modifications required. Leverages Laravel’s service container, configuration, and MCP ecosystem.
• PHP 8.2+: Uses modern features (e.g., enums, attributes) but avoids breaking changes. No runtime dependencies beyond Laravel core.
• Eloquent: Focuses on Eloquent models, not raw database schemas. Ideal for apps using Eloquent for data access.
• Laravel Boost/MCP: Full feature set requires Boost, but core schema services work independently. MCP tools integrate via Boost’s tool registration system.
• Vendor Packages: Optimized for packages using Eloquent (e.g., Spatie, MediaLibrary). Less effective for non-Eloquent packages.

Migration Path

1. Assessment Phase:

   • Audit existing Eloquent models and vendor packages to identify scope (e.g., models to include/exclude).
   • Test discovery with eloquent-schema:discover --list to validate vendor package support.
   • Benchmark performance with eloquent-schema:cache --max-depth=2 on a staging environment.

2. Pilot Integration:

   • Install the package and publish config:

     composer require visualbuilder/eloquent-schema
     php artisan vendor:publish --tag=eloquent-schema-config
     

   • Configure model_paths, included_packages, and cache_ttl in config/eloquent-schema.php.
   • Warm the cache:

     php artisan eloquent-schema:cache
     

3. Core Adoption:

   • Option A (MCP-First): Register tools in config/boost.php and expose via MCP server:

     'mcp' => [
         'tools' => [
             'include' => [
                 \Visualbuilder\EloquentSchema\Mcp\Tools\ListModels::class,
                 \Visualbuilder\EloquentSchema\Mcp\Tools\ModelSchema::class,
             ],
         ],
     ];
     

   • Option B (Programmatic): Use services directly in custom tools:

     $schema = app(ModelSchemaService::class)->getSchema(Order::class);
     

   • Option C (Hybrid): Use MCP tools for AI integrations and programmatic APIs for internal scripts.

4. Vendor Package Onboarding:

   • Run php artisan eloquent-schema:discover to identify packages with Eloquent models.
   • Add selected packages to included_packages and warm cache.

5. Cache Management:

   • Automate cache warming post-deployment (e.g., in post-deploy scripts).
   • Implement cache invalidation hooks for schema migrations (e.g., clear cache after running migrations).

Compatibility

• Laravel Versions: Tested on 11/12. May require minor adjustments for future versions (e.g., if MCP APIs change).
• Eloquent Customizations: Handles common patterns (accessors, mutators, relationships) but may miss highly customized models (e.g., dynamic properties). Validate with edge cases.
• Caching Backends: Uses Laravel’s cache system (supports Redis, database, file). No vendor-specific dependencies.
• MCP Servers: Compatible with Laravel Boost’s MCP server and custom implementations. Tools follow MCP standards.

Sequencing

1. Pre-requisites:
   • Laravel 11/12 with PHP 8.2+.
   • (Optional) Laravel Boost for MCP tools (core features work without it).
2. Discovery:
   • Configure model_paths and included_packages.
   • Run eloquent-schema:discover to validate vendor support.
3. Core Setup:
   • Publish config and set cache_ttl.
   • Warm cache with eloquent-schema:cache.
4. Tool Integration:
   • Register MCP tools (if using Boost).
   • Integrate programmatic APIs into custom tools/scripts.
5. Vendor Onboarding:
   • Add critical packages to included_packages and re-warm cache.
6. Optimization:
   • Adjust max_depth and cache TTL based on performance metrics.
   • Automate cache invalidation for CI/CD pipelines.

Operational Impact

Maintenance

• Cache Management:
  • Proactive: Schedule regular cache warming (e.g., nightly) to preempt stale schemas.
  • Reactive: Clear cache manually (eloquent-schema:clear) or via hooks after schema migrations.
  • Automation: Integrate eloquent-schema:cache into deployment pipelines (e.g., post-migration).
• Configuration:
  • Monitor config/eloquent-schema.php for drift (e.g., outdated included_packages).
  • Document excluded models and their rationale (e.g., legacy systems).
• Vendor Updates:
  • Retest discovery after major vendor package updates (e.g., Spatie Permission).
  • Watch for breaking changes in Laravel/Eloquent that affect introspection.

Support

• Troubleshooting:
  • Discovery Issues: Use eloquent-schema:discover --list to debug missing models.
  • Schema Errors: Check max_depth limits and model customizations (e.g., dynamic properties).
  • MCP Failures: Validate tool registration in Boost and server configuration.
• Documentation:
  • Maintain a runbook for common issues (e.g., "Cache not updating after migration").
  • Document programmatic usage patterns (e.g., how to fetch schemas for CLI tools).
• Team Training:
  • Educate developers on cache invalidation best practices.
  • Highlight MCP tool usage for AI integrations (e.g., "Use model-schema for Copilot prompts").

Scaling

• Performance:
  • **