How to retrieve field values from "Carbon Fields 2.1.0" WP-plugin? At which phase are they accessible?

Question

First I downloaded https://carbonfields.net/zip/latest/ and installed the plugin at WP backend. I also activated it as well.

For this test case I use the "Twenty Sixteen" template with a fresh WordPress installation without any other plugins installed and according to the documentation page of Carbon Fields I added the following piece of code to the top of my functions.php file:

<?php // PHP 7
use Carbon_Fields\Container;
use Carbon_Fields\Field;

add_action( 'carbon_fields_register_fields', 'crb_attach_theme_options' );
function crb_attach_theme_options() {
    Container::make( 'theme_options', 'Theme Options' )
        -> set_page_menu_position( 0 )
        -> add_fields( array(
            Field::make( 'text', 'crb_text')
        ) );
}

Everything looks fine so far because "Theme Options" appears in WP backend just as expected.

Now I try to retrieve the field value crb_text as follows:

// this snippet starts exactly where the previous one ended
add_action( 'after_setup_theme', 'crb_load' );
function crb_load() {
    // require_once( ABSPATH . '/vendor/autoload.php' ); original from website throws: "Failed opening required" so modified to:
    require_once( ABSPATH . 'wp-content/plugins/carbon-fields/vendor/autoload.php' );
    \Carbon_Fields\Carbon_Fields::boot();
    var_dump( carbon_get_theme_option( 'crb_text' ) ); // -> string(0) ""
    var_dump( carbon_get_theme_option( '_crb_text' ) ); // -> string(0) "" isn't actually the right way to do it but give it a try for testing purpose
    var_dump( get_option( '_crb_text' ) ); // -> string(4) "test"
}

As you can see I'm able to retrieve the data by calling get_option( '_crb_text' ) which is the native WP way but the plugins function carbon_get_theme_option( 'crb_text' ) does not work. Actually this would be fine for "simple fields" but there are "complex fields" that have to be retrieved by the plugins own functions which is carbon_get_theme_option() in this case.

I also did have a look at this question: use Carbon Fields in custom plugin class. But this question ends where mine starts.

Thank you in advance...

---

PS: I'm used to work with Carbon Fields 1.6 which works fine with quite a similar setup but want to upgrade to branch 2.

---

My enviroment again: define('WP_DEBUG', true);, Carbon Fields 2.1.0, WordPress 4.8.2–de_DE (fresh installation without other plugins than Carbon Fields), Twenty Sixteen 1.3, PHP 7

Answer 1

This is a quote from a chat which I had with one of the plugin authors "Atanas Angelov":

Hi @Elstermann you couldn't get the value because in order to get a field's value it has to be defined first. All fields are defined in the carbon_fields_fields_registered hook so any carbonget* calls before that hook has fired will not work (since no fields are defined yet).

So here is one confirmed way to bootstrap Carbon Fields:

use Carbon_Fields\Container;
use Carbon_Fields\Field;

add_action( 'carbon_fields_register_fields', 'crb_attach_theme_options' );
function crb_attach_theme_options() {
    Container::make( 'theme_options', 'Theme Options' ) -> add_fields( array(
        Field::make( 'text', 'crb_text')
    ) );
}

add_action( 'after_setup_theme', 'crb_load' );
function crb_load() {
    require_once( ABSPATH . 'wp-content/plugins/carbon-fields/vendor/autoload.php' );
    \Carbon_Fields\Carbon_Fields::boot();
}

add_action( 'carbon_fields_fields_registered', 'crb_values_are_avail' );
function crb_values_are_avail() {
    var_dump( carbon_get_theme_option( 'crb_text' ) ); // -> string(0) "test"
}

Just to emphasize the core issue here... That was the reply to the snippet above:

Yes - carbon_fields_fields_registered should be the earliest you can get a field's value

Notes For Clarification & Relevancy

This is only relevant if you want to retrieve the data earlier than in your theme files due to the fact that the carbon_fields_fields_registered action hook has already fired when your theme files are loaded. So in your theme files it should be totally fine to just call:

carbon_get_theme_option( 'your_name_of_a_carbon_field' );
// for example in the "header.php" in your theme directory you could use
<style>body{background-color:<?php
    echo carbon_get_theme_option( 'custom_body_background' );
?>}</style> // just to give a real life like example

This is the case for all "carbon_get_*" functions such as carbon_get_post_meta(), carbon_get_term_meta(), carbon_get_user_meta(), carbon_get_comment_meta().

---

Useful For

If you ever want to retrieve data earlier than in your theme files make shure that this happens on carbon_fields_fields_registered action hook or that the hook was fired already.

This could be the case if you develop a WP plugin in which you integrate Carbon Fields (which is true for me). When you bootstrap your plugin the carbon_fields_fields_registered action hook didn't happen so make sure to have the right timing.

Alternative

As also mentioned in the question you can also use:

get_option( '_your_field_name_prepended_by_lodash' )

when you want to retrieve data that is set by:

Container::make( 'theme_options', 'Theme Options' ) -> add_fields()

but this goes along with the following disadvantages:

1. this doesn't work with Complex Fields and
2. you don't have access to the values set by Field::make(...)->set_default_value( $default_value ) (in contrast to Carbon Fields methods).