README

  Serialized - PHP Library for Serialized Data

  Copyright (C) 2010-2011 Tom Klingenberg, some rights reserved

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU Affero General Public License as
    published by the Free Software Foundation, either version 3 of the
    License, or (at your option) any later version.

    See COPYING.

  README

    Serialized is a set of classes that can parse serialized data into a
  normalized representation (semi structured data or S-expression).

    The base service is to parse serialized data into a so called Array
  Notation which represents both structure and the value(s) of PHP
  serialized data. See ARRAYNOT.

    This can be used to inspect and validate serialized data w/o the need
  to unserialize it first. For example if waking up sleeping objects is
  unwanted (parsing instead the factual process of unserializing). The
  parsed data can then be inspected and changed.

    Serialized variables (Sessions) are supported as well. Those are
  a list of serialized values with their variable name.

    Potential field of use is static data analysis, session display,
  inspection and manipulation of serialized data, converting etc. .

    Right now, the library can already do both: parsing into the Array
  Notation and dumping it into serialized data again. Output into other
  formats (Text, XML, ...) is possible as well.

    The following output formats to display serialized data and sessions
  are - as of now - available (example of a serialized array data sample
  dumped differently):

    * Text - Plain text, suitable for display in a shell environment.

        `-- array(4):
             +-- [user] => string(9): "user-name"
             +-- [network] => array(1):
             |    `-- [localip] => string(7): "1.2.3.4"
             +-- [2] => string(4): "Zwei"
             `-- [language] => string(6): "german"

    * XML - Well-formed, machine readable and easy to convert.

        <?xml version="1.0" encoding="us-ascii"?>
        <serialized>
          <array members="4">
            <item name="user" type="string">
              <string len="9" value="user-name"/>
            </item>
            <item name="network" type="string">
              <array members="1">
                <item name="localip" type="string">
                  <string len="7" value="1.2.3.4"/>
                </item>
              </array>
            </item>
            <item name="2" type="int">
              <string len="4" value="Zwei"/>
            </item>
            <item name="language" type="string">
              <string len="6" value="german"/>
            </item>
          </array>
        </serialized>

    * Serialized - To store back.

        a:4:{s:4:"user";s:9:"user-name";s:7:"network";a:1:{s:7:"localip";\
        s:7:"1.2.3.4";}i:2;s:4:"Zwei";s:8:"language";s:6:"german";}

    The library sources contain a test-suite to guarantee a certain level
  of confidence and strictness.

    If you run into any problems with serialized data on your end, please
  report back as this improves the library. This will help to break the
  parser so to reproduce and extend the test-suite with abstracted
  serialized data for future regression testing.

    Naturally private data will be anonmyzed before it is put into the test-
  suite and generally it will not be published w/o a written consent.

    Feedback of any kind is always warmheartly appreciated.

    Requirements:

    PHP 5.3.3 or higher
    PHPUNIT 3.5.5 or higher (for the test-suite)

    Use:

      To make use of the library, copy over the src directory into your
    library folder.

      Serialized ships with a PSR-0 compatbile autoloader. To make use of the
    library require the base file:

      require_once('library/Serialized.php');

      After including it (the autoloader), auto-loading is enabled and the
    parser and the dumpers can be used:

      $array = Serialized\Parser::parse($serialized);

      Example: 00-basic-parsing

      Instead of using the autoloader, the library can be manually loaded as
    well:

      require_once('library/Serialized.php');
      Serialized::loadLibrary();

      For debugging purposes, there is a dump function which prints structure
    and data of a serialized string to standard output:

      $parser = new Serialized\Parser($serialized);
      $parser->dump();

      Example: 01-debug-dump

    Resources:

    PHP Serialize Function (PHP Manual)
  http://php.net/manual/en/function.serialize.php

    PHP Unserialize Function (PHP Manual)
  http://php.net/manual/en/function.unserialize.php

    Object Serialization (PHP Manual)
  http://php.net/manual/en/language.oop5.serialization.php

    The Serializable interface (PHP Manual)
  http://php.net/manual/en/class.serializable.php

    Runtime Configuration "unserialize_callback_func" (PHP Manual)
  http://www.php.net/manual/en/var.configuration.php#unserialize-callback-func

    PHP Session Decode Function (PHP Manual)
  http://php.net/manual/en/function.session-decode.php

    PHP Serialize C Sourcecode
  http://svn.php.net/viewvc/php/php-src/trunk/ext/standard/var.c

    PHP Unserialize C Sourcecode
  http://svn.php.net/viewvc/php/php-src/trunk/ext/standard/var_unserializer.re

    PHP Serialization And Recursion Demystified (by Andrea Giammarchi; 2009-09-07)
  http://webreflection.blogspot.com/2009/09/php-serialization-and-recursion.html

    Recursive Reference Serialize Library (by Nghia Nguyen; 2009-06-01)
  http://www.phpclasses.org/package/5336-PHP-Serialize-objects-with-cyclic-references.html