Symfony 7: API Platform และแนวทางปฏิบัติที่ดีที่สุด

คู่มือครบถ้วนสำหรับการสร้าง REST API ระดับมืออาชีพด้วย Symfony 7 และ API Platform 4 State Providers, Processors, validation และ serialization อธิบายพร้อมตัวอย่างจริง

Symfony 7 และ API Platform 4 สำหรับการพัฒนา REST API แบบ professional

API Platform 4 เปลี่ยนแปลงวิธีสร้าง REST API และ GraphQL ด้วย Symfony เวอร์ชัน 4.4 ที่เปิดตัวในเดือนกันยายน 2026 นำเสนอ composable filters, deprecated #[ApiFilter] decorators และรองรับ OpenAPI 3.2 แบบ native เมื่อรวมกับ service container และ autowiring ของ Symfony การสร้าง API ระดับมืออาชีพจึงทำได้โดยตรง

มีอะไรใหม่ใน API Platform 4.4

เวอร์ชัน 4.4 deprecated legacy #[ApiFilter] decorators (วางแผนลบออกใน 6.0) และแทนที่ด้วย composable filters เช่น ComparisonFilter, OrFilter และ ChainFilter Scalar UI แทนที่ Swagger UI เป็นค่าเริ่มต้นตั้งแต่ 4.3 และรองรับ OpenAPI 3.2 อย่างเต็มที่ ดู release notes อย่างเป็นทางการ สำหรับคำแนะนำในการ migrate

การติดตั้งและการกำหนดค่าเริ่มต้น

API Platform ติดตั้งได้ในไม่กี่คำสั่งด้วย Symfony Flex การกำหนดค่าเริ่มต้นครอบคลุมกรณีการใช้งานส่วนใหญ่ในขณะที่ยังคงปรับแต่งได้อย่างเต็มที่

bash
# terminal
# Create a new Symfony project with API Platform
composer create-project symfony/skeleton my-api
cd my-api

# Install API Platform with Doctrine ORM
composer require api

# Verify installation
php bin/console debug:router | grep api

Symfony Flex กำหนดค่า routes, เอกสาร OpenAPI และ Scalar UI interface ที่เข้าถึงได้ที่ /api โดยอัตโนมัติ เอกสาร API Platform ครอบคลุมตัวเลือกการกำหนดค่าทั้งหมด

yaml
# config/packages/api_platform.yaml
api_platform:
    title: 'My API'
    version: '1.0.0'
    # Supported response formats
    formats:
        jsonld: ['application/ld+json']
        json: ['application/json']
    # OpenAPI documentation
    swagger:
        versions: [3]
    # Default pagination
    defaults:
        pagination_items_per_page: 30
        pagination_maximum_items_per_page: 100

การกำหนดค่านี้กำหนดรูปแบบ serialization, pagination ทั่วไป และ metadata สำหรับเอกสาร API

การสร้าง API Resource อย่างง่าย

attribute #[ApiResource] เปิดเผย Doctrine entity เป็น REST resource API Platform สร้าง CRUD endpoints, เอกสาร OpenAPI และ validation พื้นฐานโดยอัตโนมัติ

php
<?php
// src/Entity/Book.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\Patch;
use ApiPlatform\Metadata\Delete;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Validator\Constraints as Assert;

