Download the PHP package betocampoy/champs-frontend without Composer

betocampoy/champs-frontend

Pacote Composer que centraliza templates Twig compartilhados e o micro-framework JavaScript champs-core-js para uso em projetos Symfony e projetos PHP legados com Twig.

A ideia central é eliminar a necessidade de escrever JavaScript customizado para os comportamentos de interface mais comuns, usando apenas atributos data-champs-* no HTML.

Índice

• O que o pacote entrega
• Requisitos
• Instalação
• Configuração no Symfony
• Configuração no legado
• Publicação dos assets
• Templates Twig disponíveis
  • UI
  • Lista
• Módulos JavaScript
• PHP: AjaxFormResponse
• Solução de problemas
• Licença

O que o pacote entrega

Requisitos

• PHP 8.1+
• twig/twig ^2.12 ou ^3.0
• Bootstrap 5 (peer dependency — o projeto consumidor é responsável por instalar)
• Bootstrap Icons (opcional, mas usado pelos componentes Twig de formulário)

Instalação

Configuração no Symfony

1. Registrar o namespace Twig

Abra config/packages/twig.yaml e adicione:

Após qualquer alteração no twig.yaml, limpe o cache:

2. Publicar os assets para assets/

Isso copia os arquivos para assets/vendor/champs-frontend/.

3. Incluir CSS e JS no template base

4. Criar ou ajustar assets/app.js

5. Usar componentes nos templates

Configuração no legado

Use a classe LegacyBootstrap para montar o renderer Twig. Ela registra automaticamente:

• a pasta de templates do projeto
• o namespace @ChampsFrontend
• a extension com as funções path() e asset()

Bootstrap do renderer

Publicar os assets no legado

Incluir CSS e JS no HTML

Se o projeto tiver um app.js próprio, siga o mesmo padrão do Symfony e importe a partir dele.

Publicação dos assets

O navegador não acessa arquivos dentro de vendor/, então os assets precisam ser copiados.

O destino pode ser qualquer caminho: php vendor/bin/champs-frontend-publish-assets <destino>.

Templates Twig disponíveis

Os templates ficam na vendor/ e são acessados pelo namespace @ChampsFrontend. Você não precisa copiá-los para o seu projeto.

UI

_form.html.twig — macros de formulário

Exemplo — input:

Exemplo — botão AJAX:

_modal.html.twig — modais Bootstrap

Exemplo — modal com formulário:

_card.html.twig — card Bootstrap

_notification_center.html.twig — central de notificações

Lista

Templates para construção de páginas de listagem.

Exemplo — cabeçalho:

Módulos JavaScript

O champs-core-js é um micro-framework JavaScript puro (sem dependências externas) com módulos independentes ativados por atributos data-champs-*.

Para referência completa de todos os atributos disponíveis, consulte assets/champs-core-js/DATA-DICTIONAIRE.md.

Para documentação detalhada de cada módulo, consulte assets/champs-core-js/README.md.

Resumo dos módulos

Exemplos rápidos

Máscara de input:

CEP com autopreenchimento:

Copiar texto:

Consentimento LGPD:

Submissão AJAX (sem Twig):

Fila de submits (bipagem/scanner mais rápido que o round-trip):

Sem data-champs-ajax-queue, um submit disparado enquanto o anterior ainda está em voo é simplesmente descartado. Com a fila ativada, cada submit tira um snapshot dos campos na hora (o usuário já pode digitar/bipar o próximo valor) e processa um item por vez, em ordem. A lib não desenha nenhuma UI — cada tela ouve os 3 eventos e desenha sua própria lista "fila"/"processados":

PHP: AjaxFormResponse

Construtor fluente para montar a resposta JSON das actions do pipeline.

Actions disponíveis

Formato JSON da resposta

Actions terminais

As actions abaixo interrompem a execução do pipeline assim que são processadas:

• validation-error
• redirect
• reload

PHP: Notificações Push (FcmClient)

O pacote fornece o cliente JavaScript (PushManager.js) e o service worker (firebase-messaging-sw.js) para captura e registro de tokens FCM no browser. O envio server-side fica a cargo do projeto consumidor usando symfony/http-client e a FCM HTTP v1 API.

Pré-requisito

Baixe o JSON de credenciais do service account em:

Firebase Console → Configurações do projeto → Contas de serviço → Gerar nova chave privada

Salve o arquivo fora do repositório (ex.: config/firebase/firebase-service-account.json) e adicione-o ao .gitignore.

Implementação recomendada no projeto consumidor (Symfony)

1. Serviço de envio (FcmClient.php):

2. Entidade de persistência (PushSubscription):

3. Endpoint de registro (controller):

4. Envio com ícone e link (exemplo):

5. Command para cron:

Solução de problemas

There are no registered paths for namespace "ChampsFrontend"

O namespace não foi registrado no Twig. Para Symfony, verifique se config/packages/twig.yaml contém o paths correto e rode php bin/console cache:clear.

Templates não encontrados após atualização do pacote

O Twig pode ter em cache uma versão antiga. Limpe o cache:

Assets não atualizados após composer update

Repita o comando de publicação:

O initCore não está inicializando os módulos

Verifique se:

1. O script usa type="module" no HTML
2. O initCore(document) é chamado dentro do evento DOMContentLoaded
3. O caminho para init.js está correto após a publicação dos assets

Módulos JS não reagem a elementos inseridos dinamicamente

O initCore precisa ser chamado novamente passando o container do novo conteúdo:

Observações gerais

• O pacote não impõe template base. Use {% include %} e {% import %} nos layouts já existentes no seu projeto.
• O Twig não exige copiar os templates — eles são lidos diretamente da vendor/ pelo namespace.
• Os assets JS/CSS precisam ser copiados porque o navegador não acessa vendor/.
• Os paths diferem por contexto: Symfony usa assets/vendor/champs-frontend, legado usa public/vendor/champs-frontend.

Licença

MIT — Beto Campoy