README

v2.7.16

This library provides a simple powerful HTML5 form builder, validator, spam checker, spam submitter, form contents emailer, and more.

It is designed with the end user in mind so the typing is minimized as much as possible and the syntax is as much like HTML as possible with added functionality.

This library blocks form submissions from domains other than the domain the site is on. It also protects against Cross Site Request Forgeries by default.

Install

To install with composer:

composer require truecastdesign/welder

Requires PHP 5.5 or newer.

Usage

How to build a form:

Make a new instance

<?$F = new \Truecast\Welder?>

Output the form tag and other hidden fields

<?=$F->start('action=/html-php-page class=formClassName')?>

The above code will output this HTML

<form action="/html-php-page" method="post" class="formClassName" accept-charset="utf-8">
	<input type="hidden" name="authenticity_token" value="00c9f0fdca847c547ac0292d8d45e0e1ebcd5e395dffc4daf2a0b16420616cf2">
	<input type="hidden" name="form_action" value="submit">

File Uploads

If you are going to use File Uploads in the form, than you need to have the enctype set to multipart/form-data. To set that, pass file=true as an argument on the start method.

<?=$F->start('action=/html-php-page class=formClassName file=true')?>

Text Fields

The method names are the type of field you want. textarea, checkbox, etc. The double quotes in the property string are not needed if the value does not have spaces. Saves typing by skipping them if not needed.

<?=$F->text('name=name label="Your Name *" style="width:250px" autofocus=autofocus pattern="^^([1-zA-Z0-1@.\s]{1,255})$" ');?>

Supported field types: text, password, hidden, submit, reset, image, file, number, email, tel, date, datetime, datetime-local, month, search, time, url, week, color, range, checkbox, radio, select, button.

The above code will output this HTML

<span id="error-name" class="anchor"></span>
<label for="name_1">Your Name*</label> 
<input type="text" name="name" style="width:250px" autofocus="autofocus" pattern="^^([1-zA-Z0-1@.\s]{1,255})$" id="name_1">

Other examples:

<?=$F->email('name=field_name label="The Label" style="width:250px"');?>
<?=$F->textarea('name=field_name label="The Label" style="width:250px"');?>
<?=$F->tel('name=field_name label="The Label" style="width:250px"');?>

Checkboxes

<?=$F->checkbox('name=checkBox label="Checkbox Label" value=Yes')?>

The above code will output this HTML

<span id="error-checkBox" class="anchor"></span>
<input type="checkbox" name="checkBox" value="Yes" id="checkBox_1"> 
<label for="checkBox_1">Checkbox Label</label>

Select Menus

<?=$F->select('name=selectMenu label="Select Label" selected=opt2 options="opt1:Option One| opt2:Option Two| opt3:Option Three"')?>

The above code will output this HTML

<span id="error-selectMenu" class="anchor"></span>
<label for="selectMenu_1">Select Label</label> 
<select name="selectMenu" id="selectMenu_1">
	<option value="opt1">Option One</option>
	<option value="opt2" selected>Option Two</option>
	<option value="opt3">Option Three</option>
</select>

Use an array to set create the options.

<? $options = ['Select...'=>'', 'Display Value'=>'value', 'Display Value 2'=>'value2']; ?>
<?=$F->select('name=selectMenu label="Select Label"', $options)?>

Custom Errors

Use the 'error' key to set a custom error to display when the form is submitted and validation errors are displayed.

<?=$F->email('name=field_name label="The Label" error="Please enter a valid email address!"');?>

Form Validation

The validate method takes the field name on the left and the validation method to the right of the equal sign. The available validation methods start with validate_ in the class so you can look them up to see what they do. The clean method runs several content cleaning functions to sanitize the data if it does not conform to any set pattern like emails or names, etc.

You can use the spam method to check if the form is spam. If you want to use Akismet, just pass it the field names for their name, email, and content. They need to be in that order.

If you want to make sure the form does not contain any urls then add the nourls flag like: nourls=true. Setting it to true checks all the fields. If you want to only check certain fields do that like this: nourls="field1,field2".

If you want to check the captcha add the captcha flag. Display the captcha on the page with <?$F->captcha()?>. You will need to move the form-captcha.php file to a public accessible directory and change the include path into to access the Welder.php file.

Spam Content Checking

Welder uses several spam checking method to determine if an email message is likely to be spam. Use the keyword spamcontent and set it equal to the field names you want to check. Example: spamcontent="subject,message"

Gibberish: matches text that is not real words but just random repeated keystrokes like "asdasd" or "qwejjjjjeeee"

Too Many Consonants: Checks if the message has words will more than 6 consonants in a row. Usually means it is invalid words and spam

Keyword Search: Search message for spam keyword phrases that spammers commonly use to sell you something.

$F = new Truecast\Welder; # does not need to be the same instance as the one used to build the form but can be.

if($F->validate('first_name=name email_address=email phone=clean message=required') and $F->spam('akismet="name,email,content" spamcontent="subject,message" nourls="subject,message"')) # valid
{
	$values = $F->get(); # array of values from form cleaned and ready to insert into database or what ever.
	
	# email the form contents to yourself
	$F->emailForm(['to_name'=>'Name', 'to_email'=>'name@gmail.com', 'from_name'=>$values['name'], 'from_email'=>$values['email'], 'subject'=>'Contact from Website', 'type'=>'html'], ['name', 'email', 'phone', 'message']);
	
	# take them to the thanks page
	header("Location: /contact-us/thanks"); exit;
}

Getting and Setting Field values

If you want to populate the form fields from a database record or other source on display of form but not submitting it, use the setFieldValues method to pass a key value array of field name to value. You can set more than one at a time.

$values = ['field1'=>'hello', 'field2'=>'world'];
$F->setFieldValues($values);

You can do this as an else statement on the if($F->validate()) method call if you make sure the view has access to the same Welder instance. Pass the $F variable to the view if needed.

if($F->validate()) {
	// form submitted code
} else {
	// form loaded code
	$values = ['field1'=>'hello', 'field2'=>'world'];
	$F->setFieldValues($values);
}

To get a field value or all field values in the view use:

<?=$F->getFieldValues('field1')?>

Get all in array.

<? $array = $F->getFieldValues()?>

Configuration

Turn off CSRF protection

$F = new \Truecast\Welder(['csrf'=>false]);

Turn off inline field errors

Normally there is outputted a span like:

<span id="error-first_name" class="anchor"></span>

before each field. If you don't want this tag outputted for some reason, turn it off using the below code.

$F = new \Truecast\Welder(['hide_field_error_tags'=>true]);

Use more than one form in a view or controller

$F = new \Truecast\Welder(['action_field'=>'submit1']);

$F2 = new \Truecast\Welder(['action_field'=>'submit2']);

You need to set the custom action field value on both the controller instance and the view instance so they match.

truecastdesign / welder

Maintainers

Details

README

Install

Usage

File Uploads

Text Fields

Checkboxes

Select Menus

Custom Errors

Form Validation

Spam Content Checking

Getting and Setting Field values

Configuration

Turn off CSRF protection

Turn off inline field errors

Use more than one form in a view or controller