Carbon Fields distribution woes

We’d like to share some thoughts regarding the distribution of Carbon Fields v2. Let’s get right into it!

What is Carbon Fields?

Carbon Fields is a library AND a plugin that provides tools to developers to create enhanced custom fields for posts, terms, users, themes etc. similar to ACF or CMB2. Being developer-oriented, Carbon Fields field definitions are made through PHP rather than a visual administration interface.

However, being a library, Carbon Fields is not eligible for upload into the WordPress plugin repository as mentioned by Mika Epstein as it’s aimed at developers and not end users.

Wait, if Carbon Fields is a library then how come it is already in the WordPress plugin repository?

Well, we got lucky.

The WordPress plugin repository has apparently always disapproved of libraries and frameworks being uploaded however they only started enforcing this in the past year or so and since Carbon Fields was first uploaded on the 27th of January 2016, we got approved.

So … how do I install Carbon Fields 2.0 – as a library or plugin?

We actually went back-and-forth between distribution as a plugin and only as a composer package multiple times during the development of 2.0. Eventually we came to the conclusion that we cannot ship 2.0 through the WordPress plugin repository because it contains a number of breaking changes.

Those changes would have resulted in broken sites because site administrators clicked the “Update” button.

Does this mean that Carbon Fields is no longer installable as a plugin?

It actually is installable as a plugin – just not through the WordPress plugin repository. We ended up splitting Carbon Fields into two – the main library and a barebones plugin loader (both installable through composer).

If you want to load the library you should use composer require htmlburger/carbon-fields – see the quickstart guide here

If you want to load the plugin you should use composer require htmlburger/carbon-fields-plugin (which in turn requires the library) – see the quickstart here.

This allows you to use Carbon Fields however you like and on whatever setup you have (even on Bedrock) and breaking changes will not be an issue since plugin updates will not be released in the plugin repository.

Unfortunately, this approach has a couple downsides as well:

  1. You should use composer to manage Carbon Fields’ version and update it when security patches are released
  2. You have to write your own version checking code to resolve conflicts between multiple active plugins or themes loading Carbon Fields at the same time.

In an ideal world …

… WordPress would have plugin dependencies or direct composer support for plugins and themes.

WordPress’ focus has always been the end user (which is why it’s so popular) and we understand that, however, we as developers feel a little left out. Composer has completely revamped modern PHP development but we can’t really take full advantage of that. Drupal, for example, has had plugin dependency support for years if not a decade already. PHP version requirements for plugins is apparently coming soon, but that’s not really enough, is it?

If you want to read more on the subject of libraries as plugins you can check out this article regarding CMB2 as they seem to have the same distribution pains.

Leave a Reply

Your email address will not be published. Required fields are marked *

Excited about Carbon Fields? Spread the word!