README

A lightweight, dependency-free custom field engine for vanilla PHP applications — the flexibility of WordPress ACF, without WordPress.

Requirements

• PHP 7.4+ (tested on 8.3)
• MySQL or MariaDB
• pdo_mysql extension

Installation

Option A — no Composer:

require_once '/path/to/acf-core-php/autoload.php';

Option B — with Composer, add to your composer.json:

"repositories": [{ "type": "path", "url": "path/to/acf-core-php" }],
"require": { "yourvendor/acf-core-php": "*" }

Then load the schema once:

mysql -u youruser -p your_database < database/schema.sql

This creates three tables: acf_field_groups, acf_fields, acf_field_values.

Quick Start

use ACF\ACF;
use ACF\Exceptions\ValidationException;

// 1. Bootstrap (once per request)
ACF::configure([
    'host' => 'localhost', 'dbname' => 'my_app',
    'username' => 'db_user', 'password' => 'db_password',
], [
    'base_path' => __DIR__ . '/public/uploads/acf', // where files are written
    'base_url'  => '/uploads/acf',                  // public URL prefix
]);

// 2. One-time setup (run from a migration/seed script)
$groupId = ACF::createFieldGroup(['title' => 'Product Details', 'entity_type' => 'product']);
ACF::addField($groupId, ['label' => 'Price', 'name' => 'price', 'type' => 'number', 'required' => true]);

// 3. Render a form
echo ACF::renderForm('product', $productId, ['wrap_form' => true, 'form_attrs' => ['action' => '/save']]);

// 4. Save submitted data
try {
    ACF::save('product', $productId, $_POST, $_FILES);
} catch (ValidationException $e) {
    $errors = $e->getErrors(); // ['field_name' => ['message', ...]]
}

// 5. Read values back
$values = ACF::getValues('product', $productId);          // raw values
$display = ACF::getValues('product', $productId, true);   // template-ready (formatted dates, <img> tags, etc.)

See examples/full_integration_example.php for a complete worked example (bootstrap, setup, form, save handler, display template).

Supported Field Types

Adding a Custom Field Type

use ACF\FieldTypes\AbstractFieldType;

class ColorField extends AbstractFieldType
{
    public function render(array $field, $value = null): string { /* ... */ }
    public function validate(array $field, $value): array { /* ... */ }
    public function sanitize(array $field, $value) { /* ... */ }
    public function display(array $field, $value) { /* ... */ }
}

ACF::registerFieldType('color', ColorField::class);

See examples/CustomColorField.php for a full working example.

Core API Reference

Setup

• ACF::configure(array $dbConfig, ?array $uploadConfig = null)
• ACF::registerFieldType(string $type, string $className)

Field groups & fields

• ACF::createFieldGroup(array $data): int
• ACF::addField(int $groupId, array $data): int
• ACF::getFields(string $entityType, ?string $groupSlug = null): array
• ACF::updateFieldGroup() / deleteFieldGroup() / updateField() / deleteField()

Forms

• ACF::renderForm(string $entityType, ?int $entityId, array $options = []): string
  • options: group_slug, errors, wrap_form, form_attrs

Validation & saving

• ACF::validate(string $entityType, array $postData, array $files = []): array — error array, empty if valid
• ACF::save(string $entityType, int $entityId, array $postData, array $files = []): bool — throws ValidationException on invalid data

Reading values

• ACF::getValue(string $entityType, int $entityId, string $fieldName, bool $forDisplay = false)
• ACF::getValues(string $entityType, int $entityId, bool $forDisplay = false): array
• ACF::deleteEntityValues(string $entityType, int $entityId): bool

Notes on File Uploads

• Stored values are relative paths (e.g. products/cover-64f2a1.png), built from UploadConfig's base_path/base_url.
• Re-saving a form without selecting a new file preserves the existing stored file — it won't be wiped.
• display() output for file/image fields returns ready-to-print <a>/<img> tags.

Styling

assets/acf.css has minimal default styles using plain class names (.acf-field, .acf-errors, etc.) — safe to override or ignore entirely if you're bringing your own design system.

Project Structure

acf-core-php/
├── autoload.php              # zero-dependency PSR-4-style autoloader
├── composer.json             # optional, if you prefer Composer's autoloader
├── database/schema.sql       # 3-table schema: field_groups, fields, field_values
├── src/
│   ├── ACF.php                # main facade — the class you'll actually call
│   ├── Core/                  # Database, FieldGroup, Field, FieldValue, UploadConfig
│   ├── FieldTypes/            # one class per field type + the factory/registry
│   ├── Validation/Validator.php
│   ├── Render/FormRenderer.php
│   └── Exceptions/
├── examples/
│   ├── full_integration_example.php
│   └── CustomColorField.php   # custom field type example
└── assets/acf.css