Symfony 7 กับ API Platform: แนวทางปฏิบัติที่ดีที่สุดสำหรับ REST API

<?php
// src/Entity/Product.php
namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Post;
use ApiPlatform\Metadata\Put;
use ApiPlatform\Metadata\Delete;
use ApiPlatform\Metadata\Patch;
use App\State\ProductStateProcessor;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Serializer\Annotation\Groups;
use Symfony\Component\Validator\Constraints as Assert;

#[ORM\Entity]
#[ApiResource(
    operations: [
        new GetCollection(
            normalizationContext: ['groups' => ['product:list']]
        ),
        new Get(
            normalizationContext: ['groups' => ['product:read']]
        ),
        new Post(
            denormalizationContext: ['groups' => ['product:write']],
            processor: ProductStateProcessor::class
        ),
        new Patch(
            denormalizationContext: ['groups' => ['product:update']],
            security: "is_granted('PRODUCT_EDIT', object)"
        ),
        new Delete(
            security: "is_granted('PRODUCT_DELETE', object)"
        ),
    ]
)]
class Product
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    #[Groups(['product:list', 'product:read'])]
    private ?int $id = null;

    #[ORM\Column(length: 255)]
    #[Assert\NotBlank]
    #[Assert\Length(min: 2, max: 255)]
    #[Groups(['product:list', 'product:read', 'product:write', 'product:update'])]
    private string $name = '';

    #[ORM\Column(type: 'decimal', precision: 10, scale: 2)]
    #[Assert\Positive]
    #[Groups(['product:list', 'product:read', 'product:write', 'product:update'])]
    private string $price = '0.00';

    #[ORM\Column(type: 'text', nullable: true)]
    #[Groups(['product:read', 'product:write'])]
    private ?string $description = null;

    // Getters and setters...
}

<?php
// src/Entity/Order.php
namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use Doctrine\Common\Collections\ArrayCollection;
use Doctrine\Common\Collections\Collection;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Serializer\Annotation\Groups;
use Symfony\Component\Serializer\Annotation\MaxDepth;

#[ORM\Entity]
#[ApiResource(
    operations: [
        new GetCollection(
            normalizationContext: [
                'groups' => ['order:list'],
                'enable_max_depth' => true
            ]
        ),
        new Get(
            normalizationContext: [
                'groups' => ['order:read'],
                'enable_max_depth' => true
            ]
        ),
    ]
)]
class Order
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    #[Groups(['order:list', 'order:read'])]
    private ?int $id = null;

    #[ORM\ManyToOne(targetEntity: Customer::class)]
    #[Groups(['order:list', 'order:read'])]
    #[MaxDepth(1)]
    private ?Customer $customer = null;

    #[ORM\OneToMany(targetEntity: OrderItem::class, mappedBy: 'order', cascade: ['persist'])]
    #[Groups(['order:read'])]
    #[MaxDepth(1)]
    private Collection $items;

    #[ORM\Column(type: 'decimal', precision: 12, scale: 2)]
    #[Groups(['order:list', 'order:read'])]
    private string $totalAmount = '0.00';

    public function __construct()
    {
        $this->items = new ArrayCollection();
    }

    // Getters and setters...
}

<?php
// src/State/ProductStateProcessor.php
namespace App\State;

use ApiPlatform\Metadata\Operation;
use ApiPlatform\State\ProcessorInterface;
use App\Entity\Product;
use App\Service\InventoryService;
use App\Service\SlugGeneratorService;
use Doctrine\ORM\EntityManagerInterface;
use Psr\Log\LoggerInterface;

class ProductStateProcessor implements ProcessorInterface
{
    public function __construct(
        private readonly EntityManagerInterface $entityManager,
        private readonly InventoryService $inventoryService,
        private readonly SlugGeneratorService $slugGenerator,
        private readonly LoggerInterface $logger
    ) {}

    public function process(
        mixed $data,
        Operation $operation,
        array $uriVariables = [],
        array $context = []
    ): Product {
        /** @var Product $product */
        $product = $data;

        // Generate slug from name
        if ($product->getSlug() === null) {
            $product->setSlug(
                $this->slugGenerator->generate($product->getName())
            );
        }

        // Initialize inventory record
        if ($product->getId() === null) {
            $this->inventoryService->initializeForProduct($product);
        }

        $this->entityManager->persist($product);
        $this->entityManager->flush();

        $this->logger->info('Product processed', [
            'id' => $product->getId(),
            'name' => $product->getName(),
        ]);

        return $product;
    }
}

<?php
// src/State/ProductCollectionProvider.php
namespace App\State;

use ApiPlatform\Metadata\Operation;
use ApiPlatform\State\ProviderInterface;
use App\Entity\Product;
use App\Repository\ProductRepository;
use Symfony\Bundle\SecurityBundle\Security;

