Not Just Any Old Framework

There are A LOT of open source PHP frameworks on the web today. Some of them are pretty nice tools and some of them aren’t. When evaluating a framework you need to look at several factors: community, documentation, features, support options and learning curve. Depending on your individual requirements you might have some additional criteria but I think that’s a decent baseline. Let’s see how CI stands up:

Community

Last look at the forums puts registered members at 190,000. Now that’s not necessarily active users, but that’s the number of developers who thought enough of the framework to get a forum account and join in on the conversation. EllisLab places a very high premium on their developer community and a number of the additions in 2.0 were added at their request.

Documentation

I have played around with a number of different PHP frameworks and you will be hard pressed to find a framework with better documentation than CI. The users guide is complete, easy to understand and up to date with all the latest bells and whistles. Any PHP developer with a basic understanding of object oriented programming (OOP) should be able to pick things up pretty easily.

It’s worth noting that with the release of 2.0 some new sections of the users guide are still being fleshed out, but there is enough there to help get you started.

Features

This is the true question: “can the framework do what I need it to do?” This question really depends on what it is you need it to do. But CI has most of the standard framework features including model view controller (MVC) architecture, database abstraction, form validation, session handing, error handling, flexible/scalable architecture and libraries to handle tasks like uploading files, displaying event calendars, implementing carts for e-commerce sites and much more. If that’s not enough CI also lets you add any additional functionality you want/need by building your own custom library or extending core libraries that are already there.

Support Options

So you invest all this time and effort into learning a framework and building your business around it, what do you do if things suddenly stop working? While CI doesn’t offer any kind of commercial support, the community is full of folks on the forum waiting to lend a hand when necessary. There are also a number of bloggers out there who share their CI knowledge and can be tapped for help from time to time.

The other thing worth mentioning here is that CI is backed by a successful commercial company in EllisLab (makers of ExpressionEngine CMS). So it’s a pretty safe bet that it’s not going anywhere anytime soon.

Learning Curve

We’re all on a timeline, so how long will it take to get up to speed? As I mentioned under documentation, CI is very well documented and has an active and vibrant community. With that said, anyone with a fair understanding of OOP should be able to pick things up pretty quickly.

New to Version 2.0

So now that I have your attention, let’s take a look at the exciting new additions to CI in version 2.0:

2 Flavors: Core and Reactor

As I mentioned above, CI is backed by a commercial company and is used by that company to develop their commercial products like ExpressionEngine and MojoMotor. That means that the development of the framework was limited to the needs of their products and the community got a little frustrated feeling that the development of the framework had stalled over time. In true EllisLab fashion they listened and in version 2.0 have released two different lines of development: Core and Reactor.

You now have the option of working with CI Core (maintained by EllisLab) or CI Reactor (maintained by the community). Core is the version of CI that EllisLab uses and will only change when they need to make a change for their products. This version should be used by those looking for true stability and backward/forward compatibility. Reactor, on the other hand, is maintained by a team of community engineers who collectively monitor community needs/wants and incorporate new features on a more frequent basis.

Since all changes made to Core will be incorporated into Reactor and that Reactor will be the more active of the two code bases it’s recommended that everyone use Reactor from this point forward.

PHP5 Support

A common point of contention with previous version of CI was that it wasn’t native PHP5 meaning the framework was backwards compatible with PHP4 and certain PHP5 features didn’t work or were not used. With the release of 2.0 this is no longer the case. PHP4 is no longer supported and you must be running PHP 5.1.6 or higher in order to use the framework. So feel free to start taking advantage of the OOP improvements of PHP5.

Packages

Distributing code for reuse or releasing complex libraries (for things like authentication) to the community has always been a somewhat clunky process. You would typically need to copy and paste certain files into certain places within your install in order for everything to work correctly. Config files in the config folder, libraries in their respective folder, etc. CI 2.0 does away with this issue by introducing a new way of collecting and distributing code called packages.

Packages are similar in theory to modular development in that all the resources you are distributing are self contained. All packages will have their own libraries, models, helpers, config, and language files collected in their own directory which can then be placed into the application/third_party directory of the framework for use. This provides developers with a much easier way of sharing/releasing code for use by the community. This also opens the doors for more module based application development with CI.

Drivers

In previous versions of CI there hasn’t been an elegant way of creating classes that all share a common parent class and not their sibling classes (handy in certain situations). You can now accomplish this with a new type of library called a driver. Drivers allow you to create a parent class with unlimited child classes that have no access to their siblings (for things like DB abstraction). This is a nice architecture for providing the same type of functionality only using different tools or implementation methods.

