Download the PHP package cnik87/msgpack2 without Composer

msgpack.php

A pure PHP implementation of the MessagePack serialization format.

Features

• Fully compliant with the latest MessagePack specification, including bin, str and ext types
• Supports streaming unpacking
• Supports unsigned 64-bit integers handling
• Supports object serialization
• Works with PHP 5.4-7.x and HHVM 3.9+
• Fully tested
• Relatively fast

Table of contents

• Installation
• Usage
  • Packing
    • Packing options
  • Unpacking
    • Unpacking options
• Extensions
• Type transformers
• Exceptions
• Tests
  • Performance
• License

Installation

The recommended way to install the library is through Composer:

Usage

Packing

To pack values you can either use an instance of a Packer:

or call a static method on the MessagePack class:

In the examples above, the method pack automatically packs a value depending on its type. But not all PHP types can be uniquely translated to MessagePack types. For example, the MessagePack format defines map and array types, which are represented by a single array type in PHP. By default, the packer will pack a PHP array as a MessagePack array if it has sequential numeric keys, starting from 0 and as a MessagePack map otherwise:

However, sometimes you need to pack a sequential array as a MessagePack map. To do this, use the packMap method:

Here is a list of type-specific packing methods:

Check the "Type transformers" section below on how to pack arbitrary PHP objects.

Packing options

The Packer object supports a number of bitmask-based options for fine-tuning the packing process (defaults are in bold):

The type detection mode (DETECT_STR_BIN/DETECT_ARR_MAP) adds some overhead which can be noticed when you pack large (16- and 32-bit) arrays or strings. However, if you know the value type in advance (for example, you only work with UTF-8 strings or/and associative arrays), you can eliminate this overhead by forcing the packer to use the appropriate type, which will save it from running the auto-detection routine. Another option is to explicitly specify the value type. The library provides 2 auxiliary classes for this, Map and Binary. Check the "Type transformers" section below for details.

Examples:

Unpacking

To unpack data you can either use an instance of a BufferUnpacker:

or call a static method on the MessagePack class:

If the packed data is received in chunks (e.g. when reading from a stream), use the tryUnpack method, which attempts to unpack data and returns an array of unpacked messages (if any) instead of throwing an InsufficientDataException:

Besides the above methods BufferUnpacker provides type-specific unpacking methods, namely:

Unpacking options

The BufferUnpacker object supports a number of bitmask-based options for fine-tuning the unpacking process (defaults are in bold):

1. The binary MessagePack format has unsigned 64-bit as its largest integer data type, but PHP does not support such integers, which means that an overflow can occur during unpacking.

2. Make sure that the GMP extension is enabled.

Examples:

Extensions

To define application-specific types use the Ext class:

Type transformers

In addition to the basic types, the library provides functionality to serialize and deserialize arbitrary types. In order to support a custom type you need to create and register a transformer. The transformer should either implement the Packable or the Extension interface.

The purpose of Packable transformers is to serialize a specific value to one of the basic MessagePack types. A good example of such a transformer is a MapTransformer that comes with the library. It serializes Map objects (which are simple wrappers around PHP arrays) to MessagePack maps. This is useful when you want to explicitly mark that a given PHP array must be packed as a MessagePack map, without triggering the type's auto-detection routine.

More types and type transformers can be found in src/Type and src/TypeTransformer directories.

The implementation is trivial:

Once MapTransformer is registered, you can pack Map objects:

Transformers implementing the Extension interface are intended for packing and unpacking application-specific types using the MessagePack's Extension type. For example, the code below shows how to create a transformer that allows you to work transparently with DateTime objects:

Register DateTimeTransformer for both the packer and the unpacker with a unique extension type (an integer from 0 to 127) and you are ready to go:

More type transformer examples can be found in the examples directory.

Exceptions

If an error occurs during packing/unpacking, a PackingFailedException or UnpackingFailedException will be thrown, respectively.

In addition, there are three more exceptions that can be thrown during unpacking:

• InsufficientDataException
• IntegerOverflowException
• InvalidCodeException

An InvalidOptionException will be thrown in case an invalid option (or a combination of mutually exclusive options) is used.

Tests

Run tests as follows:

Also, if you already have Docker installed, you can run the tests in a docker container. First, create a container:

The command above will create a container named msgpack with PHP 7.2 runtime. You may change the default runtime by defining the PHP_RUNTIME environment variable:

See a list of various runtimes here.

Then run the unit tests:

Performance

To check performance, run:

This command will output something like:

You may change default benchmark settings by defining the following environment variables:

• MP_BENCH_TARGETS (pure_p, pure_ps, pure_pa, pure_psa, pure_bu, pecl_p, pecl_u)
• MP_BENCH_ITERATIONS/MP_BENCH_DURATION
• MP_BENCH_ROUNDS
• MP_BENCH_TESTS

For example:

Another example, benchmarking both the library and the msgpack pecl extension:

Note, that this is not a fair comparison as the msgpack extension (0.5.2+, 2.0) doesn't support ext, bin and UTF-8 str types.

License

The library is released under the MIT License. See the bundled LICENSE file for details.