Figure out how to decouple from ACF

[acobster]

This is a research question. What I'm hoping to get out of this is a list of actionable options, such as:

• document some stuff, but don't implement any new functionality
• implement features X, Y, and Z and document them; describe how they build on Timber's integration with ACF
• burn the Conifer forest to the ground, because there is no hope of making anything useful without ACF
• etc.

No new code will be committed to Conifer as a direct result of this, but we may follow up with tickets for adding/refactoring/etc. depending on findings.

Why we're doing this

Timber docs state:

Timber is designed to play nicely with (the amazing) Advanced Custom Fields. It’s not a requirement, of course.

We want to be able to make the same claim in our docs, and we want to be sure what we mean when we say it's "not a requirement."

What we need to find out

Conifer makes exactly one reference to ACF, currently in the Conifer\Admin::add_theme_settings_page() method (although I have plans to move this to live under Conifer\Integrations). This is totally optional, non-critical Conifer functionality. So it follows that Conifer can claim that ACF is not required out of the box.

But what happens when someone does something like this?

$page = new Conifer\Post\Page();
$field = $page->get_field('my_custom_field');

Specific questions that will help us arrive at a course of action:

• What is the value of $field if ACF is not enabled?
• What exactly happens when Conifer/Timber calls out to ACF?
• If a developer has activated ACF alongside Conifer and has been running the above code suddenly (for some reason) deactivates ACF, what unpleasant surprises await them?

Update: Acceptance Criteria

• [ ] A new section of the docs titled Integrations
• [ ] Within that section, short description of Conifer's ACF integration, making clear that it basically inherits Timber's integration wholesale and doesn't put anything in the way
• [ ] Also within that section, a link to Timber's ACF documentation

[acobster]

@philmprice relevant: https://timber.github.io/docs/guides/acf-cookbook/

[philmprice]

Woohoo! I'm starting in on this.

[philmprice]

I'm putting research notes here instead of confluence so it's all in one place. Research still in progress, but so that I can remember where everything is at when I return on Monday...

From what I can see so far, the {{ post.get_field('foo') }} calls in Twig/Timber templates hits /plugins/timber-library/lib/Post.php::get_field(). From there is sends a null value (while still referencing page id, odd, still getting to the bottom of this) to a 'timber_post_get_meta_field_pre' filter, then if empty, it simply calls WP's native 'get_post_meta()' to check for value. If it exists it sends the value to another filter & then to a recursive conversion function to convert any contained WP_Post objects to Timber Post objects, and then returns result.

I would just assume that it's connectivity to ACF is simply ACF putting values in meta records and Timber pulling values from meta records, but that doesn't exactly explain how it's benefitting from ACF's specific-value return functionality (return id, name, array, etc) or why the ACF meta records I'm finding in other sites seem to be prepended with an underscore. It makes me suspect that there may be a bit more going on.

However, I should also take a step back and consider whether or not that is a specific direction worth diving into... if we already know that Timber will pull a meta record if it exists and simply return a safe/graceful "null" if it doesn't (I did test this, it's pretty bumper-guarded) - what should our next step be?

I'll be diving back into this on Monday. :)

[acobster]

IIRC, ACF actually stores two meta fields for each custom field you configure - one with the leading underscore and one without. I think the latter contains the actual data, so I'm guessing that the _-prepended one probably contains meta-meta-data. :) So maybe all the magic happens on the ACF side via actions/filters, and Timber just "integrates" with it by virtue of grabbing vanilla wp_postmeta data despite knowing nothing about ACF? It might be worth looking a little more into how ACF implements those filters and what it uses those two meta fields for, just to cover our bases.

In any case, I think this is probably enough information for us to officially say that Conifer does not depend on ACF and integrates just as well with it as Timber, with the caveat that as this isn't stable yet there may be bugs for certain use-cases, etc. Anything to add, @sdunham ?

[sdunham]

Nah, nothing to add. Looks like we're good to go on this effort.

Potentially interesting side note: At least some of the magic happens on the Timber side, via filters defined in the Timber\Integrations\ACF class. It looks like they optionally (if ACF is present, most likely) filter values for post/term/user meta to pull the value as ACF defines/filters it, vs the vanilla meta data value in the database.

[philmprice]

As a small follow up, I did another test installing ACF, creating a group/field for pages and using it to populate & display a value, then deleted ACF entirely and my value stayed on the page. So it looks like they do make a firm handshake at the meta record, but may not have much of a dependency on each other otherwise.

[acobster]

@philmprice see added acceptance criteria! :rocket: