Filesystem updated reference/filesystem/functions/file.xml

reference/filesystem/functions/file.xml

@@ -1,76 +1,207 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- EN-Revision: n/a Maintainer: fernando Status: working -->
- <!-- CREDITS: cortesi -->
- <refentry xml:id="function.file" xmlns="http://docbook.org/ns/docbook">
- <refnamediv>
- <refname>file</refname> 
- <refpurpose>Legge l'intero file in un vettore</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Descrizione</title>
- <methodsynopsis>
- <type>array</type><methodname>file</methodname>
- <methodparam><type>string</type><parameter>filename</parameter></methodparam>
- <methodparam choice="opt"><type>int</type><parameter>use_include_path</parameter></methodparam>
- <methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
- </methodsynopsis>
- <para> 
- Identica a <function>readfile</function>, eccetto per il fatto che
- <function>file</function> restituisce il file in un vettore. Ogni
- elemento del vettore corrisponde ad una riga del file, con il carattere di
- newline ancora inserito. Se la funzione non riesce restituisce 
- &false;.
- </para>
- <para>
- Puoi impostare il secondo parametro, <parameter>use_include_path</parameter>, (opzionale) ad "1",
- se vuoi cercare il file nel <link
- linkend="ini.include-path">include_path</link>.
- </para>
- <para>
- <informalexample>
- <programlisting role="php">
+<?xml version="1.0" encoding="utf-8"?>
+<!-- EN-Revision: e3ae86b439c1963f0cd6d262712e2d3f7e85bc37 Maintainer: ManueldG Status: ready -->
+<!-- Reviewed: no -->
+<!-- CREDITS: cortesi -->
+<!-- CREDITS: fernando -->
+<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.file">
+ <refnamediv>
+ <refname>file</refname>
+ <refpurpose>Legge l'intero file in un array</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+ &reftitle.description;
+ <methodsynopsis>
+ <type class="union"><type>array</type><type>false</type></type><methodname>file</methodname>
+ <methodparam><type>string</type><parameter>filename</parameter></methodparam>
+ <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
+ <methodparam choice="opt"><type class="union"><type>resource</type><type>null</type></type><parameter>context</parameter><initializer>&null;</initializer></methodparam>
+ </methodsynopsis>
+ <para>
+ Legge l'intero file in un array.
+ </para>
+ <note>
+ <para>
+ In alternativa è possibile usare <function>file_get_contents</function> per estrarre il contenuto
+ di un file sotto forma di stringa.
+ </para>
+ </note>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>filename</parameter></term>
+ <listitem>
+ <para>
+ Percorso del file.
+ </para>
+ &tip.fopen-wrapper;
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>flags</parameter></term>
+ <listitem>
+ <para>
+ Il parametro opzionale <parameter>flags</parameter> può essere uno, o
+ più valori, delle seguenti costanti: 
+ <variablelist>
+ <varlistentry>
+ <term>
+ <constant>FILE_USE_INCLUDE_PATH</constant>
+ </term>
+ <listitem>
+ <simpara>
+ Cerca il file in <link 
+ linkend="ini.include-path">include_path</link>.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <constant>FILE_IGNORE_NEW_LINES</constant>
+ </term>
+ <listitem>
+ <simpara>
+ Ometterà newline alla fine di ogni elemento dell'array
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <constant>FILE_SKIP_EMPTY_LINES</constant>
+ </term>
+ <listitem>
+ <simpara>
+ Salta le righe vuote
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <constant>FILE_NO_DEFAULT_CONTEXT</constant>
+ </term>
+ <listitem>
+ <simpara>
+ Non usa il context di default
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>context</parameter></term>
+ <listitem>
+ &note.context-support;
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ Restituisce il file in un array. Ogni elemento dell'array corrisponde a una
+ riga nel file, con newline incluso. In caso di errore,
+ <function>file</function> restituisce &false;.
+ </para>
+ <note>
+ <para>
+ Per ogni linea riportata nell'array risultante includerà newline, a meno
+ che non venga usato <constant>FILE_IGNORE_NEW_LINES</constant>.
+ </para>
+ </note>
+ &note.line-endings;
+ </refsect1>
+
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <simpara>
+ A partire da PHP 8.3.0, genera un <exceptionname>ValueError</exceptionname>
+ se <parameter>flags</parameter> include valori non validi, come
+ <constant>FILE_APPEND</constant>.
+ </simpara>
+ <para>
+ Emette un <constant>E_WARNING</constant> a livello d'errore
+ se il file non esiste.
+ </para>
+ </refsect1>
+
+ <refsect1 role="changelog">
+ &reftitle.changelog;
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>&Version;</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>8.3.0</entry>
+ <entry>
+ <exceptionname>ValueError</exceptionname> viene generato
+ per qualunque valore di <parameter>flags</parameter> non valido.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title>Esempio di <function>file</function></title>
+ <programlisting role="php">
 <![CDATA[
 <?php
-// inserisce una pagina web in un array e la stampa. In questo esempio useremo il protocollo
-// HTTP per ottenere il sorgente di un URL
+// inserisce un file in un array e lo stampa. In questo esempio useremo il protocollo
+// HTTP per ottenere il sorgente HTML di un URL
 $lines = file('http://www.example.com/');
-// Ciclo attraverso l'array, si visualizzerà il sorgente come html ed i numeri di linea
-foreach($lines as $line_num => $line) {
+//Itera attraverso quest'array, mostra il sorgente HTML così com'è e anche i numeri di riga.
+
+foreach ($lines as $line_num => $line) {
  echo "Line #<b>{$line_num}</b> : " . htmlspecialchars($line) . "<br />\n";
 }
 
-// Un'altro esempio, inserisce la pagina web in una stringa. Vedere anche file_get_contents().
-$html = implode('', file ('http://www.example.com/'));
+//Utilizzo del parametro flag opzionale 
+$trimmed = file('somefile.txt', FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
 ?>
 ]]>
- </programlisting>
- </informalexample>
- </para>
-&tip.fopen-wrapper;
- <note>
- <para>
- Ciascuna riga dell'array restituito conterrà il carattere di fine riga, occorre, pertanto,
- utilizzare <function>rtrim</function> se si desidera rimuovere il carattere
- di fine riga.
- </para>
- </note>
- &note.line-endings;
- <note>
- <para>
- A partire da PHP 4.3.0 si può utilizzare <function>file_get_contents</function> per 
- memorizzare il contenuto di un file in una stringa in formato binario.
- </para>
- </note>
- &note.context-support;
- &warn.ssl-non-standard;
- <para> 
- Vedere anche <function>readfile</function>,
- <function>fopen</function>, <function>fsockopen</function>,
- <function>popen</function>, <function>file_get_contents</function> e
- <function>include</function>.
- </para>
- </refsect1>
- </refentry>
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+
+ <refsect1 role="notes">
+ &reftitle.notes;
+ &warn.ssl-non-standard;
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <para>
+ <simplelist>
+ <member><function>file_get_contents</function></member>
+ <member><function>readfile</function></member>
+ <member><function>fopen</function></member>
+ <member><function>fsockopen</function></member>
+ <member><function>popen</function></member>
+ <member><function>include</function></member>
+ <member><function>stream_context_create</function></member>
+ </simplelist>
+ </para>
+ </refsect1>
+
+</refentry>
 
 <!-- Keep this comment at the end of the file
 Local variables: