silvesterk/object-mapper

A simple PHP object mapping library with attribute support

v1.1.0 2025-06-03 11:39 UTC

Requires

• php: >=8.1

Requires (Dev)

• phpunit/phpunit: ^12.1

MIT

• Silvester Kokai

README

A PHP library for mapping properties between objects with support for attributes and type safety.

Features

• Map properties from a source object to a target object.
• Support for custom property mapping using attributes.
• Handles uninitialized properties gracefully.
• Throws exceptions for type mismatches or mapping errors.

Requirements

• PHP 8.1 or higher
• Composer

Installation

Install the library using Composer:

composer require silvesterk/object-mapper

Usage

Basic Mutable Mapping

use Silvesterk\ObjectMapper\ObjectMapper;
use Silvesterk\ObjectMapper\Tests\TestClass\SourceTestClassWithNoAttributes;
use Silvesterk\ObjectMapper\Tests\TestClass\DestinationTestClass;

$source = new SourceTestClassWithNoAttributes();
$source->testProp = 42;

$destination = new DestinationTestClass();

ObjectMapper::map($source, $destination);

echo $destination->testProp; // Outputs: 42

Immutable Mapping

use Silvesterk\ObjectMapper\ObjectMapper;
use Silvesterk\ObjectMapper\Tests\TestClass\SourceTestClassWithNoAttributes;
use Silvesterk\ObjectMapper\Tests\TestClass\DestinationTestClass;

$source = new SourceTestClassWithNoAttributes();
$source->testProp = 42;

$destination = new DestinationTestClass();

$newDestination = ObjectMapper::mapImmutable($source, $destination);

echo $newDestination->testProp; // Outputs: 42

Mapping with Attributes

Use attributes to map properties with different names between source and target objects.

use Silvesterk\ObjectMapper\ObjectMapper;
use Silvesterk\ObjectMapper\Tests\TestClass\SourceTestClassWithTargetAttribute;
use Silvesterk\ObjectMapper\Tests\TestClass\DestinationTestClass;

class SourceTestClassWithTargetAttribute
{
    #[Target(propertyName: 'differentProp')]
    public ?int $testProp = null;
}


$source = new SourceTestClassWithTargetAttribute();
$source->testProp = 42;

$destination = new DestinationTestClass();
$mappedObject = ObjectMapper::mapImmutable($source, $destination);

echo $mappedObject->differentProp; // Outputs: 42

Handling Type Mismatches

If a property type mismatch occurs, an ObjectMapperException is thrown.

use Silvesterk\ObjectMapper\ObjectMapper;
use Silvesterk\ObjectMapper\Exception\ObjectMapperException;
use Silvesterk\ObjectMapper\Tests\TestClass\SourceTestClassWithWrongDataType;
use Silvesterk\ObjectMapper\Tests\TestClass\DestinationTestClass;


$source = new SourceTestClassWithWrongDataType();
$source->testPropInt = 'Invalid Type';

$destination = new DestinationTestClass();

try {
    ObjectMapper::mapImmutable($source, $destination);
} catch (ObjectMapperException $e) {
    echo $e->getMessage(); // Outputs the error message
}

Testing

Run the tests using PHPUnit:

vendor/bin/phpunit

Contributing

1. Fork the repository.
2. Create a new branch for your feature or bugfix.
3. Commit your changes and push the branch.
4. Open a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for details.