[Guide] Using the `ACF PRO` official install method with Bedrock/Trellis

bedrock
1

Bedrock

  • For development, use an auth.json file in the Bedrock project folder – but it should not be committed to the repository, but rather added to .gitignore as it is a secret (the ACF PRO license), similar to the .env file.
{
    "http-basic": {
+        "connect.advancedcustomfields.com": {
+            "username": "[ACF PRO license key]",
+            "password": "https://[domain.tld]"
+        }
    }
}

Use the ACF PRO license key as the username.

The password should be the site host (for which the license is active), including the protocol (https://example.com), not just the hostname or domain!
password must not be empty, it has to have some string value, and also it has to be a full URL with protocol, not just the hostname/domain, otherwise a HTTP authentication error will occur. Even if an Agency ACF PRO license is used with unlimited amount of sites, the password must be set to something (also see further below for setting a password to equal to each site host, which is needed for site-specific ACF PRO licenses).

  • Add the ACF PRO repository in composer.json:
  "repositories": [
+    {
+      "type":"composer",
+      "url":"https://connect.advancedcustomfields.com"
+    }
  ],
  • Require the ACF PRO plugin
    • Either by using the CLI:
      $ composer require wpengine/advanced-custom-fields-pro
    • Or by adding the require manually to composer.json (which the CLI command should do otherwise):
  "require": {
+  "wpengine/advanced-custom-fields-pro": "6.1.6"
  }
  • (Optional) Clean up previous mechanisms for installing ACF PRO, e.g.
  "repositories": [
-   {
-       "type": "package",
-       "package": {
-         "name": "advanced-custom-fields/advanced-custom-fields-pro",
-         "version": "6.1.6",
-         "type": "wordpress-plugin",
-         "dist": {
-           "type": "zip",
-           "url": "https://connect.advancedcustomfields.com/index.php?a=download&p=pro&k={%PLUGIN_ACF_KEY}&t={%version}"
-         },
-         "require": {
-           "composer/installers": "^2",
-           "ffraenz/private-composer-installer": "^5.0.0"
-         }
-       }
-     }
  ],
  "require": {
-  "advanced-custom-fields/advanced-custom-fields-pro": "6.1.6",
  }

But do not remove the alternative installer from allow-plugins yet,
as composer needs to have updated the dependencies once, before it can be removed without causing an error during deploy:

  "config": {
    "allow-plugins": {
      "ffraenz/private-composer-installer": true,
    }
}

This line can be cleaned up after a successful deploy:

  "config": {
    "allow-plugins": {
-      "ffraenz/private-composer-installer": true,
    }
}

Trellis

ACF PRO Agency license (unlimited sites) / global fallback

  • The same authentication data as in auth.json has to be added to group_vars/<environment>/vault.yml:
composer_authentications:
+   # Advanced Custom Fields (ACF) PRO plugin
+  - {
+       hostname: "connect.advancedcustomfields.com",
+       username: "[ACF PRO license key]",
+       password: "https://[site host (must be non-empty and a full URL with protocol)]"
+    }

ACF PRO site-specific licenses

Set the password for each site host in vault_wordpress_sites (also in group_vars/<environment>/vault.yml):

vault_wordpress_sites:
  example.com:
+    composer_authentications:
+      - {
+           hostname: "connect.advancedcustomfields.com",
+           username: "[ACF PRO license key (to which this site belongs)]",
+           password: "https://example.com" # host of site
+        }
  • (Optional) Clean up old variables used with the previous installation method:
    But only clean this variable up when the affected site uses this new installation method.
- plugin_acf_key: "..."
  • Deploy the Bedrock site, the ACF PRO plugin should be installed by Trellis using this new method.

Possible issues and workarounds

  • composer caches the packages, hence failing authentication may not be apparent until the cache was invalidated.

Possible improvements and remarks

As the ACF PRO Agency license allows for unlimited sites, it could make sense to add the ACF PRO license globally and set a different password with the host for each site. However, interpolation of a global ACF PRO license variable does not work as these are not templates. As this will work just fine when setting just one site as password for all other sites, this may not be important.

Resources

8 Likes
2

Follow up to this guide:

Besides installing ACF PRO natively using composer it can also be activated programmatically using a PHP constant:

For a Bedrock site this can be accomplished using an environment variable like ACF_PRO_LICENSE (set in .env standalone or in vault.yml in Trellis):

ACF_PRO_LICENSE='<ACF PRO key here>'

    ACF_PRO_LICENSE: '<ACF PRO key here>'

The environment variable can be set in the base config (as development.php) as PHP constant for being used by ACF PRO:

if (env('ACF_PRO_LICENSE')) {
    Config::define('ACF_PRO_LICENSE', env('ACF_PRO_LICENSE'));
}

That configuration code of Bedrock sites for setting PHP constants from environment variables is considerably growing with each newly added plugin that supports license keys/configuration from PHP constants like this.
It may be a good idea/time to add a standard library or some other mechanism to Bedrock that has a curated collection of these environment variables and PHP constants (and other variables initialized from environment variables).
I have to duplicate quite some code between existing and newly added Bedrock sites just for setting PHP constants and variables from environment variables.

1 Like
3

This is a good idea. Do you want to open a feature request on the wp-config repo?

Edit: Adds new convenience methods by kellymears · Pull Request #3 · roots/wp-config · GitHub :eyes: