Using Perch with the Slim framework

February’s project for me turned out to be something completely different to what I had originally intended. In fact it wasn’t until I was most of the way through it that I realised it even was a 12412 project. It’s maybe skirting around the edges of learning a little, as it was working with two things I was already familiar with, but combining them in a new way has turned out to be a useful experience.

What faced me a couple of weeks ago was the build of a new site for the Sidekick Studios project League of Meals, supporting its pilot phase in establishing ‘cook clubs’ to bring older people together in a communal, social kitchen with the potential to support local communities and get people eating more healthily.

Working from UX sketches and an overall brand design we initially started to put the site together in WordPress but, as the type and layout of content we were going to be adding was still in a state of flux, I wanted something with a little more short-notice flexibility. Ideally, I wanted Perch.

What is Perch?

Perch is a lightweight content management system, running in PHP, which makes it really easy to make pages editable without giving over control of layout or templating. Unlike most CMSes, which use a page-based model, Perch works through defining content regions in positions the developer chooses which are then reflected in an admin view.

I’ve used it on a couple of sites in the last year and I really like its minimal approach – I’ve never been totally comfortable with the way that the likes of WordPress are contingent on creating a “theme” when what you actually wanted to build was a “website”. I understand why it does it the way it does, and for sites that are in that mindset it works well, but the smaller-scale projects I tend to do more often than not have minimal content management requirements or a design that is far enough away from the WordPress model to make it easier to start from scratch and wire in Perch.

However as the CMS doesn’t generate its own pages from a template*, you’re still stuck with the task of development of actual pages to put content regions in to. It might sound like a slightly backwards way of working but I wanted a way to eliminate, if not all, then at least most of the rigmarole of doing this. The Slim framework for PHP seemed like a good bet.

What is Slim?

The Slim framework is something I discovered during last year, after working on an ASP.net site with a RESTful HTTP router and wanting something similar in PHP. It is exactly that, the idea being that you define ‘routes’ which are available via GET, POST, etc and then a .htaccess rule rewrites these via an index.php file in the route of the website to display whatever templates you require.

require 'Slim/Slim.php';
 
$app = new Slim(array(
    'templates.path' => 'template'
));
 
$app->view()->setData('config', $config);
 
$app->get('/', function () use ($app) {
    $app->render('head.php');
    $app->render('get/home.php');
    $app->render('cta.php');
    $app->render('foot.php');
});
 
$app->run();

A very simple Slim app defining the homepage route for our site. When the user hits the root of the site (/) the templates listed in the callback function are rendered as that page.

In this way you can add and change routes quickly and easily without needing to maintain a directory structure of ‘real’ pages and chop and change files between them as the site grows more complex. With the front controller pattern, your page components live in the ‘templates’ directory and nowhere else.

The file structure of the project. Everything that will be output as HTML sits in the ‘template’ directory regardless of its eventual location.

This conflicts with the way that Perch works out of the box, which relies on picking up the location of the page a content region is in to give it a meaningful label in the admin view. However I was determined to use a HTTP router pattern given the fluid nature of the site’s content and set to trying to make them work nicely together.

Wiring them up

Actually I needn’t have worried too much. Perch worked immediately with the Slim-powered site – the only slight weirdness being that it couldn’t work out what page a particular content region was on due to all requests running through that root index.php file, and so lumped them into the ‘home page’.

The developers of Perch had in fact already anticipated this scenario, and there is a special work around for sites that use front controllers. By simply explicitly telling Perch, in each Slim route, what ‘page’ it is supposed to be on, the admin view corrected itself and harmony was restored. It’s necessary to give this page setting an index.php file, even though that file doesn’t technically exist – this is simply a quirk of Perch.

$app->get('/our-cooks', function () use ($app) {
    PerchSystem::set_page('/our-cooks/index.php');
    $app->render('head.php');
    $app->render('get/cooks.php');
    $app->render('cta.php');
    $app->render('foot.php');
});

A route with the Perch set_page method defined

One other problem was that the .htaccess file which makes Slim work in the first place was intercepting requests to the /perch directory where the admin interface lives and returning a 404 error – there was no route for it so Slim didn’t know what to do. To get around that I looked a few ways to modify the .htaccess file to ignore the Perch directory, but in the end found the simplest method was to add a further .htaccess file in that directory with the single rule ‘RewriteEngine Off’. Once this was done the Perch admin interface was back in business, and individual and shared content regions in the pages worked perfectly.

The League of Meals site

So that brings us to the League of Meals site. As well as the initial content pages, there was also a requirement for a simple blog for which the relevant Perch add-on was used. This does work more in the traditional page-based model, and to get this running in the Slim application I needed to both define the routes for the blog archive and posts – using a route parameter for the post slug – and also edit the default templates to link to these routes rather than Perch’s query string style navigation.

$app->get('/blog/:slug', function ($slug) use ($app) {
    $app->render('head.php');
    $app->render('get/blog/post.php', array('slug' => $slug));
    $app->render('cta.php');
    $app->render('foot.php');
});

The blog post route, using a route parameter – “:slug”, which becomes $slug in the template – to ensure the correct post is fetched from the database.

The final thing I wanted was a dynamic navigation which could understand the route of the page it was on, with a selected state where appropriate. To achieve this I defined, in the root index.php file, an array of URLs and labels which is looped through in the page head template to render the navigation. Also in the head template we’re checking the page route from the Slim class and doing some comparison to check if that item should be selected – i.e. if we are on its page. This took a little wrangling, as I couldn’t do an exact comparison due to the presence of blog post slugs, so I had to use PHP’s strstr function to try and find the nav item key (e.g. /blog/) in the page route (e.g. /blog/2012-02-21-see-what-happened-at-our-first-cooking-club). A side effect of this was that the home route (/) would always match so there needed to be a little extra logic for this case.

<?php
    $app = Slim::getInstance();
    $resource = $app->request()->getResourceUri();
?>

Finding out the current route from the Slim class in the page head

<nav>
    <ul>
    <?php
        foreach ($config['nav'] as $key=>$value) {
            if ($key === '/') {
                $class = $resource === '/' ? ' class="selected"' : '';
            } else {
                $class = strstr($resource,$key) ? ' class="selected"' : '';
            }
    ?>
        <li<?=$class?>><a href="<?=$key ?>"><?=$value?></a></li>
    <?php
        }
    ?>
    </ul>
</nav>

Rendering the navigation and checking selected state against the route

Conclusions

Matching Slim and Perch together is something I’d intended to try for a while now, and I’m glad it turned out to be fairly straightforward given the short duration of the project and that I had banked on this way being easier and quicker than WordPress. In fact we came in one day under budget on development, and had time to make sure the site design was implemented in a responsive way.

Would I do it this way again? On a site that needed to be built in PHP, absolutely! However I am hoping that a focus on Node during March will lead me towards a utopian land of Javascript everywhere, and my days building sites in this way are numbered.

* Yes there is a ‘pages’ app add-on for Perch, but this didn’t seem appropriate for the very different page layouts across the site and its frankly simple enough to not need it.