Melhores práticas do Symfony (recomendação oficial)

Há alguns dias, Fabien Potencier via Sensio, lançou um e-book reunindo as melhores práticas e recomendações para o desenvolvimento de um projeto Symfony. Compilado a partir de recomendações postadas pela comunidade, o objetivo deste documento é fornecer um conjunto de conselhos relacionados a philoSophia do Symfony. Vou tentar resumir brevemente as 31 dicas descritas em inglês neste post.

Introdução

Este documento começa com alguns conselhos e algumas frases destinadas a nos inspirar com o documento.

"Este documento não é um tutorial"

Este documento foi escrito com a intenção de ser lido por todos os desenvolvedores do Symfony. Tanto especialistas quanto neófitos.

"Não refatore seus aplicativos"

Desde o início do documento, é especificamente explicado que após esta leitura, não devemos atualizar e refatorar nossos aplicativos para que se encaixem perfeitamente nas múltiplas recomendações da Sensio. Podemos, portanto, fazer imediatamente a ligação com as primeiras ideias desenvolvidas no documento: estas boas práticas devem permitir-nos simplificar as nossas vidas, bem como simplificar a revisão de código. Para apoiar minhas observações, três razões são avançadas:

• Seus aplicativos existentes não estão errados, eles apenas seguem outro conjunto de diretrizes;
• Uma refatoração completa da base de código é propensa a introduzir erros em seus aplicativos;
• A quantidade de trabalho gasto nisso poderia ser melhor dedicada a melhorar seus testes ou adicionar recursos que fornecem valor real aos usuários finais.

Crie um projeto

No capítulo 2, que trata de como declarar e criar um projeto Symfony, uma primeira “melhor prática” é fornecida:

_Sempre use o Composer. _Composer introduziu os fundamentos do PHP moderno por meio de sua resolução de dependência. Graças a ele, as dependências cadastradas no arquivo composer.json será resolvido e repatriado em seu projeto para que seja utilizável. Além disso, atualizações fáceis podem ser feitas.

Desta forma, você pode respeitar a organização estrutural de um projeto Symfony. (consulte a página 8).

EXEMPLOS:

• aplicativo/cache armazenará o cache;
• aplicativo/registros registros de armazenamento;
• aplicativo/recursos armazenará os modelos, bem como as traduções globais para seu aplicativo;
• src / armazene seus pacotes de aplicativos;
• vendedor / armazene as dependências do seu projeto;
• rede/ armazenará os recursos (css, js, imagens, etc.) bem como o arquivo frontal (app.php), permitindo que você redirecione posteriormente suas solicitações para seus controladores.
  Como resultado, uma nova recomendação sobre pacotes. Sem fazer minha própria análise que poderia questionar o philosophie do Symfony (que eu não quero), aqui vai a recomendação:

Crie um único pacote AppBundle para um aplicativo. Isso se deve ao modo como o Symfony foi projetado. Cada bundle deve ser _stand-alone. _Eles devem, portanto, ser capazes de viver de forma autônoma e independente.

Deixo-vos a meditar nesta recomendação…

Configuração

O terceiro capítulo nos dá conselhos para configurar sua aplicação. Alguns itens de configuração podem variar de um sistema de desenvolvimento para um sistema de produção.

Como a recomendação indica, você deve, portanto, defina a configuração relativa à sua infraestrutura no arquivo app/config/parameters.yml.

Por outro lado, a configuração específica do seu projeto, que será estática, será declarada em app / config / config.yml.

Além disso, o arquivo parâmetros.yml não deve ser versionado. este é o arquivo parâmetros.yml.dist quem deveria ser. É este arquivo que lhe dará opções básicas para configurar seu aplicativo. (recomendação página 12).

Como resultado, o arquivo _app / config / config.yml _em si serve como uma recomendação.

