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

9 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.

3 Likes
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:

1 Like
4

I configured everything using the instructions above and the Trellis “Composer HTTP Basic Authentication” documentation and I keep getting

  In AuthHelper.php line 205:                                                                             
    The 'https://connect.advancedcustomfields.com/v2/plugins/composer_download?  
    p=pro&t=6.3.6' URL required authentication (HTTP 401).                       
    You must be using the interactive console to authenticate

in the hooks/build-after.yml “Install Composer dependencies” deployment step.

Does anyone have any tips on what I might be missing?

site/composer.json:

  "repositories": [
    {
      "type": "composer",
      "url": "https://composer.deliciousbrains.com",
      "only": ["deliciousbrains-plugin/*"]
    },
    {
      "type": "package",
      "package": {
        "name": "kinsta/kinsta-mu-plugins",
        "type": "wordpress-muplugin",
        "version": "2.3.3",
        "dist": {
          "url": "https://kinsta.com/kinsta-tools/kinsta-mu-plugins.zip",
          "type": "zip"
        }
      }
    },
    {
      "type": "composer",
      "url": "https://connect.advancedcustomfields.com"
    },
    {
      "type": "composer",
      "url": "https://wpackagist.org",
      "only": ["wpackagist-plugin/*", "wpackagist-theme/*"]
    }
  ],
  "require": {
        "wpengine/advanced-custom-fields-pro": "^6.3",

vault.yml:

  vault_wordpress_sites:
    sitename.org:
      composer_authentications:
        - {
          hostname: connect.advancedcustomfields.com,
          username: 123456789ABCDEFGHIKLMNOPQRSTUVWXYNabcdefghijklmnopqrstuvwxyz123456789012,
          password: https://sitename.org
        }
1 Like
5
  • sitename.org in vault_wordpress_sites matches the key of the wordpress site, correct?

This is where the site-specific composer authentication is set up by Trellis:

Also in build-after hook apparently:
https://github.com/roots/trellis/blob/a5040add97ac2befc1325eb13c80ee8c96d15dc5/roles/deploy/hooks/build-after.yml#L12-L24

Site-specific variable composer_authentications_using_basic_auth:
https://github.com/roots/trellis/blob/a5040add97ac2befc1325eb13c80ee8c96d15dc5/group_vars/all/helpers.yml#L25

1 Like
6

I don’t know how much the formatting matters, but my file has the hostname, username password all on one line instead of stacked.

composer_authentications:
      - { hostname: "connect.advancedcustomfields.com", username: "abcdef123456789", password: "https://mydomain.com" }
1 Like
7

Also, what composer version is used on the Trellis web server for installing the ACF PRO plugin, an older version may have issues or not support the auth (Composer doesn't use oauth/http-basic settings for private repos · Issue #8356 · composer/composer · GitHub).

1 Like
8

I believe this was the problem! Thank you so much for pointing me there. Unfortunately I closed the terminal window where I did the update, but I believe I was on composer 2.1.? before I updated to version 2.2.9.

@JordanC26, the inline formatting of the array item doesn’t seem to matter, thanks for your suggestion!

I should add that for this to work in my local development environment, I had to run composer config http-basic.connect.advancedcustomfields.com 123456789ABCDEFGHIKLMNOPQRSTUVWXYNabcdefghijklmnopqrstuvwxyz123456789012 https://live-url.org from my site/ folder.

2 Likes
9

For development, use an auth.json file.

Edit: What I also found useful is committing an auth.json.example to the repository which has a placeholder for the actual ACF PRO key. This helps with starting from a fresh workspace (other projects, and Bedrock do the same).