> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apivalk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Property

> The Property System is the core metadata engine of Apivalk. It defines how data is structured, validated, and documented. Every property in your `getRequestDocumentation()` or `getResponseDocumentation()` is an instance of a class extending `AbstractProperty`.

## Property Types

Apivalk provides several built-in property classes:

| Class                    | Description                       | PHP Type                                    | OpenAPI Type |
| :----------------------- | :-------------------------------- | :------------------------------------------ | :----------- |
| `StringProperty`         | Plain textual data                | `string`                                    | `string`     |
| `EnumProperty`           | String restricted to a set        | `string`                                    | `string`     |
| `IntegerProperty`        | Whole numbers                     | `int`                                       | `integer`    |
| `FloatProperty`          | Decimal numbers                   | `float`                                     | `number`     |
| `DateProperty`           | Date values (YYYY-MM-DD)          | `\DateTime`                                 | `string`     |
| `DateTimeProperty`       | Date-time values (ISO 8601)       | `\DateTime`                                 | `string`     |
| `ByteProperty`           | Base64-encoded data               | `string`                                    | `string`     |
| `BinaryProperty`         | Raw binary data                   | `string`                                    | `string`     |
| `BooleanProperty`        | True/False values                 | `bool`                                      | `boolean`    |
| `SimpleArrayProperty`    | List of scalars (one-dimensional) | `int[]` / `string[]` / `float[]` / `bool[]` | `array`      |
| `ArrayProperty`          | List of objects                   | `array`                                     | `array`      |
| `AbstractObjectProperty` | Nested object structure           | `array`                                     | `object`     |

## Base Configuration

All properties share a common set of configuration methods:

* `setIsRequired(bool $required)`: Whether the property must be present.
* `setExample(string $example)`: A sample value for OpenAPI documentation.
* `addValidator(AbstractValidator $validator)`: Add custom validation logic.

## Specific Features

### `StringProperty`

* `setMinLength(int)` / `setMaxLength(int)`
* `setPattern(string)`: Regex validation.

```php theme={null}
$prop = new StringProperty('username', 'The login name');
$prop->setIsRequired(true)
     ->setMinLength(5)
     ->setMaxLength(10)
     ->setPattern('/^[a-z0-9]+$/');
```

### `EnumProperty`

Restricts a string value to a predefined set of allowed values. The enum values are passed as the third constructor argument.

* `setEnums(array)`: Update the list of allowed values.
* `setDefault(string)`: Set a default value.

```php theme={null}
$prop = new EnumProperty('status', 'Account status', ['active', 'inactive', 'suspended']);
$prop->setIsRequired(true);
```

### `IntegerProperty`

For whole numbers. Supports `int32` and `int64` formats (default: `int64`).

* `setMinimumValue(int)` / `setMaximumValue(int)`
* `setIsExclusiveMinimum(bool)` / `setIsExclusiveMaximum(bool)`
* `setFormat(string)`: `IntegerProperty::FORMAT_INT32` or `IntegerProperty::FORMAT_INT64`.

```php theme={null}
$prop = new IntegerProperty('age', 'User age', IntegerProperty::FORMAT_INT32);
$prop->setMinimumValue(0)
     ->setMaximumValue(150);
```

### `FloatProperty`

For decimal numbers. Supports `float` and `double` formats (default: `double`).

* `setMinimumValue(float)` / `setMaximumValue(float)`
* `setIsExclusiveMinimum(bool)` / `setIsExclusiveMaximum(bool)`
* `setFormat(string)`: `FloatProperty::FORMAT_FLOAT` or `FloatProperty::FORMAT_DOUBLE`.

```php theme={null}
$prop = new FloatProperty('price', 'Product price', FloatProperty::FORMAT_DOUBLE);
$prop->setMinimumValue(0.0)
     ->setIsExclusiveMinimum(true);
```

### `DateProperty`

Represents a date value in `YYYY-MM-DD` format. Automatically sets the OpenAPI format to `date` and includes a built-in pattern.

* `setDefault(string)`: Set a default date value.

```php theme={null}
$prop = new DateProperty('birth_date', 'Date of birth');
```

### `DateTimeProperty`

Represents a date-time value in ISO 8601 / RFC 3339 format. Automatically sets the OpenAPI format to `date-time` and includes a built-in pattern.

* `setDefault(string)`: Set a default date-time value.

```php theme={null}
$prop = new DateTimeProperty('created_at', 'Creation timestamp');
```

### `ByteProperty`

For base64-encoded data. Automatically sets the OpenAPI format to `byte`.

* `setMinLength(int)` / `setMaxLength(int)`
* `setPattern(string)`: Regex validation.

```php theme={null}
$prop = new ByteProperty('avatar', 'Base64-encoded avatar image');
```

### `BinaryProperty`

For raw binary data (e.g., file uploads). Automatically sets the OpenAPI format to `binary`.

* `setMinLength(int)` / `setMaxLength(int)`
* `setPattern(string)`: Regex validation.

```php theme={null}
$prop = new BinaryProperty('file', 'Uploaded file content');
```

### `SimpleArrayProperty`

For one-dimensional arrays of scalar values (e.g. `["ids" => [23, 41, 22]]`). Unlike `ArrayProperty`, it does **not** require an `AbstractObjectProperty` — you only declare the scalar item type, which is what gets written into the OpenAPI `items` schema.

The item type is passed as the third constructor argument:

* `SimpleArrayProperty::TYPE_INT` → OpenAPI `integer`, casts elements to `int`
* `SimpleArrayProperty::TYPE_STRING` → OpenAPI `string`, casts elements to `string` (default)
* `SimpleArrayProperty::TYPE_NUMBER` → OpenAPI `number`, casts elements to `float`
* `SimpleArrayProperty::TYPE_BOOL` → OpenAPI `boolean`, casts elements to `bool`

`setItemType(string)` can also change the type after construction.

```php theme={null}
$prop = new SimpleArrayProperty('ids', 'Selected record IDs', SimpleArrayProperty::TYPE_INT);
```

In your response that backs:

```php theme={null}
return ['ids' => [23, 41, 22]];
```

Each element is validated against the declared item type (a non-numeric element in an `int` array yields a `422`), and the value read back in the controller is cast to the item type — `["1", "2"]` on the wire becomes `[1, 2]`. Use `ArrayProperty` when the list holds objects rather than scalars.

### `ArrayProperty`

* `setItemProperty(AbstractProperty)`: Defines the type of items within the array.

### `AbstractObjectProperty`

* Used to define nested schemas. You extend this class and implement the `getPropertyCollection()` method to define the nested properties.

## Validation Integration

When a property is instantiated, it automatically creates a corresponding validator via the `ValidatorFactory`. This validator is used by the `RequestValidationMiddleware` to ensure incoming data matches your definitions.

Each property type has its own dedicated validator (e.g., `StringValidator`, `IntegerValidator`, `FloatValidator`, `EnumValidator`, `DateValidator`, `DateTimeValidator`, `ByteValidator`, `BinaryValidator`, `SimpleArrayValidator`), ensuring type-specific validation rules are applied automatically. `SimpleArrayValidator` additionally checks that every element matches the array's declared item type.