<?xml version="1.0" encoding="iso-8859-1"?>
<!-- EN-Revision: 1.34 Maintainer: alan_dangelo  Status: ready -->
 <reference id="ref.http">
  <title>Funzioni HTTP</title>
  <titleabbrev>HTTP</titleabbrev>

  <partintro>
   <simpara>
    Queste funzioni permettono di modificare l'output inviato verso un browser
    attraverso manipolazioni a livello di protocollo HTTP.
   </simpara>
  </partintro>

  <refentry id="function.header">
   <refnamediv>
    <refname>header</refname>
    <refpurpose>Spedisce un header HTTP</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descrizione</title>
     <methodsynopsis>
      <type>int</type><methodname>header</methodname>
      <methodparam><type>string</type><parameter>string</parameter></methodparam>
      <methodparam choice="opt"><type>bool</type><parameter>replace</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>header</function> si utilizza per inviare header <acronym>HTTP</acronym>.
     Per maggiorni informazioni riguardanti gli header <acronym>HTTP</acronym>
     si veda la risorsa <ulink url="&spec.http1.1;">HTTP 1.1 specification</ulink>.

    </para>
    <para>
     L'argomento opzionale <parameter>replace</parameter> indica se l'header 
     inviato deve sostituirne uno simile spedito precedentemente, o accodarsi 
     al primo dello stesso tipo. Per default la funzione sostituisce
     l'header precedente, ma se viene passato &false; come secondo argomento
     vengono forzate intestazioni multiple. Per esempio:
     <informalexample>
      <programlisting role="php">
<![CDATA[
header('WWW-Authenticate: Negotiate');
header('WWW-Authenticate: NTLM',false);
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
     Ci sono due casi speciali di chiamate di header. Il primo  
     &quot;Location&quot;. Location non trasmette solo un header al 
     browser, ma anche un <literal>REDIRECT</literal> con 
     codice di stato (302).
     <informalexample>
      <programlisting role="php">
<![CDATA[
header("Location: http://www.php.net/"); /* Ridireziona il browser 
                                            al sito di PHP */
exit;                 /* Assicura che il codice sottostante 
                         non sia eseguito dopo il redirezionamento. */
]]>
      </programlisting>
     </informalexample>
    </para>
    <note>
     <para>
      HTTP/1.1 richiede un <acronym>URI</acronym> assoluto come argomento di 
      <ulink url="&spec.http1.1;-sec14.html#sec14.30">Location:</ulink>
      composto da schema, hostname, e path assoluto, ma alcuni clients 
      possono accettare anche URIs relativi. E' possibile usare 
      $HTTP_SERVER_VARS['HTTP_HOST'], $HTTP_SERVER_VARS['PHP_SELF'] 
      e <function>dirname</function> per creare URI assoluti da URI relativi 
      in modo automatico:
      <informalexample>
       <programlisting>
<![CDATA[
header ("Location: http://".$HTTP_SERVER_VARS['HTTP_HOST']
                       ."/".dirname($HTTP_SERVER_VARS['PHP_SELF'])
                       ."/".$relative_url);
]]>
       </programlisting>
      </informalexample>
     </para>
    </note>
    <para>
     Il secondo caso speciale  esemplificato dalle intestazioni che 
     iniziano con la stringa, &quot;<literal>HTTP/</literal>&quot; (le maiuscole non sono 
     discriminanti), che  usato per inviare codici di stato HTTP.
     Per esempio, se si  configurato Apache per usare script PHP per la 
     manipolazione di richieste fallite (usando la direttiva 
     <literal>ErrorDocument</literal>), potete desiderare di assicurarvi
     che il vostro script generi il codice adeguato. 
     <informalexample>
      <programlisting role="php">
<![CDATA[
header ("HTTP/1.0 404 Not Found");
]]>
      </programlisting>
     </informalexample>
     <note>
      <para>
       In PHP 3, questo funziona solo se PHP  compilato come modulo
       Apache. Potete ottenere lo stesso effetto usando l'header
       <literal>Status</literal>.
       <informalexample>
        <programlisting role="php">
<![CDATA[
header("Status: 404 Not Found");
]]>
        </programlisting>
       </informalexample>
      </para>
     </note>
    </para>
    <para>
     Spesso gli scrit PHP generano contenuti dinamici, se volete evitare che i 
     contenuti vengano mantenuti nella cache di browser o proxy, 
     potete forzare il loro comportamento con questa direttiva:

     <informalexample>
      <programlisting role="php">
<![CDATA[
header("Expires: Mon, 26 Jul 1997 05:00:00 GMT");    // Data passata
header("Last-Modified: " . gmdate("D, d M Y H:i:s") . " GMT"); 
                                                     // sempre modificato
header("Cache-Control: no-store, no-cache, must-revalidate");  // HTTP/1.1
header("Cache-Control: post-check=0, pre-check=0", false);
header("Pragma: no-cache");                          // HTTP/1.0
]]>
      </programlisting>
     </informalexample>
     <note>
      <para>
       E' possibile che alcune pagine rimangano in chache anche dopo 
       l'uso degli header descritti sopra. Ci sono delle opzioni che 
       l'utente pu settare dal browser, capaci di modificare i comportamenti 
       di default del caching. Per trasmettere efficacemente gli header 
       descritti, bisogna che sia inattiva ogni regolazione che pu forzare 
       comportamenti contrari.
      </para>
      <para>
       Inoltre, <function>session_cache_limiter</function> e
       e la configurazione <literal>session.cache_limiter</literal>
       possono essere usate per generare automaticamente i corretti
       header relativi al caching durante l'uso delle sessioni.
      </para>
     </note>
    </para>
    <para>
     Bisogna ricordare che la funzione<function>header</function> va 
     chiamata prima di qualsiasi output HTML o PHP (anche righe o spazi
     vuoti). E' un errore comune leggere files con funzioni 
     <function>include</function>, o <function>require</function> 
     (o altre funzioni capaci di accedere a files), che possano emettere 
     in output spazi o linee vuote prima di una chiamata della funzione 
     <function>header</function>. Lo stesso problema esiste nell'utilizzare
     file PHP/HTML.
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php require("user_logging.inc") ?>


<?php header ("Content-type: audio/x-pn-realaudio"); ?>
// Non funziona, notate le linee vuote sopra
]]>
      </programlisting>
     </informalexample>
     <note>
      <para>
       In PHP 4, potete usare il buffering dell'output per aggirare
       questo problema, evitando ogni output al browser trattenedolo
       al server fino a che non gli si impone l'invio. Si pu fare questa operazione
       chiamando <function>ob_start</function> e <function>ob_end_flush</function>
       nello script, o settando la direttiva di configurazione 
       <literal>output_buffering</literal> nel file <filename>php.ini</filename> o
       nel file di configurazione del server.
      </para>
     </note>
    </para>    
    <para>
     Se desiderate che l'utente sia spinto a salvare i dati trasmessi 
     per esempio utilizzando un file PDF, potete usare 
     l'header <ulink url="&url.rfc2183;">Content-Disposition</ulink>, che vi
     permette di dare un nome al file e forzare il browser a mostrare la finestra
     di dialogo save.
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
header("Content-type: application/pdf");
header("Content-Disposition: attachment; filename=downloaded.pdf");

