Mixins: Standard mixins¶
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,
email@example.com has been distributed with CiviCRM 5.45+
-- but it can be used in 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|
|firstname.lastname@example.org||5.27||5.50||As above, with extra performance optimization.|
|email@example.com||5.51||5.63||As above, minus a special PHPUnit quirk|
|firstname.lastname@example.org||5.27||5.60||As above, with slightly different internal API.|
civix is a tool 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:pagewill auto-enable
- When you run
civix upgrade, it may suggest enabling or disabling specific mixins.
- If your
<compatibility>targets an older version of CiviCRM, then
civixwill automatically include polyfills and backports.
civix mixincan 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.
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 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:
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
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?
SHIMMYis the folder where it will put the extension
mixeris the command that generates the extension
-fforces the command to overwrite any pre-existing content in that path
--bareindicates that you just want to make a lightweight version of the extension. (You are not testing backports.)
mgd-php@1 smarty-v2@1are two mixins that we want to focus on
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
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
smarty-v2@1, so it pulled from these sources:
mixin/mgd-php@1/example/- Example data for
mixin/smarty-v2@1/example/- Example data for
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
- Select a specific test, such as
- (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
- The PHPUnit XML file should come from the
- The environment should not set
- The workdir should match
- Run this test again. It should execute.