Roots Discourse

How to setup Carbon Fields in Sage

Carbon Fields is a great custom field solution for WordPress that’s completely free and open source. Who doesn’t love that? Unlike some other custom field plugins for WordPress, Carbon Fields is designed to be configured in your codebase as opposed to a user interface. This paired with its expressive syntax makes Carbon Fields a great choice for developers.

Here’s how you can get started with Carbon Fields in Sage:

1. Add htmlburger/carbon-fields to your Sage project

In the root of your theme install Carbon Fields with Composer:

composer require htmlburger/carbon-fields

Now, since Sage is already autoloading the Composer dependencies in resources/functions.php, you don’t need to worry about loading Carbon Fields yourself.

2. Create a custom fields configuration file called app/fields.php

To avoid naming conflicts with Roots\Sage\Container and to keep things organized we will create a file called fields.php in the app directory.

// app/fields.php

<?php

namespace App;

use Carbon_Fields\Container;
use Carbon_Fields\Field;

/**
 * Define custom fields
 * Docs: https://carbonfields.net/docs/
 */
add_action( 'carbon_fields_register_fields', function () {
    // Your fields will go here.
});

/**
 * Boot Carbon Fields
 */
add_action( 'after_setup_theme', function () {
    \Carbon_Fields\Carbon_Fields::boot();
});

3. Add fields.php to Sage’s required files

Once you’ve created app/fields.php, you will need to tell Sage to require it. You can do that in functions.php which is located in the resources directory.

Just append fields to the array like so:

// resources/functions.php

['helpers', 'setup', 'filters', 'admin', 'fields']

4. Add your fields

Once you’ve completed the last step you are ready to start creating fields. You can read Carbon Fields’ documentation to learn more about what fields you can add and how to configure them. The following is a simple example of how you can use Carbon Fields in your theme.

1. Create a field

// app/fields.php

/**
 * Define custom fields
 * Docs: https://carbonfields.net/docs/
 */
add_action( 'carbon_fields_register_fields', function () {
    Container::make( 'post_meta', 'Page Layout' )
        ->where( 'post_type', '=', 'page' )
        ->add_fields( array(
            Field::make( 'text', 'sage_greeting', 'Greeting' )
        ));
});

2. Retrieve the data in a controller

// app/controllers/*.php

public function greeting()
{
    return carbon_get_the_post_meta( 'sage_greeting' );
}

3. Use the data in a template

// resources/views/**/*.blade.php

<h2>{{ $greeting }} friend!</h2>

As you can see, it’s super easy to get started using Carbon Fields with Sage — and this only scratches the surface of what you can do with it.

12 Likes

Just a quick note that after using CMB2 (inside my codebase) for literally years, I recently switched over to Carbon and am loving it. Much more elegant solution that hasn’t left me wanting. Actually stumbled across it here (on a CMB2 thread) by accident and stoked that I did.

Hello
i try to install it with bedrock/sage
always error, nothing find to make it working
i try to resolve with : https://github.com/htmlburger/carbon-fields/issues/5
and this : https://docs.carbonfields.net/#/overview
I made a classic wordpress install with composer , it work
but i can(t find the problem with bedrock sage
It was a good alternative to ACF pro
thanks for any help