PHPackages uspdev/forms - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Validation & Sanitization](/categories/validation) 4. / 5. uspdev/forms ActiveLibrary[Validation & Sanitization](/categories/validation) uspdev/forms ============ Formulários dinâmicos com persistência 0.8.4(2w ago)01425[3 issues](https://github.com/uspdev/forms/issues)1GPL-2.0-or-laterPHPPHP ^8.2 Since Oct 21Pushed 2w ago10 watchersCompare [ Source](https://github.com/uspdev/forms)[ Packagist](https://packagist.org/packages/uspdev/forms)[ RSS](/packages/uspdev-forms/feed)WikiDiscussions main Synced today READMEChangelog (10)Dependencies (12)Versions (26)Used By (1) Forms ===== [](#forms) 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 --------------- [](#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 ---------- [](#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 ``` 2. **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 ------------ [](#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 --------------- [](#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 ``` Sincronização de formulários ---------------------------- [](#sincronização-de-formulários) Sincroniza definições de formulários em `.json` para a tabela `form_definitions` de forma idempotente (create ou update). ``` php artisan forms:sync ``` Por padrão, o comando lê os arquivos do diretório configurado em `uspdev-forms.forms_storage_dir`. Opcionalmente, você pode informar outro diretório: ``` php artisan forms:sync --path=storage/app/formsJson ``` Uso --- [](#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**. 6. Em todos os campos pode ser definido a diretiva **validation\_rule** com a validação dos campos Laravel conforme a documentação. OBS.: **Campos são validados pelo tipo definido em type.** Por exemplo, campos do tipo "number" serão validados pela validação do Laravel "numeric". - **texto de 1 linha** ``` [ { "name": "name", "type": "text", "label": "Nome (text)", "required": true, "validation_rule": "max:150" }, ] ``` - **dois campos na mesma linha** ``` [ { "name": "name", "type": "text", "label": "Nome (text)", "required": true }, { "name": "email", "type": "email", "label": "Email (email)", "required": false, "validation_rule":"max:150" } ], ``` - select simples ``` [ { "name": "rating", "type": "select", "label": "Avaliação (select)", "options": [ "1", "2", "3", "4", "5" ], "validation_rule":"exists:ranking,id" }, ] ``` - 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); ``` 2. **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 // .... ``` 3. **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); // .... } ``` **OBS.: caso exista no $request a chave id ($request->id) o formulário anteriormente submetido com este id será atualizado.****Caso existam erros de validação, o método retorna um array com as seguintes informações: \[$validated\['status'=>'error','errors'=>\[dados do erro\],'data'=>\[dados preenchidos no formulário\]\],String HTMLFormulário preenchido\]** Exemplo de tratamento de erros: ``` $message = [ 'max'=>'O campo :attribute pode ter no máximo :max caracteres', 'required_if'=>'O campo :attribute precisa ser informado.', 'data_saida.after_or_equal'=>'O campo data saída deve ter um valor posterior à data de hoje', 'data_retorno.after_or_equal'=>'O campo data retorno deve ter um valor posterior à data informada na data de saída', 'date_format'=>'O formato de data deve ser HH:MM' ]; $form = (new Form(['editable'=>true]))->handleSubmission($request); if (is_array($form)) { $erros = ''; foreach($form['validated']['errors']->getMessages() as $field=>$value) // Instância de MessageBag (Laravel) { foreach($value as $e) { $nomE = explode('.',$e); if (!empty($message[$field.".".$nomE[1]])) $erros.="".$message[$field.".".$nomE[1]].""; else $erros.="".str_replace(":attribute",$field,$message[$nomE[1]]).""; } } $erros.=''; session(['alert_danger'=>$erros]); //precisa mostrar os erros na view no caso dessa varíavel existir return view('view-aplicacao.create',['html'=>$form['formHtml']]); //formulário preenchido } ``` 4. **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'); ``` 5. **Obter submissão**Recupere uma submissão específica pelo seu id: ``` $formSubmission = $form->getSubmission($formSubmissionId); ``` 6. **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 ------ [](#campos) ### Tipos [](#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); - pode passar `"maxlength": 100` para limitar a quantidade de caracteres; - number: campo numérico; - pode passar `"min"`, `"max"` e `"step"` para definir limites e incremento; - email: valida campos email; - select: precisa passar `options`; - textarea: parágrafos; - file: pode passar `"accept" : ".pdf, image/*"`; ### Atributos adicionais por campo [](#atributos-adicionais-por-campo) #### width para todos os campos [](#width-para-todos-os-campos) O atributo `width` define a largura do campo no grid do Bootstrap (`col-1` até `col-12`). ``` { "type": "text", "name": "nome", "width": 6 } ``` HTML gerado: ``` ``` Contribuindo ------------ [](#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 [](#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 ### Health Score 48 — FairBetter than 93% of packages Maintenance96 Actively maintained with recent releases Popularity15 Limited adoption so far Community23 Small or concentrated contributor base Maturity52 Maturing project, gaining track record Bus Factor2 2 contributors hold 50%+ of commits How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~25 days Recently: every ~17 days Total 25 Last Release 17d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/8a59480189a3ba1aa8355cb434880695569433f5d1c9e375e8238d5ff1a56beb?d=identicon)[uspdev](/maintainers/uspdev) --- Top Contributors [![antonioacampos](https://avatars.githubusercontent.com/u/129632162?v=4)](https://github.com/antonioacampos "antonioacampos (66 commits)")[![masakik](https://avatars.githubusercontent.com/u/986915?v=4)](https://github.com/masakik "masakik (52 commits)")[![ViniReiwz](https://avatars.githubusercontent.com/u/170970877?v=4)](https://github.com/ViniReiwz "ViniReiwz (25 commits)")[![Lucalopezz](https://avatars.githubusercontent.com/u/120069994?v=4)](https://github.com/Lucalopezz "Lucalopezz (17 commits)")[![DudsFerraz](https://avatars.githubusercontent.com/u/151293673?v=4)](https://github.com/DudsFerraz "DudsFerraz (5 commits)")[![pcalvesUSP](https://avatars.githubusercontent.com/u/42939800?v=4)](https://github.com/pcalvesUSP "pcalvesUSP (3 commits)") ### Embed Badge ![Health badge](/badges/uspdev-forms/health.svg) ``` [![Health](https://phpackages.com/badges/uspdev-forms/health.svg)](https://phpackages.com/packages/uspdev-forms) ``` ### Alternatives [illuminate/validation The Illuminate Validation package. 18838.2M1.7k](/packages/illuminate-validation)[fleetbase/core-api Core Framework and Resources for Fleetbase API 1235.9k20](/packages/fleetbase-core-api) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)