#[ORM\Entity]
#[ApiResource(
    // Explicit definition of available operations
    operations: [
        new GetCollection(),
        new Post(),
        new Get(),
        new Put(),
        new Patch(),
        new Delete(),
    ],
    // Default ordering for collections
    order: ['publishedAt' => 'DESC'],
    // Pagination configuration for this resource
    paginationItemsPerPage: 20
)]
class Book
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int \ = null;

    #[ORM\Column(length: 255)]
    #[Assert\NotBlank(message: 'Title is required')]
    #[Assert\Length(min: 2, max: 255)]
    private ?string \ = null;

    #[ORM\Column(type: 'text')]
    #[Assert\NotBlank]
    private ?string \ = null;

    #[ORM\Column(length: 13, unique: true)]
    #[Assert\Isbn]
    private ?string \ = null;

    #[ORM\Column]
    private ?\DateTimeImmutable \ = null;

    // Getters and setters...
    public function getId(): ?int
    {
        return \->id;
    }

    public function getTitle(): ?string
    {
        return \->title;
    }

    public function setTitle(string \): static
    {
        \->title = \;
        return \;
    }

    public function getDescription(): ?string
    {
        return \->description;
    }

    public function setDescription(string \): static
    {
        \->description = \;
        return \;
    }

    public function getIsbn(): ?string
    {
        return \->isbn;
    }

    public function setIsbn(string \): static
    {
        \->isbn = \;
        return \;
    }

    public function getPublishedAt(): ?\DateTimeImmutable
    {
        return \->publishedAt;
    }

    public function setPublishedAt(\DateTimeImmutable \): static
    {
        \->publishedAt = \;
        return \;
    }
}

entity นี้สร้าง 6 endpoints: GET /api/books, POST /api/books, GET /api/books/{id}, PUT /api/books/{id}, PATCH /api/books/{id} และ DELETE /api/books/{id}

แนะนำ UUID v7

API Platform รองรับ UUID v7 เป็น identifier แบบ native วิธีการนี้ปรับปรุงความปลอดภัย (identifier ที่คาดเดาไม่ได้) และประสิทธิภาพ (การเรียงลำดับตามวันที่สร้างตามธรรมชาติ)

Serialization Groups สำหรับควบคุมข้อมูลที่เปิดเผย

Serialization groups กำหนดอย่างแม่นยำว่า properties ใดที่จะถูกเปิดเผยสำหรับการอ่าน (normalization) และการเขียน (denormalization) การแยกนี้จำเป็นสำหรับความปลอดภัยและความยืดหยุ่นของ API สำหรับสถานการณ์ serialization ที่ซับซ้อน component Symfony Serializer มีตัวเลือกการปรับแต่งเพิ่มเติม

php
<?php
// src/Entity/User.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\Patch;
use ApiPlatform\Metadata\Delete;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Serializer\Annotation\Groups;
use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Security\Core\User\UserInterface;
use Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface;
use Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity;
use App\State\UserPasswordHasher;

#[ORM\Entity]
#[ORM\Table(name: '`user`')]
#[UniqueEntity('email')]
#[ApiResource(
    operations: [
        new GetCollection(),
        // Custom processor for password hashing
        new Post(processor: UserPasswordHasher::class,
                 validationContext: ['groups' => ['Default', 'user:create']]),
        new Get(),
        new Put(processor: UserPasswordHasher::class),
        new Patch(processor: UserPasswordHasher::class),
        new Delete(),
    ],
    // Properties exposed when reading
    normalizationContext: ['groups' => ['user:read']],
    // Properties accepted when writing
    denormalizationContext: ['groups' => ['user:create', 'user:update']],
)]
class User implements UserInterface, PasswordAuthenticatedUserInterface
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    #[Groups(['user:read'])]
    private ?int \ = null;

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

    #[ORM\Column]
    private ?string \ = null;

    // Never exposed when reading, only when writing
    #[Assert\NotBlank(groups: ['user:create'])]
    #[Groups(['user:create', 'user:update'])]
    private ?string \ = null;

    #[ORM\Column(length: 100)]
    #[Groups(['user:read', 'user:create', 'user:update'])]
    private ?string \ = null;

    #[ORM\Column(type: 'json')]
    #[Groups(['user:read'])]
    private array \ = [];

    #[ORM\Column]
    #[Groups(['user:read'])]
    private ?\DateTimeImmutable \ = null;

    public function __construct()
    {
        \->createdAt = new \DateTimeImmutable();
    }

    // UserInterface implementation
    public function getUserIdentifier(): string
    {
        return (string) \->email;
    }

    public function getRoles(): array
    {
        \ = \->roles;
        \[] = 'ROLE_USER';
        return array_unique(\);
    }

    public function getPassword(): string
    {
        return \->password;
    }

    public function eraseCredentials(): void
    {
        \->plainPassword = null;
    }

    // Getters and setters...
    public function getId(): ?int
    {
        return \->id;
    }

    public function getEmail(): ?string
    {
        return \->email;
    }

    public function setEmail(string \): static
    {
        \->email = \;
        return \;
    }

    public function setPassword(string \): static
    {
        \->password = \;
        return \;
    }

    public function getPlainPassword(): ?string
    {
        return \->plainPassword;
    }

    public function setPlainPassword(?string \): static
    {
        \->plainPassword = \;
        return \;
    }

    public function getFullName(): ?string
    {
        return \->fullName;
    }

    public function setFullName(string \): static
    {
        \->fullName = \;
        return \;
    }

    public function setRoles(array \): static
    {
        \->roles = \;
        return \;
    }

    public function getCreatedAt(): ?\DateTimeImmutable
    {
        return \->createdAt;
    }
}

ด้วยการกำหนดค่านี้ plainPassword จะไม่ถูกเปิดเผยใน responses แต่สามารถส่งได้ระหว่างการสร้างหรืออัปเดต

พร้อมที่จะพิชิตการสัมภาษณ์ Symfony แล้วหรือยังครับ?

ฝึกฝนด้วยตัวจำลองแบบโต้ตอบ, flashcards และแบบทดสอบเทคนิคครับ

State Processors สำหรับ Business Logic

State Processors ดักจับการดำเนินการ persistence เพื่อเพิ่ม business logic API Platform ทำให้การสร้างง่ายขึ้นผ่าน attribute-based dependency injection

php
<?php
// src/State/UserPasswordHasher.php

namespace App\State;

use ApiPlatform\Metadata\Operation;
use ApiPlatform\State\ProcessorInterface;
use App\Entity\User;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface;

/**
 * Processor that hashes password before persistence
 * @implements ProcessorInterface<User, User>
 */
final class UserPasswordHasher implements ProcessorInterface
{
    public function __construct(
        // Injection of standard Doctrine processor
        #[Autowire(service: 'api_platform.doctrine.orm.state.persist_processor')]
        private ProcessorInterface \,
        private UserPasswordHasherInterface \,
    ) {
    }

    public function process(mixed \, Operation \, array \ = [], array \ = []): User
    {
        // Hash password if provided
        if (\->getPlainPassword()) {
            \ = \->passwordHasher->hashPassword(
                \,
                \->getPlainPassword()
            );
            \->setPassword(\);
            \->eraseCredentials();
        }

        // Delegate persistence to standard processor
        return \->persistProcessor->process(\, \, \, \);
    }
}

รูปแบบ composition นี้ช่วยให้เพิ่ม logic ใดก็ได้ (ส่งอีเมล, events, logging) ในขณะที่รักษาพฤติกรรม persistence มาตรฐาน สำหรับสถาปัตยกรรมแบบ event-driven processors ทำงานร่วมกับ Symfony Messenger ได้อย่างราบรื่น

Processor พร้อม Conditional Logic

processor สามารถปรับพฤติกรรมตามประเภท operation

php
<?php
// src/State/BookProcessor.php

namespace App\State;

use ApiPlatform\Metadata\DeleteOperationInterface;
use ApiPlatform\Metadata\Operation;
use ApiPlatform\Metadata\Post;
use ApiPlatform\State\ProcessorInterface;
use App\Entity\Book;
use App\Service\NotificationService;
use App\Service\SearchIndexer;
use Symfony\Component\DependencyInjection\Attribute\Autowire;

/**
 * @implements ProcessorInterface<Book, Book|void>
 */
final class BookProcessor implements ProcessorInterface
{
    public function __construct(
        #[Autowire(service: 'api_platform.doctrine.orm.state.persist_processor')]
        private ProcessorInterface \,
        #[Autowire(service: 'api_platform.doctrine.orm.state.remove_processor')]
        private ProcessorInterface \,
        private NotificationService \,
        private SearchIndexer \,
    ) {
    }

