eonx-com/apiformats

Package for working with API requests and responses in different formats

v1.0.6 2020-03-27 00:19 UTC

Requires

• php: >=7.1
• ext-json: *
• doctrine/inflector: ^1.3
• eonx-com/utils: ^1.0 || ^2.0
• laminas/laminas-diactoros: ^2.1
• league/fractal: ^0.17.0 || ^0.19
• symfony/psr-http-message-bridge: ^1.0
• woohoolabs/yang: ^1.4

Requires (Dev)

• eonx-com/standards: ^0.3
• illuminate/http: ^5.8 || ^6.0
• illuminate/support: ^5.8 || ^6.0
• laravel/lumen-framework: ^5.8 || ^6.0
• phpmd/phpmd: 2.6.*
• phpstan/phpstan: ^0.11
• phpstan/phpstan-phpunit: ^0.11
• phpstan/phpstan-strict-rules: ^0.11
• phpunit/phpunit: ^8.5
• roave/security-advisories: dev-master
• sebastian/phpcpd: ^4.0
• squizlabs/php_codesniffer: ^3.0
• vlucas/phpdotenv: ^3.0

Suggests

• illuminate/http: To use the Laravel implementation
• illuminate/support: To use Laravel service provider

Provides

• php-http/client-implementation: 1.0

Replaces

• eoneopay/apiformats: *

BSD-3-Clause

• api
• formats
• eoneopay

README

Installation

Use Composer to install the package in your project:

composer require eoneopay/apiformats

Formats

By default the package handle JSON (application/json) and XML (application/xml, text/xml) formats. If you want to handle different formats or want to implement your own JSON/XML encoding logic, the only thing you need to do is creating your encoder implementing \EoneoPay\ApiFormats\Interfaces\RequestEncoderInterface and tell the package to use it, with which Mime types as explained in the Configuration section.

Integration

Laravel

To integrate the package into your Laravel or Lumen you need to register the following service provider and middleware:

• ServiceProvider: \EoneoPay\ApiFormats\Bridge\Laravel\Providers\ApiFormatsServiceProvider
• Middleware: \EoneoPay\ApiFormats\Bridge\Laravel\Middlewares\ApiFormatsMiddleware

That's it! Your application is now able to easily receive requests and generate responses in several formats.

Formatted Api Response

If you want to customise the generated response as its status code or headers without handling body encoding yourself, the package provides the \EoneoPay\ApiFormats\Bridge\Laravel\Responses\FormattedApiResponse object you can return from your controllers/middlewares. The FormattedApiResponse accept three parameters through its constructor as following:

• $content (mixed): array or object able to be cast as an array
• $statusCode (int): status code of response, default as 200
• $headers (array): headers of response, default as empty array

Configuration

The philosophy of the package is to map encoders to a list of MIME types that they can handle through an array as following:

$formats = [
    <RequestEncoderInterface> => [<mime_type>, <mime_type>, ...]
];

Each MIME type can be the exact name as application/json or a Regex used to match multiple MIME types as application/vnd.eoneopay.v[0-9]+\+json.

Laravel

To configure supported formats in your application, create a api-formats.php config file with a formats array using the encoders class as key and array of associated Mime types as value:

// config/api-formats.php

return [
    'formats' => [
        JsonRequestEncoder::class => ['application/json'],
        XmlRequestEncoder::class => ['(application|text)/xml'],
        YourCustomerEncoder::class => ['you-custom-mime-type']
    ]
];