Skip to content

Mixins: Introduction

Analogy: A PHP "class" can incorporate multiple "traits". Similarly, a CiviCRM "extension" can incorporate multiple "mixin"s.

CiviCRM mixins allow extensions to re-use prepared behaviors. They are enabled and disabled via info.xml. For example:

<extension type="module">
  <mixins>
    <mixin>menu-xml@1.0.0</mixin>
    <mixin>mgd-php@1.0.0</mixin>
  </mixins>
</extension>

This example enables two mixins (menu-xml and mgd-php). These are feature-flags: by enabling the flag, your extension gets access to more services and more functionality.

The implementation of each mixin comes from a PHP file, such as mixin/menu-xml@1/mixin.php or mixin/mgd-php@1/mixin.php. CiviCRM will find and load the appropriate PHP files.

Mixins follow an open architecture, enabling you to write new mixins or use the library of standard mixins.

Mixins always have version numbers. In the info.xml example, it declares a version-constraint ("menu-xml@1.0.0"). In the PHP file, it declares a version-code ("1.0.0").

CiviCRM notes the requested version and loads a compatible version.

Tip: CiviCRM v5.45+ includes full support for mixins. Older releases require a polyfill.

CiviCRM v5.45+ includes the full, built-in system for finding and activating mixins.

Many mixins may be used on older CiviCRM versions if the extension includes the polyfill. civix automatically adds the polyfill if you declare <compatibility> with an older version of CiviCRM.

However, the polyfill lacks some features. See the polyfill documentation for a full comparison.

Tip: If you edit info.xml, then you also need to flush caches.

The list of mixins is stored in a cache. Therefore, if you do anything that affects the list of active mixins, then you need to flush the cache.

cv flush
Tip: Standard mixins can also be enabled and disabled via civix.

Instead of editing info.xml directly, you can also run the civix mixin command.

Tip: Upgrades are automatic - within the rules of Semantic Versioning.

Suppose your extension declares a requirement for:

<mixin>menu-xml@1.0.0</mixin>

Suppose CiviCRM has found several PHP files with a matching name:

  • mixin/menu-xml@1.0.0.mixin.php
  • mixin/menu-xml@1.1.0.mixin.php
  • mixin/menu-xml@2/mixin.php

Under SemVer, 1.0.0 can be safely replaced with 1.1.0 -- but 2.0.0 represents a break in backward-compatibility. CiviCRM will use 1.1.0 for this extension.

The practical effect is that standard mixins receive automatic maintenance updates. You do not need to modify or republish your extensions for a minor update. However, major contract changes are not automatic. To use v2.x, you will need to manually update the extension.

For more information, you can see the subchapters here as well as: