Serializer.php

<?php

/**
 * @author Marwan Al-Soltany <MarwanAlsoltany@gmail.com>
 * @copyright Marwan Al-Soltany 2020
 * For the full copyright and license information, please view
 * the LICENSE file that was distributed with this source code.
 */

declare(strict_types=1);

namespace MAKS\AmqpAgent\Helper;

use Exception;
use Closure;
use MAKS\AmqpAgent\Exception\SerializerViolationException;

/**
 * A flexible serializer to be used in conjunction with the workers.
 * @since 1.0.0
 */
class Serializer
{
    /**
     * The JSON serialization type constant.
     * @var string
     */
    public const TYPE_JSON = 'JSON';

    /**
     * The PHP serialization type constant.
     * @var string
     */
    public const TYPE_PHP = 'PHP';

    /**
     * The default data the serializer works with if none was provided.
     * @var null
     */
    public const DEFAULT_DATA = null;

    /**
     * The default type the serializer works with if none was provided.
     * @var string
     */
    public const DEFAULT_TYPE = self::TYPE_JSON;

    /**
     * The default strict value the serializer works with if none was provided.
     * @var bool
     */
    public const DEFAULT_STRICT = true;

    /**
     * The supported serialization types.
     * @var array
     */
    protected const SUPPORTED_TYPES = [self::TYPE_JSON, self::TYPE_PHP];


    /**
     * The current data the serializer has.
     * @var mixed
     */
    protected $data;

    /**
     * The current type the serializer uses.
     * @var string
     */
    protected $type;

    /**
     * The current strict value the serializer works with.
     * @var bool
     */
    protected $strict;

    /**
     * The result of the last (un)serialization operation.
     * @var mixed
     */
    protected $result;


    /**
     * Serializer object constructor.
     * @param mixed $data [optional] The data to (un)serialize. Defaults to null.
     * @param string|null $type [optional] The type of (un)serialization. Defaults to JSON.
     * @param bool $strict [optional] Whether or not to assert that no errors have occurred while executing (un)serialization functions. Defaults to true.
     * @throws SerializerViolationException
     */
    public function __construct($data = null, ?string $type = null, ?bool $strict = null)
    {
        $this->setData($data ?? self::DEFAULT_DATA);
        $this->setType($type ?? self::DEFAULT_TYPE);
        $this->setStrict($strict ?? self::DEFAULT_STRICT);
    }

    /**
     * Executes when calling the class like a function.
     * @param mixed $data The data to (un)serialize.
     * @param string|null $type [optional] The type of (un)serialization. Defaults to JSON.
     * @param bool $strict [optional] Whether or not to assert that no errors have occurred while executing (un)serialization functions. Defaults to true.
     * @return mixed Serialized or unserialized data depending on the passed parameters.
     * @throws SerializerViolationException
     */
    public function __invoke($data, ?string $type = self::DEFAULT_TYPE, ?bool $strict = self::DEFAULT_STRICT)
    {
        $this->setData($data);
        $this->setType($type ?? self::DEFAULT_TYPE);
        $this->setStrict($strict ?? self::DEFAULT_STRICT);

        try {
            $this->result = is_string($data) ? $this->unserialize() : $this->serialize();
        } catch (Exception $error) {
            $dataType = gettype($data);
            throw new SerializerViolationException(
                sprintf(
                    'The data passed to the serializer (data-type: %s) could not be processed!',
                    $dataType
                ),
                (int)$error->getCode(),
                $error
            );
        }

        return $this->result;
    }


    /**
     * Serializes the passed or registered data. When no parameters are passed, it uses the registered ones.
     * @param mixed $data [optional] The data to serialize.
     * @param string|null $type [optional] The type of serialization.
     * @param bool $strict [optional] Whether or not to assert that no errors have occurred while executing serialization functions.
     * @return string|null A serialized representation of the passed or registered data or null on failure.
     * @throws SerializerViolationException
     */
    public function serialize($data = null, ?string $type = null, ?bool $strict = null): string
    {
        if (null !== $data) {
            $this->setData($data);
        }

        if (null !== $type) {
            $this->setType($type);
        }

        if (null !== $strict) {
            $this->setStrict($strict);
        }

        if (self::TYPE_PHP === $this->type) {
            $this->assertNoPhpSerializationError(function () {
                $this->result = serialize($this->data);
            });
        }

        if (self::TYPE_JSON === $this->type) {
            $this->assertNoJsonSerializationError(function () {
                $this->result = json_encode($this->data);
            });
        }

        return $this->result;
    }

    /**
     * Unserializes the passed or registered data. When no parameters are passed, it uses the registered ones.
     * @param string|null $data [optional] The data to unserialize.
     * @param string|null $type [optional] The type of unserialization.
     * @param bool $strict [optional] Whether or not to assert that no errors have occurred while executing unserialization functions.
     * @return mixed A PHP type on success or false or null on failure.
     * @throws SerializerViolationException
     */
    public function unserialize(?string $data = null, ?string $type = null, ?bool $strict = null)
    {
        if (null !== $data) {
            $this->setData($data);
        }

        if (null !== $type) {
            $this->setType($type);
        }

        if (null !== $strict) {
            $this->setStrict($strict);
        }

        if (self::TYPE_PHP === $this->type) {
            $this->assertNoPhpSerializationError(function () {
                $this->result = unserialize($this->data);
            });
        }

        if (self::TYPE_JSON === $this->type) {
            $this->assertNoJsonSerializationError(function () {
                $this->result = json_decode($this->data, true);
            });
        }

        return $this->result;
    }

    /**
     * Deserializes the passed or registered data. When no parameters are passed, it uses the registered ones.
     * @since 1.2.2 Alias for `self::unserialize()`.
     * @param string|null $data [optional] The data to unserialize.
     * @param string|null $type [optional] The type of unserialization.
     * @param bool $strict [optional] Whether or not to assert that no errors have occurred while executing unserialization functions.
     * @return mixed A PHP type on success or false or null on failure.
     * @throws SerializerViolationException
     */
    public function deserialize(?string $data = null, ?string $type = null, ?bool $strict = null)
    {
        return $this->unserialize($data, $type, $strict);
    }

    /**
     * Registers the passed data in the object.
     * @param mixed $data The data wished to be registered.
     * @return self
     */
    public function setData($data)
    {
        $this->data = $data;

        return $this;
    }

    /**
     * Returns the currently registered data.
     * @return mixed
     */
    public function getData()
    {
        return $this->data;
    }

    /**
     * Registers the passed type in the object.
     * @param string $type The type wished to be registered.
     * @return self
     * @throws SerializerViolationException
     */
    public function setType(string $type)
    {
        $type = strtoupper($type);

        if (!in_array($type, static::SUPPORTED_TYPES)) {
            throw new SerializerViolationException(
                sprintf(
                    '"%s" is unsupported (un)serialization type. Supported types are: [%s]!',
                    $type,
                    implode(', ', static::SUPPORTED_TYPES)
                )
            );
        }

        $this->type = $type;

        return $this;
    }

    /**
     * Returns the currently registered type.
     * @return string
     */
    public function getType(): string
    {
        return $this->type;
    }

    /**
     * Registers the passed strict value in the object.
     * @since 1.2.2
     * @param bool $strict The strict value wished to be registered.
     * @return self
     */
    public function setStrict(bool $strict)
    {
        $this->strict = $strict;

        return $this;
    }

    /**
     * Returns the currently registered strict value.
     * @since 1.2.2
     * @return bool
     */
    public function isStrict()
    {
        return $this->strict;
    }

    /**
     * Alias for `self::serialize()` that does not accept any parameters (works with currently registered parameters).
     * @return string The serialized data.
     * @throws SerializerViolationException
     */
    public function getSerialized(): string
    {
        return $this->serialize();
    }

    /**
     * Alias for `self::unserialize()` that does not accept any parameters (works with currently registered parameters).
     * @return mixed The unserialized data.
     * @throws SerializerViolationException
     */
    public function getUnserialized()
    {
        return $this->unserialize();
    }

    /**
     * Asserts that `serialize()` and/or `unserialize()` was executed successfully depending on strictness of the Serializer.
     * @since 1.2.2
     * @param Closure $callback The (un)serialization callback to execute.
     * @return void
     * @throws SerializerViolationException
     */
    protected function assertNoPhpSerializationError(Closure $callback): void
    {
        $this->result = null;

        try {
            $callback();
        } catch (Exception $error) {
            if ($this->strict) {
                throw new SerializerViolationException(
                    sprintf(
                        'An error occurred while executing serialize() or unserialize(): %s',
                        (string)$error->getMessage()
                    ),
                    (int)$error->getCode(),
                    $error
                );
            }
        }
    }

    /**
     * Asserts that `json_encode()` and/or `json_decode()` was executed successfully depending on strictness of the Serializer.
     * @since 1.2.2
     * @param Closure $callback The (un)serialization callback to execute.
     * @return void
     * @throws SerializerViolationException
     */
    protected function assertNoJsonSerializationError(Closure $callback): void
    {
        $this->result = null;

        try {
            $callback();
        } catch (Exception $error) {
            // JSON functions do not throw exceptions on PHP < v7.3.0
            // The code down below takes care of throwing the exception.
        }

        if ($this->strict) {
            $errorCode = json_last_error();
            if ($errorCode !== JSON_ERROR_NONE) {
                $errorMessage = json_last_error_msg();
                throw new SerializerViolationException(
                    sprintf(
                        'An error occurred while executing json_encode() or json_decode(): %s',
                        $errorMessage
                    )
                );
            }
        }
    }
}