PHPackages                             burntcaramel/perforated - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Parsing & Serialization](/categories/parsing)
4. /
5. burntcaramel/perforated

ActiveLibrary[Parsing & Serialization](/categories/parsing)

burntcaramel/perforated
=======================

Simple yet pretty powerful forms using associated arrays or JSON, with automatic server validation, dependencies and more.

1.5.3(11y ago)524MITPHPPHP >=5.3.0

Since May 23Pushed 11y ago2 watchersCompare

[ Source](https://github.com/BurntCaramel/perforated)[ Packagist](https://packagist.org/packages/burntcaramel/perforated)[ RSS](/packages/burntcaramel-perforated/feed)WikiDiscussions master Synced yesterday

READMEChangelogDependencies (1)Versions (5)Used By (0)

Perforated – simple yet pretty powerful forms
=============================================

[](#perforated--simple-yet-pretty-powerful-forms)

Perforated forms are easy to create, read, and change later on. Define your form’s structure using a simple set up of key-based arrays, in PHP or JSON.

### Edit easily.

[](#edit-easily)

The easy-to-understand syntax means you can quickly create a form in a few minutes. Use HTML5 entry types such as URL, email address, number, and checkbox. They are automatically validated on the server with no extra code.

Come back to it later and add, edit, remove. Adding new entries means just adding a few lines of simple code. The syntax is so simple you can even define your form in a JSON file, if you wish.

### Style sensibly.

[](#style-sensibly)

Perforated is designed to be smart. It groups related entries together in `` elements. Entries are automatically created with an associated ``. This means it is very easy to style in CSS. Target specific form entries. Target all entries of a certain type.

### Extend.

[](#extend)

Perforated will automatically shows type-specific errors for incorrectly entered fields. Easily extend this validation. Add your own error messages.

Form processing and validation is completely separate from form display, so extend or replace how your form is validated or how it is displayed however you wish.

### Automatically namespaced.

[](#automatically-namespaced)

Submitted forms have their own namespace e.g. `$_POST['formID']`This means it will not clash with other POST variables, so use fields like `name` without worry in WordPress:

### Make sections dependant on whatever you wish.

[](#make-sections-dependant-on-whatever-you-wish)

Sections can be made to only show when a checkbox is on with one line. Just declare what you want, there's no extra JS.

External values can be used to automatically fill entries or for dependencies to turn sections on and off, just by using a simple callback. For example, only show and use a particular part of a form if the user is logged in – no complicated if-statements.

Example
-------

[](#example)

```
define ('EXAMPLE_SUBMIT_VIDEO', 'submitVideo');
define ('BURNT_ENDASH', "\xE2\x80\x93");

// This can be written using PHP arrays, or loaded from a JSON file.
$formOptions = array(
	'baseID' => EXAMPLE_SUBMIT_VIDEO,
	// All the entries to be used in the form.
	'entries' => array(
		'videoLink' => array(
			'title' => 'Video link '.BURNT_ENDASH.' Vimeo / YouTube',
			'value' => '',
			'type' => 'url',
			'required' => true
		),
		'story' => array(
			'title' => 'Video details & story', // Don't need to worry about escaping HTML first.
			'value' => '',
			'type' => 'text',
			'multipleLines' => true,
			'required' => true
		),
		'name' => array(
			'title' => 'Your name',
			'value' => '',
			'type' => 'text',
			'required' => true
		),
		'email' => array(
			'title' => 'Your email',
			'value' => '',
			'type' => 'email',
			'required' => true
		),
		'helpedCreate' => array(
			'title' => 'Were you a part of this video?',
			'value' => false,
			'type' => 'checkbox',
			'titleWhenOff' => 'No',
			'titleWhenOn' => 'Yes'
		),
		'role' => array(
			'title' => 'What was your role?',
			'value' => '',
			'type' => 'text',
			'required' => true
		),
		'location' => array(
			'title' => 'Where are you located? (city & country)',
			'value' => '',
			'type' => 'text'
		),
		'companies' => array(
			'title' => 'Who are the companies and teams behind the video?',
			'value' => '',
			'type' => 'text',
			'multipleLines' => true
		),
		'businessEmail' => array(
			'title' => 'Is there an email we can contact for business enquiries?',
			'value' => '',
			'type' => 'email'
		)
	),
	// This is the actual structure of the form as it is displayed, grouped into subsections.
	'structure' => array(
		array(
			'id' => 'videoInfo',
			'entries' => array('videoLink')
		),
		array(
			'id' => 'aboutSubmitter',
			'dependentOn' => 'loggedOut', // Only uses (shows and processes) this if the 'loggedOut' external value is on.
			'alsoProcessIf' => 'loggedIn', // These entries are automatically filled (see 'automaticallyFillEntriesFrom' further down) so process them even if its dependency is off.
			'entries' => array('name', 'email')
		),
		array(
			'id' => 'connectionQuestion',
			'entries' => array('helpedCreate')
		),
		array(
			'id' => 'connection',
			'dependentOn' => 'helpedCreate', // Only show this if the 'helpedCreate' checkbox is on.
			'entries' => array('role', 'location', 'companies', 'businessEmail')
		)
	),
	// Automatically uses external values to fill in entries.
	'automaticallyFillEntriesFrom' => array(
		// Using external value 'loggedInMember', grab the following values:
		'loggedInMember' => array(
			'name' => 'name', // Entry value for 'name' is automatically filled from $externalValues['loggedInMember']['name']
			'email' => 'emailAddress', // Entry value for 'email' is automatically filled from $externalValues['loggedInMember'][emailAddress]
		)
	)
);
```

Using external values from the server
-------------------------------------

[](#using-external-values-from-the-server)

```
function exampleExternalValues()
{
	$loggedInMemberInfo = exampleLoggedInMemberInfo();
	$specialValues = array(
		'loggedIn' => !empty($loggedInMemberInfo),
		'loggedOut' => empty($loggedInMemberInfo),
		'loggedInMember' => $loggedInMemberInfo
	);
	return $specialValues;
}
```

Validating & processing
---------------------------

[](#validating--processing)

```
// Check if form is being submitted and if so, process the submitted entries.
$resultsForSubmitVideo = perforatedFormCheckAndProcess($formOptions, array(
	'externalValues' => 'exampleExternalValues' // Options and callbacks are kept separate to enabled $formOptions to be created as pure JSON.
));
```

Working with submitted results
------------------------------

[](#working-with-submitted-results)

```
?>

Video Submissions