cloakwp / acf-abstractions

0.0.24 2026-08-20 17:50 UTC

Requires

• php: >=8.4
• cloakwp/core: ^0.0
• composer/installers: ^2.2
• vinkla/extended-acf: dev-feat/v15-cloakwp-deltas as 15.1.0

Requires (Dev)

• phpunit/phpunit: ^11.0 || ^12.0

LGPL-3.0-only

Published on Packagist.org on 2026-08-20 17:51 UTC

README

A set of OOP abstractions around ACF to improve developer experience.

This package is meant to be used alongside the wonderful vinkla/extended-acf package, which provides OOP abstractions for registering fields. This package simply extends that package with some useful extras:

• Register ACF Groups with the FieldGroup class (a wrapper around vinkla/extended-acf's register_extended_field_group function)
• Register ACF Blocks with the Block class (all registered block instances become accessible via the BlockRegistry singleton)
• Register ACF Options Pages with the OptionsPage class
• Conditional Choices — a conditionalChoices() macro for Select/Radio/Checkbox/Button Group fields that show/hide individual choices based on another field’s live value (see docs/conditional-choices.md)
• Query — a reusable Group field for selecting/filtering posts and injecting the resolved results into a block’s REST payload (see docs/query-field-set.md)
• Some useful, special fields that extend ACF's built-in field types:
  • Query - An ACF Group (query by default) with automatic vs manual post selection, optional post-type / taxonomy / limit / ordering controls, and REST injection via into() / mapUsing() / injectUsing(). Place it like any other field; use unique names for multiple instances.
  • InnerBlocks - An auto-populated ACF Flexible Content field enabling you to select/arrange ACF blocks (assuming you register your ACF blocks via this package's Block class). Assigning InnerBlocks as a field of an ACF block enables nesting blocks within each other for powerful block composability. You can control which blocks are available for selection on a per-instance basis via the includes and excludes methods.
  • HorizontalAlignment - An auto-populated ACF Button Group field with options for left, center, right, and justify (displayed as icons). You can control which of those 4 options are available on a per-instance basis.
  • VerticalAlignment - An auto-populated ACF Button Group field with options for top, center, and bottom (displayed as icons). You can control which of those 3 options are available on a per-instance basis.
  • MenuSelect - An auto-populated ACF Select field allowing you to select a registered WordPress menu.
  • PostTypeSelect - An auto-populated ACF Select field allowing you to select a registered WordPress post type.
  • ThemeColorPicker - An auto-populated ACF Radio Button field allowing you to select a color from the active theme's theme.json color palette, with special CSS styling to mimic the built-in Gutenberg color picker.
  • ResponsiveField - Enable screen breakpoint-specific values for any ACF field by simply wrapping it in a ResponsiveField instance (eg. ResponsiveField::make(Number::make('Gap'))). Under-the-hood, it uses a Group and set of Tab fields, and duplicates the provided field for each breakpoint tab. The resulting value output is your_field_name: { mobile: '1', tablet: '2', tablet_wide: '3', laptop: '4', desktop: '5', desktop_wide: '6' }. You can define which breakpoints are available on a per-instance basis.

Installation

composer require cloakwp/acf-abstractions

Usage

Docs coming soon -- for now, see the source code of this package's src directory; it's mostly self-documenting.

Block registration integrations

Use onRegister() to attach an integration when a block is registered. The callback receives the registered block, so it can read the name from its metadata without duplicating the name in another feature. Each callback runs once per block instance, after its value filter and field-group registration are wired.

Block::make(__DIR__ . '/block.json')
  ->onRegister(function (Block $block): void {
    MyIntegration::register($block);
  })
  ->register();

See InnerBlocks layout loading for deferred definitions, value-aware parsing, editor templates, and integration escape hatches.