Along with being able to create your own drivers, CI 2.0 identifies three drivers in the documentation: Cacheing, Database and Javascript.

Javascript Library

Saving the best for last, the item I was most excited about with this release was the Javascript Library. CI 2.0 now gives you the ability to plug your favorite javascript framework into CI using drivers so you can incorporate javascript into your apps more easily. jQuery is being distributed with the framework by default but you can be sure there will be other drivers released shortly for other javascript frameworks.

Upgrading

So far this post has been mostly about what’s new and exciting in version 2.0 but there have also been some changes to the framework that might trip up seasoned developers and those of you looking to upgrade from an earlier version. First and foremost, all CI core classes are now prefixed with CI_. This means that all controllers, models, etc. now need to extend CI_Controller, CI_Model, etc. respectively. You will want to be sure to update your code accordingly when upgrading to version 2 (this already tripped me up once).

Second, some old features and functionality have finally been removed for good like scaffolding, plugins and the validation library. Plugins never really gained much traction with CI developers and have been deprecated for some time now. The CI core CAPTCHA plugin has been converted to a helper and any plugins you have developed should be converted to helpers also. The validation library, which has been replaced for a while now by form_validation, is gone. So if you have been putting off updating your code to use the new form_validation library now is the time to do it.

Finally, a number of improvements have been made to the encryption library which will prevent you from decrypting data that you have encrypted with a previous version. To deal with this, you will have to run an update on your data using the new encode_from_legacy() method which will decode your data and return a re-encrypted string using the new method for storage.

Those are the big things to look out for when upgrading from a previous version. Visit the users guide for complete upgrading instructions.

Is that it?

This is just a quick list of my top 5 changes/additions to the framework that have been released in 2.0. There’s a lot more where that came from like new cache drivers with APC, memcached, and file-based support, new security library and over 50 bug fixes. You can see the complete list of what’s new in the change log. So what are you waiting for? Take CodeIgniter 2.0 for a spin today!

Background

For those of you who don’t know, Twilio is a web service API that empowers programmers with the ability to make phone calls and send SMS text messages programmatically. I first came across the service a while back and have been keeping an eye on it ever since because I think it has a lot of potential uses in modern web applications. In the past, having your application make a phone call used to entail a lot of programming and hardware overhead ($$$). Twilio makes it as simple as one single API call (that doesn’t break the bank) and you’re done.

In this post I’m going to be building a sample application to illustrate some of what Twilio is capable of. Have you ever used a website or other service that required you to confirm your phone number by receiving a call and then entering a code given to you over the phone? Well that’s what we’re going to build. The concept is that a user fills out a generic registration form on your site and includes their phone number. Upon submission we will leverage Twilio to call the user and recite a 4 digit confirmation code that they will then have to enter in step 2 of the registration process. Upon validating the entered code from step 2 we will either send the user a SMS text message confirming a successful activation or display an error.

For the purposes of this example I am leveraging the CodeIgniter framework simply for the sake of development speed. The code that actually interacts with the API can easily be transplanted into any application and still work. When it comes to interacting with the API, Twilio has a number of client libraries to choose from. Our weapon of choice is PHP, so I will be using the PHP client library.

To make things a little easier I’m providing two downloads, one is the complete source code with all the code included. The other is just the framework preconfigured with the necessary libraries and helpers. This way, if you want to follow along, we won’t have to waste a lot of time setting up and configuring CodeIgniter.

Step 1 – Get a Twilio Account

Before you can access the Twilio API you first need to create an account to get access information. You typically have to pay to use Twilios service, but they do provide a free trial that comes with $30.00 worth of credit which you can use for the purposes of this example.

Visit https://www.twilio.com/try-twilio and fill out the provided form.

Your account dashboard is a collection of all of your account information in one easy to understand and access place. This is where you will find your Account SID and Auth Token. These are the two values you will need in order to make API requests. The dashboard also shows your account balance along with a rough calculation as to how that dollar amount translates into API requests. Your developer sandbox information is also displayed here, however we won’t be doing anything with the sandbox in this example.

The other thing you will need to do before continuing is to setup an outgoing called ID number within Twilio. For obvious reasons you can’t just go placing calls and sending text messages from any old number. You first need to enter and confirm a caller ID number within your account and then you can use that number when making API requests.

OK, so now that you have your API access information and have setup your caller ID your ready to jump in and get coding.

Step 2 – Setup

If you have not done so already, download a copy of the source code (blank or complete) and unzip the archive onto your desktop. For our registration example you will need to create a database and update CodeIgniters database settings (/application/config/database.php) with the appropriate access information. Once you have created your database, use the following SQL statement to create the one table we will be using.

