Symfony Flex

Como criar recipes do Symfony Flex e enviar para o repositório

O Symfony Flex facilita a instalação de dependências na aplicação. Ele faz isso usando uma “receita” ou em inglês recipe que indica quais ações ele deve realizar no projeto. Essa receita fica armazenada dentro dos repositórios do Symfony Flex que pode ser o repositório oficial, da própria comunidade chamado repositório contrib ou repositórios privados.

Antes de iniciar a criação do recipe aconselho realizar a leitura do post Como criar repositórios privados do Symfony Flex, pois alguns conceitos são explicados nele.

Nesse post vamos aprender como criar recipes dos nossos próprios bundles, validar e enviar para o repositório, seja ele o repositório disponível para comunidade (contrib) ou um repositório privado, já que o processo basicamente é o mesmo.

Symfony - Fundamentos
Curso de Symfony - Fundamentos
CONHEÇA O CURSO

Ações possíveis

O Symfony Flex possui um conjunto de ações que podemos inserir na receita para que ele possa executar no projeto onde a dependência foi instalada:

  • bundles configurator – configura entradas no arquivo de bundles da aplicação
  • container configurator – configura entradas no container da aplicação
  • copy-from-package configurator – copia pastas e arquivos do repositório para a aplicação
  • copy-from-recipe configurator – copia pastas e arquivos do recipe para a aplicação
  • env configurator – Adiciona entradas no arquivo de configuração de ambiente .env
  • composer-scripts configurator – registra scripts no arquivo composer.json
  • gitignore configurator – Adiciona entradas no arquivo de configuração .gitignore
  • post-install-output configurator – Permite definir informações que serão exibidas no console ao final do processo de configuração do Flex

Essas ações são definidas dentro de um arquivo JSON que será lido pelo Flex.

Estrutura de pastas de um recipe

A primeira coisa que precisamos nos preocupar quando vamos criar um recipe é a estrutura de pastas. A leitura do recipe pelo Flex depende que ele possua um padrão de pastas envolvendo o nome do fornecedor, bundle e versão mínima. Essas informações são retiradas do packagist.org, veja o exemplo abaixo:

Se formos criar um recipe para o bundle acima precisamos definir a seguinte estrutura de pastas:

elton-fonseca/empty-symfony-bundle/1.0

No caso acima, estamos informando que esse recipe deve ser usado da versão 1.0.0 em diante do nosso bundle.

Criando o primeiro recipe

Vamos agora criar nosso primeiro recipe. Crie a seguinte estrutura de pastas dentro de um local qualquer do seu computador:

Agora precisamos criar um arquivo chamado manifest.json onde devemos colocar todas as ações que o Flex deve fazer.

Vamos testar algumas das ações possíveis quando estamos trabalhando com Flex. No arquivo criado anteriormente insira o seguinte conteúdo:

{
    "env": {
        "TREINAWEB": "cursos"
    },
    "copy-from-package": {
        "Treinaweb.php": "%SRC_DIR%/Treinaweb.php"
    },
    "copy-from-recipe": {
        "config/": "%CONFIG_DIR%/"
    },
    "aliases": ["treinaweb", "treinaweb-recipe"]
}

É importante deixar uma quebra de linha no final do arquivo, caso contrário o validador do Flex da erro na hora de enviar

Primeiro declaramos que o flex deve adicionar uma nova entrada no arquivo .env do projeto com chave TREINAWEB e valor cursos.

"env": {
    "TREINAWEB": "cursos"
},

Em seguida falamos para o flex copiar um arquivo que está dentro do bundle para a pasta SRC do projeto que está instalando a dependência:

"copy-from-package": {
    "Treinaweb.php": "%SRC_DIR%/Treinaweb.php"
},

Na última ação pedimos para ele copiar uma pasta chamada config do recipe para a pasta do projeto:

"copy-from-recipe": {
    "config/": "%CONFIG_DIR%/"
},

Crie dentro da mesma pasta onde está o arquivo manifest.json uma pasta chamada config com um arquivo de exemplo chamado treinaweb.yaml. Dentro do arquivo coloque apenas um comentário:

#arquivo de teste

É importante deixar uma quebra de linha no final do arquivo, caso contrário o validador do Flex da erro na hora de enviar

