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

Confused by online payment processing? You're not alone.

In the old days during "polite" conversation, it was considered rude to talk about sex, politics, religion and money. You might think we're done with taboos, we're not (and I'll leave Steven Pinker to make the general argument about that, as he does so well in The Better Angels of Our Nature).

The taboo I'm wrestling with is about money - not how much you make, but about online payment processing, how it works, and what it costs. In this case, I think the taboo exists mainly because of the stakes at hand (i.e. lots of money) and the fact that most of those who are involved don't get much out of explaining how it really works - i.e. the more nuanced communications are overwhelmed by sales-driven messaging, and the nuanced stuff is either proprietary secrets or likely to get slapped down by the sales department.

In other words, if you want to really understand about online payment processing because you want to decide between one system and another, you'…

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…

drupal, engagement, mailing lists, email

I lived, worked and studied in Costa Rica from 1984 to 1989. Ostensibly, I was there to study Mathematics at the University, and indeed I graduated with an MSc. in Mathematics supervised by Ricardo Estrada (check that page, he even advertises me as one of his past students). And yes, I do have a nine page thesis that I wrote and defended in Spanish somewhere in my files, on a proof and extension of one of Ramanujan's theories. But mathematics is a pretty lonely endeavour, and what drew me back to Central America (after the first visit, which was more of an accident), was the life and politics. The time I lived there was extremely interesting (for me as an outsider, though also painful and tragic for it's inhabitants) because of the various wars that were largely fuelled by US regional hegemonic interests (of the usual corporate suspects and individuals) and neglect (of the politicians and public) - the Contra war in Nicaragua, the full-scale guerrilla wars in El Salvador and …