CREATE TABLE `users` (
`id` int(10) unsigned NOT NULL auto_increment,
`fname` varchar(50) NOT NULL,
`lname` varchar(50) NOT NULL,
`email` varchar(200) NOT NULL,
`phone` varchar(12) NOT NULL,
`confirm_code` varchar(4) default NULL,
PRIMARY KEY  (`id`)
) ENGINE=MyISAM AUTO_INCREMENT=1 DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;

Now that you have created your database and updated the code you can upload everything to your development environment. You will notice that if you bring up the application in a browser you will most likely get an error. That’s because we haven’t created our default controller yet, but that’s the next step.

Step 3 – Create the Controller

Now that we’re up and running with our code and database we can get to coding. First thing to do is create a new controller called register.php in /application/controllers. When a user first visits our application we want to display our registration form so let’s setup our controller to do that by default.

class Register extends Controller
{
private $_account_sid = '';
private $_auth_token  = '';
private $_from_phone  = '';

public function __construct()
{
parent::__construct();

require_once(APPPATH . 'libraries/twilio.php');
}

// ------------------------------------------------------------------------

/**
 * Display app registration form.
 *
 * @access public
 * @return void
 */
public function index()
{
$temp_data = array(
'page_title' => lang('application'),
'content_main' => $this->load->view('register/index', 0, TRUE)
);

$this->load->view('_layouts/default', $temp_data);
}
}

The above code leverages CodeIgniters default controller function index() to automatically display our registration form when a user first visits our application. Now we need to create our registration form view file. Create a new folder in /application/views called register and a new file in that folder called index.php.

<h1><?php echo lang('application'); ?></h1>
<?php echo display_form_error(validation_errors()); ?>

<?php echo form_open('register/confirm'); ?>

<p><label for="fname">First name: <em>*</em></label>
<input type="text" name="fname" id="fname" value="<?php echo set_value('fname'); ?>" /></p>

<p><label for="lname">Last name: <em>*</em></label>
<input type="text" name="lname" id="lname" value="<?php echo set_value('lname'); ?>" /></p>

<p><label for="email">Email address: <em>*</em></label>
<input type="text" name="email" id="email" value="<?php echo set_value('email'); ?>" /></p>

<p><label for="phone">Phone number: <em>*</em></label>
<input type="text" name="phone" id="phone" maxlength="12" value="<?php echo set_value('phone'); ?>" /></p>

<p><input type="submit" value="Register now" /></p>

<?php echo form_close(); ?>

This view file contains just a simple four field registration form the user will complete to begin the registration process. Save and upload your changes and when you visit the application in a browser you should see the following form displayed. But before we go much further be sure to update the class variables at the top of the controller with your Account SID, Auth Token and caller ID number. Please note, the caller ID number should start with a plus sign (+), include the country code and have no hyphens.

Step 4 – Access the API

We now have our controller and registration form. You may notice however that when you submit the registration form nothing happens. The form is looking for a controller function called confirm(). This function will begin our user registration process by validating the form input, generating the users confirmation code and contacting the Twilio API to call our user and recite the code. Let’s go ahead and create this function now in our controller.

public function confirm($call = TRUE)
{
$this->load->library('form_validation');

$this->form_validation->set_error_delimiters('<li>', '</li>');

$rules = array(
array('field' => 'fname', 'label' => 'first name', 'rules' => 'trim|required|htmlentities'),
array('field' => 'lname', 'label' => 'last name', 'rules' => 'trim|required|htmlentities'),
array('field' => 'email', 'label' => 'email address', 'rules' => 'trim|required|valid_email|htmlentities'),
array('field' => 'phone', 'label' => 'phone number', 'rules' => 'trim|required|htmlentities'),
);

$this->form_validation->set_rules($rules);

if($this->form_validation->run())
{
// generate random 4 digit confirmation code
$confirm_code = rand(1000,9999);

// add new user to DB
$user_data = array(
'fname' => $this->input->post('fname'),
'lname' => $this->input->post('lname'),
'email' => $this->input->post('email'),
'phone' => $this->input->post('phone'),
'confirm_code' => $confirm_code
);

$this->db->insert('users', $user_data);
$user_id = $this->db->insert_id();

if($call)
{
// make call request to Twilio
$twilio = new TwilioRestClient($this->_account_sid, $this->_auth_token);
$result = $twilio->request('2010-04-01/Accounts/' . $this->_account_sid . '/Calls', 'POST', array('From' => $this->_from_phone, 'To' => $this->input->post('phone'), 'Url' => site_url('register/handle_call/' . $user_id)));
}

// display confirmation form
$page_data = array(
'user_id' => $this->db->insert_id()
);

$temp_data = array(
'page_title' => lang('application'),
'content_main' => $this->load->view('register/confirm', $page_data, TRUE)
);

$this->load->view('_layouts/default', $temp_data);
}
else
{
// display form errors
$this->index();
}
}

