Faisal Ahmed

One of the biggest entry barrier while trying to start development on Civi CRM will have to be the lack of clear documentation on how to get started. So, this is my take on how I got started with extension development in Civi CRM and the basic workflow. This writeup is for advanced users and assumes you have base idea on working with docker and drupal. I have not gone into too much detail of each and every process that is not related to Civi CRM to avoid diverting focus away from the subject.

Setup Development Environment

To get started you first need to have a working development environment for CivI CRM. The easiest way to setup a working environment is to use any one of the pre-configured options from https://docs.civicrm.org/dev/en/latest/tools/buildkit/. But personally I have found https://github.com/michaelmcandrew/civicrm-buildkit-docker to be the most easiest option to get started with. Ensure you have docker installed on your system, then run the following terminal commands to clone and setup the docker instance.

git clone https://github.com/michaelmcandrew/civicrm-buildkit-docker buildkit
cd buildkit
docker-compose up -d
docker-compose exec -u buildkit civicrm civibuild create dmaster --url http://localhost:8080

The above will get the base Civi CRM configuration setup and a instance running at http://localhost:8080. The whole dmaster instance files can be found at /build/dmaster folder.
Note: At the end of the configuration the system will show Drupal admin id and password along with other details of the dmaster instance on the terminal and you should copy and save it in a text file for future reference.

Setup Extension Directory

Ensure the extension directory is at root of the framework user. For our example its Drupal root. Drupal root at out dmaster instance is at /build/dmaster/ so we now need to create a folder for Civi CRM extension. Let’s create a folder called civiext , the name of the folder can be anything. Once you created the folder login to the civicrm admin at http://localhost:8080/civicrm/ using id demo and password demo and go to Administer > System Settings > Directories and set extension directory as /buildkit/build/dmaster/civiext/ ( best is to use /buildkit/build/dmaster/sites/all/modules/civicrm/ext/ as otherwise the unit tests generates error! )which is the absolute path of the folder we just created. Note: It’s vital you create the civiext folder at the root of the framework, otherwise the civix command does not work as it generates error saying failed to find bootstrap.inc for Drupal.

Generate Extension

The easiest way to generate extension is through civix tool. Following is how we first goto the extension folder and create a blank extension. One thing to note here is we are setting a environment variable just to be ensure civix knows where the civicrm.settings.php file is. Normally it’s at the /sites/default/ folder of the drupal installation. Here we just gave it’s absolute path. This is also required for civix to work.

cd /buildkit/build/dmaster/civiext/
export CIVICRM_SETTINGS=/buildkit/build/dmaster/sites/default/civicrm.settings.php
civix generate:module com.thephpx.demo

Once the above code are run in terminal it will create a folder called com.thephpx.demo in /buildkit/build/dmaster/civiext/ folder. First thing you do in the new extension is to update the info.xml file to replace all the FIXME string with your extension specific information. Then save the file and goto Administer > System Settings > Extensions , you will be able to see your demo extension showing in the extension list!

Generate Extension Entity

Sometimes you need to create custom entity for your custom extension. We again use civix for that! Following are the code that you execute in terminal inside the module folder to generate the entity.

cd com.thephpx.demo
civix generate:entity Demo

Now you will see new files being created specially in xml and CRM folder. But now you need to define the fields of your entity table in your xml/schema/CRM/Demo/Demo.xml file. Once you are done editing the file save it and run the following command.

civix generate:entity-boilerplate
civix generate:upgrader

These command basically generates new files and updates existing entity files based on your xml modifications. Now, you need to uninstall and enable your module again. You can do it via terminal by typing the following codes –

cv ext:uninstall com.thephpx.demo
cv ext:enable com.thephpx.demo

Now, if you place an adminer.php file and connect to the Civi CRM database with the configuration you saved at the beginning you should be able to see a new table called civicrm_demo in your table list. This basically sets up your entity and you are ready to use it. Naturally there are more to it, but you need to dig in to find those gems! Best way to learn in Civi CRM is to dig in other Civi CRM extensions on github and try things out from their code.

How do I override existing themes in Civi CRM using extensions

You can override existing themes by introducing the same theme file in your extensions templates folder following the same folder path. You must note, the suffix of the file must be extra.tpl. So, if I want to override the contact summary page we see that it’s coming from /CRM/Contact/Page/View/Summary.tpl file. So we create inside our extensions template folder the followign folder structure /CRM/Contact/Page/View/ then inside the View folder we place Summary.extra.tpl . What this will do is load the content of this file at the end of the Summary.tpl file. But the file must have valid smarty template engine compatible code inside it. The idea is to add html block at the end of the desired file and then move the html code block into place using javascript on page load.

How do I insert data using my newly created entity

The idea behind Civi CRM extension is to use hooks and API calls to update / insert new data. The com.thephpx.demo extension will have a demo.php file which is should be used as the base script for the extension. You should mention it as the <file> tag inside the info.xml. This file is where you can write your hooks that you can use to inject your custom code and call the entity via the API call to get / create / update entries. One easy way to find code on how to call the entity and relevant PHP, JS & Smarty code is to goto http://localhost:8080/civicrm/api/ and use the tool to find your Entity from the dropdown and select the appropriate method. The tool generates sample code for given parameters for PHP, JavaScript and Smarty.

End Note

While I have given the base of how you can solve basic starting workflow, to understand Civi CRM extension development you have to read through existing extensions in github and figure things out through trial and errors. There does not appears to be any easy way out apart from trying your luck in their chat or forum and wait for them to respond.