On the back of a CIConf in London last month, I would like to delve a little into a common theme amongst CodeIgniter developers. Speeding up development through simple automation. To do that we’re going to take a look at the CodeIgniter Sparks project and how it can drastically speed up your development. To demonstrate, I will walk through building a little portfolio that leeches off the GitHub API.
But first, what is sparks?
Sparks is a package management system for CodeIgniter. It hosts ready-to-go user contributed code that you can pull into your projects. If you have acquired a game through Steam; installed new software with Homebrew; or sped up your work with a Ruby Gem, then you already know what a package management system can do for you.
Why not PEAR?
PHP has an existing package management system, PEAR. Ideally a framework specific package manager would simply wrap around the language equivalent. Unfortunately with PEAR’s odd approach to packaging that isn’t feasible. It is regretable that the PHP standard has not enjoyed the success that gems, easy_install, and npm have seen.
How do I get it?
The getsparks website has installation instructions. For demo purposes I will use the option that isn’t listed on that page: The CodeIgniter reactor team has been hard at work getting sparks into the core, so I’ll be working from the sparks branch on GitHub.
Let’s get started!
Find a calm area somewhere in your webroot, and run:
git clone -b feature/sparks --depth 1 git://github.com/EllisLab/CodeIgniter.git
This will do a shallow clone of the CodeIgniter Reactor repository and put us on the sparks branch. If you view the root of this new folder in your web browser, you should see the CodeIgniter welcome screen.
Next up, let’s find our first Spark. We can run sparks on the command line from the root of the CodeIgniter directory we just created. The command looks like this:
php index.php --spark <command> [arguments]
For example, to show a list of commands we can use:
php index.php --spark help
You can also replace—spark with -s if you don’t want to type it out every time.
In order to build this little portfolio site, we need to access the Github API. We know that the GitHub API is a RESTful api, so let’s see if we can find something to help us using the search command:
php index.php --spark search rest
You should see a list of packages. Scanning that list, restclient seems to fit the bill. Installing it is just as easy as finding it:
php index.php --spark install restclient
A bunch of output should spring up. The important lines are at the end. We can see that sparks installed the curl library dependency for us. We are also told what version of the spark we just installed. Sparks have versioning built right in, so you can have multiple versions of the same spark installed in parallel.
Time to try it. Open up application/controllers/welcome.php and load your new spark at the top of the index method:
$this->load->spark('restclient/2.0.0');
Once it’s loaded, we will do a test request to GitHub.
$user = 'github';
$this->rest->initialize(array('server' => 'https://api.github.com/'));
$repos = $this->rest->get('users/'.$user.'/repos');
var_dump($repos);
Sidenote: It returns false. This can happen on some local install, in particular MAMP, when there are certificate issues. If you’re seeing this, you can add the following in front of the get calls in this walkthrough:
$this->rest->option(CURLOPT_SSL_VERIFYPEER, FALSE);
So now we get data, but the output isn’t very pretty. So remove that var_dump and we will make use of a view instead. Rename the existing view to something more fitting (I like “home”). Then load it and pass along our repo data:
$this->load->view('home', array('repos' => $repos));
In that view we can now loop through our repos and output them in a pretty format. After taking a look at our previous dump, I decided to include the title, description, and a link to github.
<?php foreach ($repos as $repo):?>
<div class="project">
<h2><?php echo $repo->name?></h2>
<p><?php echo $repo->description?></p>
<a href="<?php echo $repo->html_url?>">View on Github</a>
</div>
<?php endforeach;?>
We are definitely getting somewhere. Now wouldn’t it be nice if we could also show off our awesome documentation right on our portfolio? Of course it would be. It’s usually a little more text, so we’ll start by adding a link to another page. Go ahead and add that to the loop in the view now:
<?php echo anchor('/welcome/docs/'.$repo->name, 'Documentation')?>
We are using the url helper here, so flip back to your controller and make sure it gets loaded it as well:
$this->load->helper('url');
While you’re there, create the controller method for this action:
public function docs($which) {}
GitHub has a nice convention where any README in the project root is show as documentation. A lot of these are written in markdown, so for this example we will try to look for a “README.md”. GitHub’s API can once again give us most of what we need.
$trees = $this->rest->get('repos/'.$this->user.'/'.$which.'/git/trees/HEAD');
I have picked up at the rest->get() call. The previous setup still needs to be run, but it is identical to what we had before. In my case I decided to add a constructor with any setup code.
We’re working with git and not a filesystem so the naming is a little strange, but a tree is basically a file. So we need to loop through all the files in the root and look for a README.md. Remember, you can always var_dump and double check your data. When I did this, I noticed that the API returns a new API url for the object data, so that is what I will store.
$doc_url = ‘’;
foreach ($trees->tree as $info)
{
if ($info->path == 'README.md')
{
$doc_url = str_replace('https://api.github.com/', '', $info->url);
break;
}
}
So now that we have the new api url for the readme, we can get the text for it as well. Note, that the content is encoded, so we have an added step:
$readme = $this->rest->get($doc_url);
$content = base64_decode($readme->content);
We’re almost there! We can stick that output into a view and it will work just fine:
$this->load->view('docs', array('content' => $content));
// view:
<?php echo $content?>
However, we really don’t want to show raw markdown to our visitors. Let’s go back to the command line and see what we can find:
php index.php --spark search markdown
The markdown spark looks perfect! Go ahead and install it.
php index.php --spark install markdown
Armed with our new tool, we can load up that spark, and render the parsed markdown:
$this->load->spark('markdown/1.2.0');
// in the view
<?php echo parse_markdown($content)?>
And there you have it!
Of course, we do not want to run API calls for every request when we put this site live, or we will be in trouble very quickly. So as a last step, you should cache these pages:
$this->output->cache(60*24); // cache for a day
Your finished controller should look similar to this: https://gist.github.com/2029827
And finally, thank you to the reactor and sparks team for the awesome work on this!
]]>
