🌴 Palmtree Form

PHP Form builder with Bootstrap v5 and v4 classes, validation, Google Recaptcha support and other goodies

Requirements

PHP >= 7.1
jQuery (If you want to use Recaptcha and/or AJAX submissions)

Installation

Use composer to add the package to your dependencies:

composer require palmtree/form

Usage Example

Build

use Palmtree\Form\FormBuilder;
use Palmtree\Form\Captcha\GoogleRecaptcha;

$builder = (new FormBuilder('my_form'))
    ->add('name', 'text', ['error_message' => 'Please enter your name'])
    ->add('email_address', 'email')
    ->add('message', 'textarea', [
        'required' => false,
        'label' => 'Enter your message',
    ])
    ->add('recaptcha', 'captcha', [
        'captcha' => new GoogleRecaptcha('<site_key>', '<secret>'),
    ]);

$builder->add('send_message', 'submit');

$form = $builder->getForm();
// Set $form to some variable accessible in a view

Render

<script src="/path/to/palmtree-form.pkgd.min.js"></script> <!-- Optional -->
<div class="container">
    <?= $form->render(); ?>
</div>

Process

$form->handleRequest();

if ($form->isSubmitted() && $form->isValid()) {
    // Send an email/save to database etc
    $name = $form->get('name')->getData();
}

See the examples directory for examples using AJAX, file uploads, collections and more.

Rendering Individual Fields

Use the renderStart, renderEnd, renderField and renderRest methods for more fine-grained control over how fields are rendered, such as using Bootstrap's grid system:

<div class="container">
    <?= $form->renderStart(); ?>
    <div class="row">
        <div class="col-6">
            <?= $form->renderField('first_name'); ?>
        </div>
        <div class="col-6">
            <?= $form->renderField('last_name'); ?>
        </div>
    </div>
    <?= $form->renderEnd(); ?>
</div>

By default, renderEnd will render all remaining unrendered fields before rendering the closing tag. To prevent this, pass false as the first argument:

<?= $form->renderEnd(false); ?>

Collections

The CollectionType can be used to add/remove multiple entries of the same field or set of fields:

use Palmtree\Form\FormBuilder;
$builder = (new FormBuilder('collection_example'))
    ->add('name', 'collection', [
        'entry_type'    => 'text',
        'classes'       => ['names-collection']
    ])
    ->add('submit', 'submit');

<script src="/path/to/palmtree-form.pkgd.js"></script>
<script>
$(function () {
    $('.names-collection').palmtreeFormCollection({
        minEntries: 1,
        maxEntries: 4,
        labels: {
            add: 'Add person',
            remove: 'Remove person'
        }
    });
});
</script>

See the collection example for a more advanced use-case.

Constraints

Constraints allow you to validate a field type. The current built in constraints are:

Constraint	Description
NotBlank	Ensures the field is not empty. Allows values of '0'
Email	Ensures the field is a valid email address
Number	Ensures the field is numeric and optionally between a range
Length	Ensures the field has a minimum and/or maximum length of characters
Matching	Ensures the field matches another fields value. Useful for password confirmations

By default, all required fields have a NotBlank constraint. Email fields have an email constraint and number fields a Number constraint.

Using Constraints

// Add an age field where the value must be between 18 and 80
$builder->add('age', 'number', [
    'constraints' => [
        new Constraint\Number(['min' => 18, 'max' => 80])
    ]
]);

// Add a password and confirm password field with a minimum length of 8 characters
$builder->add('password', 'repeated', [
    'repeatable_type' => 'password',
    'constraints' => [
        new Constraint\Length(['min' => 8])
    ]
]);

You can also implement your own constraints, they just need to implement the ConstraintInterface

File Uploads

UploadedFile Object

When you retrieve a FileType's data from a form, an instance of UploadedFile will be returned. This is a small wrapper object around PHP's native uploaded file array.

File Constraints

The following constraints can be used on the FileType field:

Constraint	Description
Extension	Ensures the file has an allowed extension
MimeType	Ensures the file has an allowed mime type
Size	Ensures the file size is between an allowed range

See the file upload example for usage examples of these constraints

Shorthand Type Values

Shorthand values for built-in types are determined by lower-casing the class name and removing the "Type" suffix. For example:

Class	Shorthand Value
TextType	text
NumberType	number
EmailType	email
CollectionType	collection

Examples

The simplest way to run the examples is run the serve.sh script. This script starts a small PHP Docker container and serves the examples using PHP's built-in web server.

./examples/serve.sh

License

Released under the MIT license

faustfizz / form