Zebra_Form, a jQuery augmented PHP library for creating and validating HTML forms

Get the latest updates on this PHP library via RSS

1. Overview
2. Features
3. Requirements
4. Installation
5. How to use
6. Download
7. Documentation
8. Changelog
9. Comments

Zebra_Form is a PHP library that simplifies the process of creating and validating HTML forms. Its object-oriented structure promotes rapid HTML forms development and encourages developers to write clean and easily maintainable code. It frees the developers from the repetitive task of writing the code for validating forms by offering powerful built-in client-side and server-side validation.

Zebra_Form has an integrated cross-site scripting prevention mechanism that automatically strips out potentially malicious code from the submitted data. It also prevents automated SPAM posts, out of the box and without relying on CAPTCHA by using honey pots.

Forms layout can be generated either automatically or manually – using templates. When generated automatically, the generated output validates as HTML 4.01 Strict, XHTML 1.0 Strict or HTML5, and has the same look & feel across all major browsers like Firefox, Chrome, Opera, Safari and Internet Explorer 6+.

It provides all the controls you’d expect in an HTML form and, additionally, date/time pickers, captcha and AJAX-like file upload controls.

The client-side validation is done using jQuery 1.5.2+

Zebra_Form‘s code is heavily commented and generates no warnings/errors/notices when PHP’s error reporting level is set to E_ALL.

Top

Features review

has an integrated cross-site scripting prevention mechanism that automatically strips out potentially malicious code from the submitted data
it automatically prevents automated SPAM posts using the “honey pot” technique
provides both server-side and client-side validation (client-side validation is done using jQuery 1.5.2+)
forms’ layout can be generated either automatically or manually using templates
generated output validates as HTML 4.01 Strict, XHTML 1.0 Strict or HTML5
works in all major browsers like Firefox, Chrome, Opera, Safari and Internet Explorer 6+
code is heavily commented and generates no warnings/errors/notices when PHP’s error reporting level is set to E_ALL
has comprehensive documentation

Top

Requirements

PHP 4.2.0+ or PHP 5.0.2+ (preferably PHP 5.3.0 compiled with the “fileinfo” extension for more secure file uploads – read more at the change log for version 2.7.3)

jQuery 1.5.2+

Top

Installation

Download the latest version, unpack it, and put it in a place accessible to your scripts.

Top

How to use

Live demos

The HTML

<!-- must be in strict mode! -->
<!DOCTYPE html>

<html>

    <head>

        <title>Zebra_Form Example</title>

        <meta charset="utf-8">

        <!-- load Zebra_Form's stylesheet file -->
        <link rel="stylesheet" href="path/to/zebra_form.css">

        <!-- load jQuery -->
        <script src="path/to/jquery.js"></script>

        <!-- load Zebra_Form's JavaScript file -->
        <script src="path/to/zebra_form.js"></script>

    </head>

    <body>

    <!-- the PHP code below goes here -->

    </body>

</html>

The PHP

<?php

// include the Zebra_Form class
require 'path/to/Zebra_Form.php';

// instantiate a Zebra_Form object
$form = new Zebra_Form('form');

// the label for the "email" field
$form->add('label', 'label_email', 'email', 'Email');

// add the "email" field
// the "&" symbol is there so that $obj will be a reference to the object in PHP 4
// for PHP 5+ there is no need for it
$obj = & $form->add('text', 'email', '', array('autocomplete' => 'off'));

// set rules
$obj->set_rule(array(

    // error messages will be sent to a variable called "error", usable in custom templates
    'required'  =>  array('error', 'Email is required!'),
    'email'     =>  array('error', 'Email address seems to be invalid!'),

));

// "password"
$form->add('label', 'label_password', 'password', 'Password');

$obj = & $form->add('password', 'password', '', array('autocomplete' => 'off'));

$obj->set_rule(array(

    'required'  => array('error', 'Password is required!'),
    'length'    => array(6, 10, 'error', 'The password must have between 6 and 10 characters'),

));

// "remember me"
$form->add('checkbox', 'remember_me', 'yes');

$form->add('label', 'label_remember_me_yes', 'remember_me_yes', 'Remember me');

// "submit"
$form->add('submit', 'btnsubmit', 'Submit');

// validate the form
if ($form->validate()) {

    // do stuff here

}

// auto generate output, labels above form elements
$form->render();

?>

Live demos

Top

Download

version 2.8.2 (zip, 261.9Kb)

If you find this library to be useful to you, you can support the author by donating a small amount via PayPal:

Zebra_Form is distributed under the LGPL.

In plain English, this means that you have the right to view and to modify the source code of this software, but if you modify and distribute it, you are required to license your copy under a LGPL-compatible license, and to make the entire source code of your derivation available to anybody you distribute the software to.

You also have the right to use this software together with software thas has different licensing terms (including, but not limited to, commercial and closed-source software), and distribute the combined software, as long as state that your software contains portions licensed under the LGPL license, and provide information about where the LGPL licensed software can be downloaded.

If you distribute copies of this software you may not change the copyright or license of this software.

You may also like:

Zebra_Database, a MySQL database wrapper written in PHP
Zebra_Image, a lightweight image manipulation library written in PHP
Zebra_Mptt, a PHP implementation of the modified preorder tree traversal algorithm
Zebra_Pagination, a generic pagination class written in PHP
Zebra_Session, a wrapper for PHP's default session handling functions, using MySQL for storage

Top

Documentation

Become a ninja.
Read the comprehensive documentation.

Top

Changelog

Click on a version to expand/collapse information.

version 2.8.2 (May 11, 2012)

the upload rule now has also a client-side validation side, where it checks if the indicated path exists and is writable
fixed a bug for file uploads where, if the name of the uploaded file was too long, the “x” for canceling was not visible anymore
fixed a bug where, after selecting a file, by clicking very close to the file’s name, users could open the file picker again, resulting in bogus visuals
fixed a bug which made the file name not to appear for an upload control having “upload” as the sole attached rule
updated Zebra_DatePicker to version 1.3.2
fixed a bug where setting the first day of week as anything other than Monday was not working; all credit goes to Edward!

version 2.8.1 (April 07, 2012)

elements can now be validated “on-the-fly” where an element is validated as soon as it looses focus; use the newly added “validate_on_the_fly” flag for the “client_side_validation”; thanks to François Rigaudie and Konstantin Stoyanov
all error messages can now be shown on form submit rather than only the first one; use the newly added “validate_all” flag for the “client_side_validation”; thanks to François Rigaudie and Konstantin Stoyanov;
file names can now be prefixed with a given string when uploading files (using the “upload” rule); thanks to Robert Warelis;
the library now triggers an error message if a “date” control doesn’t have the “date” rule set. note that this rule cannot be set automatically since it requires an error message to be set by the developer. thanks to bastian;
the “length” rule, set with the 4th argument to TRUE, will now always show the character counter; previously, the character counter was shown only if the lower limit was 0. thanks to Andy Vogar;
fixed a bug in the JavaScript code regarding the file upload control which was not working with jQuery UI. thanks to edward for fixing it;
fixed a bug where validation would fail if there were two or more file upload controls on a form. thanks to edward for fixing it;
fixed a bug where the class for disabled control was not correctly applied;
updates in documentation
updated Zebra_DatePicker to version 1.3.1

version 2.8 (March 10, 2012)

fixed a bug where the attach_tip() JavaScript method was not working properly; thanks to Andrei Bodeanschi
previously, the placeholders were injected to the bottom of the main document rather than right after the parent element and thus generating issues like placeholder remaining visible when hiding the parent element’s container; now the placeholders are injected in the DOM right next to the parent element;
fixed a bug where because of the fact that JavaScript and PHP treat new lines, accented characters and special characters differently (1 byte in JavaScript and 2 or 3 bytes in PHP), server-side validation of a maximum allowed length would sometimes fail if a textarea’s value would contain new lines, although client-side validation was ok; thanks to Andrei Bodeanski for spotting it;
fixed a bug where setting the “readonly_element” property to FALSE on a date element had no effect; thanks to bastian
fixed a bug where a date element’s “get_date” method was triggering a warning if the the element was not required and no date was selected; thanks to bastian
the “length” rule now accepts a 5th argument instructing the script to show a counter of remaining characters;
added a new method available for text, textarea and password controls, called change_case which can be used to instruct the script to force all letters typed by the user, to either uppercase or lowercase, in real-time;
added documentation on how to access the Zebra_Form object in JavaScript, with examples;
added documentation on how to use AJAX in custom validations (scroll down to the “custom” rule and keep reading);
tweaked the default CSS style of the date control which was a bit too short;
updated Zebra_DatePicker to version 1.2

