# Model

> Typed model mapping for modern PHP applications

Package entry: `ui-awesome/model`. Requires PHP `^8.3`. Checked 2026-11-13. [View the entry in the package directory](</docs/packages/ui-awesome/model/index.md>)

**Typed model mapping for modern PHP applications**

_Nested properties, explicit input mapping, runtime defaults, custom casting, and selective key serialization_

## Features

![Feature Overview](https://raw.githubusercontent.com/ui-awesome/model/main/docs/svgs/features.svg)

## Installation

```bash
composer require ui-awesome/model:^0.2
```

## Quick start

```php
<?php

declare(strict_types=1);

namespace App\Model;

use UIAwesome\Model\Attribute\{Cast, DefaultValue, 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 = '';

    #[Trim]
    public string $name = '';

    #[Cast('array')]
    public array $tags = [];

    #[Timestamp]
    private int $updatedAt = 0;
}

$model = new User();

$model->load(
    [
        'User' => [
            'apiVersion' => 'v2',
            'displayName' => '',
            'name' => '  Ada Lovelace  ',
            'tags' => 'php, yii2, model',
            'user-email-address' => 'ada@example.com',
        ],
    ],
);

$types = $model->getTypes();
/*
[
    'apiVersion' => 'string',
    'displayName' => 'string',
    'name' => 'string',
    'email' => 'string',
    'tags' => 'array',
    'updatedAt' => 'timestamp',
]
*/
$payload = $model->toArray(snakeCase: true, exceptProperties: ['updatedAt']);
/*
[
    'apiVersion' => 'v2',
    'display_name' => 'Guest',
    'name' => 'Ada Lovelace',
    'email' => 'ada@example.com',
    'tags' => ['php', 'yii2', 'model'],
]
*/
```

## Explicit payload mapping with `MapFrom`

Use `#[MapFrom('external-key')]` when incoming payload keys do not follow snake_case or camelCase naming.

```php
<?php

declare(strict_types=1);

namespace App\Model;

use UIAwesome\Model\Attribute\MapFrom;
use UIAwesome\Model\BaseModel;

final class JsonLdPayload extends BaseModel
{
    #[MapFrom('@context')]
    public string $context = '';
}

$payload = new JsonLdPayload();

$payload->setValues(['@context' => 'https://schema.org']);
```

## Automatic input trimming with `Trim`

Use `#[Trim]` to normalize leading and trailing spaces for string values during assignment.

```php
<?php

declare(strict_types=1);

namespace App\Model;

use UIAwesome\Model\Attribute\Trim;
use UIAwesome\Model\BaseModel;

final class Profile extends BaseModel
{
    #[Trim]
    public string $displayName = '';
}

$profile = new Profile();

$profile->setValues(['display_name' => '  Ada Lovelace  ']);
```

## Forced custom casting with `Cast`

Use `#[Cast('array')]` to transform transport formats such as comma-separated strings.

```php
<?php

declare(strict_types=1);

namespace App\Model;

use UIAwesome\Model\Attribute\Cast;
use UIAwesome\Model\BaseModel;

final class SearchFilter extends BaseModel
{
    #[Cast('array')]
    public array $tags = [];
}

$filter = new SearchFilter();

$filter->setValue('tags', 'php, yii2, model');
```

## Runtime fallback with `DefaultValue`

Use `#[DefaultValue(...)]` to apply a fallback when input values are `null` or `''`.

```php
<?php

declare(strict_types=1);

namespace App\Model;

use UIAwesome\Model\Attribute\DefaultValue;
use UIAwesome\Model\BaseModel;

final class Profile extends BaseModel
{
    #[DefaultValue('Guest')]
    public string $displayName = '';
}

$profile = new Profile();

$profile->setValue('displayName', '');
// 'Guest'
```

## Preserve selected output keys with `NoSnakeCase`

Use `#[NoSnakeCase]` to keep specific property names unchanged when serializing with `snakeCase: true`.

```php
<?php

declare(strict_types=1);

namespace App\Model;

use UIAwesome\Model\Attribute\NoSnakeCase;
use UIAwesome\Model\BaseModel;

final class ApiPayload extends BaseModel
{
    #[NoSnakeCase]
    public string $apiVersion = 'v1';

    public string $publicEmailPersonal = 'admin@example.com';
}

$payload = new ApiPayload();

$data = $payload->toArray(snakeCase: true);
/*
[
    'apiVersion' => 'v1',
    'public_email_personal' => 'admin@example.com',
]
*/
```

## Documentation

For detailed configuration options and advanced usage.

- 📚 [Installation guide](https://github.com/ui-awesome/model/blob/main/docs/installation.md)
- ⚙️ [Configuration reference](https://github.com/ui-awesome/model/blob/main/docs/configuration.md)
- 💡 [Usage examples](https://github.com/ui-awesome/model/blob/main/docs/examples.md)
- 🧪 [Testing guide](https://github.com/ui-awesome/model/blob/main/docs/testing.md)
- 🔄 [Upgrade guide](https://github.com/ui-awesome/model/blob/main/UPGRADE.md)

## AI assistance

AI agents: read the [documentation index](https://yii2-framework.github.io/docs/llms.txt) and fetch the Markdown version
of a page by appending `index.md` to its URL. The
[AI agents guide](https://github.com/yii2-framework/docs/blob/main/src/content/docs/project/ai-agents.md) covers skill
installation, client setup and verification.

- 🤖 [`ui-awesome-model` skill](https://github.com/ui-awesome/model/blob/main/docs/agents.md):
  typed input mapping, property attributes, nested values with dot
  notation and model serialization.

See the [repository guides](#documentation), the [skill source](https://github.com/ui-awesome/model/blob/main/skills/ui-awesome-model/SKILL.md), the source PHPDoc and
the [changelog](https://github.com/ui-awesome/model/blob/main/CHANGELOG.md). This package is framework-independent; it is not a database model or a validation layer.

## Our social networks

[Follow on X](https://x.com/Terabytesoftw)
[Follow on Facebook](https://www.facebook.com/wilmer.arambula.9)

## License

[License](https://github.com/ui-awesome/model/blob/main/LICENSE)

## Package

- Source code and issues: [ui-awesome/model](https://github.com/ui-awesome/model). Star the repository if the package is useful to you.
- Composer package: [ui-awesome/model](https://packagist.org/packages/ui-awesome/model).
- Changelog: [CHANGELOG.md](https://github.com/ui-awesome/model/blob/main/CHANGELOG.md).