unserialize

(PHP 3 >= 3.0.5, PHP 4, PHP 5)

unserialize --  Creates a PHP value from a stored representation

Description

mixed unserialize ( string str )

unserialize() takes a single serialized variable (see serialize()) and converts it back into a PHP value. The converted value is returned, and can be a boolean, integer, float, string, array or object. In case the passed string is not unserializeable, FALSE is returned and E_NOTICE is issued.

Внимание

FALSE is returned both in the case of an error and if unserializing the serialized FALSE value. This special case can be catched by comparing str with serialize(false) or by catching the issued E_NOTICE.

unserialize_callback_func directive: It's possible to set a callback-function which will be called, if an undefined class should be instantiated during unserializing. (to prevent getting an incomplete object "__PHP_Incomplete_Class".) Use your php.ini, ini_set() or .htaccess to define 'unserialize_callback_func'. Everytime an undefined class should be instantiated, it'll be called. To disable this feature just empty this setting. Also note that the directive unserialize_callback_func directive became available in PHP 4.2.0.

If the variable being unserialized is an object, after successfully reconstructing the object PHP will automatically attempt to call the __wakeup() member function (if it exists).

Пример 1. unserialize_callback_func example

<?php
$serialized_object='O:1:"a":1:{s:5:"value";s:3:"100";}';

// unserialize_callback_func directive available as of PHP 4.2.0
ini_set('unserialize_callback_func', 'mycallback'); // set your callback_function

function mycallback($classname)
{
   // just include a file containing your classdefinition
   // you get $classname to figure out which classdefinition is required
}
?>

Замечание: In PHP 3, methods are not preserved when unserializing a serialized object. That limitation was removed in PHP 4 as both properties and methods are now restored. Please see the Serializing Objects section of Classes and Objects or more information.

Пример 2. unserialize() example

<?php
// Here, we use unserialize() to load session data to the
// $session_data array from the string selected from a database.
// This example complements the one described with serialize().

$conn = odbc_connect("webdb", "php", "chicken");
$stmt = odbc_prepare($conn, "SELECT data FROM sessions WHERE id = ?");
$sqldata = array ($PHP_AUTH_USER);
if (!odbc_execute($stmt, &$sqldata) || !odbc_fetch_into($stmt, &$tmp)) {
   // if the execute or fetch fails, initialize to empty array
   $session_data = array();
} else {
   // we should now have the serialized data in $tmp[0].
   $session_data = unserialize($tmp[0]);
   if (!is_array($session_data)) {
       // something went wrong, initialize to empty array
       $session_data = array();
   }
}
?>

See also serialize().



unserialize
chad 0x40 herballure 0x2e com
05-May-2006 09:08
When unserializing in PHP5 (behavior observed with 5.1.2), __autoload() will be checked first, and unserialize_callback_func called only if __autoload failed to load the class definition.
fhummel at hotmail dot com
01-Mar-2006 09:37
I have noticed that using the eval function as described in other posts might produce class redefinitions if separate class files are used and included.

My solution was to include_once at the top all .php files with classes that will be used on a particular page. This way the class definition exists when unserialize is called and you get the no duplicate check for free by using include_once.

Maybe someone can chime in on how this might affect performance.
onuryerlikaya at hotmail dot com
09-Feb-2006 04:00
<?php

// Create your array()
$array = array("First","Second","Third");
// Create your package
$package = serialize($array);

// You can print your serialized package
// a:3:{i:0;s:5:"First";i:1;s:6:"Second";i:2;s:5:"Third";}
print $package."<br>";

// Unserialize your serialized package with print_r or var_dump
$data    = unserialize($package);
print_r($data);
// var_dump($data); // It's same as print_r
// Array ( [0] => First [1] => Second [2] => Third )
?>
Jules
29-Jan-2006 08:49
"Moreover, you must be *very* careful when using eval() as it can be easily used to do something nasty."