    public function process(mixed \, Operation \, array \ = [], array \ = []): mixed
    {
        // Deletion: use remove processor
        if (\ instanceof DeleteOperationInterface) {
            \->searchIndexer->remove(\);
            return \->removeProcessor->process(\, \, \, \);
        }

        // Creation: set publication date
        if (\ instanceof Post) {
            \->setPublishedAt(new \DateTimeImmutable());
        }

        // Standard persistence
        \ = \->persistProcessor->process(\, \, \, \);

        // Post-processing: indexing and notification
        \->searchIndexer->index(\);

        if (\ instanceof Post) {
            \->notifications->notifyNewBook(\);
        }

        return \;
    }
}

State Providers สำหรับแหล่งข้อมูลที่กำหนดเอง

State Providers ดึงข้อมูลจากแหล่งใดก็ได้: external APIs, cache, files หรือ business logic ที่ซับซ้อน

php
<?php
// src/State/PopularBooksProvider.php

namespace App\State;

use ApiPlatform\Metadata\Operation;
use ApiPlatform\State\ProviderInterface;
use App\Entity\Book;
use App\Repository\BookRepository;
use Symfony\Contracts\Cache\CacheInterface;
use Symfony\Contracts\Cache\ItemInterface;

/**
 * Provider that returns popular books with caching
 * @implements ProviderInterface<Book>
 */
final class PopularBooksProvider implements ProviderInterface
{
    public function __construct(
        private BookRepository \,
        private CacheInterface \,
    ) {
    }

    public function provide(Operation \, array \ = [], array \ = []): array
    {
        // 5-minute cache for popular books
        return \->cache->get('popular_books', function (ItemInterface \) {
            \->expiresAfter(300);

            return \->bookRepository->findPopular(limit: 10);
        });
    }
}

provider นี้ใช้กับ operation เฉพาะ

php
<?php
// src/Entity/Book.php (excerpt)

use App\State\PopularBooksProvider;

#[ApiResource(
    operations: [
        // ... other operations
        new GetCollection(
            uriTemplate: '/books/popular',
            provider: PopularBooksProvider::class,
            paginationEnabled: false,
        ),
    ],
)]
class Book
{
    // ...
}

Validation ขั้นสูงพร้อม Dynamic Groups

API Platform รวม Symfony Validator component แบบ native Validation groups สามารถเปลี่ยนแปลงตาม operation หรือ context

php
<?php
// src/Entity/Article.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 Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Validator\Constraints as Assert;

#[ORM\Entity]
#[ApiResource(
    operations: [
        new GetCollection(),
        new Get(),
        // Strict validation on creation
        new Post(validationContext: ['groups' => ['Default', 'article:create']]),
        // More lenient validation for updates
        new Put(validationContext: ['groups' => ['Default', 'article:update']]),
    ],
)]
class Article
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int \ = null;

    #[ORM\Column(length: 255)]
    #[Assert\NotBlank]
    #[Assert\Length(min: 10, max: 255)]
    private ?string \ = null;

    #[ORM\Column(type: 'text')]
    #[Assert\NotBlank]
    // Minimum 500 characters on creation
    #[Assert\Length(min: 500, groups: ['article:create'])]
    // Minimum 100 characters for updates
    #[Assert\Length(min: 100, groups: ['article:update'])]
    private ?string \ = null;

    #[ORM\Column(length: 50)]
    #[Assert\NotBlank(groups: ['article:create'])]
    #[Assert\Choice(choices: ['draft', 'published', 'archived'])]
    private ?string \ = 'draft';

    #[ORM\Column(nullable: true)]
    // Required only if status is "published"
    #[Assert\NotBlank(groups: ['article:publish'])]
    private ?\DateTimeImmutable \ = null;

    // Getters and setters...
}

Dynamic Validation พร้อม Service

สำหรับกฎ validation ที่ซับซ้อน custom group generator มีความยืดหยุ่นเต็มที่

php
<?php
// src/Validator/ArticleGroupsGenerator.php

namespace App\Validator;

use ApiPlatform\Symfony\Validator\ValidationGroupsGeneratorInterface;
use App\Entity\Article;
use Symfony\Bundle\SecurityBundle\Security;

