README

此包提供创建REST应用程序中CRUD操作的简单方法。包含每个资源的简单灵活配置。

安装

安装简单。只需遵循以下步骤

需求

composer require kami/api-core-bundle

将其添加到您的内核中

<?php

// AppKernel.php

    public function registerBundles()
    {
        $bundles = [
            ...
            new Kami\ApiCoreBundle\KamiApiCoreBundle(),
            ...
        ];
    }

配置

添加您的资源

# app/config/config.yml

kami_api_core:
  locales: ['en', 'de']
  resources:
    - { name: your-resource-name, entity: AppBundle\Entity\YourEntiy }

添加KamiApiCore路由加载器

kami_api_core:
    resource: '@KamiApiCoreBundle/Resources/config/routing.xml'

现在您已经准备好开始使用了。

工作流程

路由加载器

包将为您的配置中指定的每个资源生成5个路由

• GET /api/your-resource-name - 索引路由
• GET /api/your-resource-name/{id} - 获取单个资源
• GET /api/your-resource-name/filter - 过滤资源
• POST /api/your-resource-name - 创建资源
• PUT /api/your-resource-name/{id} - 更新资源
• DELETE /api/your-resource-name/{id} - 删除资源

如果资源实体实现了KamiApiCoreBundle\Model\UserAwareInterface，则将生成额外的路由

• GET /api/my/your-resource-name - 获取属于当前用户的所有资源

注意！在修改资源后，您必须清除缓存

访问规则

您必须使用注解在实体中定义访问规则。默认情况下，所有资源都有受限制的访问权限。您必须明确授予每个用户角色的访问权限。

策略

该包利用策略模式并为每个路由提供默认策略。您可以通过资源配置覆盖任何策略。

示例

# app/config/config.yml

kami_api_core:
  locales: ['en', 'de']
  resources:
      - name: your-resource-name 
        entity: AppBundle\Entity\YourEntiy 
        strategies:
            index:  "%my_awesome_index_strategy%"
            filter: "%my_awesome_filter_strategy%" 
            item:   "%my_awesome_item_strategy%"
            create: "%my_awesome_create_strategy%"
            update: "%my_awesome_update_strategy%"
            delete: "%my_awesome_delete_strategy%"

默认策略

默认策略采用以下步骤

索引

• 从请求获取反射
• 验证资源访问权限
• 获取查询构建器
• 构建选择查询
• 排序
• 分页
• 序列化响应数据

条目

• 从请求获取反射
• 验证资源访问权限
• 获取查询构建器
• 构建选择查询
• 添加条件
• 设置选择数据
• 序列化响应数据

创建

• 从请求获取反射
• 验证资源访问权限
• 从反射获取实体
• 构建创建表单
• 处理请求
• 验证表单
• 持久化
• 修剪响应
• 序列化响应数据

更新

• 从请求获取反射
• 验证资源访问权限
• 根据ID获取实体
• 构建更新表单
• 处理请求
• 验证表单
• 持久化
• 修剪响应
• 序列化响应数据

删除

• 从请求获取反射
• 验证资源访问权限
• 根据ID获取实体
• 删除

过滤

• 从请求获取反射
• 验证资源访问权限
• 获取查询构建器
• 构建选择查询
• 验证过滤器
• 过滤
• 排序
• 分页
• 序列化响应数据

添加自定义步骤

要添加自定义步骤，只需扩展Kami\ApiCoreBundle\RequestProcessor\Step\AbstractStep

示例

<?php 

namespace Acme\AppBundle\Step;

use Kami\ApiCoreBundle\RequestProcessor\Step\AbstractStep;

class MyStep extends AbstractStep
{
    public function execute()
    {
        // Do your stuff here
        
        return $this->createResponse(['your_data' => $data]);
    }

    public function requiresBefore()
    {
        return [MyStep::class];
    }
}

# services.yml

my_awesome_step: 
    class: Acme\AppBundle\Step\MyStep
    arguments:
      - "@service"
      - ...
    tags: 
      - { name: kami_api_core.strategy_step, shortcut: "my_step" }    
        

表单生成

默认策略将为POST和PUT操作生成表单。仅包括当前用户可访问的字段。

请参阅注解参考中的@CanBeCreatedBy、@CanBeEditedBy、@AnonymousCreate、@AnonymousEdit和@Form。

请求体转换器

大多数前端库以json格式发送表单数据。包将转换此负载并将参数注入到请求数据中

过滤器

GET /api/your-resource-name/filter端点接受查询参数filter，它应包含应用过滤器的base64编码json负载

可用的过滤器及其示例

可用的过滤器有

• eq - 等于
• gt - 大于
• lt - 小于
• lk - 类似于
• bw - 在...

示例

// Equals
{"type": "eq", "property": "id", "value": 1}]
// Greater than
{"type": "gt", "property": "id", "value": 3}]
// Lower than
{"type": "lt", "property": "id", "value": 3}]
// Like
{"type": "lk", "property": "title", "value": "foo"}]
// Between
{"type": "bw", "property": "id", "min": 1, "max": 5}]

排序

您可以使用sort和direction查询参数对index和filter路由响应进行排序。sort参数应表示实体字段，而direction可以是asc或desc

示例

GET /api/your-resource-name?sort=property&direction=desc

注解参考

@Access

定义可以访问资源或属性的角色的权限

使用示例

<?php

namespace AppBundle\Entity;

use Kami\ApiCoreBundle\Annotation as Api;

class YourEntity
{
    ...
        
    /**
     * @Access({"ROLE_USER", "ROLE_ADMIN"})
     * @ORM\Column(name="property", type="string", length=255)
     */
    private $property;
    
    ...
}

@AnonymousAccess

定义对资源的匿名访问

使用示例

<?php

namespace AppBundle\Entity;

use Kami\ApiCoreBundle\Annotation as Api;

/**
 * @Api\AnonymousAccess
 */
class YourEntity
{
    ...
        
    /**
     * @ORM\Column(name="property", type="string", length=255)
     * @Api\AnonymousAccess
     */
    private $property;
    
    ...
}

@AnonymousCreate

定义匿名用户是否可以创建资源

使用示例

<?php

namespace AppBundle\Entity;

use Kami\ApiCoreBundle\Annotation as Api;

/**
 * @Api\AnonymousCreate
 */
class YourEntity
{
    ...
        
    /**
     * @ORM\Column(name="property", type="string", length=255)
     * @Api\AnonymousCreate 
     */
    private $property;
    
    ...
}

@AnonymousEdit

定义匿名用户是否可以编辑资源

使用示例

<?php

namespace AppBundle\Entity;

use Kami\ApiCoreBundle\Annotation as Api;

/**
 * AnonymousUpdate
 */
class YourEntity
{
    ...
        
    /**
     * @ORM\Column(name="property", type="string", length=255)
     */
    private $property;
    
    ...
}

@CanBeCreatedBy

定义可以创建资源或属性的角色的权限

使用示例

<?php

namespace AppBundle\Entity;

use Kami\ApiCoreBundle\Annotation as Api;

/**
 * @Api\CanBeCreatedBy({"ROLE_USER", "ROLE_ADMIN"})
 */
class YourEntity
{
    ...
        
    /**
     * @Api\CanBeCreatedBy({"ROLE_USER", "ROLE_ADMIN"})
     * @ORM\Column(name="property", type="string", length=255)
     */
    private $property;
    
    ...
}

@CanBeEditedBy

定义可以更新资源或属性的角色的权限

使用示例

<?php

namespace AppBundle\Entity;

use Kami\ApiCoreBundle\Annotation as Api;

/**
 * CanBeUpdatedBy({"ROLE_USER", "ROLE_ADMIN"})
 */
class YourEntity
{
    ...
        
    /**
     * @Api\CanBeUpdatedBy({"ROLE_USER", "ROLE_ADMIN"})
     * @ORM\Column(name="property", type="string", length=255)
     */
    private $property;
    
    ...
}

@Form

用于定义表单选项。接受两个参数：type 和 options。请参阅 Symfony 表单组件文档

使用示例

<?php

namespace AppBundle\Entity;

use Kami\ApiCoreBundle\Annotation as Api;

class YourEntity
{
    ...
        
    /**
     * @Api\Form(type="Symfony\Component\Form\Extension\Core\Type\DateTimeType", options={"widget": "single_text"})
     * @ORM\Column(name="property", type="datetime")
     */
    private $property;
    
    ...
}