eleven-labs / api-service
Requires
- php: ^5.6 || ^7.0
- ext-json: *
- beberlei/assert: ^2.6
- eleven-labs/api-validator: ^0.5
- php-http/httplug: ^1.0
- php-http/message: ^1.3
Requires (Dev)
- guzzlehttp/psr7: ^1.3
- php-http/guzzle6-adapter: ^1.1
- php-http/mock-client: ^0.3.2
- phpunit/phpunit: ^5.4 || ^7.4
- squizlabs/php_codesniffer: ^3.3
- symfony/property-access: ^2.7 || ^3.4 || ^4.0
- symfony/serializer: ^2.7 || ^3.4 || ^4.0
- symfony/yaml: ^2.7 || ^3.4 || ^4.0
- tedivm/stash: ^0.14.1
Suggests
- symfony/cache: PSR-6 Cache implementation to store an API Schema in cache
- tedivm/stash: PSR-6 Cache implementation tp store an API Schema in cache
README
This component read API service descriptions written in OpenAPi/Swagger 2.0 in order serialize requests, and parse responses into easy to use model structures.
Dependencies
This component rely on well known interfaces that discribe:
- An HTTP client, using interfaces provided by HTTPlug
- HTTP Messages, using the PSR-7: HTTP message interfaces
- Cache (used to cache schema files), using the PSR-6: Caching Interface
Installation
This library can be easily installed via composer
composer require eleven-labs/api-service
Usage
In order to consume an API, you will need to write an API service description.
As of now, we only support swagger files, but we plan to support RAML 1.0 and Api Blueprint in a near future.
For standalone projects usage of the provided builder is encouraged:
<?php $apiService = ElevenLabs\Api\Service\ApiServiceBuilder::create()->build('file:///absolute/path/to/your/schema.json'); $operationId = 'getSomething'; $parameters = ['foo' => 'bar']; // A Synchronous Request /** @var \ElevenLabs\Api\Service\Resource\Resource $resource */ $resource = $apiService->call($operationId, $parameters); // An Asynchronous Request $promise = $apiService->callAsync($operationId, $parameters); /** @var \ElevenLabs\Api\Service\Resource\Resource $resource */ $resource = $promise->wait();
Important: You MUST provide an operationId for each paths described in your swagger file.
Builder Dependencies
You will need one of the HttpClient adapter provided by HttPlug and the HTTP Client Discovery Service.
# install the discivery service composer require php-http/discovery # install one of the http client adapter (here, we use the guzzle6 adapter) composer require php-http/guzzle6-adapter
Builder configuration
The builder provide additional methods to fine tune your API Service:
-
withCacheProvider(CacheItemPoolInterface $cacheProvider)
Cache the API service description using a PSR-6: Cache Interface
-
withHttpClient(HttpClient $httpClient)
Provide an HttpClient implementing the
Http\Client\HttpClient
interface.
By default, it will use theHttp\Discovery\HttpClientDiscovery::find()
method -
withMessageFactory(MessageFactory $messageFactory)
Provide a MessageFactory implementing the
Http\Message\MessageFactory
interface.
By default, it will use theHttp\Discovery\MessageFactoryDiscovery::find()
method -
withUriFactory(UriFactory $uriFactory)
Provide an UriFactory implementing the
Http\Message\UriFactory
interface.
By default, it will use theHttp\Discovery\UriFactory::find()
method -
withSerializer(SerializerInterface $serializer)
Provide a Serializer. By default, it will use the Symfony Serializer.
-
withEncoder(EncoderInterface $encoder)
Add an encoder to encode Request body and decode Response body.
By default, it register Symfony'sJsonEncoder
andXmlEncoder
. -
withPaginationProvider(PaginationProvider $paginatorProvide)
When using the default
ResourceDenormalizer
, you can provide a pagination provider to add pagination informations intoCollection
objects. Available implementations can be found in thesrc/Pagination/Provider
folder. You can create your own by implementing theElevenLabs\Api\Service\Pagination\PaginationProvider
interface. -
withDenormalizer(NormalizerInterface $normalizer)
Add a denormalizer used to denormalize
Response
decoded body.
By default, it use theElevenLabs\Api\Service\Denormalizer\ResourceDenormalizer
that denormalize aResponse
into aResource
object. AResource
object can be anItem
or aCollection
. -
withBaseUri($baseUri)
Provide a base URI from which your API is exposed.
By default, it will use your theschemes
key andhost
key defined in your API service description. -
disableRequestValidation()
Disable
Request
validation against your API service description. Enabled by default -
enableResponseValidation()
Enable
Response
validation against your API service description. Disabled by default. -
returnResponse()
Return a PSR-7 Response when using
ApiService
call()
andcallAsync()
methods instead of a denormalized object. -
setDebug($bool)
Enable debug mode. When enabled, it will expire the schema cache immediatly if a cache implementation is provided using the
withCacheProvider(CacheItemPoolInterface $cacheProvider)
method.