<?xml version="1.0" encoding="utf-8"?>

<!-- $Revision$ -->

<!-- EN-Revision: a9e47cecca7d5834de43b7641baf5d86828bb153 Maintainer: hirokawa Status: ready -->

<!-- Credits: mumumu -->

<refentry xml:id="function.unserialize" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>unserialize</refname>

<refpurpose>

保存用表現から PHP の値を生成する

</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type>mixed</type><methodname>unserialize</methodname>

<methodparam><type>string</type><parameter>data</parameter></methodparam>

<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>

</methodsynopsis>

<simpara>

<function>unserialize</function> は、シリアル化された変数を

PHP の値に戻す変換(アンシリアライズ)を行います。

</simpara>

<warning>

<para>

<literal>allowed_classes</literal> の <parameter>options</parameter> の値にかかわらず、

ユーザーからの入力をそのまま <function>unserialize</function> に渡してはいけません。

アンシリアライズの時には、オブジェクトのインスタンス生成やオートローディングなどで

コードが実行されることがあり、悪意のあるユーザーがこれを悪用するかもしれないからです。

シリアル化したデータをユーザーに渡す必要がある場合は、安全で標準的なデータ交換フォーマットである

JSON などを使うようにしましょう。

<function>json_decode</function> および <function>json_encode</function>

を利用します。

</para>

<para>

外部に保存されているシリアル化されたデータをアンシリアライズする必要がある場合は、

<function>hash_hmac</function> を使ったデータの検証を検討しましょう。

他者によるデータの改ざんがないことを確かめるためです。

</para>

</warning>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>data</parameter></term>

<listitem>

<para>

シリアル化された文字列。

</para>

<para>

もしアンシリアライズする変数がオブジェクトの場合、

オブジェクトが無事再作成された後、PHP は自動的にメンバ関数

<link linkend="object.unserialize">__unserialize()</link> または <link linkend="object.wakeup">__wakeup()</link>

(存在していれば) をコールしようとします。

</para>

<para>

<note>

<title>

<link linkend="ini.unserialize-callback-func">unserialize_callback_func</link> ディレクティブ

</title>

<para>

<link linkend="ini.unserialize-callback-func">unserialize_callback_func</link>

ディレクティブで指定したコールバックは、未定義のクラスをアンシリアライズしようとした場合にコールされます。

コールバックが指定されない場合は、<classname>__PHP_Incomplete_Class</classname>

がインスタンス化されます。

</para>

</note>

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>options</parameter></term>

<listitem>

<para>

<function>unserialize</function> に連想配列で渡すオプション。

</para>

<table>

<title>有効なオプション</title>

<tgroup cols="3">

<thead>

<row>

<entry>名前</entry>

<entry>型</entry>

<entry>説明</entry>

</row>

</thead>

<tbody>

<row>

<entry><literal>allowed_classes</literal></entry>

<entry><type class="union"><type>array</type><type>bool</type></type></entry>

<entry>

<simpara>

受け付けるクラス名の配列を指定します。あらゆるクラスを拒否する場合は

&false;、あらゆるクラスを受け付ける場合は &true; を指定します。

このオプションを指定しているときに、もし

<function>unserialize</function> が受け付け対象外のクラスのオブジェクトに遭遇すると、

そのオブジェクトを

<classname>__PHP_Incomplete_Class</classname> のインスタンスに変換します。

</simpara>

<simpara>

このオプションを省略すると、&true; を指定したのと同じ意味になります。

つまり、PHP はあらゆるクラスのオブジェクトをインスタンス化しようとします。

</simpara>

</entry>

</row>

<row>

<entry><literal>max_depth</literal></entry>

<entry><type>int</type></entry>

<entry>

<simpara>

アンシリアライズ処理の間に許される、

データ構造の再帰の深さの最大値を設定します。

これは、スタックオーバーフローを防ぐためのものです。

デフォルトの深さの最大値は <literal>4096</literal> であり、

<literal>0</literal> に設定すると、

この制限を無効にすることができます。

</simpara>

</entry>

</row>

</tbody>

</tgroup>

</table>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

変換された値が返されます。その値は、

<type>bool</type>, <type>int</type>, <type>float</type>,

<type>string</type>, <type>array</type>, <type>object</type>

のいずれかとなります。

</para>

<para>

渡された文字列が復元できなかった場合、&false; を返して

<constant>E_WARNING</constant> を発生します。

</para>

</refsect1>

<refsect1 role="errors">

&reftitle.errors;

<simpara>

オブジェクトは、

アンシリアライズを実行するハンドラで <classname>Throwable</classname> をスローしても構いません。

</simpara>

<simpara>

PHP 8.4.0 以降では、<parameter>options</parameter> の <literal>allowed_classes</literal> 要素が

