2amigos / storage-service
Slim 3 storage API microservice
Installs: 10
Dependents: 0
Suggesters: 0
Security: 0
Stars: 9
Watchers: 6
Forks: 0
Open Issues: 0
Type:project
Requires
- php: ^7.2
- ext-http: *
- ext-json: ^1.6
- ext-pdo: *
- crell/api-problem: ^2.0
- doctrine/dbal: ^2.6
- enqueue/enqueue-bundle: ^0.9.7
- enqueue/fs: ^0.9.2
- gettext/gettext: ^4.6
- gofabian/negotiation-middleware: ^0.1.2
- guzzlehttp/guzzle: ^6.3
- league/flysystem: ^1.0
- league/fractal: ^0.13.0
- league/tactician: ^1.0
- lstrojny/functional-php: ^1.6
- micheh/psr7-cache: ^0.5.0
- monolog/monolog: ^1.17
- pagerfanta/pagerfanta: ^2.0
- ramsey/uuid: ^3.8
- robmorgan/phinx: ^0.10.6
- slim/slim: ^3.9
- symfony/console: ^4.2
- symfony/dotenv: ^4.2
- symfony/framework-bundle: ^4.2
- symfony/yaml: ^4.2
- tuupola/base62: ^1.0
- tuupola/cors-middleware: ^0.8.0
- tuupola/slim-basic-auth: ^3.2
- tuupola/slim-jwt-auth: ^3.1
- zendframework/zend-inputfilter: ^2.8
- zendframework/zend-paginator: ^2.8
Requires (Dev)
- friendsofphp/php-cs-fixer: ^2.10@dev
- fzaninotto/faker: ^1.8
- overtrue/phplint: ^1.0
- phpstan/phpstan: ^0.11.2
- phpunit/phpunit: ^7.3
- roave/security-advisories: dev-master
- squizlabs/php_codesniffer: ^3.2
This package is auto-updated.
Last update: 2024-12-22 09:44:31 UTC
README
The Storage service is a microservice that stores files using league/flysystem filesystem abstraction.
It was built to allow our development teams at 2amigos to avoid having to configure storage adapters over and over on projects involving a microservices infrastructure. It's a combination of two separate applications, one being Symfony's CI application and the other being an API built with Slim3.
The project uses Monolog for logging, Fractal as a serializer, Tactitian as a command bus, Basic access authentication and Json Web Tokens for authentication (this is optional), Zend filter for data filtering and validation, and Phinx for database migrations.
Docker compose and Postman collection files are included for easy development, even though docker
is not strictly necessary for development as you could easily use the built-in PHP server.
This project tries to follow DDD principles.
Install
Install the latest version using composer.
$ composer create-project --no-interaction --stability=dev 2amigos/storage-service app
If you are using it from a private repository (using a github url here as an example).
$ composer create-project --no-interaction --stability=dev 2amigos/storage-service app --repository-url=https://github.com/2amigos/storage-service
Configuration
The project uses environment files to configure secrets. For that reason, you must create a file named .env
in the root directory of the project. An .env.example
file has been provided with all required environment values. Modify that file and save it as .env
in the root directory.
By default, the API application is configured to work under basic authentication processes. It uses an array of users for that purpose but you could easily change that behavior by configuring the authenticator
option of the [HttpBasicAuthentication middleware(https://github.com/tuupola/slim-basic-auth/blob/3.x/src/HttpBasicAuthentication.php#L43) by creating your own or using one provided by the library. Check the PdoAuthenticator.
If authentication is successful, the action will return a Json Web Token to be used for subsequent calls.
Authentication, or the usage of scopes, are optional. If you don't wish to work with this kind of setup, simply remove the middleware configurations of HttpBasicAuthentication
, JwtAuthentication
and ScopeMiddleware
middlewares.
Usage
Create a database with the credentials that you used in .env
file. Now you can run Phinx database migrations with this command:
./vendor/bin/phinx migrate -e development
For the sake of this example, go to the public
folder of the app and start the built-in PHP server like this:
php -S localhost:8080
Now we can access the api at http://127.0.0.1:8080
.
Get a token
To get a token, use the following:
$ curl "https://127.0.0.1:8080/token" \ --request POST \ --include \ --insecure \ --header "Content-Type: application/json" \ --data '["mail.all"]' \ --user test:test HTTP/1.1 201 Created Content-Type: application/json { "data": { "token": "XXXXXXXXXX", "expires": 1550271641 } }
Storing a document
Synchronous
Using the token
, you can now post a request using application/form-data
to store a document.
$ curl -X POST \ https://127.0.0.1:8080/document/store \ -H 'Authorization: Bearer YOUR_TOKEN_HERE' \ -H 'Cache-Control: no-cache' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'Postman-Token: 22bf2715-35e4-41ee-a04b-fd8beddcdd62' \ -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \ -F name=nameofthedocument \ -F async=false \ -F 'document=@/path/to/document/to/attach/41835188_10217308479844850_6484466208170049536_o.jpg'
The above command will create an email message on the spool directory, configured by default at the runtime
folder.
Asynchronous
Sending a document to the queue
Enqueue is default queue service and it is configured to use runtime/queue
directory.
curl -X POST \ https://127.0.0.1:8080/document/store \ -H 'Authorization: Bearer YOUR_TOKEN_HERE' \ -H 'Cache-Control: no-cache' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'Postman-Token: 22bf2715-35e4-41ee-a04b-fd8beddcdd62' \ -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \ -F name=nameofthedocument \ -F async=true \ -F 'document=@/path/to/document/to/attach/41835188_10217308479844850_6484466208170049536_o.jpg'
The above command will create an email message on the spool directory, configured by default at the runtime
folder.
Getting document from the queue and storing it
We use Enqueue Filesystem Transport to ease the task of storing documents from the queue as it comes with some handy commands.
The php-enqueue/enqueue-bundle comes with a set of pretty handy commands. For the full reference of those commands, please go to its documentation.
The one to consume all the documents that go to the queue is enqueue:consume
:
./bin/console enqueue:consume storage --no-interaction -vvv --receive-timeout=60000
The endpoint response will have the document's uuid which you can use in other calls:
{
"data": {
"success": true,
"status": 3,
"uuid": "136b4cdf-736e-488a-a427-b1d1114f376d"
}
}
Pagination
For pagination you can use Pagerfanta or Cursor. You can use either, it depends on your configuration inside dependencies.php
- $container['paginator'] = $container['paginator.pagerfanta'];
If you want to read more about Fractal pagination, you can do it here Fractal Pagination
Examples:
Pagerfanta
https://127.0.0.1:8080/documents/list?filter=limit(3|1):order(created_at|desc)
In response you will see something like this:
"meta": {
"pagination": {
"total": 17,
"count": 3,
"per_page": 3,
"current_page": 2,
"total_pages": 6,
"links": {
"previous": "https://127.0.0.1:8080/documents/list?filter=limit(3|1):order(created_at|desc)",
"next": "https://127.0.0.1:8080/documents/list?filter=limit(3|3):order(created_at|desc)"
}
}
}
Also notice that you have next and previous links that you can use.
Cursor
https://127.0.0.1:8080/documents/list?cursor=limit(3|2)
Where 3
is the limit and 2
is a starting ID that is used as a cursor. You will get something like this:
"meta": {
"cursor": {
"current": "2",
"prev": null,
"next": "4",
"count": 3
}
}
Testing
For testing we are using PHPUnit
Set Up
To set up your testing environment, a few steps are needed:
- create
.env.test
file. You can use.env.example
and modify it's values to create test file. Value ofAPP_ENV
should betest
- create a testing database and use values from your
env.test
file. - run a migration to populate the test database
./vendor/bin/phinx migrate -e testing
- change env file being used in
./phinx.php
to.env.test
Running tests
First you need to run your local test server. Go to the public/test/
directory and use this command:
php -S localhost:8081
If there are no errors, you should see that the test server is listening on the port 8081
-
Listening on http://localhost:8081
Finally run tests with this command:
./vendor/bin/phpunit --testdox tests --bootstrap tests/autoload.php
Contributing
To contribute, please read our CONTRIBUTION guidelines.
Credits
- Tuupola slim api skeleton Thanks for the boilerplate inspiration!
- 2amigos
- All Contributors
License
The BSD License (BSD). Please see License File for more information.
Beyond Software
www.2amigos.us