PHPackages                             zero-to-prod/data-model-helper - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. zero-to-prod/data-model-helper

ActiveLibrary[Utility & Helpers](/categories/utility)

zero-to-prod/data-model-helper
==============================

Helpers for a DataModel.

v82.1.2(5mo ago)416.0k↓28%111MITPHPPHP >=8.1.0CI passing

Since Oct 17Pushed 5mo ago1 watchersCompare

[ Source](https://github.com/zero-to-prod/data-model-helper)[ Packagist](https://packagist.org/packages/zero-to-prod/data-model-helper)[ Docs](https://github.com/zero-to-prod/data-model-helper)[ Fund](https://github.com/sponsors/zero-to-prod)[ RSS](/packages/zero-to-prod-data-model-helper/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (5)Versions (37)Used By (11)

Zerotoprod\\DataModelHelper
===========================

[](#zerotoproddatamodelhelper)

[![](art/logo.png)](art/logo.png)

[![Repo](https://camo.githubusercontent.com/9a90a3efeee26aed7d7f2feee9cd84566a26f9c362cc773b184d076210906e1c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6769746875622d677261793f6c6f676f3d676974687562)](https://github.com/zero-to-prod/data-model-helper)[![GitHub Actions Workflow Status](https://camo.githubusercontent.com/d0fc9a89151b399159b7d997443326c9263d5168b0550343cd96f208bf31ca75/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7a65726f2d746f2d70726f642f646174612d6d6f64656c2d68656c7065722f746573742e796d6c3f6c6162656c3d74657374)](https://github.com/zero-to-prod/data-model-helper/actions)[![GitHub Actions Workflow Status](https://camo.githubusercontent.com/c11289d61eeae8018087f3ed6254becc08c3986afdb650482bb754e1519fd50e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7a65726f2d746f2d70726f642f646174612d6d6f64656c2d68656c7065722f6261636b77617264735f636f6d7061746962696c6974792e796d6c3f6c6162656c3d6261636b77617264735f636f6d7061746962696c697479)](https://github.com/zero-to-prod/data-model-helper/actions)[![Packagist Downloads](https://camo.githubusercontent.com/ca030079eb8a8aa8e96dee212cb5a7b69adfc40c1e50080d1692c6e5dd2542f6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7a65726f2d746f2d70726f642f646174612d6d6f64656c2d68656c7065723f636f6c6f723d626c7565)](https://packagist.org/packages/zero-to-prod/data-model-helper/stats)[![php](https://camo.githubusercontent.com/e411ed96a6b1b243f96936dcba106e0d24788c48127f590c056e783c12136227/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f7a65726f2d746f2d70726f642f646174612d6d6f64656c2d68656c7065722e7376673f636f6c6f723d707572706c65)](https://packagist.org/packages/zero-to-prod/data-model-helper/stats)[![Packagist Version](https://camo.githubusercontent.com/188567afef856c9a5c626a53ac63666936cf8984dbd246de6a3d9966e9f49eb4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7a65726f2d746f2d70726f642f646174612d6d6f64656c2d68656c7065723f636f6c6f723d663238643161)](https://packagist.org/packages/zero-to-prod/data-model-helper)[![License](https://camo.githubusercontent.com/ff5d53c83da784b182642b6f68636498b6a1a24d513794469785fc2abd8c61f6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7a65726f2d746f2d70726f642f646174612d6d6f64656c2d68656c7065723f636f6c6f723d70696e6b)](https://github.com/zero-to-prod/data-model-helper/blob/main/LICENSE.md)[![wakatime](https://camo.githubusercontent.com/e997fd23f378b2448dadb2b4230434c974899061c8dcf10769c1a5ee09fb5661/68747470733a2f2f77616b6174696d652e636f6d2f62616467652f6769746875622f7a65726f2d746f2d70726f642f646174612d6d6f64656c2d68656c7065722e737667)](https://wakatime.com/badge/github/zero-to-prod/data-model-helper)[![Hits-of-Code](https://camo.githubusercontent.com/332b50f8b7b9b8748351646d2cb977250a07677a10673ffe3610b4fd768e2982/68747470733a2f2f686974736f66636f64652e636f6d2f6769746875622f7a65726f2d746f2d70726f642f646174612d6d6f64656c2d68656c7065723f6272616e63683d6d61696e)](https://hitsofcode.com/github/zero-to-prod/data-model-helper/view?branch=main)

Contents
--------

[](#contents)

- [Introduction](#introduction)
- [Requirements](#requirements)
- [Installation](#installation)
- [Documentation Publishing](#documentation-publishing)
    - [Automatic Documentation Publishing](#automatic-documentation-publishing)
- [Usage](#usage)
    - [Including the Trait](#including-the-trait)
- [Helper Methods](#helper-methods)
    - [when](#when): Create a map of any type by using
    - [mapOf](#mapof): Create a map of any type by using
    - [pregReplace](#pregreplace): Perform a regular expression search and replace.
    - [pregMatch](#pregmatch): Perform a regular expression match.
    - [isUrl](#isurl): Validates a url.
    - [isEmail](#isemail): Validates an email.
    - [isMultiple](#ismultiple): Validate a value is a multiple of another.
- [Local Development](./LOCAL_DEVELOPMENT.md)
- [Contributing](#contributing)

Introduction
------------

[](#introduction)

Utilities for casting values using the [DataModel](https://github.com/zero-to-prod/data-model) package.

Requirements
------------

[](#requirements)

- PHP 8.1 or higher.
- The [DataModel](https://github.com/zero-to-prod/data-model) Composer package

Installation
------------

[](#installation)

Install `Zerotoprod\DataModelHelper` via [Composer](https://getcomposer.org/):

```
composer require zero-to-prod/data-model-helper
```

This will add the package to your project’s dependencies and create an autoloader entry for it.

Documentation Publishing
------------------------

[](#documentation-publishing)

You can publish this README to your local documentation directory.

This can be useful for providing documentation for AI agents.

This can be done using the included script:

```
# Publish to default location (./docs/zero-to-prod/data-model-helper)
vendor/bin/zero-to-prod-data-model-helper

# Publish to custom directory
vendor/bin/zero-to-prod-data-model-helper /path/to/your/docs
```

#### Automatic Documentation Publishing

[](#automatic-documentation-publishing)

You can automatically publish documentation by adding the following to your `composer.json`:

```
{
  "scripts": {
    "post-install-cmd": [
      "zero-to-prod-data-model-helper"
    ],
    "post-update-cmd": [
      "zero-to-prod-data-model-helper"
    ]
  }
}
```

Usage
-----

[](#usage)

### Including the Trait

[](#including-the-trait)

Include the `DataModelHelper` trait in your class to access helper methods:

```
class DataModelHelper
{
    use \Zerotoprod\DataModelHelper\DataModelHelper;
}
```

Helper Methods
--------------

[](#helper-methods)

### `when`

[](#when)

Use `when` to call a function based on a condition.

```
class User
{
    use \Zerotoprod\DataModel\DataModel;
    use \Zerotoprod\DataModelHelper\DataModelHelper;

    #[Describe([
        'cast' => [self::class, 'when'],
        'eval' =>  [MyAction::class, 'passed'],  // Optional. Invoked when condition is true.
        'false' => [MyAction::class, 'failed'], // Optional. Invoked when condition is true.
        'required',                             // Throws PropertyRequiredException when value not present.
    ])]
    public string $value;
}
```

### `mapOf`

[](#mapof)

Create a map of any type by using the `DataModelHelper::mapOf()` method.

```
use Zerotoprod\DataModel\Describe;

class User
{
    use \Zerotoprod\DataModel\DataModel;
    use \Zerotoprod\DataModelHelper\DataModelHelper;

    /** @var Collection $Aliases */
    #[Describe([
        'cast' => [self::class, 'mapOf'], // Casting method to use
        'type' => Alias::class,           // Target type for each item
        'required',                       // Throws PropertyRequiredException when value not present
        'coerce' => true,                 // Coerce single elements into an array
        'using' => [self::class, 'map'],  // Custom mapping function
        'map_via' => 'mapper',            // Custom mapping method (defaults to 'map')
        'map' => [self::class, 'keyBy'],  // Run a function for that value.
        'level' => 1,                     // The dimension of the array. Defaults to 1.
        'key_by' => 'key',                // Key an associative array by a field.
    ])]
    public Collection $Aliases;
}
```

#### Usage

[](#usage-1)

In this case the `mapOf()` method returns an array of `Alias` instances.

This method will also work with enums.

```
use Zerotoprod\DataModel\Describe;

class User
{
    use \Zerotoprod\DataModel\DataModel;
    use \Zerotoprod\DataModelHelper\DataModelHelper;

    /** @var Alias[] $Aliases */
    #[Describe([
        'cast' => [self::class, 'mapOf'],  // Use the mapOf helper method
        'type' => Alias::class,            // Target type for each item
        'required',                        // Throws PropertyRequiredException when value not present
    ])]
    public array $Aliases;

    /** @var Name[] $Names */
    #[Describe([
        'cast' => [self::class, 'mapOf'],
        'type' => Name::class,
    ])]
    public ?array $Names;
}

class Alias
{
    use \Zerotoprod\DataModel\DataModel;

    public string $name;
}

enum Name: string
{
    case Tom = 'Tom';
    case John = 'John';
}

$User = User::from([
    'Aliases' => [
        ['name' => 'John Doe'],
        ['name' => 'John Smith'],
    ],
    'Names' => [
        'Tom',
        'John',
    ]
]);

echo $User->Aliases[0]->name; // Outputs: John Doe
echo $User->Aliases[1]->name; // Outputs: John Smith
echo $User->Names[0]; // Enum Name::Tom
echo $User->Names[1]; // Enum Name::John
```

#### Laravel Collection Example

[](#laravel-collection-example)

The `mapOf` helper is designed to work will with the `\Illuminate\Support\Collection` class.

```
use Zerotoprod\DataModel\Describe;

class User
{
    use \Zerotoprod\DataModel\DataModel;
    use \Zerotoprod\DataModelHelper\DataModelHelper;

    /** @var Collection $Aliases */
    #[Describe([
        'cast' => [self::class, 'mapOf'],
        'type' => Alias::class,
        'required', // Throws PropertyRequiredException when value not present
    ])]
    public \Illuminate\Support\Collection $Aliases;
}

class Alias
{
    use \Zerotoprod\DataModel\DataModel;

    public string $name;
}

$User = User::from([
    'Aliases' => [
        ['name' => 'John Doe'],
        ['name' => 'John Smith'],
    ]
]);

echo $User->Aliases->first()->name; // Outputs: John Doe
```

#### Coercing

[](#coercing)

Sometimes, an attribute may contain either a single element or an array of elements. By setting `'coerce' => true`, you can ensure that single elements are coerced into an array.

```
use Zerotoprod\DataModel\Describe;

class User
{
    use \Zerotoprod\DataModel\DataModel;
    use \Zerotoprod\DataModelHelper\DataModelHelper;

    /** @var Alias[] $Aliases */
    #[Describe([
        'cast'   => [self::class, 'mapOf'],
        'type'   => Alias::class,
        'coerce' => true, // Coerce single elements into an array
        'required',       // Throws PropertyRequiredException when value not present
    ])]
    public array $Aliases;
}

class Alias
{
    use \Zerotoprod\DataModel\DataModel;

    public string $name;
}

$User = User::from([
    'Aliases' => ['name' => 'John Doe'], // Single element instead of an array
]);

echo $User->Aliases[0]->name; // Outputs: John Doe
```

#### Using a Custom Mapping Function

[](#using-a-custom-mapping-function)

Specify your mapping function by setting the `using` option.

```
use Zerotoprod\DataModel\Describe;

class User
{
    use \Zerotoprod\DataModel\DataModel;
    use \Zerotoprod\DataModelHelper\DataModelHelper;

    /** @var Collection $Aliases */
    #[Describe([
        'cast'  => [self::class, 'mapOf'],
        'type'  => Alias::class,
        'using' => [self::class, 'map'], // Use custom mapping function
        'required',                      // Throws PropertyRequiredException when value not present
    ])]
    public Collection $Aliases;

    public static function map(array $values): Collection
    {
        // Map each value to an Alias instance
        $items = array_map(fn($value) => Alias::from($value), $values);

        // Return as a Collection
        return new Collection($items);
    }
}

class Alias
{
    use \Zerotoprod\DataModel\DataModel;

    public string $name;
}

class Collection
{
    public array $items;

    public function __construct(array $items = [])
    {
        $this->items = $items;
    }
}

$User = User::from([
    'Aliases' => [
        ['name' => 'John Doe'],
    ],
]);

echo $User->Aliases->items[0]->name; // Outputs: John Doe
```

#### Specifying a Custom Mapping Method

[](#specifying-a-custom-mapping-method)

By default, the map method is used to map over elements. You can specify a different method using the `map_via` option.

```
use Zerotoprod\DataModel\Describe;

class User
{
    use \Zerotoprod\DataModel\DataModel;
    use \Zerotoprod\DataModelHelper\DataModelHelper;

    /** @var Collection $Aliases */
    #[Describe([
        'cast'    => [self::class, 'mapOf'],
        'type'    => Alias::class,
        'map_via' => 'mapper', // Use custom mapping method for the `Collection` class.
        'required',            // Throws PropertyRequiredException when value not present
    ])]
    public Collection $Aliases;
}

class Alias
{
    use \Zerotoprod\DataModel\DataModel;

    public string $name;
}

class Collection
{
    public array $items;

    public function __construct(array $values)
    {
        $this->items = $values;
    }

    public function mapper(callable $callable): Collection
    {
        $this->items = array_map($callable, $this->items);
        return $this;
    }
}

$User = User::from([
    'Aliases' => [
        ['name' => 'John Doe'],
    ],
]);

echo $User->Aliases->items[0]->name; // Outputs: John Doe
```

#### Deep Mapping

[](#deep-mapping)

You can set the level for mapping deep arrays.

```
use Zerotoprod\DataModel\Describe;

class User
{
    use \Zerotoprod\DataModel\DataModel;
    use \Zerotoprod\DataModelHelper\DataModelHelper;

    /** @var Alias[] $Aliases */
    #[Describe([
        'cast' => [self::class, 'mapOf'],   // Use the mapOf helper method
        'type' => Alias::class,             // Target type for each item
        'level' => 2,                       // The dimension of the array. Defaults to 1.
        'required',                         // Throws PropertyRequiredException when value not present
    ])]
    public array $Aliases;
}

class Alias
{
    use \Zerotoprod\DataModel\DataModel;

    public string $name;
}

$User = User::from([
    'Aliases' => [
        [
            ['name' => 'John Doe'],
            ['name' => 'John Smith'],
        ]
    ]
]);

echo $User->Aliases[0][0]->name; // Outputs: John Doe
echo $User->Aliases[0][1]->name; // Outputs: John Smith
```

#### KeyBy

[](#keyby)

Key an array by an element value by using the `key_by` argument.

This also supports deep mapping.

Note: this only applies to arrays.

```
class User
{
    use \Zerotoprod\DataModel\DataModel;
    use \Zerotoprod\DataModelHelper\DataModelHelper;

    /** @var Alias[] $Aliases */
    #[Describe([
        'cast' => [self::class, 'mapOf'],
        'type' => Alias::class,
        'key_by' => 'id',
        'required', // Throws PropertyRequiredException when value not present
    ])]
    public array $Aliases;
}

class Alias
{
    use \Zerotoprod\DataModel\DataModel;

    public string $id;
    public string $name;
}

$User = User::from([
    'Aliases' => [
        [
            'id' => 'jd1',
            'name' => 'John Doe',
        ],
        [
            'id' => 'js1',
            'name' => 'John Smith'
        ],
    ]
]);

echo $User->Aliases['jd1']->name;  // 'John Doe'
echo $User->Aliases['js1']->name); // 'John Smith'
```

#### Map

[](#map)

Call a function for that value.

Note: This does not work with arrays.

```
class User
{
    use \Zerotoprod\DataModel\DataModel;
    use \Zerotoprod\DataModelHelper\DataModelHelper;

    /** @var Alias[] $Aliases */
    #[Describe([
        'cast' => [self::class, 'mapOf'],
        'type' => Alias::class,
        'map' => [self::class, 'keyBy'],
        'required', // Throws PropertyRequiredException when value not present
    ])]
    public Collection $Aliases;

    public static function keyBy(Collection $values): Collection
    {
        return $values->keyBy('id');
    }
}

class Alias
{
    use \Zerotoprod\DataModel\DataModel;

    public string $id;
    public string $name;
}

$User = User::from([
    'Aliases' => [
        [
            'id' => 'jd1',
            'name' => 'John Doe',
        ]
    ]
]);

echo $User->Aliases->get('jd1')->name;  // 'John Doe'
```

### `pregReplace`

[](#pregreplace)

Use `pregReplace` to perform a regular expression search and replace.

```
class User
{
    use \Zerotoprod\DataModel\DataModel;
    use \Zerotoprod\DataModelHelper\DataModelHelper;

    public const ascii_only = '/[^\x00-\x7F]/';

    #[Describe([
        'cast' => [self::class, 'pregReplace'],
        'pattern' => ascii_only,
        'replacement' => '!' // defaults to '' when not specified
        'required',          // Throws PropertyRequiredException when value not present
    ])]
    public string $name;
}

$User = User::from([
    'name' => 'Trophy🏆',
]);

echo $User->name; // Outputs: 'Trophy!'
```

### `pregMatch`

[](#pregmatch)

Use `pregMatch` to perform a regular expression match.

```
class User
{
    use \Zerotoprod\DataModel\DataModel;
    use \Zerotoprod\DataModelHelper\DataModelHelper;

    #[Describe([
        'cast' => [self::class, 'pregMatch'],
        'pattern' => '/s/', // Required
        'match_on' => 0 // Index of the $matches to return
        'flags' => PREG_UNMATCHED_AS_NULL
        'offset' => 0,
        'required', // Throws PropertyRequiredException when value not present
    ])]
    public string $name;
}

$User = User::from([
    'name' => 'sarah',
]);

echo $User->name; // Outputs: 's'
```

### `isUrl`

[](#isurl)

Use `isUrl` to validate an url.

```
class User
{
    use \Zerotoprod\DataModel\DataModel;
    use \Zerotoprod\DataModelHelper\DataModelHelper;

    #[Describe([
        'cast' => [self::class, 'isUrl'],
        'protocols' => ['http', 'udp'], // Optional. Defaults to all.
        'on_fail' => [MyAction::class, 'method'], // Optional. Invoked when validation fails.
        'exception' => MyCustomException::class, // Optional. Throws an exception when not url.
        'required'  // Optional. Throws \Zerotoprod\DataModel\PropertyRequiredException::class
    ])]
    public string $url;
}
```

### `isEmail`

[](#isemail)

Use `isEmail` to validate an email.

```
class User
{
    use \Zerotoprod\DataModel\DataModel;
    use \Zerotoprod\DataModelHelper\DataModelHelper;

    #[Describe([
        'cast' => [self::class, 'isEmail'],
        'on_fail' => [MyAction::class, 'method'], // Optional. Invoked when validation fails.
        'exception' => MyCustomException::class, // Optional. Throws an exception when not url.
        'required'  // Optional. Throws \Zerotoprod\DataModel\PropertyRequiredException::class
    ])]
    public string $url;
}
```

### `isMultiple`

[](#ismultiple)

Use `isMultiple` to validate a value is a multiple of another.

```
class User
{
    use \Zerotoprod\DataModel\DataModel;
    use \Zerotoprod\DataModelHelper\DataModelHelper;

     #[Describe([
         'cast' => [self::class, 'isMultiple'],
         'of' => 2                                  // The number the value is a multiple of
         'on_fail' => [MyAction::class, 'method'],  // Optional. Invoked when validation fails.
         'exception' => MyException::class,         // Optional. Throws an exception when not a valid email.
         'required',                                // Throws PropertyRequiredException when value not present.
     ])]
    public string $url;
}
```

Contributing
------------

[](#contributing)

Contributions, issues, and feature requests are welcome! Feel free to check the [issues](https://github.com/zero-to-prod/data-model-helper/issues) page if you want to contribute.

1. Fork the repository.
2. Create a new branch (`git checkout -b feature-branch`).
3. Commit changes (`git commit -m 'Add some feature'`).
4. Push to the branch (`git push origin feature-branch`).
5. Create a new Pull Request.

###  Health Score

47

—

FairBetter than 94% of packages

Maintenance69

Regular maintenance activity

Popularity31

Limited adoption so far

Community17

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~11 days

Recently: every ~66 days

Total

36

Last Release

179d ago

Major Versions

v81.11.7 → v82.0.22025-02-19

### Community

Maintainers

![](https://www.gravatar.com/avatar/502649f05d36c87d494988bd99193a4d908d345335d99c080928a726277371f5?d=identicon)[zero-to-prod](/maintainers/zero-to-prod)

---

Top Contributors

[![zero-to-prod](https://avatars.githubusercontent.com/u/61474950?v=4)](https://github.com/zero-to-prod "zero-to-prod (41 commits)")

---

Tags

dtohelperhelpersphpzero-to-proddata-model-helper

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/zero-to-prod-data-model-helper/health.svg)

```
[![Health](https://phpackages.com/badges/zero-to-prod-data-model-helper/health.svg)](https://phpackages.com/packages/zero-to-prod-data-model-helper)
```

###  Alternatives

[zero-to-prod/data-model

Transforms Data into Type-Safe DTOs.

14226.2k32](/packages/zero-to-prod-data-model)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)