README

Framework-agnostic PHP utility library providing type casting and object hydration capabilities.

Features

TypeCaster: Automatic type conversion using PHP Reflection
- Scalar types (int, float, string, bool, array)
- DateTime/DateTimeImmutable
- Enum support
- Union type support
ObjectHydrator: Create objects from arrays with automatic type casting
- Constructor parameter mapping
- Default value support
- Nullable type support
- Full type safety

Requirements

PHP 8.3 or higher

Installation

composer require nora-lib/utils

Usage

TypeCaster

Convert values to specific types using Reflection type information:

use NoraLib\Utils\TypeCaster;
use ReflectionNamedType;

$caster = new TypeCaster();

// Get type from Reflection
$param = new ReflectionParameter([SomeClass::class, 'method'], 'paramName');
$type = $param->getType();

// Cast value
$result = $caster->cast('123', $type); // int(123)
$result = $caster->cast('true', $type); // bool(true)
$result = $caster->cast('2025-12-29', $type); // DateTime object

Supported Type Conversions

Scalar Types:

$caster->cast('123', $intType);        // int(123)
$caster->cast('123.45', $floatType);   // float(123.45)
$caster->cast(123, $stringType);       // string('123')
$caster->cast('true', $boolType);      // bool(true)
$caster->cast('yes', $boolType);       // bool(true)
$caster->cast('1', $boolType);         // bool(true)

DateTime:

$caster->cast('2025-12-29 10:00:00', $dateTimeType);
// DateTime object

$caster->cast(1735459200, $dateTimeType);
// DateTime from UNIX timestamp

$caster->cast('2025-12-29', $dateTimeImmutableType);
// DateTimeImmutable object

Enum:

enum Status: string {
    case Active = 'active';
    case Inactive = 'inactive';
}

$caster->cast('active', $enumType);
// Status::Active

ObjectHydrator

Create objects from arrays with automatic type casting:

use NoraLib\Utils\ObjectHydrator;
use NoraLib\Utils\TypeCaster;

$hydrator = new ObjectHydrator(new TypeCaster());

// Define your data class
readonly class User
{
    public function __construct(
        public string $name,
        public int $age,
        public DateTime $createdAt,
        public bool $active = true
    ) {}
}

// Hydrate from array
$data = [
    'name' => 'John Doe',
    'age' => '30',                    // string → int
    'createdAt' => '2025-12-29',      // string → DateTime
    'active' => 'yes'                 // string → bool
];

$user = $hydrator->hydrate(User::class, $data);

// Type-safe access
echo $user->name;       // 'John Doe'
echo $user->age;        // int(30)
echo $user->createdAt->format('Y-m-d'); // '2025-12-29'
echo $user->active;     // bool(true)

Advanced Usage

With Enum:

enum Role: string {
    case Admin = 'admin';
    case User = 'user';
}

readonly class Account
{
    public function __construct(
        public string $email,
        public Role $role
    ) {}
}

$account = $hydrator->hydrate(Account::class, [
    'email' => 'user@example.com',
    'role' => 'admin'  // string → Role::Admin
]);

With Nullable Types:

readonly class Profile
{
    public function __construct(
        public string $username,
        public ?string $bio = null,
        public ?DateTime $lastLogin = null
    ) {}
}

$profile = $hydrator->hydrate(Profile::class, [
    'username' => 'johndoe',
    'bio' => null,           // null allowed
    'lastLogin' => null      // null allowed
]);

Real-world Example: API Response Mapping

readonly class ApiResponse
{
    public function __construct(
        public int $statusCode,
        public array $data,
        public ?string $error = null,
        public DateTime $timestamp
    ) {}
}

$json = '{"statusCode":"200","data":{"users":[]},"timestamp":"2025-12-29T10:00:00Z"}';
$response = $hydrator->hydrate(ApiResponse::class, json_decode($json, true));

// Fully type-safe
if ($response->statusCode === 200) {
    // Process data
}

Development

Available Commands

composer test              # Run unit tests
composer tests             # Run tests with quality checks
composer coverage          # Generate coverage report
composer cs                # Check coding standards
composer cs-fix            # Fix coding style
composer sa                # Run static analysis (PHPStan)
composer build             # Full build with all checks

Running Tests

# Quick test
composer test

# With coverage
composer coverage

# Full quality check
composer tests

Documentation

API documentation is automatically generated and published via GitLab Pages:

📚 API Documentation

License

MIT

Contributing

Fork the repository
Create your feature branch
Write tests for your changes
Ensure all tests pass and coverage meets threshold (80%)
Submit a merge request

nora-lib / utils

Maintainers

Details