Fintecc SDK Documentation

(1)

Fintecc

(2)

(3)

1 Sobre 3 2 Contribuindo 5 3 Boas Práticas 7 4 Instalação 9 5 Autenticação 11 6 Serviços/conexões 15 7 Domains 17

(4)

(5)

Este pacote poderoso, porem simples de ser utilizado, irá guiá-lo no desenvolvimento PHP Laravel, seja um projeto simples ou uma aplicação completa e robusta, este SDK irá te prover o necessário para começar seu desenvolvimento e auxilia-lo até o fim.

A tabela de conteúdo abaixo e no menu lateral irá ajuda-lo a ter um fácil acesso a todo conteúdo desta documentação.

Nota: Esse projeto é privado, isso significa que você precisa ser membro do grupo Fintecc e ter acesso aoRepositório para utilizá-lo em seu projeto Laravel.

Caso você encontre algum bug ou desenvolva uma melhoria, envie um issue ou Pull Request diretamente para o projeto noBitbucket.

(6)

Fintecc SDK Documentation, Release latest

(7)

Sobre

Entender um pouco sobre o objetivo desse projeto é essencial para começar a utilizá-lo. Fintecc SDK é um pacote Laravel que visa adicionar as funcionalidades básicas e comuns dos projetos do grupo ao Framework.

Nota: Consulte a documentação dePacotes Laravelpara um maior entendimento

1.1 Introdução

Esse SDK visa facilitar a implementação de projetos Fintecc disponibilizando recursos básicos e comuns as aplica-ções em um único lugar. Com isso é possível usar classes básicas de autenticação ou cadastro, por exemplo, sem a necessidade de escrever toda uma implementação nova para cada empresa/projeto.

1.2 Por que utilizar

Esse projeto pode agilizar, e muito, a implementação de novas features e a manutenção das já existentes. Utilize esse SDK para todos os projetos que precisam utilizar qualquer API da Fintecc, a mesma estrutura de autenticação, conexão com banco de dados ou simplesmente rápida referência para esses propósitos.

(8)

(9)

Contribuindo

Se você está seguindo essa documentações, provavelmente você pertence a uma das empresas do grupo Fintecc. Sendo assim, qualquer contribuição para este projeto será bem vinda.

2.1 Como contribuir

Você pode criar novas funcionalidades, novos componentes, novas classes, refatorar o código ou criar novas imple-mentações, sinta-se livre para ajudar o projeto a crescer.

Caso você tenha acesso ao repositório diretamente, basta criar um novo branch e começar a escrever seus códigos, quando tudo estiver pronto, basta fazer um pull request para a branch master através do bitbucket. Se você não tem acesso direto ao repositório, você criar um fork do projeto e então fazer o pull request.

Escolha a forma que lhe for mais conveniente.

É importante que antes de começar a contribuir você leiaBoas Práticaspara ter certeza que sua contribuição será aceita.

2.2 Fazendo o Pull request

Após efetuar sua alteração (seja ela por branch ou fork) basta ir até o site do bitbucket e criar um novo pull request. Caso não saiba como fazê-lo, ou deseja saber mais sobre este assunto veja a documentação do bitbucket paracriar um pull request

(10)

(11)

Boas Práticas

Leia atentamente cada paragrafo dessa sessão pois é de insuma importância para que você possa contribuir para o projeto. Além de ajudar no entendimento do código.

3.1 Providers e Aliases

Caso você crie um novo provider e/ou alias, eles devem ser registrado no Fintecc\Providers\MainServiceProvider. assim todas as versões do Laravel poderão utilizar o seu provider automaticamente após a instalação do SDK. VideInstalação

<?php

/** @var array PROVIDERS define os providers a serem registrados na aplicação */ const PROVIDERS = [

\Namespace\Para\Seu\Provider::class, ];

/** @var array ALIASES define os aliases a serem registrados na aplicação */ const ALIASES = [

'Alias' => \Namespace\Para\Seu\Alias::class, ];

3.2 Namespace

Caso você crie uma nova empresa/namespace é necessário dizer ao composer como carrega-lo de acordo com a PSR-4, por exemplo:

"autoload": { "psr-4":{

"Fintecc\\" : ["/src/Fintecc"], "NewCompany\\" : ["/src/NewCompany"]

(12)

} },

