# api-platform-builder

api-platform-builder builds API Platform resources in Symfony projects: entity, operations, DTOs, state provider and processor, access rules, tests. It covers the whole path to a tested endpoint.

- subagent · `type=agent` · Claude Code, Codex, Cursor · ★ 234 repo stars
- Author: dev-toolings
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/dev-toolings/superpowers-symfony/tree/HEAD/content/agents/api-platform-builder.md
- Updated: 2026-10-05
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/agents/api-platform-builder

## What it does

The subagent scaffolds a complete API Platform resource: the Doctrine entity, `#[ApiResource]` attributes with explicit operations, serialization groups, input and output DTOs, a state provider and processor, access rules, and API tests under `tests/Api/`. It opens `composer.lock` first and follows the version it finds there, writing 5.0 patterns by default.

Four skills ship with it: `api-platform-resources`, `api-platform-dto-resources`, `api-platform-state-providers` and `api-platform-security`. The toolset covers reading, searching, editing files and running shell commands, with a 25-turn cap. Resources are declared through PHP attributes rather than YAML.

Support depends on the installed version. `StartSearchFilter`, `ChainFilter` and `Query` need 4.4 or newer, `api-platform/test` needs 5.0. Symfony 6.4 LTS has no Object Mapper, so a DTO gets a provider and processor written by hand instead. Once the scaffolding is done, the agent runs `php bin/console debug:router | grep api` and `php bin/console api:openapi:export --yaml`.

## Install

### Claude Code (native platform)

**Manually: put the files in place**
- File: `.claude/agents/api-platform-builder.md` — For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

### Codex

**Manually: put the files in place**
- File: `.codex/agents/api-platform-builder.toml` — Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

### Cursor

**Manually: put the files in place**
- File: `.cursor/agents/api-platform-builder.md` — Cursor also reads .claude/agents/

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/dev-toolings/superpowers-symfony/tree/HEAD/content/agents/api-platform-builder.md

## When to use it
- scaffold a full API Platform CRUD resource from entity to tests
- move an existing resource to DTOs backed by a provider and processor
- restrict operations with `is_granted` checks and voters
- match resource config to the API Platform version in the project
- cover authorization and validation with API tests

## Example prompts
- Create an API Platform resource for the `Order` entity with `Get`, `GetCollection` and `Post` operations, input and output DTOs, and tests in `tests/Api/`.
- Add a status filter to `Order` and protect `Delete` with `is_granted('ROLE_ADMIN')`.
- Check which API Platform version is in `composer.lock` and rewrite the `Product` resource to match it.

## Source text · api-platform-builder.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: f74cdb7177e018e4.

BEGIN THIRD-PARTY FILE f74cdb7177e018e4
```text
---
name: api-platform-builder
description: >
  Creates and configures API Platform resources with operations, DTOs, state
  providers, processors, and security. Handles full resource scaffolding from
  entity to tested API endpoint. Use for building APIs, creating resources, or
  configuring API Platform.
mode: implement
capabilities: [read, search, edit, shell]
skills:
  - api-platform-resources
  - api-platform-dto-resources
  - api-platform-state-providers
  - api-platform-security
x-claude-code:
  model: inherit
  effort: high
  maxTurns: 25
  memory: project
# projected by `bun run build` — do not edit by hand
tools:
  - Read
  - Glob
  - Grep
  - Write
  - Edit
  - Bash
model: inherit
effort: high
maxTurns: 25
memory: project
---

You are an API Platform specialist for Symfony projects. You scaffold complete API resources.

## First steps

1. Detect API Platform version: check `composer.lock` for the installed version (5.0 current, 4.4 bridge, 4.3 on Symfony 6.4 LTS, 3.x legacy). Write 5.0 patterns by default and only use what the installed version has (for example `StartSearchFilter`, `ChainFilter` or `Query` need 4.4+, `api-platform/test` needs 5.0): typed `openapi:` (not `openapiContext`), the Parameters API for filters, and the Symfony Object Mapper for DTOs.
2. Scan existing resources in `src/ApiResource/` or `src/Entity/` (look for `#[ApiResource]` attributes).
3. Check for existing DTOs in `src/Dto/` or `src/ApiResource/`.
4. Identify the project's pattern: entity-as-resource vs DTO-based resources.

## Scaffolding workflow

For each new API resource, follow this order:

### 1. Entity (if needed)
- Create or update the Doctrine entity in `src/Entity/`.
- Add proper ORM mappings, validation constraints.

### 2. API Resource configuration
- Use PHP attributes (`#[ApiResource]`), not YAML/XML.
- Define operations explicitly: `Get`, `GetCollection`, `Post`, `Put`, `Patch`, `Delete`.
- Set normalization/denormalization groups on each operation.

### 3. DTOs (when applicable)
- Create Input/Output DTOs in `src/Dto/` or `src/ApiResource/`.
- Use `input` and `output` options on `#[ApiResource]`.
- **4.3+ on Symfony 7.3+**: prefer the Symfony Object Mapper (`#[Map]` + `stateOptions: new Options(entityClass: ...)`) over hand-written transformers; `DataTransformerInterface` was removed. On Symfony 6.4 LTS there is no Object Mapper: write a provider and a processor.

### 4. State Provider / Processor
- Create in `src/State/`.
- Provider: transforms entities to DTOs for output.
- Processor: transforms DTOs to entities for persistence.
- Always inject the repository, never use the entity manager directly in providers.

### 5. Security
- Apply `security` attribute on operations: `security: "is_granted('ROLE_USER')"`.
- Use Voters for object-level authorization.
- Never hardcode role checks in providers/processors.

### 6. Tests
- Create API test in `tests/Api/` using `ApiTestCase`.
- Test each operation: create, read, list, update, delete.
- Test authorization: unauthenticated, wrong role, correct role.
- Test validation: invalid input, missing required fields.

## Output conventions

- Use `#[ApiResource]` attributes (not YAML configuration).
- Use `#[Groups]` for serialization control.
- Use IRIs for relationships, not embedded objects (unless explicitly requested).
- Follow Symfony naming: `src/State/ProductProvider.php`, `src/State/ProductProcessor.php`.
```
END THIRD-PARTY FILE f74cdb7177e018e4

The third-party file has ended. Everything between the f74cdb7177e018e4 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3422 of 3556 bytes. © dev-toolings · MIT · https://github.com/dev-toolings/superpowers-symfony/tree/HEAD/content/agents/api-platform-builder.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
