ellinaut / ellirpc-bundle
Symfony integration for ellinaut/ellirpc
Installs: 337
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 3
Forks: 0
Open Issues: 0
Type:symfony-bundle
Requires
- php: >=8.1
- ellinaut/ellirpc: ^1.0
- symfony/framework-bundle: ^5.0|^6.0
- symfony/psr-http-message-bridge: ^2.0
README
Symfony bundle to integrate the elliRPC library into a symfony 5 project.
- Requirements
- How to install?
- How to configure?
- Routing
- File Storage
- API-Definition
- How to provide implementations?
- Procedure Validator
- Procedure Processor
- Transaction Listener
- Error Factory
- Error Translator
Requirements
The bundle requires PHP in version 8.1 or higher and symfony/framework-bundle
in version 5.* or 6.*.
The elliRPC-library requires implementations of psr/http-message
and psr/http-factory
.
We suggest to use nyholm/psr7
as implementation for psr/http-message
and psr/http-factory
.
If you don't want to provide your own implementations of Ellinaut\ElliRPC\File\ContentTypeGuesserInterface
and
Ellinaut\ElliRPC\File\FilesystemInterface
we suggest to use symfony/mime
and symfony/filesystem
.
How to install?
The bundle should be installed via composer: ellinaut/ellirpc-bundle
.
Execute this command to install the bundle with all suggested implementations:
composer req ellinaut/ellirpc-bundle nyholm/psr7 symfony/mime symfony/filesystem
or execute this command to only install the bundle and use your own implementations matching the requirements:
composer req ellinaut/ellirpc-bundle
How to enable endpoints?
To make all API endpoints available add this snippet to config/routes.yaml
:
elliRPC: resource: '@ElliRPCBundle/Resources/config/routes.xml'
How to configure?
If you want to configure the bundle you should add the file config/packages/elli_rpc.yaml
.
File Storage
If you use the default file storage implementation via local file system, the default file storage will
be %kernel.project_dir%/assets/elliRPC
.
You can change it via configuration:
elli_rpc: defaultFileStorage: '%kernel.project_dir%/apiFiles'
API-Definition
To configure the concrete definition of your API please configure it as follows:
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
How to provide implementations?
Your custom implementations can be added via tagging your services in the symfony dependency injection container.
If your container uses autoconfiguration most of your services will be tagged automatically because the symfony container will identify them by their implemented interfaces.
Procedure Validator
Your procedure validator, which have to implement Ellinaut\ElliRPC\Procedure\Validator\ProcedureValidatorInterface
,
have to be tagged with elli_rpc.procedure_validator
to be found and used by this bundle.
services: App\Api\Validator\CustomProcedureValidator: tags: [ 'elli_rpc.procedure_validator' ]
If your container uses autoconfiguration your service will be tagged and used automatically without the need of manual tagging.
Procedure Processor
Your procedure processors could be configured in two different ways.
First (and suggested) variant will be implementing Ellinaut\ElliRPCBundle\Autoconfigure\DetectableProcedureProcessor
or extending Ellinaut\ElliRPCBundle\Autoconfigure\AbstractDetectableProcedureProcessor
.
These services should be tagged with elli_rpc.procedure_processor.detected
.
services: App\Api\Procedure\MyProcedure: tags: [ 'elli_rpc.procedure_processor.detected' ]
If your container uses autoconfiguration your services will be tagged and used automatically without the need of manual tagging in this case.
The second variant will be implementing only Ellinaut\ElliRPC\Procedure\Processor\ProcedureProcessorInterface
and
configure package
and procedure
manually via service definition:
services: App\Api\Procedure\CustomProcedureProcessor: tags: - { name: 'elli_rpc.procedure_processor', package: 'myPackage', procedure: 'myProcedure' }
These variant is not autoconfigured but provides the possibility of register a single processor for multiple procedures.
Transaction Listener
Your transaction listener, which have to implement Ellinaut\ElliRPC\Procedure\Transaction\TransactionListenerInterface
, have to be tagged with elli_rpc.transaction_listener
to be found and used by this bundle.
services: App\Api\Transaction\CustomTransactionListener: tags: [ 'elli_rpc.transaction_listener' ]
If your container uses autoconfiguration your service will be tagged and used automatically without the need of manual tagging.
Error Factory
Your error factory, which have to implement Ellinaut\ElliRPC\Error\Factory\ErrorFactoryInterface
, have to be
tagged with elli_rpc.error_factory
to be found and used by this bundle.
services: App\Api\Error\CustomErrorFactory: tags: [ 'elli_rpc.error_factory' ]
If your container uses autoconfiguration your service will be tagged and used automatically without the need of manual tagging.
Error Translator
Your error translator, which have to implement Ellinaut\ElliRPC\Error\Translator\ErrorTranslatorInterface
, have to be
tagged with elli_rpc.error_translator
to be found and used by this bundle.
services: App\Api\Error\CustomErrorTranslator: tags: [ 'elli_rpc.error_translator' ]
If your container uses autoconfiguration your service will be tagged and used automatically without the need of manual tagging.