Download the PHP package skrz/meta without Composer
On this page you can find all versions of the php package skrz/meta. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Package meta
Short Description Different wire formats, different data sources, single object model
License MIT
Informations about the package meta
Skrz\Meta
Different wire formats, different data sources, single object model
Requirements
Skrz\Meta
requires PHP >= 5.4.0
and Symfony >= 2.7.0
.
Installation
Add as Composer dependency:
Why?
At Skrz.cz, we work heavily with many different input/output formats and data sources (databases). E.g. data from partners come in as XML feeds; internally our micro-service architecture encodes data into JSON as wire format; data can come from MySQL, Redis, and Elasticsearch databases, and also has to be put in there.
However, in our PHP code base we want single object model that we could also share between projects. This need came mainly from micro services' protocols that got quite wild - nobody really knew what services sent to each other.
Serialization/deserialization had to be fast, therefore we created concept of so-called meta classes. A meta class is an
object's companion class that handles object's serialization/deserialization from/into many different formats. Every class
has exactly one meta class, in which methods from different modules are combined - modules can use each others methods
(e.g. JsonModule
uses methods generated by PhpModule
).
Usage
Have simple value object:
You would like to serialize object into JSON. What you might do is to create method toJson
:
Creating such method for every value object that gets sent over wire is tedious and error-prone. So you generate meta class that implements such methods.
Meta classes are generated according to meta spec. A meta spec is a class extending Skrz\Meta|AbstractMetaSpec
:
Method configure()
initializes spec with matchers and modules. A matcher is a set of classes that satisfy certain
criteria (e.g. namespace, class name). A module is generator that takes class matched by the matcher and generates
module-specific methods in the meta class. ApiMetaSpec
creates meta classes for every class directly in Skrz\API
namespace
(it does not include classes in sub-namespaces, e.g. Skrz\API\Meta
). The meta classes are generated from PHP and JSON modules
(Skrz\Meta\BaseModule
providing basic functionality of a meta class is added automatically).
To actually generate classes, you have supply some files to spec to process:
Similar code should be part of your build process (or in development part of Grunt watch task etc.).
By default, spec generates meta class in Meta
sub-namespace with Meta
suffix (e.g. Skrz\API\Category
-> Skrz\API\Meta\CategoryMeta
)
and stores it inside Meta
sub-directory of original class's directory.
After the meta classes has been generated, usage is quite simple:
Fields
- Fields represent set of symbolic field paths.
- They are composite (fields can have sub-fields).
- Fields can be supplied as
$filter
parameters into*()
methods.
Fields are inspired by:
- Facebook Graph API's
?fields=...
query parameter - Google Protocol Buffers'
FieldMask
(and its JSON serialization)
Annotations
Skrz\Meta
uses Doctrine annotation parser. Annotations can change mappings.
Also Skrz\Meta
offers so called groups - different sources can offer different field names, however, they map onto same object.
@PhpArrayOffset
@PhpArrayOffset
annotation can be used to change name of outputted keys in arrays generated by toArray
and inputs to fromArray
:
@JsonProperty
@JsonProperty
marks names of JSON properties. (Internally every group created by @JsonProperty
creates PHP group
prefixed by json:
- PHP object is first mapped to array using json:
group, then the array is serialized using
json_encode()
.)
@XmlElement
& @XmlElementWrapper
& @XmlAttribute
& @XmlValue
- Modelled after javax.xml.bind.annotation.
- Works with
DOMDocument
(for streaming or DOM-based XML APIs).
For more examples see classes in test/Skrz/Meta/Fixtures/XML
and test/Skrz/Meta/XmlModuleTest.php
.
@PhpDiscriminatorMap
& @JsonDiscriminatorMap
@PhpDiscriminatorMap
and @JsonDiscriminatorMap
encapsulate inheritance.
@PhpDiscriminatorOffset
& @JsonDiscriminatorProperty
@PhpDiscriminatorOffset
and @JsonDiscriminatorProperty
make subclasses differentiated using offset/property.
Known limitations
-
private
properties cannot be hydrated. Hydration of private properties would require using reflection, or usingunserialize()
hack, which is contrary to requirement of being fast. Therefore meta classes compilation will fail if there is aprivate
property. If you need aprivate
property, mark it using@Transient
annotation and it will be ignored. - There can be at most 31/63 groups in one meta class. Group name is encoded using bit in integer type. PHP integer is platform dependent and always signed, therefore there can be at most 31/63 groups depending on platform the PHP's running on.
TODO
- YAML - just like JSON
@XmlElementRef
License
The MIT license. See LICENSE
file.
All versions of meta with dependencies
doctrine/annotations Version ~1.10
nette/php-generator Version ~2.6
symfony/finder Version ~2.7|~3.0|~4.0|~5.0|~6.0|~7.0
symfony/console Version ~2.7|~3.0|~4.0|~5.0|~6.0|~7.0