The majority of this code should be pretty self explanatory (for those familiar with CI) but let’s review just to be safe. The first 13 lines are all about validation. We are using CodeIgniters form_validation library to validate our form input and ensure we have valid data. If there are any errors we display the form again with error messages. On line 19 we create a random 4 digit number that we will use as our confirmation code. This is the code we will pass to Twilio to recite to our users and then test for in step 2 of our process. This will be stored in our database along with our other user data. Lines 21-31 handle the database insertion for our user record using CIs active record library. 33-38 are where we contact the Twilio API and make our request to call the user (I’ll review these lines in a moment). The remainder of the function displays step 2 of our registration form which is just a single field asking the user to enter their confirmation code. Before we forget let’s create this new view file called confirm.php in /application/views/registration.

<h1><?php echo lang('application'); ?></h1>

<h2>Confirm Your Identity</h2>

<p>You will receive a phone call shortly providing a 4 digit confirmation code.
Please enter that code below and click <strong>Confirm</strong>.</p>

<?php echo display_form_error(validation_errors()); ?>

<?php echo form_open('register/confirm_code'); ?>

<input type="hidden" name="user_id" value="<?php echo $user_id; ?>" />

<p><label for="confirm_code">Confirmation code: <em>*</em></label>
<input type="text" name="confirm_code" id="confirm_code" maxlength="4" value="" />
<input type="submit" value="Confirm" /></p>

<?php echo form_close(); ?>

As I mentioned above, lines 33-38 are where we actually make our API request to Twilio.

if($call)
{
// make call request to Twilio
$twilio = new TwilioRestClient($this->_account_sid, $this->_auth_token);
$result = $twilio->request('2010-04-01/Accounts/' . $this->_account_sid . '/Calls', 'POST', array('From' => $this->_from_phone, 'To' => $this->input->post('phone'), 'Url' => site_url('register/handle_call/' . $user_id)));
}

The first thing we do here is determine if we need to make the call or not by checking the $call variable passed to the function. I put this in here to avoid making additional API calls if the user enters a wrong confirmation code (this will make sense later on). Next we create a new instance of TwilioRestClient which is the PHP client library and pass it our Account SID and Auth Token for authentication. Using our new TwilioRestClient object, we make a request to the API using the request() function. This function takes 3 arguments: the path to the API method your calling, the type of request your making (POST, GET, etc.) and any data you are passing along to the API (as an array).

Something to make note of here is the path to the API method we are passing. In a rather odd turn of events, each API call must include your Account SID. I find this rather odd and verbose but alas it is required. There are ways to make this easier to use within your code by making a minor modification to their library, but I chose to keep things just the way they provide for the purposes of our example.

So we are calling the /Accounts/Calls API method and passing it a “From” phone number, “To” phone number and “Url” to handle the call. The “From” number is the phone number the call will be made from (your Twilio called ID number). The “To” number is the number Twilio will be calling. It’s worth noting that this number must inclue the country code and contain no hyphens. The code should probably include some sanitization to ensure this, but I kept it out for simplicity. Finally the URL to handle the call is where Twilio will look for instructions on what to do for this call. This is where we have to provide it with instructions using TwiML or Twilio Markup Language.

Step 5 – TwiML

There is an entire section of documentation dedicated to TwiML, so I don’t intend on spending a tremendous amount of time on it. Suffice it to say it is the XML format that Twilio expects when looking for instructions on what to do when placing a phone call. You have several options to choose from but all we care to do is place a call and read a script. Let’s go ahead and create a new function in our controller called handle_call() to generate the necessary TwiML.

public function handle_call($user_id = NULL)
{
if(!is_null($user_id))
{
$user = $this->db->get_where('users', array('id' => $user_id))->row();

// put spaces between code so Twilio will pronounce digits instead of the complete number
$confirm_code = '';
for($i=0; $i<=3; ++$i)
{
$confirm_code .= $user->confirm_code[$i] . ' ';
}

$script = 'Hello your confirmation code is ' . $confirm_code . '.';
}
else
{
$script = 'Im sorry but your account could not be verified.';
}

$twilio = new Response();
$twilio->addSay($script, array('loop' => 2));
$twilio->Respond();
}

The above code basically creates the following XML document.

<?xml version="1.0" encoding="UTF-8" ?>
<Response>
     <Say loop="2">Hello your confirmation code is XXXX.</Say>
