oswa/formify-php

A flexible and easy-to-use PHP form builder library

0.0.1 2025-12-21 22:53 UTC

Requires

• php: 8.3.*
• aplus/http: ^4.5
• illuminate/translation: ^12.43
• illuminate/validation: ^12.43

Requires (Dev)

• pestphp/pest: ^2.0

MIT

• Oswa

• form
• validation
• html
• form-builder

README

Una librería flexible y fácil de usar para construir formularios HTML en PHP.

Instalación

Puedes instalar el paquete via Composer:

composer require oswa/formify-php

Uso

Uso Básico

use Oswa\FormifyPhp\FormifyPhp;

// Crear un nuevo formulario
$form = new FormifyPhp('POST', '/submit');

// Agregar campos
$form->addField('text', 'name', [
    'label' => 'Nombre',
    'required' => true,
    'placeholder' => 'Tu nombre',
    'class' => 'form-control'
]);

$form->addField('email', 'email', [
    'label' => 'Email',
    'required' => true
]);

$form->addField('textarea', 'message', [
    'label' => 'Mensaje',
    'rows' => 5
]);

// Agregar botón de submit
$form->submitButton([
    'text' => 'Enviar',
    'class' => 'btn btn-primary'
]);

// O simplemente con string
$form->submitButton('Enviar');

// Renderizar el formulario
echo $form->render();

Personalización Global de Labels

Puedes customizar cómo se renderizan todos los labels del formulario:

$form = new FormifyPhp('POST', '/submit');

// Personalizar el renderizado de labels para todos los campos
$form->setRenderLabel(function ($field) {
    return sprintf(
        '<label for="%s" class="font-bold text-blue-600">%s%s</label>',
        $field['name'],
        $field['label'],
        $field['required'] ? ' *' : ''
    );
});

$form->addField('text', 'name', ['label' => 'Nombre', 'required' => true]);

Personalización por Campo Individual

Cada campo puede tener su propio renderizado completamente personalizado usando customRenderer dentro de las opciones:

$form = new FormifyPhp('POST', '/submit');

// Campo con diseño personalizado (input dentro del label)
$form->addField('email', 'email', [
    'label' => 'Correo Electrónico',
    'placeholder' => '[e-mail]',
    'required' => true,
    'customRenderer' => function ($field) {
        return sprintf(
            '<div class="mb-4">' .
            '<label class="block">' .
            '<span class="text-gray-700">%s</span>' .
            '<input type="%s" name="%s" class="mt-1 block w-full" />' .
            '</label>' .
            '</div>',
            htmlspecialchars($field['options']['label']),
            $field['type'],
            $field['name']
        );
    }
]);

Wrapper Personalizado para Campos

Define cómo se envuelve cada campo globalmente:

$form->setFieldWrapper(function ($field) {
    $html = '<div class="mb-6">' . PHP_EOL;
    $html .= $field['label'];
    $html .= $field['input'];
    
    if ($field['error']) {
        $html .= sprintf('<p class="text-red-500 text-sm mt-1">%s</p>', $field['error']);
    }
    
    $html .= '</div>' . PHP_EOL;
    return $html;
});

Ejemplo con Tailwind CSS

$form = new FormifyPhp('POST', '/submit');

$form->setAttributes(['class' => 'space-y-6']);

$form->setRenderLabel(function ($field) {
    return sprintf(
        '<label for="%s" class="block text-sm font-medium text-gray-700 mb-2">%s%s</label>',
        $field['name'],
        $field['label'],
        $field['required'] ? ' <span class="text-red-500">*</span>' : ''
    );
});

$form->addField('text', 'name', [
    'label' => 'Nombre completo',
    'required' => true,
    'class' => 'mt-1 block w-full rounded-md border-gray-300 shadow-sm focus:border-indigo-500 focus:ring-indigo-500'
]);

// Campo con custom renderer
$form->addField('email', 'email', [
    'label' => 'Email',
    'required' => true,
    'class' => 'mt-1 block w-full rounded-md border-gray-300',
    'customRenderer' => function ($field) {
        return sprintf(
            '<label class="flex items-center gap-2">' .
            '<svg class="w-5 h-5">...</svg>' .
            '%s' .
            '<input type="email" name="%s" class="%s" />' .
            '</label>',
            $field['options']['label'],
            $field['name'],
            $field['options']['class']
        );
    }
]);

// Submit button con custom renderer
$form->submitButton([
    'text' => 'Enviar',
    'class' => 'w-full bg-indigo-600 text-white rounded-lg px-6 py-3',
    'customRenderer' => function ($field) {
        return sprintf(
            '<button type="submit" class="%s hover:bg-indigo-700">' .
            '<span>%s</span>' .
            '</button>',
            $field['options']['class'] ?? '',
            $field['text']
        );
    }
]);

echo $form->render();

Manejo de Errores

$form = new FormifyPhp('POST', '/submit');
$form->addField('email', 'email', ['label' => 'Email']);

// Establecer errores de validación
$form->setErrors([
    'email' => 'El email no es válido'
]);

echo $form->render();

Características

• ✅ Constructor de formularios fluido y encadenable
• ✅ Soporte para todos los tipos de campos HTML5
• ✅ Renderizado personalizable a nivel global y por campo
• ✅ Labels personalizables - puedes poner el input dentro del label o cualquier diseño
• ✅ Wrapper personalizable para controlar cómo se envuelve cada campo
• ✅ customRenderer en options - API limpia y consistente
• ✅ Compatible con Tailwind CSS, Bootstrap y cualquier framework CSS
• ✅ Validación de campos y mensajes de error
• ✅ Clases CSS completamente personalizables
• ✅ Botones de submit con atributos y renderers personalizados

Requisitos

• PHP 8.0 o superior

Testing

Los tests están escritos con Pest:

composer test

O ejecutar Pest directamente:

./vendor/bin/pest

Changelog

Por favor ver CHANGELOG para más información sobre cambios recientes.

Contribuir

Las contribuciones son bienvenidas. Por favor ver CONTRIBUTING para más detalles.

Seguridad

Si descubres algún problema de seguridad, por favor envía un email a [e-mail].

Créditos

• Oswa

Licencia

La licencia MIT (MIT). Por favor ver License File para más información.