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!

What’s it about?

PHP5 Social Networking by Michael Peacock is a complete detail packed reference on how to build your own social network. Weighing in at over 400 pages this book isn’t a quick read but it has a wealth of information for those people looking for answers to common social network construction questions. Everything is covered from user profiles and groups to activity streams and events. You will even construct your own API.

The author starts off deconstructing a handfull of popular social networks down to their most basic features and functions. He then puts together a list of the features they all have in common and that becomes the feature list of the network you will build throughout the book. From that point on the author walks  you step by step through the creation of your own PHP framework and social network for dinosaur owners (yeah, I said dinosaurs). Finally, the book wraps up with some sections on hosting and maintaining your site as well as marketing it to your users.

Pros and Cons

I could have really used this book a year or two ago when I first started building myScoutPath. Everything is here to get you well on your way to a fully functioning social network with all the bells and whistles. The author does a good job at walking the reader through each solution and what they can do to improve them further. The examples are also clear enough where you can take what you learn and implement it with whatever framework or architecture you choose.

If they could improve anything I would say cut down on the code samples a little bit. Complete code libraries are printed throughout the book and I think it makes it unnecessarily big and potentially overwhelming to some. Maybe just provide excerpts from libraries within the book; users can view the complete source code later on if they wish anyway.

I don’t recommend sitting down and reading this book cover to cover unless you’re in for a nap (as with any technical book). Seek out the sections that you’re curious about the most and dig in. There’s a little something for everybody.

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.

Why is this important?

Some of you may be asking yourselves “what is Chris talking about? I’ve linked up my sign-up form so I’m done, right?” Unfortunately no, your not quite finished. The thing to keep in mind, when working with any kind of third party billing service, is that we’re talking about 2 separate and distinct systems. Your application is not aware of any changes/updates made in the billing system and vice verse.  This is a problem because if a users credit card expires in your billing system you need some way of notifying your application so you can suspend access. Or if your customer cancels their account in your application you need to be sure to update your billing system so they don’t continue to get charged.

This is the same concept when working with PayPal or any other 3rd party payment processor where the transaction takes place on their servers. We need a method for identifying accounts that have changed recently in our billing system so we can make any necessary updates in our application.

Listening for Changes

Spreedly is not shy about telling you when your customer data changes. In fact, when any of your subscribers change, Spreedly will POST a comma separated list of subscriber id’s (your customer id’s) to a URL which you specify. While tooling around your Spreedly accounts general settings you may have noticed a group of fields that start with “Subscribers Changed Notification URL”. This field is where you place the URL that Spreedly should use when POSTing changed accounts back to your application. This page can be part of your application or just a script that has access to  your database, but it needs to be there so that Spreedly has someone to talk to.

When any of your subscribers change within Spreedly, the application will send a POST request to an address you specify in your settings containing a comma separated list of IDs. These are the customer IDs of those subscribers who have changed. So this is Spreedlys way of telling you that account 2, 4, 6 and 8 have changed and you may want to check them out and update your DB accordingly.

As far as the necessary code, basically all we’re talking about is a method of a new or existing controller (using CodeIgniter) looking for the “subscriber_ids” POST variable and processing appropriately:

public function update_customers
{
$ids = explode(',', $this->input->post('subscriber_ids'));

foreach($ids as $id)
{
// get users data from Spreedly

// update your DB with new data
}
}

Pretty easy huh?

Why did this take so long?

This series set a new record for how long it’s taken me to wrap up a post series and I apologize for that. The reason though is because I’ve been taking a good long look at all the payment services out there (they’re popping up all over the place) and have determined that there are others I like better than Spreedly. So as I started to change my mind and focus I spent less time with this service and as a result was unable to share my knowledge as I had planned.

Currently Sign-Up-Sheet.com uses Chargify which won me over shortly after I started this series. However, I have since found another app that I like better called OpenGateway. The details as to why one is better than the other is for another post, but that’s what happened here. I got sidetracked by other options and simply was unable to regain my focus. Stay tuned for additional information on these payment options and let me know if you would like to see another series possibly on OpenGateway (which coincidentally happens to be built on CI) in the comments.