Defina a configuração relacionada ao seu aplicativo em app/config/config.yml
Seguindo esta recomendação, no entanto, é aconselhável gerar um arquivo configuração.yml, config_dev.yml e um arquivo config_prod.yml. Esses arquivos destinam-se a armazenar as constantes específicas do ambiente de desenvolvimento e do ambiente de produção.
Devemos considerar um valor como constante quando seu valor muda muito pouco.

Injeção de dependência

Aqui estamos ! No terceiro capítulo, é detalhada uma recomendação sobre o uso de dependências. Aconselho-o a ler esta recomendação se a minha explicação lhe parecer vaga.

Esta recomendação é sobre injetar serviços em serviços. Sensio recomenda declará-los em um arquivo src/AppBundle/Resources/config/services.yml.

Também convido você a ler meu artigo sobre injeção de dependência e como limitar o uso do contêiner de super serviço.

Declarar lógica interna

O Capítulo 4 trata da organização de seu aplicativo. Dependendo de suas necessidades, a organização será diferente. Para funções globais e não comerciais, a Sensio recomenda colocá-las em uma pasta Útil ou simplesmente retire-os do pacote e coloque-os em uma pasta separada. Depois disso, é altamente recomendável que você declare sua classe como um serviço. Uma nova recomendação é dada para nos ajudar a declará-los.

O nome do seu serviço deve ser o mais curto possível, de preferência uma única palavra.

Escolhendo o formato do arquivo

Sendo particularmente apegado ao formato Yaml dentro do Symfony, imagino que este ponto irá gerar discórdia. A Sensio recomenda inflexivelmente o uso do formato Yaml nos aplicativos. Os bundles desenvolvidos são compartilhados entre dois formatos: XML e Yaml.

Sensio decidiu recomendar este último simplesmente porque é mais " user-friendly ". O uso de outro formato não mudaria a maneira como seu aplicativo funciona.

Não defina uma variável para a declaração de seus serviços

Esta é uma prática que você verá muito em certos pacotes e, no entanto, o Sensio avisa. Aqui está o exemplo dado no livro de receitas :

1 2 3 4 5 6 7 8

#app/config/services.yml # serviço definição com namespace de classe como parâmetro parâmetros: slugger.class: AppBundleUtilsSlugger Serviços: lançador no beisebol: classe: “%slugger.class%”

Aqui está o exemplo de um código inútil. Declarar a classe a ser usada para um serviço é um erro, pois essa variável pode ser usada em outro lugar no código. Além disso, e esta é a razão dada pela Sensio, pesa na criação do serviço.

A escolha do ORM

A Sensio recomenda o uso do Doctrine ORM dentro do Symfony. Sendo um usuário do Doctrine, sua integração com o Symfony é muito avançada. Daí resulta uma recomendação que relança a organização lógica dos nossos projetos. A declaração de entidade deve manter a lógica dentro de um pacote. Veja o exemplo na página 18.

Declaração do mapeamento

A declaração do mapeamento do Doctrine deve preferencialmente ser realizada usando as anotações que são recomendadas no âmbito do Doctrine, mas também para outras aplicações.

Use anotações para declarar o mapeamento de entidade.
Um exemplo é dado na página 19.

Instalação de acessórios

A Sensio aconselha, sem avançar, a configurar luminárias. Para os não iniciados, são conjuntos de dados que serão usados ​​por padrão para iniciar o aplicativo antes mesmo de colocá-lo em produção.

Padrões de codificação (final do capítulo 4)

Esta é uma parte que Sensio estranhamente quase eclipsou. Eu digo estranhamente, já que é uma parte importante para mim.

Symfony é codificado respeitando os padrões PSR1 e PSR2. Esses padrões devem ser promovidos dentro da comunidade de desenvolvedores Symfony, mas também com desenvolvedores PHP. O Symfony publicou um artigo para coletar e destacar os " Padrões de Codificação ". O líder da Sensio, Fabien Potencier, também colocou uma ferramenta no GitHub para realizar verificações de conformidade com os padrões.

Controladores

Quando se trata de controladores, o ph do Symfonyilosophie “controladores magros e modelos gordos”. Isso significa que os controladores devem permanecer leves. Cada método (ação) que será acessado via rota representa uma ação. O código para cada um desses métodos deve ser "leve" e chamar e coordenar ações. Esses compartilhamentos devem estar em serviços.

Este modelo apresenta um controlador usando códigos/peças de aplicação.

Um controlador deve seguir algumas regras

• Um controlador deve ter no máximo 5 variáveis.
• Um controlador tem no máximo 10 ações.
• Cada ação deve conter no máximo 20 linhas.
  • Um método pode conter mais de 20 linhas, desde que o código utilizado não possa ser fatorado.
    

    Um controlador deve herdar o controlador de base FrameworkBundle da Sensio e usar anotações para gerenciar rotas, cache e segurança.

    O uso de anotações é recomendado, mas também é válido o uso de XML, YAML ou PHP. O aplicativo deve usar apenas um único formato.

Não use o @Template

Esta é uma recomendação para os menos inesperados e, no entanto, a explicação é particularmente poderosa.

Não use a anotação @Template() para configurar o template usado pelo controller
A explicação é simples, o @Template usa um TemplateListener que é chamado quando o evento kernel.view é lançado.
Durante a produção deste documento, foi realizado um teste. O uso de @Template leva 26ms antes de iniciar a geração enquanto que para esta mesma página que teria sido gerada usando " $this->render(…) », o tempo de espera de 5 milissegundos.

Use a anotação ParamConverter

A utilização desta anotação permite automatizar a hidratação de uma entidade.

Usar o truque do ParamConverter é bom quando é simples e conveniente.

Modelos

O Capítulo 6 detalha a geração do modelo. É sem alarde _o que o documento nos dá na sequência de várias recomendações.

• Use o mecanismo de modelo Twig
  A Sensio recomenda o Twig por vários motivos. Além de ser um motor amplamente utilizado pela comunidade PHP, tanto por desenvolvedores PHP do princípio, apenas por desenvolvedores do Symfony e outros frameworks. A simplicidade é enfatizada e a promoção de seu produto é claramente visível. Finalmente, Sensio garante suporte para Symfony até sua versão 3. Você também pode encontrar as primeiras transições a fazer para preparar seu código para migrar para a versão 3.
• Armazenar modelos de aplicativos em aplicativo/recursos/visualizações.
  Por padrão, os desenvolvedores se acostumaram a armazenar seus modelos na pasta Info de cada pacote. Isso não é ruim, mas Fabien Potencier recomenda armazenar os modelos globais para seu aplicativo na pasta mencionada acima.
• Defina suas extensões do Twig em AppBundle/Twig e configurar os serviços em app/config/services.yml.
  Extensões de galhos sofrem com pouca visibilidade. Essas extensões, embora muito úteis, às vezes são usadas de forma muito sistemática. A Sensio apresenta essa parte que considero essencial, como uma forma de injetar código de negócio em seus templates. Eu recomendo que você leia como declarar uma extensão do Twig.

Formulários

O Capítulo 7 nos dá instruções sobre o uso de formulários.

• Defina seus formulários em classes PHP.
  O Symfony oferece a possibilidade de gerar classes PHP permitindo a geração automatizada de formulários para determinadas entidades. O Formulários como são chamados, oferece integração completa. A modificação de entidades é assistida. Além disso, o uso de Formulários permite deportar o gerenciamento de formulários de modelos.
• Não declare um botão para enviar seu formulário.
  Este é um ponto surpreendente, já que este recurso foi introduzido no Symfony 2.5. No momento em que escrevo estas linhas, o Symfony 2.6 está em processo de aceitação e, portanto, ainda não foi lançado oficialmente. Podemos assim levantar algumas questões sobre a utilidade desta funcionalidade, não deve ser utilizada!Adicionar botões em modelos em vez de formulários, por quê?
  Em sua explicação, a equipe Sensio explica que, embora esse recurso permaneça "amigo do usuário" e que simplifica a implementação de formulários, certas funcionalidades permanecem restritas.
  Exemplo, se você adicionar um botão do tipo enviar com um rótulo "Criar", este formulário não pode ser reutilizado para uma página de edição. Você terá então que declarar seu formulário como um serviço para realizar uma herança, o que não é recomendado um pouco mais abaixo.
