Write Your Own

Extend Peso in case you need more from it.

Integration

Writing your own integration is easy:

• Depend on peso/core

• Follow the Advanced Usage instruction

Service

To write your own service implementation you need to extend the Service interface:

<?php

declare(strict_types=1);

namespace Peso\Core\Services;

use Peso\Core\Exceptions\RuntimeException;
use Peso\Core\Requests\CurrentConversionRequest;
use Peso\Core\Requests\CurrentExchangeRateRequest;
use Peso\Core\Requests\HistoricalConversionRequest;
use Peso\Core\Requests\HistoricalExchangeRateRequest;
use Peso\Core\Responses\ConversionResponse;
use Peso\Core\Responses\ErrorResponse;
use Peso\Core\Responses\ExchangeRateResponse;

interface PesoServiceInterface
{
    /**
     * @template T of object
     * @param T $request
     * @return (
     *      T is CurrentExchangeRateRequest ? ExchangeRateResponse|ErrorResponse : (
     *      T is HistoricalExchangeRateRequest ? ExchangeRateResponse|ErrorResponse : (
     *      T is CurrentConversionRequest ? ConversionResponse|ErrorResponse : (
     *      T is HistoricalConversionRequest ? ConversionResponse|ErrorResponse : (
     *      ErrorResponse
     * )))))
     * @throws RuntimeException
     */
    public function send(object $request): ExchangeRateResponse|ConversionResponse|ErrorResponse;

    /**
     */
    public function supports(object $request): bool;
}

supports() Method

The supports() method is used for a fast check if the service can handle a request.

• If supports($request) returns false, send($request) MUST return ErrorResponse.

• supports() SHOULD NOT do any external requests, it SHOULD be as simple and fast as possible.

• The user is not obliged to call supports($request) before send($request), so send($request) MUST NOT crash just because it was fed an unsupported request.

send() Method

The send() method executes a request.

• If the request object is not supported, the service MUST return the ErrorResponse.

• The service MUST return a response object that corresponds to the request according to the model.

• The service MAY add custom request objects but not custom response objects.

• You do not need to declare responses in the response type hint that you don’t plan to return, therefore only the ErrorResponse is required. See PHP manual for Covariance and Union Types in PHP.

• If the request can’t be handled for expected and valid reasons, the method MUST return an instance of ErrorResponse that wraps an instance of Peso\Core\Exceptions\PesoResponseException. (MUST NOT throw!) For example, if the currency pair or the request type itself is unsupported.

• If the request can’t be handled for some unexpected reason, like network failure or unexpected response from a server, the method MUST throw either an instance of Peso\Core\Exceptions\RuntimeException or an instance of \Error.