PHPackages                             juliangut/mapping - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. juliangut/mapping

ActiveLibrary[Database & ORM](/categories/database)

juliangut/mapping
=================

Base for mapping support

1.4.3(1y ago)210.7k↓23.8%[2 PRs](https://github.com/juliangut/mapping/pulls)3BSD-3-ClausePHPPHP ^8.0CI passing

Since Oct 22Pushed 1y ago1 watchersCompare

[ Source](https://github.com/juliangut/mapping)[ Packagist](https://packagist.org/packages/juliangut/mapping)[ Docs](https://github.com/juliangut/mapping)[ GitHub Sponsors](https://github.com/juliangut)[ RSS](/packages/juliangut-mapping/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (12)Versions (20)Used By (3)

[![PHP version](https://camo.githubusercontent.com/6913801024bb6087176dec5fdb59388730a49b167cbb013222a7acbaecb48b7c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d253345253344382e302d3838393242462e7376673f7374796c653d666c61742d737175617265)](http://php.net)[![Latest Version](https://camo.githubusercontent.com/d449cb3102f0b55f79ad89b94186f97d0e1706f6199396c96c2310f875d0256c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a756c69616e6775742f6d617070696e672e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/juliangut/mapping)[![License](https://camo.githubusercontent.com/9123dff8323a729453160a727c150be38cdee5023806d3578f380e2da4a7127b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6a756c69616e6775742f6d617070696e672e7376673f7374796c653d666c61742d737175617265)](https://github.com/juliangut/mapping/blob/master/LICENSE)

[![Total Downloads](https://camo.githubusercontent.com/d22dc2fe3056b9470ff92b9f92713723b9d4cdc5b4b9ffd4b5ac03472641fc4c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6a756c69616e6775742f6d617070696e672e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/juliangut/mapping/stats)[![Monthly Downloads](https://camo.githubusercontent.com/c756a99ef358b261df9744b3a8ef92ad9123112c63c470a02287ed1c8a0bd9f8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646d2f6a756c69616e6775742f6d617070696e672e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/juliangut/mapping/stats)

Mapping
=======

[](#mapping)

Base mapping parsing library for any kind of project or library.

This library frees you from the most tedious part of mapping parsing by providing a set of functionalities to easily load mappings from PHP's Attributes or files of different formats (PHP, JSON, XML, YAML), so you can focus on the actual parsing of mappings into metadata you can use onwards.

Examples
--------

[](#examples)

Examples of packages fully implementing this library can be found at

- [juliangut/slim-routing](https://github.com/juliangut/slim-routing)
- [juliangut/json-api](https://github.com/juliangut/json-api)

Installation
------------

[](#installation)

### Composer

[](#composer)

```
composer require juliangut/mapping

```

To use yaml files mappings

```
composer require symfony/yaml

```

Usage
-----

[](#usage)

Require composer autoload file

```
require './vendor/autoload.php';
```

### Drivers

[](#drivers)

Should retrieve parsed metadata stored in a specific format

#### File mapping

[](#file-mapping)

Any kind of format that can be returned on an array can be used

```
use Jgut\Mapping\Driver\AbstractMappingDriver;
use Jgut\Mapping\Driver\Traits\PhpMappingTrait;
use Jgut\Mapping\Metadata\MetadataInterface;

class PhpDriver extends AbstractMappingDriver
{
    use PhpMappingTrait;

    public function getMetadata(): array
    {
        $mappingData = $this->getMappingData();

        // Return your parsed metadata
    }
}

$driver = new PhpDriver(['path/to/classes']);

$driver->getMetadata();
```

There are mapping traits to easily support four types of mapping files:

- DriverInterface::DRIVER\_PHP => Jgut\\Mapping\\Driver\\Traits\\PhpMappingTrait
- DriverInterface::DRIVER\_JSON => Jgut\\Mapping\\Driver\\Traits\\JsonMappingTrait
- DriverInterface::DRIVER\_XML => Jgut\\Mapping\\Driver\\Traits\\XmlMappingTrait
- DriverInterface::DRIVER\_YAML => Jgut\\Mapping\\Driver\\Traits\\YamlMappingTrait

#### Attribute mapping

[](#attribute-mapping)

```
use Jgut\Mapping\Driver\AbstractClassDriver;
use Jgut\Mapping\Metadata\MetadataInterface;

class AttributeDriver extends AbstractClassDriver
{
    public function getMetadata(): array
    {
        $mappingClasses = $this->getMappingClasses();

        // Parse class attributes with PHP Reflection

        // Return your parsed metadata
    }
}

$driver = new AttributeDriver(['path/to/classes']);

$driver->getMetadata();
```

#### Annotation mapping

[](#annotation-mapping)

*Annotations are deprecated and discouraged. Use Attribute mapping instead*

```
composer require doctrine/annotations

```

```
use Doctrine\Common\Annotations\AnnotationReader;
use Jgut\Mapping\Driver\AbstractAnnotationDriver;
use Jgut\Mapping\Metadata\MetadataInterface;

class AnnotationDriver extends AbstractAnnotationDriver
{
    public function getMetadata(): array
    {
        $mappingClasses = $this->getMappingClasses();

        // Parse class annotations. Annotation reader available on $this->annotationReader

        // Return your parsed metadata
    }
}

$driver = new AnnotationDriver(['path/to/classes'], new AnnotationReader());

$driver->getMetadata();
```

#### Factory

[](#factory)

Create your driver factory extending from Jgut\\Mapping\\Driver\\AbstractDriverFactory, it allows to automatically get a mapping driver from mapping sources

```
use Doctrine\Common\Annotations\AnnotationReader;
use Jgut\Mapping\Driver\AbstractDriverFactory;
use Jgut\Mapping\Driver\DriverInterface;

class DriverFactory extends AbstractDriverFactory
{
    protected function getPhpDriver(array $paths): DriverInterface
    {
        return new PhpDriver($paths);
    }

    protected function getAttributeDriver(array $paths): DriverInterface
    {
        return new AttributeDriver($paths);
    }

    protected function getAnnotationDriver(array $paths): DriverInterface
    {
        return new AnnotationDriver($paths, new AnnotationReader());
    }
}
```

### Resolver

[](#resolver)

Given mapping source definitions, metadata resolver will resolve final metadata using a driver factory

```
use Jgut\Mapping\Driver\DriverFactoryInterface;
use Jgut\Mapping\Metadata\MetadataResolver;

$mappingSources = [
    [
        'type' => DriverFactoryInterface::DRIVER_ATTRIBUTE,
        'path' => '/path/to/mapping/files',
    ]
];

$metadataResolver = new MetadataResolver(new DriverFactory(), new PSR16Cache());

$metadata = $metadataResolver->getMetadata($mappingSources);
```

> It's not mandatory, but highly recommended, to add a PSR-16 cache implementation to metadata resolver, collecting mapping data from annotations and/or files and transforming them into metadata objects can be an intensive operation that benefits vastly of caching

#### Mapping source

[](#mapping-source)

Define where your mapping data is and how it will be parsed

- `type` one of \\Jgut\\Mapping\\Driver\\DriverFactoryInterface constants: `DRIVER_ATTRIBUTE`, `DRIVER_PHP`, `DRIVER_JSON`, `DRIVER_XML`, `DRIVER_YAML` or `DRIVER_ANNOTATION` **if no driver, defaults to DRIVER\_ATTRIBUTE**
- `path` a string path or array of paths to where mapping files are located (files or directories) **REQUIRED if no driver**
- `driver` an already created \\Jgut\\Mapping\\Driver\\DriverInterface object **required if no type AND path**

### Annotations

[](#annotations)

Base AbstractAnnotation class is provided to ease annotations creation.

```
use Jgut\Mapping\Annotation\AbstractAnnotation;

/**
 * @Annotation
 *
 * @Target("CLASS")
 */
class Event extends AbstractAnnotation
{
    protected string $event;

    protected bool $enabled;

    public function setEvent(string $event): void
    {
        $this->event = $event;
    }

    public function setEnabled(bool $enabled): void
    {
        $this->enabled = $enabled;
    }

    protected function getDefaultProperty(): ?string
    {
        return 'event';
    }
}
```

```
/**
 * @Event("post_deserialize", enabled=true)
 */
class Example
{
}
```

`getDefaultParameter` defines which annotation property is considered the default ("value" by default). In this previous example `event` property will be set to "post\_deserialize"

Contributing
------------

[](#contributing)

Found a bug or have a feature request? [Please open a new issue](https://github.com/juliangut/mapping/issues). Have a look at existing issues before.

See file [CONTRIBUTING.md](https://github.com/juliangut/mapping/blob/master/CONTRIBUTING.md)

License
-------

[](#license)

See file [LICENSE](https://github.com/juliangut/mapping/blob/master/LICENSE) included with the source code for a copy of the license terms.

###  Health Score

43

—

FairBetter than 91% of packages

Maintenance38

Infrequent updates — may be unmaintained

Popularity27

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity77

Established project with proven stability

 Bus Factor1

Top contributor holds 97.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~148 days

Recently: every ~91 days

Total

18

Last Release

596d ago

Major Versions

0.5 → 1.02020-01-06

PHP version history (4 changes)0.1PHP ^7.0

1.0PHP ^7.1

1.1PHP ^7.4|^8.0

1.3PHP ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/4c50421f1ab4148354dc2dd5dcaba168656b17ea913b310d112deb39a6f73ca1?d=identicon)[juliangut](/maintainers/juliangut)

---

Top Contributors

[![juliangut](https://avatars.githubusercontent.com/u/1104131?v=4)](https://github.com/juliangut "juliangut (66 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")[![mbolli](https://avatars.githubusercontent.com/u/722725?v=4)](https://github.com/mbolli "mbolli (1 commits)")

---

Tags

phpjsonxmlyamldoctrineannotationsmappingattributes

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/juliangut-mapping/health.svg)

```
[![Health](https://phpackages.com/badges/juliangut-mapping/health.svg)](https://phpackages.com/packages/juliangut-mapping)
```

###  Alternatives

[martin-georgiev/postgresql-for-doctrine

Extends Doctrine with native PostgreSQL support for arrays, JSONB, ranges, PostGIS geometries, text search, ltree, uuid, and 100+ PostgreSQL-specific functions.

4485.3M4](/packages/martin-georgiev-postgresql-for-doctrine)[mathielen/import-engine

Full-blown importer stack for importing almost any data into your application

2711.9k2](/packages/mathielen-import-engine)[rolfvreijdenberger/izzum-statemachine

A superior statemachine library php >= 5.3. Integrates with your domain models perfectly.

7425.5k](/packages/rolfvreijdenberger-izzum-statemachine)[event4u/data-helpers

Framework-agnostic PHP library for data mapping, DTOs and utilities. Includes DataMapper, SimpleDto/LiteDto, DataAccessor/Mutator/Filter and helper classes (MathHelper, EnvHelper, etc.). Works with Laravel, Symfony/Doctrine or standalone PHP.

1421.5k](/packages/event4u-data-helpers)[davidepastore/slim-config

A slim middleware to read configuration from different files based on hassankhan/config

338.9k1](/packages/davidepastore-slim-config)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)