</Response>

The first thing we do here is find our user based on ID in the DB. Next we take their confirmation code and put spaces between the numbers. Without doing this Twilio will pronounce the number as a complete number instead of digit by digit which would be a bummer for our users. Finally we put it all together in a script and call the addSay() function adding a loop attribute of 2 to make sure Twilio repeats the message twice. If you were to visit this function in your browser (/registration/handle_call) you would hopefully see the XML I provided above as an example.

Step 6 – Confirmation

We now have the majority of our application in place. The only thing we’re missing is the processing code to handle step 2 of our registration process. Let’s create a new function in our controller called confirm_code() to handle the final bit of validation.

function confirm_code()
{
$this->load->library('form_validation');

$this->form_validation->set_error_delimiters('<li>', '</li>');

$rules = array(
array('field' => 'confirm_code', 'label' => 'confirmation code', 'rules' => 'trim|numeric|max_length[4]|htmlentities'),
);

$this->form_validation->set_rules($rules);

if($this->form_validation->run())
{
$user = $this->db->get_where('users', array('id' => $this->input->post('user_id')))->row();

if($user->confirm_code == $this->input->post('confirm_code'))
{
$this->db->update('users', array('confirm_code' => NULL), array('id' => $user->id));

// make SMS request to Twilio
$twilio = new TwilioRestClient($this->_account_sid, $this->_auth_token);
$result = $twilio->request('2010-04-01/Accounts/' . $this->_account_sid . '/SMS/Messages', 'POST', array('From' => $this->_from_phone, 'To' => $user->phone, 'Body' => 'Hi ' . $user->fname . ', Thanks for activating your account.'));

$content_main = $this->load->view('register/account_activated', 0, TRUE);
}
else
{
$content_main = $this->load->view('register/account_error', 0, TRUE);
}

$temp_data = array(
'page_title' => lang('application'),
'content_main' => $content_main
);

$this->load->view('_layouts/default', $temp_data);
}
else
{
$this->confirm(FALSE);
}
}

The above code processes the confirmation code submission and checks to see if our user entered the correct code or not. If correct, we send the user a SMS text message using Twilio and display a view called account_activated.php. If incorrect, we simply display a view called account_error.php. Let’s create those two views now in /application/views/register.

<h1><?php echo lang('application'); ?></h1>

<p>Your account has been activated.</p>

<h1><?php echo lang('application'); ?></h1>

<p>Your account could not be verified at this time.</p>

The code for sending the text message is very similar to the block we used to make the phone call above.

$twilio = new TwilioRestClient($this->_account_sid, $this->_auth_token);
$result = $twilio->request('2010-04-01/Accounts/' . $this->_account_sid . '/SMS/Messages', 'POST', array('From' => $this->_from_phone, 'To' => $user->phone, 'Body' => 'Hi ' . $user->fname . ', Thanks for activating your account.'));

This time we are requesting the /SMS/Messages API method to send a text message and passing along “From”, “To” and “Body” as parameters. Just like above “From” is the phone number we are sending from (our Twilio caller ID number), “To” is the number we are sending to and “Body” is the actual content of the text message. It’s worth mentioning that text messages don’t require any TwiML instructions, only phone calls.

And there you have it. If you save and upload your changes you should now have a functioning example. Enter your phone number in the phone number field of the registration form (being sure to include the country code and no hyphens) and hit submit. You should shortly receive a phone call reciting your confirmation code. Enter that code in the confirmation code form and submit. You should then see the success message and receive a congratulatory text message.

Debugging

When I was first building this app I was not having much luck with placing phone calls. Twilio would call me but say there was a system error and then hang up (very frustrating). Come to find out that I had my site password protected and it couldn’t get to the handle_call() function for the TwiML instructions. The point of this story is I wouldn’t have been able to figure out what the problem was without the Twilio Debugger available through your Twilio account.

Conclusion

This is obviously not a complete and well polished application but it does illustrate some of what Twilio is capable of. Some possible enhancements to this code could include adding a country code drop down menu to the registration form so the user doesn’t have to enter it as part of their phone number, better phone number validation to ensure processing and maybe e-mail integration since we are collecting the users e-mail address. Feel free to experiment on your own and let me know how you make out by leaving a comment.

I know this was a long post but thanks for sticking with me. To learn more about what Twilios capable of, be sure to visit their documentation and implementation gallery.

