uspdev/forms

Formulários dinâmicos com persistência

0.6.3 2025-08-22 19:52 UTC

Requires

• php: ^8.2
• illuminate/support: ^11.0
• spatie/laravel-activitylog: ^4.10
• uspdev/replicado: *

GPL-2.0-or-later

• Masaki Kawabata Neto

README

Forms é uma biblioteca uspdev que permite gerar formulários dinâmicos a partir de definições armazenadas em banco de dados e, opcionalmente, persiste os resultados.

Funcionalidades

• Gera formulários a partir de definições no BD;
• Processa a submissão dos formulários com validação e persistência;
• Mostra o resultado com views padrão;
• Possui crud completo para admin;
• Suporta estilos em Bootstrap 4 e 5;
• Integra com aplicações Laravel 11 em diante.

Instalação

1. Instale a biblioteca via Composer e publique as migrations

composer require uspdev/forms
php artisan vendor:publish --tag=forms-migrations
php artisan migrate

1. Menu na aplicação

No arquivo config/laravel-usp-theme.php, adicione ou reposicione a chave uspdev-forms para mostrar o menu. Ele será visível apenas para administradores.

[
    'key' => 'uspdev-forms',
],

Configuração

Você pode personalizar as configurações do pacote modificando o arquivo config/uspdev-forms.php.

php artisan vendor:publish --tag=forms-config

Formulário demo

Popula o banco com um formulário de demonstração com vários tipos de campos, facilitando testes rápidos.

php artisan forms:demo

Uso

1. Crie uma entrada na tabela form_definitions

2. Nome do formulário: nome único que identifica o formulário

3. Grupo: serve para agrupar vários formulários em implementações mais complexas

4. Descrição: campo livre sem uso específico no sistema

5. Campos: campos do formulário

   OBS.: Os campos USP dependem do replicado.

• texto de 1 linha

[
    {
      "name": "name",
      "type": "text",
      "label": "Nome (text)",
      "required": true
    },
]

• dois campos na mesma linha

  [
    {
      "name": "name",
      "type": "text",
      "label": "Nome (text)",
      "required": true
    },
    {
      "name": "email",
      "type": "email",
      "label": "Email (email)",
      "required": false
    }
  ],

• select simples

[
  {
    "name": "rating",
    "type": "select",
    "label": "Avaliação (select)",
    "options": [
      "1",
      "2",
      "3",
      "4",
      "5"
    ]
  },
]

• textarea

[
  {
    "name": "message",
    "type": "textarea",
    "label": "Mensagem (textarea)"
  },
]

• file (upload de arquivo)

[
  {
    "name": "arquivo",
    "type": "file",
    "label": "Arquivo",
    "accept": ".pdf, image/*"
  },
]

• pessoa-usp

[
  {
    "name": "codpes",
    "type": "pessoa-usp",
    "label": "Pessoa USP",
    "required": true
  },
]

• disciplina-usp

[
  {
    "name": "coddis",
    "type": "disciplina-usp",
    "label": "Disciplina USP",
    "required": true
  },
]

• patrimonio-usp

[
  {
    "name": "numpat",
    "type": "patrimonio-usp",
    "label": "Patrimônio USP",
    "required": true
  },
]

• local-usp

[
  {
    "name": "codlocusp",
    "type": "local-usp",
    "label": "Local USP",
    "required": true
  },
]

• data

[
  {
    "name": "data",
    "type": "date",
    "label": "Campo de data",
    "required": true
  },
]

FormDefinition::create($form);

1. Gere o formulário na sua view:

Use a classe FormGenerator para renderizar o formulário no seu template Blade:

use Uspdev\Forms\Form;

$form = new Form($key = null, ['action' => route('forms.action')]);
$formHtml = $form->generateHtml('demo'); // conforme definido em $form

// ....

1. Trate as submissões do formulário:

No seu controller, trate a submissão do formulário salvando os dados no banco de dados:

public function store(Request $request)
{
  $form = (new Form())->handleSubmission($request);
  
  // ....
}

1. Listar submissões Recupere todas as submissões em geral ou de um formulário específico:

$allSubmissions = $form->listSubmission();

// Ou

$allFormNameSubmissions = $form->listSubmission('form-name');

1. Obter submissão Recupere uma submissão específica pelo seu id:

$formSubmission = $form->getSubmission($formSubmissionId);

1. Download de arquivo Faça o download de um arquivo de uma submissão através do nome do campo:

$formSubmission = $form->downloadSubmissionFile($formSubmission, $fieldName);

OBS.: Os arquivos são armazenados em storage/app/formsubmissions/<ano>/id<00>-<hash>.<ext>. Caso tenha problemas de download verifique se os arquivos estão no local correto.

Campos

Tipos

• pessoa-usp: campo tipo select que faz busca no replicado e retorna uma pessoa. nome do campo recomendado: codpes;
• disciplina-usp: campo tipo select que faz busca no replicado e retorna uma disciplina. nome do campo recomendado: coddis;
• patrimonio-usp: campo tipo select que faz busca no replicado e retorna um bem patrimoniado. nome do campo recomendado: numpat;
• local-usp: campo tipo select que faz busca no replicado e retorna um local da usp já formatado. nome do campo recomendado: codlocusp;
• data: data simples no formato dd/mm/aaaa;
• text: texto simples (linha única);
• email: valida campos email;
• select: precisa passar options;
• textarea: parágrafos;
• file: pode passar "accept" : ".pdf, image/*";

Contribuindo

Contribuições são bem-vindas! Siga estes passos para contribuir:

• Faça um fork do repositório.
• Crie um novo branch (git checkout -b feature/SuaFuncionalidade).
• Faça suas alterações e commit (git commit -m 'Adiciona nova funcionalidade').
• Envie para o branch (git push origin feature/SuaFuncionalidade).
• Crie um novo Pull Request.

Resumo do Conteúdo

• Visão Geral do Pacote: Descreve o que o pacote faz.
• Funcionalidades: Destaca as principais funcionalidades.
• Passos de Instalação: Fornece instruções detalhadas de instalação.
• Detalhes de Configuração: Guia sobre como personalizar as configurações.
• Exemplos de Uso: Mostra como criar um formulário YAML e usá-lo na sua aplicação.
• Guia de Contribuição: Incentiva contribuições com passos claros.
• Informações de Licença: Indica a licença