That’s all folks

And that does it for the Spreedly guide. My apologies for taking so long to complete but things got away from me a bit and one thing lead to another. If you think there is something I didn’t cover or have any additional questions please let me know in the comments.

Quick Disclaimer

Spreedly has a full featured API which provides people with programming experience a greater amount of integration flexibility, you just need to be conscience of the security liabilities involved. Links to 3rd party libraries and documentation can be found on the Spreedly website. To save on time and get this series wrapped up I will not be reviewing the API.

Your Sign-up Process

Before we can get to the Spreedly side of things we first need to define how our sign-up process is going to work. It is in our best interests, as the business owners, to make our sing-up process as quick and simple as possible so that more people will purchase accounts. Smashing Magazine published a post or two on sign-up form design a while back and I recommend you refer to those poses for further information on designing your process.

The one thing I will say, as it pertains to process, is to keep your sign-up form short and sweet. We will be redirecting users to our Spreedly accounts for the actual financial transaction so don’t worry about collecting any of that data (address, CC info, etc.) on your form. Just collect the items that are vitally necessary to get the user setup and worry about the non-essentials after they log-in for the first time.

Prerequisites

As I mentioned above, we don’t need to worry about collecting any financial information on our website because all the financial transaction stuff will be handled by Spreedly. However, there is one bit of data that we need to keep track of in order to redirect our users over to Spreedly and that is the subscription plan ID. The way I have chosen to handle this is by creating a table in my applications database to hold a copy of my subscription plans and each plan will include their Spreedly ID. Come to find out I needed to create this table anyway to track the limits of each subscription plan and hold my users to the limits of the account they purchased. So in reality I simply added an additional column to this table to hold the Spreedly ID.

Now you can chose to handle this any way that works for you and your application, but the bottom line is you simply need to be able to keep track of the subscription plans you have setup in Spreedly and the unique ID that has been assigned to them.

Constructing the Subscribe Link

So now that we have our subscription process down and have defined a place to keep track of our subscription plans and their IDs on the application side we can start looking at how exactly we will be linking to Spreedly.

Spreedly makes it somewhat difficult to find your subscription plan ID so you have to go looking for it. When you are logged into your account, click Plans to view your subscription plans and click the name to edit it. The edit screen, which is shown above, allows you to make changes to your subscription plan. If you look at the URL of this page you will be able to find the ID of your subscription plan. It’s the number displayed between “subscription_plans” and “edit”. That’s the number you will need to keep track of on your application side. You should also take  a look at their documentation links in the box on the right side of the page which also reviews linking to subscription plans from your application.

OK, so now that we have our subscription plan IDs we need to determine what the URL is going to look like.

https://spreedly.com/signupsheet/subscribers/84736/subscribe/1019/screen-name-for-84736

The URL displayed above is a sample URL for the basic subscription plan.  Let’s take a look at this URL piece by piece to figure out what we need to modify:

• https:// – very important for security purposes. Since we are working with credit cards plain old http is forbidden.
• spreedly.com – as I’ve already mentioned, all the financial stuff is happening on the Spreedly servers and this is the proof.
• signupsheet – this is your unique account short site name. This can be modified on the Site Details screen under Configuration.
• subscribers/84736 - the number 84736 is the ID of the user or account in OUR system. So this number if the first thing we will customize. I recommend setting it to the unique identifier you use in your application to identify your accounts or users. Whatever is the root account level entity within your application. Be sure not to omit the “subscribers/” either, this identifies the ID your passing to Spreedly.
• 1019 – this is the subscription plan ID. This is the next thing we will customize depending on the subscription plan our user is purchasing.
• screen-name-for-84736 – this is a unique user/account name that we provide Spreedly. This is the last thing we will customize. Set this to whatever you wish, perhaps some combination of account name and ID. Whatever will make it easy for you to identify the account within Spreedly by name instead of ID.

