API Platform CRUD Skill

Context (Input)

• Need to create new API resource with REST endpoints
• Implementing CRUD operations (Create, Read, Update, Delete)
• Adding DTOs for input/output transformation
• Configuring API Platform operations, filters, or pagination
• Working with state processors following CQRS pattern

Task (Function)

Implement production-ready REST API CRUD operations following DDD, CQRS, and hexagonal architecture patterns.

Success Criteria:

• All CRUD operations functional (POST, GET, PUT, PATCH, DELETE)
• DTOs properly validated
• Domain entities remain framework-agnostic
• Command bus pattern used for write operations

• make ci

  outputs "✅ CI checks successfully passed!"

Template examples reference MongoDB/Doctrine ODM. In this service, use Doctrine ORM with MySQL (

.orm.xml

mappings,

EntityManagerInterface

) while keeping the same layering and DTO/processor patterns.

Quick Start: Complete CRUD in 10 Steps

Full Implementation Example: See examples/complete-customer-crud.md for detailed code.

Step 1: Create Domain Entity

Create pure PHP entity in

src/Core/{Context}/Domain/Entity/{Entity}.php

• ❌ NO Doctrine annotations/attributes
• ❌ NO Symfony imports
• ❌ NO API Platform attributes
• ✅ Pure business logic only

Step 2: Create Doctrine XML Mapping

Create

config/doctrine/{Entity}.mongodb.xml

See: database-migrations skill for XML mapping patterns.

Step 3: Create Input DTOs

Create three DTOs in

src/Core/{Context}/Application/DTO/

• {Entity}Create

  - For POST requests

• {Entity}Put

  - For PUT requests (full update)

• {Entity}Patch

  - For PATCH requests (partial update)

See: reference/dto-validation-patterns.md

Step 4: Configure Validation

Create

config/validator/{Entity}.yaml

Step 5: Create API Platform Resource Configuration

Create

config/api_platform/resources/{entity}.yaml

App\Core\{Context}\Domain\Entity\{Entity}:
  shortName: { Entity }
  operations:
    ApiPlatform\Metadata\GetCollection: ~
    ApiPlatform\Metadata\Get: ~
    ApiPlatform\Metadata\Post:
      input: App\Core\{Context}\Application\DTO\{Entity}Create
      processor: App\Core\{Context}\Application\Processor\Create{Entity}Processor
    ApiPlatform\Metadata\Put:
      input: App\Core\{Context}\Application\DTO\{Entity}Put
      processor: App\Core\{Context}\Application\Processor\Update{Entity}Processor
    ApiPlatform\Metadata\Patch:
      input: App\Core\{Context}\Application\DTO\{Entity}Patch
      processor: App\Core\{Context}\Application\Processor\Patch{Entity}Processor
    ApiPlatform\Metadata\Delete: ~

See: reference/configuration-patterns.md for detailed patterns.

Step 6: Configure Serialization Groups

Create

config/serialization/{Entity}.yaml

Step 7: Create State Processors

Create processors in

src/Core/{Context}/Application/Processor/

• Create{Entity}Processor

  - Handles POST

• Update{Entity}Processor

  - Handles PUT

• Patch{Entity}Processor

  - Handles PATCH

Each processor:

1. Receives DTO
2. Transforms to Command
3. Dispatches via Command Bus
4. Returns resulting Entity

Step 8: Create Command and Handler

Create:

• Command in

  Application/Command/{Action}{Entity}Command.php

• Handler in

  Application/CommandHandler/{Action}{Entity}CommandHandler.php

Handler contains business logic and calls repository.

See: implementing-ddd-architecture for CQRS patterns.

Step 9: Create Repository

Create:

• Interface in

  Domain/Repository/{Entity}RepositoryInterface.php

• Implementation in

  Infrastructure/Repository/{Entity}Repository.php

• Register in

  config/services.yaml

See: database-migrations skill for repository patterns.

Step 10: Configure Filters (Optional)

Add filters in

config/services.yaml

See: reference/filters-and-pagination.md

Architecture Flow

REST Request → API Platform
            ↓
        Processor (Application)
            ↓
        DTO → Transformer → Command
            ↓
        Command Bus
            ↓
        Handler (Application)
            ↓
        Entity (Domain) ← Repository (Infrastructure)
            ↓
        MongoDB

See: reference/configuration-patterns.md for detailed architecture.

Constraints (Parameters)

NEVER

• Add framework annotations/attributes to Domain entities
• Put business logic in Processors (use Handlers)
• Skip validation configuration
• Use PHP attributes for API Platform config (use YAML)
• Violate layer boundaries (check with

  make deptrac

  )
• Skip DTO transformation (direct Entity manipulation)

ALWAYS

• Keep Domain entities framework-agnostic
• Use YAML for all configuration (validation, serialization, resources)
• Dispatch Commands via Command Bus for write operations
• Create separate DTOs for Create, Put, and Patch
• Follow IRI pattern for entity references
• Run

  make ci

  before committing

Format (Output)

Expected API Endpoints

GET    /api/{entities}           # List all
GET    /api/{entities}/{id}      # Get one
POST   /api/{entities}           # Create
PUT    /api/{entities}/{id}      # Full update
PATCH  /api/{entities}/{id}      # Partial update
DELETE /api/{entities}/{id}      # Delete

Expected OpenAPI Spec

make generate-openapi-spec
# Generates .github/openapi-spec/spec.yaml

Expected CI Result

✅ CI checks successfully passed!

Verification Checklist

After implementation:

• Domain entity created (no framework imports)
• Doctrine XML mapping configured
• Three DTOs created (Create, Put, Patch)
• Validation rules configured in YAML
• API Platform resource YAML created
• Serialization groups configured
• State Processors created for write operations
• Commands and Handlers implemented
• Repository interface and implementation created
• Filters configured (if needed)
• Resource directory registered in

  api_platform.yaml

• All endpoints respond correctly (test with Postman/Behat)
• Validation works (test invalid inputs)

• make deptrac

  passes (no violations)

• make ci

  passes (all checks green)
• OpenAPI spec generated successfully

Related Skills

• implementing-ddd-architecture - DDD patterns and CQRS
• deptrac-fixer - Fix architectural violations
• database-migrations - MongoDB entity management
• openapi-development - OpenAPI documentation
• testing-workflow - Write E2E tests for endpoints

Quick Commands

# Clear cache after config changes
make cache-clear

# Generate OpenAPI spec
make generate-openapi-spec

# Validate architecture
make deptrac

# Run E2E tests
make behat

# Full CI check
make ci

Reference Documentation

For detailed patterns and examples:

• Configuration Patterns - YAML config, operations, pagination, IRI resolution
• DTO & Validation Patterns - DTO design, validation rules, exception handling
• Filters & Pagination - Search filters, sorting, pagination config
• Troubleshooting - Common issues and solutions
• Complete Example - Full Customer CRUD implementation

Template Syntax

Throughout documentation, placeholders follow these conventions:

{Entity}

Customer

{Context}

Customer

{entity}

customer

{entities}

customers

{Action}

Create

Update