(PHP 5 >= 5.3.0, PHP 7, PHP 8)
str_getcsv — Analisa uma string CSV e retorna os dados em um array
$string
,$separator
= ",",$enclosure
= "\"",$escape
= "\\"Interpreta uma string de entrada procurando por campos no formato CSV e retorna um array contendo os campos encontrados.
Nota: As configurações de localidade são consideradas por esta função. Por exemplo, dados em certas codificações de um byte podem ser interpretados incorretamente se
LC_CTYPE
foren_US.UTF-8
.
string
A string a ser analisada.
separator
O parâmetro separator
define o delimitador de campo.
Precisa ser um caractere de um byte.
enclosure
O parâmetro enclosure
define o caractere que cerca um campo.
Precisa ser um caractere de um byte.
escape
O parâmetro escape
define o caractere de escape.
Precisa ser um caractere de um byte ou uma string vazia.
Uma string vazia (""
) desabilita o mecanismo de escape proprietário.
Nota: Normalmente um caractere de
enclosure
sofre escape dentro de um campo através da duplicação; entretanto, o caractereescape
pode ser usado como uma alternativa. Portanto, para os parâmetros padrões os valores""
e\"
têm o mesmo significado. Além de permitir fazer escape no caractereenclosure
, o caractereescape
não tem nenhum significado especial adicional; muito menos foi projetado para fazer escape de si mesmo.
A partir do PHP 8.4.0, depender do valor padrão de
escape
foi descontinuado.
Ele precisa ser fornecido explicitamente tanto por posição quanto pelo uso
de argumentos nomeados.
Quando o parâmetro escape
for definido para algo diferente de uma string vazia
(""
), isso pode resultar em um CSV que não esteja conforme a
» RFC 4180 ou que não seja capaz de sobreviver a uma viagem de ida e volta
através das funções CSV do PHP. O padrão para escape
é
"\\"
, portanto é recomendado defini-lo explicitamente para a string vazia.
O valor padrão será alterado em uma versão futura do PHP, mas não antes do PHP 9.0.
Retorna um array indexado contendo os campos lidos.
Lança uma ValueError se
separator
ou enclosure
não tiver comprimento de um byte.
Lança uma ValueError se
escape
não tiver comprimento de um byte ou se for uma string vazia.
Versão | Descrição |
---|---|
8.4.0 |
Depender do valor padrão de escape agora está
descontinuado.
|
8.4.0 |
Agora lança um ValueError se
separator , enclosure ,
ou escape for inválido.
Isto imita o comportamento de fgetcsv() e de
fputcsv().
|
8.3.0 | Uma string vazia é retornada ao invés de uma string com um único byte nulo para o último campo, se ele contiver apenas um demarcador não terminado. |
7.4.0 |
O parâmetro escape agora interpreta uma string
vazia como o sinal para desabilitar o mecanismo de escape. Antes,
uma string vazia era tratada como valor padrão do parâmetro.
|
Exemplo #1 Exemplo de str_getcsv()
<?php
$string = 'PHP,Java,Python,Kotlin,Swift';
$data = str_getcsv($string, escape: '\\');
var_dump($data);
?>
O exemplo acima produzirá:
array(5) { [0]=> string(3) "PHP" [1]=> string(4) "Java" [2]=> string(6) "Python" [3]=> string(6) "Kotlin" [4]=> string(5) "Swift" }
Exemplo #2 Exemplo de str_getcsv()com uma string vazia
Com uma string vazia esta função retorna o valor [null]
em vez de um array vazio.
<?php
$string = '';
$data = str_getcsv($string, escape: '\\');
var_dump($data);
?>
O exemplo acima produzirá:
array(1) { [0]=> NULL }