So that’s it. All URLs will be the same except for the 4 pieces identified above (in red): your short site name, an account/user ID from your system, the subscription plan ID and a user/account screen name. By customizing those segments you should now be able to successfully redirect your users to Spreedly for credit card processing.

Passing Additional Data

It’s also worth mentioning that you can pass additional data to your Spreedly subscription pages like the subscribers name and e-mail address. If you are already collecting this data on your applications sign-up form it would be helpful if these fields were already filled in on the subscription page. You can easily pass this data along to Spreedly by adding some GET variables onto the URL we constructed above:

• email=someone@someplace.com
• first_name=someone
• last_name=special

If we use the above GET variables to pass additional information to our subscription forms, then our final Spreedly URL is going to look something like this:

https://spreedly.com/signupsheet/subscribers/84736/subscribe/1019/screen-name-for-84736?email=someone@someplace.com&first_name=someone&last_name=special

That’s all there is to it. Once the user inputs their credit card information they will be redirected to the URL which you specified in the subscription plan settings. You can also modify this on the fly by providing an additional GET variable to your URL: return_url. Using that variable you can dynamically redirect the user wherever you specify upon successfully completing the payment process. This comes in handy if you need to pass any kind of dynamic information along with your user when they are redirected back to your site.

What’s Next?

If you followed along you should now be up and running with using Spreedly to manage your applications payment processing. You may however notice one thing is missing… we have no way of knowing whether the payment was processed successfully or not. The user simply gets redirected where we say and that’s it. We also have no way of knowing when their subscription expires (unless we track that ourselves). In the next post I will look at how we open up the lines of communication between Spreedly and our applications so that we know more about whose paying and whose not.

To program, or not to program that is the question

If you have spent any time on this site or on LOCCs you will have some idea of the projects I’m involved with. I developed BadgeTracker about 5 years ago, Sign-Up-Sheet.com followed about a year or two later accompanied most recently by myScoutPath and ScoutMailer. Contrary to most entrepreneurs I actually found my niche after I had developed a product. BadgeTracker was developed quickly and gained a following and after a little research I determined that the scouting industry was an attractive market to compete in so I selected it as my niche. The products that followed were aimed at scouts first and other groups second and I saw that as having great potential.

The problem here, that I didn’t realize until just recently, is that I had taken on too much. While I do outsource some work to contractors I am the only programmer, support person and business administrator I got. That means that while I’m answering support e-mails development stops. While I’m following up on overdue invoices no one is following up with the sales leads. While I’m programming no one is marketing. This lead to having 3 or 4 mediocre projects/products that were moving forward at a snails pace.

I had jumped head first into any idea that popped into my head, investing time and money to get it online and then ran out of resources to sustain, support and grow them. This lead to a great deal of frustration on my part because I was unable to work on the things I wanted to work on, investigate new ideas and opportunities or even write on my blog because I was stuck in the muck.

Wait… where’s the money?

Some of you may be wondering why I didn’t hire a staff or assistants to help maintain some of this. The short answer is the money wasn’t there. While the scouting industry may have looked like an attractive market at first, I have found over the years that working with non-profits is somewhat complicated and making a sale is difficult needle to thread. So while I was making some money it wasn’t enough to hire help or even leave my day job to dedicate more time. All of this of course contributed to more frustration on my part which is a very unproductive mind set to be in.

Recovery

What this all boils down to is not having a good vision and plan in place for the business. I should have slowed things down and investigated new ideas a bit more before jumping in a starting development and I should have finished one thing before starting another. I’m sick and tired of being sick and tired so I think it’s time for a new plan.

