Document Annotations
Cache behavior, collection mapping and validation of documents.
Overview
Document annotations define persistence mapping, Redis-backed document-cache eligibility, and per-property validation. Class-level cache and database annotations are resolved from the most concrete child class upwards.
Cacheable / NotCacheable
| Parameter | Type | Default | Behavior |
|---|---|---|---|
| Cacheable | class marker | none | Enable document caching. |
| NotCacheable | class marker | none | Disable document caching. |
The first cache annotation found while traversing from the concrete child class to its parents wins. Without either marker, document caching is disabled.
#[Cacheable]
class BaseProduct extends \Core\Document\Base {}
#[NotCacheable]
class Product extends BaseProduct {} // Caching disabled
Document Database
| Parameter | Type | Default | Behavior |
|---|---|---|---|
| collection | string | Required | Class of the associated APPNETOS Collection. |
The concrete child class can override the collection mapping of its parent. The referenced Collection must itself define its own Collection Database annotation.
use Core\Document\Annotation\Database;
#[Database(ProductCollection::class)]
class Product extends \Core\Document\Base {}
Validation
| Parameter | Type | Default | Behavior |
|---|---|---|---|
| required | bool | false | Require a value that is not null, empty string or empty array. |
| minLength | int|null | null | Minimum string length. |
| maxLength | int|null | null | Maximum string length. |
| minimum | int|float|null | null | Minimum numeric value. |
| maximum | int|float|null | null | Maximum numeric value. |
| pattern | string|array|null | null | Regular expression metadata; runtime currently validates string patterns only. |
| patternConfig | string|null | null | Configuration key for a regular expression. |
| format | string|null | null | Format metadata; runtime implements special email checking. |
| enum | array | [] | Allowed-value schema metadata; not enforced by the examined runtime validator. |
| example | mixed | null | Example for generated schema. |
| description | string|null | null | Description for generated schema. |
#[Validation(
required: true,
minLength: 3,
maxLength: 100,
pattern: '/^[a-z0-9-]+$/',
description: 'Unique product slug',
example: 'my-product'
)]
protected string|null $slug = null;
- Runtime validation and OpenAPI schema generation are separate consumers.
- Array-valued patterns and enum restrictions are represented in schema metadata, but not fully enforced by the examined runtime validator.
- Child-property validation metadata takes precedence over inherited metadata.