Download the PHP package punkstar/document-marshaller without Composer
On this page you can find all versions of the php package punkstar/document-marshaller. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download punkstar/document-marshaller
More information about punkstar/document-marshaller
Files in punkstar/document-marshaller
Package document-marshaller
Short Description A library for encoding and decoded structured data in JSON
License MIT
Homepage https://github.com/punkstar/document-marshaller
Informations about the package document-marshaller
Document Marshaller
This is an experiment - use at your own risk!
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.
Notes on implementation:
- Booleans will be converted into integers
Installation
composer require punkstar/document-marshaller
Usage
Create your document using Document
and DocumentFragment
, for example:
$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:
$checksumCalculator = new Checksum();
$fragmentMarshaller = new DocumentFragment\Marshaller();
$marshaller = new DocumentMarshaller($fragmentMarshaller, $checksumCalculator);
The marshall the document:
$marshalledDocument = $marshaller->marshall($document);
Document Format
The document is encoded using JSON in the following structure:
{
"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 of1
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:
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:
[
{
"n": "Header",
"d": "Hello"
},
{
"n": "Body",
"d": "World"
}
]
The checksum of this document would therefore be:
sha256([{"n":"SGVhZGVy","d":"SGVsbG8="},{"n":"Qm9keQ==","d":"V29ybGQ="}]) == "d827049039f82a8b65a9b0f52e637cf3bc5d1e0dec7d6198edf901a5e3dcae7d"
The entire document expressed would therefore be:
{
"v": 1,
"c": "d827049039f82a8b65a9b0f52e637cf3bc5d1e0dec7d6198edf901a5e3dcae7d",
"f": [{
"n": "Header",
"d": "Hello"
}, {
"n": "Body",
"d": "World"
}]
}