Fintecc SDK Documentation

Transcrição

1 Fintecc SDK Documentation Release latest Fintecc fev 21, 2018

2

3 Geral: 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 i

4 ii

5 Aviso: Essa documentação é referente a uma versão instável (dev branch). Procurando pela documentação da versão estável atual? Aqui está. Bem vindo a documentação do Fintecc SDK, um pacote SDK Laravel fechado para as empresas do grupo Fintecc! 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 ao Repositó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 no Bitbucket. Essa documentação está organizada da seguinte forma: Geral: 1

6 2 Geral:

7 CAPÍTULO 1 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 de Pacotes Laravel para 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. 3

8 4 Capítulo 1. Sobre

9 CAPÍTULO 2 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 implementaçõ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ê leia Boas Práticas para 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 para criar um pull request 5

10 6 Capítulo 2. Contribuindo

11 CAPÍTULO 3 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. Vide array PROVIDERS define os providers a serem registrados na aplicação const PROVIDERS = [ \Namespace\Para\Seu\Provider::class, 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"] 7

12 , 3.3 Comentários Todo código no SDK está comentando utilizando os padrões do PHP Documentor. Você pode consultar a PSR do PHP Documentor para 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 guia PHP Do Jeito Certo. 3.5 TAGs As tags do projeto devem ser numeradas de uma forma que seja consistente com o Versionamento Semântico 8 Capítulo 3. Boas Práticas

13 CAPÍTULO 4 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": "git@bitbucket.org: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 para mais informações veja a documentação do composer para repositórios VCS 9

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: Laravel 5.5+ O Laravel vai identificar a referências dos providers automaticamente Laravel 5.4- Basta fazer a referência de um único provider no arquivo config/app.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. 10 Capítulo 4. Instalação

15 CAPÍTULO 5 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. php e em Authentication Guards defina fintecc como o provider a ser utilizado: '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. 'providers' => [ //... 'fintecc' => [ 'driver' => 'fintecc_auth', 'model' => <EMPRESA>\Models\User::class, ], ], //... 11

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 namespace NewCompany\Models; use Fintecc\Models\User as FinteccUser; class User extends 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: string $minhaprop minha propriedade customizada minhaprop private 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 public static function login(array $credentials) 12 Capítulo 5. Autenticação

17 $service = static::defaultservice(); $response = (new $service)->post('/minha/url/de/autenticacao', $credentials); return Domain::create(static::class, $response, true); Para mais informações sobre como criar seus atributos veja Domains Autenticação Customizada 13

18 14 Capítulo 5. Autenticação

19 CAPÍTULO 6 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: "api_url" => [ // NEW COMPANTY "new_company" => [ "local" => " "test" => " "production" => " ], 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: namespace Fintecc\Interfaces; interface string API_NEW_COMPANY nome da api da new_company 15

20 const API_NEW_COMPANY = "new_company"; //... Então sua classe ficaria assim: namespace NewCompany\Models; use Fintecc\Models\Service as FinteccService; class Service extends public function defaultapiname() return 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 $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 $service = new NewCompany\Models\Service(); $result = $service->get('/minha/url'); $service->setapiauth(static::auth_admin); $result = $service->get('minha/url/de/admin'); 16 Capítulo 6. Serviços/conexões

21 CAPÍTULO 7 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, e cpf, por exemplo. A estrutura de um domain consistem simplesmente em propriedades privadas ou protegidas que possuam seus respectivos meodos Get e Set, por exemplo: class MeuDomain string $id token de sessão do cliente clientetokenid private $id; int $pureid id sequencial do cliente id private $pureid; string $status status atual do cliente statusid private $status; string $name nome completo do cliente pessoa->nome private $name; 17

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 de cada propriedade Domain::create(MeuDomain::class, $data, true); Ao colocar a 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, 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 usuario->nome. E isso pode ocorrer de forma 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 + da sua propriedade. Por exemplo: class MeuDomain string $phone numero de telefone do cliente telefone->ddd + telefone->numero private $phone; //... Getters e Setters O exemplo acima vai inserir o que estiver dentro de: "telefone" : "ddd" : 11, "numero" : Capítulo 7. Domains

23 Em uma única propriedade phone do seu Domain, então o valor dessa propriedade após criada será Isso não se limita as propriedades dentro de uma mesma key você pode fazer algo como: class MeuDomain string $phone numero de telefone do cliente paises->codigos->brasil + cidades->saopaulo->ddd + telefone->numero private $phone; //... Getters e Setters Se seu array/objeto for: "paises" : "codigos" : "brasil" : "+55", "cidades" : "saopaulo" : "ddd" : 11, "telefone" : "numero" : Então o valor de sua propriedade após criada será para Array O caminho inverso para é 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 Por exemplo, se sua classe for algo como: class MeuDomain string $id token de sessão do cliente clientetokenid private $id; para Array 19

24 int $pureid id sequencial do cliente id private $pureid; string $status status atual do cliente statusid private $status; string $name nome completo do cliente pessoa->nome private $name; string $phone numero de telefone do cliente telefone->ddd + telefone->numero private $phone; //... Getters e Setters E você invocar o método toarray passando o segundo parâmetro como true (para que a tradução seja feita): $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. 20 Capítulo 7. Domains

25 7.3.1 Propriedades concatenadas para o toarray Caso a propriedade do seu objeto consista de uma concatenação de propriedades (como o telefone no exemplo anterior) o método Get da propriedade deve saber como retornar os valores separadamente recebendo como parâmetro o index de cada propriedade concatenada respectivamente. Por exemplo, digamos que seu 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. class MeuDomain string $phone numero de telefone do cliente telefone->ddd + telefone->numero private $phone; * Get $phone telefone do cliente * mixed $splitindex caso exista será utilizado para retornar o valor parcial da propriedade 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 * 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. para Array 21