maarheeze/codegraph-laravel

Instant code understanding for Laravel applications.

This package extends maarheeze/codegraph to automatically extract and index Laravel patterns—routes, models, services, and dependencies. Understand your codebase instantly without guessing, grepping, or slow IDE searches.

Why Use It?

Answer questions about your Laravel app in milliseconds.

• Where is X bound? — Find service bindings instantly
• What breaks if I change this? — See all callers, relations, and dependents
• How does this route work? — Trace the full call chain from route → controller → models → queries
• Where is this model used? — Find all relations and eager-loading patterns
• What models relate to this one? — See all hasMany, belongsTo, morphs, and polymorphic relations at a glance

How it helps:

• ⚡ Faster refactoring — Know exactly what breaks before you change it
• 💰 Cheaper AI assistance — Feed Claude accurate, structured data instead of raw file contents
• 🔍 Offline navigation — No IDE plugin or running app needed; index once, query forever
• ✨ Automatic extraction — No manual mapping; parses your actual code structure (AST-based, not regex)
• 🤖 Works with Claude Code, Cursor, and any AI — MCP protocol integration for context-aware code assistance

What It Extracts

This package extends CodeGraph with Laravel-aware extraction:

• Routes — All route definitions with HTTP methods and controller handlers
• Eloquent Relations — Model relationships (hasMany, belongsTo, hasOne, hasManyThrough, belongsToMany, morphMany, morphTo)
• Service Bindings — Service container bindings (bind, singleton, scoped, instance, factory)
• Call Graph — Complete call graphs across your codebase
• Inheritance & Traits — Class hierarchies and trait usage

Installation

composer require maarheeze/codegraph-laravel --dev

The package auto-registers via Laravel's service provider system. No additional configuration needed.

Usage

Index Your Application

php artisan codegraph:index

Scans your app/ and routes/ directories and extracts all Laravel patterns into .codegraph/index.sqlite. This directory is auto-generated and should be added to .gitignore.

View Indexing Status

php artisan codegraph:status

Shows what was extracted: routes, relations, service bindings, and other patterns.

Automatic Indexing on Install

To automatically initialize and index your codebase after dependencies are installed or updated, add the following to your composer.json:

{
  "scripts": {
    "post-autoload-dump": [
      "@php artisan codegraph:init",
      "@php artisan codegraph:index"
    ]
  }
}

This ensures your code graph is initialized and stays in sync whenever dependencies change or the codebase is freshly checked out.

Architecture

The package implements the CodeGraph plugin system:

• LaravelPlugin — Registers Laravel-specific extractors
• RouteExtractor — Parses route definitions
• EloquentRelationExtractor — Detects model relationships
• ServiceProviderBindingExtractor — Captures service bindings
• LaravelIndexingService — Wraps core IndexingService with Laravel defaults
• LaravelStatusService — Provides query interface for extracted data

All extractors extend BaseAstVisitor and work with the AST (Abstract Syntax Tree) to ensure accuracy.

How It Works

1. Register plugin — LaravelPlugin registers all extractors with CodeGraph
2. Scan files — Discovers and parses PHP files in app/, routes/, and configurable directories
3. Extract patterns — Each extractor identifies Laravel-specific patterns in the AST (Abstract Syntax Tree)
4. Build graph — Creates nodes for routes, models, services, and edges for dependencies
5. Persist index — Stores the complete code graph in SQLite for fast, offline querying
6. Resolve references — CodeGraph resolves all cross-file references automatically

The index is incremental — subsequent runs only re-scan changed files, keeping indexing fast even on large codebases.

Use Cases

• Impact Analysis — Answer "what breaks if I change this?" before you refactor
• Dependency Discovery — Understand the full dependency graph of a feature
• Refactoring Safety — See all callers, relations, and bindings before making changes
• Onboarding — New developers understand the codebase structure instantly
• Documentation — Auto-generate architecture diagrams from actual code
• IDE & Tools — Integrate with Claude Code, custom scripts, or build tools for context-aware assistance
• Code Review — Verify that refactors are complete and consistent

Requirements

• PHP 8.3+
• Laravel 13.0+
• ext-sqlite3 extension

License

MIT