Conforme vimos anteriormente além das ações mostradas neste exemplo é possível realizar outras. Você pode consultar todas as ações possíveis no repositório oficial da equipe do Symfony.

Clonando o repositório na máquina local

Independente se enviará seu recipe para um repositório privado ou público, a primeira coisa que precisa fazer é clonar o repositório. Vamos usar como exemplo o repositório privado criado no post sobre esse assunto citado no início do artigo:

Para clonar o repositório vamos usar a linha de comandos. Se estiver usando Windows aconselho o Power Shell, se estiver usando Linux ou MacOS pode usar o terminal padrão sem problemas. Execute o comando para clonar:

git clone https://github.com/elton-fonseca/flex-private-repository.git

Entre na pasta flex-private-repository com o comando:

cd flex-private-repository

Agora precisamos criar uma nova branch no repositório que clonamos. Através dessa branch podemos criar um pedido para que nosso recipe seja validado e integrado ao repositório. Execute o comando:

git checkout -b new-recipe
Symfony - Gerenciando aplicações com Symfony Flex
Curso de Symfony - Gerenciando aplicações com Symfony Flex
CONHEÇA O CURSO

Enviando o recipe para o repositório

Agora dentro da pasta onde clonou o repositório faça a cópia da pasta do recipe que criamos, representada pelo nome do fornecedor do pacote.

Precisamos enviar essas alterações para o servidor do Github. Execute os comandos:

git add .

git commit -m "adicionar um novo recipe"

git push origin new-recipe

Precisamos dizer ao Github que desejamos que as alterações realizadas no branch novo sejam adicionadas ao branch principal. Ao acessar o repositório no Github automaticamente ele te dirá que enviou um branch se deseja unir a outro:

No nosso caso precisamos unir o novo branch ao master, clique no botão conforme abaixo para realizar esse pedido:

Uma vez que envia o pedido automaticamente, o robô do Symfony Flex faz a validação do conteúdo do seu recipe. Se tudo for aprovado basta clicar Merge Pull Request:

Ao voltar na página inicial do repositório verá que a pasta do recipe já está no branch master:

Testando o recipe

Acesse uma aplicação gerenciada pelo Symfony Flex com código de projeto inserido no repositório, caso seja um repositório privado, e execute o comando para instalação do nosso bundle:

composer install elton-fonseca/empty-symfony-bundle

Ao instalar o pacote no seu projeto automaticamente serão executadas as ações do recipe:

Ao verificar as diferenças no projeto depois da execução verá que as ações foram executadas corretamente:

  • Copiou o arquivo do recipe para a pasta de configuração
  • Copiou o arquivo do bundle para a pasta SRC
  • Adicionou um novo valor no arquivo de env

Isso indica que nosso recipe foi criado corretamente.

Como criar repositórios privados do Symfony Flex

O Symfony Flex possui 2 repositórios públicos onde ele busca os recipes. O primeiro é o repositório oficial onde ficam as recipes da própria equipe do Symfony. O segundo é o repositório contrib onde o pessoal da comunidade envia as recipes que são usadas para bundles públicos que não são oficiais.

Quando precisamos criar recipes para automatizar tarefas em bundles que serão usados apenas em projetos privados, os dois repositórios anteriores não são aplicáveis. Nesses casos podemos criar os nossos próprios repositórios privados para armazenar nossas recipes.

Symfony - Gerenciando aplicações com Symfony Flex
Curso de Symfony - Gerenciando aplicações com Symfony Flex
CONHEÇA O CURSO

Como criar o repositório privado

O repositório privado do Symfony Flex, na verdade, é um repositório comum Git hospedado no GitHub e integrado ao robô de verificação da equipe do Symfony. O repositório no GitHub pode ser público ou privado, em ambos os casos o recipe será reconhecido, porém já que estamos criando um repositório privado do Flex faz mais sentido o repositório do GitHub também ser privado.

No início de 2019 o GitHub passou a permitir a criação de repositórios privados ilimitados nas contas pessoais gratuitamente, mais informações https://github.blog/2019-01-07-new-year-new-github/

Vamos criar um novo repositório privado no GitHub. Uma vez logado acesse o endereço https://github.com/new e preencha as informações conforme abaixo:

Integrando o repositório do GitHub com o Flex

Agora precisamos indicar ao Symfony Flex que ele deve validar e ler os recipes que colocamos dentro do repositório que acabamos de criar. Isso é feito através de uma integração com o GitHub, acesse o endereço https://github.com/apps/symfony-flex-server/installations/new e selecione a conta que está o repositório que criamos no passo anterior:

Ele vai confirmar sua senha do GitHub e perguntar se você deseja adicionar todos os repositórios da sua conta como repositório do Flex ou apenas 1. Aconselho indicar somente os repositórios que realmente serão usados como repositórios do Symfony Flex:

Depois de clicar em instalar ele apresentará uma tela de congratulations, vamos falar dos passos explicados nessa tela mais adiante.

Desenvolvedor Symfony Full-Stack
Formação: Desenvolvedor Symfony Full-Stack
Nesta formação você aprenderá desenvolver aplicações PHP usando o framework Symfony com desenvoltura. Ao final desta formação, terá condições de trabalhar em grandes aplicações web ou APIs integradas com diversos serviços, tudo isso usando as melhores práticas do mercado.
CONHEÇA A FORMAÇÃO

Como liberar os projetos que podem acessar o repositório

Como nós temos um repositório privado é importante que apenas os projetos autorizados consigam utilizar nossos recipes. Para isso nós geramos um identificador único de cada projeto e configuramos dentro do nosso repositório.

Na aplicação Symfony que utiliza o Flex para gerenciamento, execute o comando abaixo:

composer symfony:generate-id

Esse comando não retorna nenhuma mensagem no console. Ele realiza a criação de um identificador do seu projeto dentro do arquivo composer.json na sessão extra.symfony.id:

"extra": {
    "symfony": {
        "allow-contrib": false,
        "require": "4.3.*",
        "id": "01DFEFJHVTGS3PAR3J1K2HB60T"
    }
}

Agora precisamos configurar esse id no repositório junto com todos outros projetos que terão acesso aos recipes. Esse conteúdo é definido dentro do arquivo config.json na raiz do projeto com o seguinte padrão:

{
  "projects": {
    "id1": "descriçao do projeto 1",
    "id2": "descriçao do projeto 2",
    "id3": "descriçao do projeto 3"
  }
}

Crie o arquivo na raiz do repositório:

Como enviar os recipes

Precisamos enviar os recipes que vamos usar em nossos projetos para o repositório. O processo para criação e envio do recipe é o mesmo usado para o repositório de contrib do Symfony.

Vamos ver como criar um recipe e como enviar para o repositório no próximo post.

O que é o Symfony Flex e como ele funciona

O Symfony é um dos frameworks mais utilizados na linguagem PHP. Ele possui grande importância no ecossistema, pois além da utilização direta do framework, diversas outras ferrramentas e até frameworks utilizam seus componentes como base de desenvolvimento. Mesmo com tanta relevância o Symfony não era tão falado na comunidade brasileira, porém com as novidades apresentadas nos últimos tempos ele voltou a ganhar bastante destaque. Inclusive, prova disso é o evento oficial da Symfony que aconteceu em São Paulo.

Desenvolvedor Symfony Full-Stack
Formação: Desenvolvedor Symfony Full-Stack
Nesta formação você aprenderá desenvolver aplicações PHP usando o framework Symfony com desenvoltura. Ao final desta formação, terá condições de trabalhar em grandes aplicações web ou APIs integradas com diversos serviços, tudo isso usando as melhores práticas do mercado.
CONHEÇA A FORMAÇÃO

Um dos recursos mais interessantes aprensentados pela equipe do Symfony é o Flex. Ele automatiza o processo de configuração das dependências no momento da instalação. Isso possibilita ao desenvolvedor começar o projeto com o mínimo possível de dependencias, algo parecido com um micro framework, e adicionar novas dependencias de forma muito fluida até chegar a uma estrutura parecida com um framework full stack.

O que é Symfony Flex

O Symfony Flex é um plugin para composer. Ele automatiza os principais processos na hora da criação do projeto e instalação das dependências. Pode ser usado a partir da versão 3.4 do Symfony e passou a ser usado por padrão a partir da versão 4. O Flex altera o comportamento padrão de alguns dos comandos do Composer para permitir a automatização das tarefas de gerenciamento do projeto.