class ProductCollectionProvider implements ProviderInterface
{
    public function __construct(
        private readonly ProductRepository $productRepository,
        private readonly Security $security
    ) {}

    public function provide(
        Operation $operation,
        array $uriVariables = [],
        array $context = []
    ): iterable {
        $user = $this->security->getUser();

        // Different query logic based on user role
        if ($this->security->isGranted('ROLE_ADMIN')) {
            return $this->productRepository->findAll();
        }

        if ($this->security->isGranted('ROLE_VENDOR')) {
            return $this->productRepository->findByVendor($user);
        }

        // Public users see only published products
        return $this->productRepository->findPublished();
    }
}

<?php
// src/Security/Voter/ProductVoter.php
namespace App\Security\Voter;

use App\Entity\Product;
use App\Entity\User;
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Component\Security\Core\Authorization\Voter\Voter;

class ProductVoter extends Voter
{
    public const EDIT = 'PRODUCT_EDIT';
    public const DELETE = 'PRODUCT_DELETE';
    public const VIEW = 'PRODUCT_VIEW';

    protected function supports(string $attribute, mixed $subject): bool
    {
        return in_array($attribute, [self::EDIT, self::DELETE, self::VIEW])
            && $subject instanceof Product;
    }

    protected function voteOnAttribute(
        string $attribute,
        mixed $subject,
        TokenInterface $token
    ): bool {
        $user = $token->getUser();

        if (!$user instanceof User) {
            return false;
        }

        /** @var Product $product */
        $product = $subject;

        return match ($attribute) {
            self::VIEW => $this->canView($product, $user),
            self::EDIT => $this->canEdit($product, $user),
            self::DELETE => $this->canDelete($product, $user),
            default => false,
        };
    }

    private function canView(Product $product, User $user): bool
    {
        // Published products are visible to all authenticated users
        if ($product->isPublished()) {
            return true;
        }
        // Unpublished products only visible to owner or admin
        return $product->getOwner() === $user
            || in_array('ROLE_ADMIN', $user->getRoles());
    }

    private function canEdit(Product $product, User $user): bool
    {
        return $product->getOwner() === $user
            || in_array('ROLE_ADMIN', $user->getRoles());
    }

    private function canDelete(Product $product, User $user): bool
    {
        return in_array('ROLE_ADMIN', $user->getRoles());
    }
}

# config/packages/api_platform.yaml
api_platform:
    title: 'Product API'
    version: '1.0.0'
    formats:
        jsonld: ['application/ld+json']
        json: ['application/json']
        html: ['text/html']
    swagger:
        api_keys:
            JWT:
                name: Authorization
                type: header
    defaults:
        stateless: true
        cache_headers:
            vary: ['Content-Type', 'Authorization', 'Origin']
        extra_properties:
            standard_put: true
            rfc_7807_compliant_errors: true

# config/packages/security.yaml
security:
    providers:
        app_user_provider:
            entity:
                class: App\Entity\User
                property: email

    firewalls:
        dev:
            pattern: ^/(_(profiler|wdt)|css|images|js)/
            security: false

        login:
            pattern: ^/api/auth/login
            stateless: true
            json_login:
                check_path: /api/auth/login
                username_path: email
                password_path: password
                success_handler: lexik_jwt_authentication.handler.authentication_success
                failure_handler: lexik_jwt_authentication.handler.authentication_failure

        api:
            pattern: ^/api
            stateless: true
            jwt: ~

    access_control:
        - { path: ^/api/auth/login, roles: PUBLIC_ACCESS }
        - { path: ^/api/docs, roles: PUBLIC_ACCESS }
        - { path: ^/api, roles: IS_AUTHENTICATED_FULLY }

<?php
// src/Filter/PriceRangeFilter.php
namespace App\Filter;

use ApiPlatform\Doctrine\Orm\Filter\AbstractFilter;
use ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface;
use ApiPlatform\Metadata\Operation;
use Doctrine\ORM\QueryBuilder;

final class PriceRangeFilter extends AbstractFilter
{
    protected function filterProperty(
        string $property,
        mixed $value,
        QueryBuilder $queryBuilder,
        QueryNameGeneratorInterface $queryNameGenerator,
        string $resourceClass,
        Operation $operation = null,
        array $context = []
    ): void {
        if ($property !== 'price_range') {
            return;
        }

        if (!isset($value['min']) && !isset($value['max'])) {
            return;
        }

        $alias = $queryBuilder->getRootAliases()[0];

        if (isset($value['min'])) {
            $minParam = $queryNameGenerator->generateParameterName('price_min');
            $queryBuilder
                ->andWhere(sprintf('%s.price >= :%s', $alias, $minParam))
                ->setParameter($minParam, $value['min']);
        }

        if (isset($value['max'])) {
            $maxParam = $queryNameGenerator->generateParameterName('price_max');
            $queryBuilder
                ->andWhere(sprintf('%s.price <= :%s', $alias, $maxParam))
                ->setParameter($maxParam, $value['max']);
        }
    }