/* ... manda in output un file pdf ... */
]]>
      </programlisting>
     </informalexample>
     <note>
      <para>
       Per un bug di Microsoft Internet Explorer 4.01 qusto sistema
       non funziona. Non ci sono soluzioni. C' un altro bug in Microsoft 
       Internet Explorer 5.5 che impedisce il giusto funzionamento,
       ma  possibile risolverlo con l'upgrade del Service Pack 2 o superiore.
      </para>
     </note>
    </para>
    <para>
     Vedi anche <function>headers_sent</function>,
     <function>setcookie</function>, e la sezione 
     <link linkend="features.http-auth">Autenticazione HTTP usando PHP</link>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.headers-sent">
   <refnamediv>
    <refname>headers_sent</refname>
    <refpurpose>Restituisce &true; se gli header sono stati trasmessi.</refpurpose>

   </refnamediv>
   <refsect1>
    <title>Descrizione</title>
     <methodsynopsis>
      <type>bool</type><methodname>headers_sent</methodname>
      <void/>
     </methodsynopsis>
    <para>
     Questa funzione restituisce &true; se gli header <acronym>HTTP</acronym> 
     sono stati spedite correttamente, &false; in caso contrario.
    </para>
    <para>
     Vedi anche <function>header</function>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.setcookie">
   <refnamediv>
    <refname>setcookie</refname>
    <refpurpose>Spedisce un cookie</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descrizione</title>
     <methodsynopsis>
      <type>int</type><methodname>setcookie</methodname>
      <methodparam><type>string</type><parameter>name</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>value</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>expire</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>path</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>domain</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>secure</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>setcookie</function> definisce un cookie da inviare insieme 
     alle altre informazioni di header. I cookie devono essere spediti
     <emphasis>prima</emphasis> di qualsiasi altra intestazione (questa  
     una restrizione dei cookies, non di PHP). E' necessario perci chiamare 
     la funzione <function>setcookie</function> <emphasis>prima</emphasis> di 
     qualsiasi tags, anche <literal>&lt;html></literal> o <literal>&lt;head></literal>.
    </para>
    <para>
     Tutti gli argomenti della funzione eccetto <parameter>name</parameter>
     sono opzionali. Se viene passato alla funzione solo l'argomento 
     <parameter>name</parameter>, il cookie registrato con quel nome 
     verr cancellato dal client su cui  archiviato. E' possibile 
     sostituire gli argomenti che non si intende specificare utitlizzando 
     una stringa vuota (<emphasis>&quot;&quot;</emphasis>). Gli argomenti 
     <parameter>expire</parameter> e <parameter>secure</parameter> che richiedono
     numeri interi, non possono essere omessi inserendo una stringa vuota, per 
     questo scopo si usa (<emphasis>0</emphasis>). L'argomento 
     <parameter>expire</parameter>  un normale intero Unix Timestamp ottenibile
     grazie alle funzioni <function>time</function> o <function>mktime</function>.
     <parameter>secure</parameter> sta ad indicare che il cookie dovrebbe essere
     trasmesso soltanto attraverso un collegamento sicuro di tipo HTTPS.
    </para>
    <para>
     Errori comuni:
     <itemizedlist>
      <listitem>
       <simpara>
        I cookie diventano disponibili soltanto dalla pagina successiva a quella
        che li ha generati, o dopo il ricaricamento di questa. 
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        I cookie devono essere cancellati specificando gli stessi parametri con cui sono stati creati.
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <simpara>
     In PHP 3, chiamate successive di <function>setcookie</function>
     nello stesso script sono eseguite in ordine inverso. Se state provando 
     a cancellare un cookie prima dell' inserimento di un altro cookie, 
     dovete creare il secondo prima della cancellazione del primo. In PHP 4, 
     chiamate successive di <function>setcookie</function> invece, sono eseguite secondo l'ordine di chiamata. 
    </simpara>
    <para>
     Alcuni esempi sul modo di spedire cookie:
     <example>
      <title><function>setcookie</function> esempi di spedizione/creazione</title>
      <programlisting role="php">