Quando realizamos a instalação de um novo pacote do composer, o Symfony Flex verifica dentro de um repositório próprio se existe alguma automatização correspondente a essa dependência, se existir ele executa as ações definidas.

O que são Recipes

Recipe (receita) é o nome dado ao conjunto de arquivos responsável pela automatização do processo de instalação de uma dependência específica. As instruções são definidas dentro de um arquivo chamado manifest.json que fica dentro do repositório do Flex, veja um exemplo abaixo:

{
    "bundles": {
        "Symfony\Bundle\DebugBundle\DebugBundle": ["dev", "test"]
    },
    "copy-from-recipe": {
        "config/": "%CONFIG_DIR%/"
    }
}

O recipe acima está pedindo para adicionar um novo bundle no arquivo de configuração e copiar a pasta config de dentro do repositório do Symfony Flex para o projeto. Esse arquivo faz parte do recipe de debug https://github.com/symfony/recipes/blob/master/symfony/debug-bundle/4.1/manifest.json

Ao executar essas tarefas, o Flex evita que o desenvolvedor necessite executar manualmente, diminuindo a chance de erro e a complexidade de instalação de novos pacotes.

Symfony - Gerenciando aplicações com Symfony Flex
Curso de Symfony - Gerenciando aplicações com Symfony Flex
CONHEÇA O CURSO

Repositório de recipes

O Symfony Flex possui 2 repositórios de recipes. O primeiro é o repositório oficial onde somente projetos da equipe do Symfony são colocados:

O segundo é o repositório contrib onde qualquer pessoa pode submeter um recipe para automatizar as configurações do seu bundle.

Ainda é possível criar repositórios privados onde podemos colocar as recipes do Flex que serão usadas somente dentro dos nossos projetos.

Como o Flex cria a estrutura da aplicação Symfony na instalação

Symfony - Fundamentos
Curso de Symfony - Fundamentos
CONHEÇA O CURSO

Como instalar novas dependências no projeto

Uma vez que temos uma aplicação que utiliza o Flex podemos facilmente instalar novas dependências e se beneficiar das automatizações. O Symfony possui uma página onde podemos consultar todos os recipes tanto oficiais quanto do repositório de contrib https://flex.symfony.com, vamos procurar por twig:

Note que temos vários recipes relacionados ao twig. Vamos instalar o pacote symfony/twig-bundle.

composer require symfony/twig-bundle

Se tudo der certo o resultado final será parecido com esse:

Note que após instalar o pacote do composer no projeto ele executou o recipe. Ao fazer isso o Flex configurou todos os detalhes necessários para o Twig funcionar no seu projeto. Podemos ver isso na prática se olharmos no Git as alterações realizadas:

Apelidos para os pacotes do Flex

Alguns pacotes possuem Aliases (apelidos). Se notar o pacote que instalamos verá que ele possui alguns nomes definidos:

O principal objetivo do alias é facilitar na hora de instalação, podemos fazer simplesmente:

composer require twig

Ou

composer require template

Se estiver dentro de uma aplicação que não utiliza o Flex, o composer não vai encontrar esses pacotes, pois o padrão para identificação de pacotes do composer é nome-vendor/nome-pacote. Usar apelidos só é possível graças ao Symfony Flex e em pacotes que possuem Recipes.

Symfony -  Formulários e Validações
Curso de Symfony - Formulários e Validações
CONHEÇA O CURSO

Prefetch e download simultâneo

Quando usamos o Flex ele adiciona 2 funções muito interessantes ao composer:

  • Prefetch – Ele baixa todos os pacotes necessários antes de iniciar a instalação
  • Download Simultâneo – O composer por padrão baixa uma dependência por vez, com uso do Flex ele passar a realizar o download ao mesmo tempo de vários pacotes, tornando mais rápido o processo.

O interessante é que se instalarmos o Flex globalmente no sistema operacional esses 2 recursos passam a ser usados em qualquer projeto, mesmo que não utilize o Symfony. Para instalar o Flex global basta executar:

composer global require symfony/flex 

Conclusão

O Flex torna o gerenciamento das dependências de uma aplicação muito mais simples, rápido e seguro. Uma vez que remove a necessidade de configuração manual por parte do desenvolvedor. Além disso ele ainda conta com uma série de recursos avançados que facilitam o trabalho diário de manutenção de aplicações Symfony.