mixin/polyfill.md

   1 # Mixin Polyfill
   2
   3 Mixins will have built-in support in a future version of CiviCRM (vTBD). However,
   4 for an extension to use a mixin on an older version of CiviCRM, it should
   5 include the polyfill ([mixin/polyfill.php](../mixin/polyfill.php)).
   6
   7 ## Usage
   8
   9 The polyfill will be enabled in `civix` (vTBD).  To activate the polyfill in
  10 a bespoke extension (`myext`, `org.example.myextension`), copy `mixin/polyfill.php`.
  11 Load this file during a few key moments:
  12
  13 ```php
  14 function _myext_mixin_polyfill() {
  15   if (!class_exists('CRM_Extension_MixInfo')) {
  16     $polyfill = __DIR__ . '/mixin/polyfill.php';
  17     (require $polyfill)('org.example.myextension', 'myext', __DIR__);
  18   }
  19 }
  20
  21 function myext_civicrm_config() {
  22   _myext_mixin_polyfill();
  23 }
  24
  25 function myext_civicrm_install() {
  26   _myext_mixin_polyfill();
  27 }
  28
  29 function myext_civicrm_enable() {
  30   _myext_mixin_polyfill();
  31 }
  32 ```
  33
  34 ## Limitations / Comparison
  35
  36 The polyfill loader is not as sophisticated as the core loader. Here's a comparison to highlight some of the limitations:
  37
  38 | Feature | Core Loader | Polyfill Loader |
  39 | -- | -- | -- |
  40 | Load mixins from files (`mixin/*.mixin.php`) | Yes | Yes |
  41 | Load mixins from subdirectories (`mixin/*/mixin.php`) | Yes | No |
  42 | Read annotations from mixin files (eg `@mixinVersion`) | Yes | No |
  43 | Activation - How does it decide to activate a mixin? | Read `info.xml` | Read `mixin/*.mixin.php` |
  44 | Boot cache - How does it store boot-cache? | All boot-caches combined into one file | Each extension has separate boot-cache file |
  45 | Deduplication - If two extensions include the same mixin, then only load one copy. | Yes | Partial - for exact version matches. |
  46 | Upgrade - If two extensions include different-but-compatible versions, always load the newer version. | Yes | No |