README

将 elliRPC 库集成到 symfony 5 项目的 Symfony 扩展包。

1. 需求
2. 如何安装？
3. 如何配置？
   1. 路由
   2. 文件存储
   3. API 定义
4. 如何提供实现？
   1. 过程验证器
   2. 过程处理器
   3. 事务监听器
   4. 错误工厂
   5. 错误翻译器

需求

此包需要 PHP 版本 8.1 或更高版本，以及版本 5.* 或 6.* 的 symfony/framework-bundle。

elliRPC-library 需要实现 psr/http-message 和 psr/http-factory。

我们建议使用 nyholm/psr7 作为 psr/http-message 和 psr/http-factory 的实现。

如果您不想提供自己的 Ellinaut\ElliRPC\File\ContentTypeGuesserInterface 和 Ellinaut\ElliRPC\File\FilesystemInterface 实现，我们建议使用 symfony/mime 和 symfony/filesystem。

如何安装？

请使用 composer 安装此包： ellinaut/ellirpc-bundle。

执行此命令以安装带有所有建议实现的包

composer req ellinaut/ellirpc-bundle nyholm/psr7 symfony/mime symfony/filesystem

或执行此命令仅安装包并使用自己的实现

composer req ellinaut/ellirpc-bundle

如何启用端点？

要使所有 API 端点可用，请将以下代码片段添加到 config/routes.yaml

elliRPC:
  resource: '@ElliRPCBundle/Resources/config/routes.xml'

如何配置？

如果您想配置此包，请添加文件 config/packages/elli_rpc.yaml。

文件存储

如果您通过本地文件系统使用默认的文件存储实现，默认文件存储将为 %kernel.project_dir%/assets/elliRPC。

您可以通过配置来更改它

elli_rpc:
  defaultFileStorage: '%kernel.project_dir%/apiFiles'

API 定义

请按如下方式配置您的 API 的具体定义

elli_rpc:
  application: 'My API' # default: 'API'
  description: 'My custom API' # default: null
  packages: # list of packages
    myPackage: # name of the package
      description: 'Description of my package.' # default: null
      fallbackLanguage: 'de' # default: null
      procedures: # list of procedure definitions
        myProcedure: # name of the procedure
          description: 'My procedure description' # default: null
          request: # request definition
            data: # transport definition, default: null
              context: null # default: null (for same package)
              schema: 'MySchema' # used schema name
              wrappedBy: # default: null
                context: 'OtherPackageName' # default: null
                schema: 'List'
              nullable: true # default: false
            meta: # meta definition, default: null
              context: 'OtherPackageName' # default: null (for same package)
              schema: 'MetaInfo' # used schema name
          response: # response definition
            data: null # transport definition, default: null, see: request -> data
            meta: null # meta definition, default: null, see: request -> meta
          errors: [ 'my_error' ] # list of possible error codes, default: []
          allowedUsage: 'STANDALONE' # default: null, possible: 'STANDALONE' or 'TRANSACTION'
      schemas: # list of schema definitions
        MySchema: # name of the schema
          abstract: true # default: false
          extends: # default: null
            context: 'https://schema.org' # default: null
            schema: 'Event' # name of the extended schema
          description: 'My schema description' # default: null
          properties: # list of property definitions
            myProperty: # name of the property
              description: '' # default: null
              type: # property type definition
                context: null # default: null
                type: 'string' # the build-in type or name of the used schema
                options: [ '@list' ] # a list of assigned options in the correct order, default: []
      errors: # list of error definitions
        my_error: # unique error code within the package
          description: 'My error description' # default: null
          context: # default: null
            context: 'https://schema.org' # default: null
            schema: 'Thing' # name of the used schema

如何提供实现？

您可以通过在 symfony 依赖注入容器中对服务进行标记来添加自定义实现。

如果您的容器使用自动配置，大多数服务将自动标记，因为 symfony 容器将根据它们实现的接口来识别它们。

过程验证器

您的过程验证器必须实现 Ellinaut\ElliRPC\Procedure\Validator\ProcedureValidatorInterface，并使用 elli_rpc.procedure_validator 标记，以便此包可以找到和使用它。

services:
  App\Api\Validator\CustomProcedureValidator:
    tags: [ 'elli_rpc.procedure_validator' ]

如果您的容器使用自动配置，则服务将自动标记和使用，无需手动标记。

过程处理器

您的过程处理器可以通过两种不同的方式配置。

第一种（也是建议的）方式是实现 Ellinaut\ElliRPCBundle\Autoconfigure\DetectableProcedureProcessor 或扩展 Ellinaut\ElliRPCBundle\Autoconfigure\AbstractDetectableProcedureProcessor。这些服务应标记为 elli_rpc.procedure_processor.detected。

services:
  App\Api\Procedure\MyProcedure:
    tags: [ 'elli_rpc.procedure_processor.detected' ]

如果您的容器使用自动配置，则服务将自动标记和使用，无需手动标记。

第二种方式是实现仅 Ellinaut\ElliRPC\Procedure\Processor\ProcedureProcessorInterface，并通过服务定义手动配置 package 和 procedure。

services:
  App\Api\Procedure\CustomProcedureProcessor:
    tags:
      - { name: 'elli_rpc.procedure_processor', package: 'myPackage', procedure: 'myProcedure' }

此选项不是自动配置的，但提供了为多个过程注册单个处理器的可能性。

事务监听器

您的交易监听器必须实现 Ellinaut\ElliRPC\Procedure\Transaction\TransactionListenerInterface，并使用 elli_rpc.transaction_listener 标记，以便此包可以找到和使用它。

services:
  App\Api\Transaction\CustomTransactionListener:
    tags: [ 'elli_rpc.transaction_listener' ]

如果您的容器使用自动配置，则服务将自动标记和使用，无需手动标记。

错误工厂

您的错误工厂必须实现 Ellinaut\ElliRPC\Error\Factory\ErrorFactoryInterface，并使用 elli_rpc.error_factory 标记，以便此包可以找到和使用它。

services:
  App\Api\Error\CustomErrorFactory:
    tags: [ 'elli_rpc.error_factory' ]

如果您的容器使用自动配置，则服务将自动标记和使用，无需手动标记。

错误翻译器

您的错误翻译器必须实现 Ellinaut\ElliRPC\Error\Translator\ErrorTranslatorInterface 接口，并且需要使用 elli_rpc.error_translator 标签来被此包找到和使用。

services:
  App\Api\Error\CustomErrorTranslator:
    tags: [ 'elli_rpc.error_translator' ]

如果您的容器使用自动配置，则服务将自动标记和使用，无需手动标记。