Igbinary is a drop in replacement for the standard php serializer.
C PHP C++ Other
Clone or download
Pull request Compare This branch is 284 commits ahead of somia:master.
TysonAndre Merge pull request #188 from TysonAndre/fix-php73-compiler-warnings
Fix format strings/args for zend_error (normally unreachable)
Latest commit c629472 Jun 10, 2018
Permalink
Failed to load latest commit information.
benchmark Speed up array unserialization Oct 15, 2017
ci Remove references to php 7.2 RCs in travis builds Nov 30, 2017
src Fix format strings/args for zend_error (normally unreachable) Jun 9, 2018
tests Add a separate test for php5 serializing missing properties Apr 1, 2018
.gitignore Rename package2.xml to package.xml Aug 29, 2014
.travis.yml Allow failures for igbinary on php 7.3-dev Mar 26, 2018
COPYING PECL stuff, updated COPYING Aug 28, 2014
CREDITS Add myself to CREDITS Jul 30, 2016
Makefile.bench Add simple and remove ol benmarking scripts. Jul 22, 2012
NEWS Promote igbinary 2.0.6 to stable May 12, 2018
README.md Spelling nits Nov 14, 2017
WINDOWS.md Spelling nits Nov 14, 2017
appveyor.yml Bump php windows test version to 7.1, update windows env variables Jun 10, 2017
config.m4 Remove build flags that cause unavoidable warnings. Mar 26, 2018
config.w32 Windows: Allow session to not be enabled in configure Jan 9, 2018
igbinary.h Fixes main/internal_functions_cli.c ... error: ‘phpext_igbinary_ptr’ … Mar 28, 2017
igbinary.php Initial commit Mar 21, 2009
igbinary.php.ini Add option to disable compacting of duplicate strings. Oct 2, 2009
igbinary.spec Another rm check Dec 31, 2009
package.xml Update rest of package.xml for 2.0.6 (stable) May 12, 2018
php_igbinary.h Fixes main/internal_functions_cli.c ... error: ‘phpext_igbinary_ptr’ … Mar 28, 2017
tags.sh Don't duplicate tags.sh. Run ../../tags.sh instead Jul 30, 2016

README.md

igbinary

Build Status Build status (Windows)

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 compact binary form. Savings are significant when using memcached or similar memory based storages for serialized data. About 50% reduction in storage requirement can be expected. Specific number depends on your data.

Unserialization performance is at least on par with the standard PHP serializer. Serialization performance depends on the igbinary.compact_strings option which enables duplicate string tracking. String are inserted to a hash table which adds some overhead. In usual scenarios this does not have much significance since usage pattern is "serialize rarely, unserialize often". With "compact_strings" option igbinary is usually a bit slower than the standard serializer. Without it, a bit faster.

Features

  • Supports 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, Linux ARM, Mac OSX x86, HP-UX PA-RISC and NetBSD sparc64
  • Hooks up to the APCu in-memory key-value store as a serialization handler. (For older PHP releases, this also hooks up to APC opcode cache(APC 3.1.7+)
  • Compatible with PHP 5.2 – 5.6, 7.0 – 7.2

Implementation details

Storing complex PHP data structures like arrays of associative arrays with the standard PHP serializer is not very space efficient. The main reasons in order of significance are (at least in our applications):

  1. Array keys are repeated redundantly.
  2. Numerical values are plain text.
  3. Human readability adds some overhead.

Igbinary uses two specific strategies to minimize the size of the serialized output.

  1. Repetitive strings are stored only once. Collections of objects benefit significantly from this. See the igbinary.compact_strings option.

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

  3. ( Well, it is not human readable ;)

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

; Enable or disable compacting of duplicate strings
; The default is On.
igbinary.compact_strings=On

; Use igbinary as serializer in APC cache (3.1.7 or later)
;apc.serializer=igbinary

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

Installing

Note: Sometimes phpize must be substituted with phpize5. In such cases the following option must be given to configure script: "--with-php-config=.../php-config5"

  1. phpize

  2. ./configure

    • With GCC: ./configure CFLAGS="-O2 -g" --enable-igbinary
    • With ICC (Intel C Compiler) ./configure CFLAGS=" -no-prec-div -O3 -xO -unroll2 -g" CC=icc --enable-igbinary
    • With clang: ./configure CC=clang CFLAGS="-O0 -g" --enable-igbinary
  3. make

  4. make test

  5. make install

  6. igbinary.so is installed to the default extension directory

To run APCu test cases

# go to modules directory
cd modules

# ... and create symlink to apcu extension
# it will be loaded during test suite
/opt/lib/php/extensions/no-debug-non-zts-20121212/apcu.so

A similar approach should work for APC.

Installing on Windows

If you are a contributor to/packager of igbinary, see WINDOWS.md

Bugs & Contributions

Mailing list for bug reports and other development discussion can be found at http://groups.google.com/group/igbinary

File bug reports at https://github.com/igbinary/igbinary/issues

The preferred ways for contributions are pull requests and email patches (in git format). Feel free to fork at http://github.com/igbinary/igbinary

Utilizing in other extensions

Igbinary can be called from other extensions fairly easily. Igbinary installs its header file to ext/igbinary/igbinary.h. There are just two straightforward functions: igbinary_serialize and igbinary_unserialize. Look at igbinary.h for prototypes and usage.

Add PHP_ADD_EXTENSION_DEP(yourextension, igbinary) to your config.m4 in case someone wants to compile both of them statically into php.

Trivia

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