Skip to main content

​
Property Types

Apivalk provides several built-in property classes:
ClassDescriptionPHP TypeOpenAPI Type
StringPropertyPlain textual datastringstring
EnumPropertyString restricted to a setstringstring
IntegerPropertyWhole numbersintinteger
FloatPropertyDecimal numbersfloatnumber
DatePropertyDate values (YYYY-MM-DD)\DateTimestring
DateTimePropertyDate-time values (ISO 8601)\DateTimestring
BytePropertyBase64-encoded datastringstring
BinaryPropertyRaw binary datastringstring
BooleanPropertyTrue/False valuesboolboolean
SimpleArrayPropertyList of scalars (one-dimensional)int[] / string[] / float[] / bool[]array
ArrayPropertyList of objectsarrayarray
AbstractObjectPropertyNested object structurearrayobject

​
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');

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