Getting Started

Installation:

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

Configure config/eloquent-schema.php with your model paths and cache settings.

First Use Case: Warm the cache to discover models and preload schemas:

php artisan eloquent-schema:cache

Test the MCP tools directly:

php artisan eloquent-schema:mcp list-models
php artisan eloquent-schema:mcp model-schema --model='App\Models\User'

Quick Integration: For Laravel Boost users, add the tools to config/boost.php under mcp.tools.include:

\Visualbuilder\EloquentSchema\Mcp\Tools\ListModels::class,
\Visualbuilder\EloquentSchema\Mcp\Tools\ModelSchema::class,
\Visualbuilder\EloquentSchema\Mcp\Tools\ModelFields::class,

Implementation Patterns

1. AI Assistant Integration

Workflow:

Configure MCP tools in config/boost.php or your custom MCP server.
Use model-schema to fetch full model details (columns, relationships, accessors) for AI-generated queries.

Example: Generate a query for all Order records with status = 'shipped' and their related User data:

// MCP Request
{
  "tool": "ModelSchema",
  "args": {"model": "App\\Models\\Order", "max_depth": 2}
}

// AI-generated Eloquent code (based on schema)
Order::with(['user', 'lineItems'])
     ->where('status', 'shipped')
     ->get();

Tip: Cache schemas with max_depth=1 for lightweight queries, then fetch deeper relationships on demand.

2. CLI Tool Development

Pattern: Use the programmatic API to build dynamic CLI commands.

// In a custom Artisan command
public function handle()
{
    $schema = app(ModelSchemaService::class);
    $fields = $schema->getFlatFieldList(Order::class);

    $this->info("Available fields for Order: " . implode(', ', $fields['columns']));
    $this->info("Relationships: " . implode(', ', $fields['relationships']));
}

Use Case: Auto-generate --filter options for CLI tools based on model schemas.

3. Vendor Package Schema Access

Workflow:

Discover vendor packages:
```
php artisan eloquent-schema:discover
```
Select packages (e.g., spatie/laravel-permission) and update config/eloquent-schema.php.

Access schemas programmatically:

$schema = app(ModelSchemaService::class);
$roleSchema = $schema->getSchema(\Spatie\Permission\Models\Role::class);

Tip: Use include_vendor: true in list-models to filter vendor models in AI tools.

4. Dynamic Form/Query Builders

Pattern: Fetch model-fields to populate UI components.

// Frontend (via MCP)
const response = await mcp.call('ModelFields', {
  model: 'App\\Models\\Product'
});
// Render checkboxes for each column/relationship

Laravel Example:

// In a controller
$fields = app(ModelSchemaService::class)->getFlatFieldList(Product::class);
return view('admin.products.create', compact('fields'));

5. Migration Safety Checks

Pattern: Compare schemas before/after migrations.

// Pre-migration
$oldSchema = app(ModelSchemaService::class)->getSchema(Order::class);

// Post-migration
$newSchema = app(ModelSchemaService::class)->getSchema(Order::class);

// Log differences
$diff = array_diff($oldSchema['columns'], $newSchema['columns']);

Gotchas and Tips

Pitfalls

Caching Quirks:
- Issue: Schemas don’t update after model changes.
- Fix: Clear the cache with php artisan eloquent-schema:clear --schema or disable caching (cache_ttl: 0) in development.
- Tip: Use php artisan eloquent-schema:cache --max-depth=1 for lightweight caching during active development.
Vendor Model Deduplication:
- Issue: Your app’s User model extends Spatie\Permission\Models\User, but both appear in list-models.
- Fix: The package auto-prefers app models, but verify with:
```
php artisan eloquent-schema:mcp list-models --vendor
```
Relationship Depth Limits:
- Issue: max_depth: 2 returns incomplete schemas for deeply nested relationships.
- Fix: Set max_depth: 3 (max allowed) but cache separately to avoid memory spikes:
```
php artisan eloquent-schema:cache --max-depth=3 --cache-key=deep_schemas
```

Enum/Accessors Serialization:

Issue: Custom accessors or enums may not serialize cleanly in MCP responses.

Fix: Extend the schema service:

// app/Providers/EloquentSchemaServiceProvider.php
use Visualbuilder\EloquentSchema\Services\ModelSchemaService;

public function boot()
{
    $schemaService = app(ModelSchemaService::class);
    $schemaService->extendSchema(function ($schema, $model) {
        $schema['custom_accessors'] = $model->getCustomAccessors();
    });
}

Debugging Tips

Inspect Raw Schema Data:

$schema = app(ModelSchemaService::class)->getSchema(Order::class);
dd($schema); // Debug the full structure

Check Discovery Logs:

php artisan eloquent-schema:cache --verbose

Validate MCP Tools:

php artisan mcp:tools --describe ModelSchema

Extension Points

Custom Schema Fields: Add metadata to schemas via service providers:

$schemaService->extendSchema(function ($schema, $model) {
    $schema['api_resource'] = $model->getApiResource();
});

Dynamic Model Filtering: Override the discovery service to exclude models:

app()->bind(ModelDiscoveryService::class, function ($app) {
    $service = new \Visualbuilder\EloquentSchema\Services\ModelDiscoveryService();
    $service->excludeModels([
        \App\Models\ExcludedModel::class,
    ]);
    return $service;
});

Cache Tags: Use cache tags for model-specific invalidation:

Cache::tags(['eloquent-schema', 'App\Models\User'])->put(...);

Performance Tips

Cache Granularity:
- Cache model-fields separately from model-schema if you frequently need lightweight data:
```
Cache::remember("fields_{$model}", now()->addHours(1), fn() => $schema->getFlatFieldList($model));
```

Lazy-Load Relationships: For large apps, fetch relationships on-demand:

$schema = $schemaService->getSchema(Order::class, max_depth: 0);
$schema['relationships'] = $schemaService->getRelationships(Order::class, max_depth: 1);

Vendor Package Optimization: Disable vendor model discovery if unused:
```
'included_packages' => [], // Empty array
```

Eloquent Schema Laravel Package