Skip to content

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.36.0 <authors> introduced as part of schema
5.24.0 <tags> introduced as part of schema
5.0.0 <ver> tags now imply forward compatibility when the version specified is 4.7 or higher. (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. If you want to specify multiple version compatibility for both lower than 4.7 and higher, then you need to specify multiple <ver> tags for all of the lower versions and at least one of 4.7 or higher, e.g. <ver>4.5</ver> <ver>4.6</ver> <ver>4.7</ver>.
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> or authors
  • Description: Name of the person and/or organisation maintaining the extension
  • Contains: text (if inside <maintainer>) | elements (if inside <authors>)

Elements acceptable within <author> if inside <authors>

Element Acceptable instances
<name> 1
<email> 1
<homepage> 1
<role> 1

<authors>

  • Containing element: <extension>
  • Description: Replaces <maintainer> allowing for multiple authors to be designated. Backwards compatible with the pre 5.36 <maintainer> syntax.
  • Contains elements

Elements acceptable within <authors>

Element Acceptable instances
<author> Unlimited

<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. Each <ver> child element should only contain a single compatible version of CiviCRM.
  • 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> or <author>
  • 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

<homepage>

  • Containing element: <author>
  • Description: Contains the web address for an author.
  • 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> | <author>
  • Description: Human-readable name of the extension. It can contain spaces | Use For the extension author's name inside an <author> tag.
  • 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+

<role>

  • Containing element: <author>
  • Description: Holds the role for the author. Could be "Maintainer" for example.
  • Contains: text

<tags>

  • Containing element: <extension>
  • Description: Freeform tags allow extensions to be organized into categories or selected as subgroups. Tags MUST contain only letters, numbers, dashes,and colons. Tags are case-sensitive. Tags MUST follow the structure <prefix>:<some-tag-name>. Tags SHOULD be documented in the table below. (If you need to use a new/unknown tag, then please submit a documentation update with a description.)
  • Contains: elements
  • Example:

    <extension key="org.civicrm.foo" type="module">
      <tags>
        <tag>comp:CiviContribute</tag>
        <tag>topic:payment-processor</tag>
        <tag>mgmt:hidden</tag>
      </tags>
    </extension>
    

The topic:* tags relate to a general topic/business area/problem area. Topics must use "snake-case" (lowercase/hyphenated).

Tag name Description
topic:reporting Provides reporting functionality
topic:search Provides search functionality
topic:email Provides email functionality

The comp:* tags relate to specific implementations (components/extensions/modules). Components may use capitalization that matches the original component. Where applicable, tags SHOULD match counterparts in the Gitlab labels.

Tag name Description
comp:CiviCampaign Improves or alters the CiviCase component
comp:CiviCase Improves or alters the CiviCase component
comp:CiviContribute Improves or alters the CiviContribute component
comp:CiviEvent Improves or alters the CiviEvent component
comp:CiviGrant Improves or alters the CiviGrant component
comp:CiviMail Improves or alters the CiviMail component
comp:CiviReport Improves or alters the CiviReport component

The mgmt:* tags relate to the management of extensions. Management tags must use "snake-case" (lowercase/hyphenated).

Tag name Description
mgmt:hidden The extension is not displayed in the administrative UI, but it can be managed via CLI and API. (Implemented in v5.24+.)
mgmt:mandatory The extension must always be enabled. (Implementation pending)
mgmt:autoinstall The extension is installed by default on new sites. (Implementation pending)

<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, each <ver> element should only contain a single compatible version of CiviCRM.
  • Contains: text
  • Example: 4.7

Which version to choose?

Specify the minimum version number required by this extension. You may use a particular minor version, e.g. 5.23, but point releases (e.g. 5.23.2) are not supported.

For compatibility with CiviCRM versions prior to the 5.x.x version number change you should continue to specify the version as <ver>4.7</ver>.

<ver> elements imply forward compatibility. So <ver>5.0</ver> means all 5.. versions of CiviCRM. Because 4.7.x and 5.x are substantively the same series, <ver>4.7</ver> implies forward compatiblity with 5.x.

It is not currently possible to specify a "maximum compatible version".

<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