CodeIgniter 1.7 Professional Development is a complete soup to nuts overview of the CI framework. Coming in at 10 chapters and around 260 pages this book is perfect for those new to CI. The book starts out with reviewing CIs MVC architecture, system libraries and form validation techniques. Then the author dedicates 2 chapters to user authentication and walks you through building your own authentication solution (includes details on oAuth and Facebook Connect). Application security, large scale development and extending CIs core is also covered in later chapters. All in all this book provides a very well rounded sampling of topics for complete newbies and experienced developers alike.

The one chapter I found most informative was chapter 8 Web Services. Like most developers, I have done quite a bit of work with consuming APIs but never had to write one of my own. Recently however I was charged with the task of writing an API that other developers would be interacting with and I had to stumble along and come up with my own solution. In chapter 8 the author reviews web services in depth and how to create your own REST service using CI. Very helpful for those new to that particular topic.

To be honest, when I first received the book I was a little disappointed. I’m not a CI beginner so I was hoping for a lot more advanced items, answers to questions I’ve been struggling with myself. But after spending some time with the book and writing this review I think I have changed my tune. The author spends ample time on the basic stuff but also finds time to touch on more advanced topics like user authentication (with oAuth and Facebook Connect), application security and web service development.

If you are a professional web worker who uses CI in your day to day activities then you should consider getting this book. There is a little something for everyone.

So far in this series I’ve discussed my typical application structure, configuration and helper files when developing apps using CodeIgniter (CI). In this final post I’ll review creating code templates for quick consistent development.

There is nothing really functional/technical about code templates. Templates are a set of simple files that have the basic document structure for the specified file (controller, model, library, etc.) that you use as a common starting point when creating any new file for your app. Your template should contain common elements to all files like the header comment block, class declaration, constructor, etc. There is no need to come up with your own standard when creating your templates because CI has a very nice style guide you should follow.

CI Style Guide

A few versions ago, CI added a page to their users guide entitled PHP Style Guide. In this section they do a great job at outlining the proper format when declaring variables, writing comments, naming files, etc. This is a great place to start when creating your templates. If you don’t already, you should think about getting in the habit of following these standards (even if you aren’t programming with CI) because they will help keep your code clean and consistent.

Template Files

Before I start coding my app I typically create a template file and place it in the controller and model folders. The templates are different of course, but they both create a nice starting point whenever I need to create a new file. It’s important to note that you don’t necessarily have to create physical template files to accomplish clean and well formatted code. Some tools like Coda and TextMate give you the ability to save bits of text and reuse them in your files. So you could create your header comment block and save it in your editor and just call upon that whenever you create a new file. Doesn’t really matter how you do it, it just matters that you do.

That’s a Wrap

OK… lecture over. That does it for the building applications using CodeIgniter post series. If interested, you can download a copy of the final CI install that we’ve created over the last 4 posts with helpers, code templates and all.

I hope by sheding some light on my process and explaining how I do things you came up with some ideas on how you can improve your own CI apps. As always, feel free to leave any questions or feedback as a comment below.

What belongs in a helper?

Something I’ve struggled with in the past is determining when a certain function or process belongs in a helper file and when it would be better off elsewhere. There is no cold hard rule for determining when something belongs in a helper and when it doesn’t but you do need to be aware of the following:

“Unlike most other systems in CodeIgniter, Helpers are not written in an Object Oriented format. They are simple, procedural functions. Each helper function performs one specific task, with no dependence on other functions.”
- CI Users Guide

This means that in order to access libraries and models within your helper functions you will need to get a CI instance:

$CI =& get_instance();

With the technicalities out of the way let’s take a look at the 2 helper files I’ve developed: display_helper.php and  flash_helper.php.

display_helper.php

A lot can be accomplished with CI’s built in templating but there are still some things that require logic and therefore fit nicely within a helper function. The display_helper.php file holds a number of common HTML display functions that I use throughout my program view files. To see what this file looks like, download an example. The functions in this file are pretty self-explanatory but I will briefly describe what each does below:

display_error()

The display_error() function displays a properly formatted HTML error message. I have this function setup so it can display 2 types of message: standard and form. When using the form_validation library I use the set_error_delimiter() method to wrap my error messages in list item tags and then display form error messages as unordered lists. So, I can easily accomplish displaying both types of messages using this function just by passing some variables.

display_msg()

This function just displays a properly formatted HTML message. This doesn’t necessarily need to be in a helper function because it’s so simple. But, the nice thing about having it here is if I ever decide to change the format of my messages I just need to come here in one place and make the update. So it consolidates my code nicely… but the same could probably be accomplished by using more generic CSS ID names.

req_field()

You should always identify required fields on your forms so users know what they need to fill in and what can be left blank. I’ve put the display of this flag in a helper function again to consolidate my code. As with the display_msg() function, if I ever decide to change my required field flag I just need to come to this one place and change it instead of going into all my view files and going a find and replace.

