igbinary
========

What it is?
-----------

Igbinary is a drop in replacement for the standard php serializer. Instead of
time and space consuming textual representation, igbinary stores php data
structures in a compact binary form. Savings are significant when using
memcached or similar memory based storages for serialized data.

But where does the name "igbinary" come from? There was once a similar project
called fbinary but it has disappeared from the Internet. Its architecture
wasn't very clean either. IG is an abbreviation for a finnish social networking
site IRC-Galleria (http:https://irc-galleria.net/)

Supports:
- PHP5 (tested with 5.2.4 and 5.2.5)
- Same data types as the standard php serializer:
  null, bool, int, float, string, array and objects.
- __autoload & unserialize_callback_func
- __sleep & __wakeup
- Serializable -interface
- Data portability between platforms (32/64bit, endianess)
- Tested on Linux amd64, Mac OSX x86 and NetBSD sparc64

Why to use
----------

Storing complex php data structures like arrays of associative arrays in
serialized form is not very space efficient. Igbinary uses two strategies to
minimize size of the serialized form.

Strings are stored only once by using a hash table. Arrays of associate arrays
with very verbose keys are stored very compactly.

Numerical values are stored in the smallest primitive data type available.
123 = int8_t
1234 = int16_t
123456 = int32_t
... and so on.

How to use
----------

Add the following lines to your php.ini:

# Load igbinary extension
extension=igbinary.so

# Use igbinary as session serializer
session.serialize_handler=igbinary

.. and in your php code replace serialize and unserialize function calls
with igbinary_serialize and igbinary_unserialize.

Installing
----------

Note:
Sometimes you may have to substitute phpize with phpize5.
is such cases you will probably want to add "--with-php-config=.../php-config5" as
an option to configure.

Compiling:

1. phpize

If you use GCC:
2. ./configure CFLAGS="-O2 -g" --enable-igbinary

If you use ICC (Intel C Compiler)
2. ./configure CFLAGS=" -no-prec-div -O3 -xO -unroll2 -g" CC=icc --enable-igbinary

3. make
4. ( make test)
5. make install
6. igbinary.so is installed in the default extensions directory

Bugs & Contributions
--------------------

To report bugs, or to contribute fixes and improvements send email to
[email protected]

Use from other extensions
-------------------------

If you are writing own extension and it is possible to use igbinary.
Igbinary installs own header igbinary.h to the ext/igbinary/igbinary.h.
There are just two straighforward functions: igbinary_serialize and igbinary_unserialize.
Look at the igbinary.h for prototypes and more information.

Use PHP_ADD_EXTENSION_DEP(yourextension, igbinary) in config.m4 if someone wants
compile both of them statically into php.