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

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

<refnamediv>

<refname>fgetcsv</refname>

<refpurpose>Prende una riga da un puntatore a file e l'analizza in cerca di campi CSV</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type class="union"><type>array</type><type>false</type></type><methodname>fgetcsv</methodname>

<methodparam><type>resource</type><parameter>stream</parameter></methodparam>

<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>length</parameter><initializer>&null;</initializer></methodparam>

<methodparam choice="opt"><type>string</type><parameter>separator</parameter><initializer>","</initializer></methodparam>

<methodparam choice="opt"><type>string</type><parameter>enclosure</parameter><initializer>"\""</initializer></methodparam>

<methodparam choice="opt"><type>string</type><parameter>escape</parameter><initializer>"\\"</initializer></methodparam>

</methodsynopsis>

<para>

Simile a <function>fgets</function> eccetto per il fatto che

<function>fgetcsv</function> analizza le riga letta alla ricerca di campi

in formato <acronym>CSV</acronym> e restituisce un array contenente i campi

letti.

</para>

<note>

<simpara>

Le impostazioni locali vengono prese in considerazione da questa funzione.

Ad esempio, i dati codificati in determinati formati a byte singolo potrebbero essere analizzati

in modo errato se <constant>LC_CTYPE</constant> è impostato su

<literal>en_US.UTF-8</literal>.

</simpara>

</note>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>stream</parameter></term>

<listitem>

<para>

Un puntatore valido a un file che punta a un file aperto con successo da

<function>fopen</function>, <function>popen</function> o

<function>fsockopen</function>.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>length</parameter></term>

<listitem>

<para>

Deve essere più grande della riga più lunga (in caratteri) per essere trovato nel

file CSV (tenendo conto dei caratteri di fine riga). Altrimenti, la riga

viene suddivisa in blocchi di <parameter>length</parameter> caratteri,

a meno che la divisione non avvenga all'interno di una chiusura.

</para>

<para>

Se si omette questo parametro (o lo si imposta su 0,

o &null; in PHP 8.0.0 o versioni successive), la lunghezza massima della riga non è limitata,

ma è leggermente più lenta.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>separator</parameter></term>

<listitem>

<para>

Il parametro <parameter>separator</parameter> imposta il separatore di campo.

Deve essere un carattere a byte singolo.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>enclosure</parameter></term>

<listitem>

<para>

Il parametro <parameter>enclosure</parameter> imposta il carattere di chiusura del campo.

Deve essere un carattere a byte singolo.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>escape</parameter></term>

<listitem>

<para>

Il parametro <parameter>escape</parameter> imposta il carattere di escape.

Deve essere un carattere a byte singolo o la stringa vuota.

La stringa vuota (<literal>""</literal>) disabilita il meccanismo di escape proprietario.

</para>

<warning xml:id="function.fgetcsv..warn.escape.parameter">

<simpara>

Nel flusso di input, il carattere <parameter>enclosure</parameter>

può sempre essere sottoposto a escape raddoppiandolo all’interno di una stringa tra virgolette,

producendo un singolo carattere <parameter>enclosure</parameter>

nel risultato analizzato.

Il carattere <parameter>escape</parameter> funziona in modo diverso:

se una sequenza di caratteri <parameter>escape</parameter> e

<parameter>enclosure</parameter> appare nell’input,

entrambi i caratteri saranno presenti nel risultato analizzato.

Quindi, per i parametri predefiniti, una riga CVS come

<literal>"a""b","c\"d"</literal> avrà i campi analizzati come

<literal>a"b</literal> e <literal>c\"d</literal>, rispettivamente.

</simpara>

</warning>

<warning>

<simpara>

A partire da PHP 8.4.0, dipendere dal valore predefinito di

<parameter>escape</parameter> è deprecato.

Deve essere fornito esplicitamente, sia per posizione che mediante l'uso

dei <link linkend="functions.named-arguments">named arguments</link>.

</simpara>

</warning>

</listitem>

</varlistentry>

</variablelist>

</para>

&warning.csv.escape-parameter;

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Restituisce un array indicizzato contenente i campi letti in caso di successo, &return.falseforfailure;.

</para>

<note>

<para>

Una riga vuota in un file CSV verrà restituita come un array

contenente un singolo campo <type>null</type> e non sarà trattata

come un errore.

</para>

</note>

&note.line-endings;

</refsect1>

<refsect1 role="errors">

&reftitle.errors;

<simpara>

Genera un <exceptionname>ValueError</exceptionname> se

<parameter>separator</parameter> o <parameter>enclosure</parameter>

non sono lunghi un byte.

</simpara>

<simpara>

Genera un <exceptionname>ValueError</exceptionname> se

<parameter>escape</parameter> non è lungo un byte o è una stringa vuota.

</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>

L'affidamento sul valore predefinito di <parameter>escape</parameter> è ora

deprecato.

</entry>

</row>

<row>

<entry>8.3.0</entry>

<entry>

Viene restituita una stringa vuota invece di una stringa con un singolo

byte null per l'ultimo campo se contiene solo una chiusura

non terminata.

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

<parameter>length</parameter> è ora nullable.

</entry>

</row>

<row>

<entry>7.4.0</entry>

<entry>

Il parametro <parameter>escape</parameter> ora accetta anche una stringa

vuota per disabilitare il meccanismo di escape proprietario.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Legge e stampa il contenuto di un file CSV</title>

<programlisting role="php">

</programlisting>

</example>

</para>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<simplelist>

<member><function>fputcsv</function></member>

<member><function>str_getcsv</function></member>

<member><methodname>SplFileObject::fgetcsv</methodname></member>

<member><methodname>SplFileObject::fputcsv</methodname></member>

<member><methodname>SplFileObject::setCsvControl</methodname></member>

<member><methodname>SplFileObject::getCsvControl</methodname></member>

<member><function>explode</function></member>

<member><function>file</function></member>

<member><function>pack</function></member>

</simplelist>

</refsect1>

</refentry>