README

API 工具包 Bundle，用于处理 POST、PUT、PATCH 和 DELETE 方法。

安装

使用 composer 安装该软件包

composer require check24/apitk-manipulation-bundle

用法

示例类

查看此存储库中的 example 文件夹：[https://github.com/alexdo/apitk-manipulation-bundle/tree/master/example](https://github.com/alexdo/apitk-manipulation-bundle/tree/master/example)

用户实体

namespace MyApp\Entity;

use Symfony\Component\Validator\Constraints as Assert;

class User
{
    private $id;

    /**
     * @Assert\NotBlank()
     */
    private $username;

    /**
     * @Assert\NotBlank()
     * @Assert\Email()
     */
    private $email;

    /**
     * @Assert\NotBlank()
     */
    private $fullname;

    // ...
}

用户表单类型

namespace MyApp\Form\Type;

use MyApp\Entity\User;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\EmailType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;

class UserV1Type extends AbstractType
{
    /**
     * @param FormBuilderInterface $builder
     * @param array                $options
     */
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            ->add('username', TextType::class)
            ->add('email', EmailType::class)
            ->add('fullname', TextType::class);
    }

    public function configureOptions(OptionsResolver $resolver)
    {
        $resolver->setDefaults(
            [
                'data_class' => User::class,
            ]
        );
    }
}

控制器

namespace MyApp\Controller;

use FOS\RestBundle\Controller\Annotations as Rest;
use MyApp\Entity\User;
use Shopping\ApiTKManipulationBundle\Annotation as Manipulation;
use Swagger\Annotations as SWG;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Symfony\Component\HttpFoundation\Response;

class UserV1Controller extends Controller
{
    /**
     * Create a new user.
     *
     * @Rest\Post("/v1/users/{id}")
     * @Manipulation\Update("user", type=UserV1Type::class)
     *
     * @SWG\Tag(name="User")
     *
     * @param User $user
     *
     * @return Response
     */
    public function postUserV1(User $user): Response
    {
        return new Response('', 200);
    }

    /**
     * Update all properties of a given user.
     *
     * @Rest\Put("/v1/users/{id}")
     * @Manipulation\Update("user", type=UserV1Type::class)
     *
     * @SWG\Tag(name="User")
     *
     * @param User $user
     *
     * @return Response
     */
    public function putUserV1(User $user): Response
    {
        return new Response('', 200);
    }

    /**
     * Partially update a users's properties.
     *
     * @Rest\Patch("/v1/users/{id}")
     * @Manipulation\Update("user", type=UserV1Type::class)
     *
     * @SWG\Tag(name="User")
     *
     * @param User $user
     *
     * @return Response
     */
    public function patchUserV1(User $user): Response
    {
        return new Response('', 200);
    }

    /**
     * Remove a user.
     *
     * @Rest\Delete("/v1/user/{id}")
     *
     * @Manipulation\Delete("id", entity=User::class)
     *
     * @SWG\Tag(name="User")
     *
     * @return Response
     */
    public function deleteUserV1(Response $response): Response
    {
        return $response;
    }
}

更新实体（POST、PUT、PATCH）

更新实体通过将请求数据映射到表单、验证它然后将表单数据持久化到数据库（通过 Doctrine）来实现。

您需要

• Doctrine 实体
• 带有 data_class 的表单类型
• 控制器操作

use Shopping\ApiTKManipulationBundle\Annotation as Manipulation;

/**
 * Partially update a users's properties.
 *
 * @Rest\Patch("/v1/users/{id}")
 * @Manipulation\Update("user", type=UserV1Type::class)
 *
 * @SWG\Tag(name="User")
 *
 * @param User $user
 *
 * @return Response
 */
public function patchUserV1(User $user): Response
{
    return new Response('', 200);
}

这将自动生成适当的 Swagger 参数。使用 FOSRest bundle 是可选的。控制器方法对 POST 和 PUT 是相同的。

$user 参数是请求的用户已更新版本。您可以用它做任何事情：序列化、JSON 编码等。

内部，Update 注解获取默认的 EntityManager，获取 Repository 并对其执行 find($id)。您可以通过以下三种方式自定义此操作

1. 如果您想使用与 default 不同的 ORM 连接，请通过 entityManager 提供它

   @Manipulation\Update("user", type=UserV1Type::class, entityManager="custom")
   

   这将导致注解从 "custom" EntityManager 中获取 Repository 和实体。

2. 如果您想使用与 find 不同的 不同 Repository 方法，请使用 methodName 选项

   @Manipulation\Update("user", type=UserV1Type::class, methodName="findById")
   

3. 如果您的 路径组件 与 id 不同，例如 email，您可以通过 requestParam 选项提供要使用的参数

   @Manipulation\Update("user", type=UserV1Type::class, requestParam="email", methodName="findByEmail")
   

删除实体（DELETE）

要删除实体，请向控制器添加使用 Delete-注解的操作。

use Shopping\ApiTKManipulationBundle\Annotation as Manipulation;

/**
 * Remove a user.
 *
 * @Rest\Delete("/v1/user/{id}")
 *
 * @Manipulation\Delete("id", entity=User::class)
 *
 * @SWG\Tag(name="User")
 *
 * @return Response
 */
public function deleteUserV1(Response $response): Response
{
    return $response;
}

@Manipulation\Delete("id", entity=User::class)

• "id" 是获取 ID 的路径组件名称
• entity=User::class 是要删除的实体类型

$response 参数是一个 HTTP 204-响应（无内容）。您可以简单地返回它，或者忽略它并构建自己的响应。

默认情况下，Delete 将通过在 UserRepository 上执行 find($id) 并通过 ObjectManager::remove 删除实体来执行硬删除。

与 Update 一样，您可以自定义此行为

1. 如果您想执行 软删除或其他操作，请使用 methodName 选项

   @Manipulation\Delete("id", entity=User::class, methodName="deleteById")
   

   这将导致注解调用 DeleteRepository::deleteById(DeletionService $deletionService)。DeletionService 允许您访问所有请求参数。执行任何操作以标记实体为已删除，例如将已删除属性从 0 设置为 1，然后刷新 EntityManager。

2. 如果您想使用与 default 不同的 ORM 连接，请通过 entityManager 提供它

   @Manipulation\Delete("id", entity=User::class, entityManager="custom")
   

   这将导致注解针对 "custom" EntityManager 运行。