Perch: from a(nother) Drupallers POV

As many of you may already know, I am a Drupal developer, andhave been for some time. I find it a really powerful CMS,I enjoy usingit, 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 useperch_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.

    <?php    PerchSystem::set_vars(array(      '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/PHPwill 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 thehas_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

include('../../../core/inc/api.php');$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 {  print "THIS APP HAS ALREADY BEEN ACTIVATED!";}

• 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 _config.inc 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

Conclusion

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 anyPHP 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.

• The move to PythonAnywhere
• Moving host to PythonAnywhere
• Basic theming of my Wagtail site
• Migrating my Drupal7 site into Wagtail
• Drupal 8 vdd and csv migration

• Apache
• PHP
• mySQL
• Perch