edit

info.xml

Every CiviCRM extension must have an info.xml file within it to provide information about the extension. This page is a reference for the schema of the info.xml file.

Typically, you'll begin by running civix generate:module and civix will create a basic info.xml file for you. Use this page to learn how to customize that file.

Example

Here is an example of a full info.xml file from CiviVolunteer.

<?xml version="1.0"?>
<extension key="org.civicrm.volunteer" type="module">
  <file>volunteer</file>
  <name>CiviVolunteer</name>
  <description>The CiviVolunteer extension provides tools for signing up, managing, and tracking volunteers.</description>
  <license>AGPL-3.0</license>
  <maintainer>
    <author>Ginkgo Street Labs; CiviCRM, LLC; and the CiviCRM community</author>
    <email>inquire@ginkgostreet.com</email>
  </maintainer>
  <releaseDate>2016-12-06</releaseDate>
  <version>4.6-2.2.1</version>
  <develStage>stable</develStage>
  <compatibility>
    <ver>4.6</ver>
    <ver>4.7</ver>
  </compatibility>
  <comments>
    Developed by Ginkgo Street Labs and CiviCRM, LLC with contributions from the community. Special thanks to Friends of Georgia State Parks &amp; Historic Sites for funding the initial release, and to The Manhattan Neighborhood Network for funding the 1.4 release.
  </comments>
  <civix>
    <namespace>CRM/Volunteer</namespace>
  </civix>
  <urls>
    <url desc="Documentation">https://docs.civicrm.org/volunteer/en/latest</url>
  </urls>
</extension>

Changelog

CiviCRM Version Description
5.0.0 <ver> tags now imply forward compatibility. (e.g. an extension declaring <ver>5.1</ver> is displayed on 5.2, 5.3 etc. but not on 5.0.) Because 4.7.x and 5.x are substantively the same series, <ver>4.7</ver> implies forward compatiblity with 5.x.
4.7.27 Added <requires> and <ext>
4.5 <develStage> is not always required; when using civicrm.org's automated release management, this value is inferred from the version; for manual or private releases, the field should still be defined.
4.2 Most extensions should be packaged as generic module rather than type-specific extensions.
4.2 <downloadUrl> is optional for ordinary development; when using civicrm.org to distribute extensions, the <downloadUrl> will be specified when announcing the release on the website
4.2 <downloadUrl> can point to auto-generated zipballs on Github.com
4.2 Introduce stable support for generic modules.
4.1 Introduce experimental extension-type for generic modules.
3.3 Introduce extension-types for payment-processors, report-templates, and custom-searches.

Elements

Here we describe all the elements acceptable within the XML file. They are presented in alphabetical order, but note that the root element must be <extension>, so you might wish to begin reading about <extension> first.

<author>

  • Containing element: <maintainer>
  • Description: Name of the person and/or organisation maintaining the extension
  • Contains: text

<civix>

  • Containing element: <extension>
  • Description: Used to store settings which civix reads and writes
  • Contains: elements

Elements acceptable within <civix>

Element Acceptable instances
<namespace> 1

<classloader>

  • Containing element: <extension>
  • Description: Specifies the namespace and file-path of classes to add to the classloader.
  • Contains: elements

Elements acceptable within <classloader>

Element Acceptable instances
<psr4> 1+

For example, if you want to write PHP classes in the Civi namespace and autoload those classes within your extension, you'll need to use the following XML:

<classloader>
  <psr4 prefix="Civi\" path="Civi"/>
</classloader>

<comments>

  • Containing element: <extension>
  • Description: A long description of the extension that will display to the user before installation.
  • Contains: text

<compatibility>

  • Containing element: <extension>
  • Description: specifies the versions of CiviCRM with which this extension is compatible
  • Contains: elements

Elements acceptable within <compatibility>

Element Acceptable instances
<ver> 1+

<description>

  • Containing element: <extension>
  • Description: A brief (one sentence) human-readable description of what the extension does
  • Contains: text

<develStage>

  • Containing element: <extension>
  • Description: development stage
  • Contains: text
  • Acceptable values: stable, beta, alpha
  • Notes:
    • If you want your extension to be available for automated distribution, it must be marked as stable.
    • If you use civicrm.org's automated release management (based on git tags), the <develStage> value will be determined automatically by searching for "alpha" or "beta" in the version.

<downloadUrl>

  • Containing element: <extension>
  • Description: The url to the zip file with your extension.
  • Contains: text

Deprecated

<downloadUrl> was deprecated in CiviCRM 4.2

<email>

  • Containing element: <maintainer>
  • Description: The maintainer's email address
  • Contains: text

<ext>

  • Containing element: <requires>
  • Description: Specifies the unique name of one extension on which this extension is dependent.
  • Notes:
    • It is not currently possible to specify versions in these dependencies.
    • See <requires> for more details about extension dependencies.
  • Contains: text
  • Example: org.civicrm.shoreditch
  • Added in: CiviCRM 4.7.27

<extension>

  • Containing element: None. This is the root element of info.xml.
  • Description: Describe one extension
  • Contains: elements

