Troubleshooting: TGMPA causes gulp install task to fail - dotherightthing/wpdtrt-plugin-boilerplate GitHub Wiki

Status

  • Stable @ 1.4.26
  • Resolves local install issue with DTRT Gallery

Trigger

yarn run build

Error message

If you have debugging enabled, a message similar to this will be output to debug.log:

Call to undefined function did_action() in /Volumes/DanBackup/Websites/wpdtrt-blocks/vendor/tgmpa/tgm-plugin-activation/class-tgm-plugin-activation.php

Explanation

Background

TGMPA is a 3rd party module for requiring and loading (PHP-based) plugins into WordPress. TGMPA allows developers to tell theme/plugin users that they could/should/must have a particular plugin, and notifies them when an update is available. It mirrors the functionality of the built-in WordPress plugin management system, but also crucially allows developers to require plugins which haven't been published to the WordPress Plugin Directory (including the DTRT plugins), although the update notifications don't work in that case.

DTRT WordPress Plugin Boilerplate uses TGMPA to specify plugin dependencies when building WordPress themes, and when building plugins that piggyback on existing plugin functionality. DTRT WordPress Plugin Boilerplate also loads these plugins via Composer, so that unit tests can be run with them present, but they are not bundled with the plugin as it breaks their upgrade path via WordPress.

Cause

TGMPA has a known issue with its autoloading. The code within the autoloaded files appears to assume that it will be run within a WordPress environment. This doesn't happen until the PHPUnit step of the build, so TGMPA fails, taking out PHPDoc in the process. See TGMPA: Fatal error when using composer and DTRT WordPress Plugin Boilerplate: PHPDoc fails due to TGMPA.

Workaround

DTRT WordPress Plugin Boilerplate sidesteps this issue by deferring the loading of TGMPA until after PHPDoc has run. In order to prevent TGMPA from being loaded too soon, a reference to the TGMPA package is stored within a (valid) custom require-after-phpdoc key in composer.json's extra field.

"extra": [
    {
        "require-after-phpdoc": "tgmpa/tgm-plugin-activation:2.6.*"
    }
]

Gulp orchestrates the plugin build and runs the composer install early on, uninstalls TGMPA prior to PHPDoc being run (useful for local dev updates), then reinstalls it before PHPUnit is run.

Common causes

  • You have manually edited composer.json prior to a commit, then run composer update
  • You have a stale composer.lock file
  • The vendor file contains out-of-date packages (with stale composer.lock files)

Solution

  1. Delete the vendor folder: rm -rf vendor
  2. Download dependencies and update the lock file: composer update
  3. Install build dependencies: yarn install
  4. Install plugin dependencies: yarn run build