Project Graph in Semitexa: Map PHP Dependencies Before You Edit

What is a project graph?

A project graph is a map of software entities and the relationships between them. Classes, routes, handlers, services, events, and modules are nodes. Relationships such as “handles this payload,” “implements this interface,” or “depends on this class” are directed edges. Unlike a list of text matches, the graph can answer structural questions: what uses this type, what does it depend on, and what could a change affect?

That is useful when a repository is larger than one person's working memory. A developer can find an entry point before editing; a reviewer can inspect downstream impact; an AI assistant can receive a focused architecture slice rather than a large collection of loosely related files.

What Semitexa Project Graph actually records

The optional semitexa-project-graph package scans PHP source and Semitexa attributes, extracts structural facts, and stores a directed graph. Its nodes include routes, payloads, handlers, services, events, and execution flows. Its edges capture relationships such as handles, returns, implements, and cross-module dependencies. The stored graph powers several different questions without making each developer reconstruct the architecture from scratch.

The package keeps graph data on its own project_graph database connection, separate from application data. A local SQLite fallback makes the command workflow available without turning the primary database into an architecture index. Build or refresh the graph when you need current answers, then check its state:

bin/semitexa ai:review-graph:generate --json
bin/semitexa ai:review-graph:stats --json

stats reports the indexed files, nodes, edges, and generation time. The counts change as the repository changes; the useful check is that the graph covers the code you are about to reason about. The Project Graph overview demo explains when to reach for it.

A real Project Graph query from Semitexa Demo

Take the original Framework blog index, which now redirects to the canonical articles on semitexa.com. Its BlogIndexPayload still declares the old route, and BlogIndexHandler handles that payload. The following query examines that Demo module relationship:

bin/semitexa ai:review-graph:query \
  --usages='Semitexa\Demo\Application\Payload\Request\BlogIndexPayload' \
  --compact --json

The result names BlogIndexHandler and labels the relationship handles. Querying the handler's dependencies also reveals BlogIndexResource as its produced response and TypedHandlerInterface as an implemented contract. These are relationships derived from real code, not a diagram that someone must update by hand.

For a wider view, ai:review-graph:show renders a module slice, while ai:review-graph:module Demo --include-events --include-flows --format=json packages a module overview. The inspection demo shows these commands and the questions each one answers.

Check impact before the edit, then give AI the right context

Finding a direct user is only the first step. ai:review-graph:impact walks downstream relationships and groups affected nodes by distance and module. In the Demo graph used for this example, asking about BlogIndexPayload identifies BlogIndexHandler at distance one:

bin/semitexa ai:review-graph:impact \
  'Semitexa\Demo\Application\Payload\Request\BlogIndexPayload' \
  --depth=2 --json

That small result is useful precisely because it is specific. A shared interface or service can produce a much wider radius. Check the result before changing a contract, rather than assuming the file you opened is the whole change surface.

The same package can prepare focused context for a task with ai:review-graph:context. For impact work, --context adds relevant source snippets, and --prompt=review shapes them for a review. This helps an assistant reason from the affected structure instead of starting with an oversized prompt:

bin/semitexa ai:review-graph:impact \
  'Semitexa\Demo\Application\Payload\Request\BlogIndexPayload' \
  --context --prompt=review

The impact and context demo walks through this workflow and the package's watch mode for long editing sessions.

A practical Project Graph workflow

1. Start with the change you need to make. Name the route, class, event, or module involved.
2. Ask one structural question. Use query --usages or --dependencies for direct relationships, module for a broader view, or impact for downstream effects.
3. Check freshness. Read stats and refresh with generate when the stored graph no longer reflects the files relevant to your task. Watch mode can keep it current during a long session.
4. Verify behavior after the edit. The graph describes structure extracted from code. It cannot prove that every runtime path or test still works.

This is where Project Graph earns its place in Semitexa: the same architecture map serves onboarding, refactoring, code review, and AI-assisted work. It gives each task a narrow, inspectable starting point while keeping the source code and tests as the final authority.

Project Graph FAQ

Is Semitexa Project Graph required for every application?

No. It is an optional package for repositories where structural queries, impact analysis, and task context pay for themselves.

Is a project graph the same as a text search?

No. Text search finds matching bytes. A graph query follows typed relationships between code entities, such as which handler consumes a payload.

Does Project Graph replace tests?

No. It estimates structural reach from the graph it has built. Run tests and runtime checks to verify actual behavior after changing code.

How does the graph help an AI coding assistant?

It can supply a task-specific view of relevant nodes, edges, and source snippets. That makes a review or implementation prompt more focused and easier to inspect.