Document Marshaller
, (*1)
This is an experiment - use at your own risk!, (*2)
The purpose of this library is provide a mechanism for marshalling and unmarshalling data using a single document,
allowing for the transportation and storage of related data in a single file., (*3)
Notes on implementation:, (*4)
- Booleans will be converted into integers
Installation
composer require punkstar/document-marshaller
Usage
Create your document using Document
and DocumentFragment
, for example:, (*5)
$document = new Document([
new DocumentFragment("Fragment One", "This is the content in this fragment"),
new DocumentFragment("Fragment Two", "This is the content in this fragment, the second")
]);
Create the marshallers and the checksum calculator:, (*6)
$checksumCalculator = new Checksum();
$fragmentMarshaller = new DocumentFragment\Marshaller();
$marshaller = new DocumentMarshaller($fragmentMarshaller, $checksumCalculator);
The marshall the document:, (*7)
$marshalledDocument = $marshaller->marshall($document);
The document is encoded using JSON in the following structure:, (*8)
{
"v": "", // Document Version
"c": "" // Document Checksum
"f": [ // Document Fragments
{
"n": "" // Document Fragment Name
"d": "" // Document Fragment Data
}
...
]
}
Document
- A document MUST be an object.
- A document SHOULD have a version indicated by the value of the key:
v
. If a version is absent then a version value
of 1
MUST be assumed.
- A document SHOULD have a checksum indicated by the value of the key:
c
. If a checksum is absent then any
verification logic should be skipped and the user SHOULD be presented with a non fatal warning if appropriate.
- A document SHOULD have a fragments array indicated by the value of the key:
f
. If the fragments array is absent
then it MUST be assumed that the document has no fragments.
Document Version
- The document version MUST be expressed as an integer.
Document Fragments
- The document fragments MUST be an array of objects with a name key:
n
, and a data key: d
.
- The name and the data of the document fragment MUST be encoded with base64.
Document Checksum
- The document checksum MUST be calculated by: sorting the fragments objects by name, then performing a hash of the JSON
fragments array using sha256.
Some examples are provided below:, (*9)
The first document consists of two fragments, one called Header
; the other Body
. The content of the Header
fragment is the string Hello
. The content of the Body
fragment is World
. The JSON representation of these
fragments is as follows:, (*10)
[
{
"n": "Header",
"d": "Hello"
},
{
"n": "Body",
"d": "World"
}
]
The checksum of this document would therefore be:, (*11)
sha256([{"n":"SGVhZGVy","d":"SGVsbG8="},{"n":"Qm9keQ==","d":"V29ybGQ="}]) == "d827049039f82a8b65a9b0f52e637cf3bc5d1e0dec7d6198edf901a5e3dcae7d"
The entire document expressed would therefore be:, (*12)
{
"v": 1,
"c": "d827049039f82a8b65a9b0f52e637cf3bc5d1e0dec7d6198edf901a5e3dcae7d",
"f": [{
"n": "Header",
"d": "Hello"
}, {
"n": "Body",
"d": "World"
}]
}