Skip to content
PHP Ecosystem
Explore

Configuration reference

This content is not available in your language yet.

This guide describes model design conventions and behavior that affect runtime consistency.

Create models by extending BaseModel and declaring typed properties.

<?php
declare(strict_types=1);
namespace App\Model;
use UIAwesome\Model\Attribute\{Cast, DefaultValue, DoNotCollect, MapFrom, NoSnakeCase, Timestamp, Trim};
use UIAwesome\Model\BaseModel;
final class User extends BaseModel
{
#[NoSnakeCase]
public string $apiVersion = 'v1';
#[DefaultValue('Guest')]
public string $displayName = '';
#[MapFrom('user-email-address')]
public string $email = '';
#[DoNotCollect]
private string $internalToken = '';
#[Trim]
public string $name = '';
#[Trim]
public string $publicEmailPersonal = '';
#[Cast('array')]
public array $tags = [];
#[Timestamp]
private int $updatedAt = 0;
}
  • load(iterable $data, ?string $modelName = null) accepts scoped and unscoped payloads.
  • Input keys must match existing properties; undefined keys throw InvalidArgumentException.
  • load() and setValues() both support explicit input mapping via #[MapFrom('external-key')].
  • isEmpty() indicates whether loaded raw data is empty.
$model = new User();
$model->load(
[
'User' => [
'name' => 'Ada Lovelace',
'user-email-address' => 'ada@example.com',
],
],
);
  • Use getTypes() to retrieve collected property types.
  • Nullable properties include null in the collected metadata.
$types = $model->getTypes();
/*
[
'apiVersion' => 'string',
'displayName' => 'string',
'email' => 'string',
'name' => 'string',
'publicEmailPersonal' => 'string',
'tags' => 'array',
'updatedAt' => 'timestamp',
]
*/
  • setValue() assigns a single property and supports nested paths (profile.address.city).
  • setValues() assigns multiple values and converts snake_case input keys to camelCase.
  • #[MapFrom('key')] has priority over snake_case conversion for matching input payload keys.
  • #[Trim] trims string values before type casting and assignment.
  • #[DefaultValue(...)] applies runtime defaults when assigned values are null or ''.
  • #[Cast('array')] converts comma-separated strings into arrays before native property casting.
  • #[Cast(YourCaster::class)] supports custom casting classes implementing CastValueInterface.
  • setValues($data, $except) exclusions are evaluated in camelCase.
$model->setValues(
['public_email_personal' => 'dev@example.com'],
['publicEmailPersonal'],
);
$model->setValues(
['user-email-address' => 'dev@example.com'],
);
$model->setValue('displayName', '');
// displayName => 'Guest'
  • DateTime and DateTimeImmutable typed properties are cast automatically from string values.
  • Invalid date strings and overflow-normalized dates (for example 2026-02-30) throw InvalidArgumentException.
final class Article extends \UIAwesome\Model\BaseModel
{
public ?\DateTimeImmutable $publishedAt = null;
}
$article = new Article();
$article->setValue('publishedAt', '2026-03-01T10:00:00+00:00');
// $article->publishedAt is a DateTimeImmutable instance.
  • toArray(bool $snakeCase = false, array $exceptProperties = []) exports model data.
  • Use snakeCase: true to transform output keys.
  • #[NoSnakeCase] preserves marked property names when snakeCase: true is enabled.
$payload = $model->toArray(snakeCase: true, exceptProperties: ['updatedAt']);
/*
[
'apiVersion' => 'v1',
'display_name' => 'Guest',
'email' => 'dev@example.com',
'name' => 'Ada Lovelace',
'public_email_personal' => '',
'tags' => [],
]
*/