version 2.7.7 (January 18, 2012)

fixed a bug that made disabling dates impossible; thanks to Andrei Bodeanschi
fixed a bug with the “convert” rule that made it always delete the converted image immediately after conversion, if the “overwrite” argument was set to TRUE
added albanian translation; thanks to Faton Sopa

version 2.7.6b (December 06, 2011)

fixed a bug where placeholders (labels used as “hints” inside text/password/textarea controls) would not follow their parent control upon resizing the browser window;
sometimes error messages get stuck and cannot be closed; although I couldn’t find the root of the problem I’ve done some tweaks and it seems to be working a bit better now (especially error messages related to file upload controls). the whole logic around error messages needs to be rewritten tough, as I realized that there are some faulted approaces there.

version 2.7.6 (December 06, 2011)

fixed a bug that appeared since the last version that made file uploads to never pass validation

version 2.7.5 (November 20, 2011)

fixed a bug where using multiple forms on a single page would disable client-side validation for all forms but the first one; thanks to Pedro Abreu for reporting;
fixed a bug where if there were selection groups in a select, it would never pass validation;
fixed a bug where placeholders (labels as hints inside textboxes and textareas) were not working on textareas; thanks to Chris for reporting it a long time ago and to Andrei Bodeanschi for recently reminding me about it;
elements that have display:none or visibility:hidden are no longer checked in the client-side validation process;
the Zebra_Transform plugin is not included anymore in the library; it can be downloaded and used separately from here if needed; as a result, the form’s fancy_form() method is also gone;
some additions to documentation;

version 2.7.4 (September 27, 2011)

fixed another bug that would make date validation impossible in certain scenarios;
minor updates to the JavaScript code;

version 2.7.3 (September 16, 2011)

fixed a bug where dates having the day < 10 would not pass validation; thanks to Dev for reporting;
fixed a bug where Zebra_TransForm was incorrectly initialized and was transforming controls on the entire page rather than just the current form’s controls
fixed a bug that made impossible to set custom classes for the actual <form> tag, through the form’s constructor method; thanks to Sebi Popa for reporting;
fixed a bug that would cause the script to trigger a warning when a select control would have [] (square brackets) in its name but the multiple attribute was not also set;
fixed an issue that allowed malicious users to submit arbitrary values instead of the ones defined at the form’s creation, for select controls, checkboxes and radio buttons; the severity of the issue was low as the submitted values were still filtered for cross-site scripting (XSS) attempts, so no real harm could be done; thanks for PunKeel for reporting;
previously, the library would rely on information available in the $_FILES super-global for determining an uploaded file’s mime type, which, as it turns out, is determined by the file’s extension, representing a potential security risk; now, for PHP versions 5.3.0+ compiled with the “php_fileinfo” extension, the uploaded file’s mime type is determined using PHP’s finfo_file function; thanks to DaveK for reporting;
now the script throws a JavaScript error if the JavaScript function required by a custom validation doesn’t exists; previously, it would silently ignore the fact;
updated the Zebra_DatePicker to version 1.1.2
updated documentation to reflect the recent changes in the Zebra_Image library

version 2.7.2 (August 29, 2011)

fixed a bug in the date picker’s JavaScript code regarding event delegation that would crash the script in certain scenarios; thanks to Sebi Popa for spotting it!;

version 2.7.1 (July 30, 2011)

fixed a bug where date would never validate for languages other than English; thanks to alfred;
the form now completely adheres to http://www.w3.org/TR/WCAG20-TECHS/H44.html which requires that all controls have an associated label; previously, the honeypot element did not have an associated label. thanks to Alexis;
minor optimizations in the PHP code;
some clarifications in the documentation regarding the “resize” rule;

version 2.7 (July 19, 2011)

