PHPackages                             mvrk/icenberg - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. mvrk/icenberg

ActiveLibrary[Utility & Helpers](/categories/utility)

mvrk/icenberg
=============

Library to abstract away Advanced Custom Fields flexible content markup

v0.9.2(5mo ago)7592MITPHPPHP >=7.4

Since Jun 1Pushed 5mo ago2 watchersCompare

[ Source](https://github.com/maverick-international/Icenberg)[ Packagist](https://packagist.org/packages/mvrk/icenberg)[ RSS](/packages/mvrk-icenberg/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (2)Versions (45)Used By (0)

Icenberg 🥶
==========

[](#icenberg-)

- [Icenberg 🥶](#icenberg-)
    - [What is it?](#what-is-it)
    - [Getting Started](#getting-started)
        - [Initialise](#initialise)
        - [`Icenberg::__construct($layout, $prefix = 'block', $post_id = false)`](#icenberg__constructlayout-prefix--block-post_id--false)
    - [Using with ACF Flexible Content blocks](#using-with-acf-flexible-content-blocks)
    - [Using in an ACF Gutenberg Block](#using-in-an-acf-gutenberg-block)
        - [Icenberg Methods](#icenberg-methods)
            - [`get_element($field_name, $tag = 'div', $modifiers = [])`](#get_elementfield_name-tag--div-modifiers--)
            - [`the_element($field_name, $tag = 'div', $modifiers = [])`](#the_elementfield_name-tag--div-modifiers--)
            - [Global Options](#global-options)
            - [`enclose($class, array $elements, $tag = 'div', $attrs = [], $modifiers = [])`](#encloseclass-array-elements-tag--div-attrs---modifiers--)
    - [Values](#values)
    - [Conditionals and manipulations](#conditionals-and-manipulations)
        - [`field($field_name)`](#fieldfield_name)
        - [`get($tag = 'div', $modifiers = [])`](#gettag--div-modifiers--)
        - [`prune(array $exclusions)`](#prunearray-exclusions)
        - [`only(array $inclusions)`](#onlyarray-inclusions)
        - [`is($value)`](#isvalue)
        - [`lessThan($value)` / `greaterThan($value)`](#lessthanvalue--greaterthanvalue)
    - [Special Fields](#special-fields)
        - [Google Maps Field](#google-maps-field)
        - [`settings($field_name, $additional_classes = [])`](#settingsfield_name-additional_classes--)
        - [`get_buttons($field_name, $modifiers = [])` / `the_buttons($field_name, $modifiers = [])`](#get_buttonsfield_name-modifiers----the_buttonsfield_name-modifiers--)
    - [CLI](#cli)
        - [Available commands](#available-commands)
        - [Configuration](#configuration)
    - [Supported fields](#supported-fields)
        - [Full Support](#full-support)
        - [Third party fields:](#third-party-fields)
        - [Special Fields](#special-fields-1)
        - [VS Code Extension](#vs-code-extension)

### What is it?

[](#what-is-it)

Icenberg is an opinionated abstraction for ACF Fields in WordPress. It cleans up and simplifies ACF Flexible content and ACF Gutenberg block templates which often involve a lot of repetition and logic tangled up in presentation (in true WordPress style).

Using Icenberg's methods we can render acf fields complete with BEM classes and settings in a clean(er) object oriented fashion, while still allowing us to do things the old fashioned way if necessary.

[![icenberg logo](images/comparison.png)](images/comparison.png)

Icenberg requires ACF Pro and is primarily for internal use at Maverick, although it is easy to implement on any WordPress template using ACF fields. It also includes a convenient CLI for generating ACF Gutenberg blocks.

It is designed to be used primarily with flexible content fields and ACF Gutenberg blocks but works with any field including option fields. It could also work within other scenarios, in theory.

### Getting Started

[](#getting-started)

Install via composer:

```
composer require mvrk/icenberg
```

make sure autoloading is set up in functions.php - something like:

```
$composer_path = $_SERVER['DOCUMENT_ROOT'] . '/../vendor/';

if (file_exists($composer_path)) {

    require_once $composer_path . 'autoload.php';
}
```

Make sure you have ACF Pro installed. The library also supports [ACF Gravity forms](https://wordpress.org/plugins/acf-gravityforms-add-on/) plugin.

#### Initialise

[](#initialise)

```
use MVRK\Icenberg\Icenberg;

$ice = new Icenberg($layout = 'block_name', $prefix = 'block', $post_id = false);
```

#### `Icenberg::__construct($layout, $prefix = 'block', $post_id = false)`

[](#icenberg__constructlayout-prefix--block-post_id--false)

ArgumentTypeRequiredDescription`$layout`stringYesACF layout or block name`$prefix`stringNoPrefix used for classnames etc. Defaults to `'block'``$post_id`mixedNoOverride the default post ID. Defaults to `false`---

### Using with ACF Flexible Content blocks

[](#using-with-acf-flexible-content-blocks)

The following example takes place inside ACF's the\_row() - ie:

```
if (have_rows('content_blocks', $id)) :

    while (have_rows('content_blocks', $id)) : the_row();

        get_template_part('inc/blocks/block_template');

    endwhile;

endif;
```

Initialise with ACFs `get_row_layout()` in your block template:

```
use MVRK\Icenberg\Icenberg;

$ice = new Icenberg(get_row_layout());

$ice->the_element('quote');
$ice->the_element('attribution');
$ice->the_element('portrait');
```

Using in an ACF Gutenberg Block
-------------------------------

[](#using-in-an-acf-gutenberg-block)

Since v0.5.0 you can use Icenberg in an ACF gutenberg block, just pass the block title instead of the row layout. You can use the wrap method in a gutenberg block to wrap the block frontend in a similar way to how it is wrapped automatically by wp in the backend:

```
use MVRK\Icenberg\Icenberg;

$icenberg = new Icenberg(strtolower($block['title']));

$icenberg::wrap(
    [
        $icenberg->get_element('quote'),
        $icenberg->get_element('attribution'),
        $icenberg->get_element('portrait'),
    ],
    $block,
    true
);
```

### Icenberg Methods

[](#icenberg-methods)

#### `get_element($field_name, $tag = 'div', $modifiers = [])`

[](#get_elementfield_name-tag--div-modifiers--)

ArgumentTypeRequiredDescription`$field_name`stringYesThe ACF field name to render`$tag`stringNoThe HTML tag to wrap the element in. Defaults to `'div'``$modifiers`arrayNoAn array of modifiers to use as BEM classesReturns an ACF field as a formatted string, wrapped up in all the divs you need and with any special considerations applied. Takes the field name as an argument and optionally a tag for the uppermost element. If no tag is set it will use 'div'

```
$field_name = $ice->get_element('field_name');

echo $field_name;
```

#### `the_element($field_name, $tag = 'div', $modifiers = [])`

[](#the_elementfield_name-tag--div-modifiers--)

ArgumentTypeRequiredDescription`$field_name`stringYesThe ACF field name to echo`$tag`stringNoThe HTML tag to wrap the element in. Defaults to `'div'``$modifiers`arrayNoAn array of modifiers to use as BEM classesAs above, but echoes it out immediately.

```
$ice->the_element('field_name');
```

Icenberg is smart enough to know what a field's type is, so you don't need to differentiate, you just pass the field name in.

#### Global Options

[](#global-options)

To retrieve a global option simply pass a comma delimeted string to `the_element()` or `get_element()` - it must be all as one string as opposed to seperate args and it must be comma delimited, where the first part is the field name and the second part is the options name, eg

```
$ice->the_element('field_name, options');
```

#### `enclose($class, array $elements, $tag = 'div', $attrs = [], $modifiers = [])`

[](#encloseclass-array-elements-tag--div-attrs---modifiers--)

ArgumentTypeRequiredDescription`$class`stringYesClassname to apply to wrapper div (BEM modifiers will be appended automatically)`$elements`arrayYesArray of rendered HTML elements (e.g. `get_element()` results or strings)`$tag`stringNoThe HTML tag to wrap the element in. Defaults to `'div'``$attrs`arrayNoAn array of additional attributes to apply to the wrapper element`$modifiers`arrayNoAn array of modifiers to use as BEM classesEnclose is a utility for wrapping multiple icenberg fields in a container div without having to use a ?> anywhere. You just need to pass it a classname (without prefixes as these will be applied by icenberg). So clean!

So for example, in a 'Cta' block, where cta\_heading is a text field and cta\_content is a wysiwyg field:

```
$ice->enclose('text', [
    $ice->get_element('cta_heading')
    $ice->get_element('cta_content'),
]);
```

will generate:

```

                    I'm a heading, look at me!

                        sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

```

You could also pass any thing else you like to enclose as part of the array, as long as its storable as a variable (for example inserting a `get_template_part()` won't work here because it effectively prints the content).

```
$random_text = "I am some random text, isn't it wonderful?";

$ice->enclose('text', [
    $ice->get_element('cta_heading'),
    $random_text
]);
```

Of course life is never simple, so you will most likely need more complex layouts, but icenberg doesn't mind. You can insert it in html if you want to.

```

    the_element('motif_blurple');
    endif; ?>

```

Values
------

[](#values)

You can us the `value()` method to return the 'raw', value of a given field without checking for existence or specifiying if it is a sub field.

```
$lady_in_red = $ice->value('dancing_with_me');
```

as this just returns the value there are no special considerations for individual field types.

Conditionals and manipulations
------------------------------

[](#conditionals-and-manipulations)

#### `field($field_name)`

[](#fieldfield_name)

ArgumentTypeRequiredDescription`$field_name`stringYesName of the field to work withyou can use icenberg to evaluate fields and do some more comlplex field manipualtion too, using the `field()` method in conjucntion with the below methods. `field()` takes the field name as an argument and returns the icenberg instance for method chaining.

```
$ice->field($field_name)
```

#### `get($tag = 'div', $modifiers = [])`

[](#gettag--div-modifiers--)

ArgumentTypeRequiredDescription`$tag`stringNoTag to use for the wrapper. Defaults to `'div'``$modifiers`arrayNoAn array of modifiers to use as BEM classesReturns the icenbergified field html (in the same way as get\_element). Optionally pass a tag for the wrapper.

```
$ice->field('saxaphone')->get()
```

#### `prune(array $exclusions)`

[](#prunearray-exclusions)

ArgumentTypeRequiredDescription`$exclusions`arrayYesField names to exclude from the group/repeater outputpass an array of field names to the prune method to remove them from a group or from a repeater row.

```
$group = $ice->field('bad_singers')->prune(['chris_de_burgh', 'cliff_richard'])->get();
```

#### `only(array $inclusions)`

[](#onlyarray-inclusions)

ArgumentTypeRequiredDescription`$inclusions`arrayYesField names to include in the group/repeater output```
$group = $ice->field('great_singers')->only(['chris_de_burgh'])->get('marquee');
```

#### `is($value)`

[](#isvalue)

ArgumentTypeRequiredDescription`$value`mixedYesValue to compare against the field valuereturns true if the value of the field equals the argument passed to `is()`. You don't need to check for a fields existance before using these methods as they will do it for you and return `false` if they don't.

```
 if ($ice->field('font_colour')->is('red')) :
    $ice->the_element('font_colour');
else :
    echo 'oh no';
endif;
```

#### `lessThan($value)` / `greaterThan($value)`

[](#lessthanvalue--greaterthanvalue)

ArgumentTypeRequiredDescription`$value`intYesInteger to compare field value againstSelf explanatory, both take an integer as an argument. Warning: If you use it on a non numeric field it will return false.

```
if ($ice->field('range_test')->lessThan(51)) :
    $class = 'text_' . $ice->field('range_test')->field;
    $ice->enclose($class, [
        $ice->get_element('cta_content'),
        $ice->get_element('cta_image'),
    ]);
endif;
```

Special Fields
--------------

[](#special-fields)

#### Google Maps Field

[](#google-maps-field)

For the Google Maps field to work properly on front and backends you will need an API key. Once you have the key, add it to icenberg.yml in your project and the frontend will work. To make it work in the backend, add the following to your functions.php (in this example the key is defined in wp-config.php)

```
function acf_google_map_field($api)
{
    $api['key'] = GOOGLE_MAPS_API_KEY;

    return $api;
}
add_filter('acf/fields/google_map/api', 'acf_google_map_field');
```

#### `settings($field_name, $additional_classes = [])`

[](#settingsfield_name-additional_classes--)

ArgumentTypeRequiredDescription`$field_name`stringarrayYes`$additional_classes`arrayNoAdditional classnames to append as modifiersPass in a field group of settings and optionally an array of manually set classes and it will attach them as CSS modifier classes. if you include a text field called 'unique\_id' in your group icenberg will attach it as a id too.

Example using settings in `enclose()`:

```
$classes = ['banana', 'orange'];

$block_settings = get_sub_field($block_settings);

$settings = $ice->settings($block_settings, $classes);

$ice->enclose ($settings, [
    $ice->get_element('cheese_board'),
    $ice->get_element('flame_thrower')
])
```

or in regular php/html

```

    ...whatever you want

```

which will print out something like

```
"class='orange orange_padding_top_300 orange_skin_purple' id='cheese_board'"
```

Depending on the settings in your group.

#### `get_buttons($field_name, $modifiers = [])` / `the_buttons($field_name, $modifiers = [])`

[](#get_buttonsfield_name-modifiers----the_buttonsfield_name-modifiers--)

ArgumentTypeRequiredDescription`$field_name`stringYesField group name for buttons`$modifiers`arrayNoAn array of modifiers to use as BEM classesReturn a formatted group of buttons with a huge range of styles catered for - very Maverick specific.Expects our usual group of buttons format.

CLI
---

[](#cli)

you can now use the Icenberg CLI to rapidly bootstrap Icenberg blocks (since v0.5.0). This extends wp-cli so you need to have that installed and working first.

Add the below to your functions.php, after the autoload.

```
$is_wp_cli = defined('WP_CLI') && WP_CLI;

if ($is_wp_cli) {
    \MVRK\Icenberg\Commands\Bootstrap::setup();
}
```

### Available commands

[](#available-commands)

`wp icenberg block --block_name`

this bootstraps an ACF gutenberg block with all relevant files ready to go.

This assumes that your blocks are in a folder called 'blocks' in your template root directory but this is configurable via icenberg.yaml

Icenberg generates a folder per block within the blocks folder. This folder contains

- block.json
- <block\_name>.php
- <block\_name>.css

It will also register an empty field group ready for access via the ACF GUI.

`wp icenberg block --block_name --flexible`

this is similar to the above but creates just the php and scss files for flexible content blocks.

### Configuration

[](#configuration)

Config options are now available by placing an 'icenberg.yaml' file in your project's root directory. If this file doesn't exist or can't be parsed, icenberg will just go ahead and use its defaults.

Supported config options below with their default values:

```
block_directory_name: 'blocks' #change the default block directory name
sass_path: 'src/sass/blocks' #specify a location for sass partials
google_maps_api_key: ''
```

Supported fields
----------------

[](#supported-fields)

#### Full Support

[](#full-support)

- Gallery
- Group
- Image
- Link
- Number
- OEmbed
- Range
- Repeater
- Select
- Text
- Textarea
- Wysiwyg
- Relationship
- Post Object
- Page Link
- Google Maps

#### Third party fields:

[](#third-party-fields)

- Forms
- Swatch

#### Special Fields

[](#special-fields-1)

- Buttons
- Settings

### VS Code Extension

[](#vs-code-extension)

An extension with useful snippets is available for Virtual Studio Code.

[Icenberg Snippets](https://marketplace.visualstudio.com/items?itemName=coderjerk.icenberg-snippets&ssr=false#overview)

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance70

Regular maintenance activity

Popularity21

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 76.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~30 days

Recently: every ~50 days

Total

43

Last Release

171d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/42ca0d6cedc29ed4cc557e116aa1cdea8f1d55cd6374b3241068acc8c582cbb7?d=identicon)[Mvrk](/maintainers/Mvrk)

---

Top Contributors

[![danieldevine](https://avatars.githubusercontent.com/u/5939939?v=4)](https://github.com/danieldevine "danieldevine (70 commits)")[![cathal-maverick](https://avatars.githubusercontent.com/u/32732059?v=4)](https://github.com/cathal-maverick "cathal-maverick (21 commits)")

---

Tags

acfadvanced-custom-fieldsbemwordpressacfadvanced custom fieldsflexible-content

### Embed Badge

![Health badge](/badges/mvrk-icenberg/health.svg)

```
[![Health](https://phpackages.com/badges/mvrk-icenberg/health.svg)](https://phpackages.com/packages/mvrk-icenberg)
```

###  Alternatives

[hellonico/acf-country

A country field for ACF.

12193.2k](/packages/hellonico-acf-country)[vinkla/extended-acf

Register advanced custom fields with object-oriented PHP

503264.8k11](/packages/vinkla-extended-acf)[samrap/acf-fluent

A fluent interface for the Advanced Custom Fields WordPress plugin

28656.0k4](/packages/samrap-acf-fluent)[log1x/acf-editor-palette

A replica Gutenberg color picker field for Advanced Custom Fields.

100284.1k](/packages/log1x-acf-editor-palette)[log1x/acf-phone-number

A real ACF phone number field.

12072.5k](/packages/log1x-acf-phone-number)[mmirus/acf-flexible-content-title

Display the content of a field in the title bar of your Advanced Custom Fields flexible content sections.

362.8k](/packages/mmirus-acf-flexible-content-title)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)