The one thing that all great businesses have in common is  great products. There are plenty of businesses out there with mediocre products and they come and go each year along with whatever is “in” at the time. I have decided that I’m not content with creating mediocre products… I’m out to create a great product and doing that requires focus. So I’ve come to the conclusion that I need to “reboot” and start 2010 with a new plan/vision. I think Dr. Charles Emerson Winchester III, from M.A.S.H, put it best when he said “I do one thing at a time, I do it very well and then I move on.” This probably means some of my many projects and ideas may be discontinued or abandoned to drift with the current but I’m confident that this is a better approach than what I have been trying.

One of the difficulties when selling software that needs to be installed is making sure the software is compatible with the users computer/system. I know this is supposed to be a responsibility of the user, but if they make a mistake they will be contacting you for support. Fever takes a unique approach to confirming users are installing the software on compatible machines. Shaun has created a process that links a compatibility check with his checkout/licensing process so that users can only purchase a license if they are installing the program on a compatible machine.

Before you can purchase a license you first download a small package that you upload to the location where you intend on installing the program. From there the package checks your systems compatibility and asks for database information (shown in the image above). Once entered, and after privileges have been checked, you are provided with a link back to the Fever site that populates the purchase form with a unique ID. This ID, I assume, matches your site with the compatibility check performed and then you continue with purchasing the license.

This process is genius! It allows the developer to prove the user is going to be installing the software on a compatible machine before selling them a license. I can image this process greatly reduces, if not eliminates, the support requests having to do with system compatibility and installation issues. Very cool idea!

For those viewers following along at home, if you look at the configuration page, I’m going to cover each section in reverse order wrapping up with setting up your subscription plans.

Site Details

The site details section is where, you guess it, you enter the details of the site you are going to be integrating with Spreedly. The information requested on this form is pretty straight forward so I’m just going to touch on 2 parts.

URLs

About half way through the form they ask for 3 URLs:

1. Subscriber Changed Notification URL

   Since you are using a system that is external to your application to handle payment processing you will have to work out some way to sync the two so your sure people have only those accounts they have paid for. That’s where the subscribers changed notification URL comes into play. When subscriber data within Spreedly changes, the service will POST a comma separated value list of subscriber IDs to the address you specify here. It then becomes your responsibility to process those changes and sync them with your application.

2. Individual user URL on your site

   This is the address that users visit to view their specific information in your program. Spreedly uses this address to redirect users back to your program from their update screen.

3. Subscription selection URL on your site

   This is that place in your program where users can upgrade/downgrade their account. Again, Spreedly uses this address to redirect users back to your program from their system.

I will come back to these URLs later in the series so go ahead and leave them blank for now.

API Authentication Token

At the bottom of the site details form you will find your sites API Authentication Token. This is the token you will use when interacting with the Spreedly API. Be sure to handle with care and keep it a secret… you can always generate a new one if you need to. Make note of this because we will be using it in the posts to come.

Manage Site Users

One of the really nice things about Spreedly is that you can add as many users to your account as you wish without hitting any limits. So, if your organization has a 10 person support/accounting team (wishful thinking perhaps) you can add them all with their own access information from the Manage Site Users section.

Payment Gateway

The Payment Gateway section is where you will go when you’re ready to take your site out of testing and into production. You will have to upgrade your Spreedly account from a test site to a production site and either sign-up for the monthly pricing option or bite the bullet and get a Kickstart package. For the time being, the page just displays some example CC numbers you can use to generate different errors.

Subscription Plans

Now to the important stuff! The Subscription Plans section is where you setup your applications different subscription plans and pricing. By default, Spreedly has setup one example plan to give you an idea how things work. I will issue one word of caution here, you CANNOT delete subscription plans. I hope this is coming soon, because I have made a mess out of my other account, but for right now it can’t be done. Just keep this in mind as you enter your plans.

I want to draw your attention to 2 pieces on this form:

Feature Level

The feature level is the name with which you will refer to the subscription plan through the API. You want to keep this simple yet specific so you can easily match it up with a subscription type. I typically just repeat the plan name as one word lowercase just to keep it easy.

Plan Type