js_confirm()

JavaScript confirmation messages come in handy when you want to check with a user to make sure they are sure of something before you do it. You can accomplish the same confirmation by writing more PHP but that takes more work. The js_confirm() function, when used with the default CI URL helper anchor() function, displays a browser pop-up message with whatever text I pass to the function. If I’m in a hurry and don’t provide a message the function just returns a generic “Are you sure?” message.

Your display_helper file might look much different than mine, this is just an example of how I use it. But you want to be on the look out while your coding for repetition and little details here and there that might be changing down the road. If you can consolidate those things in a helper file you will end up saving a lot of time updating down the road.

flash_helper.php

CI added flashdata to it’s session library a few versions back and I for one was happy to see it. Flashdata allows you to pass messages for display between pages.  Simple status messages like “record added” or “record not found” can be placed in a flashdata variable and then displayed after the user is redirected to another page. A very handy tool for letting your users know the results of their actions.

While I do like this functionality, writing $this->session->set_flashdata(‘item’, ‘value’) and $this->session->flashdata(‘item’) every time I need to set or get something is a lot of typing. So the flash_helper is a pair of wrapper functions that handle the job of setting and displaying flash messages for me. To see what this file looks like, download an example.

display_flash()

The display_flash() function displays a selected flash message in a view file. Simply provide the name of the flash variable and it will display it in a properly formatted HTML div.

set_flash()

This function sets a flash variable with a value I specify. Since I use flash variables for a lot of different messages, which I may need to format differently, I also use this function to store some formatting data along with the message. That way when I display the message it is automatically displayed using the CSS style I intended.

The flash_helper file is based on the same concept that Michael Wales posted about a while back. I would link to the post but I can’t seem to find it anymore.

Last up: Code Templates

That wraps up the 3rd installment of this series. In the next, and final post, I’ll discuss creating code templates to help you maintain consistency between your files.

Config

All of CI’s configuration files are stored in application/config.

- config
— autoload.php
— config.php
— constants.php
— database.php
— doctypes.php
— hooks.php
— mimes.php
— routes.php
— smileys.php
— user_agents.php

The purpose of each file coincides with it’s name. To get us up and running we are only going to worry about autoload.php, config.php, database.php and routes.php.

config.php

The config.php file is the main configuration file for the framework. In this file you can control things like logging, character sets, extension prefixs, etc. The folks over at EllisLab have done a great job at commenting this file so I’m not going to go through the whole thing. The only thing I’m going to change here are lines 14 and 26.

Line 14 holds the full web path to your CI installation. In the past I used to type this in by hand until I had the need to write portable apps that could be distributed and installed without much configuration on the users end. Since then I have resorted to using this code I found on the CI wiki. By replacing line 14 with that code you can set this variable and forget about it. Wherever your program ends up this config variable will be set automatically so you don’t have to worry about it.

Line 26 of the config file holds the name of the index file. Since I use search engine friendly URLs where ever possible I just delete the value and leave it blank (just like the comment tells you to do).

autoload.php

Now that the config.php file is taken care of we turn our attention to the tools we need to build out app. What libraries, models, helpers, etc. are we going to need on a regular basis throughout the entire app? The answer to this question will probably differ based on what app your building, but I have found there are a number of common files I always load throughout any application:

Libraries – database, session

Helper – form, url, display, flash

Config – program

The libraries above, database and session, are the default CI libraries to handle database abstraction and user sessions (note, if your app doesn’t use a database consistently throughout the whole app you might not want to autoload this library). The form and url helpers are both default CI helpers but display and flash are two custom helper files I’ve developed to assist with some common tasks. I will discuss helpers in the next post. Finally, program is a custom config file that I create for all my applications which I will discuss shortly.

database.php

If you are app is interacting with a database then you need to update the database.php config file. This file stores the access information for the database or databases that your app will be interacting with. This file is pretty self-explanitory so I’m wont go to delve into it.

routes.php

The routes.php file allows you to define custom URLs and map them to specfic controllers and methods. This is a very powerful tool that comes built into the CI framework. The only thing we want to update in this file to get started is line 43. Right now it’s set for the default welcome message we saw before. I usually set this variable to home just because it’s pretty generic and tends to work well in URLs but you can set it to whatever makes sense to you and your app.

program.php

Now that I’ve discussed all the default CI files, I’m going to create a custom config file called program.php (the same one we auto-loaded above) and place it in the config folder. This file will store all the application wide configuration settings and information that I will be referring to both programmtically and manually. To see what this file looks like you can dowload an example for reference.