final class ArticleGroupsGenerator implements ValidationGroupsGeneratorInterface
{
    public function __construct(
        private Security \,
    ) {
    }

    public function __invoke(object \): array
    {
        assert(\ instanceof Article);

        \ = ['Default'];

        // Admins have fewer restrictions
        if (\->security->isGranted('ROLE_ADMIN')) {
            \[] = 'admin';
            return \;
        }

        // Additional validation if publishing
        if (\->getStatus() === 'published') {
            \[] = 'article:publish';
        }

        return \;
    }
}
ประสิทธิภาพ Validation

Validation ที่ซับซ้อนอาจส่งผลต่อประสิทธิภาพ สำหรับการ import จำนวนมาก พิจารณาปิดใช้งาน validation บางอย่างชั่วคราวหรือใช้ asynchronous constraints

Filters สำหรับ Queries ที่ยืดหยุ่น

API Platform 4.4 ออกแบบระบบ filter ใหม่ด้วย composable filters Legacy #[ApiFilter] decorator ถูก deprecated (วางแผนลบใน 6.0) และมี codemod สำหรับการ migration

php
<?php
// src/Entity/Product.php

namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\ApiFilter;
use ApiPlatform\Doctrine\Orm\Filter\SearchFilter;
use ApiPlatform\Doctrine\Orm\Filter\RangeFilter;
use ApiPlatform\Doctrine\Orm\Filter\OrderFilter;
use ApiPlatform\Doctrine\Orm\Filter\BooleanFilter;
use ApiPlatform\Doctrine\Orm\Filter\DateFilter;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[ApiResource]
// Text search on name and description
#[ApiFilter(SearchFilter::class, properties: [
    'name' => 'partial',       // LIKE %value%
    'description' => 'partial',
    'category.name' => 'exact', // Search on relation
    'sku' => 'exact',          // Exact match
])]
// Range filtering
#[ApiFilter(RangeFilter::class, properties: ['price', 'stock'])]
// Date filtering
#[ApiFilter(DateFilter::class, properties: ['createdAt', 'updatedAt'])]
// Boolean filtering
#[ApiFilter(BooleanFilter::class, properties: ['isActive', 'isFeatured'])]
// Customizable sorting
#[ApiFilter(OrderFilter::class, properties: [
    'name',
    'price',
    'createdAt',
], arguments: ['orderParameterName' => 'sort'])]
class Product
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int \ = null;

    #[ORM\Column(length: 255)]
    private ?string \ = null;

    #[ORM\Column(type: 'text', nullable: true)]
    private ?string \ = null;

    #[ORM\Column(length: 50, unique: true)]
    private ?string \ = null;

    #[ORM\Column(type: 'decimal', precision: 10, scale: 2)]
    private ?string \ = null;

    #[ORM\Column]
    private ?int \ = null;

    #[ORM\Column]
    private ?bool \ = true;

    #[ORM\Column]
    private ?bool \ = false;

    #[ORM\ManyToOne(targetEntity: Category::class)]
    private ?Category \ = null;

    #[ORM\Column]
    private ?\DateTimeImmutable \ = null;

    #[ORM\Column(nullable: true)]
    private ?\DateTimeImmutable \ = null;

    // Getters and setters...
}

filters เหล่านี้สร้างเอกสาร OpenAPI โดยอัตโนมัติและเปิดใช้งาน queries เช่น:

text
GET /api/products?name=phone&price[gte]=100&price[lte]=500&isActive=true&sort[price]=asc

API Platform 4.4 แนะนำ filters ใหม่: StartSearchFilter, EndSearchFilter, WordStartSearchFilter และ composable wrappers เช่น ComparisonFilter, OrFilter และ ChainFilter

Relations และ Subresources

API Platform จัดการ entity relations อย่างสวยงามด้วยตัวเลือก serialization และ subresources

php
<?php
// src/Entity/Author.php

namespace App\Entity;

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

