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
FileProperty	Uploaded file (multipart)	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.

$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.

$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.

$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.

$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.

$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.

$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.

$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.

$prop = new BinaryProperty('file', 'Uploaded file content');

BinaryProperty describes binary data inside the request body. For an actual multipart/form-data upload use FileProperty — body properties are never populated from $_FILES.

FileProperty

For files uploaded as multipart/form-data. Unlike every other property the value does not live in a parameter bag but in the request’s file bag, so it is declared with addFileProperty() and validated by the FileValidator. Declaring at least one file property also switches the generated OpenAPI request body to multipart/form-data.

• setMaxSizeInBytes(?int): Rejects larger uploads with file_is_larger_than_max_size.
• setAllowedMediaTypes(string[]): Whitelist of media types. The type is detected from the file contents, the client supplied Content-Type is never trusted. An empty list accepts every type.

public static function getDocumentation(): ApivalkRequestDocumentation
{
    $documentation = new ApivalkRequestDocumentation();

    $file = new FileProperty('file', 'The document to archive');
    $file->setMaxSizeInBytes(32 * 1024 * 1024)
        ->setAllowedMediaTypes(['application/pdf']);

    $documentation->addFileProperty($file);
    $documentation->addBodyProperty(new StringProperty('document_type', 'The document type'));

    return $documentation;
}

Declared file properties are picked up by the DocBlock generator, which adds a file() shape to the request just like the body, query and path shapes. In the controller the file is then read from the file bag with typed access:

$file = $request->file()->file;      // ?File, typed through the generated file shape
$contents = $file->getContents();

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.

$prop = new SimpleArrayProperty('ids', 'Selected record IDs', SimpleArrayProperty::TYPE_INT);

In your response that backs:

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.