    public function getDescription(string $resourceClass): array
    {
        return [
            'price_range[min]' => [
                'property' => 'price',
                'type' => 'float',
                'required' => false,
                'description' => 'Minimum price filter',
            ],
            'price_range[max]' => [
                'property' => 'price',
                'type' => 'float',
                'required' => false,
                'description' => 'Maximum price filter',
            ],
        ];
    }
}

<?php
// src/Entity/Product.php — เพิ่ม filter attribute
use ApiPlatform\Metadata\ApiFilter;
use ApiPlatform\Doctrine\Orm\Filter\SearchFilter;
use ApiPlatform\Doctrine\Orm\Filter\OrderFilter;
use App\Filter\PriceRangeFilter;

#[ApiResource(/* ... */)]
#[ApiFilter(SearchFilter::class, properties: [
    'name' => 'partial',
    'category.name' => 'exact'
])]
#[ApiFilter(OrderFilter::class, properties: ['name', 'price', 'createdAt'])]
#[ApiFilter(PriceRangeFilter::class)]
class Product
{
    // ...
}

<?php
// src/Entity/Product.php — Pagination configuration
#[ApiResource(
    operations: [
        new GetCollection(
            normalizationContext: ['groups' => ['product:list']],
            paginationEnabled: true,
            paginationItemsPerPage: 20,
            paginationMaximumItemsPerPage: 100,
            paginationClientItemsPerPage: true,
        ),
    ]
)]
class Product
{
    // ...
}

<?php
// src/Repository/ProductRepository.php
namespace App\Repository;

use App\Entity\Product;
use Doctrine\Bundle\DoctrineBundle\Repository\ServiceEntityRepository;
use Doctrine\Persistence\ManagerRegistry;

class ProductRepository extends ServiceEntityRepository
{
    public function __construct(ManagerRegistry $registry)
    {
        parent::__construct($registry, Product::class);
    }

    public function findPublished(): array
    {
        return $this->createQueryBuilder('p')
            ->where('p.published = :published')
            ->setParameter('published', true)
            ->orderBy('p.createdAt', 'DESC')
            ->getQuery()
            ->getResult();
    }

    public function findByVendor(mixed $vendor): array
    {
        return $this->createQueryBuilder('p')
            ->where('p.owner = :vendor')
            ->setParameter('vendor', $vendor)
            ->orderBy('p.createdAt', 'DESC')
            ->getQuery()
            ->getResult();
    }

    /**
     * Cursor-based pagination for large datasets.
     * @return Product[]
     */
    public function findAfterCursor(int $cursor, int $limit = 20): array
    {
        return $this->createQueryBuilder('p')
            ->where('p.id > :cursor')
            ->setParameter('cursor', $cursor)
            ->orderBy('p.id', 'ASC')
            ->setMaxResults($limit)
            ->getQuery()
            ->getResult();
    }
}

<?php
// src/Entity/Product.php — Cache configuration
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;

#[ApiResource(
    operations: [
        new GetCollection(
            cacheHeaders: [
                'max_age' => 60,
                'shared_max_age' => 120,
                'vary' => ['Authorization', 'Accept-Language'],
            ]
        ),
        new Get(
            cacheHeaders: [
                'max_age' => 300,
                'shared_max_age' => 600,
            ]
        ),
    ]
)]
class Product
{
    // ...
}

<?php
// src/Entity/Product.php — เพิ่ม cache invalidation tag
use ApiPlatform\Metadata\ApiResource;
use Symfony\Component\HttpFoundation\Response;

#[ApiResource(
    extraProperties: [
        'cache_headers' => [
            'vary' => ['Content-Type', 'Authorization'],
        ]
    ]
)]
class Product
{
    // ...
}

<?php
// src/Entity/User.php
namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Post;
use ApiPlatform\Metadata\Patch;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Serializer\Annotation\Groups;
use Symfony\Component\Validator\Constraints as Assert;

