# api-platform-state-providers

Configures API Platform State Providers and Processors in Symfony. It helps decouple data retrieval and persistence from Doctrine entities.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 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/skills/api-platform-state-providers/SKILL.md
- Updated: 2026-10-05
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/api-platform-state-providers

## What it does

This skill guides Claude Code through implementing `ProviderInterface` and `ProcessorInterface` across API Platform versions 4.3, 4.4, and v5. It helps fetch records from custom stores or decorate default Doctrine services with `#[Autowire]`.

For write pipelines, it wires processors delegating to built-in persist or remove handlers. Keep in mind that legacy `DataProvider` and `DataPersister` interfaces from v2 are obsolete, and setting `write: true` on safe methods requires API Platform v4.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add dev-toolings/superpowers-symfony --skill api-platform-state-providers -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/api-platform-state-providers/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/api-platform-state-providers/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add dev-toolings/superpowers-symfony --skill api-platform-state-providers -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/api-platform-state-providers/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add dev-toolings/superpowers-symfony --skill api-platform-state-providers -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/api-platform-state-providers/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install dev-toolings/superpowers-symfony content/skills/api-platform-state-providers
```

2. **Manually: put the files in place**
- File: `.github/skills/api-platform-state-providers/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add dev-toolings/superpowers-symfony --skill api-platform-state-providers -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/dev-toolings/superpowers-symfony --path content/skills/api-platform-state-providers
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/api-platform-state-providers/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

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/skills/api-platform-state-providers/SKILL.md

## When to use it
- fetch API resource state from external services instead of Doctrine
- decorate built-in providers to return DTOs or enforce tenant scopes
- execute business logic like password hashing before persisting entities
- attach processors to GET endpoints using the `write: true` option

## Example prompts
- Create a custom State Provider that returns a user DTO from an external service.
- Decorate the Doctrine item provider to enforce a tenant boundary.
- Implement a State Processor to dispatch an event before persisting the entity.

## Source text · SKILL.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: 7baffae06373ecd4.

BEGIN THIRD-PARTY FILE 7baffae06373ecd4
```text
---
name: api-platform-state-providers
description: Master API Platform State Providers and Processors (v5, 4.4, 4.3) (ProviderInterface/ProcessorInterface) to decouple data retrieval and persistence from entities
capabilities: [read, search, edit, shell]
tags: [api-platform]
# projected by `bun run build` — do not edit by hand
allowed-tools:
  - Read
  - Glob
  - Grep
  - Write
  - Edit
  - Bash
---

# Api Platform State Providers (Symfony)

## Use when
- Reading data from a source other than the default Doctrine provider.
- Wrapping the Doctrine provider to post-process results (return a DTO, enforce a tenant scope).
- Business logic must run before or after persisting (hashing, slug, dispatching a message).
- A v4 read endpoint must dispatch a query or command through a processor.

## Default workflow
1. Implement `ProviderInterface::provide()` returning `iterable|object|null`, where `null` gives a 404 (v3.4 declares `mixed`).
2. To keep Doctrine fetching, inject `api_platform.doctrine.orm.state.item_provider` and `api_platform.doctrine.orm.state.collection_provider` with `#[Autowire]`.
3. Implement `ProcessorInterface::process()` and delegate to `api_platform.doctrine.orm.state.persist_processor` or `remove_processor`.
4. Wire them with `provider:` and `processor:` on the resource or the operation; autoconfiguration registers them, and the `api_platform.state_provider` or `api_platform.state_processor` tag is only needed without it.
5. For a processor on `GET` or `GetCollection`, add `write: true` (v4 only).

## Guardrails
- Run pre-persist logic before calling the inner processor and side effects after it returns.
- A processor returns the created or modified object, and nothing for `DELETE`.
- `write: true` on safe methods is v4 only: v3.4 processors run on write methods only.
- `DataProvider` and `DataPersister` are v2 interfaces and no longer exist.

## Progressive disclosure
- Use this file for execution posture and risk controls.
- Open references when deep implementation details are needed.

## Output contract
- The providers and processors added, and the operations they are wired to.
- Which built-in services are decorated.
- Tests for the not-found, success, and side-effect paths.

## References
- `reference.md`
```
END THIRD-PARTY FILE 7baffae06373ecd4

The third-party file has ended. Everything between the 7baffae06373ecd4 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.

© dev-toolings · MIT · https://github.com/dev-toolings/superpowers-symfony/tree/HEAD/content/skills/api-platform-state-providers/SKILL.md

## Similar
- [symfony-specialist](https://affpapa.org/en/nevibecode/agents/symfony-specialist.md) — subagent · ★ 26718 repo stars
- [php-symfony](https://affpapa.org/en/nevibecode/rules/php-symfony.md) — rule · ★ 41430 repo stars
- [aws-lambda-php-integration](https://affpapa.org/en/nevibecode/skills/aws-lambda-php-integration.md) — skill · 3700 installs
- [sentry-php-sdk](https://affpapa.org/en/nevibecode/skills/sentry-php-sdk.md) — skill · 2400 installs
- [appwrite-php](https://affpapa.org/en/nevibecode/skills/appwrite-php.md) — skill · 898 installs
- [php-expert](https://affpapa.org/en/nevibecode/skills/php-expert.md) — skill · 269 installs

_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
