Download the PHP package tbruckmaier/corcel-acf without Composer

Corcel ACF Plugin

Use Wordpress Advanced Custom Fields (ACF) in laravel.

This Corcel plugin allows you to fetch WordPress custom fields created by the ACF plugin using the same syntax of Eloquent, from the Laravel Framework. You can use Eloquent models and Collections to improve your development, using the WordPress backend with any PHP application.

For more information about how Corcel works please visit the repository.

• Installation
• Features
• Usage
  • Functionality
  • Fields
  • Custom field types
• Running Tests
• Licence

Installation

To install the ACF plugin for Corcel is easy:

Corcel is required for this plugin, but don't worry, if it's missing it will be installed as well.

Features

• loads ACF fields via eloquent relations
  • loads acf data for a post only once and save sql queries
  • supports eager loading of acf relations
• supports deeply encapsulated fields (e.g. a image in a repeater in a flexible content)
• return suitable data types for the different acf fields (see table below)
  • unknown fields return a generic class with access to the raw db values
  • custom classes can be used for existing & unknown fields
• possible to access acf field config and internal attributes
• full support for option page
• support for PHP- & database-based ACF config
• toArray() and toJson() work recursively even on nested repeaters/ other fields (since 1.6)

Basic usage

The easiest way to create the acf relations is the included trait:

This dynamically creates the relationships acf_title() and acf_thumbnail(). Acf fields can now be accessed:

To make things easier, AcfTrait also includes getAcfAttribute, which returns an instance of the helper class Acf (this replaces the outdated corcel acf plugin from https://github.com/corcel/acf). Relation can also be accessed like:

PHP-based ACF config

If your ACF configuration works via PHP, you can must pass the config array in AcfTrait:

To determine which model is used for which field, the acf field's type variable is used. See below for a full list.

Functionality

Wordpress stores the config of each acf field in the table wp_posts as a custom post type acf-field. post_content contains the serialized config array, which contains the acf field type (type) and everything else you can specify when creating acf fields. Some of these values are important for parsing, some only specify things on how to display the field in wordpress itself.

When a post is saved in Wordpress with acf fields, those values are stored as the post's meta data in the table wp_postmeta. Each acf field saves two values: the according acf field name in wp_posts and the actual value. Depending on the acf field type and configuration, the saved value differs (text field values are stored as plain text, relation fields like image as the attachment id, and repeater & flexible content fields as a whole bunch of different fields).

For instance, the example fields from above are saved like this:

When loading a post with corcel, the meta data is automatically retrieved from the database anyway. If the static propery $acfRelations is defined in the model's boot() method,

The base Acf class uses this data and passes it to all fields (and possibly subfields), so no extra queries are needed. Just relational fields like Image need another query to find the correct Attachment class (though if you are only interested in the attachment's id, you can access $post->acf->thumbnail()->internal_value and no additional query is used).

This just adds a getAcfAttribute() method, which returns an instance of the base Tbruckmaier\Corcelacf\Acf class (this overwrites the corcel-internal default support for the outdated Corcel acf plugin: https://github.com/corcel/acf/tree/. If you would like to use it in parallel, you can define the getAcfAttribute method by yourself with a different name)

Option page

Fields in ACF option pages can be used the same way, though it is a bit more tricky to instantiate the option page. The relevant field configs are stored in wp_posts with post_type acf-field and are all children of a acf-field-group (via post_parent). The field values are stored in wp_options, with a certain prefix (defaults to options).

First of all, we need to find the option page's acf-field-group. We can find its id in the url when editing the field group in Wordpress: /wp-admin/post.php?post=1016&action=edit. It can also be found by its slug or page title (see below)

The prefix is normally set in functions.php and defaults to options.

If anyone stumbles upon an easier solution for option pages, I am open for suggestions. Maybe there is a way to get the field group by passing the prefix, or the other way round?

Advanced usage

Custom field classes

You can use your own classes for certain field types to extend them with custom attributes & methods. Publish the configuration via artisan vendor:publish --provider='Tbruckmaier\Corcelacf\ServiceProvider' and fill in the class names in config/corcel-acf.php. You can overwrite existing field types or define new ones:

The custom classes should extend Tbruckmaier\Corcelacf\BaseField

Defining acf relations

Instead of using the model's boot() method to create relationships on the fly, one can also define them manually:

Whenever Corcel models are returned (for instance an Corcel\Model\Attachment class for an image), the corcel class mapping config is considered (see https://github.com/corcel/corcel#-custom-post-type).

Eager loading

If you want to eager-load acf fields, you can use the standard eloquent syntax. If the relationships are created from $acfRelations, do not forget to pass the prefix:

Fields

The following field types are supported (everything else just returns a Generic field):

Link

The link field reacts on the configured return value, so it returns either an array with title, text and url or just the url as string.

The field has a render() method, which renders a html tag. render() supports custom link text and custom attributes: render('<img src="img.jpg" />', ['class' => 'class-1']) returns <a href="#" target="_blank" class="class-1" title="acf title"><img src="img.jpg" /></a>

Tests with different php & laravel versions are defined in .github/workflows/ci.yml. They can be run locally via act

Licence

MIT License © Junior Grossi