What Is Form Keeper?

This is where Form Keeper steps in. Form Keeper is a CakePHP 1.3 plugin that takes over from where CakePHP’s awesome Form Helper left off. Usually your forms would be constructed in a way like:

<input name="data[ModelName][field_name]" id="ModelNameFieldName" value="" type="hidden" />

This is all well and good. PHP will take those posted results, turn the data into a multidimensional array, pass it onto CakePHP and CakePHP will handle the rest, like a boss. The only problem with this is, it leaves a bad feeling in my stomach, in that, the end user knows your models, your field names in the database. Now there may be no immediate security threat with that, but less information provided, means less information for the end user to get construct blueprints of your database. So with FormKeeper you get:

<input name="6a03949c66c7cc5c7bce550c21308659c1d848a7" type="text" maxlength="40" id="6a03949c66c7cc5c7bce550c21308659c1d848a7">

What FormKeeper Does

Form Keeper takes your forms, with all the power of CakePHP’s FormHelper, and adds a layer of one way encryption to your field names and field id’s. These values are firstly SHA1′d, cached locally into a hash table of your choice (using CakePHP’s cache engine, also check out my CakePHP SuperStack plugin for some cache redundancy action), then outputted to the view. When the form is then submitted, FormKeeper checks the value is in the hash table, reconstructs the data multidimensional array, and inserts the values.

Now if you are thinking “this is all good, but CakePHP’s security component is a mean bastard when it comes to forms and blackhole-ing”, well that part is covered. The tokenizing works just fine with this plugin, so you can use the security component alongside the FormKeeper for obfuscation and form tampering fun.

Setting FormKeeper Up

This is all well and good, but how do I set FormKeeper up? Quite easily, FormKeeper is a CakePHP plugin, so all you need to do is clone the Github repository to your plugins directory and then include both the plugin’s helper and component elements to either your AppController (if you want to use it site wide) or to the controller of your choice.

git clone https://github.com/voidet/form_keeper app/plugins/form_keeper

Or if you use submodules (like you should):

git submodule add https://github.com/voidet/form_keeper app/plugins/form_keeper
git submodule init
git submodule update

From there all that is left is adding it to your controller(s):

<?php

class UsersController extends AppController {

