PHPackages                             arshpharala/advanced-custom-fields - 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. [Admin Panels](/categories/admin)
4. /
5. arshpharala/advanced-custom-fields

ActiveLibrary[Admin Panels](/categories/admin)

arshpharala/advanced-custom-fields
==================================

A powerful, beautiful, and easy-to-use custom fields system for Laravel with Admin UI, drag-and-drop sorting, and migrate:fresh-safe export/import.

v1.0.8(3mo ago)013MITPHPPHP ^8.1

Since Jan 30Pushed 3mo agoCompare

[ Source](https://github.com/arshpharala/advanced-custom-fields)[ Packagist](https://packagist.org/packages/arshpharala/advanced-custom-fields)[ RSS](/packages/arshpharala-advanced-custom-fields/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (10)Versions (10)Used By (0)

Advanced Custom Fields for Laravel
==================================

[](#advanced-custom-fields-for-laravel)

[![Latest Version on Packagist](https://camo.githubusercontent.com/9ba41fedde1f126dc6731ea48d93f81641a68dd5870e0b271de25a1ebffc8427/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6172736870686172616c612f616476616e6365642d637573746f6d2d6669656c64732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/arshpharala/advanced-custom-fields)[![Total Downloads](https://camo.githubusercontent.com/a437c88db7ef805ee8ca268a0445c8d38becb98b0ab95086e8cb0336757e8e61/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6172736870686172616c612f616476616e6365642d637573746f6d2d6669656c64732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/arshpharala/advanced-custom-fields)[![Laravel Version](https://camo.githubusercontent.com/8633a273624f91777568896aa34dea64c23830ccb4ec2b0879da059472f383a1/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d31302e7825323025374325323031312e7825323025374325323031322e782d7265642e7376673f7374796c653d666c61742d737175617265)](https://laravel.com)[![PHP Version](https://camo.githubusercontent.com/e9336ae887317cae5a4e64d0e124d6f05b4dbb6884cc8b50612238ad8d3a92ea/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e312b2d626c75652e7376673f7374796c653d666c61742d737175617265)](https://php.net)

Empower your Laravel application with a sophisticated, user-friendly, and developer-centric custom fields system. Inspired by WordPress ACF but rebuilt from the ground up for the modern Laravel ecosystem, this package provides a schema-less, highly performant way to manage content that doesn't belong in your core database tables.

---

Table of Contents
-----------------

[](#table-of-contents)

- [Why ACF++ for Laravel?](#why-acf-for-laravel)
- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Admin Panel](#admin-panel)
- [Configuration](#configuration)
- [Permissions & Security](#permissions--security)
- [Model Integration](#model-integration)
- [Rendering Fields](#rendering-fields)
- [Reading Values](#reading-values)
- [Querying & Filtering](#querying--filtering)
- [Locations & Rules](#locations--rules)
- [Field Types](#field-types)
- [Presentation & Theming](#presentation--theming)
- [Conditional Logic](#conditional-logic)
- [Export/Import & migrate:fresh Safety](#exportimport--migratefresh-safety)
- [Health & Recovery](#health--recovery)
- [Caching & Performance](#caching--performance)
- [Troubleshooting FAQ](#troubleshooting-faq)
- [Roadmap](#roadmap)
- [License](#license)

---

Why ACF++ for Laravel?
----------------------

[](#why-acf-for-laravel)

Laravel often forces a choice: either bloat your models with dozens of nullable columns or use a rigid EAV system. **Advanced Custom Fields** solves this by providing:

1. **Schema-less values**: Values live in a single polymorphic table, keeping your main tables clean.
2. **Powerful UI**: A plug-and-play admin interface for non-technical users.
3. **Developer Experience**: Fluent API, Blade directives, and exportable definitions that version-control perfectly.

---

Features
--------

[](#features)

### 💎 Admin UX

[](#-admin-ux)

- **Beautiful Dashboard**: Glassmorphism-inspired UI with Bootstrap 5 and Alpine.js.
- **Drag & Drop**: Reorder fields effortlessly using integrated SortableJS.
- **Search & Filter**: Find field groups instantly in large-scale setups.
- **Contextual Management**: Manage fields directly where they are used.

### 🛠️ Developer DX

[](#️-developer-dx)

- **Fluent Trait**: Simple `use HasAdvancedCustomFields` on any Eloquent model.
- **Blade Components**: `` handles all input rendering and validation.
- **Global Helpers**: Access data anywhere with `acf($model, 'key')`.
- **Eager Loading**: Prevents N+1 issues when fetching custom data.

### 🛡️ Safety & Stability

[](#️-safety--stability)

- **Export/Import Engine**: Definitions move from DB to JSON, making `migrate:fresh` painless for teams.
- **Soft Deletes**: Field groups and fields are never destroyed accidentally.
- **Mismatch Detection**: Real-time warnings if your database is out of sync with your JSON definitions.

### ⚡ Performance

[](#-performance)

- **Optimized SQL**: Polymorphic queries are indexed and eager-load friendly.
- **Tag-based Caching**: Instant retrieval of field definitions.

---

Requirements
------------

[](#requirements)

- PHP 8.1 or higher
- Laravel 10.x, 11.x, or 12.x
- Bootstrap 5 or Tailwind CSS (for Admin UI)

---

Installation
------------

[](#installation)

### 1. Install via Composer

[](#1-install-via-composer)

```
composer require arshpharala/advanced-custom-fields
```

### 2. Run the Install Command

[](#2-run-the-install-command)

This command will publish the config, migrations, and assets, and run the initial migrations.

```
php artisan acf:install
```

### 3. Manual Publishing (Optional)

[](#3-manual-publishing-optional)

If you need to manually publish specific tags:

```
# Publish Config
php artisan vendor:publish --tag="acf-config"

# Publish Assets
php artisan vendor:publish --tag="acf-assets"

# Publish Views (for deep customization)
php artisan vendor:publish --tag="acf-views"
```

---

Quick Start (5-Minute Setup)
----------------------------

[](#quick-start-5-minute-setup)

1. **Create a Group**: Go to `/admin/advanced-custom-fields` and create "Product Details".
2. **Add a Field**: Add a "Technical Specifications" textarea with key `specs`.
3. **Set Location**: Set the rule to `Post Type == Product`.
4. **Attach Trait**: Add the trait to your model. ```
    use Arshpharala\AdvancedCustomFields\Traits\HasAdvancedCustomFields;

    class Product extends Model {
        use HasAdvancedCustomFields;
    }
    ```
5. **Render Form**: Add the component to your edit view. ```

    ```
6. **Read Value**: Use the helper in your frontend. ```
    {{ acf($product, 'specs') }}
    ```

---

Admin Panel
-----------

[](#admin-panel)

The Admin Panel is accessible via `/admin/advanced-custom-fields` by default.

### Available Screens:

[](#available-screens)

- **Field Groups**: List, search, and manage groups.
- **Group Editor**: Add fields, configure location rules, and sort via drag & drop.
- **Import/Export**: Handle JSON synchronization.
- **Health Check**: Detect orphan values and system issues.

Tip

You can change the route prefix and apply custom middleware (e.g., `auth`, `admin.only`) in the `config/advanced-custom-fields.php` file.

---

Configuration
-------------

[](#configuration)

```
return [
    /*
    |--------------------------------------------------------------------------
    | Admin Route Configuration
    |--------------------------------------------------------------------------
    */
    'route_prefix' => 'admin/advanced-custom-fields',
    'middleware' => ['web', 'auth'],

    /*
    |--------------------------------------------------------------------------
    | Theme & UI Presets
    |--------------------------------------------------------------------------
    | 'bootstrap5' (default) or 'tailwind'
    */
    'theme' => 'bootstrap5',

    /*
    |--------------------------------------------------------------------------
    | Export Configuration
    |--------------------------------------------------------------------------
    */
    'export_path' => storage_path('app/acf/definitions.json'),
    'auto_export' => false, // Automatically export on save (dev only)
];
```

---

Permissions & Security
--------------------------

[](#permissions--security)

### Defining Access

[](#defining-access)

Use a Laravel Gate to control who can access the ACF Admin UI.

```
// app/Providers/AuthServiceProvider.php
Gate::define('view-acf-admin', function ($user) {
    return $user->is_admin;
});
```

Then specify the middleware in `config/advanced-custom-fields.php`:

```
'middleware' => ['web', 'auth', 'can:view-acf-admin'],
```

### HTML Snippet Safety

[](#html-snippet-safety)

If using fields that allow HTML, ensure you sanitize output unless explicitly trusted.

```
{!! clean(acf($post, 'html_content')) !!}
```

---

Model Integration
-----------------

[](#model-integration)

Add the `HasAdvancedCustomFields` trait to any Eloquent model.

### API Reference

[](#api-reference)

- `acf(string $key, $default = null)`: Get a processed value.
- `setAcf(string $key, $value)`: Set a value (persists on save or via updateOrCreate).
- `syncAcf(array $values)`: Batch update values.
- `acfAll()`: Get all custom values for the model.
- `acfMeta(string $key)`: Get the raw `Value` model (includes locale/metadata).

---

Rendering Fields (Admin)
------------------------

[](#rendering-fields-admin)

### Blade Component

[](#blade-component)

The most common way to render fields on a model edit page.

```
{{-- Renders all groups assigned to the "normal" position for this model --}}

{{-- Renders for a create screen (no model instance yet) --}}

```

### Manual Rendering

[](#manual-rendering)

```
@foreach($product->acfGroups() as $group)
    {{ $group->name }}
    @foreach($group->fields as $field)
        {!! acf_field($field, $product) !!}
    @endforeach
@endforeach
```

---

Reading Values (Frontend Blade)
-------------------------------

[](#reading-values-frontend-blade)

### 1. Loop Through All Assigned Fields

[](#1-loop-through-all-assigned-fields)

Ideal for "Details" or "Specifications" tabs where you want to show everything assigned to the model.

```

    Specifications

        @foreach($product->acfAll() as $key => $value)
            @if($value)
                {{ ucfirst(str_replace('_', ' ', $key)) }}
                {{ is_array($value) ? implode(', ', $value) : $value }}
            @endif
        @endforeach

```

### 2. Access Specific Fields Individually

[](#2-access-specific-fields-individually)

Use the `@acf` directive or the `acf()` helper for fine-grained control.

```
{{-- Using the Directive (Best for simple strings/colors) --}}

    @acf($product, 'headline')

{{-- Using the Helper (Best for toggles and logic) --}}
@if(acf($product, 'show_sidebar'))
    ...
@endif

@foreach(acf($product, 'features', []) as $feature)
    {{ $feature }}
@endforeach
```

### 4. Repeater Fields

[](#4-repeater-fields)

Repeater fields allow you to create rows of content with sub-fields.

```
@if(have_rows('hero_slides', $product))

        @while(have_rows('hero_slides', $product))
            @php the_row('hero_slides', $product); @endphp

                {{ get_sub_field('caption') }}
                {{ get_sub_field('description') }}

        @endwhile

@endif
```

Note

`the_row()` advances the pointer and returns the row data. `get_sub_field()` retrieves values from the current row.

### 3. Accessing Field Metadata (Labels/Instructions)

[](#3-accessing-field-metadata-labelsinstructions)

If you need the **Label** instead of the Raw Key:

```
@php $field = $product->acfMeta('warranty_info'); @php

@if($field)

        {{ $field->name }}
        {{ $field->instructions }}
        {{ acf($product, 'warranty_info') }}

@endif
```

---

Querying & Filtering
------------------------

[](#querying--filtering)

ACF for Laravel provides powerful query scopes to filter models based on custom field values.

### Basic Filtering

[](#basic-filtering)

```
// Find all products with a 'rating' > 4
$topProducts = Product::whereAcf('rating', '>', 4)->get();

// Find products with 'color' in a list
$blueItems = Product::whereAcfIn('color', ['blue', 'navy', 'sky'])->get();
```

### Sorting & Ordering

[](#sorting--ordering)

```
// Order products by a custom 'priority' field
$ordered = Product::orderByAcf('priority', 'desc')->get();
```

### Advanced Eloquent Integration

[](#advanced-eloquent-integration)

```
// Combine with standard Eloquent queries and relationships
$products = Product::where('status', 'active')
    ->with('category')
    ->whereAcf('sale_price', '