• Não use as funções do Twig Formato() e _formacomeçar().
  Foi criada uma parte dedicada à renderização dos templates. Ela nos ensina que o uso das funções do Twig Formato() E _ formulário_start()_ está obsoleto. Mais uma vez, isso é um erro para mim, pois essas funções só foram disponibilizadas recentemente.
  No Symfony, existem várias maneiras de renderizar um formulário. Das diferentes formas de renderizar, a melhor forma é aquela que oferece o máximo de flexibilidade.
  Usar as funções do Twig listadas acima traz poucos benefícios. Sensio fala sobre maior legibilidade ao usar tags HTML nativas. Apesar desse argumento, isso representa um pequeno benefício… Muito pequeno!

Declare seus formulários como serviços

Os formulários são classes PHP, o que significa que podem ser declarados como um serviço. Você poderá ver este método nos pacotes de AmigosDoSymfony. Este método não é recomendado pela Sensio exceto em certos casos que cito abaixo:

• Se você quiser reutilizar formulários existentes. Configurar a herança entre dois formulários permite limitar a reescrita de todos os atributos.
• Se quisermos incorporar coleções de entidades.
  O uso de formulários como serviços no caso de um formulário de adição ou edição não é recomendado porque o uso de um serviço carrega o @recipiente. Além disso, será difícil entender que esse serviço é usado por um controlador.

Anexar (fichário) seus formulários

Recentemente, a Sensio iniciou uma constante migração do código Symfony2 para o futuro código Symfony3. Entre a lista de modificações que podem ser feitas (você pode encontrar todas elas em UPGRADE-3.md), está a nova solução para ligante o pedido enviado por um formulário com o formulário que foi criado. A nova metodologia está detalhada na página 21 do Melhores Práticas.

Voz do trecho apresentado:

1 2 3 4 5 6 7 8 9 10 11 12 13