	public $components = array('FormKeeper.FormKeeper');
	public $helpers = array('FormKeeper.FormKeeper');

Now user views have access to the FormKeeper power! But how do views use it? Easy, instead of $this->Form, you will now use $this->FormKeeper, for everything!

<?php

echo $this->FormKeeper->create();
echo $this->FormKeeper->input('username');
echo $this->FormKeeper->input('password');
echo $this->FormKeeper->input('remember_me', array('type' => 'checkbox'));
echo $this->FormKeeper->end('Login');

Configuration

There are two parameters (so far) that you can change for the plugin. It’s as simple as adding in a configuration file into your app/config folder, named form_keeper.php, app/config/form_keeper.php. The two parameters that can be changed is the salt string to encrypt with (if not provided the Security.salt value in core.php will be used) and the cache config that you want to use (by default it will be the default core cache config, which is usually file). So create app/config/form_keeper.php and add in:

<?php

$config['FormKeeper'] = array(
	'salt' => 'ixNE257AeJI2mbVicRwjEFM169seG59lzmxP8N4Z',
	'cacheKey' => 'default',
);

Also please note that the Id’s of the input field are also hashed. To avoid this, you can simply provide an id in your input options, as you would to override cake’s default ID. This is primarily used for object selection in the DOM with jQuery etc.

Security Component

CakePHP has an excellent form tampering protection method that comes standard with the Security Component. It basically takes all the form fields in the view/layout between create and end, serializes their names and then hashes this into a token. The token is stored in a hidden field within the form, and once posted back is then checked against the posted data keys. If there is any variance in the rehashed field names that have been posted and in the token field then the user’s request will be blackHoled, effectively white screen of death (which can be easily overridden for your security pleasure).

FormKeeper maintains this level of security and functionality of CakePHP’s security component. The way FormKeeper achieves this is simply down to order of execution. FormKeeper taps into the power of the Form Helper by overriding how it creates field names. So basically Security Component generates it’s tokens (found in Form::secure()) against FormKeepers new field names. Coming back is also a matter of execution. FormKeeper remaps/restitches the hashed/protected field names back into the proper data[Model][fieldname] structure, because Security Component get’s its eager hands on the data ready to crush with the blackHole method. So in effect FormKeeper gets in and out before Security component knows any different.

Thats It!

This is an early release of the plugin, and is not tested in production just yet. Expect many updates to come in the near future, and hopefully some test cases to be written. Also if you’re using the security component, then please include it after the FormKeeper component at this point in time, as that is what has been *thoroughly* tested with. Thank you in advance for any comments and feedback left! If you’re having issues with the plugin, I usually respond pretty fast with updates or advice. Enjoy!

CakePHP 2.0

SignMeUp has now been updated to work with CakePHP 2.0. There will be a few more updates in the next few days after I get better access to the internet. Any issues either comment here or open up an issue ticket on Github. To check out the 2.0 updates simply clone down SignMeUp and then do git checkout 2.0.

https://github.com/voidet/sign_me_up/tree/2.0

Introduction

Sign Me Up is a CakePHP plugin that allows you to easily integrate a user sign up form. It comes with:

• User registration form with basic fields Username, email, password and password confirmation.
• Default field validation which can be easily overwritten in your models.
• Welcome email sending upon successful registration.
• User activation code generation and activation via a link/post.
• Integrates with Auth settings for redirects and email/view templates easily overwritten.

Where to get it: https://github.com/voidet/sign_me_up
Clone with git: git clone https://github.com/voidet/sign_me_up.git

Using Sign Me Up

Firstly you will need to clone the plugin into your plugins directory:

cd /the/path/to/my/cakeapp/app/plugins/
git clone https://github.com/voidet/sign_me_up.git

Now that we have the plugin available to us, it is time to attach it to your controller/models. To do so you will need to add the Sign Me Up component to the controller that handles your user functions, such as login etc. Add in the component code for example:

class UsersController extends AppController {
public $components = array('SignMeUp.SignMeUp');

That’s one part of the story, however it is probably best to add in the behaviours to your user/member model also:

class User extends AppModel {
public $actsAs = array('SignMeUp.SignMeUp');

Next up in your controller you will need to create the actions and link them up to the Sign Me Up plugin:

public function register() {
$this->SignMeUp->register();
};

public function activate() {
$this->SignMeUp->activate();
}

public function forgotten_password() {
$this->SignMeUp->forgottenPassword();
}

It’s pretty easy from there. You can make custom routes to these actions to keep your urls SEO friendly or whatever you like.

Configuration

Sign me up uses a basic config file which should be stored in app/config/sign_me_up.php If you don’t have this file then the Sign Me Up plugin will exit with a message saying it could not find the config file. SignMeUp configuration allows you to overwrite all default CakePHP email parameters by simply specifying the elements in the SignMeUp configuration array i.e change email sending to HTML format via setting the sendAs to HTML or change the email layout with ‘layout’ => ‘myLayout’. The only thing that you would need to diverge from the Email Component settings with is the welcome and activate templates. You can set them with welcome_template and activation_template elements:

<?php
$config['SignMeUp'] = array(
	'from' => 'MyDomain.com <admin@exampledomain.com>',
	'layout' => 'default',
	'welcome_subject' => 'Welcome to MyDomain.com %username%!',
	'activation_subject' => 'Activate Your MyDomain.com Account %username%!',
	'sendAs' => 'html',
	'activation_template' => 'activate',
	'welcome_template' => 'welcome',
	'password_reset_template' => 'forgotten_password',
	'password_reset_subject' => 'Password reset from MyDomain.com',
	'new_password_template' => 'new_password',
	'new_password_subject' => 'Your new password from MyDomain.com',
	'xMailer' => 'MyDomain.com Email-bot',
);

Also note you can include fields in the subject line from your user model. Simply specify the field name you want placed in the subject line with %field_name%. That is that!

The Views

The plugin allows the end user to easily overwrite the view files for emails and the front end forms etc. Firstly to create your registration page make a new view in your views/users/register.ctp You can then add in all your design elements or simply include the default Sign Me Up registration element via:

<?php echo $this->element('register', array('plugin' => 'SignMeUp')); ?>

The same goes with the activation element, which you can include in views/users/activate.ctp

<?php echo $this->element('activate', array('plugin' => 'SignMeUp')); ?>

Also for the forgot your password page, views/users/forgotten_password.ctp

<?php echo $this->element('forgotten_password', array('plugin' => 'SignMeUp')); ?>

Email Templates

You will need to create the CakePHP layouts and views to use. I have only used text based emails, quite simple. So to do so create a new layout in app/views/layouts/emails/text/default.ctp with

<?php echo $content_for_layout; ?>

And now for the welcome email view, which comes with the activation code:

Registration (app/views/elements/email/text/welcome.ctp):

Welcome <?php echo $user['username']; ?>,

In order to get started please click on the following link to activate your account:

<?php echo Router::url(array('action' => 'activate', 'activation_code' => $user['activation_code']), true)."n"; ?>
We look forward to seeing you!
Regards,
MyDomain.com Staff

Also your forgotten password email template can look something like, app/views/elements/email/text/forgotten_password.ctp

Hi <?php echo $user['username']; ?>,

Someone (hopefully you) has requested a password reset on your account. In order to reset your password please click on the link below:

<?php echo $this->Html->link('Reset your password', Router::url(array('action' => 'forgotten_password', 'password_reset' => $user['password_reset']), true)); ?>

Regards,
MyDomain.com Staff

We Dont Need No, Activation

So you want a basic sign up system, but want to knock out the user activation hassle? Well to do so simply ensure that you have setup the SignMeUp plugin to have no activation field set. To do that simply set your activation_field to false:

	public $components = array('SignMeUp.SignMeUp' => array(
'activation_field' => false,
'useractive_field' => false,
));

You can also see that useractive_field is set to false, this is for fields that signify if the user is active or not, and saves a boolean value. With the activation_field set to false this will, instead of sending out an activation email, send out a welcome email, of which can be defined in the SignMeUp configuration file as above.

Please note that if you want to use a welcome email, the template of the email should be specified in your SignMeUp config file, and then created. All the user information will still be available.

I Need Help

That is a quick summary of the basic functions of the Sign Me Up plugin. The plugin will be developed further as either users request features or I need them built in for my own projects. Just to eliminate any confusion, a look at some routes you might want to use:

Router::connect('/register', array('controller' => 'users', 'action' => 'register'));
Router::connect('/activate', array('controller' => 'users', 'action' => 'activate'));
Router::connect('/activate/:activation_code', array('controller' => 'users', 'action' => 'activate'), array('pass' => 'activation_code'));
Router::connect('/forgotten_password/:password_reset', array('controller' => 'users', 'action' => 'forgotten_password'), array('pass' => 'password_reset'));
Router::connect('/login', array('controller' => 'users', 'action' => 'login'));
Router::connect('/logout', array('controller' => 'users', 'action' => 'logout'));

If you need any assistance or find bugs, please leave a comment and I can help you out patch some bugs

I Put What Where?

There has been some confusion as to what fields are required or optional in your authentication table (users, members etc table). Also people are finding that their emails are being sent out, or max execution time is being hit. This section will help describe what to do with your database, where to put the email files and how to send out emails.

My DB Table

CREATE TABLE `users` (
  `id` int(11) unsigned NOT NULL AUTO_INCREMENT,
  `username` varchar(40) DEFAULT NULL,
  `email` varchar(255) DEFAULT NULL,
  `password` varchar(40) DEFAULT NULL,
  `activation_code` varchar(40) DEFAULT NULL,
  `active` tinyint(1) DEFAULT NULL,
  `password_reset` varchar(40) DEFAULT NULL,
  `created` timestamp NULL DEFAULT NULL,
  `modified` timestamp NULL DEFAULT NULL,
  PRIMARY KEY (`id`)
); 

This uses the default values found in SignMeUp. You can override these as mentioned above in your sign_me_up.php config file which should be stored in app/config/sign_me_up.php

My Email Files

This section really depends what email type you are sending out, html, text-only, or both. Either way. Lets say we are sending out text only emails, you will need to first make the layout file in app/views/layouts/email/text/default.ctp and just put in

Next up you need to setup your email templates. The email templates are basically your view for each email that you send out, be it the welcome or activation emails for example. So in order to send out a welcome email you would make your file in app/views/elements/email/text/welcome.ctp This template is as defined in your sign_me_up.php configuration file. You can use the example welcome text as seen above.

Basically you need to include your email layouts and templates in your application, not inside the sign_me_up plugin.

Max Execution time being hit

I have seen one person hit this issue and it comes down to email sending. If you are using SMTP for your email sending type then make sure your network that you’re on allows connection to whatever address you’re trying to send out to. A max execution time is being hit because the application cannot establish a connection to the smtp server and is left hanging.

Updates

To make things easy, I will keep any updates on the GitHub page and updates written below here as a small change log:

0.7 Added in forgotten password functionality
0.6 Pushed updates that now allow user activation to be optional. Activations will only be attempted if the default settings of activation_field is not set to false.
0.5.5 Bug Fixes thanks to the comments received
0.5 Initial Release

So after asking around a bit i decided to write my own method of ordering my tree data in the database, which was a Category list to be used in a select box. My helper came out to be:

/app/views/helpers/tree.php

<?php
	
	class TreeHelper extends AppHelper {
		
		function indentTree($array, $counter=0){
			$ret = '';
			$array2 = array();
			$pre = '';
			for($i = 1;$i < $counter; $i++){
				$pre .= '--';
			}
			
			foreach($array as $key => $value){
				if($key == 'children'){
					if(isset($value['Category']) || (isset($value['children']) && sizeof($value['children']) > 0)){
						$indented[] = $this->indentTree($value, ++$counter);
					} else {
						if(sizeof($value) > 0) {
							$indented[] = $this->indentTree($value, $counter);
						}
					}
				}	elseif($key == 'Category'){
					$indented[$value['id']] = ' '.$pre.' '.$value['name'];
				}	elseif(isset($value['Category']['name'])){
					$indented[] = $this->indentTree($value, $counter);	
				}
			}
			return $this->flatten_array($indented, 2);
		}
		
		function flatten_array($array, $preserve_keys = 0, &$out = array()) {
			foreach($array as $key => $child){
				if(is_array($child)){
					$out = $this->flatten_array($child, $preserve_keys, $out);
				} elseif($preserve_keys + is_string($key) > 1){
					$out[$key] = $child;
				} else {
					$out[] = $child;
				}
			}
			return $out;
		}
		
	}	
	
?>

To use this simply include the helper in your controller via:

var $helpers = array('Html', 'Form', 'Text', 'Javascript', 'Tree');

And then within your action you must select the data in a threaded form, the same as GenerateTreeList would do, however pre-ordered:

$categories = $this->Category->find('threaded', array('order' => array('Category.name' => 'ASC')));
$this->set('categoriesList', $categories);

Next up you use the helper in your view via:

echo $form->input('parent_id', array('type'=>'select', 'options'=>$tree->indentTree($categoriesList), 'empty'=>'--------', 'div'=>'row'));

And thats it!
For me this will return an ordered flattened array of my categories to be used within the select box!
I know this explanation is a bit low but it should be enough to get you started! If you have any questions please comment and i will see what i can do to help you out!