opaweb / juno-laravel
Integração Juno para Laravel
Requires
- php: ^7.4
- ext-json: *
- guzzlehttp/guzzle: 6.5.5
Requires (Dev)
- orchestra/testbench: ^6.2
- phpunit/phpunit: ^9.4
This package is auto-updated.
Last update: 2024-09-23 21:20:15 UTC
README
Forked from jetimob/juno-sdk-php-laravel.
DONE:
- Credit card tokenization (must use JS tokenization from Juno).
TODO:
- UI for credit card;
- Local JS interface for Juno JS tokenization.
Make sure to add JUNO_PRIVATE_TOKEN
, JUNO_CLIENT_ID
and JUNO_CLIENT_SECRET
to your .env
file to identify your account in every request.
JUNO_PRIVATE_TOKEN
is also referred asX-Resource-Token
in the docs.
Installing
Using Composer:
$ composer require opaweb/juno-laravel
Publishing configurations
The command below will publish the configuration file to Laravel's config folder.
$ php artisan juno:install
Config file
private_token
: sets the X-Resource-Token of the authorization endpointclientId
: in conjunction ofsecret
they make the authorization header - base64(clientId
:secret
)secret
: in conjunction ofclientId
they make the authorization header - base64(clientId
:secret
)guzzle
: sets the configurations of Guzzlebase_uri
: base uri to make the requests to the resource server (info)sandbox
production
authorization_base_uri
: base uri to make the requests to the authorization server (info)sandbox
production
connect_timeout
: number of seconds to wait while trying to connect to a server. 0 waits indefinitelytimeout
: time needed to throw a timeout exception after a request is made. 0 waits indefinitelydebug
: outputs Guzzle's debug messages to stdout
version
: Juno's API versionenvironment
: sets the current environment to build the request's URL. production | sandboxlogging
: enables the logging to Laravel's Log facaderequest_max_attempts
: Juno's API is currently unstable and being so, is common that we need to perform a request more than one time until the request succeeds. Choose a value that you think that is acceptable. If the request fails even after the N times set, an exception will be thrownrequest_attempt_delay
: Time in ms to wait before trying to execute a new request attemptrecoverable_status_codes
: Array of status codes that are considered recoverable. Only the ones specified in this array will trigger a reattempt in case of a failed request.
Usage
Import the API namespace and use it with:
use Juno; $response = Juno::request($requestObject, $resourceToken);
Where $requestObject
MUST be an instance of the Request class.
Every class inside the
Jetimob\Juno\Lib\Http
namespace implements Request.
$response will always return an instance ofResponse
.
$resourceToken
is required to make sure that the request is being made to the right endpoint with the right credentials.
Simple requests as DocumentListRequest
can be made passing the class the request
function:
Juno::request(DocumentListRequest::class, $resourceToken);
Complex objects MUST be manually configured, as:
$billing = new Billing(); $billing->name = 'NAME'; $billing->document = 'document'; $billing->phone = 'phone'; $billing->email = 'email@xxxxxxx.com'; $billing->notify = true; $charge = new Charge(); $charge->description = 'description'; $charge->amount = 99999.99; $charge->dueDate = Juno::formatDate(2020, 2, 25); $charge->maxOverdueDays = 99; $charge->fine = 9.9; $charge->interest = 9.9; /** @var ChargeCreationResponse $response */ $response = Juno::request(new ChargeCreationRequest($charge, $billing), $resourceToken);
Response
Every request made with the API will return an instance of the Response
object.
All objects that implement Request
have they own Response
object. i.e.: ChargeConsultRequest
has its ChargeConsultResponse
.
If an error occurs during the request (a non 200 code), the returned object will be an instance of ErrorResponse
.
Errors
When a request is made, several problems can arise, so to prevent this from happening, wrap the request
call with a try
/catch
block.
Every Juno exception is a child of JunoException
so all exceptions that can arise during a request can be handled within a single try
block.
try { Juno::request(DocumentListRequest::class, $resourceToken); } catch (JunoAccessTokenRejection $e) { [...] } catch (JunoException $e) { [...] } catch (Exception $e) { [...] }
Access Token caching
The authorization token (access token) is cached to Laravel's default Cache
facade, make sure to have it correctly configured.
If you change the environment from
production
tosandbox
or vice-versa, you MUST clear the cache with:php artisan juno:clear-cache
. Otherwise, the cached access token will be used and you'll receive a 401 error.
Creating a custom request
If you need to make a custom request to Juno's API, you'll need to create two classes, the Request
and the Response
.
Let's imagine that we need to make a request to docs
endpoint.
We'll need to create DocsCustomRequest
and DocsCustomResponse
as exemplified:
DocsCustomRequest.php
use Jetimob\Juno\Lib\Http\Method; use Jetimob\Juno\Lib\Http\Request; use Jetimob\Juno\Lib\Http\BodyType; class DocsCustomRequest extends Request { /** @var string $id pathParam */ public string $id; public string $param1; public string $param2; /** * @var string $responseClass overrides the response serialization class. * * Every successful request will have its response cast to an instance of the class defined by * this property. * * If the response class has the same name with 'Request' exchanged with 'Response', you can leave * don't need to set this property. */ protected string $responseClass = DocsCustomResponse::class; /** * @var string $bodyType overrides the request body type * @see http://docs.guzzlephp.org/en/stable/request-options.html */ protected string $bodyType = BodyType::JSON; /** @var string[] $bodySchema specifies which properties of the current instance should be sent with the body */ protected array $bodySchema = [ 'param1', 'param2', ] /** * Specifies the request method */ protected function method(): string { return Method::GET; } /** * Specifies the endpoint to be merged with base_uri defined in the configuration file. * Anything inside brackets {} will trigger the request to update the matched identifier with this * instance's property with the same name. e.g.: the {id} below will be exchanged to the value of * $this->id; */ protected function urn(): string { return 'docs/{id}'; } }
OddResponseObject.php
use Jetimob\Juno\Lib\Traits\Serializable; class OddResponseObject { use Serializable; public string $property1; public int $property2; }
DocsCustomResponse.php
use Jetimob\Juno\Lib\Http\Response; /** * All properties defined in this class MUST match the object keys defined in Juno's API response. * * Complex objects can be typed so that the SDK can cast an instance and define this instance property * ($param in the class example below) * * If there is data inside an '_embedded' key, you MUST override the initComplexObjects function and * use the helper functions of Response class. * * @see https://dev.juno.com.br/api/v2 */ class DocsCustomResponse extends Response { protected string $id; protected int $value; protected OddResponseObject $param; /** @var OddResponseObject $embeddedData */ protected array $embeddedData; /** * This function is mainly used to deserialize embedded data. * * The first parameter given to deserializeEmbeddedArray specifies in which key, inside the * _embedded object, is the data that we are trying to deserialize. */ public function initComplexObjects(): void { $this->embeddedData = $this->deserializeEmbeddedArray( 'propertyInsideEmbedded', // key name inside _embedded OddResponseObject::class, // deserialize each element to the given class [], // default value if the key is non existent ); } [... getters] }
usage:
$requestData = new DocsCustomRequest(); $requestData->id = 'XXXXXXXXXXXXXXXXXXXXXXXXX'; $requestData->param1 = 'XXXXXXXXXXXXXXXXXXXXXXXXX'; $requestData->param2 = 'XXXXXXXXXXXXXXXXXXXXXXXXX'; // error handling ignored for example readability /** @var DocsCustomResponse $response */ $response = Juno::request($requestData, $resourceToken); // all properties are initialized and can be easily accessed: $response->getParam()->property1;
For more information about Juno's API, see the docs here and here (detailed PDF).