3.3 Comentários

Todo código no SDK está comentando utilizando os padrões do PHP Documentor. Você pode consultar aPSR do PHP Documentorpara saber exatamente como comentar seu código.

3.4 Nomenclaturas

Os padrões definidos pelo projeto são:

• Nome de variáveis e propriedades de classes devem seguir o padrão camelCase

• Constantes devem ser definidas com todas as letras maiúsculas e palavras devem ser separadas por underscore (CONSTANTE_NOME)

O restante do código DEVE seguir os padrões definidos na PSR-2. Caso você tenha alguma dúvida sobre PSRs ou como estruturar seu código, consulte o guiaPHP Do Jeito Certo.

3.5 TAGs

As tags do projeto devem ser numeradas de uma forma que seja consistente com oVersionamento Semântico

(13)

Instalação

Os passos a seguir mostram a forma básica para instalar e começar a utilizar a Fintecc SDK em seu projeto.

4.1 Composer

Esse SDK deve ser instalado diretamente pelo composer, por se tratar de um repositório VCS privado você deve inserir a referência desse repositório no composer.json do seu projeto:

"repositories": [ { "type": "vcs", "url": "[email protected]:ambientedevfintecc/sdk.fintecc.com.br.git" } ]

E então utilizar o comando composer required fintecc/sdk Ou inserir a dependência diretamente no arquivo composer.json "require": {

"fintecc/sdk": _"1.*" },

Nota: Para instalar o fintecc/sdk a partir de um branch (não uma tag) coloque o prefixo dev- seguido do nome do branch desejado, como dev-bug_fix por exemplo.

Em seguida bastar executar composer update fintecc/sdk E o SDK já estará disponível para utilização

(14)

4.2 Inicialização

A inicialização dos providers e aliases pode variar de acordo com a versão do Laravel, veja como iniciar os providers para cada versão:

4.2.1 Laravel 5.5+

O Laravel vai identificar a referências dos providers automaticamente.

4.2.2 Laravel

5.4-Basta fazer a referência de um único provider no arquivo config/app.php

<?php

'providers' => [

Fintecc\Providers\MainServiceProvider::class ]

4.3 Publicando

Para publicar as configurações do SDK para sua aplicação basta executar php artisan vendor:publish no diretório do projeto, isso fará com que todos os arquivos de configuração, blades, traduções, etc, sejam publicados em seu projeto. Se você precisar atualizar esses arquivos após a instalação (devido a uma atualização do SDK por exemplo) você pode executar php artisan vendor:publish --force para forçar o Laravel a sobrescrever os arquivos.

(15)

Autenticação

Essa sessão mostra como efetuar a autenticação utilizando qualquer API do grupo Fintecc. Isso fará com que o Laravel não execute mais a autenticação pelo Eloquent mas acesse as APIs via curl.

5.1 Iniciando

Primeiramente você precisa dizer ao Laravel para utilizar a autenticação da Fintecc. Para isso, vá em config\auth. phpe em Authentication Guards defina fintecc como o provider a ser utilizado:

