api-platform-crud

Original source / Raw SKILL.md

---
name: api-platform-crud
description: Create complete REST API CRUD operations using API Platform 4 with DDD and CQRS patterns. Use when adding new API resources, implementing CRUD endpoints, creating DTOs, configuring operations, or setting up state processors. Follows the repository's hexagonal architecture with YAML resource configuration and command bus pattern.
---

# 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!"

---

## Quick Start: Complete CRUD in 10 Steps

> **Full Implementation Example**: See [examples/complete-customer-crud.md](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` with field mappings and indexes.

**See**: [database-migrations](../database-migrations/SKILL.md) 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](reference/dto-validation-patterns.md)

### Step 4: Configure Validation

Create `config/validator/{Entity}.yaml` with validation rules for each DTO.

### Step 5: Create API Platform Resource Configuration

Create `config/api_platform/resources/{entity}.yaml`:

```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](reference/configuration-patterns.md) for detailed patterns.

### Step 6: Configure Serialization Groups

Create `config/serialization/{Entity}.yaml` to control which fields are exposed.

### 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](../implementing-ddd-architecture/SKILL.md) 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](../database-migrations/SKILL.md) skill for repository patterns.

### Step 10: Configure Filters (Optional)

Add filters in `config/services.yaml` for search, ordering, etc.

**See**: [reference/filters-and-pagination.md](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](reference/configuration-patterns.md) for detailed architecture.

---

## Constraints

### 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

```bash
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](../implementing-ddd-architecture/SKILL.md) - DDD patterns and CQRS
- [deptrac-fixer](../deptrac-fixer/SKILL.md) - Fix architectural violations
- [database-migrations](../database-migrations/SKILL.md) - MongoDB entity management
- [developing-openapi-specs](../developing-openapi-specs/SKILL.md) - OpenAPI documentation
- [testing-workflow](../testing-workflow/SKILL.md) - Write E2E tests for endpoints

---

## Quick Commands

```bash
# Clear cache after config changes
make cache-clear

# Generate OpenAPI spec
make generate-openapi-spec

# Validate architecture
make deptrac

# Run E2E tests
make e2e-tests

# Full CI check
make ci
```

---

## Reference Documentation

For detailed patterns and examples:

- **[Configuration Patterns](reference/configuration-patterns.md)** - YAML config, operations, pagination, IRI resolution
- **[DTO & Validation Patterns](reference/dto-validation-patterns.md)** - DTO design, validation rules, exception handling
- **[Filters & Pagination](reference/filters-and-pagination.md)** - Search filters, sorting, pagination config
- **[Troubleshooting](reference/troubleshooting.md)** - Common issues and solutions
- **[Complete Example](examples/complete-customer-crud.md)** - Full Customer CRUD implementation

---

## Template Syntax

Throughout documentation, placeholders follow these conventions:

| Placeholder  | Example            | Usage                         |
| ------------ | ------------------ | ----------------------------- |
| `{Entity}`   | `Customer`         | PascalCase class name         |
| `{Context}`  | `Customer`         | Bounded context/module name   |
| `{entity}`   | `customer`         | Lowercase for configs/filters |
| `{entities}` | `customers`        | Plural for collection names   |
| `{Action}`   | `Create`, `Update` | Command action verb           |