Skip to content

The codebase

This chapter provides a general overview of the codebase organisation.

Tip

In order to explore the directories inside the CiviCRM repository it is generally quickest to make a local clone of CiviCRM from GitHub, or better yet install buildkit.

Namespaces

Classes in CiviCRM must be placed in one of two folders:

CRM (e.g.: CRM_Core_Invoke) classes use PEAR-style class-naming conventions that were common up until PHP 5.2. Class names include underscores and MUST NOT use the PHP "namespace" directive. Use CRM style when creating classes that plug into existing CRM subsystems such as payment processors (CRM_Core_Payment) and reports (CRM_Report).

Civi (e.g.: \Civi\API\Kernel) "Civi" classes use PHP 5.3 namespaces. They MUST use the "namespace" directive. Namespaces are designated with "\".

Tip

The Civi namespace uses composer's PSR-0 autoloader. This autoloader does not support custom PHP overrides. Use Civi when creating new object-oriented subsystems (like \Civi\API).

Traditional CRM_* classes (DAO, BAO, Form, Page)

Historically, most code driving the functionality of CiviCRM was located in CRM_ DAO/BAO/Form/Page classes:

  • DAO (data access object) classes extended PearDB-DataObject, which allowed a database table to be accessed like a php object (e.g. $dao->fetch()). These php files used to be generated from an xml document. Historically each DAO file corresponded to an entity (table) and contained metadata about the entity (table name, a list of fields, indices, etc.).
  • BAO (business access object) classes extended DAOs, and added entity-specific functionality (e.g. creating event participants). These used to contain functions like create() and del() which mixed generic CRUD functionality with entity-specific logic.
  • Form objects extended Pear-QuickForm, called BAO functions to read/write data, and added extra user-facing logic (e.g. checking if an event was full before registering). Form elements were assigned to a Smarty template for display.
  • Page objects would fetch data and assign it to a Smarty template for rendering.

Although much CiviCRM core code still looks like this, a transition is underway to use newer patterns:

  • DAO classes have all been reduced to an empty stub. They now extend a class which provides the old methods for backward-compatibility. The new way to read/write an entity is via APIv4 or Civi::entity().
  • BAO functions are in a process of gradual deprecation. The new way to add entity-specific logic is via hooks or events.
  • Form classes are still widely in use, but Afform provides a new way to write forms.
  • Page classes are still heavily used, but some pages can be replaced with SearchKit Displays.

Schema

This directory contains entityType files; each declares an entity. For example the Activity.entityType.php file declares the Activity entity, defines its schema, and describes other attributes of the entity such as title, description, field metadata, etc. For details see the chapter on CiviCRM Entities.

Xml

This directory contains the menu (router) which maps urls to CRM form or page classes and controls access to these URLs using permissions.

Templates

The templates directory contains all the HTML for pages and forms. Directly inside the templates directory is a CRM directory. In general, all templates map to a form or page class. CiviCRM chooses a template for the form or page based on the class name.

For example, the class CRM_Member_Form_MembershipRenewal looks for a template in templates/CRM/Member/Form/MembershipRenewal.tpl.

Templates are written in Smarty, a common PHP template engine. Variables can be passed to smarty using $this->assign() which is available to all Form and Page classes.

Customising templates is discussed in more detail in the Page Templates chapter.

The API

The latest version of CiviCRM's application programming interface (APIv4) is located in the Civi/Api4 directory. See the APIv4 Usage chapter for details.

bin scripts

The bin directory contains a variety of scripts that can be run to carry out specific functions. Some of these scripts are run on a regular basis, for example the CiviMail 'send' and 'process' scripts. Others are run on a one-off or occasional basis, e.g. update geo-coding.

SQL

The SQL directory contains sql files that e.g. insert demo data. Most developers will not need to edit files in this directory.

l10n

This directory contains automatically generated localisation files. You should not need to edit this directory directly. You should instead use CiviCRM's online translation tool Transifex.

Composer

Most 3rd party libraries are included via Composer. PHP libraries are downloaded to the vendor directory, while most javascript libraries are (for historic reasons) placed in bower_components.

Packages

Older libraries that are not downloadable via composer are found in the packages directory.