Versatile Object Mapper

The Versatile Object Mapper - or in short VOM - is a PHP library to transform any data structure into strictly typed models, by simply adding PHP attributes to model classes.

• Installation
• Quickstart
• Documentation
• Examples

Installation

VOM is available on packagist. To install, simply require it via composer.

composer require zolex/vom ^0.4

Plain PHP

When installed via composer or as a download from the releases page, you are ready to use VOM without a framework.

Symfony

When using symfony, the package also integrates as a bundle. With flex and autoconfiguration there is nothing else to do. You are ready to use the VOM Symfony Service. For the best interoperability, VOM implements the Symfony normalizer and denormalizer interfaces.

Without autoconfiguration, or if you choose to not run symfony/flex recipe generation, you have to enable the bundle manually by adding it to config/bundles.php.

<?php

return [
    // ...
    Zolex\VOM\Symfony\Bundle\ZolexVOMBundle::class => ['all' => true],
    // ...
];

Laravel

VOM also comes with a Laravel Service Provider. After installing with composer, the VersatileObjectMapper class is registered for Dependency Injection and can also be accessed using app(), resolve() etc. See the example for VOM in Laravel.

Quickstart

To give you a basic idea of what VOM does, here is a first short example.

Given, your application receives the following flat array of values from somewhere.

$data = [
    'firstname' => 'Jane',
    'surname' => 'Doe',
    'street' => 'Samplestreet 123',
    'city' => 'Worsthausen',
    'zip' => '12345',
    'country_name' => 'United Kingdom',
    'email_address' => 'jane.doe@coxautoinc.com',
    'phone' => '0123456789'
];

Usually you would write some code that creates the model instances, sets their properties and nests them properly. In very simple scenarios, writing the transformation logic as code might be a good choice, but it can be a pain when it comes to very huge models, the input data structures and/or application models change while still in development, or if you want to reuse the transformation logic in other projects too, because it receives the same inputs and/or uses the same models.

How it works using VOM

Instead of writing business logic that feeds your models, with VOM you simply configure the models using PHP attributes.

use Zolex\VOM\Mapping as VOM;

#[VOM\Model]
class Person
{
    #[VOM\Property]
    public string $firstname;
    
    #[VOM\Property('[surname]')]
    public string $lastname;
    
    #[VOM\Property(accessor: false)]
    public Address $address;
    
    #[VOM\Property(accessor: false)]
    public Contact $contact;
}

#[VOM\Model]
class Address
{
    #[VOM\Property]
    public string $street;
    
    #[VOM\Property('[zip]')]
    public string $zipCode;
    
    #[VOM\Property]
    public string $city;
    
    #[VOM\Property('[country_name]')]
    public string $country; 
}

#[VOM\Model]
class Contact
{
    #[VOM\Property('[email_address]')]
    public string $email;
    
    #[VOM\Property]
    public string $phone;
}

To create instances of your models, you simply pass the data to the denormalize() method.

$person = $objectMapper->denormalize($data, Person::class);

You may have noticed, that some property attributes have arguments while others don't. For all details on that, head to the full documentation.

Now, do I need this?

If there is any difference between the data structure of your input and your application's models, VOM may be a good choice to avoid writing and maintaining code, but instead just add some PHP attributes.

Note

If you need to inject data into your entities that already is in a structure matching your models, this library can be used but may be an overhead. In this scenario you could simply utilize a standard Symfony normalizer.

Documentation

The full documentation is available in the docs folder of this repository.

Examples

The example from the quickstart and more can be found in the VOM Examples repository.