クラス名の <type>array</type> でない場合、

<function>unserialize</function> は <exceptionname>TypeError</exceptionname> と

<exceptionname>ValueError</exceptionname> をスローします。

</simpara>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<para>

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>8.4.0</entry>

<entry>

<parameter>options</parameter> の <literal>allowed_classes</literal> 要素が

クラス名の <type>array</type> でない場合、

<exceptionname>TypeError</exceptionname> と <exceptionname>ValueError</exceptionname> を

スローするようになりました。

</entry>

</row>

<row>

<entry>8.3.0</entry>

<entry>

入力された文字列の末尾に余計なデータがある場合、<constant>E_WARNING</constant> が発生するようになりました。

</entry>

</row>

<row>

<entry>8.3.0</entry>

<entry>

渡された文字列が復元できない場合、

<constant>E_WARNING</constant> が発生するようになりました。

これより前のバージョンでは、<constant>E_NOTICE</constant>

が発生していました。

</entry>

</row>

<row>

<entry>7.4.0</entry>

<entry>

<parameter>options</parameter> に <literal>max_depth</literal> が追加されました。

これは、アンシリアライズ処理の間に許される、

データ構造の再帰の深さの最大値を設定するものです。

</entry>

</row>

<row>

<entry>7.1.0</entry>

<entry>

<parameter>options</parameter> の <literal>allowed_classes</literal> 要素は、

型を厳密に調べるようになりました。

つまり、<type>array</type> または <type>bool</type> 以外の型が与えられると、

<function>unserialize</function> 関数は &false; を返し、

<constant>E_WARNING</constant> レベルの警告を発生させます。

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title><function>unserialize</function> の例</title>

<programlisting role="php" annotations="non-interactive">

<![CDATA[

<?php

// ここで、データベースから $session_data にセッションデータをロード

// するために unserialize() を使用します。

// この例は、serialize() で記述された例を補足するものです。

$conn = odbc_connect("webdb", "php", "chicken");

$stmt = odbc_prepare($conn, "SELECT data FROM sessions WHERE id = ?");

$sqldata = array($_SERVER['PHP_AUTH_USER']);

if (!odbc_execute($stmt, $sqldata) || !odbc_fetch_into($stmt, $tmp)) {

// 実行または取得が失敗した場合、空の配列で初期化します

$session_data = array();

} else {

// tmp[0] にシリアル化されたデータを保持している必要があります。

$session_data = unserialize($tmp[0]);

if (!is_array($session_data)) {

// 何か問題があったため、空の配列で初期化します。

$session_data = array();

}

}

?>

]]>

</programlisting>

</example>

</para>

<para>

<example>

<title>unserialize_callback_func の例</title>

<programlisting role="php">

<![CDATA[

<?php

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

ini_set('unserialize_callback_func', 'mycallback'); // 独自のコールバック関数を設定する

function mycallback($classname)

{

// クラスが定義されているファイルをインクルードするだけです。

// どのクラス定義が必要になるのかを $classname で判断します。

var_dump($classname);

}

unserialize($serialized_object);

?>

]]>

</programlisting>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<warning>

<para>

エラーやシリアライズされた &false; 値をアンシリアライズする場合、

&false; が返されます。この特殊なケースは

<parameter>data</parameter> を <literal>serialize(false)</literal>

で比較する、もしくは <constant>E_WARNING</constant>

をキャッチすることで区別することができます。

</para>

</warning>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>json_encode</function></member>

<member><function>json_decode</function></member>

<member><function>hash_hmac</function></member>

<member><function>serialize</function></member>

<member><link linkend="language.oop5.autoload">クラスのオートローディング</link></member>

<member><link linkend="ini.unserialize-callback-func">unserialize_callback_func</link></member>

<member><link linkend="ini.unserialize-max-depth">unserialize_max_depth</link></member>

<member><link linkend="object.wakeup">__wakeup()</link></member>

<member><link linkend="object.serialize">__serialize()</link></member>

<member><link linkend="object.unserialize">__unserialize()</link></member>

</simplelist>

</para>

</refsect1>

</refentry>

<!-- Keep this comment at the end of the file

Local variables:

mode: sgml

sgml-omittag:t

sgml-shorttag:t

sgml-minimize-attributes:nil

sgml-always-quote-attributes:t

sgml-indent-step:1

sgml-indent-data:t

indent-tabs-mode:nil

sgml-parent-document:nil

sgml-default-dtd-file:"~/.phpdoc/manual.ced"

sgml-exposed-tags:nil

sgml-local-catalogs:nil

sgml-local-ecat-files:nil

End:

vim600: syn=xml fen fdm=syntax fdl=2 si

vim: et tw=78 syn=sgml

vi: ts=1 sw=1

-->