Commit 4170ddc3 authored by Patrick Barroca's avatar Patrick Barroca 😁
Browse files

improve readme

parent ccf136c0
Pipeline #16841 passed with stage
in 38 seconds
Pellicule is a RESTFul service that fetches records media from multiple providers
# Pellicule
I'm a RESTFul service that fetches records media from multiple providers.
I use [Slim Framework 4](https://github.com/slimphp/Slim) as a lightweight framework.
## Install
### Code
Beware: I use a mix of two dependencies management systems
* [git submodules](https://git-scm.com/docs/gitsubmodules) see [declared modules](.gitmodules)
* [composer](https://getcomposer.org)
Clone repository, then get dependencies with
Further more, as I do not want to depend on composer packagist repository availability, even composer packages are provided as [submodule repository](https://git.afi-sa.net/afi/pellicule-dependency)
To have a local copy of me, simply clone this repository, then get submodules dependencies with
```sh
git submodule init
git submodule update
```
This will download composer packages in vendor directory and storm in library/storm.
### Datas
### Run unit tests
Import all sql files from database directory in filename order into mariadb.
```sh
vendor/bin/phpunit -c tests/phpunit.xml
```
### Init datas
Import all sql files from [database](/database) directory in filename order into mariadb.
## Configuration
I load configuration files from [public index](public/index.php) at Slim application bootstraping time.
### Database access
Database connection is configured in conf/database.php, see conf/database.template.php.
My database connection must be configured in a file conf/database.php, see [conf/database.template.php](conf/database.template.php).
Supported values are described in [storm configuration](https://git.afi-sa.net/afi/storm-light/-/blob/master/src/Persistence/Configuration.php)
### HTTP client
My HTTP client options must be configured in a file conf/http_client.php, see [conf/http_client.template.php](conf/http_client.template.php)
Supported values are described in [Buzz Client Curl](https://git.afi-sa.net/afi/pellicule-dependency/-/blob/master/kriswallsmith/buzz/lib/Client/AbstractCurl.php#L190)
### Thumbnails persistence
My thumbnails persistence must be configured in a file conf/persistence.php, see [conf/persistence.template.php](conf/persistence.template.php)
The only option is `base_path` to set path where downloaded thumbnails will be saved, it is relative to public folder
## Try API
### Http client options
The root of the service will display a swagger interface to try calling the API
Http client options are configured in conf/http_client.php see conf/http_client.template.php
OpenAPI file is available at [public/openapi.yml](public/openapi.yml)
## Add new thumbnails provider
## Dependencies handling
When a client ask for a record thumbnail through its ISBN, EAN or ARK, I will try to find it firstly in my local database.
### Composer
If it's not found and the client provided an Authorization header, I will try to find a provider for this Authorization header.
For dependencies available through composer use it but vendor directory is handled as submodule to not depend on packagist servers availability.
To be valid the header must start with "Pellicule " followed by base64 encoded JSON string with at least a "provider" property.
So any composer commands resulting in vendor directory content modification should be committed in its dedicated repository.
My [RemoteProviders](src/Providers/RemoteProviders.php) class will try to match the "provider" property value with any of its known providers `$this->_providers`
### Others
Adding a new provider will require to add a new class extending src/Providers/RemoteProvider.php and declare it in `RemoteProviders::$_providers`
Other dependencies are handled as submodules in library directory.
This new class
* MUST have a `const ID` or implements `static function handles(string $provider_id) : bool` to be matched by RemoteProviders
* SHOULD implement `function providerName() : string` as it defaults to full namespaced class name which is not very user-friendly
* SHOULD override constructor to receive and store credentials
* MUST validate credentials for your provider by implementing `_isValidCredentials() : bool`, I will extract them from the Authorization header and provide them in the constructor of your remote provider
* MUST compute the thumbnail url for a given identifier by implementing `_coverUrl(string $identifier)`
You can review already existing providers for inspiration.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment