co-stack / reversible
Provides portable reversible functions and queues. Can be used e.g. for transport encoding or complex value processing
Requires
- php: ^7.2 || ^8.0 <8.4
- ext-json: *
- ext-openssl: *
- ext-zlib: *
README
What is a reversible function
A reversible function is a function that can be executed forwards and backwards (reverted). They are side effect free (idempotent) and stateless.
These functions are especially useful for transport encoding, persistence mapping, encryption and many other use cases.
Notice
Some encodings are not fully idempotent, like Base64Encoding
. The base64_encode
function does not preserve data types (int, float, bool).
Implementations of Reversible
that may not be full idempotent implement the Lossy
interface.
Abstract
The true strength of this package lies in the ReversiblePipe
.
The simpler examples down below are just for clarification.
$mySecret = 'correcthorsebatterystaple';
$myValue = [
'foo-bar-baz',
'boo-beng-fump'
];
$pipe = new \CoStack\Reversible\Applicable\ReversiblePipe();
$pipe->enqueue(new \CoStack\Reversible\Operation\Encoding\JsonEncoding())
->enqueue(new \CoStack\Reversible\Operation\Security\HmacAssertion($mySecret))
->enqueue(new \CoStack\Reversible\Operation\Encoding\Base64Encoding());
// The pipe will json encode the array, add the HMAC to the encoded array and base64 encode it
$transportSafeAndHmacProtected = $pipe->execute($myValue);
// Transport over wire
// ------->------->------->
// The pipe will base64 decode it and validate the HMAC. If the HMAC is valid the string will be json decoded and the array returned
$myValue = $pipe->reverse($transportSafeAndHmacProtected);
Examples
I have prepared some useful examples for you, which show the versatility of this package
Scalar value sent over the air
On System A:
// System A
$input = random_bytes(256);
$encoding = new \CoStack\Reversible\Operation\Encoding\Base64Encoding();
$output = $encoding->execute($input);
// System B
$encoding = new \CoStack\Reversible\Operation\Encoding\Base64Encoding();
$restoredInput = $encoding->reverse($output);
// $restoredInput is exactly $input what was generated on System A
Associative array transportation via string without serialization
// Shared Library
function getPipe(): \CoStack\Reversible\Applicable\ReversiblePipe {
$pipe = new \CoStack\Reversible\Applicable\ReversiblePipe();
$pipe->enqueue(new \CoStack\Reversible\Operation\Mapping\ArrayKeyMapping(['key1', 'key2', 'payload']));
$pipe->enqueue(new \CoStack\Reversible\Applicable\ApplyOnArrayValueRecursively(new \CoStack\Reversible\Operation\Encoding\Base64Encoding()));
$pipe->enqueue(new \CoStack\Reversible\Operation\Transform\ImplodeTransform());
return $pipe;
}
// System A
$array = [
'key1' => 1,
'key2' => 'value',
'payload' => uniqid(),
];
$pipe = getPipe();
$safeEncodedObject = $pipe->execute($array);
// The string will contain base64 encoded values, imploded with "|". There are no associative keys in the string because they have been replaced by the ArrayKeyMapping
// System B
$pipe = getPipe();
$array = $pipe->reverse($safeEncodedObject);
Please notice that ImplodeTransform
is lossy because explode(',', implode(',', [2])) === ['2']
(an integer will become a string).
Object transportation via problematic medium (e.g. get parameter)
// Shared Library
function getPipe(): \CoStack\Reversible\Applicable\ReversiblePipe {
$pipe = new \CoStack\Reversible\Applicable\ReversiblePipe();
$pipe->enqueue(new \CoStack\Reversible\Operation\Encoding\SerializationEncoding());
$pipe->enqueue(new \CoStack\Reversible\Operation\Encoding\UrlEncode());
return $pipe;
}
// System A
$object = new SplFileInfo('file.txt');
$pipe = getPipe();
$safeEncodedObject = $pipe->execute($object);
// System B
$pipe = getPipe();
$object = $pipe->reverse($safeEncodedObject);
UUIDv4 to binary and back (e.g., for persisting uuid as binary in databases)
$uuid = gen_uuid();
$uuidToBinary = new \CoStack\Reversible\Applicable\ReversiblePipe();
$uuidToBinary->enqueue(new \CoStack\Reversible\Operation\Fixed\FixedStringStripping('-', [8, 4, 4, 4]));
$uuidToBinary->enqueue(new \CoStack\Reversible\Operation\Encoding\HexToBinEncoding());
$binary = $uuidToBinary->execute($uuid);
// Persist binary uuid in DB
// Select binary uuid from DB and convert to readable string again
$uuidAgain = $uuidToBinary->reverse($binary);
Security
Add \CoStack\Reversible\Operation\Security\HmacAssertion
at the end of your data transformation and encoding to generate
a HMAC, which will be automatically validated on reversal.
$mySecretKey = 'Tr0ub4dor&3';
$protectMeFromChanges = uniqid();
$pipe = new \CoStack\Reversible\Applicable\ReversiblePipe();
$pipe->enqueue(new \CoStack\Reversible\Operation\Encoding\Base64Encoding());
$pipe->enqueue(new \CoStack\Reversible\Operation\Security\HmacAssertion($mySecretKey));
$stringWithHmac = $pipe->execute($protectMeFromChanges);
$stringWithHmac .= 'EvilChanges';
try {
$pipe->reverse($stringWithHmac);
} catch (\CoStack\Reversible\Exception\HmacAssertionFailedException $exception) {
echo 'Someone fiddled with the string!';
exit(1);
}