Laravel and Symfony projects are great places to use AI agents. Not because PHP is "easy" (it isn't), but because PHP backends carry a lot of real business logic. Controllers, services, console commands, queue jobs, Doctrine repositories, Eloquent models, event listeners, validators, policies, migrations, and tests all coexist in one repo, and the relationships between them are exactly the kind of context that's expensive for a human to load and cheap for a careful agent to map.
The best use of an agent in a PHP codebase is not "generate me random code." It's closer to:
Help me understand this backend flow.
Help me protect behavior.
Help me find missing tests.
Help me review risky queries.
Help me document what this code actually does.
That's where AI becomes a codebase partner instead of a code typist. A good Laravel/Symfony agent should work like a careful senior assistant. It inspects files, maps flows, explains side effects, suggests tests, reviews ORM queries, and only edits code when you explicitly allow it. This article walks through practical workflows for that kind of agent, in a way that doesn't turn your codebase into a guessing game.
Start With Understanding, Not Editing
A good agent should first answer "what does this code do?" before it ever asks "what code should I write?" That ordering matters more in PHP than in most languages, because Laravel and Symfony hide a lot of behavior behind facades, service containers, and event listeners. Reading a controller in isolation tells you almost nothing about what actually happens when the route fires.
Take this Laravel controller:
final class SubscriptionController
{
public function cancel(Request $request, int $subscriptionId): JsonResponse
{
$subscription = Subscription::query()
->where('user_id', $request->user()->id)
->findOrFail($subscriptionId);
$this->subscriptionService->cancel($subscription, $request->boolean('immediately'));
return response()->json([
'status' => $subscription->status,
'ends_at' => $subscription->ends_at?->toISOString(),
]);
}
}
A weak prompt is "refactor this controller." It puts the agent in editing mode before it has any idea what the code is responsible for. A much better starting move is something like:
Analyze this Laravel controller and explain the backend flow.
Please identify:
- the HTTP entry point,
- request inputs,
- authorization assumptions,
- service calls,
- database reads/writes,
- events/jobs/emails that may happen downstream,
- response shape,
- behavior that should be protected by tests.
Do not edit code yet.
This is much safer, and it's the kind of prompt the agent can actually answer well. It might come back with something like:
The controller scopes the subscription by current user.
The `immediately` request parameter changes cancellation behavior.
The response shape includes `status` and `ends_at`.
The service may contain important side effects.
Tests should protect user scoping and response shape.
Now you understand the risk surface before refactoring: what the public contract is, what's hidden, and where tests need to land first.
Laravel Flow: Controllers, Services, Jobs, Commands
Laravel projects usually have several types of entry points to the same feature: routes/api.php, an HTTP controller, an Artisan command, a scheduled command, a queue job, an event listener, a webhook controller, a notification class. The same business operation often runs through more than one of these paths, and the surprising bugs live exactly where those paths diverge.
That makes "find every entry point" a high-value question for an agent:
Find every entry point related to subscription cancellation.
Search for:
- routes,
- controllers,
- services,
- jobs,
- commands,
- event listeners,
- notifications,
- tests.
Group the results by execution path.
For each path, explain what triggers it and what side effects it may cause.
This matters because changing only the controller may not change the real production path. For example:
final class CancelExpiredTrialsCommand extends Command
{
protected $signature = 'subscriptions:cancel-expired-trials';
public function handle(): int
{
Subscription::query()
->where('status', 'trialing')
->where('trial_ends_at', '<', now())
->each(fn (Subscription $subscription) =>
$this->subscriptionService->cancel($subscription, immediately: true)
);
return self::SUCCESS;
}
}
The same SubscriptionService::cancel() is called from both the API controller and a scheduled command, which means your tests need to cover both paths. An agent that maps the call graph for you will catch that even when grep wouldn't.
Symfony Flow: Controllers, Services, Commands, Doctrine
Symfony projects make dependencies more explicit through services and constructor injection, which is good news for an agent. There's less magic to chase. A typical controller looks like this:
final class CancelSubscriptionController
{
public function __construct(
private readonly SubscriptionCanceller $subscriptionCanceller,
private readonly SubscriptionRepository $subscriptionRepository,
) {}
public function __invoke(Request $request, string $id): JsonResponse
{
$subscription = $this->subscriptionRepository->findOwnedByUser(
$id,
$this->getUser()->getId(),
);
if (!$subscription) {
throw $this->createNotFoundException();
}
$this->subscriptionCanceller->cancel(
subscription: $subscription,
immediately: $request->query->getBoolean('immediately'),
);
return $this->json([
'status' => $subscription->status()->value,
'endsAt' => $subscription->endsAt()?->format(DATE_ATOM),
]);
}
}
A useful prompt for that kind of file:
Analyze this Symfony controller and related services.
Explain:
- which services are injected,
- which repository methods are used,
- how authorization is enforced,
- where Doctrine flush likely happens,
- which domain events or messages may be dispatched,
- which response fields are public API contracts,
- what tests should exist before refactoring.
The agent can help you trace from controller to service to repository, but it should always inspect the files, never assume behavior from the class names alone. Domain layers are full of services that look generic and do something very specific.
Generating PHPUnit Tests That Protect Behavior
AI can generate tests quickly, but quick isn't the goal. Random tests aren't enough. You want behavior-protecting tests, the kind that fail loudly when a refactor accidentally changes a side effect or a response contract.
For Laravel, that looks something like:
public function test_user_can_cancel_own_subscription(): void
{
Queue::fake();
Mail::fake();
$user = User::factory()->create();
$subscription = Subscription::factory()->create([
'user_id' => $user->id,
'status' => 'active',
]);
$response = $this
->actingAs($user)
->postJson("/api/subscriptions/{$subscription->id}/cancel", [
'immediately' => true,
]);
$response
->assertOk()
->assertJsonStructure([
'status',
'ends_at',
]);
$this->assertDatabaseHas('subscriptions', [
'id' => $subscription->id,
'status' => 'canceled',
]);
}
For Symfony, the same idea translated to its WebTestCase:
public function testUserCanCancelOwnSubscription(): void
{
$client = static::createClient();
$user = UserFactory::createOne();
$subscription = SubscriptionFactory::createOne([
'user' => $user,
'status' => SubscriptionStatus::Active,
]);
$client->loginUser($user->_real());
$client->request(
'POST',
sprintf('/api/subscriptions/%s/cancel', $subscription->getId()),
['immediately' => true],
);
self::assertResponseIsSuccessful();
$payload = json_decode($client->getResponse()->getContent(), true);
self::assertArrayHasKey('status', $payload);
self::assertArrayHasKey('endsAt', $payload);
}
When you ask an agent to produce tests like this, give it the rules up front:
Generate PHPUnit tests for this backend flow.
Rules:
- Protect current behavior before refactoring.
- Include authorization tests.
- Include failure cases.
- Include response shape checks.
- Include database assertions.
- Mock external services, but do not mock the domain logic.
- Explain why each test exists.
That last line is the important one. A test without a stated reason is often just noise. It pins behavior nobody intentionally chose, and the next refactor has to fight it.
Reviewing Eloquent Queries
AI agents are useful for reviewing Eloquent queries because ORM code can hide SQL problems that look fine at the call site. Take this example:
$orders = Order::query()
->where('status', 'paid')
->whereDate('created_at', now()->toDateString())
->get();
foreach ($orders as $order) {
echo $order->customer->email;
}
This looks simple, but it has two common issues. First, whereDate() may prevent efficient index usage because it applies a date expression to the column, so a normal created_at index can't be used. Second, $order->customer inside the loop triggers one extra query per order. Textbook N+1.
A safer rewrite:
$start = now()->startOfDay();
$end = now()->endOfDay();
$orders = Order::query()
->with('customer')
->where('status', 'paid')
->whereBetween('created_at', [$start, $end])
->get();
foreach ($orders as $order) {
echo $order->customer->email;
}
The prompt that gets you there:
Review this Eloquent query for performance.
Check:
- possible N+1 queries,
- missing eager loading,
- functions applied to indexed columns,
- filtering order,
- pagination issues,
- whether an index may help,
- whether the query loads too many rows.
Suggest the safest change first.
Do not change behavior silently.
The agent should explain the trade-off, not just rewrite the code. A "safer" query that quietly drops a row or changes ordering is not actually safer.
Reviewing Doctrine Queries
Doctrine can hide performance problems too, in slightly different shapes. A typical repository call:
$orders = $orderRepository->findBy([
'status' => OrderStatus::Paid,
]);
foreach ($orders as $order) {
echo $order->getCustomer()->getEmail();
}
If customer is lazy-loaded (the Doctrine default), this triggers one query for orders and then one query per customer. The query-builder version that fetches both in one shot:
$orders = $entityManager->createQueryBuilder()
->select('o', 'c')
->from(Order::class, 'o')
->join('o.customer', 'c')
->where('o.status = :status')
->setParameter('status', OrderStatus::Paid)
->getQuery()
->getResult();
Useful agent prompt for Doctrine:
Review this Doctrine query and related entity mappings.
Check:
- lazy loading that may cause N+1 queries,
- missing joins,
- hydration cost,
- pagination behavior,
- indexes needed by WHERE/JOIN columns,
- whether the query loads unnecessary associations.
Return:
- current behavior,
- likely SQL shape,
- performance risks,
- safest improvement,
- tests or profiling checks.
Detecting N+1 Issues
N+1 queries are one of the easiest performance bugs to introduce, and one of the easiest for an agent to catch, if you ask the right question. A Laravel example:
$users = User::query()->where('active', true)->get();
return $users->map(fn (User $user) => [
'id' => $user->id,
'team' => $user->team->name,
]);
Better, with eager loading:
$users = User::query()
->with('team')
->where('active', true)
->get();
A Symfony/Doctrine equivalent:
$users = $userRepository->findActiveUsers();
foreach ($users as $user) {
$teamName = $user->getTeam()->getName();
}
Better, with a join:
$queryBuilder
->select('u', 't')
->from(User::class, 'u')
->join('u.team', 't')
->where('u.active = true');
The prompt that catches these consistently:
Analyze this code for possible N+1 queries.
Look for:
- relationship access inside loops,
- lazy-loaded Doctrine associations,
- Eloquent relationship properties,
- serializers that access relations,
- API resources that access nested data,
- notifications or exports that loop over models.
For each possible N+1:
- show the line,
- explain why it may trigger extra queries,
- suggest eager loading or query change,
- mention possible memory trade-offs.
The memory trade-off is worth flagging out loud. Eager loading everything isn't always correct. A list endpoint that pulls 10,000 rows shouldn't also hydrate every related entity. The right fix depends on the call site.
Refactoring Legacy PHP In Small Steps
Legacy PHP often has large service methods that do five things at once. Something like:
public function processRefund(int $orderId, int $amount): void
{
$order = Order::findOrFail($orderId);
if ($order->status !== 'paid') {
throw new RuntimeException('Order is not refundable.');
}
if ($amount > $order->paid_amount) {
throw new RuntimeException('Refund amount is too high.');
}
$response = $this->gateway->refund($order->transaction_id, $amount);
if (!$response->successful()) {
Log::warning('Refund failed', ['order_id' => $order->id]);
throw new RuntimeException('Refund failed.');
}
$order->refunds()->create([
'amount' => $amount,
'gateway_reference' => $response->reference(),
]);
$order->update([
'refunded_amount' => $order->refunded_amount + $amount,
]);
event(new OrderRefunded($order));
Mail::to($order->user)->queue(new RefundProcessedMail($order));
}
Don't ask the agent to "rewrite this cleanly." That phrasing invites it to invent abstractions that don't match your domain. Ask it for an analysis first:
Analyze this legacy PHP method for safe refactoring.
First:
- summarize current behavior,
- list validation rules,
- list side effects,
- identify external services,
- identify events/emails/jobs,
- suggest characterization tests,
- propose a small-step refactor plan.
Do not change code yet.
A good plan back from the agent might look like this:
1. Add tests for non-paid order, amount too high, gateway failure, successful refund.
2. Extract refund eligibility checks into a private method.
3. Extract gateway refund call into a small method.
4. Keep event and email behavior unchanged.
5. Only then consider a dedicated RefundService.
That's how AI helps without creating chaos: small, testable steps in an order that keeps behavior intact between every commit.
Updating Documentation For Backend Flows
AI agents are excellent for documentation because they can read code paths and summarize them, which is exactly the work humans tend to skip. A solid prompt:
Create developer documentation for this backend flow.
Include:
- entry points,
- request parameters,
- main services,
- database tables changed,
- events/jobs/emails triggered,
- external APIs called,
- failure modes,
- tests that cover the flow.
Use plain English.
Do not invent behavior.
If something is uncertain, mark it as uncertain.
The output looks something like:
# Subscription Cancellation Flow
## Entry Points
- `POST /api/subscriptions/{id}/cancel`
- `subscriptions:cancel-expired-trials` scheduled command
## Main Service
`SubscriptionService::cancel()` handles cancellation rules.
## Side Effects
- Updates `subscriptions.status`
- May set `subscriptions.ends_at`
- Dispatches `SubscriptionCanceled`
- Queues cancellation email
## External APIs
The payment gateway may be called for immediate cancellation.
## Tests
- `CancelSubscriptionTest`
- `CancelExpiredTrialsCommandTest`
This kind of doc is gold for onboarding and maintenance. It surfaces the behavior the code already has without anyone needing to re-read the whole module.
A Practical Agent Setup For PHP Teams
A useful PHP agent doesn't need unlimited access. The pattern that works well is a tiered set of tools. Read-only by default, safe execution where it pays off, and write access only behind a confirmation:
Read-only tools:
- search codebase,
- read file,
- list routes,
- inspect composer.json,
- inspect migrations,
- inspect tests.
Safe execution tools:
- run PHPUnit,
- run PHPStan/Psalm,
- run PHP CS Fixer in dry-run mode,
- run Doctrine schema validation,
- run Laravel route:list.
Write tools with approval:
- edit files,
- create tests,
- update docs,
- create PR summary.
Blocked by default:
- deploy,
- run arbitrary shell,
- access production secrets,
- modify .env,
- change CI secrets,
- merge PRs.
This gives the agent enough power to help, but not enough to damage the system. The agent that can grep your code and run your tests is already a senior collaborator; the one with deploy keys is just a liability.
Final Thoughts
The best Laravel/Symfony workflow with AI is not "AI writes code, developer hopes it works." It's closer to:
AI maps the flow.
AI finds risks.
AI suggests tests.
AI reviews queries.
AI documents behavior.
Developer decides and approves changes.
That's where AI fits naturally into senior backend development. Use agents to understand services, controllers, jobs, commands, Doctrine, Eloquent, tests, and documentation. Let them shorten the time it takes to load context. Don't let them replace judgment.
In PHP projects, the most valuable agent is not the one that writes the most code. It's the one that helps you change less code, more safely.
Originally published at nazarboyko.com.