At the very least this file will always have 2 variables: ci_version and program_version. Both are pretty straight forward in purpose, ci_version stores the current version of CI that I’ve used to build the app and program_version is the current version of my app. I’ll typically call upon the program_version and display it in the footer of the app and knowing the version of CI running comes in handy when updating or making any framework modifications.

When building an app of any size you always want to build in a quick and easy way of taking the app offline. I accomplish this with the status variable. If the status is true then the program is online and everything is operational but if it’s false then things are offline. By creating a config variable for this I can easily refer to this flag throughout the program to determine whether or not input should be accepted and processed.

Another thing I commonly store in the program config file is e-mail settings that will be used whenever an e-mail is sent from the app. This commonly consists of the from and reply-to address and names. Again, by storing this information here it’s easily accessed whenever sending an e-mail.

Your program config file can store any type of system wide configuration information that your app will need to reference from many places. You could theoretically store this configuration information in a database but then you wouldn’t be able to take advantage of the native CI config tools available. In the end it’s up to you.

Next up: Helpers

That wraps up configuration. In the next post I will review some custom helper files I’ve developed and autoload in most of my applications.

When submitting sensitive information over the web it’s important to ensure that the requested page is being accessed via an HTTPS encrypted connection. I’ve come across some forms that don’t check whether a secure connection has been made or not. In other words, you can delete the S from HTTP and instead of redirecting the user back to the HTTPS connection the form is just displayed unsecured. This is a BIG NO NO… as a programmer you cannot rely on the visitor, or even other developers who would be linking to the form, to request a form securely. In this post I will review how you can ensure that your users are accessing certain pages using a secure connection.

The Server Superglobal

How can you tell if your user is requesting a certain page using a secure connection (HTTPS)? Enter the PHP server surperglobal.

“$_SERVER is an array containing information such as headers, paths, and script locations. The entries in this array are created by the web server.”
- PHP Manual (http://www.php.net)

There are 2 elements within this array that you can check that will tell you whether the user has made a secure request or not: https and server_port.

Programmer Beware

Something to keep in mind is that each web server will provide or not provide certain information in the $_SERVER array depending on their configuration. The PHP manual also points this out:

“There is no guarantee that every web server will provide any of these; servers may omit some, or provide others not listed here.”
- PHP Manual (http://www.php.net)

So I guess that brings us back to the original question: how can you tell if your user is requesting a certain page using a secure connection (HTTPS)? Of the 2 elements mentioned above, server_port is part of the CGI 1.1 specification so the chances are good that element will be available in most servers. You can check for the availability of the https element if you wish but you should also include a check of the server_port as a fallback.

The Code

There is a good code example in the comments of the PHP manual of a function that checks whether or not the user has made a secure request:

<?php
function isSSL(){

if($_SERVER['https'] == 1) /* Apache */ {
return TRUE;
} elseif ($_SERVER['https'] == 'on') /* IIS */ {
return TRUE;
} elseif ($_SERVER['SERVER_PORT'] == 443) /* others */ {
return TRUE;
} else {
return FALSE; /* just using http */
}

}
?>

This example function makes use of both the https and server_port elements of the superglobal array and also takes into account the different values that might be provided based on the web server. The only thing I will mention about using the server_port element is to make sure you know what port your server is using for HTTPS connections. I believe 443 is the standard, but ports can be changed so you just want to make sure you are checking the correct port for your server.

What about CodeIgniter (CI)?

If your programming using CI, you could certainly put the function above in a helper and call it whenever necessary. Or, a technique I’ve used successfully in the past, is to put the check in a custom library and auto load it. When you do it this way the connection is tested every time a page is loaded automatically without you having to make any additional function calls. And instead of returning TRUE or FALSE you can simply redirect the user to the requested page using HTTPS instead of HTTP which truly automates the process.

One thing that can trip you up when making secure connections using CI is the address you’ve entered on line 14 of application/config/config.php. If you enter just a static address starting with HTTP then HTTP will be used when calling any URL helper function like site_url() or anchor(). To avoid this issue,  you can replace line 14 with the following code from the CI wiki:

$config['base_url'] = ((isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] == "on") ? "https" : "http");
$config['base_url'] .= "://".$_SERVER['HTTP_HOST'];
$config['base_url'] .= str_replace(basename($_SERVER['SCRIPT_NAME']),"",$_SERVER['SCRIPT_NAME']); 

This code will automatically set the base_url config element so you don’t have to. This also comes in real handy when writing portable code that you want to distribute to other users or clients for installation on their own servers.

That’s a wrap

That does it for making sure your files are being accessed securely. If you have any questions or use a different technique for checking secure connections please share them by posting a comment.