Attributes acceptable for <extension>

Attribute Description
key The unique name of the extension, e.g. org.example.myextension. It should match the name of directory this extension resides in. Read more about choosing a name.
type One of module, search, payment, report.

Elements acceptable within <extension>

Element Acceptable instances Acceptable
when
<civix> 0 or 1
<classloader> 0 or 1
<compatibility> 1
<comments> 0 or 1
<description> 1
<develStage> 0 or 1
<downloadUrl> 0
<file> 1
<label> 0 or 1 <extention type="search">
<license> 1
<maintainer> 1
<name> 1
<releaseDate> 1
<requires> 0 or 1
<urls> 1
<version> 1

Legacy extensions: Payment, Report, Search

Historically, CiviCRM v3.x-4.1 strictly categorized extensions as "Payment", "Report", or "Search" -- which required additional XML tags. These have been phased out during the 4.x cycle, and they are no longer documented here. For archival documentation, see CRMDOC46: Extension Reference.

<file>

  • Containing element: <extension>
  • Description: The name of the file to invoke when the extension is executed (not including .php file extension) This file must be present in the root of the extension .zip file / in base directory of the extension
  • Contains: text

<label>

  • Containing element: <extension>
  • Description: For search extensions, this element is used as the menu item text on Custom Searches list
  • Contains: text

<license>

  • Containing element: <extension>
  • Description: The name of the license under which your extension is offered.
  • Contains: text
  • Example: AGPL-3.0

Tip

For more information on what license to choose, see CiviCRM licensing page. For technical details on how to identify a license, see SPDX License List

<maintainer>

  • Containing element: <extension>
  • Description: Used to store information about the person (or organization maintaining the extension)
  • Contains: elements

Elements acceptable within <maintainer>

Element Acceptable instances
<author> 1
<email> 1

<name>

  • Containing element: <extension>
  • Description: Human-readable name of the extension. It can contain spaces
  • Contains: text

<namespace>

  • Containing element: <civix>
  • Description: The PHP namespace that civix uses when generating code
  • Contains: text
  • Example: CRM/Volunteer

<psr4>

  • Containing element: <classloader>
  • Description: Specifies the namespace and file-path of classes to add to the classloader in PSR-4 Standard.
  • Contains: nothing — should be empty

Attributes acceptable for <psr4>

Attribute Contains Purpose
prefix text Namespace of classes to add
path text Directory path to classes to add

<releaseDate>

  • Containing element: <extension>
  • Description: The release date of the current version (use YYYY-MM-DD format)
  • Contains: text

<requires>

  • Containing element: <extension>
  • Description: Used to to specify other extensions on which this extension is dependent.
  • Contains: elements
  • Example:

    <extension key="org.civicrm.foo" type="module">
      <requires>
        <ext>org.civicrm.bar</ext>
      </requires>
    </extension>
    
  • Notes:

    • For example if org.civicrm.foo requires org.civicrm.bar, then CiviCRM core will not enable org.civicrm.foo unless it can enable org.civicrm.bar first.
    • Also, if org.civicrm.bar depends on other extensions, the process will continue recursively, always by enabling the dependencies first.
    • CiviCRM core does not download the dependencies — it only enables them. The user must first download the dependencies.
    • Currently, <requires> is only for managing dependencies on other extensions (not other libraries).
  • Added in: CiviCRM 4.7.27

Elements acceptable within <requires>

Element Acceptable instances
<ext> 1+

<url>

  • Containing element: <urls>
  • Description: Represents one URL which is associated with this extension. For example, the URL of the extension's documentation.
  • Contains: text

Attributes acceptable for <url>

Attribute Contains Purpose
desc text A short (usually one word) description of the URL. This will display next to the URL in the CiviCRM UI before users install the extension. For example "Documentation" and "Support" are common values.

<urls>

  • Containing element: <extension>
  • Description: Stores all the urls that you think are appropriate and necessary for users to find out more about what your extension does, additional documentation, etc.
  • Contains: elements

Elements acceptable within <urls>

Element Acceptable instances
<url> 1+

<ver>

  • Containing element: <compatibility>
  • Description: a version of CiviCRM with which this extension is compatible; expressed as two digits
  • Contains: text
  • Example: 4.7

Point releases

It is not currently possible to specify compatibility with point releases. If your extension is compatible with CiviCRM 4.7.21 but not 4.7.20, then you will need to clearly specify this in the comments.

Forward compatibility (4.7/5.x)

For CiviCRM 3.x and 4.x, <ver> tags must explicitly list all compatible versions.

For CiviCRM 4.7.x and 5.x, <ver> tags imply forward compatibility.

Because 4.7.x and 5.x are substantively the same series, <ver>4.7</ver> implies forward compatiblity with 5.x.

<version>

  • Containing element: <extension>
  • Description: The current version of this extension (used for upgrade detection and used to sort available releases for automated distribution)
  • Contains: text

Valid version formats include: 1, 1.1, 1.2.3.4, 1.2-3, 1.2.alpha2 , 1.2.rc2, 2012-01-01-1, 2012-01-01, r456, r5000