added a new validation rule called filetype; with this rule one can restrict the types of files that are upload-able by specifying a list of allowed file extension; it’s important to note that validation is not done by file extension but by the MIME type of the uploaded files; for this, a new file is available in the root of the library called mimes.json containing the currently supported extensions and associated MIME types;
the library now makes use of the Zebra_TransForm jQuery plugin to replace radio buttons, check boxes and select boxes with nicer ones; see the newly added “fancy_form” method for configuration;
due to popular request CAPTCHA images are now easier to read;
if the script was run on a virtual host, it could not correctly determine the path to the “process.php” file (this file is used for validating uploads client-side and for CAPTCHAs);
fixed a bug that would break the file upload control when the form name had dashes in it (i.e. “my-form”); thanks to MarcosBL;
fixed a bug that was introduced in the previous version that made disabling the client-side validation impossible;
fixed a bug that caused the name of the uploaded file to appear in the wrong position;
fixed a bug where the “date” control’s “get_date” method was returning a string enclosed in an array rather just the plain string;
fixed a bug where the “date” control’s “direction” method was not working when using “false” as argument;
some clarification in the documentation regarding the upload rule;
some clarification in the documentation regarding the set_attribute method; thanks to Jack Ryan;
added French language file; thanks to Sébastien GASTARD;
added German language file; thanks to Chris Banford;

version 2.6.1 (July 01, 2011)

fixed a bug where the settings for client-side validation would get reset if a file upload control was added to the form. thanks to kszys for reporting.
fixed a bug where the client-side validation would crash when the format of the date contained day names or month names. thanks to Chris for reporting.
fixed a bug where determining the path where the library is located (for executing the process.php file required for AJAX-like uploads) was not working for certain configurations. thanks to kszys for helping.
fixed a bug that would crash the script if date format would contain “/” (slashes) – thanks to Jack Ryan for reporting
fixed a bug where the length rule was tested even if the element had no value nor was the required rule set. unless the required rule is set, the length rule is not to be tested as long as there is no value entered.
additions to the documentation of radio buttons and checkboxes. thanks to kszys the suggestion.
additions to the documentation of the “upload” rule where it is now stated that after the rule is run, the DOM element the rule is attached to will get an attribute called file_info which will contain information about the uploaded file, usable in the JavaScript part of a custom function.
Spanish language file added – thanks to José Machado for providing it

version 2.6 (June 24, 2011)

fixed a bug that broke the “resize” rule (thanks to jose for reporting)
added an extra example for the “resize” rule on how to create multiple sizes of an uploaded image by using the resize rule.

version 2.5 (June 21, 2011)

fixed a bug where the labels inside controls were not working in Internet Explorer prior to 9
corrected the documentation about how to access the JavaScript object (thanks to Jonathan Kratzke for reporting)

version 2.4 (June 20, 2011)

fixed a bug where the regexp rule was not working if the regular expression contained parentheses (thanks to Sebi Popa and to Dragos Oancea for reporting)

version 2.3 (June 19, 2011)

fixed a few bugs related the “date” control (thanks to Jack Ryan for reporting)
fixed a bug that affected file upload validation

version 2.2 (June 11, 2011)

fixed a bug where, for custom validations, the JavaScript function was not getting any additional arguments except the element’s value (thanks to Robert Grzesinski for reporting)
fixed a bug where the “date” control would add an invalid attribute to the element that would cause the generated output not to pass the W3C validation
fixed a bug where in the newest versions of PHP 5 the script would generate “PHP Strict Standards” notices because of how mktime() (with no arguments) and array_shift() is treated in these versions
some documentation updates and clarifications (thanks to Andrei Bodeianschi for suggesting some of those)

version 2.1 (June 02, 2011)

ported the client-side validation to jQuery
the “date” control has some new methods thanks to the integration with the Zebra_Datepicker jQuery plugin
regardless of the format used for a date, the submitted date can now easily be retrieved in YYYY-MM-DD format for use with a database or with PHP’s strtotime function by using the newly added get_date() method;
Zebra_Form was not working if the jQuery was loaded at the end of the page (thanks to Sebi P for reporting)
fixed a bug with custom validation rules
fixed a bug with “selects” having the “other” option set

version 2.0 (April 10, 2011)

added client-side validation. requires MooTools 1.2.5+
added automatic handling of file uploads. the script can now automatically upload files to a specified folder. it can also automatically check for valid image files, permitted file size and it can also automatically resize uploaded images (requires the Zebra_Image class)
a new method is now available: reset() which clears the values of all the form’s controls
added a new control type: “time”; this outputs a time picker
controls now have rounded corners (in browsers that support CSS3) and have a :hover state
infinite levels of nested option groups can now be created for “select” controls (until now, only one level could be created);
select controls now have a default, language dependent, “- select -” option
select controls can now have a new attribute: “other”. when set, a text box control will be automatically created having the name “[control_name]_other” (where [control_name] is the name of the select box). the text box will be hidden until users select the automatically added “Other…” option from the selectable options.
dropped XTemplate templating engine in favor of pure PHP templating
the generated HTML validates as HTML 4.01 Strict. If you want it to validate as XHTML 1.0 Strict use the newly added doctype() method
access keys can now be set for labels
added a bunch of new validation rules
improved CAPTCHA control
a new “control” is available – you can now add “notes” (information boxes telling the users what they are expected to enter/select in a field) in the same way as adding “labels”
fixed a bug regarding XSS prevention
fixed a bug where the “number” rule would not allow the input of negative numbers
fixed a bug where the “compare” rule would validate when the values was compared to that of a nonexisting control
fixed a bug where option groups couldn’t be created for the “select” control
fixed a bug that appeared since the last release that caused emails to never pass validation
fixed a bug that would not render the captcha image on some systems
many documentation refinements

version 1.2 (September 22, 2008)

a new feature has been added: automatic output generation. if your form does not need any special output format, you can simply call the render() method without specifying a template name to let the script handle it, thus saving you some time as you are not needed to also code the form’s layout.
a new type of controls has been added: “html”. with this you can insert arbitrary HTML code into your forms. This is usefull when you don’t use templates but rather let the script generate your forms and you need to have some extra HTML in your forms (notes, descriptions, etc) – because letting the script to automatically generate your forms means that you don’t have a template to insert your HTML code into
arrays of custom rules can now be set for controls; up until now, only one custom rule per control could be set
generated forms are now (more) W3C compliant
CAPTCHA is now case insensitive
default template is now nicer
better error reporting
fixed a few minor bugs
many documentation refinements

version 1.1.1 (May 08, 2008)

rewritten css for the default template
fixed a bug where submitting array-like controls (multiple checkboxes with sharing the same name or a “select” control with “multiple” set) would crash the script
fixed a bug where submitting text fields with empty spaces would pass the validation for “required” fields
fixed a bug where the captcha image was not updated upon submission
upon submission, all characters were transformed to their applicable html entities, which could cause a lot of headaches if you were submitting text in other language than english

version 1.1 (December 03, 2007)

added *heavy* XSS (cross site scripting) injection prevention (the class used for filtering for XSS injection is the Input class from the CodeIgniter PHP framework
previously some accented characters got scrambled upon submission as htmlentities() was being called without the UTF-8 argument
fixed an error where, when having multiple forms on a page, all forms were processed upon submission

version 1.0 (June 02, 2007)

trying to change the main template of the class had no effects
the class was not working correctly in PHP 4.x.x
fixed an error where using a nonnumeric index for the first element in a “select” control (indicating the “nothing selected” condition of the control) would lead to a crash
added validation rule for a list of comma separated email addresses
many people have asked for it so i’ve added an example on how to use the radio controls, the checkbox controls and on how to do quick custom validations
multiple instances of the form could not be created on the same page
error messages can now be customized from the main template (the one in the /templates folder) – thanks to Claude Quezel for suggesting
custom blocks can now be parsed in the form’s template by using the newly added “parseBlock” method
the “addOptions” method of the “select” control was overwriting any previously set options. now subsequent calls to this method will append options to the existing ones
custom form actions can now be specified – previously, forms were always submitted to themselves
a new property was added: “locked”. by default, when a form is reloaded after a submission, all the controls will have their respective submitted value, while the default value set by user will be ignored. setting this property to TRUE, will make the controls preserve their user-provided default values, ignoring the submitted value
previously, only variables could be passed to the addVar method. now strings and constant can also be passed
multiple options can now be preselected for select controls having the “multiple” attribute set (read the documentation for the constructor of select controls) – this one was actually working just wasn’t documented. thanks to sridhar for reporting
in order to make the generated output valid XHTML 1.0, the label controls no longer have the “name” attribute and the form has now the “action” attribute set; also the “selected” attribute is now correctly set for “select” ontrols (thanks to Claude Quezel)
made some changes in the main template’s CSS file, provided by Claude Quezel, that makes the fieldsets look in the same way in Firefox and Opera as in IE – thanks!
on some PHP installations file upload was not working (enctype and max_file_size were not being set)

version 1.0 BETA 3 (February 17, 2007)

for the “select” control, if options were specified having literal keys and the “required” rule was set, the control would never pass validation (thanks to sridhar for reporting)
a major security issue was fixed where an attacer could inject arbitrary HTML and/or JavaScript code along with the submitted data. now all the submitted data is passed through the htmlentities() function and, if magic_quotes are on, are stripslashed (thanks to Bartosz for reporting)
file uploads were not working because neither “enctype” nor MAX_FILE_SIZE were set upon the rendering of the form
if you would set a checkbox’s state as “checked” by default, any subsequent submits would set the checkbox’s value to “checked” even if user would uncheck it (thanks to sridhar for reporting)
“required” rule could not be set to the “file” control (thanks to sridhar for reporting)
a new method was added: “addVar()”. through this method, user defined variables can be made accessible from within the form’s template file
added a new control: “captcha” which generates CAPTCHA images
password controls no longer re-display the entered value

version 1.0 BETA 2 (January 05, 2007)

fixed various bugs in code, example and documentation;
in Firefox, trying to open the date picker would produce a JavaScript error;
the icon for opening the date picker was not visible in Firefox;

version 1.0 BETA (December 19, 2006)

initial release;

Top

419 responses to “Zebra_Form, a jQuery augmented PHP library for creating and validating HTML forms”

Follow the comments via RSS

Allan, 2012-05-16, 01:07

I see that this has been asked before but was never answered.

I need to use a custom form with dynamic checkboxes but cannot work out how to display them.

ie I have $label_checkbox_1 and $checkbox_1 but I might also have $label_checkbox_2 and $checkbox_2 or $label_checkbox_5 and $checkbox_5

Reply
- Stefan Gabos, 2012-05-16, 04:42
  
  the way I do it is to put all the controls I need on the page right from the start, with all the needed rules attached. From jQuery I can easily control what’s visible and when, and rely on the fact Zebra_Form will not do client-side validation on elements that have “display:none” or “visibility:hidden”.
  
  The problem is that if client-side validation is done and ok, the form will submit but in PHP you will not know which elements were hidden BUT you know all the values that were submitted. So, the trick is that when you create the form, attach rules based on value of $_POST like:
```
// we have a random checkbox
$form->add('checkbox', 'mycheckbox', 1);

// this second checkbox is required only if the first one is
// selected; whether this checkbox is visible or not is
// controlled from jQuery
$obj = &$form->add(
  'checkbox',
  'myothercheckbox',
  2,
  array('style' => 'display:none')
);

if (
  isset($_POST['mycheckbox']) &&
  $_POST['mycheckbox'] == 1
) {

  $obj->set_attributes(array('style' => 'display:block'));

  $obj->set_rule(array(
    'required' => array('error', 'Some error');
  ));

);
```
  I hope this makes sense
- Allan, 2012-05-16, 13:02
  
  Thanks Stefan but I think you missed 1 big point. I don’t know what the checkboxes will be because they are dynamic (generated from records in a database that change over time. some stay. some go. some are selected for the particular situation. etc)
  
  Using the *horizontal or *vertical layout works fine, but I need a more customized layout. What would be useful is if an array could be passed to the template instead of the particular multiple variables.
  
  eg instead of $label_checkbox_1 and $checkbox_1 etc could we please get $label_checkbox['1'] and $checkbox['1']. That way we could simple foreach through the array.
- Stefan Gabos, 2012-05-16, 13:48
  
  by all means: use custom templates!
Raphaël, 2012-05-16, 07:59

Found a little bug on your include Button.php you definied
‘type’ => ‘submit’ but submit type is already exist with submit class and cause some problem for guy only need normal button :p.

Reply

Stefan Gabos web developer extraordinaire