You are here

Perch: from a(nother) Drupallers POV

Tuesday, May 12, 2015

As many of you may already know, I am a Drupal developer, and have been for some time.   I find it a really powerful CMS, I enjoy using it, and have learnt a lot over the years through using it and looking at all the other developers code within it.  I am with Drupal for the long game. 

That said, there are many situations when you might consider Drupal either unsuitable, or just overkill for the job at hand.  Some examples of this are small blog sites, retrofitting onto other frameworks, or design-led projects (eg. the css is done in purecss or something nice and lightweight, which we want to keep clean).  For these sorts of projects, the go-to-CMS for some years has been wordpress, which I am not a fan of.  There are lots of talks of it being easy to use, and it can be, but more often than not, it is just frustrating for me.  And so, enter Perch.

Please note, what I talk about below are my learnings over a 2 week project, I may have learnt some bad habits, but hopefully it is still useful to someone.


What is perch?

Perch labels itself as - The original “really little CMS”.  And it fulfills this title nicely, the code footprint is much smaller than many other systems, the barrier to entry is relatively low for both content admins and/or fresh faced developers, and the capabilities out of the box are also small (which is certainly not a bad thing - too often do we get over engineered functionality which we don't want or need).  The main area it does not meet this saying is the amount of code required to write 'addons' which I will go into later.  I expect an addon to be a simple object which you add a few pieces to, and enable UI based things you want to resuse from core.  Instead you end up creating several files in various nested folders, although the content of these files can be reduced drastically, there is still a lot of creating multiple objects as opposed to just when that you use called $PAGE or suchlike.  Still though, this is a minor gripe, which I even ignore myself when I rant.

I am sure that if you have looked at Perch, you have noted you need to pay for it.  I am personally used to open source projects which are developed by the community, so was not 100% down with the idea of paying for a PHP application, but wanted to give it a go, and I must say, it works well.  The cost of a developer license is about £60 (once you include VAT) and that is a one off fee which is made worth it just by the support you get online.  With most open source projects, unless you were asking an 'on-topic' question, or knew someone in the know, you could be waiting days/weeks to get help.  But on the perch forum, the 2 core developers are darting around answering questions, usually in a matter of hours, but I have never had to wait more than a good nights sleep for an initial reply to my questions.

One other thing to note is that there are 2 Perch products:

  • Perch - a nice simple CMS which is great for applying CMS capabilities to an application which has been built already.  So say adding to some HTML, or an MVC application.  You can still write custom add-ons to do pretty much anything you need, and as it's PHP you can add things to it.
  • Perch Runway - The main advantages of this are some out of the box extras useful for performance (eg. CDN or varnish integration), but also it is the best choice when you are having Perch owning a whole site, creating pages more than just the basic blog, a little more like Drupal can.

In my opinion, the regular Perch is the exciting one where it is at, it still works on PHP5.3 (runway requires 5.4) which is great for old/budget hosts.  But also, it does what you want from a simple framework, otherwise you may start to think that Drupal could be a fair alternative to Runway (especially when you consider scope creep on those sorts of projects).  Runway is a little more expensive then regular Perch too, and also note that the developer license is a runway license, so you will have to develop against runway even if you are developing for regular perch.  It is unlikely to be too big an issue, but please check the capabilities of your versions of Perch before committing too much.

For reference though, there is a nice comparison page showing the features for each


Basic Perch usage

Ok, so first you need to get Perch installed.  Just login to perch, get your access key and download the application code.  Then you drop the folder into your site (eg. at /perch) and then go to /perch/setup in a browser.  From there you get some fields to fill out (all run of the mill stuff), once you have done that successfully, you will have a working perch setup ready to use.

So, what do you need to do?  The first thing will be to add 'perch' capabilities to a page.  This line does nothing by itself, but gives you access to everything you will need:

<?php include('perch/runtime.php'); ?>

Next you will need to choose which content you want to be editable, generally you can do that with a nice simple line like below.  Once you visit that page for the first time, it will add the item to your perch admin UI so you can choose the content type, and insert some content.

<?php perch_content('Intro'); ?>

Sometimes this may not work in the way you want it to, for example when retrofitting an MVC application because all pages worked via a single php file, making all the content confusing and hard to find.  What I found was a really nice way of working around this was to use perch_content_custom() instead.  This allows you to pass in a custom template file full of settings and placeholders, it also allows you to set a page name for the admin UI and pass in variables to use in the template.  Just pop the below code onto your php page, and then create page.html and place inside /perch/templates/content/ and insert the various perch placeholders to use.

      'postcode' => trim($postcode),
    perch_content_custom('Registration (Fareshare) Step2', array(
      'page' => 'This is page1',
      'template' => 'page1.html',

In my experience, there are some key things to know about the placeholders.  First, at their most basic, they are just a type and an id

<perch:content type="text" id="some-content" />

But if you want to use the vars you passed in, just replace the id with the array name.  You will also want to change the type to hidden

<perch:content type="hidden" id="sdata" />

One other useful thing, especially if you are planning with a pre-existing app is that you may want to pass html in as one of the vars.  If you do this, simple set encode to false, otherwise it will render the HTML as text

<perch:content type="hidden" id="sdata" encode="false" />


Extending Perch

Ok then, you have some content appearing in the CMS, and in a lot of cases, this may be all you need.  But is not all you are able to do.  For those that have used Drupal and it's concept of modules will be able to adapt to the idea of Perch 'addons'.  So, if we want a new piece of functionality we can download one of the core addons, or develop your own.  If you are going to develop your own, go grab the example addon which is on the perch website, as it is very handy to see some of the concepts used.

But what if you have (as in my case) inherited an MVC application, and you wanted to also manage the content in one of it's mySQL tables that already exists.  For this, I created a nice addon using the example addon and extended/edited this accordingly.  Sadly though, Perch can only talk to tables using the same prefix as perch is using.  So you may have to rename the table OR create a mySQL view to map the original table to a table with the required prefix.  I did the latter here, and it worked perfectly, it allowed reading and writing aswell, which wasn't entirely expected beforehand.  In doing things this way, we have a nice object for the content we will be editing, and a really good UI to do things.

There are also times where you don't need to edit, and maybe don't want to mess with a view.  You can of course create more of a wrapper addon and run regular PHP/mySQL queries inside of it.  You should though use the variables defined in your /perch/config/config.php file for reliability though.  Writing your custom mySQL/PHP will of course mean you don't have access to some of the nice free stuff you get when you use the main Perch API, but it can help if you just need something done quick, or maybe something that is very bespoke such as a really complex pivot query with exports and security checks.

Of course, there are some more very cool useful things you may want to use, so here are a few quick pieces of functionality and tips you might want to use:

  • Objects - Perch is built on a several objects, and these objects may not be easy to know that they exist, but there are a couple that are there for free which you may want to use such as $CurrentUser and $Perch.  Others are quick to make such as the oft used $API, $LANG, $FORM, and $HTML
  • Priviledges - You can create priviledges inside your activate.php file, but be aware this file will need to be run either manually or by the system.  You can then test these priviledges with the has_priv() method on $CurrentUser  Also, you will want to ensure everything is wrapped in an if conditional of some form to stop activation running twice.  For example I was just checking to see if a piviledge existed by running the below
$API  = new PerchAPI(1.0, 'fareshare_reports');
$UserPrivileges = $API->get('UserPrivileges');
if(!$UserPrivileges->get_one_by('privKey', 'test-addon.create')) {
  // This module is not yet installed
  $UserPrivileges->create_privilege('test-addon.create', 'Test permission');
} else {
  • Creating a form is really simple once you get the basics in play, so use it.  Just create your form object $Form = $API->get('Form') then add any require_field() calls and add all the fields you might want.  Just remember to set require_field() before you add your fields, otherwise it doesn't work.
  • Cheat - It's not really cheating but here is a nice cheatsheet from grabaperch
  • Modify the UI - Do you want to change how the UI works, you can.  I had to ask on the forum, but you can just add a css file into /perch/addons/plugins/ui/ and also refer to it from inside the file in there.  Be careful not to break the UI of other pages, but you should have the classes/ids you need to theme the UI however you need
  • dashboard - Perch has a nice dashboard which you need to turn on in the sidebars settings.  Once there, your addon just needs to add a dashboard.php file and you can add things to that page quickly and easily.  I mainly use it as a splashboard for admin links, but there is no reason you couldn't add data and graphs, or anything else if you wanted an intro video or something


Some gotchas

  • The API is there to help, so try not to steam in too much.  Also, the forum is really friendly, so come up with your plan, then anity check it with your peers
  • Don't just start your addon and enable it.  Remember that activate.php should only really run once, therefore once chance to add your permissions.  Of course, you can tweak this to run as often as you want, but still, planning is good
  • Check PHP versions, as Perch Runway requires PHP 5.4 whereas the regular version only needs PHP 5.3



I really like Perch, and it is likely now going to be my go to CMS for lightweight and non-Drupal projects.  It's as clean as you want it to be, and gives you a world of flexibility to get some good and reliable CMS functionality into nearly any PHP project.  There are areas I could see it improving, but so long as the goal remains to keep it small, and the improvements allow us to keep our code even smaller (eg. when making addons), then that will be great.  We all know Drupal is going down a very complex, but powerful route, I therefore enjoyed Perch for it's focussed objective of being small and easy to integrate, and so long as it continues with this mantra, then I will likely keep using it.


Blog & News

Monday, March 7, 2016

Okay, I know it is awful practice to put 2 things into one article, but I didn't want to write two tbh, so I will keep this tidy, and you can grab out what you need.


Subscribe to Blog & News


Cultivating a better future, with the seeds of better websites

For several years I have evolved through one of the largest media charities in the UK to the role of Senior developer.  I loved it there, but have to stepped out on my own as a freelance developer.

My main skills are with the Drupal CMS, developing code for it, ensuring standards through projects (whether that design, development, or planning), and leading teams to build applications they can be proud of.

Digital Consultancy, Web Development and Project Architecture are where I try to focus my skills, supporting my passion and desire to create stunning websites on time, in budget, and meeting your objectives.

To build a powerful web presence, I combine my creative, technical, and managerial experience (alongside a good splash of passion) which I have cultivated over 10 years in the industry, creating websites people want to shout about.

More on how I can help