Corcel Acf Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require wp4laravel/corcel-acf
   

   Ensure wp4laravel/corcel is also installed (Corcel is a Laravel package for WordPress).

2. Service Provider Add to config/app.php under providers:

   Wp4laravel\CorcelAcf\CorcelAcfServiceProvider::class,
   

3. Publish Config (Optional)

   php artisan vendor:publish --provider="Wp4laravel\CorcelAcf\CorcelAcfServiceProvider"
   

   Config file: config/corcel-acf.php.

4. First Use Case Fetch an ACF field from a WordPress post:

   use Wp4laravel\Corcel\Post;
   use Wp4laravel\CorcelAcf\Facades\Acf;
   
   $post = Post::find(1);
   $customField = Acf::getField('field_123abc', $post); // 'field_123abc' is your ACF field key
   

Implementation Patterns

Common Workflows

1. Fetching ACF Fields

   • Single Field:

     $title = Acf::getField('field_title', $post);
     

   • All Fields (returns associative array):

     $fields = Acf::getFields($post);
     

   • Flexible Content:

     $flexibleContent = Acf::getField('field_flexible', $post);
     // Process nested layouts/rows
     

2. Validation & Type Handling

   • Cast ACF fields to Laravel types (e.g., dates, booleans):

     $date = Acf::getField('field_date', $post)->castAsDateTime();
     

3. Integration with Eloquent

   • Extend Corcel models to auto-load ACF fields:

     use Wp4laravel\CorcelAcf\HasAcf;
     
     class CustomPost extends Post
     {
         use HasAcf;
     
         protected $acfFields = ['field_title', 'field_content'];
     }
     

     Now access fields directly:

     $post = CustomPost::find(1);
     $post->field_title; // No need for Acf::getField()
     

4. Repeater Fields

   • Iterate over repeater rows:

     $repeater = Acf::getField('field_repeater', $post);
     foreach ($repeater as $row) {
         $row['sub_field_key']; // Access sub-fields
     }
     

5. Relationships

   • Fetch related posts via ACF relationships:

     $relatedPosts = Acf::getField('field_related_posts', $post);
     // $relatedPosts is a collection of Post models
     

Gotchas and Tips

Pitfalls

1. Field Key vs. Name

   • Always use field keys (e.g., field_123abc) instead of field names (e.g., title) for reliability. Field names can change in the WordPress UI, but keys are stable.

2. Caching Quirks

   • ACF fields are cached by default. Clear cache after updates:

     php artisan corcel:clear-cache
     

   • Disable caching for dynamic fields (e.g., in config/corcel-acf.php):

     'cache' => false,
     

3. Flexible Content Depth

   • Nested layouts in Flexible Content may require recursive processing. Use Acf::getField() with the full layout key:

     $layout = Acf::getField('field_layout_123', $post, 'layout_key');
     

4. Post vs. User Context

   • ACF fields are context-aware. Ensure you’re fetching fields from the correct object (e.g., Post, User, or Term):

     // Wrong (if $user has no ACF fields)
     $user = User::find(1);
     Acf::getField('field_title', $user); // May return null
     

5. WordPress Multisite

   • If using multisite, specify the blog ID:

     Acf::setBlogId(2); // Switch to blog ID 2
     

Debugging Tips

1. Check Field Existence

   • Verify the field exists in WordPress (via ACF UI or wp_json_and_bail() in wp-admin/admin-ajax.php):

     Acf::hasField('field_123abc', $post); // Returns boolean
     

2. Log Raw ACF Data

   • Dump raw ACF data for debugging:

     dd(Acf::getRawField('field_123abc', $post));
     

3. Handle Missing Fields

   • Provide defaults to avoid errors:

     $value = Acf::getField('field_maybe_missing', $post, 'default_value');
     

Extension Points

1. Custom Field Types

   • Extend support for custom ACF field types by creating a custom resolver:

     Acf::extend('my_custom_field_type', function ($value, $field) {
         return processCustomValue($value);
     });
     

2. Event Hooks

   • Listen for ACF field updates via Corcel events:

     use Wp4laravel\CorcelAcf\Events\AcfFieldUpdated;
     
     AcfFieldUpdated::listen(function ($event) {
         // React to ACF field changes
     });
     

3. Bulk Operations

   • Use Acf::syncFields() to update fields in bulk:

     $posts = Post::where('status', 'publish')->get();
     Acf::syncFields($posts, ['field_title', 'field_content']);