documentation/manual/en/module_specs/Zend_Serializer-Adapter.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.serializer.adapter">
   4     <title>Zend_Serializer_Adapter</title>
   5
   6     <para>
   7         <classname>Zend_Serializer</classname> adapters create a bridge for different methods of
   8         serializing with very little effort.
   9     </para>
  10
  11     <para>
  12         Every adapter has different pros and cons. In some cases, not every <acronym>PHP</acronym>
  13         datatype (e.g., objects) can be converted to a string representation. In most such cases,
  14         the type will be converted to a similar type that is serializable -- as an example,
  15         <acronym>PHP</acronym> objects will often be cast to arrays. If this fails, a
  16         <classname>Zend_Serializer_Exception</classname> will be thrown.
  17     </para>
  18
  19     <para>
  20         Below is a list of available adapters.
  21     </para>
  22
  23     <sect2 id="zend.serializer.adapter.phpserialize">
  24         <title>Zend_Serializer_Adapter_PhpSerialize</title>
  25
  26         <para>
  27             This adapter uses the built-in <methodname>un/serialize</methodname>
  28             <acronym>PHP</acronym> functions, and is a good default adapter choice.
  29         </para>
  30
  31         <para>
  32             There are no configurable options for this adapter.
  33         </para>
  34     </sect2>
  35
  36     <sect2 id="zend.serializer.adapter.igbinary">
  37         <title>Zend_Serializer_Adapter_Igbinary</title>
  38
  39         <para>
  40             <ulink url="http://opensource.dynamoid.com">Igbinary</ulink> is Open Source Software
  41             released by Sulake Dynamoid Oy. It's a drop-in replacement for the standard
  42             <acronym>PHP</acronym> serializer. Instead of time and space consuming textual
  43             representation, igbinary stores <acronym>PHP</acronym> data structures in a compact
  44             binary form. Savings are significant when using memcached or similar memory based
  45             storages for serialized data.
  46         </para>
  47
  48         <para>
  49             You need the igbinary <acronym>PHP</acronym> extension installed on your system in order
  50             to use this adapter.
  51         </para>
  52
  53         <para>
  54             There adapter takes no configuration options.
  55         </para>
  56     </sect2>
  57
  58     <sect2 id="zend.serializer.adapter.wddx">
  59         <title>Zend_Serializer_Adapter_Wddx</title>
  60
  61         <para>
  62             <ulink url="http://wikipedia.org/wiki/WDDX">WDDX</ulink> (Web Distributed Data eXchange)
  63             is a programming-language-, platform-, and transport-neutral data interchange mechanism
  64             for passing data between different environments and different computers.
  65         </para>
  66
  67         <para>
  68             The adapter simply uses the <ulink
  69                 url="http://php.net/manual/book.wddx.php">wddx_*()</ulink> <acronym>PHP</acronym>
  70             functions. Please read the <acronym>PHP</acronym> manual to determine how you may enable
  71             them in your <acronym>PHP</acronym> installation.
  72         </para>
  73
  74         <para>
  75             Additionally, the <ulink
  76                 url="http://php.net/manual/book.simplexml.php">SimpleXML</ulink>
  77             <acronym>PHP</acronym> extension is used to check if a returned
  78             <constant>NULL</constant> value from <methodname>wddx_unserialize()</methodname> is
  79             based on a serialized <constant>NULL</constant> or on invalid data.
  80         </para>
  81
  82         <para>
  83             Available options include:
  84         </para>
  85
  86         <table id="zend.serializer.adapter.wddx.table.options">
  87             <title>Zend_Serializer_Adapter_Wddx Options</title>
  88
  89             <tgroup cols="4">
  90                  <thead>
  91                       <row>
  92                           <entry>Option</entry>
  93                           <entry>Data Type</entry>
  94                           <entry>Default Value</entry>
  95                           <entry>Description</entry>
  96                     </row>
  97                  </thead>
  98
  99                  <tbody>
 100                       <row>
 101                           <entry><emphasis>comment</emphasis></entry>
 102                           <entry><type>string</type></entry>
 103                           <entry></entry>
 104                           <entry>An optional comment that appears in the packet header.</entry>
 105                       </row>
 106                   </tbody>
 107              </tgroup>
 108         </table>
 109     </sect2>
 110
 111     <sect2 id="zend.serializer.adapter.json">
 112         <title>Zend_Serializer_Adapter_Json</title>
 113
 114         <para>
 115             The <acronym>JSON</acronym> adapter provides a bridge to the
 116             <classname>Zend_Json</classname> component and/or ext/json. Please read the <link
 117                 linkend= "zend.json.introduction">Zend_Json documentation</link> for further
 118             information.
 119         </para>
 120
 121         <para>
 122             Available options include:
 123         </para>
 124
 125         <table id="zend.serializer.adapter.json.table.options">
 126             <title>Zend_Serializer_Adapter_Json Options</title>
 127
 128             <tgroup cols="4">
 129                  <thead>
 130                       <row>
 131                         <entry>Option</entry>
 132                         <entry>Data Type</entry>
 133                         <entry>Default Value</entry>
 134                         <entry>Description</entry>
 135                     </row>
 136                  </thead>
 137
 138                  <tbody>
 139                       <row>
 140                           <entry><emphasis>cycleCheck</emphasis></entry>
 141                           <entry><type>boolean</type></entry>
 142                           <entry>false</entry>
 143                           <entry>See <xref linkend="zend.json.advanced.objects1"/></entry>
 144                       </row>
 145
 146                       <row>
 147                           <entry><emphasis>objectDecodeType</emphasis></entry>
 148                           <entry><type>Zend_Json::TYPE_*</type></entry>
 149                           <entry>Zend_Json::TYPE_ARRAY</entry>
 150                           <entry>See <xref linkend= "zend.json.advanced.objects1"/></entry>
 151                       </row>
 152
 153                       <row>
 154                           <entry><emphasis>enableJsonExprFinder</emphasis></entry>
 155                           <entry><type>boolean</type></entry>
 156                           <entry>false</entry>
 157                           <entry>See <xref linkend= "zend.json.advanced.expr"/></entry>
 158                       </row>
 159                   </tbody>
 160              </tgroup>
 161         </table>
 162     </sect2>
 163
 164     <sect2 id="zend.serializer.adapter.amf03">
 165         <title>Zend_Serializer_Adapter_Amf 0 and 3</title>
 166
 167         <para>
 168             The <acronym>AMF</acronym> adapters, <classname>Zend_Serializer_Adapter_Amf0</classname>
 169             and <classname>Zend_Serializer_Adapter_Amf3</classname>, provide a bridge to the
 170             serializer of the <classname>Zend_Amf</classname> component. Please read the <link
 171                 linkend= "zend.amf.introduction">Zend_Amf documentation</link> for further
 172             information.
 173         </para>
 174
 175         <para>
 176             There are no options for these adapters.
 177         </para>
 178     </sect2>
 179
 180     <sect2 id="zend.serializer.adapter.pythonpickle">
 181         <title>Zend_Serializer_Adapter_PythonPickle</title>
 182
 183         <para>
 184             This adapter converts <acronym>PHP</acronym> types to a <ulink
 185                 url="http://docs.python.org/library/pickle.html">Python Pickle</ulink> string
 186             representation. With it, you can read the serialized data with Python and read Pickled
 187             data of Python with <acronym>PHP</acronym>.
 188         </para>
 189
 190         <para>
 191             Available options include:
 192         </para>
 193
 194         <table id="zend.serializer.adapter.pythonpickle.table.options">
 195             <title>Zend_Serializer_Adapter_PythonPickle Options</title>
 196
 197             <tgroup cols="4">
 198                  <thead>
 199                       <row>
 200                         <entry>Option</entry>
 201                         <entry>Data Type</entry>
 202                         <entry>Default Value</entry>
 203                         <entry>Description</entry>
 204                     </row>
 205                  </thead>
 206
 207                  <tbody>
 208                       <row>
 209                           <entry><emphasis>protocol</emphasis></entry>
 210                           <entry><type>integer</type> (0 | 1 | 2 | 3)</entry>
 211                           <entry>0</entry>
 212
 213                           <entry>
 214                                The Pickle protocol version used on
 215                                <methodname>serialize</methodname>
 216                           </entry>
 217                       </row>
 218                   </tbody>
 219              </tgroup>
 220         </table>
 221
 222         <para>
 223             Datatype merging (PHP to Python) occurs as follows:
 224         </para>
 225
 226         <table id="zend.serializer.adapter.pythonpickle.table.php2python">
 227             <title>Datatype merging (PHP to Python)</title>
 228
 229             <tgroup cols="2">
 230                  <thead>
 231                       <row>
 232                         <entry>PHP Type</entry>
 233                         <entry>Python Type</entry>
 234                     </row>
 235                  </thead>
 236
 237                  <tbody>
 238                       <row>
 239                           <entry><type>NULL</type></entry>
 240                           <entry><type>None</type></entry>
 241                       </row>
 242
 243                       <row>
 244                           <entry><type>boolean</type></entry>
 245                           <entry><type>boolean</type></entry>
 246                       </row>
 247
 248                       <row>
 249                           <entry><type>integer</type></entry>
 250                           <entry><type>integer</type></entry>
 251                       </row>
 252
 253                       <row>
 254                           <entry><type>float</type></entry>
 255                           <entry><type>float</type></entry>
 256                       </row>
 257
 258                       <row>
 259                           <entry><type>string</type></entry>
 260                           <entry><type>string</type></entry>
 261                       </row>
 262
 263                       <row>
 264                           <entry><type>array</type></entry>
 265                           <entry><type>list</type></entry>
 266                       </row>
 267
 268                       <row>
 269                           <entry><type>associative array</type></entry>
 270                           <entry><type>dictionary</type></entry>
 271                       </row>
 272
 273                       <row>
 274                           <entry><type>object</type></entry>
 275                           <entry><type>dictionary</type></entry>
 276                       </row>
 277                   </tbody>
 278              </tgroup>
 279         </table>
 280
 281         <para>
 282             Datatype merging (Python to <acronym>PHP</acronym>) occurs per the following:
 283         </para>
 284
 285         <table id="zend.serializer.adapter.pythonpickle.table.python2php">
 286             <title>Datatype merging (Python to PHP)</title>
 287
 288             <tgroup cols="2">
 289                  <thead>
 290                       <row>
 291                         <entry>Python-Type</entry>
 292                         <entry>PHP-Type</entry>
 293                     </row>
 294                  </thead>
 295
 296                  <tbody>
 297                       <row>
 298                           <entry><type>None</type></entry>
 299                           <entry><type>NULL</type></entry>
 300                       </row>
 301
 302                       <row>
 303                           <entry><type>boolean</type></entry>
 304                           <entry><type>boolean</type></entry>
 305                       </row>
 306
 307                       <row>
 308                           <entry><type>integer</type></entry>
 309                           <entry><type>integer</type></entry>
 310                       </row>
 311
 312                       <row>
 313                           <entry><type>long</type></entry>
 314
 315                           <entry>
 316                               <type>integer</type> | <type>float</type> | <type>string</type>
 317                               | <classname>Zend_Serializer_Exception</classname>
 318                           </entry>
 319                       </row>
 320
 321                       <row>
 322                           <entry><type>float</type></entry>
 323                           <entry><type>float</type></entry>
 324                       </row>
 325
 326                       <row>
 327                           <entry><type>string</type></entry>
 328                           <entry><type>string</type></entry>
 329                       </row>
 330
 331                       <row>
 332                           <entry><type>bytes</type></entry>
 333                           <entry><type>string</type></entry>
 334                       </row>
 335
 336                       <row>
 337                           <entry><type>Unicode string</type></entry>
 338                           <entry><type>UTF-8 string</type></entry>
 339                       </row>
 340
 341                       <row>
 342                           <entry><type>list</type></entry>
 343                           <entry><type>array</type></entry>
 344                       </row>
 345
 346                       <row>
 347                           <entry><type>tuple</type></entry>
 348                           <entry><type>array</type></entry>
 349                       </row>
 350
 351                       <row>
 352                           <entry><type>dictionary</type></entry>
 353                           <entry><type>associative array</type></entry>
 354                       </row>
 355
 356                       <row>
 357                           <entry>All other types</entry>
 358                           <entry><classname>Zend_Serializer_Exception</classname></entry>
 359                       </row>
 360                   </tbody>
 361              </tgroup>
 362         </table>
 363     </sect2>
 364
 365     <sect2 id="zend.serializer.adapter.phpcode">
 366         <title>Zend_Serializer_Adapter_PhpCode</title>
 367
 368         <para>
 369             This adapter generates a parsable <acronym>PHP</acronym> code representation using
 370             <ulink url="http://php.net/manual/function.var-export.php">var_export()</ulink>. On
 371             restoring, the data will be executed using <ulink
 372                 url="http://php.net/manual/function.eval.php">eval</ulink>.
 373         </para>
 374
 375         <para>
 376             There are no configuration options for this adapter.
 377         </para>
 378
 379         <warning>
 380             <title>Unserializing objects</title>
 381
 382             <para>
 383                 Objects will be serialized using the <ulink
 384                     url="http://php.net/manual/language.oop5.magic.php#language.oop5.magic.set-state">__set_state</ulink>
 385                 magic method. If the class doesn't implement this method, a fatal error will occur
 386                 during execution.
 387             </para>
 388         </warning>
 389
 390         <warning>
 391             <title>Uses eval()</title>
 392
 393             <para>
 394                 The <classname>PhpCode</classname> adapter utilizes <methodname>eval()</methodname>
 395                 to unserialize. This introduces both a performance and potential security issue as a
 396                 new process will be executed. Typically, you should use the
 397                 <methodname>PhpSerialize</methodname> adapter unless you require human-readability
 398                 of the serialized data.
 399             </para>
 400         </warning>
 401     </sect2>
 402 </sect1>
 403 <!--
 404 vim:se ts=4 sw=4 et:
 405 -->