CiviCRM Extensions framework - taking off in 3.3

This blog post is outdated. For latest information about how to create extension, please refer to Extensions Wiki Page.

It had to happen sooner or later - CiviCRM is growing with with variety of functionality, where people can plug in their own, custom pieces and make CiviCRM more tailored to their needs. Most prominent examples at the moment include payment processors, custom searches and custom reports. Don't confuse it with "larger scale" customisation, like writing Drupal modules which - using API and hooks - modify CiviCRM behaviour. We're talking about well defined, self-contained pieces of code which throw in some useful functionality into your existing installation. As of now, it's a bit of a hassle to install them - you need to put files in proper places, register them using administrator section and so on: nothing extremely complicated, but also definitely not the easiest part of CiviCRM setup and configuration. More to that, some very useful extensions (like some payment processors) are shipped with vanilla CiviCRM, but not supported by core team, some  of them are not shipped, but available only from forums or issue tracker. In general - you can find a lot of useful things, it's just requires some effort.

So now, what if you could just install CiviCRM, than go to an "Extensions" admin page, review available pieces, pick what you need from the list and just click "Install" button? We felt tempted to make it happen and some time ago we started talking about such feature. Now it's time to start introducing it - CiviCRM 3.3 will provide the first pieces of more long term effort in making CiviCRM extensibility easier. Work is currently in progress, most of pieces are there already (expect first demo in a few days), but before pushing out the first version, we would like to get your feedback and/or constructive criticism on the path we're taking. During next few weeks, before we hit alpha with 3.3, I will be publishing blog posts describing different aspects of how our extensions will work. If you're interested in this topic, follow the Extensions category on the blog and be active in comments (and in other ways as well, but that's to be announced later on). :-)

Goals for the first phase (and a bit beyond)

What will you see in the first phase of building our extensions framework? In CiviCRM 3.3 you will see:

• extension packaging format for custom searches and payment processors (describing it below)
• simple user interface for manipulating exensions (install, deinstall, turn on and off)
• first take on custom report packaging

I suspect that whole 3.3 life cycle period will be mainly about gathering experience with with packaged extensions - in that sense it will be more of an experimental functionality. Old ways of installing payment processors, custom searches and custom reports will be still available. After this "trial period", as the number of packaged extension grows, we'll start eliminating pieces of old functionality, but backwards compatibility will be held over at least 1-2 versions ahead.

CiviCRM Extension info file

Here we go, let's go with introducing first, most fundamental concept of our extension framework. We need to know what given extension does, who wrote it, who supports it and quite a few other things. That's what info file is for. It's in XML format and it's relatively simple. Here's an example:

<?xml version="1.0" encoding="UTF-8" ?>
 <extension key="org.civicrm.activity" type="search">
  <callback>ActivitySearch</callback>
  <name>Activity Search</name>
  <description>
   This custom search allows to search through activities 
   and returns activities as results (not contacts as 
   regular search).
  </description>
  <url>http://civicrm.org</url>
  <license>AGPL</license>
  <maintainer>CiviCRM Core Team &lt;noreply@civicrm.org&gt;</maintainer>
  <releaseDate>2010-09-01</releaseDate>
  <version>1.0</version>
  <compatibility>
   <ver>3.3</ver>
   <ver>3.4</ver>
  </compatibility>
  <develStage>beta</develStage>
  <comments>For support, please contact project team on the forums. (http://forum.civicrm.org)</comments>
</extension>

Quick description of XML elements:

• extension - enclosing element: everything needs to sit inside of it. Attributes are:
  1. key: unique name of the extension (should match the name of directory this extension resides in). We're going with Java like reverse domain naming to make it easier with identifying unique extensions and giving developers more flexibility on providing different extensions.
  2. type: one of "search", "payment", "report" for now, meaning that this extension is - respectively - a custom search, payment processor or custom report.
• callback - the name of the class that should be called in order to run this extension. Following the namespacing convention in CiviCRM, it will also be the name of the php file. Above example means that the file $extension_dir/search/ActivitySearch.php should exist and contain Extension_Search_ActivitySearch class. Extension_Search part of the namespace is obligatory, the rest is under extension author's control.
• name - well, that one's easy. It's a name of the extension.
• description - easy as well.
• url - address to extensions website with documentation, more information, etc.
• license - the name of the license under given extension is offered.
• mainainer - self explanatory, hopefully. Email address inside required.
• releaseDate - date when given extension has been released on.
• version - version of the extension.
• develStage - if you want to push out you extension in unstable state, here's the opportunity to be sincere about it. Allowed values are: "alpha", "beta", "stable". Beta is the default if you don't define develStage - 'cause you must have been unsure, if you forgot to provide such crucial piece of information. :-)
• compatibility, ver - lists compatible versions. It cares only about first two elements of version name and ignores the rest to avoid the need for frequent updating. So if your extension is compatible with CiviCRM 3.3, also means it supports 3.3.beta4. However, if you state it supports 3.3.beta4 (<compatibility><ver>3.3.beta4</ver></compatibility>), it won't support any other version - no go on 3.3.1.
• comments - last one, the opportunity to say anything you want. :-)

Loving all the things localised, we've added that too. There is possibility to provide extension description in other languages - optional localisedInfo section of the info file does that:

 
<extension ...>
    ...regular stuff
    <localisedInfo>
        <pl_PL>
            <description>Opis po polsku.</description>
            <maintainer>Zespół CiviCRM &lt;noreply@civicrm.org&gt;</maintainer>
            <comments>Wsparcie dla tego rozszerzenia dostępne na forum CiviCRM (http://forum.civicrm.org).</comments>
        </pl_PL>
        <pt_BR>
            ...
        </pt_BR>
    </localisedInfo>
</extension>

It only supports name, description, maintainer and comments sections - all other extension information defined here will be ignored.

That's more or less everything about the info file. Got suggestions? Comments under this post await your voices. :-) Coming up next in a few days - step by step tutorial on packaging your extension.