https://github.com/zero-to-prod/data-model-helper
Helper Methods for DataModels
https://github.com/zero-to-prod/data-model-helper
dto helper helpers php
Last synced: 3 months ago
JSON representation
Helper Methods for DataModels
- Host: GitHub
- URL: https://github.com/zero-to-prod/data-model-helper
- Owner: zero-to-prod
- License: mit
- Created: 2024-10-14T12:38:53.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-03-01T12:08:50.000Z (5 months ago)
- Last Synced: 2025-03-29T05:41:39.282Z (4 months ago)
- Topics: dto, helper, helpers, php
- Language: PHP
- Homepage: https://zero-to-prod.github.io/data-model-helper/
- Size: 232 KB
- Stars: 2
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# `Zerotoprod\DataModelHelper`
[](https://github.com/zero-to-prod/data-model-helper)
[](https://github.com/zero-to-prod/data-model-helper/actions)
[](https://packagist.org/packages/zero-to-prod/data-model-helper/stats)
[](https://packagist.org/packages/zero-to-prod/data-model-helper)
[](https://github.com/zero-to-prod/data-model-helper)
[](https://github.com/zero-to-prod/data-model-helper/blob/main/LICENSE.md)
Utilities for casting values using the [DataModel](https://github.com/zero-to-prod/data-model) package.
## Installation
Install the package via Composer:
```bash
composer require zero-to-prod/data-model-helper
```
### Additional Packages
- [DataModel](https://github.com/zero-to-prod/data-model): Transform data into a class.
- [DataModelFactory](https://github.com/zero-to-prod/data-model-factory): A factory helper to set the value of your `DataModel`.
- [Transformable](https://github.com/zero-to-prod/transformable): Transform a `DataModel` into different types.
## Quick Start
Here’s how to use the `mapOf` helper with all its arguments:
```php
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
'coerce' => true, // Coerce single elements into an array
'using' => [self::class, 'map'], // Custom mapping function
'map_via' => 'mapper', // Custom mapping method (defaults to 'map')
])]
public Collection $Aliases;
}
```
## Usage
### Including the Trait
Include the `DataModelHelper` trait in your class to access helper methods:
```php
class DataModelHelper
{
use \Zerotoprod\DataModelHelper\DataModelHelper;
}
```
### mapOf()
The `mapOf()` method returns an array of `Alias` instances.
```php
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
])]
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]->name; // Outputs: John Doe
echo $User->Aliases[1]->name; // Outputs: John Smith
```
#### Laravel Collection Example
The `mapOf` helper is designed to work will with the `\Illuminate\Support\Collection` class.
```php
class User
{
use \Zerotoprod\DataModel\DataModel;
use \Zerotoprod\DataModelHelper\DataModelHelper;
/** @var Collection $Aliases */
#[Describe([
'cast' => [self::class, 'mapOf'],
'type' => Alias::class,
])]
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
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.
```php
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
])]
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
Specify your mapping function by setting the `using` option.
```php
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
])]
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
By default, the map method is used to map over elements. You can specify a different method using the `map_via` option.
```php
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.
])]
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
```