The type of plan is where you can specify if this is a regular subscription, gift subscription or free trial. This really gives you a lot of options when setting up your applications pricing structure. You can set the amount of time each plan is valid for before charging the user again (number of days or months). You can also specify if you want to require auto-recurring purchases (you only accept auto-recurring payments) or not. The sky’s the limit!

That’s it!

After you play around with your settings and subscription types a little bit you will have a configured Spreedly test account ready to accept subscribers. In the next post I’m going to take a break from the Spreedly specific stuff for a little while and talk about planning your sign-up/checkout process and determining how that’s going to work with your newly configured Spreedly account.

What is Spreedly?

Aside from the best thing since sliced bread… Spreedly is a service that takes the hassle out of collecting subscription fees for web based services/applications. Developing applications that use 3rd party payment gateways and that sell recurring subscriptions is a difficult and often expensive undertaking. Spreedly simplifies the process by handling the complex task of subscription management and payment processing for you so you can focus your time and money on your product.

After configuring your Spreedly account and entering your subscription types and pricing scheme, the service will handle all the payment gateway interaction and user subscription management for you… no muss no fuss. Accepting payments literally becomes as easy as redirecting your user to a Spreedly URL and having them enter their credit card information. That’s it!!

Supported Gateways

It’s important to understand that Spreedly is not a payment gateway. Spreedly simply acts as the middle man between your application and your selected gateway using APIs. This means you will still need to find a payment gateway and merchant account (if necessary). The simplest, and cheapest, option is probably PayPal because it’s a gateway and merchant account all-in-one. But if that doesn’t work for you, Spreedly currently supports the following gateways:

• Authorize.net (Only US dollars)
• Beanstream (Only Canadian dollars)
• eWAY (Only Australian dollars)
• PayPal Website Payments Pro (also UK)
• PayPal Express Checkout (also UK)
  (does not currently support automatically recurring subscriptions)
• Sage Pay (formerly Protx)
• USA ePay (Only US dollars)

They are constantly adding new gateways to the service so be sure to visit their site for the most updated list. If you don’t see your gateway listed above the odds are good that they can add it for you. Just contact their support team and they will research what’s involved.

Pricing

Accepting credit cards online is an expensive proposition… that’s why I have avoided it up until now. There are bank fees for merchant accounts, fees for each transaction, monthly fees for the payment gateway, etc… not to mention the percentage of each transaction that certain parities take just because they can. It’s enough to make you dizzy!

The pricing for Spreedly is pretty straight forward:

$19 per month + transaction fees

• 3% on the first 50 transactions per month
• 2% on transactions 51 through 5000
• 1% on all transactions after 5000

The thing to point out here is that the Spreedly fees will be on top of whatever your payment gateway charges. In the end you are still probably looking at a decent sum of money… but odds are it’s still cheaper (programming included) than if you went it alone or with another service.

If there are too many monthly fees for you to handle, Spreedly also has another pricing option called the Kickstart package. For one single payment of $699.00 you can get a Spreedly account for life with:

• a frozen per-transaction fee of 1%
• no monthly fees
• and it never expires!!

It pays to keep an eye on the Spreedly site (and maybe follow their Twitter account) for special offers because when they first launched Kickstart the price was $499.00 for a limited time. So there are opportunities for picking up deals if you pay attention.

Account Setup

Now that you have a basic understanding of what Spreedly is, let’s go ahead and create a test account. Spreedly makes it super easy to get your bearings and see how the system works without spending any money. You can sign-up for a free test account (which gives you access to everything you need) and see if it will work for you. To create your account, visit https://www.spreedly.com/signup and fill out the form.

After signing-up you will be directed to your test site overview page (shown above). The overview page gives you a summary of your account in terms of transactions and subscribers. You can click around the interface if you like but it’s going to be pretty empty until we start submitting transactions (which we’ll get to later in this series).

That’s a wrap

That does it for the Spreedly intro. In the next post I will review how to configure your account and setup your subscription plans/pricing scheme.

I’m just getting started with Spreedly so stay tuned!