# Advanced Custom Fields Field Validation System

This theme includes a custom validation system for ACF fields that allows you to define validation rules directly in your field entities.

## How to Use

### 1. Add Validation Rules to Field Entities

In your field entity class, add a `$validation` property with your validation rules:

```php
<?php
declare(strict_types=1);

namespace WP_AUX\Entities\AuxCF\OptionsFields;

use AuxCF\Entities\Field\TextFieldEntity;

class MyCustomFieldEntity extends TextFieldEntity
{
  public static string $name = 'my_custom_field';

  protected string $label = 'My Custom Field';

  protected string $instructions = 'Enter a value for this field.';

  // Define validation rules
  protected array $validation = [
    'required' => true,
    'regex' => '/^[A-Z]{2,5}$/'
  ];
}
```

### 2. Supported Validation Rules

The validation system supports the following rules:

#### Basic Rules
- `required` - (true or false - default is false) Field must not be empty
- `email` - Field must be a valid email address
- `url` - Field must be a valid URL
- `numeric` - Field must be a number

#### Length Rules
- `min:X` - Field must be at least X characters long
- `max:X` - Field must be no more than X characters long

#### Custom Regex Rules
- `regex:/pattern/` - Field must match the specified regex pattern

#### Multiple Rules
You can combine multiple rules in the array:

```php
protected array $validation = [
  'required' => true,
  'email' => true,
  'max' => 100
];
```

### 3. Example: Google Tag Manager ID Field

The GTM ID field demonstrates how to use regex validation with custom error messages:

```php
protected array $validation = [
  'required' => false,
  'regex' => '/^GTM-[A-Za-z0-9]{6,10}}$/',
  'custom_messages' => [
    'regex' => 'This value does not appear to be a valid Google Tag Manager ID.'
  ]
];
```

This ensures the field matches the GTM ID format (GTM- followed by 6-10 alphanumeric characters)

### 4. How It Works

1. The `ValidationService` scans all field entities in the theme
2. It extracts validation rules from the `$validation` property
3. It caches these rules by field key
4. When ACF validates a field, it calls our validation function
5. Our function applies the cached validation rules

### 5. Debugging

To debug validation issues, enable `WP_DEBUG` in your `wp-config.php`:

```php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
```

The validation service will log:
- Validation rules cache on initialization
- Field validation attempts
- Validation rules found for specific fields

### 6. Error Messages

The system provides user-friendly error messages that include:
- The field label
- Specific validation requirements
- Internationalization support

#### Custom Error Messages

You can define custom error messages directly in the validation array:

```php
class GtmFieldEntity extends TextFieldEntity
{
  protected array $validation = [
    'required' => true,
    'regex' => '/^GTM-[A-Za-z0-9]{6,10}$/',
    'custom_messages' => [
      'regex' => 'This value does not appear to be a valid Google Tag Manager ID.',
      'required' => 'GTM ID is required for tracking.',
    ]
  ];
}
```

**Supported rule keys for custom messages:**
- `required` - When field is empty
- `email` - When email format is invalid
- `url` - When URL format is invalid
- `numeric` - When value is not numeric
- `min` - When value is too short
- `max` - When value is too long
- `regex` - When regex pattern doesn't match

### 7. Extending the System

To add new validation rules, modify the `applyValidationRules()` method in `ValidationService.php`.

## Files Involved

- `inc/WP_AUX/Services/AuxCF/ValidationService.php` - Main validation service
- `inc/AuxCF/Entities/FieldEntity.php` - Base field entity with validation support
- `inc/AuxCF/AuxCF.php` - Main AuxCF class that initializes validation
- `inc/WP_AUX/Entities/AuxCF/OptionsFields/GtmFieldEntity.php` - Example field with validation 
