115 lines
5.0 KiB
Markdown
115 lines
5.0 KiB
Markdown
|
# Introduction
|
||
|
|
|
||
|
|
zend-serialzier provides an adapter-based interface for serializing and
|
||
|
|
deserializing PHP types to and from different representations.
|
||
|
|
|
||
|
|
For more information what a serializer is read the wikipedia page of
|
||
|
|
[Serialization](http://en.wikipedia.org/wiki/Serialization).
|
||
|
|
|
||
|
|
## Quick Start
|
||
|
|
|
||
|
|
Serializing adapters can either be created from the provided
|
||
|
|
`Zend\Serializer\Serializer::factory` method, or by instantiating one of the
|
||
|
|
`Zend\Serializer\Adapter\*` classes.
|
||
|
|
|
||
|
|
```php
|
||
|
|
use Zend\Serializer\Adapter;
|
||
|
|
use Zend\Serializer\Exception;
|
||
|
|
use Zend\Serializer\Serializer;
|
||
|
|
|
||
|
|
// Via factory:
|
||
|
|
$serializer = Serializer::factory(Adapter\PhpSerialize::class);
|
||
|
|
|
||
|
|
// Alternately:
|
||
|
|
$serializer = new Adapter\PhpSerialize();
|
||
|
|
|
||
|
|
// Now $serializer is an instance of Zend\Serializer\Adapter\AdapterInterface,
|
||
|
|
// specifically Zend\Serializer\Adapter\PhpSerialize
|
||
|
|
|
||
|
|
try {
|
||
|
|
$serialized = $serializer->serialize($data);
|
||
|
|
// now $serialized is a string
|
||
|
|
|
||
|
|
$unserialized = $serializer->unserialize($serialized);
|
||
|
|
// now $data == $unserialized
|
||
|
|
} catch (Exception\ExceptionInterface $e) {
|
||
|
|
echo $e;
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
The method `serialize()` generates a storable string. To regenerate this
|
||
|
|
serialized data, call the method `unserialize()`.
|
||
|
|
|
||
|
|
Any time an error is encountered serializing or unserializing, the adapter will
|
||
|
|
throw a `Zend\Serializer\Exception\ExceptionInterface`.
|
||
|
|
|
||
|
|
Because an application often uses only one serializer internally, it is possible
|
||
|
|
to define and use a default serializer. That serializer will be used by default
|
||
|
|
by other components like `Zend\Cache\Storage\Plugin\Serializer`.
|
||
|
|
|
||
|
|
To define and use the default serializer, use the static serialization methods
|
||
|
|
of the basic `Zend\Serializer\Serializer`:
|
||
|
|
|
||
|
|
```php
|
||
|
|
use Zend\Serializer\Adapter;
|
||
|
|
use Zend\Serializer\Exception;
|
||
|
|
use Zend\Serializer\Serializer;
|
||
|
|
|
||
|
|
Serializer::setDefaultAdapter(Adapter\PhpSerialize::class);
|
||
|
|
|
||
|
|
try {
|
||
|
|
$serialized = Serializer::serialize($data);
|
||
|
|
// now $serialized is a string
|
||
|
|
|
||
|
|
$unserialized = Serializer::unserialize($serialized);
|
||
|
|
// now $data == $unserialized
|
||
|
|
} catch (Exception\ExceptionInterface $e) {
|
||
|
|
echo $e;
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## Basic configuration Options
|
||
|
|
|
||
|
|
To configure a serializer adapter, you can optionally use an instance of
|
||
|
|
`Zend\Serializer\Adapter\AdapterOptions`, an instance of one of the adapter
|
||
|
|
specific options class, an `array`, or a `Traversable` object. The adapter
|
||
|
|
will convert it into the adapter specific options class instance (if present) or
|
||
|
|
into the basic `Zend\Serializer\Adapter\AdapterOptions` class instance.
|
||
|
|
|
||
|
|
Options can be passed as the second argument to the provided
|
||
|
|
`Zend\Serializer\Serializer::factory` and `::setDefaultAdapter` methods, via the
|
||
|
|
adapter's `setOptions` method, or as constructor arguments when directly
|
||
|
|
instantiating an adapter.
|
||
|
|
|
||
|
|
## Available Methods
|
||
|
|
|
||
|
|
Each serializer implements the interface `Zend\Serializer\Adapter\AdapterInterface`.
|
||
|
|
|
||
|
|
This interface defines the following methods:
|
||
|
|
|
||
|
|
Method signature | Description
|
||
|
|
---------------- | -----------
|
||
|
|
`serialize(mixed $value) : string` | Generates a storable representation of a value.
|
||
|
|
`unserialize(string $value) : mixed` | Creates a PHP value from a stored representation.
|
||
|
|
|
||
|
|
The base class `Zend\Serializer\Serializer` is used to instantiate the
|
||
|
|
adapters, to configure the factory, and as a proxy for serialization operations.
|
||
|
|
|
||
|
|
It defines the following static methods, where the following references map to
|
||
|
|
classes/interfaces as follows:
|
||
|
|
|
||
|
|
- `AdapterPluginManager`: `Zend\Serializer\AdapterPluginManager`
|
||
|
|
- `AdapterInterface`: `Zend\Serializer\Adapter\AdapterInterface`
|
||
|
|
- `AdapterOptions`: `Zend\Serializer\Adapter\AdapterOptions`
|
||
|
|
|
||
|
|
Method signature | Description
|
||
|
|
---------------- | -----------
|
||
|
|
`factory(/* ... */) : AdapterInterface` | Create a serializer adapter instance. Arguments are: `string|AdapterInterface $adapterName, AdapterOptions|array|Traversable $adapterOptions = null`.
|
||
|
|
`setAdapterPluginManager(AdapterPluginManager $adapters) : void` | Change the adapter plugin manager.
|
||
|
|
`getAdapterPluginManager() : AdapterPluginManager` | Get the adapter plugin manager.
|
||
|
|
`resetAdapterPluginManager() : void` | Resets the internal adapter plugin manager.
|
||
|
|
`setDefaultAdapter(string|AdapterInterface $adapter /* ... */) : void` | Change the default adapter. Full argument list: `string|AdapterInterface $adapter, AdapterOptions|array|Traversable $adapterOptions = null`.
|
||
|
|
`getDefaultAdapter() : AdapterInterface` | Get the default adapter.
|
||
|
|
`serialize(mixed $data /* ... */) : string` | Generates a storable representation of a value using the default adapter. Optionally, provide a different adapter via the second argument. Full argument list: `mixed $value, string|AdapterInterface $adapter = null, AdapterOptions|array|Traversable $adapterOptions = null`.
|
||
|
|
`unserialize(string $value /* ... */) : mixed` | Creates a PHP value from a stored representation using the default adapter. Optionally, provide a different adapter via the second argument. Full argument list: `string $value, string|AdapterInterface|null $adapter = null, AdapterOptions|array|Traversable $adapterOptions = null`
|