#[ORM\Entity]
#[ApiResource(
    operations: [
        new Post(
            denormalizationContext: ['groups' => ['user:create']],
            validationContext: ['groups' => ['Default', 'user:create']]
        ),
        new Patch(
            denormalizationContext: ['groups' => ['user:update']],
            validationContext: ['groups' => ['Default', 'user:update']],
            security: "is_granted('USER_EDIT', object)"
        ),
    ]
)]
class User
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    #[ORM\Column(length: 180, unique: true)]
    #[Assert\NotBlank]
    #[Assert\Email]
    #[Groups(['user:create', 'user:read'])]
    private string $email = '';

    #[ORM\Column]
    #[Assert\NotBlank(groups: ['user:create'])]
    #[Assert\Length(min: 8, groups: ['user:create', 'user:update'])]
    #[Groups(['user:create', 'user:update'])]
    private string $plainPassword = '';

    #[ORM\Column(length: 100)]
    #[Assert\NotBlank]
    #[Assert\Length(min: 2, max: 100)]
    #[Groups(['user:create', 'user:update', 'user:read'])]
    private string $displayName = '';

    // Getters and setters...
}

<?php
// src/Exception/InsufficientStockException.php
namespace App\Exception;

use Symfony\Component\HttpKernel\Exception\UnprocessableEntityHttpException;

class InsufficientStockException extends UnprocessableEntityHttpException
{
    public function __construct(
        private readonly string $productName,
        private readonly int $requested,
        private readonly int $available
    ) {
        parent::__construct(
            sprintf(
                'Insufficient stock for product "%s": requested %d, available %d',
                $productName,
                $requested,
                $available
            )
        );
    }

    public function getProductName(): string
    {
        return $this->productName;
    }
}

<?php
// src/State/OrderStateProcessor.php
namespace App\State;

use ApiPlatform\Metadata\Operation;
use ApiPlatform\State\ProcessorInterface;
use App\Entity\Order;
use App\Exception\InsufficientStockException;
use App\Service\StockService;
use Doctrine\ORM\EntityManagerInterface;

class OrderStateProcessor implements ProcessorInterface
{
    public function __construct(
        private readonly EntityManagerInterface $entityManager,
        private readonly StockService $stockService
    ) {}

    public function process(
        mixed $data,
        Operation $operation,
        array $uriVariables = [],
        array $context = []
    ): Order {
        /** @var Order $order */
        $order = $data;

        foreach ($order->getItems() as $item) {
            $available = $this->stockService->getAvailableStock($item->getProduct());

            if ($item->getQuantity() > $available) {
                throw new InsufficientStockException(
                    $item->getProduct()->getName(),
                    $item->getQuantity(),
                    $available
                );
            }
        }

        $this->entityManager->persist($order);
        $this->entityManager->flush();

        return $order;
    }
}

{
  "@context": "/api/contexts/Error",
  "@type": "hydra:Error",
  "hydra:title": "An error occurred",
  "hydra:description": "Insufficient stock for product \"Widget Pro\": requested 10, available 3",
  "status": 422,
  "title": "Unprocessable Content",
  "detail": "Insufficient stock for product \"Widget Pro\": requested 10, available 3"
}

<?php
// tests/Functional/ProductApiTest.php
namespace App\Tests\Functional;

use ApiPlatform\Symfony\Bundle\Test\ApiTestCase;
use App\Entity\Product;
use App\Factory\ProductFactory;
use App\Factory\UserFactory;
use Zenstruck\Foundry\Test\Factories;
use Zenstruck\Foundry\Test\ResetDatabase;

class ProductApiTest extends ApiTestCase
{
    use ResetDatabase;
    use Factories;

    public function testGetProductCollection(): void
    {
        ProductFactory::createMany(5, ['published' => true]);
        ProductFactory::createMany(3, ['published' => false]);

        $response = static::createClient()->request('GET', '/api/products');

        $this->assertResponseIsSuccessful();
        $this->assertResponseHeaderSame(
            'content-type',
            'application/ld+json; charset=utf-8'
        );
        $this->assertJsonContains([
            '@context' => '/api/contexts/Product',
            '@type' => 'hydra:Collection',
            'hydra:totalItems' => 5,
        ]);
    }

    public function testCreateProductRequiresAuthentication(): void
    {
        static::createClient()->request('POST', '/api/products', [
            'json' => [
                'name' => 'New Product',
                'price' => '29.99',
            ],
        ]);

        $this->assertResponseStatusCodeSame(401);
    }

    public function testCreateProductAsAuthenticatedUser(): void
    {
        $user = UserFactory::createOne(['roles' => ['ROLE_VENDOR']]);
        $token = $this->generateJwtToken($user->object());

        $response = static::createClient()->request('POST', '/api/products', [
            'auth_bearer' => $token,
            'json' => [
                'name' => 'Premium Widget',
                'price' => '49.99',
                'description' => 'A high-quality widget',
            ],
        ]);

        $this->assertResponseStatusCodeSame(201);
        $this->assertJsonContains([
            'name' => 'Premium Widget',
            'price' => '49.99',
        ]);
    }

    private function generateJwtToken(mixed $user): string
    {
        $jwtManager = static::getContainer()->get('lexik_jwt_authentication.jwt_manager');
        return $jwtManager->create($user);
    }
}