README

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 either from Doctrine annotations 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

Full implementation examples of this library can be found at

• juliangut/slim-routing
• juliangut/json-api

Installation

Composer

composer require juliangut/mapping

To use mappings in class annotations

composer require doctrine/annotations

To use yaml files mappings

composer require symfony/yaml

Usage

Require composer autoload file

require './vendor/autoload.php';

Drivers

Should retrieve parsed metadata stored in a specific format

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;

    /**
     * @return MetadataInterface[]
     */
    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

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

class AttributeDriver extends AbstractClassDriver
{
    /**
     * @return MetadataInterface[]
     */
    public function getMetadata(): array
    {
        $mappingClasses = $this->getMappingClasses();

        // Parse class attributes with PHP's reflection

        // Return your parsed metadata
    }
}

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

$driver->getMetadata();

Annotation mapping

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

class AnnotationDriver extends AbstractAnnotationDriver
{
    /**
     * @return MetadataInterface[]
     */
    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

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

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

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

• type one of \Jgut\Mapping\Driver\DriverFactoryInterface constants: DRIVER_ATTRIBUTE, DRIVER_ANNOTATION, DRIVER_PHP, DRIVER_JSON, DRIVER_XML or DRIVER_YAML if no driver, defaults to DRIVER_ATTRIBUTE in PHP >=8.0 or DRIVER_ANNOTATION PHP < 8.0
• 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

Base AbstractAnnotation class is provided to ease annotations creation.

use Jgut\Mapping\Annotation\AbstractAnnotation;

/**
 * Custom annotation.
 *
 * @Annotation
 * @Target("PROPERTY")
 */
class Custom extends AbstractAnnotation
{
}

Contributing

Found a bug or have a feature request? Please open a new issue. Have a look at existing issues before.

See file CONTRIBUTING.md

License

See file LICENSE included with the source code for a copy of the license terms.