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</author>
    <email>ginkgomzd@fastmail.com</email>
  </maintainer>
  <releaseDate>2018-06-29</releaseDate>
  <version>2.4.3</version>
  <compatibility>
    <ver>5.28</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>
  <requires>
    <ext>org.civicrm.angularprofiles</ext>
  </requires>
</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
`<psr0>`	0+
`<psr4>`	0+

For example, many extensions will define class-loading rules for the CRM and Civi namespaces:

<classloader>
  <psr0 prefix="CRM_" path="."/>
  <psr4 prefix="Civi\" path="Civi"/>
</classloader>

The CRM_ namespace is an older convention that complies with the older standard, PSR-0.

The Civi\ namespace is a newer convention that complies with the newer standard, PSR-4.

`<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

`<psr0>`¶

Within the CiviCRM ecosystem, the <psr0> tag is typically used for loading the CRM_ namespace.

Containing element: <classloader>
Description: Specifies the namespace and file-path of classes to add to the classloader, as per PSR-0.
Contains: nothing — should be empty

Attributes acceptable for <psr0>

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

How does PSR-0 compare to PSR-4?

PSR-0 has stricter file-naming conventions. The file-name must mirror the full class-name.

Path:       src/
Prefix:     Fruit_
Class name: Fruit_Apple_Fuji
File name:  src/Fruit/Apple/Fuji.php

PSR-0 has more flexible namespacing. One may use either:

// Old style namespaces
$obj = new Fruit_Apple_Fuji();

class Fruit_Apple_Fuji { }

// New style namespaces
$obj = new \Fruit\Apple\Fuji();

namespace Fruit\Apple;
class Fuji {}

`<psr4>`¶

Within the CiviCRM ecosystem, the <psr4> tag is typically used for loading the Civi\ namespace.

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

Attributes acceptable for <psr4>

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

How does PSR-4 compare to PSR-0?

PSR-4 has more flexible file-naming. It is possible (but not required) to have shorter file-paths.

Path:       src/
Prefix:     Fruit\Apple\
Class name: Fruit\Apple\Fuji
File name:  src/Fuji.php

PSR-4 has stricter namespacing. One MUST use formal namespace declarations.

$obj = new \Fruit\Apple\Fuji();

namespace Fruit\Apple;
class Fuji {}

`<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 "kebab-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 "kebab-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

info.xml¶

Example¶

Changelog¶

Elements¶

<author>¶

<authors>¶

<civix>¶

<classloader>¶

<comments>¶

<compatibility>¶

<description>¶

<develStage>¶

<downloadUrl>¶

<email>¶

<ext>¶

<extension>¶

<file>¶

<homepage>¶

<label>¶

<license>¶

<maintainer>¶

<name>¶

<namespace>¶

<psr0>¶

<psr4>¶

<releaseDate>¶

<requires>¶

<role>¶

<tags>¶

<url>¶

<urls>¶

<ver>¶

<version>¶