Content
# Model Explorer for Laravel
[](https://packagist.org/packages/onelearningcommunity/laravel-model-explorer)
[](https://github.com/one-learning-community/laravel-model-explorer/actions?query=workflow%3Arun-tests+branch%3Amain)
[](https://packagist.org/packages/onelearningcommunity/laravel-model-explorer)
A developer tool for Laravel that gives you a browsable UI to explore your Eloquent models — their attributes, casts, relations, scopes, traits, and live data — without reading code.
**Zero setup beyond Composer install.** No `vendor:publish`, no frontend tooling required in your application.
## Requirements
- PHP 8.3+
- Laravel 11, 12, or 13
## Features
- **Model list** — searchable grid of all discovered Eloquent models
- **Model detail** — DB columns, casts, fillable/hidden/guarded, relations with type badges and foreign keys, scopes with source snippets, traits, and accessor snippets
- **Record lookup** — find any record by primary key or unique field; browse raw attributes, lazy-loaded accessor values, and expandable relations with drill-down navigation and breadcrumb trail
- **Relationship graph** — interactive force-directed SVG graph of all model relationships
## Installation
```bash
composer require --dev onelearningcommunity/laravel-model-explorer
```
The package auto-registers via Laravel's package discovery — no additional setup required.
## Usage
Visit `/_model-explorer` in your application. In local environments, access is granted by default.
## Authorization
Access is controlled by the `viewModelExplorer` gate, which defaults to allowing access in `local` environments only. Override it in your `AuthServiceProvider` to control access elsewhere:
```php
Gate::define('viewModelExplorer', function (User $user): bool {
return $user->isAdmin();
});
```
To disable the explorer entirely regardless of the gate, set the environment variable:
```env
MODEL_EXPLORER_ENABLED=false
```
## Configuration
Publish the config file to customise behaviour:
```bash
php artisan vendor:publish --tag="model-explorer-config"
```
```php
return [
// Set to false to disable entirely (e.g. force off in production regardless of gate)
'enabled' => env('MODEL_EXPLORER_ENABLED', true),
// URL prefix for all Model Explorer routes
'path' => env('MODEL_EXPLORER_PATH', '_model-explorer'),
// Middleware applied to all routes ('web' is required)
'middleware' => ['web'],
// Directories scanned for Eloquent models (add more for DDD layouts, packages, etc.)
// Keys are the root namespace, values are absolute directory paths.
'model_paths' => [
'App' => app_path(),
// 'Domain\\Billing' => base_path('src/Billing'),
],
// Model classes matching these patterns are hidden, even inside a scanned path.
// Entries match the FQCN and may use `*` as a wildcard (leading `\` is ignored).
'excluded_models' => [
// 'Laravel\\Telescope\\*',
// 'App\\Models\\Internal\\AuditLog',
],
// Traits whose FQN begins with these prefixes will be hidden in the UI
'excluded_trait_prefixes' => [
'Illuminate\Database\Eloquent\Concerns\\',
'Illuminate\Database\Eloquent\HasCollection',
'Illuminate\Support\Traits\\',
],
// Related records shown per page when drilling into a to-many relation,
// and the cap on collection-returning accessor values.
'per_page' => env('MODEL_EXPLORER_PER_PAGE', 15),
// Cache model discovery and inspection results (recommended for large apps).
// Disabled by default so model changes appear immediately during development.
'cache' => [
'enabled' => env('MODEL_EXPLORER_CACHE', false),
'store' => env('MODEL_EXPLORER_CACHE_STORE'), // null = default store
'ttl' => env('MODEL_EXPLORER_CACHE_TTL'), // seconds; null = forever
],
];
```
### Caching
For apps with many models, the filesystem scanning and reflection behind the model
list, detail, and graph views can be enabled for caching via `MODEL_EXPLORER_CACHE=true`.
Model detail pages auto-refresh when the model file changes; the model list and graph
are cached until the TTL expires or you clear them manually:
```bash
php artisan model-explorer:clear
```
## AI Model Introspection (MCP)
Model Explorer ships a local [`laravel/mcp`](https://laravel.com/docs/mcp) server,
`model-explorer`, that lets AI coding agents introspect your Eloquent models without
scanning source. Register it in your AI client:
```json
{
"mcpServers": {
"model-explorer": {
"command": "php",
"args": ["artisan", "mcp:start", "model-explorer"]
}
}
}
```
Tools: `list-models`, `inspect-model` (opt-in sections via `include`),
`relationship-graph`, `find-model` (filter by `trait`/`extends`/`relatesTo`/`hasColumn`),
and `model-source`. If you use [Laravel Boost](https://laravel.com/docs/boost),
`boost:install` automatically advertises these tools to your agent.
The tools read live by default so an agent never sees stale structure mid-development.
Set `MODEL_EXPLORER_MCP_CACHE=true` to trade freshness for speed on very large model
sets, or `MODEL_EXPLORER_MCP=false` to disable the server entirely.
## Security
Model Explorer for Laravel is intended for development use. The `viewModelExplorer` gate should prevent access in production environments.
All record reads are wrapped in a rolled-back transaction with `Model::withoutEvents()` to prevent accidental writes from observers or model events. Note that non-database side effects from accessor methods (HTTP calls, cache writes, queue pushes) are **not** prevented.
## Changelog
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