<?php 'guards' => [ 'web' => [ 'driver' => 'session', 'provider' => 'fintecc', ], //... ]

E em User Providers (no mesmo arquivo) defina o driver para fintecc_auth e diga o usuário que o driver deve utilizar. Os usuários padrões para cada Empresa já estão disponíveis no SDK.

<?php

'providers' => [

//...

'fintecc' => [

'driver' => 'fintecc_auth',

'model' => <EMPRESA>\Models\User::class, ],

//...

(16)

Com apenas isso a autenticação do Laravel já vai funcionar normalmente utilizando a API da Fintecc.

5.2 Autenticação Customizada

Caso você queira uma autenticação customizada ou está criando uma nova instância da autenticação para o SDK, basta criar uma nova model de usuário que estenda a model padrão da fintecc definindo a forma de conexão.

Por exemplo, digamos que você está criando um novo usuário para uma nova empresa, basta criar uma classe que estenda Fintecc\Models\User

<?php

namespace NewCompany\Models;

use Fintecc\Models\User as FinteccUser;

class User extends FinteccUser {

/** @inheritDoc */

public static function defaultService() {

return \NewCompany\Models\Service::class; }

}

Sua nova classe deve obrigatoriamente definir um método estático com o nome defaultService que ira dizer ao SDK qual service de conexão com a API ele deve utilizar. Para mais informações veja:Serviços/conexões

Nota: Você não precisa criar um service novo, você pode utilizar um já existente caso queira, basta referencia-lo no método defaultService da sua classe.

Caso sua nova classe não siga os padrões de Url e propriedades já definidos, você pode criar suas próprias propriedades e métodos de login. Para tal, basta sobrescrever os métodos estáticos findById e login:

<?php

/**

* @var string $minhaProp minha propriedade customizada * @translate minhaProp

*/

private $myProp; /** @inheritDoc */

public static function findById(string $id) {

$service = static::defaultService();

$response = (new $service)->get('minha/url/get/cliente/'.$id);

$user = Domain::create(static::class, $response, true);

$user->id = $id; return $user; }

/** @inheritDoc */

public static function login(array $credentials) {

(17)

(18)

(19)

Serviços/conexões

Um Service é uma model de conexão com alguma API da Fintecc.

6.1 Utilização

Caso você esteja criando seu próprio service você deve estender o service padrão da Fintecc, e então implementar os métodos estáticos defaultApiName e defaultApiAuth. Esses métodos vão apenas dizer qual API e com qual autenticação sua conexão deve ser feita.

Esses métodos devem retornar uma string que faça referência as configurações que estão em Fintecc\config\fintecc.php

Por exemplo, digamos que você tenha criado as URLs de sua nova conexão da seguinte forma:

<?php "api_url" => [ // NEW COMPANTY "new_company" => [ "local" => "https://local.api.new_company.com.br/", "test" => "https://tst.api.new_company.com.br/", "production" => "https://api.new_company.com.br/", ],

O método defaultApiName da sua classe deve retornar a string new_company.

Uma boa prática para os services (caso você esteja criando uma nova configuração no SDK) é retornar uma constante definida em Fintecc\Interfaces\ServicesInterface:

<?php

namespace Fintecc\Interfaces;

interface ServicesInterface {

(20)

const API_NEW_COMPANY = "new_company";

//...

}

Então sua classe ficaria assim:

<?php

namespace NewCompany\Models;

use Fintecc\Models\Service as FinteccService;

class Service extends FinteccService {

/** @inheritDoc */

public function defaultApiName() {

return static::API_NEW_COMPANY; }

/** @inheritDoc */

public function defaultApiAuth() {

return static::AUTH_API; }

}

Agora você pode utilizar todos os métodos HTTP como GET e POST, por exemplo, que a conexão será feita através dessas configurações

<?php

$service = new NewCompany\Models\Service();

$result = $service->get('/minha/url');

6.2 Alterando API e Autenticação

Você pode alterar a API e a autenticação que seu service usa em tempo de execução com os métodos setApiName e setApiAuth que recebem como parâmetro uma string que faça referência as configurações que estão em Fintecc\config\fintecc.php

<?php

$service = new NewCompany\Models\Service();

$result = $service->get('/minha/url');

$service->setApiAuth(static::AUTH_ADMIN);

$result = $service->get('minha/url/de/admin');

(21)

Domains

Domains são classes semânticas que contem um conjunto de informações que possuem, de alguma forma, valor para o sistema.

Um bom exemplo de domain é a classe de Cliente que possui um conjunto de informações como nome, email e cpf, por exemplo.

A estrutura de um domain consistem simplesmente em propriedades privadas ou protegidas que possuam seus respec-tivos meodos Get e Set, por exemplo:

<?php

class MeuDomain

{ /**

* @var string $id token de sessão do cliente * @translate clienteTokenId

*/

private $id; /**

* @var int $pureId id sequencial do cliente * @translate id

*/

private $pureId; /**

* @var string $status status atual do cliente * @translate statusId

*/

private $status; /**

* @var string $name nome completo do cliente * @translate pessoa->nome

*/

(22)

//... Getters e Setters

}

7.1 Criando um domain

Para criar um domain você pode usar o método create da classe Fintecc\Domains\Domain, que recebe como parâmetro a classe que o deve ser instanciada, as informações a serem inseridas no domain e um boolean que define se as propriedades devem ser traduzidas com o padrão definido em @translate de cada propriedade

<?php

Domain::create(MeuDomain::class, $data, true);

7.2 @translate

Ao colocar a tag @translate no comentário de sua propriedade você está dizendo ao método create como definir essa propriedade quando vinda de alguma lugar que deve ser traduzida.

Por exemplo, digamos que ao fazer um GET de um usuário na API a propriedade name venha como nomeDoUsuario, colocando @translate nomeDoUsuario no comentário da propriedade já faz com ela seja traduzida ao ser criada.

Aviso: A função create assume que suas propriedades estão acessíveis por meio dos métodos Get e Set, caso sua propriedade não possua esses métodos ela será ignorada.

Caso você queira traduzir a propriedade a partir de um array associativo ou de um objeto basta utilizar o operador de objeto ->. Por exemplo, @translate usuario->nome. E isso pode ocorrer de forma recursiva: @translate usuario->dados->detalhes->nome

Caso sua propriedade consiste na concatenação de duas ou mais propriedades do seu array associativo/objeto você pode dizer isso ao create ao inserir o operador de adição + no @translate da sua propriedade. Por exemplo:

<?php

{ /**

* @var string $phone numero de telefone do cliente * @translate telefone->ddd + telefone->numero */

private $phone;

}

O exemplo acima vai inserir o que estiver dentro de: {

"telefone" : { "ddd" : 11, "numero" : 123456789

(23)

Isso não se limita as propriedades dentro de uma mesma key você pode fazer algo como:

<?php

{ /**

* @var string $phone numero de telefone do cliente

* @translate paises->codigos->brasil + cidades->saoPaulo->ddd + telefone->numero */

private $phone;

}

Se seu array/objeto for: { "paises" : { "codigos" : { "brasil" : "+55" } }, "cidades" : { "saoPaulo" : { "ddd" : 11 } }, "telefone" : { "numero" : 123456789 } }

Então o valor de sua propriedade após criada será +5511123456789

7.3 @translate para Array

O caminho inverso para o @translate é feito pelo método toArray da classe Fintecc\Domains\Domain. Esse método faz com que a classe seja convertida para um array associativo traduzindo suas propriedades conforme descrito na documentação @translate.

Por exemplo, se sua classe for algo como:

<?php

{ /**

* @var string $id token de sessão do cliente * @translate clienteTokenId

*/

(24)

/**

* @var int $pureId id sequencial do cliente * @translate id

*/

private $pureId; /**

* @var string $status status atual do cliente * @translate statusId

*/

private $status; /**

* @var string $name nome completo do cliente * @translate pessoa->nome

*/

private $name; /**

private $phone;

}

E você invocar o método toArray passando o segundo parâmetro como true (para que a tradução seja feita):

<?php

$meuObjeto = new MeuDomain();

$array = Domain::toArray($meuObjeto, true); A variável $array será algo como:

{ "clienteTokenId" : "", "id" : "", "statusId" : "", "pessoa" : { "nome" : "" }, "telefone" : { "ddd" : "", "numero" : "" } }

Nota: como já abordado na sessão anterior sobre o método create o método toArray também assume que suas propriedades são acessíveis a partir de métodos Get e Set e caso a propriedade não possua esses métodos ela será ignorada.

(25)

Por exemplo, digamos que seu translate seja @translate telefone->ddd + telefone->numero o mé-todo get dessa propriedade será chamado duas vezes, uma vez passando como parâmetro o inteiro 0 e uma segunda vez passando como parâmetro o inteiro 1 que representam telefone->ddd e telefone->numero respectivamente.

<?php

{ /**

private $phone; /**

* Get $phone telefone do cliente *

* @param mixed $splitIndex caso exista será utilizado para retornar o valor ˓→parcial da propriedade

* @return string */

public function getPhone($splitIndex = null) {

if (is_int($splitIndex)) { switch ($splitIndex) {

case 0:

return substr($this->phone, 0, 2); break;

case 1:

return substr($this->phone, 2); break;

} }

return $this->phone; }

/**

* Set $phone telefone do cliente *

* @param string */

public function setPhone(string $phone) {

$this->phone = $phone; }

}

Nota: O código acima é apenas para ser tomado como exemplo, uma boa prática seria criar um novo método que devesse ser chamado caso o parâmetro $splitIndex não seja vazio/nulo.