público função novaAção(Pedir $pedir) { // construa seu formulário $form->handleRequest($request); if ($form->isSubmitted() && $form->isValid()) { $em = $ This->container->get(“doctrine.orm.default_entity_manager”); $em->persist($post); $em->flush(); retorno $ This->redirecionar($ This->generateUrl(“admin_post_show”), ordem("eu ia" => $post->getId())); } }

Internacionalização

O objetivo do módulo de internacionalização é traduzir o conteúdo de um idioma para outro, dependendo da região ou do idioma do usuário. Mais do que dados de recomendações, este capítulo foi escrito mais para mostrar as possibilidades nesta parte que sempre permanece sensível.

No Capítulo 8, os editores detalham como ativar o tradução.

e o formato

O Symfony oferece uma infinidade de formatos de tradução:

• PHP
• Qt
• .po
• .mo
• JSON
• CSV
• INI
• e muitos outros
  

  Use o formato XLIFF para seus arquivos de tradução.
  Esta citação é obviamente uma recomendação da Sensio. Sim mas por quê ? Uma resposta breve e precisa nos é dada.
  Entre todos os formatos suportados, apenas o formato XLIFF e o formato gettext são suportados por ferramentas de tradução profissionais. Como o XLIFF é baseado em XML, ele se beneficia da validação de conteúdo.
  O Symfony 2.6 traz um novo recurso que permite "comentar" (adicionar notas) em seus arquivos XLIFF. Essa é uma grande novidade, pois a geração de arquivos de tradução pode causar problemas para o tradutor entender o significado de uma frase ou o contexto em que ela é utilizada. Resumindo, XLIFF é bom!

Onde armazenar nossos arquivos de tradução?

Esta questão introduz uma Melhor prática. Sensio recomenda armazenar nossos arquivos em app/Recursos/traduções.

Normalmente, costumávamos armazenar nossas traduções em cada um de nossos pacotes. Isso não foi ruim, mas as traduções geralmente são consideradas partes globais de nossos aplicativos, assim como os modelos globais, é por isso que a Sensio recomenda que as armazenemos no app.

Como traduzir nossos aplicativos?

Sempre use chaves para traduzir seu conteúdo.
nesta Melhores, não darei minha opinião, pois tenho poucas oportunidades de traduzir aplicativos. Sensio aconselha que para traduzir uma palavra como "Nome de usuário", você deve usar uma chave como rótulo.nome de usuário.

Um exemplo é dado na página 35.

Segurança

O capítulo 9 do livro trata de uma parte central do Symfony; segurança !

O Symfony foi projetado para configurar e autenticar facilmente os usuários que desejam se conectar aos nossos aplicativos. Esta parte é muito complexa e cheia de detalhes, por isso é um esboço grosseiro. Você pode encontrar mais documentação na página dedicada.

Declare seus firewalls

As opções de configuração devem ser inseridas no arquivo segurança.yml que está em aplicativo/configuração.

A menos que você tenha duas conexões diferentes com seu aplicativo (sistema e usuários), recomendamos usar apenas um firewall de entrada com a opção anônima ativada.
Uau uau uau! Espera, cheguei no Symfony, não entendi nada!

O que é um firewall?

Você pode encontrar um artigo feito no Wanadev, sobre como declarar e configurar a autenticação nativa no Symfony. Neste artigo, é detalhado o que é um firewall.

Um único firewall? Por que um ?

Se você acabou de ler o artigo do link acima, deve ter notado que vários firewalls foram declarados.

No referido artigo, os três nomes foram dev, principal et entrar. Apesar disso, a regra dada é respeitada, apenas um firewall pode ser considerado um gateway.

• dev : este firewall permite que o barra de depuração mostrar.
• principal : este firewall é nosso PONTO DE ENTRADA. Usuários anônimos poderão fazer login como se respeitassem a regra. Todas as rotas que começam com / usarão esta entrada.
• entrar : é um firewall. Esta será nossa porta de entrada em um único caso: se quisermos nos conectar. Isso é essencial para ter acesso a um formulário de login.
  A regra é, portanto, respeitada.

Definir uma codificação

Codificar senhas é uma decisão importante. Existem vários algoritmos, como sha (sha1, sha256, sha512, md5...).

Ao declarar uma codificação (veja como declarar uma codificação), três parâmetros podem ser fornecidos.

• O algoritmo de criptografia (padrão: sha512);
• O número de iterações (por padrão: 5000);
• A codificação é base64 da senha codificada (padrão: true).
  Apesar desses valores padrão, convido você a modificá-los para modificá-los para seus aplicativos. A Sensio também recomenda o uso do algoritmo bcrypt.

  Use a codificação bcrypt para criptografar senhas de usuário.
  Sensio explica como usar bcrypt. Isso inclui um salga valor. Isso limita os ataques e é mais resistente a ataques do tipo força bruta. Você pode encontrar mais detalhes no artigo da Wikipedia acima.

Definir permissões

Durante uma conexão, o Symfony detecta qual firewall deve ser usado. Posteriormente, e antes mesmo de acessar o controlador, é realizada uma verificação de acesso. Eles são definidos no arquivo segurança.yml,

Sensio recomenda:

1. proteger nossos "padrões de URL de ponta", entender nossos padrões globais (exemplo: /admin);
2. Usar anotações @Segurança tanto quanto possível ;
3. Verifique os direitos de um usuário através do serviço segurança.contexto (desde o Symfony 2.6, o serviço evoluiu, veja aqui);
4. Defina os eleitores para gerenciar facilmente a segurança no trânsito;
5. Use o ACL para gerenciar direitos de objetos e usuários.

Use anotações @Security

Sensio recomenda usar a anotação @Security.

1 2 3 4 5 6 7 8 9 10 11 12 13 14

usar SensioPacoteEstruturaExtraBundleConfiguraçãoRota; usar SensioPacoteEstruturaExtraBundleConfiguraçãoSegurança; //… / ** * Exibe um formulário para criar uma nova entidade Post. * @Rota(“/new”, nome=”admin_post_new”) * @Segurança("has_role('ROLE_ADMIN')") */ público função novaAção() { //… }

Use expressões para tornar as restrições mais complexas

A Sensio nos explica que essa anotação também permite gerar condições mais complexas, como a comparação de dois atributos entre dois objetos. Esta anotação pode exigir o uso de ParamConverter.

Você pode encontrar mais informações no documento:

• Gerar Expressões
• Converter atributos em objetos

Segurança de acesso no Twig

Se você quiser comparar o usuário conectado com o usuário de um objeto, você pode acessar no Twig o usuário Em progresso.

1 2 3

{% if app.user… %} ... {% endif %}

Gerencie sua segurança facilmente

Gerenciar a segurança geralmente é uma parte delicada e organizar nosso código é uma parte essencial para proteger com sucesso nosso aplicativo. O uso de Os eleitores é altamente recomendado. Outras maneiras de organizar seu código podem ser consideradas. Por exemplo, podemos transferir uma decisão para um método de nossa entidade.

Você pode ver o exemplo Sensio na página 40.

Esta parte é muito pouco detalhada em comparação com as possibilidades que o Symfony oferece. Aconselho você a ler um pouco mais de documentação sobre esta parte se você se deparar com uma tarefa de segurança.

Ativos da Web

Os ativos nos permitem gerenciar recursos como Javascript, CSS, fontes fos, imagens… para que sejam acessíveis a partir de suas páginas.

Seus ativos devem ser armazenados na pasta web/
Dessa forma, você pode carregar seus recursos em seus modelos como este:

1 2	<link rel="folha de estilos" href=« {{ asset(‘css/bootstrap.min.css’) }}«  /> <escrita src=« {{ asset(‘js/jquery.min.js’) }}« ></escrita>

Mantenha a pasta da web pública e tudo armazenado nela.

Use Assetic

Assetic tem múltiplos interesses, como compilação de arquivos. Por exemplo, arquivos Less, Sass, TypeScript… Por esse motivo, a pasta web não pode conter arquivos como arquivos .menos.

Use o Assetic para compilar, combinar e reduzir seus ativos, a menos que você esteja usando o GruntJS.

Saiba mais sobre Asset

Assetic é uma ferramenta completa, apesar de algumas desvantagens. Você pode encontrar documentação sobre este módulo usando os links abaixo:

• Use Assetic
• Minimize CSS e JS
• Comprimir imagens
• Veja a documentação oficial

Configurar testes

O teste é reconhecido pela maioria dos desenvolvedores como essencial. No entanto, apenas uma minoria os implementa.

Veremos como Sensio nos aconselha a realizar nossos testes.

Executar testes de unidade

Os testes de unidade são usados ​​para realizar testes funcionais que, por sua vez, testarão a lógica do seu aplicativo. O Symfony não determinou nenhuma ferramenta específica para testar seus testes. As ferramentas PhpUnitGenericName et PhpSpecName são citados.

Realizar testes funcionais

Criar bons cenários para seus testes funcionais é essencial, mas os desenvolvedores rapidamente se deparam com problemas para implementá-los.

Defina um teste funcional para testar se sua página foi carregada corretamente.

Tente usar URLs codificados em vez de gerá-los por meio do gerador.

Testar a funcionalidade do JavaScript

Existem muitas ferramentas como Vison (uma biblioteca PHPUnit) e Casper JS.

Gerar conjuntos de dados

Isso geralmente é uma preocupação para os desenvolvedores, gerando conjuntos de dados.

Sensio recomenda o uso de bibliotecas Faker et Alice.

Conclusão

Este artigo foi retirado de Melhores Práticas para Symfony. Apesar de simples, este artigo visa dissecar as 50 páginas de conselhos para orientar os novos desenvolvedores do Symfony.