Easily create forms and validation with Formjack

Today we’ve open sourced our new library for easy form generation and validation called Formjack. Want to learn more about it? Follow along!

Formjack is an open-source PHP library. Via its minimalist and simplistic API, it helps you to build, validate and deploy custom forms with ease.The Formjack library can be viewed and downloaded from it’s official GitHub repository. Keep in mind this library is still in the pre-alpha stage of development which means that API methods and their implementation could change slightly in the future.

Installation

In order to integrate and use the library within your site or app you’ll first need to download or clone it from it’s official GitHub repository located at https://github.com/Slicejack/Formjack. Now copy or move the Formjack directory into your projects directory and include it within your project.

Let’s now create a new PHP file that we’ll use to create forms for our site. Let’s call it forms.php and include it into our main PHP file right below the Formjack library inclusion.

Usage

Let’s now open our forms.php file where we’ll create our first form. We’ll use the Formjack\Form class to create our new form instance.

With our new form instance in place we can now add fields to it. Before we start adding and using those fields we must first understand how they actually work and how they are built. The abstraction behind is fairly simple. Every field extends and thereby is a instance of the Formjack\Fields\AbstractField class. Every field type has it’s own class and at this very moment the Formjack library allows you to create the following fields: Textarea, Text, Number, Email, Password, Select (with the multiselect option), Checkbox and Radio. You can learn more about how to implement and use those fields on the official Formjack Wiki.

Now let’s add the “name” and “email” field instances to our form.

The fields can be added in a more dynamic way by using the addField method provided by the Formjack\Form class as well.

Now that we’ve added all the fields we need tp render them within our sample view file. To do so we’ll first create the view.php file, include it into our project right below the forms.php file and add some HTML and PHP code into it.

Once you refresh the page you should see your new form show up. It did? Awesome. Let’s now add a few custom attributes to our fields. We can do that by passing the options array as a second argument to our field constructor and by specifying the attributes array in which the key represents the attribute and value represents the actual attribute value.

We can also use that same array of options to customize the default (initial) field state and/or it’s behaviour. To test that let’s set a default value to our “name” field.

Now, the next time you refresh the page you’ll see the “name” field is pre-filled with the “Default” text. Also, if you inspect the fields, you’ll see they also contain the attributes defined within the attribute option. Since every field accepts a different set of options that can be used to customize the field appearance and behaviour you should visit the offical Formjack Wiki where you can read more about those very options.

Binding and validating

Now that we have our form configured and rendered we must equally cover the form submission case. In order to do so first we will create a new php file called handlers.php and we will include it inside out project right inbetween forms.php and view.php files.

Let’s now open the handlers.php file and write a simple code that assumes that the form is submited if the HTTP request is a POST request and var_dumps the value of all fields if the form is really submited. Note that if you’re implementing this on a production site you might want to check which action or form triggered the POST request since one page could have more POST request triggers.

Since we don’t want to receive data that is invalid we’ll add some validation rules to our form fields. Let’s make our “name” field required and make sure that the “email” field value is a valid email. To do so we’ll need to pass validation array to the constructor of our fields and we’ll also need to update the handlers.php field.

If you were to submit the form now you would see an array of errors appear right above the form in the case of invalid form submission (one or more field values are invalid). Alternatively you may see an array of form field values appear in that same spot in the case of a valid form submission (both field values are valid). Now let’s say that you wish to ensure that the “email” field value is a valid email only if the value is not empty. That option can come in handy if a field isn’t required but should be valid if a user decides to fill it in. To make that kind of validation we’ll update the “email” field validation array by replacing the “Email” rule with the “When” rule which will hold the “Email” rule as it’s child rule.

The “When” rule accepts 2 parameters. The first parameter is a function that receives the form field values array as it’s first and only parameter. That function will return either true or false while the second parameter is an array of rules that will be used within the validation process only if the first parameter (anonymous function) returns true.

You can see that we’ve implemented our function in such a way that it returns true only if the “email” value is not empty which means that our value will be validated against the “Email” rule only if the value is not empty.

If you wish to learn more about some other rules, go ahead and visit the official Formjack Wiki.

Future development and contribution

Formjack is currently in an early stage of development. Nevertheless, the library is pretty much stable and in active use by our development team. There’s a small chance that the API could change slightly until we reach the first stable release but we’ll try to avoid that as much as possible. Feel free to contribute to the project by adding new fields and validation rules or by reporting errors that you encounter to our issue tracker. We also accept new ideas to make this project even better so feel free to contribute 😉