cvs: phpdoc /hu/functions session.xml

goba Sun Mar 17 10:49:25 2002 EDT Modified files: /phpdoc/hu/functions session.xml Log: Commit long awaited translation of session.xml (only 50% of it ready), next 50% is coming the next week.

Index: phpdoc/hu/functions/session.xml diff -u /dev/null phpdoc/hu/functions/session.xml:1.3 --- /dev/null Sun Mar 17 10:49:25 2002 +++ phpdoc/hu/functions/session.xml Sun Mar 17 10:49:25 2002 @@ -0,0 +1,1305 @@ +<?xml version="1.0" encoding="iso-8859-2"?> +<!-- EN-Revision: 1.83 Maintainer: goba Status: half translated --> + <reference id="ref.session"> + <title>Munkamenet kezelõ függvények</title> + <titleabbrev>Munkamenetek</titleabbrev> + + <partintro> + <para> + A PHP munkamenet kezelése lehetõvé teszi adatok megõrzését az + egymást követõ oldal lekérdezések között. Ez képessé tesz + még testreszabhatóbb oldalak készítésére. + </para> + <para> + Ha ismered a PHPLIB munkamenet kezelését, sok hasonlóságot + fogsz felfedezni a PHP munkamenet kezelõ függvényeit illetõen. + </para> + <para> + Minden webhelyedre látogató egy-egy egyedi azonosítót kap, + az úgynevezett munkamenet azonosítót (session azonosítót). + Ez vagy egy sütiben (cookie) tárolódik a látogató gépén, + vagy az URL-ben közlekedik oldalról oldalra. + </para> + <para> + A munkamenet támogatás lehetõvé teszi tetszõleges számú változó + megõrzését a PHP oldal lekérdezések között. Ha egy látogató + érkezik webhelyedre, háromféleképpen kezdõdhet el, vagy folytatódhat + a munkamenete. Mindhárom esetben a PHP egy munkamenet + azonosító érkezését várja. Ha nem érkezik, új munkamenetet + indít. + </para> + <para> + Ha a session.auto_start be van kapcsolva, a PHP automatikusan + megkezdni / folytatja a munkamenetet. Ha ez nincs bekapcsolva, + akkor közvetlenül a <function>session_start</function> + függvénnyel, vagy közvetve a <function>session_register</function> + függvénnyel tudod a munkamenetet folytatni / megkezdeni. + Ha egy érvényes azonosító érkezett, a korábban beállított + munkamenet környezet visszaállításra kerül. + </para> + <para> + Minden a munkamenethez rendelt változó szerializálódik a + PHP oldal futásának befejezõdésekor. A nem definiált, + de munkamenethez rendelt változók a késõbbi folytatásokban + nem jönnek újból létre. + </para> + <para> + A <link + linkend="ini.track-vars"><literal>track_vars</literal></link> és + <link + linkend="ini.register-globals"><literal>register_globals</literal></link> + ini beállítások befolyásolják a munkamenet változók tárolásának + és visszaállításának módját. + </para> + + <note> + <para> + A PHP 4.0.3 verziótól kezdve a <link + linkend="ini.track-vars"><literal>track_vars</literal></link> mindig + be van kapcsolva, kikapcsolására nincs mód. + </para> + </note> + <note> + <para> + A 4.1.0 verziótól kezdve a <varname>$_SESSION</varname> szuperglobális + változó rendelkezésre áll, csakúgy mint a <varname>$_POST</varname>, + <varname>$_GET</varname>, <varname>$_REQUEST</varname> és így tovább. + A <varname>$HTTP_SESSION_VARS</varname> változótól eltérõen a + <varname>$_SESSION</varname> mindig elérhetõ (szuperglobális). + Ezért a <literal>global</literal> kulcsszóval nem szabad egyûtt + használni a <varname>$_SESSION</varname> változót. + </para> + </note> + + <para> + Ha a <link + linkend="ini.track-vars"><literal>track_vars</literal></link> be + van kapcsolva, és a <link + linkend="ini.register-globals"><literal>register_globals</literal></link> + ki van kapcsolva, csak a <varname>$HTTP_SESSION_VARS</varname> + asszociatív tömb elemei a munkamenet változók. A visszaállított + munkamenet változók is csak a <varname>$HTTP_SESSION_VARS</varname> + tömbben lesznek megtalálhatóak. + <example> + <title> + Változó bejegyzése a munkamenetbe a <link + linkend="ini.track-vars"><literal>track_vars</literal></link> + bekapcsolt állapotában. + </title> + <programlisting role="php"> +<![CDATA[ +<?php +if (isset($HTTP_SESSION_VARS['szamlalo'])) { + $HTTP_SESSION_VARS['szamlalo']++; +} +else { + $HTTP_SESSION_VARS['szamlalo'] = 0; +} +?> +]]> + </programlisting> + </example> + </para> + <para> + A <varname>$_SESSION</varname> változó használata (vagy + a <varname>$HTTP_SESSION_VARS</varname> változó használata + PHP 4.0.6 vagy régebbi verzió esetén) javasolt biztonsági + és olvashatósági szempontok miatt. A + <varname>$_SESSION</varname> vagy + <varname>$HTTP_SESSION_VARS</varname> használatával nincs szükség + a session_register()/session_unregister()/session_is_registered() + függvényekre. A programozók éppen úgy dolgozhatnak a munkamenet + változókkal, mint a "normális" változókkal. + <example> + <title> + Változó bejegyzése a munkamenetbe a $_SESSION tömbbel. + </title> + <programlisting role="php"> +<![CDATA[ +<?php +// Használd a $HTTP_SESSION_VARS tömböt PHP 4.0.6 vagy régebbi verzióban +if (!isset($_SESSION['szamlalo'])) { + $_SESSION['szamlalo'] = 0; +} else { + $_SESSION['szamlalo']++; +} +?> +]]> + </programlisting> + </example> + <example> + <title> + Változó bejegyzés törlése a $_SESSION tömbbel. + </title> + <programlisting role="php"> +<![CDATA[ +<?php +// Használd a $HTTP_SESSION_VARS tömböt PHP 4.0.6 vagy régebbi verzióban +unset($_SESSION['szamlalo']); + +?> +]]> + </programlisting> + </example> + </para> + <para> + Ha a <link + linkend="ini.register-globals"><literal>register_globals</literal></link> + be van kapcsolva, akkor minden globális változó lehet munkamenet + változóként regisztrálva, és a munkamenet késõbbi folytatásaiban is + létre fognak jönni globális változókként a bejegyzett változók. + Mivel ebben az esetben a PHP-nek tudnia kell, hogy mely globális + változók bejegyzett munkamenet változók is egyben, a programozónak + a session_register() függvényt kell használnia. Emlékeztetõként a + <varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname> + tömbök használatakor nincs szükség a session_register() függvényre. + <caution> + <para> + Ha a + <varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname> + tömböt használod és kikapcsolod a <link + linkend="ini.register-globals"><literal>register_globals</literal></link> + beállítást, ne használd a <function>session_register</function>, + <function>session_is_registered</function> és + <function>session_unregister</function> függvényeket. + </para> + <para> + Ha bekapcsolod a <link + linkend="ini.register-globals"><literal>register_globals</literal></link> + beállítást, a <function>session_unregister</function> függvényt + kell használnod, mivel a munkamenet változók globális változókban + jelennek meg. A <link + linkend="ini.register-globals"><literal>register_globals</literal></link> + kikapcsolása javasolt mind biztonsági, mind teljesítmény szempontokból. + </para> + </caution> + <example> + <title> + Változó bejegyzése a <link + linkend="ini.register-globals"><literal>register_globals</literal></link> + bekapcsolt állapota mellett. + </title> + <programlisting role="php"> +<![CDATA[ +<?php +if (!session_is_registered('szamlalo')) { + session_register("szamlalo"); + $szamlalo = 0; +} +else { + $szamlalo++; +} +?> +]]> + </programlisting> + </example> + </para> + <para> + Ha mind a <link + linkend="ini.track-vars"><literal>track_vars</literal></link>, mind a + <link + linkend="ini.register-globals"><literal>register_globals</literal></link> + beállítások be vannak kapcsolva, a globális változók és a + <varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname> + tömbök elemei ugynazokra az értékekre fognak mutatni a már + bejegyzett változókat illetõen. + </para> + <para> + Ha a programozó a session_register() függvényt használja munkamenet + változók bejegyzésére, akkor ebben az esetben a + <varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname> + tömbökben nem fog megjelenni ez a változó a következõ munkamenet + folytatása elõtt (azaz a következõ PHP program futás elõtt). + </para> + <para> + Kétféleképpen "közlekedhet" a munkamenet azonosító: + <itemizedlist> + <listitem> + <simpara> + Süti formájában + </simpara> + </listitem> + <listitem> + <simpara> + URL / ûrlap paraméterben + </simpara> + </listitem> + </itemizedlist> + </para> + <para> + A munkamenetkezelõ modul mindkét formát támogatja. A sütik + optimálisak, de sajnos nem megbízhatóak (sokan nem fogadják + a sütiket), ezért nem lehet rájuk biztonsággal építeni. + A második módszer az azonosítót közvetlenül az URL-ekbe + és ûrlapokba helyezi. + </para> + <para> + A PHP képes ezutóbbi azonosító terjesztést átlátszóan végezni, ha az + <link linkend="install.configure.enable-trans-sid"> + <literal>--enable-trans-sid</literal></link> opcióval fodítottad. + Ha ezt az opciót bekapcsolod, a reltív URL-ekhez és ûrlapokhoz + automatikusan hozzáteszi a PHP a munkamenet azonosítót. Alternatív + módszerként használhatod a <literal>SID</literal> konstanst, ami + definiált, ha a kliens nem küldte vissza a megfelelõ sütit. A + <literal>SID</literal> vagy <literal>session_name=session_id</literal> + (munkamenet név, munkamenet azonosító) formátumú, vagy egy üres + karektersorozat. + </para> + <para> + A következõ példa egy változó bejegyzést, és egy következõ oldalra + mutató link készítését mutatja, + <example> + <title>Egy látogató által lehívott oldalak számlálása</title> + <programlisting role="php"> +<![CDATA[ +<?php +if (!session_is_registered('szamlalo')) { + session_register('szamlalo'); + $szamlalo = 1; +} +else { + $szamlalo++; +} +?> + +Üdv látogató, eddig <?php echo $szamlalo; ?> alkalommal +láttad ezt az oldalt.<p> + +<?php +# Az <?php echo SID?> szükséges, hogy a munkamenet azonosítót +# megõrizzük abban az esetben is, ha a látogató nem fogadja +# a sütit. (<?=SID?> használható, ha a rövid tagek engedélyezettek) +?> + +A továbblépéshez <A HREF="kovoldal.php?<?php echo SID?>">kattints ide</A>. +]]> + </programlisting> + </example> + </para> + <para> + A <literal>&lt;?=SID?&gt;</literal> nem szükséges, ha az + <link linkend="install.configure.enable-trans-sid"> + <literal>--enable-trans-sid</literal></link> opcióval + fordítottad a PHP-t. + </para> + <note> + <para> + A nem relatív hivatkozások feltételezetten külsõ oldalakra + mutatnak, ezért nem egészülnek ki automatikusan a SID-el. + Komoly biztonsági problémákat okozna, ha a SID-ek + elkerülnének egy másik kiszolgálóhoz. + </para> + </note> + <para> + A munkamenethez tartozó adatok állományokban tárolódnak. + Ha adatbázisban, vagy más tároló eszközön szeretnéd rögzíteni + a munkamenethez tartozó adatokat, a + <function>session_set_save_handler</function> függvényt + kell használnod a saját tároló függvényeid bejegyzéséhez. + </para> + <para> + A munkamenet kezelõ függvények számos beállítási lehetõséget + biztosítanak, amiket a php.ini állományban helyezhetsz el. + Egy rövid áttekintés következik. + <itemizedlist> + <listitem> + <simpara> + A <literal>session.save_handler</literal> beállítás adja + meg a használt tárolás kezelõt, ami a munkamenet adatok + elmentésére, és visszakeresésére szolgál. Az alapértéke + <literal>files</literal>. + </simpara> + </listitem> + <listitem> + <simpara> + A <literal>session.save_path</literal> beállítás az a paraméter, + amit a tárolás kezelõ megkap. Ha az alapértelmezett állomány + kezelõt használod, ez a munkamenetek tárolására használt + ideiglenes állományok könytárának elérési útja. Alapértelmezése + <literal>/tmp</literal>. Ha a <literal>session.save_path</literal> + mélysége több mint kettõ, az automatikus szemét takarítás + nem fog mûködni. + </simpara> + <warning> + <para> + Ha ezt az értéket egy mindenki által olvasható könyvtárra + állítod (mint az alapbeállítású <filename>/tmp</filename>), + akkor a kiszolgálón lévõ többi felhasználó el tudja kapni + a munkameneteidet a könyvtárban lévõ állományok neve és + tartalma alapján. + </para> + </warning> + </listitem> + <listitem> + <simpara> + A <literal>session.name</literal> a munkamenet neve, amit + a PHP a süti beállításakor, az URL / ûrlap paraméterek + felvételekor és a munkamenet folytatásakor használ. Csak + alfanumerikus karaktereket tartalmazhat. Alapértéke + <literal>PHPSESSID</literal>. + </simpara> + </listitem> + <listitem> + <simpara> + A <literal>session.auto_start</literal> beállítás adja meg, + hogy a PHP kezdjen-e / folytasson-e minden PHP oldal + futattásnál automatikusan munkamenetet. Alapértéke + <literal>0</literal> (kikapcsolt). + </simpara> + </listitem> + <listitem> + <simpara> + A <literal>session.cookie_lifetime</literal> a beállított + süti élettartalmát szabályozza másodpercekben megadva. + A nulla érték azt jelenti, hogy "amíg a böngészõt be + nem zárják". Alapértéke éppen <literal>0</literal>. + </simpara> + </listitem> + <listitem> + <simpara> + A <literal>session.serialize_handler</literal> a + szerializáláshoz használt kezelõ nevét adja meg. + Jelenleg egy beépített PHP formátum (<literal>php</literal> + néven) és egy WDDX formátum támogatott + (<literal>wddx</literal> néven). A WDDX formátumhoz + szükséges, hogy a WDDX támogatás a PHP-be legyen + fordítva. Lásd <link linkend="ref.wddx">WDDX</link>. + Alapértéke a beépített <literal>php</literal> kezelõ. + </simpara> + </listitem> + <listitem> + <simpara> + A <literal>session.gc_probability</literal> megadja, hogy + mekkora valószínûséggel indul el a gc (garbage collection - + szemétgyûjtés) az egyes PHP lekérdezésekkor. Az értéket + százalékban kell megadni. Alapértéke <literal>1</literal>. + </simpara> + </listitem> + <listitem> + <simpara> + A <literal>session.gc_maxlifetime</literal> megadja, hogy + hány másodperc elteltével tekinti a szemétgyûtjtõ szemétnek, + és eltakarítandónak a munkamenet adatokat. + </simpara> + </listitem> + <listitem> + <simpara> + A <literal>session.referer_check</literal> azt a + rész-karaktersorozatot tartalmazza, amit minden HTTP + Referer fejlécben keresni szeretnél a munkamenetek még + biztonságosabb azonosítása céljából. Ha a megadott + rész-karaktersorozatot nem találja meg a PHP a Refererben, + a küldött munkamenet azonosítót nem fogja elfogadni. + Alapértéke az üres karaktersorozat. + </simpara> + </listitem> + <listitem> + <simpara> + A <literal>session.entropy_file</literal> egy elérési utat + határoz meg ahhoz az "állományhoz", amit a PHP külsõ entrópia + forrásnak használ a munkamenet azonosító elõállításakor. + Ez lehet például <literal>/dev/random</literal> vagy + <literal>/dev/urandom</literal>. Ezek sok Unix rendszeren + elérhetõek. + </simpara> + </listitem> + <listitem> + <simpara> + A <literal>session.entropy_length</literal> az olvasott + byte-ok számát adja meg, amennyit a fent említett + állományból olvas a PHP. Alapértéke <literal>0</literal> + (kikapcsolt). + </simpara> + </listitem> + <listitem> + <simpara> + A <literal>session.use_cookies</literal> határozza meg, + hogy a PHP használ-e sütiket a munkamenet azonosító + tárolására a kliens oldalon. Alapértéke + <literal>1</literal> (engedélyezett). + </simpara> + </listitem> + <listitem> + <simpara> + A <literal>session.cookie_path</literal> azt az elérési + utat határozza meg, amit a munkamenet sütiben beállít + a PHP. Alapértéke <literal>/</literal>. + </simpara> + </listitem> + <listitem> + <simpara> + A <literal>session.cookie_domain</literal> azt a domain + értéket határozza meg, amit a PHP a munkamenet sütiben + beállít. Alapértéke semmi. + </simpara> + </listitem> + <listitem> + <simpara> + A <literal>session.cache_limiter</literal> azt a cache metódust + határozza meg, amit a munkamenet oldalakra alkalmazni kell. + Lehetséges értékei: none, nocache, private, private_no_expire és + public. Alapértéke <literal>nocache</literal>. + </simpara> + </listitem> + <listitem> + <simpara> + A <literal>session.cache_expire</literal> megadja, hogy hány + percig legyen aktuális a cache-ben egy munkamenetet használó + oldal. Ennek nincs hatása, ha nocache módot választasz. + Alapértéke <literal>180</literal>. + </simpara> + </listitem> + <listitem> + <simpara> + A <literal>session.use_trans_sid</literal> szabályozza, hogy + az átlátszó SID hozzáadás be van-e kapcsolva vagy nincs. + Ehhez szükséges, hogy a + <link linkend="install.configure.enable-trans-sid"> + <literal>--enable-trans-sid</literal></link> opcióval + fordítsd korábban a PHP-t. Alapértéke <literal>1</literal> + (engedélyezett). + </simpara> + </listitem> + <listitem> + <simpara> + Az <literal>url_rewriter.tags</literal> adja meg, hogy mely + HTML elemeket kell átírni, ha a munkamenet azonosítók + átlátszó elhelyezése be van kapcsolva. Alapértéke + <literal>a=href,area=href,frame=src,input=src,form=fakeentry</literal> + </simpara> + </listitem> + </itemizedlist> + <note> + <para> + A munkamenetek támogatása a PHP 4.0 verzióban jelent meg. + </para> + </note> + </para> + </partintro> + + <refentry id="function.session-start"> + <refnamediv> + <refname>session_start</refname> + <refpurpose>Munkamenet megkezdése / folytatása</refpurpose> + </refnamediv> + <refsect1> + <title>Leírás</title> + <methodsynopsis> + <type>bool</type><methodname>session_start</methodname> + <void/> + </methodsynopsis> + <simpara> + A <function>session_start</function> elkezd egy új munkamenetet, + vagy folytat egy korábbit, ha a PHP érvényes munkamenet azonosító + érkezését érzékelte GET/POST paraméterben vagy sütiben. + </simpara> + <simpara> + Ha az alapbeállítású névtõl eltérõ nevet szeretnél használni + a munkamenet számára, használd a <function>session_name</function> + függvényt a <function>session_start</function> meghívása + <emphasis>elõtt</emphasis>. + </simpara> + <simpara> + Ez a függvény mindig &true; értékkel tér vissza. + </simpara> + <note> + <para> + Ha süti alapú munkameneteket használsz, a + <function>session_start</function> hívásnak minden + kimenetet meg kell elõznie. + </para> + </note> + <simpara> + A <function>session_start</function> egy belsõ kimenet kezelõt + regisztrál az URL-ek és ûrlapok átírására, ha a + <literal>trans-sid</literal> funkció be van kapcsolva. + Ha az <literal>ob_gzhandler</literal>-t vagy más hasonló kimenet + kezelõket használsz az <function>ob_start</function> függvénnyel, + a kimenet kezelõk sorrendje fontos a megfelelõ kimenet érdekében. + Ezért az <literal>ob_gzhandler</literal>-t a munkamenet megkezdése + elõtt kell regisztrálni. + </simpara> + <note> + <simpara> + A <literal>zlib.output_compression</literal> használata javasolt + az <literal>ob_gzhandler</literal> helyett. + </simpara> + </note> + </refsect1> + </refentry> + + <refentry id="function.session-destroy"> + <refnamediv> + <refname>session_destroy</refname> + <refpurpose>Adott munkamenethez tartozó minden adat törlése</refpurpose> + </refnamediv> + <refsect1> + <title>Leírás</title> + <methodsynopsis> + <type>bool</type><methodname>session_destroy</methodname> + <void/> + </methodsynopsis> + <simpara> + A <function>session_destroy</function> az aktuális munkamenethez + tartozó minden adatot töröl. Nem törli azonban a globális + változókat, vagy a munkamenethez beállított sütit. + </simpara> + <simpara> + Ez a függvény &true; értékkel tér vissza siker esetén, + &false; értékkel tér vissza, ha nem tudja a munkamenet + adatait törölni. + </simpara> + <para> + <example> + <title>Munkamenet törlése</title> + <programlisting role="php"> +<![CDATA[ +<?php + +// Munkamenet megkezdése / folytatása. +// Ha használsz session_name("valami") hívást, ne feledd itt! +session_start(); +// Minden munkamenet változó törlése. +session_unset(); +// A munkamenet törlése. +session_destroy(); + +?> +]]> + </programlisting> + </example> + </para> + <para> + <example> + <title>Munkamenet törlése a $_SESSION tömbbel</title> + <programlisting role="php"> +<![CDATA[ +<?php + +// Munkamenet megkezdése / folytatása. +// Ha használsz session_name("valami") hívást, ne feledd itt! +session_start(); +// Minden munkamenet változó törlése. +$_SESSION = array(); +// A munkamenet törlése. +session_destroy(); + +?> +]]> + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.session-name"> + <refnamediv> + <refname>session_name</refname> + <refpurpose>Az aktuális munkamenet név lekérdezése / beállítása</refpurpose> + </refnamediv> + <refsect1> + <title>Leírás</title> + <methodsynopsis> + <type>string</type><methodname>session_name</methodname> + <methodparam choice="opt"><type>string</type><parameter>name</parameter></methodparam> + </methodsynopsis> + <para> + A <function>session_name</function> visszaadja az aktuális munkamenet + nevét. Ha a <parameter>name</parameter> paraméter meg van adva, az + aktuális munkamenet neve erre változik. + </para> + <para> + A munkamenet neve azonosítja a munkamenetet a sütikben, + URL-ekben és ûrlapokban. Csak alfanumerikus karaktereket + tartalmazhat, rövidnek és érthetõnek kell lennie (azon + látogatók számára, akik például bekapcsolt süti + figyelmeztetõk olvasása alapján döntik el a süti + engedélyezését). A munkamenet neve visszatér a php.ini + <literal>session.name</literal> beállítására a PHP + program futása kezdetén. Ezért mindig meg kell hívni + a <function>session_name</function> függvényt a kívánt + névvel a <function>session_start</function> és/vagy + <function>session_register</function> hívások elõtt, + ha nem az alapértelmezett munkamenet nevet szeretnéd + használni. + </para> + <example> + <title><function>session_name</function> példa</title> + <programlisting role="php"> +<![CDATA[ +<?php + +// a munkamenet nevét webhelyneve-re állíjtuk + +$elozo_nev = session_name("webhelyneve"); + +echo "A megelõzõ munkamenet név $elozo_nev volt.<p>"; +?> +]]> + </programlisting> + </example> + </refsect1> + </refentry> + + <refentry id="function.session-module-name"> + <refnamediv> + <refname>session_module_name</refname> + <refpurpose>Get and/or set the current session module</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>string</type><methodname>session_module_name</methodname> + <methodparam choice="opt"><type>string</type><parameter>module</parameter></methodparam> + </methodsynopsis> + <para> + <function>session_module_name</function> returns the name of the + current session module. If <parameter>module</parameter> is + specified, that module will be used instead. + </para> + </refsect1> + </refentry> + + <refentry id="function.session-save-path"> + <refnamediv> + <refname>session_save_path</refname> + <refpurpose>Get and/or set the current session save path</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>string</type><methodname>session_save_path</methodname> + <methodparam choice="opt"><type>string</type><parameter>path</parameter></methodparam> + </methodsynopsis> + <para> + <function>session_save_path</function> returns the path of the current + directory used to save session data. If <parameter>path</parameter> + is specified, the path to which data is saved will be changed. + <note> + <para> + On some operating systems, you may want to specify a path on a + filesystem that handles lots of small files efficiently. For + example, on Linux, reiserfs may provide better performance than + ext2fs. + </para> + </note> + </para> + </refsect1> + </refentry> + + <refentry id="function.session-id"> + <refnamediv> + <refname>session_id</refname> + <refpurpose>Get and/or set the current session id</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>string</type><methodname>session_id</methodname> + <methodparam choice="opt"><type>string</type><parameter>id</parameter></methodparam> + </methodsynopsis> + <para> + <function>session_id</function> returns the session id for the + current session. If <parameter>id</parameter> is specified, it + will replace the current session id. + </para> + <para> + The constant <systemitem>SID</systemitem> can also be used to + retrieve the current name and session id as a string suitable for + adding to URLs. + </para> + </refsect1> + </refentry> + + <refentry id="function.session-register"> + <refnamediv> + <refname>session_register</refname> + <refpurpose> + Register one or more variables with the current session + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>bool</type><methodname>session_register</methodname> + <methodparam><type>mixed</type><parameter>name</parameter></methodparam> + <methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam> + </methodsynopsis> + <para> + <function>session_register</function> accepts a variable number of + arguments, any of which can be either a string holding the name of a + variable or an array consisting of variable names or other arrays. For + each name, <function>session_register</function> registers the global + variable with that name in the current session. + </para> + <caution> + <para> + This registers a <emphasis>global</emphasis> variable. If you want to + register a session variable inside a function, you need to make sure to + make it global using <function>global</function> or use the session + arrays as noted below. + </para> + </caution> + <caution> + <para> + If you are using + <varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname>, + do not use <function>session_register</function>, + <function>session_is_registered</function> and + <function>session_unregister</function>. + </para> + </caution> + <para> + This function returns &true; when all of the variables are successfully + registered with the session. + </para> + <para> + If <function>session_start</function> was not called before this function + is called, an implicit call to <function>session_start</function> with no + parameters will be made. + </para> + <para> + You can also create a session variable by simply setting the + appropriate member of the <varname>$HTTP_SESSION_VARS</varname> + or <varname>$_SESSION</varname> (PHP >= 4.1.0) array. + <informalexample> + <programlisting role="php"> +<![CDATA[ +$barney = "A big purple dinosaur."; +session_register("barney"); + +$HTTP_SESSION_VARS["zim"] = "An invader from another planet."; + +# the auto-global $_SESSION array was introduced in PHP 4.1.0 +$_SESSION["spongebob"] = "He's got square pants."; +]]> + </programlisting> + </informalexample> + </para> + <note> + <para> + It is not currently possible to register resource variables in a + session. For example, you can not create a connection to a + database and store the connection id as a session variable and + expect the connection to still be valid the next time the + session is restored. PHP functions that return a resource are + identified by having a return type of + <literal>resource</literal> in their function definitions. A + list of functions that return resources are available in the + <link linkend="resource">resource types</link> appendix. + </para> + <para> + If <varname>$_SESSION</varname> (or + <varname>$HTTP_SESSION_VARS</varname> for PHP 4.0.6 or less) is + used, assign variable to + <varname>$_SESSION</varname>. i.e. $_SESSION['var'] = 'ABC'; + </para> + </note> + <para> + See also <function>session_is_registered</function> and + <function>session_unregister</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.session-unregister"> + <refnamediv> + <refname>session_unregister</refname> + <refpurpose> + Unregister a variable from the current session + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>bool</type><methodname>session_unregister</methodname> + <methodparam><type>string</type><parameter>name</parameter></methodparam> + </methodsynopsis> + <para> + <function>session_unregister</function> unregisters (forgets) + the global variable named <parameter>name</parameter> from the + current session. + </para> + <para> + This function returns &true; when the variable is successfully + unregistered from the session. + </para> + <note> + <para> + If <varname>$_SESSION</varname> (or + <varname>$HTTP_SESSION_VARS</varname> for PHP 4.0.6 or less) is + used, use <function>unset</function> to unregister a session + variable. + </para> + </note> + <caution> + <para> + This function doesn't unset the corresponding global variable for + <parameter>name</parameter>, it only prevents the variable from being + saved as part of the session. You must call <function>unset</function> + to remove the corresponding global variable. + </para> + </caution> + <caution> + <para> + If you are using + <varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname>, + do not use <function>session_register</function>, + <function>session_is_registered</function> and + <function>session_unregister</function>. + </para> + </caution> + </refsect1> + </refentry> + + <refentry id="function.session-unset"> + <refnamediv> + <refname>session_unset</refname> + <refpurpose> + Free all session variables + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>void</type><methodname>session_unset</methodname> + <void/> + </methodsynopsis> + <para> + The <function>session_unset</function> function free's all session variables + currently registered. + </para> + <note> + <para> + If <varname>$_SESSION</varname> (or + <varname>$HTTP_SESSION_VARS</varname> for PHP 4.0.6 or less) is + used, use <function>unset</function> to unregister session + variable. i.e. $_SESSION = array(); + </para> + </note> + </refsect1> + </refentry> + + <refentry id="function.session-is-registered"> + <refnamediv> + <refname>session_is_registered</refname> + <refpurpose> + Find out if a variable is registered in a session + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>bool</type><methodname>session_is_registered</methodname> + <methodparam><type>string</type><parameter>name</parameter></methodparam> + </methodsynopsis> + <para> + <function>session_is_registered</function> returns &true; if there + is a variable with the name <parameter>name</parameter> + registered in the current session. + </para> + <note> + <para> + If <varname>$_SESSION</varname> (or + <varname>$HTTP_SESSION_VARS</varname> for PHP 4.0.6 or less) is + used, use <function>isset</function> to check a variable is + registered in <varname>$_SESSION</varname>. + </para> + </note> + <caution> + <para> + If you are using + <varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname>, + do not use <function>session_register</function>, + <function>session_is_registered</function> and + <function>session_unregister</function>. + </para> + </caution> + </refsect1> + </refentry> + + <refentry id="function.session-get-cookie-params"> + <refnamediv> + <refname>session_get_cookie_params</refname> + <refpurpose> + Get the session cookie parameters + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>array</type><methodname>session_get_cookie_params</methodname> + <void/> + </methodsynopsis> + <para> + The <function>session_get_cookie_params</function> function returns an + array with the current session cookie information, the array contains + the following items: + <itemizedlist> + <listitem> + <simpara> + "lifetime" - The lifetime of the cookie. + </simpara> + </listitem> + <listitem> + <simpara> + "path" - The path where information is stored. + </simpara> + </listitem> + <listitem> + <simpara> + "domain" - The domain of the cookie. + </simpara> + </listitem> + <listitem> + <simpara> + "secure" - The cookie should only be sent over secure connections. + (This item was added in PHP 4.0.4.) + </simpara> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="function.session-set-cookie-params"> + <refnamediv> + <refname>session_set_cookie_params</refname> + <refpurpose> + Set the session cookie parameters + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>void</type><methodname>session_set_cookie_params</methodname> + <methodparam><type>int</type><parameter>lifetime</parameter></methodparam> + <methodparam choice="opt"><type>string</type><parameter>path</parameter></methodparam> + <methodparam choice="opt"><type>string</type><parameter>domain</parameter></methodparam> + </methodsynopsis> + <para> + Set cookie parameters defined in the php.ini file. The effect of this + function only lasts for the duration of the script. + </para> + </refsect1> + </refentry> + + <refentry id="function.session-decode"> + <refnamediv> + <refname>session_decode</refname> + <refpurpose>Decodes session data from a string</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>bool</type><methodname>session_decode</methodname> + <methodparam><type>string</type><parameter>data</parameter></methodparam> + </methodsynopsis> + <para> + <function>session_decode</function> decodes the session data in + <parameter>data</parameter>, setting variables stored in the + session. + </para> + </refsect1> + </refentry> + + <refentry id="function.session-encode"> + <refnamediv> + <refname>session_encode</refname> + <refpurpose> + Encodes the current session data as a string + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>string</type><methodname>session_encode</methodname> + <void/> + </methodsynopsis> + <para> + <function>session_encode</function> returns a string with the + contents of the current session encoded within. + </para> + </refsect1> + </refentry> + + <refentry id="function.session-set-save-handler"> + <refnamediv> + <refname>session_set_save_handler</refname> + <refpurpose> + Sets user-level session storage functions + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>void</type><methodname>session_set_save_handler</methodname> + <methodparam><type>string</type><parameter>open</parameter></methodparam><methodparam><type>string</type><parameter>close</parameter></methodparam><methodparam><type>string</type><parameter>read</parameter></methodparam><methodparam><type>string</type><parameter>write</parameter></methodparam><methodparam><type>string</type><parameter>destroy</parameter></methodparam><methodparam><type>string</type><parameter>gc</parameter></methodparam> + </methodsynopsis> + <para> + <function>session_set_save_handler</function> sets the user-level + session storage functions which are used for storing and + retrieving data associated with a session. This is most useful + when a storage method other than those supplied by PHP sessions + is preferred. i.e. Storing the session data in a local database. + </para> + <note> + <para> + You must set the configuration option + <parameter>session.save_handler</parameter> to + <parameter>user</parameter> in your php.ini file for + <function>session_set_save_handler</function> to take effect. + </para> + </note> + <note> + <para> + The "write" handler is not executed until after the output + stream is closed. Thus, output from debugging statements in the + "write" handler will never be seen in the browser. If debugging + output is necessary, it is suggested that the debug output be + written to a file instead. + </para> + </note> + <para> + The following example provides file based session + storage similar to the PHP sessions default save handler + <parameter>files</parameter>. This example could easily be + extended to cover database storage using your favorite PHP + supported database engine. + </para> + <para> + Read function must return string value always to make save + handler work as expected. Return empty string if there is no data + to read. Return values from other handlers are converted to + boolean expression. TRUE for success, FALSE for failure. + </para> + <para> + <example> + <title> + <function>session_set_save_handler</function> example + </title> + <programlisting role="php"> +<![CDATA[ +<?php +function open ($save_path, $session_name) { + global $sess_save_path, $sess_session_name; + + $sess_save_path = $save_path; + $sess_session_name = $session_name; + return(true); +} + +function close() { + return(true); +} + +function read ($id) { + global $sess_save_path, $sess_session_name; + + $sess_file = "$sess_save_path/sess_$id"; + if ($fp = @fopen($sess_file, "r")) { + $sess_data = fread($fp, filesize($sess_file)); + return($sess_data); + } else { + return(""); // Must return "" here. + } + +} + +function write ($id, $sess_data) { + global $sess_save_path, $sess_session_name; + + $sess_file = "$sess_save_path/sess_$id"; + if ($fp = @fopen($sess_file, "w")) { + return(fwrite($fp, $sess_data)); + } else { + return(false); + } + +} + +function destroy ($id) { + global $sess_save_path, $sess_session_name; + + $sess_file = "$sess_save_path/sess_$id"; + return(@unlink($sess_file)); +} + +/********************************************* + * WARNING - You will need to implement some * + * sort of garbage collection routine here. * + *********************************************/ +function gc ($maxlifetime) { + return true; +} + +session_set_save_handler ("open", "close", "read", "write", "destroy", "gc"); + +session_start(); + +// proceed to use sessions normally + +?> +]]> + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.session-cache-limiter"> + <refnamediv> + <refname>session_cache_limiter</refname> + <refpurpose>Get and/or set the current cache limiter</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>string</type><methodname>session_cache_limiter</methodname> + <methodparam choice="opt"><type>string</type><parameter>cache_limiter</parameter></methodparam> + </methodsynopsis> + <para> + <function>session_cache_limiter</function> returns the name of the + current cache limiter. If <parameter>cache_limiter</parameter> is + specified, the name of the current cache limiter is changed to the + new value. + </para> + <para> + The cache limiter controls the cache control HTTP headers sent to the + client. These headers determine the rules by which the page content + may be cached. Setting the cache limiter to <literal>nocache</literal>, + for example, would disallow any client-side caching. A value of + <literal>public</literal>, however, would permit caching. It can also + be set to <literal>private</literal>, which is slightly more restrictive + than <literal>public</literal>. + </para> + <para> + In <literal>private</literal> mode, Expire header sent to the + client, may cause confusion for some browser including Mozilla. + You can avoid this problem with + <literal>private_no_expire</literal> mode. Expire header is never + sent to the client in this mode. + </para> + <note> + <para> + <literal>private_no_expire</literal> was added in PHP 4.2.0dev. + </para> + </note> + <para> + The cache limiter is reset to the default value stored in + <literal>session.cache_limiter</literal> at request startup time. Thus, + you need to call <function>session_cache_limiter</function> for every + request (and before <function>session_start</function> is called). + </para> + <example> + <title><function>session_cache_limiter</function> examples</title> + <programlisting role="php"> +<![CDATA[ +<?php + +# set the cache limiter to 'private' + +session_cache_limiter('private'); +$cache_limiter = session_cache_limiter(); + +echo "The cache limiter is now set to $cache_limiter<p>"; +?> +]]> + </programlisting> + </example> + </refsect1> + </refentry> + + <refentry id='function.session-cache-expire'> + <refnamediv> + <refname>session_cache_expire</refname> + <refpurpose>Return current cache expire</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>int</type><methodname>session_cache_expire</methodname> + <methodparam choice="opt"><type>int</type><parameter>new_cache_expire</parameter></methodparam> + </methodsynopsis> + <para> + <function>session_cache_expire</function> returns current cache expire. + If <parameter>new_cache_expire</parameter> is given, the current + cache expire is replaced with <parameter>new_cache_expire</parameter>. + </para> + </refsect1> + </refentry> + + <refentry id="function.session-write-close"> + <refnamediv> + <refname>session_write_close</refname> + <refpurpose>Write session data and end session</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>void</type><methodname>session_write_close</methodname> + <void/> + </methodsynopsis> + <para> + End the current session and store session data. + </para> + <para> + Session data is usually stored after your script terminated + without the need to call <function>session_write_close</function>, but as + session data is locked to prevent concurrent writes only one + script may operate on a session at any time. When using framesets + together with sessions you will experience the frames loading one + by one due to this locking. You can reduce the time needed to + load all the frames by ending the session as soon as all changes + to session variables are done. + </para> +<!-- commented out until final decision on implementation + <para> + See also: <function>session_readonly</function>. + </para> +--> + </refsect1> + </refentry> + +<!-- commented out until final decision on implementation + <refentry id="function.session-readonly"> + <refnamediv> + <refname>session_readonly</refname> + <refpurpose>Begin session - reinitializes freezed variables, but no writeback on request end</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>void</type><methodname>session_readonly</methodname> + <void/> + </methodsynopsis> + <para> + Read in session data without locking the session data. Changing + session data is not possible, but frameset performance will be improved. + </para> + </refsect1> + </refentry> +--> + </reference> + +<!-- 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:"../../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 +--> +