juliangut / mapping
Base for mapping support
Fund package maintenance!
juliangut
Installs: 6 419
Dependents: 4
Suggesters: 0
Security: 0
Stars: 2
Watchers: 3
Forks: 0
Open Issues: 1
Requires
- php: ^8.0
- psr/simple-cache: ^1.0|^2.0|^3.0
Requires (Dev)
- ext-json: *
- ext-libxml: *
- ext-simplexml: *
- doctrine/annotations: ^2.0
- infection/infection: ~0.25|~0.27
- juliangut/easy-coding-standard-config: ^1.19
- juliangut/phpstan-config: ^1.2
- overtrue/phplint: ^9.0
- phpcompatibility/php-compatibility: ^9.3
- phpmd/phpmd: ^2.14
- phpunit/phpunit: ^9.6|^10.4
- povils/phpmnd: ^3.2
- roave/security-advisories: dev-master
- symfony/yaml: ^6.0|^7.0
Suggests
- symfony/yaml: In order to load mappings from YAML files (>=6.0)
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 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 of packages fully implementing this library can be found at
Installation
Composer
composer require juliangut/mapping
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; 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 { 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
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
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_PHP
,DRIVER_JSON
,DRIVER_XML
,DRIVER_YAML
orDRIVER_ANNOTATION
if no driver, defaults to DRIVER_ATTRIBUTEpath
a string path or array of paths to where mapping files are located (files or directories) REQUIRED if no driverdriver
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; /** * @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
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.