wikibase / data-model-serialization
Serializers and deserializers for the Wikibase DataModel
Installs: 192 126
Dependents: 7
Suggesters: 0
Security: 0
Stars: 9
Watchers: 28
Forks: 9
Open Issues: 2
Requires
- php: >=5.5.9
- data-values/serialization: ~1.0
- serialization/serialization: ~4.0|~3.1
- wikibase/data-model: ~9.0|~8.0|~7.0|~6.0|~5.0|~4.2
Requires (Dev)
- data-values/geo: ~4.0|~3.0
- data-values/number: >=0.1 <0.11
- data-values/time: ~1.0|~0.2
- phpunit/phpunit: ^4.8.35
- wikibase/wikibase-codesniffer: ^0.4.1
Suggests
- data-values/geo: Needed for deserialization of geographical values
- data-values/number: Needed for deserialization of numerical values
- data-values/time: Needed for deserialization of time values
- dev-master / 2.9.x-dev
- 2.9.1
- 2.9.0
- 2.8.0
- 2.7.0
- 2.6.0
- 2.5.0
- 2.4.0
- 2.3.0
- 2.2.0
- 2.1.0
- 2.0.0
- 1.9.1
- 1.9.0
- 1.8.0
- 1.7.0
- 1.6.0
- 1.5.0
- 1.4.0
- 1.3.0
- 1.2.0
- 1.1.1
- 1.1.0
- 1.0.3
- 1.0.2
- 1.0.1
- 1.0
- 0.1
- dev-legacy
- dev-Make_sure_all_Wikibase_codebases_run_PHPCS_during_composer_test
- dev-dm9x-1
- dev-removeOptions
- dev-micro-opti-entityid-stuffz
- dev-entity-setid-nonull
This package is auto-updated.
Last update: 2024-11-15 15:09:09 UTC
README
Library containing serializers and deserializers for the basic Wikibase DataModel entity types and components they are made of. The supported formats are limited to public ones, ie those used by a web API. Serialization code for private formats, such as the format used by the Wikibase Repo data access layer, belongs in other components.
Recent changes can be found in the release notes.
Installation
The recommended way to use this library is via Composer.
Composer
To add this package as a local, per-project dependency to your project, simply add a
dependency on wikibase/data-model-serialization
to your project's composer.json
file.
Here is a minimal example of a composer.json
file that just defines a dependency on
version 2.0 of this package:
{ "require": { "wikibase/data-model-serialization": "~2.0" } }
Manual
Get the code of this package, either via git, or some other means. Also get all dependencies. You can find a list of the dependencies in the "require" section of the composer.json file. Then take care of autoloading the classes defined in the src directory.
Library usage
Construct an instance of the specific deserializer or serializer you need via the appropriate factory.
use Wikibase\DataModel\DeserializerFactory; $deserializerFactory = new DeserializerFactory( /* ... */ ); $itemDeserializer = $deserializerFactory->newItemDeserializer();
Then use the deserialize
or serialize
method.
$item = $itemDeserializer->deserialize( $myItemSerialization );
In case of deserialization, guarding against failures is good practice. So it is typically better to use the slightly more verbose try-catch approach.
try { $item = $itemDeserializer->deserialize( $myItemSerialization ); } catch ( DeserializationException $ex ) { // Handling of the exception }
All access to services provided by this library should happen through the SerializerFactory and DeserializerFactory. The rest of the code is an implementation detail which users should not know about.
Library structure
The Wikibase DataModel objects can all be serialized to a generic format from which the objects
can later be reconstructed. This is done via a set of Serializers\Serializer
implementing objects.
These objects turn for instance a Statement
object into a data structure containing only primitive
types and arrays. This data structure can thus be readily fed to json_encode
, serialize
, or the
like. The process of reconstructing the objects from such a serialization is provided by
objects implementing the Deserializers\Deserializer
interface.
Serializers can be obtained via an instance of SerializerFactory
and deserializers can be obtained
via an instance of DeserializerFactory
. You are not allowed to construct these serializers and
deserializers directly yourself or to have any kind of knowledge of them (ie type hinting). These
objects are internal to this component and might change name or structure at any time. All you
are allowed to know when calling $serializerFactory->newItemDeserializer()
is that you get back
an instance of Serializers\Serializer
.
Running the tests
For tests only
composer test
For style checks only
composer cs
For a full CI run
composer ci
Authors
Wikibase DataModel Serialization has been written by Thomas PT as volunteer and by Jeroen De Dauw as Wikimedia Germany employee for the Wikidata project.
Links
- Wikibase DataModel Serialization on Packagist
- Wikibase DataModel Serialization on TravisCI
- Wikibase DataModel Serialization on ScrutinizerCI
- Wikibase DataModel Serialization on OpenHub
See also
- Wikibase DataModel
- Wikibase Internal Serialization (For the "internal" serialization format)