#[ORM\Entity]
#[ApiResource(
    normalizationContext: ['groups' => ['author:read']],
)]
class Author
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    #[Groups(['author:read', 'book:read'])]
    private ?int \ = null;

    #[ORM\Column(length: 255)]
    #[Groups(['author:read', 'book:read'])]
    private ?string \ = null;

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

    #[ORM\OneToMany(mappedBy: 'author', targetEntity: Book::class)]
    #[Groups(['author:read'])]
    private Collection \;

    public function __construct()
    {
        \->books = new ArrayCollection();
    }

    // Getters and setters...
}
php
<?php
// src/Entity/Book.php (with relation)

namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Link;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Serializer\Annotation\Groups;

#[ORM\Entity]
#[ApiResource(
    normalizationContext: ['groups' => ['book:read']],
)]
// Subresource: GET /api/authors/{authorId}/books
#[ApiResource(
    uriTemplate: '/authors/{authorId}/books',
    operations: [new GetCollection()],
    uriVariables: [
        'authorId' => new Link(
            fromProperty: 'books',
            fromClass: Author::class
        ),
    ],
    normalizationContext: ['groups' => ['book:read']],
)]
class Book
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    #[Groups(['book:read', 'author:read'])]
    private ?int \ = null;

    #[ORM\Column(length: 255)]
    #[Groups(['book:read', 'author:read'])]
    private ?string \ = null;

    #[ORM\ManyToOne(targetEntity: Author::class, inversedBy: 'books')]
    #[ORM\JoinColumn(nullable: false)]
    #[Groups(['book:read'])]
    private ?Author \ = null;

    // Getters and setters...
}

Security และ Access Control

API Platform รวมเข้ากับระบบ security ของ Symfony อย่างราบรื่น Voters และ security expressions ควบคุมการเข้าถึง resource สำหรับภาพรวมของรูปแบบ security ของ Symfony ดู Symfony Security: Voters, Firewalls และคำถามสัมภาษณ์

php
<?php
// src/Entity/Order.php

namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Post;
use ApiPlatform\Metadata\Patch;
use ApiPlatform\Metadata\Delete;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[ApiResource(
    operations: [
        // List: authenticated users see their orders
        new GetCollection(
            security: "is_granted('ROLE_USER')",
            // Automatic filter by connected user
            provider: UserOrdersProvider::class,
        ),
        // Creation: any authenticated user
        new Post(
            security: "is_granted('ROLE_USER')",
            processor: CreateOrderProcessor::class,
        ),
        // Read: owner or admin
        new Get(
            security: "is_granted('ROLE_ADMIN') or object.getCustomer() == user",
            securityMessage: "Access denied to this order.",
        ),
        // Modification: admin only
        new Patch(
            security: "is_granted('ROLE_ADMIN')",
        ),
        // Deletion: admin only
        new Delete(
            security: "is_granted('ROLE_ADMIN')",
        ),
    ],
)]
class Order
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int \ = null;

    #[ORM\ManyToOne(targetEntity: User::class)]
    #[ORM\JoinColumn(nullable: false)]
    private ?User \ = null;

    #[ORM\Column(length: 50)]
    private ?string \ = 'pending';

    #[ORM\Column(type: 'decimal', precision: 10, scale: 2)]
    private ?string \ = null;

    #[ORM\Column]
    private ?\DateTimeImmutable \ = null;

    // Getters...
    public function getCustomer(): ?User
    {
        return \->customer;
    }
}

expression object.getCustomer() == user ให้การเข้าถึง entity ปัจจุบันและผู้ใช้ที่เชื่อมต่ออยู่สำหรับการตรวจสอบอย่างละเอียด

การทดสอบ API อัตโนมัติ

API Platform มี PHPUnit traits สำหรับทดสอบ endpoints ได้อย่างง่ายดาย

php
<?php
// tests/Api/BookTest.php

namespace App\Tests\Api;

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

class BookTest extends ApiTestCase
{
    use ResetDatabase;
    use Factories;

    public function testGetCollection(): void
    {
        // Create test data
        BookFactory::createMany(30);

        // GET request on collection
        \ = static::createClient()->request('GET', '/api/books');

        // Assertions
        \->assertResponseIsSuccessful();
        \->assertResponseHeaderSame('content-type', 'application/ld+json; charset=utf-8');
        \->assertJsonContains([
            '@context' => '/api/contexts/Book',
            '@type' => 'Collection',
            'totalItems' => 30,
        ]);
        // Verify pagination (20 items per page)
        \->assertCount(20, \->toArray()['member']);
    }

