PHPackages mcguffin/acf-wp-objects - 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. mcguffin/acf-wp-objects ActiveWordpress-plugin[Utility & Helpers](/categories/utility) mcguffin/acf-wp-objects ======================= Integrating WordPress and ACF 0.8.10(3mo ago)24244[1 issues](https://github.com/mcguffin/acf-wp-objects/issues)[3 PRs](https://github.com/mcguffin/acf-wp-objects/pulls)GPL-3.0-or-laterPHPPHP >=8.1.0 Since Oct 25Pushed 3mo ago6 watchersCompare [ Source](https://github.com/mcguffin/acf-wp-objects)[ Packagist](https://packagist.org/packages/mcguffin/acf-wp-objects)[ Docs](https://github.com/mcguffin/acf-wp-object.git)[ RSS](/packages/mcguffin-acf-wp-objects/feed)WikiDiscussions master Synced yesterday READMEChangelog (10)Dependencies (5)Versions (134)Used By (0) ACF-WP-Objects ============== [](#acf-wp-objects) Filling some gaps between WordPress and ACF. Features -------- [](#features) Integrate WordPress Objects objects into ACF. - **Edit WP-Post properties** with ACF fields: - Settings: blogname - Settings: blogdescription - Post: post\_title - Post: post\_excerpt - Post: post\_content - Post: post\_thumbnail - Post: attachments - Term: term\_name - Term: term\_description - Theme-Mod: custom\_logo - New **Field types**: - Post Type - Taxonomy - Image Size - Includer (include all fields from a different field group) - User Role - Sweet Spot (use with media) - Plugin Template Select (Selector for template file from plugin) - New **Location Rules**: - Post Type / Taxonomy is public / builtin / show\_ui / show\_in\_menu / show\_in\_nav\_menus - Post type supports - Editor is Classic / Block editor - WP Options page is General / Writing / Reading / Discussion / Media / Permalinks - Plugin Template Settings - Everywhere - **Choice fields**: get choices from a repeater, e.g. from an ACF options page - **Multisite**: - Add a network admin page with `acf_add_options_(sub_)page()`. Add `"network" => true,` to the page args (ACF Pro only – both plugins must be network-enabled) - **Styling**: - More compact styles in block editor sidebar - Add classes `no-head` and `no-sort` to repeaters - Add classes `seamless` and `no-label` to fields - Add class `button-group` to checkboxes (make them look like button groups) - **Page Layouts**: Generic flexible content field providing a location rule for field groups. Init `acf_add_page_layout('foobar')`, render with `acf_page_layouts('foobar')` - **JSON-Paths**: Save Field group JSON in custom places (like plugins) - **Localization**: Localize ACF Field labels through po-files - **ACF Options Page**: Optionally for Reset, Export and Import in the Backend and from [WPCLI](https://wp-cli.org). - **Tab Field** Open a tab by URL. Just append `#Tab Label` Installation ------------ [](#installation) ### Production (using Github Updater – recommended for Multisite) [](#production-using-github-updater--recommended-for-multisite) - Head over to [releases](../../releases) - Download 'acf-wp-objects.zip' - Upload and activate it like any other WordPress plugin - AutoUpdate will run as long as the plugin is active ### Development [](#development) - cd into your plugin directory - $ `git clone git@github.com:mcguffin/acf-wp-objects.git` - $ `cd acf-wp-objects` - $ `npm install` - $ `npm run dev` JSON-Paths ---------- [](#json-paths) Consider the follwing Scenario: You are using local json field groups in your theme. You want to override them in a child theme. Or alternatively, you have a plugin with an ACF dependency, incorporating field groups as local json. This will load and save ACF JSON from the subdirectory `path/to/json-files` inside the theme and child theme directory but only if the field group key is `group_my_fieldgroup_key`. ``` acf_register_local_json( 'path/to/json-files', // e.g. 'acf-json' in a theme function( $field_group ) { // callback // return true, if the field group JSON // should be saved at the given location return $field_group['key'] === 'group_my_fieldgroup_key'; }, [ // parent paths to check get_template_directory(), get_stylesheet_directory(), ] ); ``` Sweet Spot Field ---------------- [](#sweet-spot-field) An easy way to choose the right clipping for images having `object-fit: cover`. The easyest way to enable the Sweet Spot feature for all images is the following bit of php code, living in your Theme's `functions.php` or in a mu-plugin. ``` add_filter( 'acf_image_sweetspot_enable', '__return_true' ); ``` The plugin will then register a field group for image attachments including a sweet spot field and in the frontend add an inline style rule to the image attributes, e.g. `object-position: 12.3% 81.4%;`. [![Sweet Spot Field UI](.wporg/screenshot-1.png)](.wporg/screenshot-1.png) JSON I18n --------- [](#json-i18n) ACF provides support for WPML to localize Field groups. ACF WP Objects offers a different approach through `.po` files. ``` acf_localize_field_groups( 'my-textdomain', function( $field_group ) { // callback which should return true, if the field group // localization is available under the given textdomain return $field_group['key'] === 'group_my_fieldgroup_key'; }); ``` If you are using local json, here is a node script allowing you to extract the strings [`src/run/json-i18n.js`](src/run/json-i18n.js) and add them to a pot file: Install [WP CLI](https://wp-cli.org/). Place `src/run/json-i18n.js` and `src/run/lib/json-extract.js` in your package directory. Extract strings from json files and add them to a PHP file: ``` node ./src/run/json-i18n.js 'my-texdomain' ./path/to/json ./php-output.php ``` Generate pot with WP CLI: ``` wp i18n make-pot . languages/my-textdomain.pot --domain=my-textdomain ``` Template Files (ACF Pro only) ----------------------------- [](#template-files-acf-pro-only) 1. Filter template types ``` add_filter('acf_wp_objects_template_types', function( $types ) { $slug = 'foo-plugin'; $key = 'Items Template'; $theme_location = 'foo-plugin'; // will point to wp-content/themes//foo-plugin/ // default: $slug $plugin_location = 'templates'; // will point to wp-content/plugins/foo-plugin/templates/ // null: use default, false: no plugin location, string: custom location inside plugin $types[ $slug ] = [ 'header_key' => $key, 'theme_location' => $theme_location, 'plugin_location' => $plugin_location, ]; return $types; }); ``` WP Objects will scan for template files having a header key in theme and plugin locations. 2. Create a Template select field with name `my_fabulous_template`. Use it like this: `get_template_part( get_field('my_fabulous_template') );` 3. Place some template files in location ``` /* Items Template: List */ $settings = get_field('my_fabulous_template_settings'); ``` Page layouts (ACF Pro only) --------------------------- [](#page-layouts-acf-pro-only) Generate a flexible content field and turn field groups to Layouts. Ideal if you need an extendible Set of Layouts to choose from. 1. Add a layout section: ``` acf_add_page_layout([ 'title' => 'My Layout', 'name' => 'my-layout', ]); ``` 2. Create field groups. Set "Page Layouts" "equals" "My Layout" as a location, and enter a row layout slug at the very bottom. 3. Create template files in your theme corresponding to the slugs chosen above. Filenames should match `acf/layout-.php`. Don't forget to use `get_sub_field()`, you are inside a flexible content field! 4. In your page.php template file call this inside the loop: ``` acf_page_layouts( 'my-layouts' ); ``` Repeater Choices with repeater row return ----------------------------------------- [](#repeater-choices-with-repeater-row-return) ACF doesn't load the field groups in the frontend by default. To retrieve the value of a Repeater Choice in the frontend, ACF has to know about this. You can achieve this by adding `do_action( 'acf_wpo_load_fields' );` ACF Options Page ---------------- [](#acf-options-page) Some new options for `acf_add_options_page()` and `acf_add_options_sub_page()`. ``` acf_add_options_page([ 'import' => false, 'import_message' => __( 'Options Imported', 'acf-wp-objects' ), 'import_error_message' => __( 'Invalid Import Data', 'acf-wp-objects' ), 'import_button' => __( 'Import', 'acf-wp-objects' ), 'import_select_file' => __( 'Select File…', 'acf-wp-objects' ), 'export' => false, 'export_references' => false, 'export_button' => __( 'Export Settings', 'acf-wp-objects' ), 'reset' => false, 'reset_button' => __( 'Restore defaults', 'acf-wp-objects' ), 'reset_message' => __( 'Options Reset to Defaults', 'acf-wp-objects' ), ]); ``` ### Args [](#args) - **`import`** `Boolean` Enable Import feature - **`import_message`** `String` Message after sucessful import - **`import_error_message`** `String` Message after failed import - **`import_button`** `String` Import button label - **`import_select_file`** `String` Import file input label - **`export`** `Boolean|Array` Enable export feature. `true` will simply export values from the current options page. Passing an array of options page IDs will export from multiple options pages at once - **`export_references`** `Boolean` Whether to export referenced content like posts, images or terms - **`export_button`** `String` Export button label - **`reset`** `Boolen|String` Enable reset feature. Passing the path to a valid import file will import it. - **`reset_message`** `String` Message after a sucessful reset - **`reset_button`** `String` Reset button label ### Examples [](#examples) Enable import and export. ``` acf_add_options_page([ 'page_title' => 'Configure Foobar Options', 'menu_title' => 'Foobar Options', 'post_id' => 'foobar_options', 'parent_slug' => 'themes.php', 'menu_slug' => 'foobar-options', 'import' => true, 'export' => true, ]); ``` Enable reset too. ``` acf_add_options_page([ 'page_title' => 'Configure Foobar Options', 'menu_title' => 'Foobar Options', 'post_id' => 'foobar_options', 'parent_slug' => 'themes.php', 'menu_slug' => 'foobar-options', 'import' => true, 'export' => true, 'reset' => true, ]); ``` Enable reset and get values from an export file. ``` acf_add_options_page([ 'page_title' => 'Configure Foobar Options', 'menu_title' => 'Foobar Options', 'post_id' => 'foobar_options', 'parent_slug' => 'themes.php', 'menu_slug' => 'foobar-options', 'import' => true, 'export' => true, // pass file path to reset 'reset' => get_template_directory().'/foobar-defaults.json', ]); ``` ### WP-CLI [](#wp-cli) Create an export file ``` wp acf-options-page export foobar-options --pretty > wp-content/themes/my-theme/foobar-defaults.json ``` Import options from file ``` wp acf-options-page import wp-content/themes/my-theme/foobar-defaults.json ``` Reset options page. Regardless of the configuration passed to `acf_add_options_page()` this will not import the values from a file. Use `wp acf-options-page import` to do so. ``` wp acf-options-page reset foobar-options ``` ### Health Score 50 — FairBetter than 96% of packages Maintenance82 Actively maintained with recent releases Popularity18 Limited adoption so far Community14 Small or concentrated contributor base Maturity74 Established project with proven stability Bus Factor1 Top contributor holds 99.5% 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 ~17 days Recently: every ~26 days Total 130 Last Release 92d ago PHP version history (2 changes)0.2.0PHP >=5.6.0 0.6.28PHP >=8.1.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/2e32281e1b5f0cbc598ece29eae06589fc9ed6aeb4529f5dd927bf0641e42fa4?d=identicon)[mcguffin](/maintainers/mcguffin) --- Top Contributors [![mcguffin](https://avatars.githubusercontent.com/u/402988?v=4)](https://github.com/mcguffin "mcguffin (576 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (3 commits)") --- Tags pluginwordpress ### Code Quality Code StylePHP\_CodeSniffer ### Embed Badge ![Health badge](/badges/mcguffin-acf-wp-objects/health.svg) ``` [![Health](https://phpackages.com/badges/mcguffin-acf-wp-objects/health.svg)](https://phpackages.com/packages/mcguffin-acf-wp-objects) ``` ### Alternatives [iceicetimmy/acf-post-type-selector Post type selector for Advanced Custom Fields. 559.0k](/packages/iceicetimmy-acf-post-type-selector) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)