Acf Builder Laravel Package

Getting Started

First Steps

1. Installation

   composer require stoutlogic/acf-builder
   

   Publish the config file:

   php artisan vendor:publish --provider="StoutLogic\AcfBuilder\AcfBuilderServiceProvider" --tag="acf-builder-config"
   

2. Basic Setup

   • Define a field group in a dedicated FieldGroup class (e.g., app/Acf/FieldGroups/PageHero.php):

     use StoutLogic\AcfBuilder\FieldsBuilder;
     
     class PageHero extends FieldsBuilder
     {
         public function getTitle()
         {
             return 'Page Hero Settings';
         }
     
         public function setup()
         {
             $this->setLocation('post_type', '==', 'page');
             $this->setLocation('post_status', '==', 'publish');
     
             $this->addField([
                 'label'        => 'Hero Image',
                 'instructions' => 'Upload a hero image for the page.',
                 'name'         => 'hero_image',
                 'type'         => 'image',
                 'required'     => 0,
             ]);
         }
     }
     

   • Register the field group in config/acf-builder.php:

     'field_groups' => [
         \App\Acf\FieldGroups\PageHero::class,
     ],
     

3. Sync Fields Run the Artisan command to push fields to ACF:

   php artisan acf:builder:push
   

4. Access Fields in Templates Use get_field() or get_sub_field() in Blade:

   $heroImage = get_field('hero_image');
   <img src="{{ $heroImage['url'] }}" alt="{{ $heroImage['alt'] }}">
   

Implementation Patterns

Common Workflows

1. Dynamic Field Groups

   • Use conditional logic in setup() to dynamically adjust fields:

     public function setup()
     {
         $this->addField([
             'name'    => 'featured_product',
             'type'    => 'post_object',
             'post_type' => ['product'],
         ]);
     
         if ($this->getOption('show_variations')) {
             $this->addField([
                 'name'    => 'product_variations',
                 'type'    => 'repeater',
                 'sub_fields' => [
                     ['name' => 'variation_title', 'type' => 'text'],
                 ],
             ]);
         }
     }
     

2. Reusable Field Logic

   • Extract repeated field configurations into methods:

     protected function addImageField($name, $label)
     {
         $this->addField([
             'name'    => $name,
             'label'   => $label,
             'type'    => 'image',
             'return_format' => 'array',
         ]);
     }
     

3. Integration with Eloquent

   • Attach fields to models via hasMany or morphTo:

     // In a model (e.g., Post.php)
     public function acfFields()
     {
         return $this->morphMany(\App\Models\AcfField::class, 'fieldable');
     }
     

   • Use acf() helper to fetch fields:

     $post->acf()->where('name', 'hero_image')->first();
     

4. Localization Support

   • Add language-specific fields:

     $this->addField([
         'name'    => 'title',
         'type'    => 'text',
         'label'   => __('Title', 'lang'),
         'instructions' => __('Enter the title in your language.', 'lang'),
     ]);
     

5. Field Group Inheritance

   • Extend base field groups for shared configurations:

     class BaseContent extends FieldsBuilder
     {
         public function setup()
         {
             $this->addField(['name' => 'content', 'type' => 'wysiwyg']);
         }
     }
     
     class BlogPost extends BaseContent
     {
         public function setup()
         {
             parent::setup();
             $this->addField(['name' => 'excerpt', 'type' => 'textarea']);
         }
     }
     }
     
     

6. Modifying Nested Fields (New in v1.12.0)

   • Use getField() and getLayout() to modify or remove nested fields in Flexible Content or Repeater fields:

     public function setup()
     {
         $this->addField([
             'name'    => 'sections',
             'type'    => 'flexible_content',
             'layouts' => [
                 'hero' => [
                     'title' => 'Hero Section',
                     'sub_fields' => [
                         ['name' => 'sub_title', 'type' => 'text'],
                     ],
                 ],
             ],
         ]);
     
         // Modify nested field after setup
         $this->getLayout('hero')->getField('sub_title')->setLabel('Updated Subtitle');
     
         // Remove nested field using shorthand syntax
         $this->removeField('sections->hero->sub_title');
     }
     

Gotchas and Tips

Common Pitfalls

1. Field Name Conflicts

   • ACF field names must be unique across all field groups. Use namespacing (e.g., group_name_field) to avoid collisions.
   • Debug Tip: Run php artisan acf:builder:dump to list all registered fields.

2. Location Rules Overlap

   • Overlapping setLocation() rules may cause unexpected field visibility. Test with:

     php artisan acf:builder:validate
     

3. Caching Issues

   • Clear ACF cache after pushing changes:

     php artisan acf:builder:clear-cache
     

   • Disable caching during development in config/acf-builder.php:

     'cache' => false,
     

4. Field Type Limitations

   • Some ACF field types (e.g., google_map) require additional setup (e.g., API keys). Check the ACF docs for prerequisites.

5. Database Bloat

   • Repeater fields can bloat the database. Use limit in setup() to restrict entries:

     $this->addField([
         'name'    => 'gallery',
         'type'    => 'repeater',
         'limit'   => 10,
     ]);
     

6. Nested Field Modifications (v1.12.0)

   • Shorthand Syntax: The -> delimiter is used for nested field paths (e.g., sections->hero->sub_title). Avoid using . in field names to prevent unintended conflicts.
   • Backward Compatibility: Existing field names with . are unaffected. Future major versions may revisit the delimiter choice.

Debugging Tips

1. Log Field Group Errors Enable logging in config/acf-builder.php:

   'log' => [
       'enabled' => true,
       'path'    => storage_path('logs/acf-builder.log'),
   ],
   

2. Validate Field Groups Run the validator to catch syntax errors:

   php artisan acf:builder:validate
   

3. Inspect ACF JSON Dump the raw ACF JSON for a field group:

   php artisan acf:builder:dump --group="PageHero"
   

4. Nested Field Debugging

   • Use dd($builder->getLayout('layout_name')->getFields()) to inspect nested fields before modification.
   • Test changes in a staging environment first, as nested field modifications can have cascading effects.

Extension Points

1. Custom Field Types

   • Extend StoutLogic\AcfBuilder\FieldsBuilder to add custom field logic:

     class CustomFieldBuilder extends FieldsBuilder
     {
         public function addCustomField($config)
         {
             $this->fields[] = array_merge($config, [
                 'type' => 'custom_type',
             ]);
         }
     }
     

2. Pre/Post Push Hooks

   • Use service provider hooks to modify fields before pushing:

     // In AppServiceProvider
     public function boot()
     {
         AcfBuilder::extend(function ($builder) {
             $builder->addField(['name' => 'custom_field', 'type' => 'text']);
         });
     }
     

3. Dynamic Field Group Registration

   • Register field groups dynamically (e.g., from a database):

     $fieldGroups = \App\Models\FieldGroup::all();
     foreach ($fieldGroups as $group) {
         $class = "App\Acf\FieldGroups\\" . $group->name;
         if (class_exists($class)) {
             AcfBuilder::register($class);
         }
     }
     

4. Flexible Content Layout Modifications (New in v1.12.0)

   • Dynamically add, remove, or modify layouts in Flexible Content