acf-objects: Turning ACF Arrays into Fluent PHP Objects

A surgical wrapper for Advanced Custom Fields that replaces array-juggling, null checks, and template clutter with objects, collections, Carbon dates, and Blade-powered renderers.

8 min read • View on GitHub • More from tombroucke

A wide editorial scene shows a WordPress template workspace being fed tangled slips of ACF field data into a mechanical press. On the other side, the machine outputs neat object cards, a calendar marked in Carbon-style date blocks, and a small collection ledger. The image explains how the library turns messy template inputs into structured PHP objects.
`acf-objects` does not merely prettify output. It changes the data contract between ACF and your template code.
Key Takeaways

The hidden cost of ACF arrays

ACF looks harmless until you meet the template code it produces. You start with a simple field, then you are checking nested keys, guarding against nulls, and repeating the same shape of defensive PHP everywhere.

That cost is not just verbosity. It changes how you think. Instead of working with a model, you are babysitting a return value.

<?php
$image = get_field('hero_image');

if ($image && isset($image['sizes']['large'])) {
    echo '<img src="' . esc_url($image['sizes']['large']) . '" alt="' . esc_attr($image['alt']) . '">';
}

This package converts the return values of ACF to objects with easy-to-use methods.

Tom Broucke, Maintainer · tombroucke/acf-objects - Packagist.org

What acf-objects changes

The promise is simple. A field becomes an object. A repeater becomes a collection. A date becomes Carbon. An image can render itself through a view instead of forcing you to assemble markup by hand.

Standard ACF template codeacf-objects
Raw arrays and magic strings.Fluent objects with methods that match the field type.
Repeated null checks and `isset()` branches.Fallback objects and default values reduce branch clutter.
Manual image and link markup.Renderable field objects and Blade views.
Repeaters handled as nested arrays.Repeaters behave like collections.
Dates are parsed ad hoc.Dates arrive as Carbon instances.

The library is not trying to make ACF look fashionable. It is trying to make ACF feel native to a modern PHP stack.

The interception trick

The clever part is that `acf-objects` does not wait until after ACF has already flattened everything into a useless shape. It marks the field with a `return_object` flag, routes the value through ACF’s formatting pipeline, and then intercepts the formatted result in its service provider.

The package’s trick is not post-processing. It is interception inside ACF’s own formatting path.

// Conceptually, the flow looks like this.
$field['return_object'] = true;

add_filter('acf/format_value', function ($value, $post_id, $field) {
    if (!empty($field['return_object'])) {
        return app('acf-objects.field')->make($field['type'], $value, $field);
    }

    return $value;
}, 10, 3);
A close-up editorial scene shows a hand inserting a small return_object tag into a stream of field packets passing through a narrow gate. On the far side, the packets split into labeled object paths for image, repeater, date, and fallback values. The image explains that the library changes behavior by intercepting ACF’s formatting path, not by wrapping output later.
The hidden flag is the switch. Once it is set, ACF’s own formatting hook becomes the conversion point.

Field objects as a fluent API

Once the value is converted, the API starts to feel deliberately designed. `Field.php` gives the shared behavior. Traits like `FetchesArrayValues` let field keys become methods, which means the surface area stays small even as the supported field types grow.

<?php
$image = AcfObjects::getField('hero_image');

$image->default('fallback.jpg');
$image->isSet();
$image->url('large');
$image->alt();
Shared behaviorEffect
`default()`Provides a fallback value without forcing template branches.
`isSet()`Lets templates check presence without touching the raw array.
Magic accessorsExpose array keys as method calls.
Collection supportMakes repeaters feel like native Laravel collections.

That is the nice part of the design. The package does not add more concepts than necessary. It standardizes access so the field type itself carries the behavior.

Why empty values do not explode

Null safety is where this kind of package proves its worth. The `FallbackField` pattern keeps empty values from turning into fatal errors, which is the difference between a graceful template and a late-night production fix.

<?php
$date = AcfObjects::getField('event_date');

if ($date->isSet()) {
    echo $date->format('F j, Y');
}

// No special casing for empty values.
// No call to format() on null.
Without acf-objectsWith acf-objects
Branch before every field access.Use object methods that encode the field’s behavior.
`null` can leak into templates.Fallback objects absorb empty states safely.
Every field type needs bespoke checks.Shared contracts handle the common cases.
The template owns the data cleanup.The field object owns its own safety rules.

Blade as the rendering layer

The package does not stop at data. It also lets fields render through Blade views, which matters because it moves markup decisions into one overrideable place. That is especially natural in the Roots and Acorn ecosystem.

<?php
$image = AcfObjects::getField('hero_image');

{!! $image->image('medium') !!}

$image->attributes([
    'class' => 'rounded-full',
    'data-lazy' => 'true',
])->image();

This is the real DX win. You get centralized rendering, but you do not lose the ability to override it. The object is fluent, and the view layer stays open.

Where it fits in the WordPress ecosystem

`acf-objects` is not a replacement for ACF, and it is not a page builder widget. It solves a narrower problem: how developers handle ACF data inside theme and plugin code when they want a Laravel-like experience.

ToolWhat it solvesWhere it lives
Standard ACF template codeNothing beyond raw field retrieval.Inside each template file.
acf-to-rest-apiExposing ACF data through the REST API.API layer and headless setups.
Elementor ACF widgetsDisplaying a specific ACF field in a builder UI.Builder-specific presentation.
acf-objectsFluent, object-oriented access to ACF data.Theme and plugin PHP code.

That positioning is why the project feels bigger than its footprint. It does not compete on breadth. It competes on the quality of the default developer experience.

Why this project feels bigger than it looks

The surface area is small, but the idea is not. `acf-objects` pulls a familiar Laravel pattern into WordPress without asking you to rewrite the whole stack. That makes it useful to one team, and suggestive to everyone else.

The package’s real achievement is not that it wraps ACF values. It changes the posture of the code around them. Instead of defensive template scripting, you get a domain-shaped object model that is harder to misuse.