An associative array of items uploaded to the current script via the HTTP POST method.

This property, available only if a file upload has occurred, will have the same values as $_FILES plus some extra values:

• path - the path where the file was uploaded to
• file_name - the name the file was uploaded with
• imageinfo - available only if the uploaded file is an image!
  an array of attributes specific to the uploaded image as returned by getimagesize() but with meaningful names:
  bits
  channels
  mime
  width
  height
  type (possible types)
  html
  

Note that the file name can be different than the original name of the uploaded file!

By design, the script will append a number to the end of a file's name if at the path where the file is uploaded to there is another file with the same name (for example, if at the path where a file named "example.txt" is uploaded to, a file with the same name exists, the file's new name will be "example1.txt").

The file names can also be random-generated. See the set_rule() method and the upload rule

Indicates the filesystem permissions to be set for files uploaded through the upload rule.

1. $form->file_upload_permissions = '0777';

The permissions are set using PHP's chmod function which may or may not be available or be disabled on your environment. If so, this action will fail silently (no errors or notices will be shown by the library).

Better to leave this setting as it is.

If you know what you are doing, here is how you can calculate the permission levels:

• 400 Owner Read
• 200 Owner Write
• 100 Owner Execute
• 40 Group Read
• 20 Group Write
• 10 Group Execute
• 4 Global Read
• 2 Global Write
• 1 Global Execute

Default is '0755'

void __construct ( string $name , [ string $method = 'POST'] , [ string $action = ''] , [ array $attributes = ''] )

Constructor of the class

Initializes the form.

1. $form = new Zebra_Form('myform');

Parameters:

reference & add ( string $type , mixed $arguments )

Adds a control to the form.

1. //  create a new form
2. $form = new Zebra_Form('my_form');
3.  
4. // add a text control to the form
5. $obj = $form->add('text', 'my_text');
6.  
7. // make the text field required
8. $obj->set_rule(
9.      'required' => array(
10.         'error',            // variable to add the error message to
11.         'Field is required' // error message if value doesn't validate
12.      )
13. );
14.  
15. // don't forget to always call this method before rendering the form
16. if ($form->validate()) {
17.     // put code here
18. }
19.  
20. //  output the form using an automatically generated template
21. $form->render();

Tags:

Parameters:

void add_error ( string $error_block , string $error_message )

Appends a message to an already existing error block

1. //  create a new form
2. $form = new Zebra_Form('my_form');
3.  
4. // add a text control to the form
5. $obj = $form->add('text', 'my_text');
6.  
7. // make the text field required
8. $obj->set_rule(
9.      'required' => array(
10.         'error',            // variable to add the error message to
11.         'Field is required' // error message if value doesn't validate
12.      )
13. );
14.  
15. // don't forget to always call this method before rendering the form
16. if ($form->validate()) {
17.  
18.     // for the purpose of this example, we will do a custom validation
19.     // after calling the "validate" method.
20.     // for custom validations, using the "custom" rule is recommended instead
21.  
22.     // check if value's is between 1 and 10
23.     if ((int)$_POST['my_text']) < 1 || (int)$_POST['my_text']) > 10) {
24.  
25.         $form->add_error('error', 'Value must be an integer between 1 and 10!');
26.  
27.     } else {
28.  
29.         // put code here that is to be executed when the form values are ok
30.  
31.     }
32.  
33. }
34.  
35. //  output the form using an automatically generated template
36. $form->render();

Parameters:

void assets_path ( string $server_path , string $url )

Set the server path and URL to the "process.php" and "mimes.json" files.

These files are required for CAPTCHAs and uploads.

By default, the location of these files is in the same folder as Zebra_Form.php and the script will automatically try to determine both the server path and the URL to these files. However, when the script is run on a virtual host, or if these files were moved, the script may not correctly determine the paths to these files. In these instances, use this method to correctly set the server path - needed by the script to correctly include these files, and the URL - needed by the client-side validation to include these files.

Also, for security reasons, I recommend moving these two files by default to the root of your website (or another publicly accessible place) and manually set the paths, in order to prevent malicious users from finding out information about your directory structure.

Parameters:

void assign ( string $variable_name , mixed $value )

Creates a PHP variable with the given value, available in the template file.

1. //  create a new form
2. $form = new Zebra_Form('my_form');
3.  
4. // make available the $my_value variable in the template file
5. $form->assign('my_value', '100');
6.  
7. // don't forget to always call this method before rendering the form
8. if ($form->validate()) {
9.     // put code here
10. }
11.  
12. // output the form
13. // notice that we are using a custom template
14. // my_template.php file is expected to be found
15. // and in this file, you may now use the $my_value variable
16. $form->render('my_template.php');

Parameters:

void auto_fill ( [ array $defaults = array()] , [ boolean $specifics_only = false] )

Call this method anytime *before* calling the render() method to instruct the library to automatically fill out all of the form's fields with random content while obeying any rules that might be set for each control.

You can also use this method to set defaults for the form's elements by setting the method's second argument to TRUE.

Notes:

• unless overridden, the value of password controls will always be "12345678";
• unless overridden, the value of controls having the "email" or "emails" rule set will be in the form of random_text@random_text.com;
• unless overridden, the value of controls having the "url" rule set will be in the form of random_text.com, prefixed or not with "http://", depending on the rule's attributes;
• file upload controls and controls having the "captcha" or "regexp" rule set will *not* be autofilled;

Tags:

Parameters:

void captcha_storage ( string $method )

Sets the storage method for CAPTCHA values.

By default, captcha values are triple md5 hashed and stored in cookies, and when the user enters the captcha value the value is also triple md5 hashed and the two values are then compared.

Sometimes, your users may have a very restrictive cookie policy and so cookies will not be set, and therefore, they will never be able to get past the CAPTCHA control. If it's the case, call this method and set the storage method to "session".

In this case, call this method and set the the storage method to "session".

Tags:

Parameters:

void clientside_validation ( mixed $properties )

Sets properties for the client-side validation.

Client-side validation, when enabled, occurs on the "onsubmit" event of the form.

1. //  create a new form
2. $form = new Zebra_Form('my_form');
3.  
4. // disable client-side validation
5. $form->clientside_validation(false);
6.  
7. // enable client-side validation using default properties
8. $form->clientside_validation(true);
9.  
10. // enable client-side validation using customized properties
11. $form->clientside_validation(array(
12.     'close_tips'                =>  false,      //  don't show a "close" button on tips with error messages
13.     'on_ready'                  =>  false,      //  no function to be executed when the form is ready
14.     'disable_upload_validation' =>  true,       //  using a custom plugin for managing file uploads
15.     'scroll_to_error'           =>  false,      //  don't scroll the browser window to the error message
16.     'tips_position'             =>  'right',    //  position tips with error messages to the right of the controls
17.     'validate_on_the_fly'       =>  false,      //  don't validate controls on the fly
18.     'validate_all'              =>  false,      //  show error messages one by one upon trying to submit an invalid form
19. ));

To access the JavaScript object and use the public methods provided by it, use $('#formname').data('Zebra_Form') where formname is the form's name with any dashes turned into underscores!

Therefore, if a form's name is "my-form", the JavaScript object would be accessed like $('my_form').data('Zebra_Form').

From JavaScript, these are the methods that can be called on this object:

• attach_tip(element, message) - displays a custom error message, attached to the element with the indicated ID (so, remember, "element" is string, not an object!)
• clear_errors() - hides all error messages;
• submit() - submits the form;
• validate() - checks if the form is valid; returns TRUE or FALSE;

Here's how you can use these methods, in JavaScript:

1. //  let's submit the form when clicking on a random button
2.  
3. // get a reference to the Zebra_Form object
4. var $form = $('#formname').data('Zebra_Form');
5.  
6. // handle the onclick event on a random button
7. $('#somebutton').bind('click', function(e) {
8.  
9.     // stop default action
10.     e.preventDefault();
11.  
12.     // validate the form, and if the form validates
13.     if ($form.validate()) {
14.  
15.         // do your thing here
16.  
17.         // when you're done, submit the form
18.         $form.submit();
19.  
20.     }
21.  
22.     // if the form is not valid, everything is handled automatically by the library
23.  
24. });

Parameters:

void client_side_validation ( $properties )

Alias of clientside_validation() method.

Deprecated since 2.8.9

Parameters:

void csrf ( [ string $csrf_storage_method = 'auto'] , [ integer $csrf_token_lifetime = 0] , [ array $csrf_cookie_config = array('path' => '/', 'domain' => '', 'secure' => false, 'httponly' => false)] )

Enables protection against Cross-site request forgery (CSRF) attacks.

Read more about specifics and a simple implementation on Chris Shiflett's website.

This method is automatically called by the library, so protection against CSRF attacks is enabled by default for all forms and the script will decide automatically on the method to use for storing the CSRF token: if a session is already started then the CSRF token will be stored in a session variable or, if a session is not started, the CSRF token will be stored in a session cookie (cookies that expire when the browser is closed) but, in this case, it offers a lower level of security.

If cookies are used for storage, you'll have to make sure that Zebra_Form is instantiated before any output from your script (this is a protocol restriction) including &lt;html> and &lt;head> tags as well as any whitespace! A workaround is to turn output buffering on in php.ini.

You are encouraged to start a PHP session before instantiating this class in order to maximize the level of security of your forms.

The CSRF token is automatically regenerated when the form is submitted regardless if the form validated or not. A notable exception is that the form doesn't validate but was submitted via AJAX the CSRF token will not be regenerated - useful if you submit forms by AJAX.

As an added benefit, protection against CSRF attacks prevents "double posts" by design.

1. // recommended usage is:
2.  
3. // call session_start() somewhere in your code but before outputting anything to the browser
4. session_start();
5.  
6. // include the Zebra_Form
7. require 'path/to/Zebra_Form.php';
8.  
9. // instantiate the class
10. // protection against CSRF attack will be automatically enabled
11. // but will be less secure if a session is not started (as it will
12. // rely on cookies)
13. $form = new Zebra_Form('my_form');

Tags:

Parameters:

void doctype ( [ string $doctype = 'html'] )

By default, this class generates HTML 4.01 Strict markup.

Use this method if you want the generated HTML markup to validate as XHTML 1.0 Strict.

Parameters:

void language ( string $language )

Sets the language to be used by some of the form's controls (the date control, the select control, etc.)

The default language is English.

Parameters:

mixed render ( [ string $template = ''] , [ boolean $return = false] , [ array $variables = ''] )

Renders the form.

Tags:

Parameters:

void reset ( )

Resets the submitted values for all of the form's controls (also resets the POST/GET/FILES superglobals)

void show_all_error_messages ( [ boolean $value = false] )

Sets how error messages generated upon server-side validation are displayed in an error block.

Client-side validation is done on the "onsubmit" event of the form. See clientside_validation() for more information on client-side validation.

1. //  create a new form
2. $form = new Zebra_Form('my_form');
3.  
4. //  display all error messages of error blocks
5. $form->show_all_error_messages(true);

Parameters:

boolean validate ( )

This method performs the server-side validation of all the form's controls, making sure that all the values comply to the rules set for these controls through the set_rule() method.

Only by calling this method will the form's controls update their values. If this method is not called, all the controls will preserve their default values after submission even if these values were altered prior to submission.

This method must be called before the render() method or error messages will not be available.

After calling this method, if there are file controls on the form, you might want to check for the existence of the $file_upload property to see the details of uploaded files and take actions accordingly.

Client-side validation is done on the "onsubmit" event of the form. See clientside_validation() for more information on client-side validation.

Tags:

boolean validate_control ( string $control )

This method performs the server-side validation of a control, making sure that the value complies to the rules set for the control through the set_rule() method.

Tags:

Parameters: