README.md
1igbinary
2========
3
4[](https://github.com/igbinary/igbinary/actions/workflows/main.yml?query=branch%3Amaster)
5[](https://travis-ci.org/igbinary/igbinary)
6[](https://ci.appveyor.com/project/TysonAndre/igbinary-bemsx)
7
8Igbinary is a drop in replacement for the standard php serializer.
9Instead of the time and space consuming textual representation used by PHP's `serialize`,
10igbinary stores php data structures in a compact binary form.
11Memory savings are significant when using memcached, APCu, or similar memory based storages for serialized data.
12The typical reduction in storage requirements are around 50%.
13The exact percentage depends on your data.
14
15Unserialization performance is [at least on par with the standard PHP serializer, and is much faster for repetitive data](benchmarks/comparisons.php).
16Serialization performance depends on the `igbinary.compact_strings` option which enables
17duplicate string tracking.
18String are inserted to a hash table, which adds some overhead when serializing.
19In usual scenarios this does not have much of an impact,
20because the typical usage pattern is "serialize rarely, unserialize often".
21With the `compact_strings` option enabled,
22igbinary is usually a bit slower than the standard serializer.
23Without it, igbinary is a bit faster.
24
25Features
26--------
27
28- Support for the same data types as the standard PHP serializer: null, bool, int,
29 float, string, array and object.
30- `__autoload` & `unserialize_callback_func`
31- `__sleep` & `__wakeup`
32- `__serialize` & `__unserialize` (only used in php 7.4+)
33- Serializable -interface
34- Data portability between platforms (32/64bit, endianness)
35- Tested on Linux amd64, Linux ARM, Mac OSX x86, HP-UX PA-RISC and NetBSD sparc64
36- Hooks up to the APCu in-memory key-value store as a serialization handler.
37- Compatible with 7.0 – 8.0 (The older igbinary [2.x releases](https://github.com/igbinary/igbinary/tree/v2) support 5.2 – 5.6, 7.0 – 7.3)
38
39Implementation details
40----------------------
41
42Storing complex PHP data structures such as arrays of associative arrays
43with the standard PHP serializer is not very space efficient.
44The main reasons of this inefficiency are listed below, in order of significance (at least in our applications):
45
461. Array keys, property names, and class names are repeated redundantly.
472. Numerical values are plain text.
483. Human readability adds some overhead.
49
50Igbinary uses two strategies to minimize the size of the serialized
51output.
52
531. Repeated strings are stored only once (this also includes class and property names).
54 Collections of objects benefit significantly from this.
55 See the `igbinary.compact_strings` option.
56
572. Integer values are stored in the smallest primitive data type available:
58 *123* = `int8_t`,
59 *1234* = `int16_t`,
60 *123456* = `int32_t`
61 ... and so on.
62
633. ( Well, it is not human readable ;)
64
65How to use
66----------
67
68Add the following lines to your php.ini:
69
70```ini
71; Load igbinary extension
72extension=igbinary.so
73
74; Use igbinary as session serializer
75session.serialize_handler=igbinary
76
77; Enable or disable compacting of duplicate strings
78; The default is On.
79igbinary.compact_strings=On
80
81; If uncommented, use igbinary as the serializer of APCu
82; (APCu 5.1.10 or newer is strongly recommended)
83;apc.serializer=igbinary
84```
85
86Then, in your php code, replace `serialize` and `unserialize` function calls
87with [`igbinary_serialize` and `igbinary_unserialize`](./igbinary.php).
88
89Installing
90----------
91
92### Linux
93
94If PHP was installed through your package manager,
95the package manager may also contain prebuilt packages for `igbinary`
96(with a package name similar to php-igbinary).
97
98- The packages from some package managers and OS versions may be out of date and have known bugs. The latest release of igbinary is [](https://github.com/igbinary/igbinary/releases)
99
100Igbinary may also be installed with the command `pecl install igbinary` (You will need to enable igbinary in php.ini)
101
102Alternately, you may wish to [build from source](#building-from-source)
103
104### MacOS
105
106`pecl install igbinary` is the recommended installation method (You will need to enable igbinary in php.ini)
107
108Alternately, you may wish to [build from source](#building-from-source).
109
110### Installing on Windows
111
112Prebuilt DLLs can be [downloaded from PECL](https://pecl.php.net/package/igbinary).
113
114If you are a contributor to/packager of igbinary, or need to build from source, see [WINDOWS.md](./WINDOWS.md)
115
116### Building from source
117
1181. `phpize`
1192. `./configure`
120
121 - With GCC: `./configure CFLAGS="-O2 -g" --enable-igbinary`
122 - With ICC (Intel C Compiler) `./configure CFLAGS=" -no-prec-div -O3 -xO -unroll2 -g" CC=icc --enable-igbinary`
123 - With clang: `./configure CC=clang CFLAGS="-O0 -g" --enable-igbinary`
1243. `make`
1254. `make test`
1265. `make install`
1276. `igbinary.so` is installed to the default extension directory
128
129Bugs & Contributions
130--------------------
131
132Mailing list for bug reports and other development discussion can be found
133at http://groups.google.com/group/igbinary (no longer used)
134
135File bug reports at
136https://github.com/igbinary/igbinary/issues
137
138The preferred way to contribute is with pull requests.
139Feel free to fork this at http://github.com/igbinary/igbinary
140
141See [TESTING.md](./TESTING.md) for advice for testing patches.
142
143See [TECH\_NOTES.md](./TECH_NOTES.md) for information about how igbinary is implemented
144
145Utilizing in other extensions
146-----------------------------
147
148Igbinary can be called from other extensions fairly easily. Igbinary installs
149its header file to _ext/igbinary/igbinary.h_. There are just two straightforward
150functions: `igbinary_serialize` and `igbinary_unserialize`. Look at _igbinary.h_ for
151prototypes and usage.
152
153Add `PHP_ADD_EXTENSION_DEP(yourextension, igbinary)` to your _config.m4_ in case
154someone wants to compile both of them statically into php.
155
156Trivia
157------
158
159Where does the name "igbinary" come from? There was once a similar project
160called fbinary but it has disappeared from the Internet a long time ago. Its
161architecture wasn't particularly clean either. IG is an abbreviation for a
162Finnish social networking site IRC-Galleria (http://irc-galleria.net/)
163
){kind=link}
){kind=link}
){kind=link}