Actually, you should probably be equally careful with unserialize, as using it might result in code from your (or standard PHP) classes being executed when you aren't expecting it.  It's clearly harder to exploit, but the possibility is there.  Therefore, only unserialize data that you know you generated yourself (either because it's stored where you put it, or because its signed, or has been validated in some other way).
mina86 at projektcode dot org
19-Jan-2006 10:28
Accualy artistan's function does not work (there should be $serialized_data instead of $text in function body). Moreover, you must be *very* careful when using eval() as it can be easily used to do something nasty. Here comes what I've made basing on the two available versions:

<?php
function unserialize_data($str, $objs = true) {
   if ($objs && preg_match_all('/O:\d+:"([a-zA-Z0-9_]+)":/', $str, $arr)) {
       $callback = ini_get('unserialize_callback_func');
       foreach ($arr[1] as $cls) {
           if (!class_exists($cls)) {
               call_user_func($callback, $cls);
           }
           if (!class_exists($cls)) {
               eval('class ' . $cls . ' { }');
           }
       }
   }
   return unserialize($str); 
}
?>

However, better (not tested though) sollution seems to be:

<?php
function declare_empty_class($classname) {
   static $callback = null;
   if ($callback===null) {
       $callback = $classname;
       return;
   }
   if ($callback) {
       call_user_func($callback, $classname);
   }
   if (!class_exists($classname)) {
       eval('class ' . $classname . ' { }');
   }
}
declare_empty_class(ini_get('unserialize_callback_func'));
ini_set('unserialize_callback_func', 'declare_empty_class');
?>
artistan at cableone dot net
11-Jan-2006 08:46
// thanks to user comments I created this

   /**
       UnSerialize and return data
       @param string [$serialized_data] data to unserialize
       @return mixed
   */
   function unserialize_data($serialized_data,$objects=true){
       if($objects){
           // thanks to comment from veg@rd.no 04-Jan-2006 10:34 at http://us2.php.net/manual/en/function.unserialize.php
           // make classes for those that do not exist
           $matches = Array();
           preg_match_all('/O:(\d)*:"([^":]*)":/', $text, $matches);
           foreach ($matches[2] as $class)
           {
               if(!class_exists($class))
                   eval('class '.$class.' { }');
           }
       }
         return unserialize($serialized_data);
   }

// if using php5 you may want to modify to use __autoload function.
veg at rd dot no
04-Jan-2006 10:34
Unserializing an object of a class that hasn't been declared where it is being unserialized will result in an unusable object. I do not know why this happens, but I know of two workarounds which I've written about here; http://vega.rd.no/entry/200601_serializing_objects_in_php

In short, the solution is to declare the class before unserializing the object; so this code will do when unserializing an object of type MyClass;

<?php
   class MyClass {}
   $object = unserialize($serializedData);
?>

However, if you have several different classes, which you don't necessarily know the names of beforehand, use this short function to handle it for you;

<?php
   function unserializeUnknownObject($text)
   {
       $matches = Array();
       preg_match_all('/O:(\d)*:"([^":]*)":/', $text, $matches);
       foreach ($matches[2] as $class)
       {
           eval('class '.$class.' { }');
       }
       return unserialize($text);
   }
   $object = unserializeUnknownObject($serializedData);
?>

This could also have been accomplished by using unserialize_callback_func.
tarwin at gmail dot com
18-Dec-2005 05:30
I screwed around with this for hours and hours and it was doing my head in. Hopefully this can help.

When I was loading my page which was unserializing a string it would just hang (not finish sending information to the browser) at random places if I had not put the Class information first.

This is probably obvious (I know it says that it "will not work" if I do not declare the classes first) but the strange error of randomly stopping putting data to the page was very offputting from the actual error. It seems to go for a few KB or something and then just decide to stop.
none at none dot none
10-Dec-2005 07:57
The only complaint I have about serializing, is that it will not save the variable name.  To fix this, as well as add support for more then one variable/array, I chose to write this class:

 class SaveVar
 {
  function store($list)
  {
   $sl = explode("|", $list);
   for ($i = 0; $i < count($sl); $i++)
   {
   $varname    = $sl[$i];
   global $$varname;
   $thevar    = $$varname;
   $serialized = serialize($thevar);
   $saved[$i] = base64_encode($varname)."@".base64_encode($serialized);
   }
   $data = implode("|", $saved);
   return($data);
  }

  function restore($stored)
  {
   $sv = explode("|", $stored);
   for ($i = 0; $i < count($sv); $i++)
   {
   $svp  = $sv[$i];
   list($name64, $value64) = explode("@", $svp);
   $name  = base64_decode($name64);
   $value = base64_decode($value64);
   global $$name;
   $$name = unserialize($value);
   }
  }
 }

----

An example of using this class is as follows...

----

 $arr1 = array("Hello", "World");
 $arr2 = array("World", "Hello");

 $sv = new SaveVar;

 $saved = $sv->store("arr1|arr2");

 $arr1 = NULL;
 $arr2 = NULL;

 echo $saved;
 echo "<HR>";
 $sv->restore($saved);

 print_r($arr1);
 echo "<BR>";
 print_r($arr2);

----

I hope someone finds this useful...

   -Jestin S Larson
martin dot goldinger at netserver dot ch
15-Aug-2005 04:48
When you use sessions, its very important to keep the sessiondata small, due to low performance with unserialize. Every class shoud extend from this class. The result will be, that no null Values are written to the sessiondata. It will increase performance.

<?
class BaseObject
{
   function __sleep()
   {
       $vars = (array)$this;
       foreach ($vars as $key => $val)
       {
           if (is_null($val))
           {
               unset($vars[$key]);
           }
       }   
       return array_keys($vars);
   }
};
?>
ungu at terong dot com
05-Feb-2005 10:20
I got the same case as yabba at the dot hut with his post
>> caveat: stripslashes!!!

In my server configutation the magic_quotes_gpc is on therefore it will automatically escape ' (single-quote), " (double quote), \ (backslash) and NUL's with a backslash.
And the stripslashes is the workaround for my case as well.

Erwin
Chris Hayes (chris at hypersites dot com)
23-Oct-2004 09:27
In reply to the earlier post about having to include object definitions *before* using unserialize.  There is a workaround for this.

When an object is serialized, the first bit of the string is actually the name of the class.  When an unknown object is unserialized, this is maintained as a property.  So if you serialize it again, you get back the exact same string as if you'd serialized the original object.  Basically, to cut to the point...

If you use

$_SESSION['my_object'] = unserialize(serialize($_SESSION['my_object']))

then you get back an object of the correct type, even if the session had originally loaded it as an object of type stdClass.
hfuecks at phppatterns dot com
09-Sep-2004 04:14
If you are accepting a serialized string from an untrusted source (e.g. generated in Javascript), you need to be careful to check that it doesn't result in "unexpected" objects being created when you unserialize it.

The following function pulls out the class names of all objects in a _valid_ serialized string. It works by first removing an serialized string values (which might contain serialized object syntax) then pulling out the class names from the remaining string. The returned value is a unique list of class names which the serialized string contains.

Note it assumes the serialized string is valid (that it will be accepted by unserialize()). There may be invalid serialized strings that could trick this function but these should fail when unserialized.

<?php
function getSerializedClassNames($string) {

   // Stip any string representations (which might contain object syntax)
   $string = preg_replace('/s:[0-9]+:".*"/Us','',$string);

   // Pull out the class named
   preg_match_all('/O:[0-9]+:"(.*)"/U', $string, $matches, PREG_PATTERN_ORDER);

   // Make sure names are unique (same object serialized twice)
   return array_unique($matches[1]);

}
?>

Unit tests for a version of this function can be found at:

http://cvs.sourceforge.net/viewcvs.py/xmlrpccom
   /scriptserver/tests/php/classparser.test.php?view=auto

See also the discussion here;
http://marc.theaimsgroup.com/?t=109439858700006&r=1&w=2
http://marc.theaimsgroup.com/?l=php-dev&m=109444959007776&w=2
pfister at avenir dot de
02-Sep-2004 02:25
Having had a problem with an mysql-stored serialized array which I had edited I found out that unserialize seems to have got a problem with "\r" within the string I wanted to unserialize.

It simply quits it's job with "false".

To work arround this problem I just replaced \r with "":

<?php
$serializedArray = 'a:1:{i:0;a:2:{s:4:"name";s:70:"Here comes the newline\r\nthis is the new line";s:5:"value";d:2.20;}}';

var_dump(unserialize($serializedArray)); //This just outputs bool(false)

$serializedArray = str_replace("\r", "", $serializedArray);

var_dump(unserialize($serializedArray)); //This outputs the array structure
?>
eoin at joy dot ucc dot ie
17-Aug-2004 11:38
I recently found myself in need of unserializing PHP session data (stored in a database) that had expired but was not yet deleted i.e. I needed to get at the contents of the session but was unable to use the usual PHP interface. The following function takes a string of serialized session data and returns an array of PHP values. The structure of the returned array is the same as the $_SESSION array if you were using the normal interface. I haven't tested this extensively but it did the job for me.

<?php
function unserialize_session_data( $serialized_string ) {
   $variables = array(  );
   $a = preg_split( "/(\w+)\|/", $serialized_string, -1, PREG_SPLIT_NO_EMPTY | PREG_SPLIT_DELIM_CAPTURE );
   for( $i = 0; $i < count( $a ); $i = $i+2 ) {
       $variables[$a[$i]] = unserialize( $a[$i+1] );
   }
   return( $variables );
}
?>
yonman at gamer dot co dot il
30-May-2004 09:29
yabba at the dot hut:

The cookie mechanism for the webserver adds the slashes automatically. instead of just dumping strings into the cookie, make sure you base64_encode them first - to protect the cookie's content from escape characters.

Of course, this means that when retrieving the cookie, you'll need to base64_decode the string.
13-Mar-2004 10:42
If a a string is unserializeable FALSE is returned as well as an E_NOTICE error. This is odd since you may want to know if a given string converts back to a PHP value and act accordingly. If you run your script with E_ALL reporting this will show up.

I noticed this debugging this line of code:
$b = unserialize(base64_decode($a));

Curiously, base64_decode() does not throw errors if the string can't be decoded. The only workaround is to prepend the @ operator to unserialize() or to change the error level.
yabba at the dot hut
28-Jan-2004 01:09
caveat: stripslashes!!!

if using
       setcookie('hubba',serialize($data));
to set a cookie, you might want to check
       $data(unserialize(stripslashes($_COOKIE['hubba']));
to retrieve them back!!!

this is, if unserialize fails. you can also print_r($_COOKIE) to look into what you've got back.

beats me how the slashes got there in the first place....
Terry Johnson
09-Dec-2003 05:27
It is possible to make a neat autoloader for class definitions using this, but there are some gotchas for the unwary programmer:

1) If you are setting the unserialize_callback_func directive in the ini or .htaccess file, use auto_prepend_file to load the definition of your callback function - otherwise objects that stay in the session may trigger errors on pages where you didn't expect the object to be used.

2) It helps if you define all your classes in files with lowercase file names from the beginning.  The callback function is always call with the class name in lower case, and it is a lot quicker to use that directly than make a lookup table:

function callback_func($classname) {
   @include_once("${classname}.class.php");
}

3) It does not appear to be possible to use a static member fuction of a class (for example, a your object persistence layer) as the unserialize callback function, so this will cause confusion:

php_value auto_prepend_file "Persist.php"
php_value unserialize_callback_func Persist::factory

The next best solution is to make it a function in the global scope and have your object factory call it as required:

Class Persist
{
   function &factory($type) {
       callback_func(strtolower($type));
       $classname = "${type}";
       if (!class_exists($classname)) {
           return PEAR::raiseError('Class Not Found',PERSIST_ERROR_CLASS_NOT_FOUND,PEAR_ERROR_RETURN);
       }
       @$obj =& new $classname;
       return $obj;
   }
...
}
aderyn at nowhere dot tld
30-Oct-2003 10:02
A quick note:
If you store a serialized object in a session, you have to include the class _before_ you initialize (session_start()) the session.

<strvalunset>
 Last updated: Tue, 15 Nov 2005