yeremi/schema-mapper

A PHP library for mapping external API data to PHP objects using PHP 8 attributes.

v1.0.1 2025-01-06 23:18 UTC

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.65.0
• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^9.5
• rector/rector: ^2@dev

MIT

• yeremi

• api
• attributes
• normalizer

README

A PHP library for mapping external API data to PHP objects using PHP 8 attributes. This library helps you easily transform API responses into strongly-typed PHP objects with minimal boilerplate code.

Index

1. Requirements
2. Installation
3. Basic Usage
4. Features
5. Error Handling
6. Examples
7. License
8. Support

Requirements

• PHP 8.0+

Installation

Install the package via Composer:

composer require yeremi/schema-mapper

Basic Usage

1. Define your data class with attributes:

use Yeremi\SchemaMapper\Attributes\ApiSchema;

class User
{
    #[ApiSchema(key: 'first_name')]
    private string $firstName;

    #[ApiSchema(key: 'last_name')]
    private string $lastName;

    #[ApiSchema(key: 'email')]
    private string $email;

    // Getters
    public function getFirstName(): string
    {
        return $this->firstName;
    }

    public function getLastName(): string
    {
        return $this->lastName;
    }

    public function getEmail(): string
    {
        return $this->email;
    }
}

1. Use the normalizer to map your data:

use Yeremi\SchemaMapper\Normalizer\NormalizerInterface;

class MyUseCase {
    public function __construct(
        NormalizerInterface $normalizer
    ) {}
    
    public function fetchSomeData(){
        $response = [
            'first_name' => 'John',
            'last_name' => 'Doe',
            'email' => '[e-mail]'
        ];

        $user = $this->normalizer->normalize($response, User::class);
        echo $user->getFirstName(); // Outputs: John
    }
}

Features

• Map API responses to PHP objects using attributes
• Support for nested objects
• Type validation
• Nullable properties support
• Dependency injection ready with interfaces

Error Handling

The library throws specific exceptions:

• TypeMismatchException: When the data type doesn't match the property type
• ReflectionException: When there are issues with class reflection

Examples

For more examples and advanced use cases, refer to the examples directory in the documentation.

License

This project is open source and licensed under the MIT License - see the LICENSE file for details.

Support

If you encounter any problems or have any questions, please open an issue.