Skip to main content

CiviCRM developer secret handshake

I'm at a CiviCRM developer training and have to share my discoveries. Before yesterday, I always felt like a CiviCRM hacker, without really knowing why, and now I think I do. For me, the difference is between knowing a few tricks to accomplish what I want to do, compared with actually understanding the code as a whole and feeling like I could responsibly contribute stuff and not just cross my fingers that I'm not missing something important. So, no, it's not a secret handshake, but here's  what I've learned:

1. Dispatcher and permissions

In Drupal, we have a bunch of code called the "menu system" which takes care of (among other things, like the actual visible menu), how a particular url maps onto a specific piece of code to be executed - i.e. which callback function gets invoked. This mapping of urls to callbacks is implemented by modules in the hook_menu function and stored in a table that gets rebuilt when modules get added and rebuilt or the menu cache gets cleared. This function in Drupal also takes care of the top level of permissioning - i.e. who gets to call which urls.

CiviCRM, because it's CMS agnostic, doesn't use Drupal's menu for it's individual urls, but instead just exposes to Drupal a single callback path "civicrm" and then deals with the dispatching and permissioning itself.

So here's what I learned: the way CiviCRM implements dispatching and permissioning is similar to Drupal, but it's done via xml files rather than implementing a hook. So, dive into the CiviCRM code base, pick your favourite module (e.g. Events) and look in there for xml files. It's got a pretty obvious structure.

2. Module Extensions

CiviCRM now has a thing equivalent to a Drupal module, it's called a Module Extension.

"Equivalent to" is an expression that gets a lot of abuse by sales types, so let me be more specific: in Drupal, there are really three parts to "core", namely:
a) the really core essential stuff that mostly lives in the includes directory + the index.php file.
b) the modules that you can't disable
c) the other modules that are distributed with Drupal
What makes module development work in Drupal is the discipline this structure imposes on the code as a whole - even modules that you can't disable are built with the same tools as modules that you can contribute, the same hooks, etc. So, at least in theory, a contributed module can do things as powerful as the core.

What we get with a Module Extension is access to the same tools and structure that CiviCRM core is built with. Okay, maybe not quite, not yet, but that's the promise and I'm going to hold them to it.

What this means for CiviCRM developers is: your standard tools for customizing CiviCRM look like this:

a. Custom tpl and php directories - difficult to maintain, limited in what it can do and easy to implement, or difficult to go beyond the really basic stuff. In other words, a documented way to hack core. Roughly "equivalent" to using the theme layer in Drupal to do your customizations.

b. Drupal module - use the civicrm api to expose custom callback functions that  access the civicrm code, db, etc. A nice development environment, but also limited in how much it can sensibly accomplish. Also not portable to other CMSs. Feels kind of like throwing rocks, involves some crossing of fingers.

c. The CiviCRM module extension. Can now replace my big hacks that currently use a grab bag of 1. and 2. - makes them more easily shareable across installations and CMSs.

3. Development Tools

Okay, so we've now got access to the same mechanism that builds CiviCRM functionality (with the usual disclaimers), but we're not core developers so we don't know the code base as well. With Drupal we have the api documentation, books and other documentation. We don't have quite the same level of maturity with CiviCRM, but here's what I've found:

a. the api explorer. You get this automatically with your own civicrm installation, it's a bit beta, but a cool interface and has the basics. A real important difference with Drupal is that the actual api code is a separate, thin layer over the actual code, so most of the time you need to look at the core code to figure out arguments.

b. the core code. See it here:, it's linked with the warning "code level documentation".

c. the list of hooks. CiviCRM adopted Drupal's hook idea a while ago. See:

d. Eileen's civicrm_developer module (the civicrm version of the Drupal devel module). I'm going on hearsay from Tim and respect for Eileen's past work, but I doubt you'll be disappointed.

e. Tim's civix. This should almost be first on the list - it's module extension generator. The only non-obvious thing I ran into was that you first create the module extension, then you use a separate subsequent command to add stuff for different types of things you want your module to do. For example, if you just want to use the hooks to intervene on some existing pages, you can just use the basic scaffolding. If you want to create a new url with functionality, then you add in a "page". Yes Tim, it's documented, I just didn't read it carefully.

Conclusion: many thanks to Tim for explaining all this, and to Joe and Louis-Charles for getting this developer training to happen.

Popular posts from this blog

Me and varnish win against a DDOS attack.

This past month one of my servers experienced her first DDOS - a distributed denial of service attack. A denial of service attack (or DOS) just means an attempt to shut down an internet-based service by overwhelming it with requests. A simple DOS attack is usually relatively easy to deal with using the standard linux firewall called iptables.  The way iptables works is by filtering the traffic based on the incoming request source (i.e., the IP of the attacking machine). The attacking machine's IP can be added into your custom ip tables 'blacklist' to block all traffic from it, and it's quite scalable so the only thing that can be overwhelmed is your actual internet connection, which is hard to do.

The reason a distributed DOS is harder is because the attack is distributed from multiple machines. I first noticed an increase in my traffic about a day after it had started - it wasn't slowing down my machine, but it did show up as a spike in traffic. I quickly saw that…

CiviCRM's invoice_id field and why you should love the hash

I've been banging my head against a distracted cabal of developers who seem to think that a particular CiviCRM core design, which I'm invested in via my contributed code, is bad, and that it's okay to break it.

This post is my attempt to explain why it was a good idea in the first place.

The design in question is the use of a hash function to populate a field called 'invoice_id' in CiviCRM's contribution table. The complaint was that this string is illegible to humans, and not necessary. So a few years ago some code was added to core, that ignores the current value of invoice_id and will overwrite it, when a human-readable invoice is generated.

The complaint about human-readability of course is valid, and the label on the field is misleading, but the solution is terrible for several reasons I've already written about.

In this post, I'd like to explain why the use of the hash value in the invoice_id field is actually a brilliant idea and should be embrac…

Upgrading to Drupal 8 with Varnish, Time to Upgrade your Mental Model as well

I've been using Varnish with my Drupal sites for quite a long while (as a replacement to the Drupal anonymous page cache). I've just started using Drupal 8 and naturally want to use Varnish for those sites as well. If you've been using Varnish with Drupal in the past, you've already wrapped your head around the complexities of front-end anonymous page caching, presumably, and you know that the varnish module was responsible for translating/passing the Drupal page cache-clear requests to Varnish - explicitly from the performance page, but also as a side effect of editing nodes, etc.

But if you've been paying attention to Drupal 8, you'll know that it's much smarter about cache clearing. Rather than relying on explicit calls to clear specific or all cached pages, it uses 'cache tags' which require another layer of abstraction in your brain to understand.

Specifically, the previous mechanism in Drupal 7 and earlier was by design 'conservative' …