    public function testCreateBook(): void
    {
        \ = UserFactory::createOne(['roles' => ['ROLE_ADMIN']]);

        static::createClient()->request('POST', '/api/books', [
            'auth_bearer' => \->getToken(\),
            'json' => [
                'title' => 'Clean Code',
                'description' => 'A Handbook of Agile Software Craftsmanship',
                'isbn' => '9780132350884',
            ],
        ]);

        \->assertResponseStatusCodeSame(201);
        \->assertJsonContains([
            '@type' => 'Book',
            'title' => 'Clean Code',
        ]);
    }

    public function testCreateBookValidationFails(): void
    {
        \ = UserFactory::createOne(['roles' => ['ROLE_ADMIN']]);

        static::createClient()->request('POST', '/api/books', [
            'auth_bearer' => \->getToken(\),
            'json' => [
                'title' => '', // Empty title = error
                'isbn' => 'invalid-isbn',
            ],
        ]);

        \->assertResponseStatusCodeSame(422);
        \->assertJsonContains([
            '@type' => 'ConstraintViolationList',
            'violations' => [
                ['propertyPath' => 'title', 'message' => 'Title is required'],
            ],
        ]);
    }

    private function getToken(object \): string
    {
        // Implementation depends on your authentication system
        return 'test_token';
    }
}

แหล่งอ้างอิง

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

API Platform ร่วมกับ Symfony เป็นตัวแทนของมาตรฐานล่าสุดสำหรับการสร้าง REST API ระดับมืออาชีพใน PHP การแยกที่ชัดเจนระหว่าง State Providers (อ่าน) และ State Processors (เขียน) รวมกับ serialization groups และระบบ validation ช่วยให้สร้าง API ที่แข็งแกร่งและบำรุงรักษาได้

Checklist สำหรับ API คุณภาพสูง

  • ใช้ serialization groups ที่แตกต่างกันสำหรับการอ่านและเขียน
  • ใช้งาน State Processors สำหรับ business logic (hash รหัสผ่าน, แจ้งเตือน)
  • กำหนดค่า filters สำหรับการค้นหาและเรียงลำดับ (migrate จาก deprecated #[ApiFilter] เป็น composable filters)
  • ใช้ validation ตาม operation ด้วย groups
  • ป้องกัน endpoints ด้วย security expressions
  • เขียน functional tests สำหรับทุก endpoint
  • จัดทำเอกสาร API ผ่าน OpenAPI metadata

เริ่มฝึกซ้อมเลย!

ทดสอบความรู้ของคุณด้วยตัวจำลองสัมภาษณ์และแบบทดสอบเทคนิคครับ

ปรัชญาของ API Platform สนับสนุน composition มากกว่า inheritance และ configuration มากกว่า convention ผลลัพธ์คือ API ที่ปรับขนาดได้ ทดสอบได้ และสอดคล้องกับมาตรฐาน REST/JSON-LD พร้อมใช้งานจริงตั้งแต่วันแรก

ชาเลนจ์ประจำวัน

คุณหาบั๊กใน Symfony เจอไหม

โค้ดจริงหนึ่งชิ้น บั๊กที่ซ่อนอยู่หนึ่งจุด วันละหนึ่งครั้ง ลองได้โดยไม่ต้องมีบัญชี

Anthony Fillion-Maillet

เขียนโดย

Anthony Fillion-Maillet

ผู้ก่อตั้ง SharpSkill

เป็นนักพัฒนาฟูลสแตกมากว่า 10 ปี ดูแล SharpSkill และรับผิดชอบทุกสิ่งที่เผยแพร่ที่นี่

อัปเดตเมื่อ 12 ตุลาคม 2569

แท็ก

#symfony
#api platform
#php
#rest api
#api development

แชร์

บทความที่เกี่ยวข้อง