Request Lifecycle Tracer

Overview

Traces the complete lifecycle of an HTTP request or CLI command through all application layers — from entry point through middleware, handler, business logic, persistence, and back to response. Documents the full chain with data transformations at each step.

Tracing Process

Step 1: Identify the Request Entry

# Find route definition for the target endpoint
Grep: "#\\[Route\\(" --glob "**/*.php" -A 2
Grep: "Route::(get|post|put|delete)" --glob "**/routes/*.php"

# Find the handler for this route
# Read the route config or controller to identify the handler method

Step 2: Trace Middleware Stack

# Symfony middleware (event listeners on kernel.request)
Grep: "kernel.request|kernel.controller|kernel.response" --glob "**/*.php"
Grep: "implements EventSubscriberInterface" --glob "**/*.php"

# Laravel middleware
Grep: "class.*Middleware" --glob "**/Middleware/**/*.php"
Grep: "'middleware'" --glob "**/Kernel.php"

# PSR-15 middleware
Grep: "implements MiddlewareInterface" --glob "**/*.php"

# Authentication middleware
Grep: "authenticat|JWT|Bearer|token" --glob "**/Middleware/**/*.php"

# Authorization middleware
Grep: "authoriz|permission|role|access" --glob "**/Middleware/**/*.php"

Step 3: Trace Controller/Action

# Read the handler method
Read: controller/action file

# Find what it receives (Request object/DTO)
Grep: "function.*\\(.*Request|function.*\\(.*DTO|function.*\\(.*Command" in handler

# Find what it calls (service/use case)
Grep: "\\$this->.*->handle|\\$this->.*->execute|\\$this->.*->dispatch" in handler

# Find response construction
Grep: "return.*Response|return.*JsonResponse|return.*json\\(" in handler

Step 4: Trace Use Case / Service

# Read the use case/service method
Read: use case file

# Find domain operations
Grep: "\\$this->.*Repository->find|\\$this->.*->save" in use case

# Find domain method calls
Grep: "\\$.*->create|\\$.*->update|\\$.*->process" in use case

# Find event dispatching
Grep: "dispatch|publish|raise" in use case

Step 5: Trace Repository Operations

# Read repository implementation
Grep: "implements.*Repository" --glob "**/Infrastructure/**/*.php"

# Find query patterns
Grep: "->createQueryBuilder|->find\\(|->findOneBy" in repository

# Find persistence operations
Grep: "->persist|->flush|->save|->insert|->update" in repository

Step 6: Trace Response Construction

# Response mapping
Grep: "->toArray|->toResponse|->jsonSerialize" in handler/response class

# Error responses
Grep: "ExceptionListener|ExceptionHandler|ErrorHandler" --glob "**/*.php"

# HTTP status codes used
Grep: "Response\\(.*[0-9]{3}|status.*[0-9]{3}|HTTP_" --glob "**/*.php"

Output Format

## Request Lifecycle

### Endpoint: POST /api/orders

#### Route Definition
- **Method:** POST
- **Path:** /api/orders
- **Controller:** `CreateOrderAction::__invoke`
- **Route file:** `config/routes/api.yaml:15`

#### Request Flow

Client Request (POST /api/orders, JSON body) │ ▼ [1] Router (matches POST /api/orders → CreateOrderAction) │ ▼ [2] Middleware Stack ├── CorsMiddleware — adds CORS headers ├── AuthenticationMiddleware — validates JWT token ├── RateLimitMiddleware — checks rate limits └── JsonRequestMiddleware — parses JSON body │ ▼ [3] Controller/Action: CreateOrderAction::__invoke(CreateOrderRequest $request) │ Input: CreateOrderRequest (validated DTO) │ - customerId: string (from JWT) │ - items: array [{productId, quantity}] │ - shippingAddress: {street, city, zip} │ ▼ [4] Use Case: CreateOrderUseCase::execute(CreateOrderCommand $command) │ Transforms: CreateOrderRequest → CreateOrderCommand │ ├── [4a] CustomerRepository::find(customerId) │ Returns: Customer entity │ ├── [4b] ProductRepository::findByIds(productIds) │ Returns: Product[] entities │ ├── [4c] Order::create(customer, items, address) │ Domain logic: validates, calculates total │ Raises: OrderCreated event │ ├── [4d] OrderRepository::save(order) │ Persists: INSERT into orders + order_items │ └── [4e] EventBus::dispatch(OrderCreated) Async: sends to message queue │ ▼ [5] Response Construction │ Transforms: Order entity → OrderResponse DTO │ OrderResponse: {id, status, total, items[], createdAt} │ ▼ [6] HTTP Response Status: 201 Created Headers: Content-Type: application/json, Location: /api/orders/{id} Body: {"id": "...", "status": "pending", "total": 150.00, ...}

#### Error Paths

| Error | Where | HTTP Status | Response |
|-------|-------|-------------|----------|
| Invalid JSON | Middleware [2] | 400 | {"error": "Invalid JSON"} |
| Unauthorized | Middleware [2] | 401 | {"error": "Token expired"} |
| Validation fail | Action [3] | 422 | {"errors": {"items": "..."}} |
| Customer not found | UseCase [4a] | 404 | {"error": "Customer not found"} |
| Out of stock | Domain [4c] | 409 | {"error": "Product out of stock"} |
| DB error | Repository [4d] | 500 | {"error": "Internal error"} |

#### Data Transformation Chain

JSON Body → CreateOrderRequest (DTO) → CreateOrderCommand (CQRS Command) → Order Entity (Domain) → OrderResponse (DTO) → JSON Response

#### Key Files in Chain

| Step | File | Line | Purpose |
|------|------|------|---------|
| Route | config/routes/api.yaml | 15 | Route definition |
| Action | src/Api/Action/CreateOrderAction.php | 22 | HTTP handler |
| Request | src/Api/Request/CreateOrderRequest.php | 1 | Input validation |
| Command | src/Application/Command/CreateOrderCommand.php | 1 | CQRS command |
| UseCase | src/Application/UseCase/CreateOrderUseCase.php | 15 | Orchestration |
| Entity | src/Domain/Order/Order.php | 45 | Domain logic |
| Repo | src/Infrastructure/Repository/DoctrineOrderRepo.php | 30 | Persistence |
| Response | src/Api/Response/OrderResponse.php | 1 | Output mapping |

Lifecycle Quality Indicators

Indicator	Good	Warning
Input validation	At boundary (Request/DTO)	In controller logic
Business logic	In Domain/UseCase	In controller
Error handling	Exception handler	Try-catch everywhere
Response mapping	Dedicated Response class	Array building in controller
Side effects	Via events (async)	Direct calls in handler

Integration

This skill is used by:

• data-flow-analyst

  — provides lifecycle documentation

• trace-data-transformation

  — traces DTO transformations

• explain-business-process

  — maps processes to request flows