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.

Curso Symfony - Fundamentos

Conhecer 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

Curso Symfony - Gerenciando aplicações com Symfony Flex

Conhecer 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.

Formação Desenvolvedor Symfony Full-Stack

Conhecer a formação