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
This package is not auto-updated.
Last update: 2025-07-02 10:06:51 UTC
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
- Fork the repository.
- Create a new branch for your feature or bugfix.
- Commit your changes and push the branch.
- Open a pull request.
License
This project is licensed under the MIT License. See the LICENSE
file for details.