API platform по быстрому

API platform это полнофункциональный REST API, который вы получите за считанные минуты.Вот неполный список фич:

— Генерация CRUD

— Поддержка GraphQL

— Машиночитаемая документация API в форматах Hydra и Swagger/Open API, гененрится из метаданных PHPDoc, Serializer, Validator и Doctrine ORM / MongoDB ODM

— Хорошая удобочитаемая документация, созданная с использованием пользовательского интерфейса Swagger (включая песочницу) и / или ReDoc

— Пагинация

— Куча фильтров

— Проверка с использованием компонента Symfony Validator (с поддержкой групп)

— Расширенные правила аутентификации и авторизации

— Расширенная сериализация благодаря компоненту Symfony Serializer (поддержка групп, встраивание отношений, максимальная глубина…)

— Поддержка JWT и OAuth- Файлы и \DateTime, сериализация и десериализация

— Все полностью настраивается благодаря мощной системе событий и сильному ООП.

Сразу отмечу, что в Symfony можно создавать API через контроллер

php bin/console make:controller --no-template SuperApiController

и так же настроить валидацию и доступы через атрибуты

namespace App\Controller;  use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; use Symfony\Component\HttpFoundation\JsonResponse; use Symfony\Component\Routing\Annotation\Route; use Symfony\Component\Security\Http\Attribute\IsGranted;  class SuperApiController extends AbstractController {     #[Route('/super/api', name: 'app_super_api')]     #[IsGranted("ROLE_ADMIN")]     public function index(): JsonResponse     {         return $this->json([             'message' => 'Welcome to your new controller!',             'path' => 'src/Controller/SuperApiController.php',         ]);     } }

Но если можно не писать код, а использовать уже проверенный, почему бы не пойти такой дорогой?

После изучения этого материала ты узнаешь:

• Как с помощью API platform создать CRUD и получить документацию swagger.

• Добавим операцию регистрации пользователя и аутентификацию через токен.

• Добавим доступы к операциям и позволим менять пароль через API только себе.

Устанавливаем API platform

composer require api

Создадим сущность пользователя

php bin/console make:user

И теперь, давай добавим просто атрибут [ApiResource] у этой сущности

namespace App\Entity;  use ApiPlatform\Metadata\ApiResource;   #[ApiResource] //<-- Добавил только это #[ORM\Entity(repositoryClass: UserRepository::class)] class User implements UserInterface, PasswordAuthenticatedUserInterface { ... 

Вот и всё готово! Мы создали полноценное REST Api.

Заходи по ссылке http://localhost/api

И видим, что у нас появились методы для CRUD. По сути, мы написали одну строчку кода, добавив один атрибут, и уже имеем такой мощный функционал.

Отлично, движемся дальше.

Делаем метод регистарции пользователя

Для этого нам необходимо добавить поле токен к сущности пользователя

php bin/console make:entity User

добавим поле token

В самой сущности, добавим поле plainPassword, которой добавим атрибут

use Symfony\Component\Serializer\Annotation\SerializedName; //....  class User implements UserInterface, PasswordAuthenticatedUserInterface { //...  #[SerializedName('password')] private $plainPassword;     /**      * @return mixed      */     public function getPlainPassword()     {         return $this->plainPassword;     }      /**      * @param   mixed  $plainPassword      */     public function setPlainPassword($plainPassword): void     {         $this->plainPassword = $plainPassword;     }    /**      * @see UserInterface      */     public function eraseCredentials()     {         // If you store any temporary, sensitive data on the user, clear it here          $this->plainPassword = null; // <--- Раскоментируем эту строчку      } }

Далее нам необходимо реализовать процессор состояний, который будет содержать логику хэширования пароля и добавления ролей пользователю по умолчанию.

Смотри документацию про Процессоры состояний

После чего мы сможем использовать этот процессор в операциях для создания пользователя и изменения пароля.

Поехали

php bin/console make:state-processor UserPasswordHasherProcessor

Регистрируем его в конфиге services.yaml

#services.yaml services:      App\State\UserPasswordHasherProcessor:     bind:       '@api_platform.doctrine.orm.state.persist_processor'

Сам процессор будет выглядеть так.

<?php  namespace App\State;  use ApiPlatform\Metadata\Operation; use ApiPlatform\Metadata\Post; use ApiPlatform\State\ProcessorInterface; use App\Entity\User; use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface;  class UserPasswordHasherProcessor implements ProcessorInterface {     public function __construct(private readonly ProcessorInterface $processor, private readonly UserPasswordHasherInterface $passwordHasher)     {     }       /**      * @param   User      $data      * @param   Operation  $operation      * @param   array      $uriVariables      * @param   array      $context      *      * @return mixed      * @throws \Exception      */     public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = [])     {         if (!$data->getPlainPassword()) {             return $this->processor->process($data, $operation, $uriVariables, $context);         }          $hashedPassword = $this->passwordHasher->hashPassword(             $data,             $data->getPlainPassword()         );         $data->setPassword($hashedPassword);         $data->eraseCredentials();         // Если это операция по созданию нового пользователя, то генерим токе и назначаем роль по умолчанию          if ($operation instanceof Post){             $data->setToken(bin2hex(random_bytes(60)));             $data->setRoles($data->getRoles());         }          return $this->processor->process($data, $operation, $uriVariables, $context);     } }

Настраиваем операции

Пришло время, связать наш ресурс API с логикой, описанной в процессоре. Для этого добавим атрибут operations к сущности User и пропишем все необходимые операции в виде методов API.

Обрати внимание, я указал созданный нами процессор UserPasswordHasherProcessor в операциях Post() и Patch(). А так же, в операции пост добавил параметр uriTemplate со значением /registration, что изменит uri у этого метода с /api/users на /api/registration.

use ApiPlatform\Metadata\Delete; use ApiPlatform\Metadata\GetCollection; use ApiPlatform\Metadata\Patch; use ApiPlatform\Metadata\Post; use ApiPlatform\Metadata\Put; use ApiPlatform\Metadata\Get;  ...  #[ApiResource( operations: [     new GetCollection(),     new Post(processor: UserPasswordHasherProcessor::class,              uriTemplate: '/registration'),     new Get(),     new Patch(processor: UserPasswordHasherProcessor::class),     new Delete(),     ] )]  #[ORM\Entity(repositoryClass: UserRepository::class)] #[ORM\Table(name: '`user`')] class User implements UserInterface, PasswordAuthenticatedUserInterface { 

Отлично, давай посмотрим на то, как сейчас выглядит swagger. И видим, то что раньше у нас были поля в разделе Example value, а сейчас пусто. 

Все нормально! 

Так как я переопределил, каждый метод в параметре operations, API Platform не понимает, какие поля ему нужно использовать для каждого метода как входные параметры, и какие поля будут отображены после успешной работы метода. Пришло время настроить сериализацию и нормализацию данных.

Группы сериализации и нормализации

Смотри документацию про Сериализацию

Для этого в атрибуте ApiResource в сущности User опишем параметры normalizationContext для чтения данных из сущности, и denormalizationContext для записи данных в сущность.

use Symfony\Component\Serializer\Annotation\Groups; ...  #[ApiResource(         normalizationContext: ['groups' => ['user:read']],         denormalizationContext: ['groups' => ['user:create', 'user:update']],         operations: [ 

А дальше, назначим эти группы для полей в сущности User. Так, чтобы для создания пользователя мы запрашивали только логин и пароль, а возвращали токен.

class User implements UserInterface, PasswordAuthenticatedUserInterface {     #[ORM\Id]     #[ORM\GeneratedValue]     #[ORM\Column]     private ?int $id = null;      #[Groups(['user:create', 'user:update'])]     #[ORM\Column(length: 180, unique: true)]     private ?string $email = null;      #[ORM\Column]     private array $roles = [];      /**      * @var string The hashed password      */     #[ORM\Column]     private ?string $password = null;      #[ORM\Column(length: 255)]     #[Groups(['user:read'])]     private ?string $token = null;       #[Groups(['user:create', 'user:update'])]     #[SerializedName('password')]     private $plainPassword;

Посмотрим, как теперь выглядит в Swagger Example value в методе /api/registration. Обновим страничку с описанием и видим что, все так как и запланировали.

{   "email": "string",   "password": "string" }

И в ответе мы видим, что будет возращен токен

{   "@context": "string",   "@id": "string",   "@type": "string",   "token": "string" }

Ты не поверишь, но метод регистрации уже работает! Можно уже сейчас нажать кнопку execute и все сработает! Опа, ошибка вывалилась!

Ну конечно! А ты настроил соединение с БД и выполнил миграцию данных?

БД и миграции

Пришло время настроить подключение и заполнить БД.

#.env DATABASE_URL="mysql://root:root@mysql:3306/app?serverVersion=8&charset=utf8mb4"

Создадим миграцию

php bin/console make:migration

И выполним её

php bin/console doctrine:migrations:migrate

Регистрируем пользователя через API

Заполняем данные в Swagger Example value в методе /api/registration и нажимаем execute

Это же amazing какой-то!

Кстати, метод Patch тоже работает. И в нем так же можно изменить два поля

{   "email": "string",   "password": "string" } 

И в ответ вернется значение поля token. Только токен не будет генерироваться вновь, так как в UserPasswordHasherProcessor, есть такое условие:

    ...     if ($operation instanceof Post){ // <- только для метода Post          $data->setToken(bin2hex(random_bytes(60)));         $data->setRoles($data->getRoles());     }

Авторизация

В swagger, сверху есть такая кнопка Authorize, нажав на которую, мы видим…пустое окно. Сейчас мы настроим наше API чтобы он мог авторизовывать пользователя через токен, а в swagger мы могли использовать этот токен.

Начнем с настройки API Platform. Добавим такой конфиг config/packages/api_platform.yaml

#config/packages/api_platform.yaml api_platform:   # The title of the API.   title: 'Edu API'    # The description of the API.   description: 'Edu API description'    # The version of the API.   version: '0.0.1'    # Set this to false if you want Webby to disappear.   show_webby: false    mapping:     paths: ['%kernel.project_dir%/src/Entity']   patch_formats:     json: ['application/merge-patch+json']   swagger:     versions: [3]     api_keys:       Bearer:         name: AUTH-TOKEN         type: header 

И теперь нажав на кнопку Authorize, появится форма, с полем AUTH-TOKEN куда можно вставить токен нашего пользователя. Значение которого можно вытащить из таблицы user.

Но пока, авторизацию не реализована у нас в API, и хоть swagger радостно сообщит, что авторизовался, и будет честно слать токен в заголовке, API его не воспримет.

Давай реализуем необходимый аутентификатор, и все настроим.

Выполним команду и выберем вариант 0 Empty authenticator и дадим название ApiTokenAuthenticator

php bin/console make:auth   What style of authentication do you want? [Empty authenticator]:   [0] Empty authenticator   [1] Login form authenticator  > ApiTokenAuthenticator 

Теперь, реализуем в нем все необходимые методы:

namespace App\Security;  use Symfony\Component\HttpFoundation\Request; use Symfony\Component\HttpFoundation\Response; use Symfony\Component\Security\Core\Authentication\Token\TokenInterface; use Symfony\Component\Security\Core\Exception\AuthenticationException; use Symfony\Component\Security\Core\Exception\CustomUserMessageAuthenticationException; use Symfony\Component\Security\Http\Authenticator\AbstractAuthenticator; use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge; use Symfony\Component\Security\Http\Authenticator\Passport\Passport; use Symfony\Component\Security\Http\Authenticator\Passport\SelfValidatingPassport;  class ApiKeyAuthenticator extends AbstractAuthenticator {      protected const HEADER_AUTH_TOKEN = 'AUTH-TOKEN';      /**      * @inheritDoc      */     public function supports(Request $request): ?bool     {         return $request->headers->has(self::HEADER_AUTH_TOKEN);     }      /**      * @inheritDoc      */     public function authenticate(Request $request): Passport     {         $apiToken = $request->headers->get(self::HEADER_AUTH_TOKEN);          if (null === $apiToken) {             throw new CustomUserMessageAuthenticationException('Auth token not found (header: "{{ header }}")', [                 '{{ header }}' => self::HEADER_AUTH_TOKEN,             ]);         }          return new SelfValidatingPassport(new UserBadge($apiToken));     }      /**      * @inheritDoc      */     public function onAuthenticationSuccess(Request $request, TokenInterface $token, string $firewallName): ?Response     {         return null;     }      /**      * @inheritDoc      */     public function onAuthenticationFailure(Request $request, AuthenticationException $exception): ?Response     {         throw $exception;     } }

Настроим UserProvider на работу с полем token и настроим firewall

#config/packages/security.yaml  security:     #....     providers:                  app_user_provider:             entity:                 class: App\Entity\User                 property: token # <-- тут устанавливаем поле token      firewalls:         dev:             pattern: ^/(_(profiler|wdt)|css|images|js)/             security: false         main:             lazy: true             stateless: true  # <-- добавляем stateless: true так как у нас не будут использоваться сессии               provider: app_user_provider             custom_authenticator: App\Security\ApiKeyAuthenticator  # <-- регистрируем ApiKeyAuthenticator     #...  

Вот теперь, наш API готов к авторизации пользователя. Только в текущий момент, все что мы сделали абсолютно бесполезно, так как у нас не настроены доступы.

Доступы и роли

Определим роли и разрешения

Давай представим, а как бы хотелось пользоваться текущим API.

1. Метод POST /api/registration должен быть доступен всем, чтобы пользователи свободно регистрировались.

2. Должен быть метод POST /api/login тоже должен быть доступен всем, и в ответ давать свежий токен для авторизации

3. Методы GET /api/users и /api/users/{id} доступно только залогиненым пользователям

4. Методы PATCH /api/users/{id} можно менять пароль только себе, доступно только залогиненым пользователям

5. Методы DELETE /api/users/{id} можно удалить только себя, доступно только залогиненым пользователям

Первый пункт, уже реализован.

Для пункта 2, давай сделаем процессор для метода login и добавим его в операции.

php bin/console make:state-processor UserLoginProcessor

Так же добавим метод findOneByLogin в UserRepository для нахождения пользователя по email

  public function findOneByLogin($value): ?User     {         return $this->createQueryBuilder('u')             ->andWhere('u.email = :val')             ->setParameter('val', $value)             ->getQuery()             ->getOneOrNullResult();     }

Теперь добавим логику для процессора.

namespace App\State;  use ApiPlatform\Metadata\Operation; use ApiPlatform\State\ProcessorInterface; use App\Entity\User; use App\Repository\UserRepository; use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException; use Symfony\Component\HttpKernel\Exception\NotFoundHttpException; use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface;  class UserLoginProcessor implements ProcessorInterface {     public function __construct(private UserRepository $repository, private UserPasswordHasherInterface $userPasswordEncoder)     {      }      /**      * @param   User      $data      * @param   Operation  $operation      * @param   array      $uriVariables      * @param   array      $context      *      * @return User      * @throws \Exception      */     public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = [])     {         $user = $this->repository->findOneByLogin($data->getEmail());         if ($user instanceof  User) {              if (!$this->userPasswordEncoder->isPasswordValid($user,  $data->getPlainPassword())) {                 throw new AccessDeniedHttpException();             }              $user->setToken(bin2hex(random_bytes(60)));             $this->repository->save($user, true);             return  $user;         }          throw new NotFoundHttpException();     } }

Если служба автозапуска и автоконфигурации включена (они включены по умолчанию), то все готово!

# api/config/services.yaml services:     # default configuration for services in this file     _defaults:         autowire: true      # Automatically injects dependencies in your services.         autoconfigure: true # Automatically registers your services as commands, event subscribers, etc.

В противном случае, если вы используете пользовательскую конфигурацию внедрения зависимостей, вам необходимо зарегистрировать соответствующую службу и добавить тег api_platform.state_processor.

# api/config/services.yaml services:     # ...     App\State\UserLoginProcessor: ~     # Uncomment only if autoconfiguration is disabled     #tags: [ 'api_platform.state_processor' ]

Осталось создать новый метод для логина и настроить все доступы, как описано в пунктах 3-5

Настроим доступы

Для удовлетворения требований пункта 2, переходим к сущности User и добавим операцию для метода POST /api/login

use App\State\UserLoginProcessor;  ...  #[ApiResource(     normalizationContext: ['groups' => ['user:read']],     denormalizationContext: ['groups' => ['user:create']],     operations: [         new GetCollection(),         new Post(processor: UserPasswordHasherProcessor::class, uriTemplate: '/registration'),         new Post(processor: UserLoginProcessor::class,             uriTemplate: '/login'         ),         new Get(),         new Patch(),         new Delete(),     ] )]

Если взглянуть на swagger, то появился новый метод, который уже работает.

Теперь для пункта 3, наших требований, добавим параметр security для операций Get() и GetCollection()

use App\State\UserLoginProcessor;  ...  #[ApiResource(     normalizationContext: ['groups' => ['user:read']],     denormalizationContext: ['groups' => ['user:create']],     operations: [         new GetCollection(security: "is_granted('ROLE_USER')"),         new Post(processor: UserPasswordHasherProcessor::class, uriTemplate: '/registration'),         new Post(processor: UserLoginProcessor::class,             uriTemplate: '/login'         ),         new Get(security: "is_granted('ROLE_USER')"),         new Patch(),         new Delete(),     ] )]

Теперь, если вызвать эти операции через swagger, без установленного токена, получим ошибку 403 Доступ запрещен

И теперь, самое интересное — пункты 4 и 5.

use App\State\UserLoginProcessor;  ...  #[ApiResource(     normalizationContext: ['groups' => ['user:read']],     denormalizationContext: ['groups' => ['user:create']],     operations: [         new GetCollection(security: "is_granted('ROLE_USER')"),         new Post(processor: UserPasswordHasherProcessor::class, uriTemplate: '/registration'),         new Post(processor: UserLoginProcessor::class,             uriTemplate: '/login'         ),         new Get(security: "is_granted('ROLE_USER')"),         new Patch(security: "object == user",             securityMessage: 'Пароль можно менять только себе'),         new Delete(security: "object == user",             securityMessage: 'Удалять можно только себя'),     ] )]

Доступными переменными являются:

user: текущий объект, вошедший в систему 

object: текущий класс ресурсов во время денормализации, текущий ресурс во время нормализации или коллекция ресурсов 

previous_object: (только после securityPostDenormalize) клон объекта, до внесения изменений — это значение равно null для операций создания нового объекта 

request (только на уровне ресурсов): текущий запрос

Проверки контроля доступа в атрибуте безопасности всегда выполняются перед этапом денормализации. Это означает, что для запросов PUT или PATCH объект содержит не значение, отправленное пользователем, а значения, хранящиеся в данный момент на уровне сохраняемости (persistence layer).

И ещё один момент — для операции Patch() сейчас отображаются поля

{   "email": "string",   "password": "string" }

А хотелось бы настроить поля так, чтобы менять можно было только пароль.

И в результат, выдавать не token, а например email. Для таких целей, можно настроить группы на уровне операции и добавить их на соответствующие поля в сущности.

use App\State\UserLoginProcessor;  ...  #[ApiResource(     normalizationContext: ['groups' => ['user:read']],     denormalizationContext: ['groups' => ['user:create']],     operations: [         new GetCollection(security: "is_granted('ROLE_USER')"),         new Post(processor: UserPasswordHasherProcessor::class, uriTemplate: '/registration'),         new Post(processor: UserLoginProcessor::class,             uriTemplate: '/login'         ),         new Get(security: "is_granted('ROLE_USER')"),         new Patch(security: "object == user",             securityMessage: 'Пароль можно менять только себе',             normalizationContext: ['groups' => ['user:passwordRead']],             denormalizationContext: ['groups' => ['user:passwordUpdate']],             ),         new Delete(security: "object == user",             securityMessage: 'Удалять можно только себя'),     ] )] #[ORM\Entity(repositoryClass: UserRepository::class)] #[ORM\Table(name: '`user`')] class User implements UserInterface, PasswordAuthenticatedUserInterface {     #[ORM\Id]     #[ORM\GeneratedValue]     #[ORM\Column]     private ?int $id = null;      #[Groups(['user:create', 'user:passwordRead'])]     #[ORM\Column(length: 180, unique: true)]     private ?string $email = null;      #[ORM\Column]     private array $roles = [];      /**      * @var string The hashed password      */     #[ORM\Column]     private ?string $password = null;      #[ORM\Column(length: 255)]     #[Groups(['user:read'])]     private ?string $token = null;       #[Groups(['user:create', 'user:passwordUpdate'])]     #[SerializedName('password')]     private $plainPassword;

Вот так, у нас получился гибкий функционал. И, обрати внимание как мало кода было написано! В следующих материалах, расскажу про другие фичи этой библиотеки.

Надеюсь всё было понятно и полезно, и данный материал поможет создавать классные сервисы быстро и безопасно.

Заключение

Вы можете найти код из этого материала на GitHub.

Перевод документации на русский тут

Буду рад вашим добрым советам, замечаниям и здоровой критики.

Отличного дня!