Mixins: Standard mixins¶

About this document

This page presents the standard library of pre-built mixins. It assumes you have read about the general concepts.

Introduction¶

The "standard mixins" are published by CiviCRM. Standard mixins aim to be short, simple, and portable. They have additional testing and tooling to provide consistent support over time.

It is often safe to copy a standard mixin and run it on an older environment. For example, menu-xml@1.0.0 is distributed with CiviCRM 5.45+ -- but it also works on CiviCRM 5.27. This is called "backporting". If you manage your extension with civix, then backporting is automatic.

List of mixins¶

Name	Minimum Compatible CiviCRM	Distributed Since CiviCRM	Description
afform-entity-php@1.0.0	5.31	5.50	Scan `afformEntities/*.php`. Register via internal event.
ang-php@1.0.0	5.27	5.45	Scan `ang/*.ang.php`. Register via hook_angularModules.
case-xml@1.0.0	5.27	5.45	Scan `xml/case/*.xml`. Register via hook_caseTypes.
entity-types-php@1	5.45	5.57	Scan `xml/schema/**.entityType.php`. Register via `hook_entityTypes`.
menu-xml@1.0.0	5.27	5.45	Scan `xml/Menu/*.xml`. Register with Menu-Router via hook_xmlMenu.
mgd-php@1.0.0	5.27	5.45	Scan `*/.mgd.php`. Register via hook_managed.
mgd-php@1.1.0	5.27	5.50	As above, with extra performance optimization.
scan-classes@1.0.0	5.51	5.52	Scan `CRM/.php` and `Civi/.php` for key interfaces and annotations. Register via hook_scanClasses.
scan-classes@1.1.0	5.51	5.63	As above, minus a special PHPUnit quirk
setting-php@1.0.0	5.27	5.45	Scan `settings/*.setting.php`. Register via hook_alterSettingsFolders.
smarty-v2@1.0.0	5.27	5.59	Add `templates/**.tpl` to Smarty. Register via hook_config.
smarty-v2@1.0.1	5.27	5.60	As above, with slightly different internal API.
theme-php@1.0.0	5.27	5.45	Scan `*/.theme.php`. Register via hook_themes.

This table is representative. It may not be completely up-to-date. For an authoritative list of standard mixins, browse civicrm-core:mixin/ and civix:mixin-backports.php.

Civix support¶

civix is a tool to help extension-developers. It includes built-in support for standard mixins:

When you make a new extension, some common mixins are enabled by default.
When you generate new skeletal code, it will auto-enable any required mixins. (For example, civix generate:page will auto-enable menu-xml@1.)
When you run civix upgrade, it may suggest enabling or disabling specific mixins.
If your <compatibility> targets an older version of CiviCRM, then civix will automatically include polyfills and backports.

The command civix mixin can be used to view, enable, and disable mixins.

## List the standard mixins. Report on whether they are active.
civix mixin

## Enable all standard mixins
civix mixin --enable-all

## Enable specific mixins
civix mixin --enable=ang-php@1,setting-php@1

## Disable specific mixins
civix mixin --disable=ang-php@1

## Reset the mixins.
civix mixin --disable-all --enable=mgd-php@1

Civix only supports mixins identified by civix:mixin-backports.php.

Quality assurance¶

Suppose you want to develop a new standard mixin that's available to other extension-developers. This is much like developing a basic mixin... but harder. Standard mixins need to work across a range of use-cases:

Applied to core extensions and contrib extensions
Distributed via core tarball and via backport
Activated (and deactivated) during installation (and uninstallation)
Executed via web and CLI and E2E-test and headless-test
Mixed and matched with other standard-mixins

Quality assurance is oriented around an example extension named shimmy. shimmy is not a regular extension. It is dynamically re-generated numerous times. Each time, it uses a different set of mixin options, and it's put through a series of installation and uninstallation tests. This is a brutal process designed to find (and prevent) subtle discrepancies in how mixins interact with system-services and system-caches.

To run the full suite (with all the permutations of shimmy), use this script:

./tools/mixin/bin/test-all

test-all is important for the CI server, but it's an entire suite of tests. If you are trying to debug a specific problem, then you'll need to focus on one instance of shimmy. To do this, pick a folder where you will put shimmy and then run the mixer command.

SHIMMY=$(cv path -c extensionsDir/example-mixin)
./tools/mixin/bin/mixer create -f --bare "$SHIMMY" mgd-php@1 smarty-v2@1

What are the options in this command?

SHIMMY is the folder where it will put the extension
mixer is the command that generates the extension
-f forces the command to overwrite any pre-existing content in that path
--bare indicates that you just want to make a lightweight version of the extension. (You are not testing backports.)
mgd-php@1 smarty-v2@1 are two mixins that we want to focus on

Pick one SHIMMY folder and stick to it.

If you generate two copies of shimmy (in different folders), then this will quickly become confusing.

The example above is chosen to match the test-all script.

What does the example extension look like?

After creating this folder, you can inspect it:

find $SHIMMY -type f

You should see something that resembles a regular extension:

/srv/web/sites/default/files/civicrm/ext/example-mixin/info.xml
/srv/web/sites/default/files/civicrm/ext/example-mixin/shimmy.php
/srv/web/sites/default/files/civicrm/ext/example-mixin/shimmy.civix.php
/srv/web/sites/default/files/civicrm/ext/example-mixin/phpunit.xml.dist
/srv/web/sites/default/files/civicrm/ext/example-mixin/CRM/ShimmyGroup.mgd.php
/srv/web/sites/default/files/civicrm/ext/example-mixin/CRM/BunnyDance.mgd.php
/srv/web/sites/default/files/civicrm/ext/example-mixin/tests/mixin/ManagedCaseTypeTest.php
/srv/web/sites/default/files/civicrm/ext/example-mixin/tests/mixin/ManagedTest.php
/srv/web/sites/default/files/civicrm/ext/example-mixin/tests/mixin/SmartyTest.php
/srv/web/sites/default/files/civicrm/ext/example-mixin/tests/phpunit/E2E/Shimmy/LifecycleTest.php
/srv/web/sites/default/files/civicrm/ext/example-mixin/tests/phpunit/bootstrap.php
/srv/web/sites/default/files/civicrm/ext/example-mixin/templates/CRM/Shimmy/Example.tpl

Where does the example code come from?

We asked mixer to focus on mgd-php@1 and smarty-v2@1, so it pulled from these sources:

mixin/mgd-php@1/example/ - Example data for mgd-php
mixin/smarty-v2@1/example/ - Example data for smarty-v2
tests/extensions/shimmy/ - Common boilerplate

Now, you have a regular extension. You can run tests in the usual ways:

cd "$SHIMMY"
phpunit9 --group e2e
phpunit9 --group headless

How do I run the test in PHPStorm?

If PhpStorm is already configured to run core tests, then:

In the SHIMMY folder, open tests/phpunit/E2E/Shimmy/LifecycleTest.php
Select a specific test, such as testLifecycleWithLocalFunctions.
- (If you have freedom to choose, then use this -- it's easier to debug.)
Run this test like usual. It will fail.
Update the test options ("Run > Edit Configurations"). Find "LifecycleTest" and update it:
- The workdir should match SHIMMY folder
- The PHPUnit XML file should come from the SHIMMY folder.
- The environment should not set CIVICRM_UF
Run this test again. It should execute.