home / skills / makfly / superpowers-symfony / api-platform-state-providers

api-platform-state-providers skill

This skill helps you define explicit API Platform state provider contracts in Symfony, ensuring secure, versioned operations and consistent serialization.

npx playbooks add skill makfly/superpowers-symfony --skill api-platform-state-providers

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.3 KB

---
name: symfony:api-platform-state-providers
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Deliver robust API Platform contracts in Symfony with explicit operations, mapping, and policy-safe behavior. Use for api platform state providers tasks.
---

# Api Platform State Providers (Symfony)

## Use when
- Designing or evolving API Platform contracts and operations.
- Aligning serialization, validation, and security behavior.

## Default workflow
1. Define operation-level contract and payload boundaries.
2. Implement resource/DTO/provider/processor changes with explicit mapping.
2. Apply operation-specific validation and security constraints.
2. Validate functional behavior across happy and negative paths.

## Guardrails
- Keep API contract explicit and version-aware.
- Avoid exposing internal entity fields implicitly.
- Prevent drift between docs and actual serialization.

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

## Output contract
- API artifacts changed (resource/DTO/provider/processor).
- Contract/security decisions and rationale.
- Functional verification results.

## References
- `reference.md`
- `docs/complexity-tiers.md`

Overview

This skill helps design and implement API Platform state providers in Symfony with clear operation contracts, explicit mapping, and policy-safe behavior. It focuses on aligning serialization, validation, and security per operation to prevent contract drift and accidental data exposure. Use it to deliver predictable API behavior and verifiable changes to resources, DTOs, providers, and processors.

How this skill works

The skill inspects each API operation and enforces an operation-level contract that defines payload boundaries, mapping rules, and validation scopes. It guides implementation of resource/DTO changes, provider and processor wiring, and operation-specific security checks. Outputs include the artifacts changed, the contract and security decisions with rationale, and functional verification results for happy and negative paths.

When to use it

Designing or evolving API Platform contracts and operation behavior
Aligning serialization and validation to prevent inconsistent public representations
Implementing explicit mapping between entities and DTOs for security reasons
Introducing or tightening operation-specific security or validation rules
Preventing documentation and runtime serialization from drifting apart

Best practices

Define operation-level contracts before changing resources or DTOs
Keep public payloads explicit and version-aware to avoid accidental leaks
Apply validation and security at the operation boundary, not only on entities
Use dedicated providers/processors per operation for clear responsibilities
Document the contract and the rationale for any security choices

Example use cases

Create a read-only DTO and provider for public listing while keeping entity fields private
Introduce a create operation with a dedicated processor that enforces business rules and validation
Migrate an existing endpoint to a new versioned contract without breaking clients
Restrict fields returned for sensitive operations via explicit serialization groups
Validate negative paths and security failures as part of CI functional checks

FAQ

What output should I expect when using this skill?

You get a list of changed artifacts (resources, DTOs, providers, processors), the contract and security decisions with rationale, and functional verification results for both happy and negative paths.

How does this prevent exposing internal entity fields?

By requiring explicit DTOs, mapping rules, and serialization groups per operation, it avoids implicit exposure and enforces version-aware public contracts.