<![CDATA[
setcookie ("TestCookie", "Test Value");
setcookie ("TestCookie", $value,time()+3600);  /* aspira in 1 ora */
setcookie ("TestCookie", $value,time()+3600, "/~rasmus/", ".utoronto.ca", 1);
]]>
      </programlisting>
     </example>
    </para>
    <para>
     Gli esempi mostrano come cancellare i cookie introdotti nell'esempio precedente:
     <example>
      <title><function>setcookie</function> esempi di cancellazione</title>
      <programlisting role="php">
<![CDATA[
setcookie ("TestCookie");
// set the expiration date to one hour ago
setcookie ("TestCookie", "", time() - 3600);
setcookie ("TestCookie", "", time() - 3600, "/~rasmus/", ".utoronto.ca", 1);
]]>
      </programlisting>
     </example>
     Per cancellare un cookie dovete assicurarvi che la data di scadenza del 
     cookie sia gi trascorsa, in questo modo il cookie verr rimosso dal client.
    </para>
    <para>
     Si noti che i valori salvati nei cookies sono automaticamente codificati
     per la trasmissione via URL (urlencoded) quando il cookie viene inviato, 
     e che al momento del richiamo sono automaticamente decodificati e assegnati ad 
     una variabile che ha lo stesso nome del cookie. Per vedere il contenuto di 
     un cookie in uno script, si usa una di queste due sintassi: 
     <informalexample>
      <programlisting role="php">
<![CDATA[
echo $TestCookie;
echo $HTTP_COOKIE_VARS["TestCookie"];
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
     Potete registrare array in un cookie usando la notazione degli array 
     al posto del nome del cookie. Questo equivale alla spedizione di tanti 
     cookie quanti sono gli elementi dell'array, ma si ha un vantaggio: quando 
     il cookie  ricevuto, tutti i suoi valori sono ordinati in un singolo array 
     che ha per nome il nome del cookie:
     <informalexample>
      <programlisting role="php">
<![CDATA[
setcookie ("cookie[three]", "cookiethree");
setcookie ("cookie[two]", "cookietwo");
setcookie ("cookie[one]", "cookieone");
if (isset ($cookie)) {
    while (list ($name, $value) = each ($cookie)) {
        echo "$name == $value&lt;br>\n";
    }
}
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
     Per saperne di pi sui cookies, Netscape's cookie
     specification  la risorsa giusta <ulink
     url="&spec.cookies;">&spec.cookies;</ulink>.
    </para>
    <simpara>
     Microsoft Internet Explorer 4 con Service Pack 1 non 
     crea correttamente cookie che hanno il parametro 
     <parameter>path</parameter> specificato.
    </simpara>
    <simpara>
     Netscape Communicator 4.05 e Microsoft Internet Explorer 3.x 
     sembrano utilizzare in modo errato i cookie quando 
     <parameter>path</parameter> ed <parameter>expire</parameter> non sono specificati.
    </simpara>
   </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
-->