Dev.to AI πŸ€– Ai πŸ‘ 0 πŸ“– 4 min read

What does this change break? Teaching an AI agent to see through Laravel facades

Ask a coding agent to change ThemeService::dispatch() in BookStack and it will do what you would do: search for ->dispatch( and ThemeService, read what comes back, and edit. It finds one caller. There are 19 call sites.

Ask a coding agent to change ThemeService::dispatch() in BookStack and it will do what you would do: search for ->dispatch( and ThemeService, read what comes back, and edit. It finds one caller.

There are 19 call sites. They look like this:

Theme::dispatch(ThemeEvents::AUTH_LOGIN, $method, $user);

Theme is a facade:

class Theme extends Facade
{
    protected static function getFacadeAccessor(): string
    {
        return ThemeService::class;
    }
}

No @mixin, no @method. Nothing written in the code links Theme::dispatch() to ThemeService::dispatch(). A person who knows Laravel makes the jump without thinking. A grep doesn't, and neither does an agent that only has grep.

A graph instead of a grep

phpgraph builds a knowledge graph of a PHP project by static analysis: classes, methods, calls, routes, messages and their handlers. Every relation has a confidence level: read in the code, inferred from declared types, or guessed. There is no LLM and no network call. It never boots your application: the code is parsed, not run. Agents use it through MCP (Claude Code, Codex, Cursor…), or you use it from the command line.

Since 2.4.0, it follows facades. When a facade has no @mixin or @method for the method called, phpgraph reads getFacadeAccessor():

  • if it returns X::class, the call goes to X;
  • if it returns a key ('steam', 'preferences'), phpgraph looks for that key in your service providers: bind(), singleton(), scoped(), instance() and their *If forms, and the $bindings and $singletons arrays. The bound class can be X::class, new X, or a closure that returns one:
$this->app->bind('steam', static fn (): Steam => new Steam());

A key bound nowhere, or bound to two different classes, is not guessed. phpgraph overview lists the facades it could not follow, with the reason.

Here is the same question, asked of phpgraph:

$ phpgraph impact 'ThemeService::dispatch'
Impact of changing ThemeService::dispatch() [method], app/Theming/ThemeService.php L53
73 classes up to 3 relations away, 146 routes; 58 tests

Routes reaching it, ← from their handler:
  POST /register ← RegisterController::postRegister() ← LoginService::login()
  POST /oidc/login ← OidcController::login() ← OidcService::login()
  POST /books ← BookController::store() ← ActivityLogger::add()
  PUT /books/{bookSlug}/sort ← BookSortController::update() ← ActivityLogger::add()
  ...

Direct dependents:
  LoginService (BookStack\Access): login L53; ...
  RegistrationService (BookStack\Access): registerUser L91, L106; ...

That's 73 classes instead of 1, every route that ends up running the method, and the 58 tests to run before you push. The chains go through the job (DispatchWebhookJob) the activity logger dispatches, because phpgraph links jobs and events to their handlers too.

On Firefly III, which has 11 facades bound by string keys, this adds 1,289 resolved calls. impact of Steam::bcround() went from 0 classes to 91.

Eloquent relations

The second Laravel change in 2.4.0 is about models. A relation method is now an edge of the graph:

public function pages(): HasMany
{
    return $this->hasMany(Page::class);
}

gives Book::pages() relates_to Page. phpgraph's outline command answers "how does this feature work?" with the classes involved, the routes running into them and the tests. Before 2.4.0, outline "Book" folded Page, Chapter and Bookshelf into a family line ("Entity: 5"), because they all extend Entity. Now it names them, with the relation that brought each one in:

Core, by namespace:
  BookStack\Entities\Models [Entities]
    Book (class) [seed]
    Bookshelf (class, implements HasDescriptionInterface, HasCoverInterface) [belongsToMany by Book::shelves]
    Page (class) [hasMany by Book::pages]
    Chapter (class, implements HasDescriptionInterface, HasDefaultTemplateInterface) [hasMany by Book::chapters]
    SortRule (class) [belongsTo by Book::sortRule]

Polymorphic relations (morphMany for comments, tags, views…) are left out on purpose: they link a model to every other model that can be commented on, which says nothing about the feature.

Casts, timestamps and relations read as properties were already typed, so $page->book->chapters() resolves through the whole chain.

What else it reads in a Laravel app

  • Events, jobs and listeners: $listen, Event::listen(), subscribers, listeners of a union of events, event(), dispatch(), Job::dispatch().
  • Routes: route files, groups with prefix, domain and name, resources, Route::view and redirect.
  • The HTTP client: Http:: calls linked to the routes they reach, relative to their baseUrl().
  • The container: app(X::class) and app()->make(X::class) give an X.

And Laravel Boost?

If you use Laravel Boost, the two fit together. Boost tells the agent about the running application: routes, database schema, logs, the docs for your versions, Tinker. phpgraph tells it what calls what, and what a change reaches, without booting anything.

Limits

  • Blade and Twig templates are not read: a call written in a view is not in the graph.
  • when()->needs()->give() is not used. When an interface has several implementations, impact lists the callers of each.
  • A facade bound by code phpgraph can't read is reported, not guessed.

The full list is in docs/LIMITATIONS.md.

Trying it

curl -fsSL https://raw.githubusercontent.com/alpine-ronin/phpgraph/main/install.sh | sh
cd your-laravel-app
phpgraph mcp-config claude   # or codex, cursor, json

It's a single binary that needs no PHP, and there is also a PHAR, a Composer package and a Docker image. The graph builds on first use and rebuilds itself when the code changes. It's MIT licensed.

If you try it on your app and a facade, a binding or a relation isn't followed, open an issue with the snippet. Several of the Laravel fixes so far started that way.

πŸ“° Read the original article on Dev.to AI

Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes β€” full credit and traffic to the original publisher.