Analiza una string CSV en un array

# str_getcsv

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

str_getcsv — Analiza una string CSV en un array

### Descripción

function str_getcsv(
string `$string`,
string `$separator` = ",",
string `$enclosure` = "\"",
string `$escape` = "\\"
): array

Analiza una cadena de caracteres que representa campos en formato CSV y devuelve un array que contiene todos los campos leídos.

> Nota: Los parámetros de configuración local son tenidos en cuenta por esta función. Por ejemplo, los datos codificados en ciertos juegos de caracteres de un byte pueden ser analizados incorrectamente si `LC_CTYPE` es `en_US.UTF-8`.

### Parámetros

`string`

  La cadena a analizar.

`separator`

  El parámetro `separator` define el separador de campo. Debe tratarse de un carácter de un solo byte.

`enclosure`

  El parámetro `enclosure` define el carácter de encierro de los campos. Debe tratarse de un carácter de un solo byte.

`escape`

  El parámetro `escape` define el carácter de escape. Debe tratarse de un carácter de un solo byte o una cadena vacía. La cadena vacía (`""`) desactiva el mecanismo de escape propietario.

  Advertencia

  En el flujo de entrada, el carácter `enclosure` siempre puede ser escapado duplicándolo dentro de una cadena entrecomillada, lo que resulta en un único carácter `enclosure` en el resultado analizado. El carácter `escape` funciona de manera diferente: si una secuencia de caracteres `escape` y `enclosure` aparece en la entrada, ambos caracteres estarán presentes en el resultado analizado. Así, para los parámetros por defecto, una línea CSV como `"a""b","c\"d"` tendrá los campos analizados como `a"b` y `c\"d`, respectivamente.

  Advertencia

  A partir de PHP 8.4.0, el uso del valor por omisión de `escape` está deprecado. Debe ser proporcionado explícitamente ya sea por posición o mediante el uso de los argumentos nombrados.

Advertencia

Cuando `escape` se define con un valor diferente a una cadena vacía (`""`), puede resultar en un CSV que no sea compatible con » RFC 4180 o que no pueda sobrevivir a un ciclo de ida y vuelta a través de las funciones CSV de PHP. El valor predeterminado de `escape` es `"\\"`, por lo que se recomienda definirlo explícitamente como cadena vacía. El valor predeterminado cambiará en una futura versión de PHP, no antes de PHP 9.0.

### Valores devueltos

Devuelve un array que contiene los campos leídos.

### Errores/Excepciones

Genera una ValueError si `separator` o `enclosure` no tiene una longitud de un byte.

Genera una ValueError si `escape` no tiene una longitud de un byte o es una cadena vacía.

### Historial de cambios

Versión | Descripción
--- | ---
8.4.0 | Confiar en el valor por omisión de `escape` está ahora deprecado.
8.4.0 | Ahora lanza una ValueError si `separator`, `enclosure`, o `escape` es inválido. Esto imita el comportamiento de fgetcsv() y fputcsv().
8.3.0 | Una cadena vacía es devuelta en lugar de una cadena que contiene un solo byte nulo para el último campo si este contiene únicamente un delimitador no terminado.
7.4.0 | El argumento `escape` interpreta ahora una cadena vacía como señal para desactivar el mecanismo de escape propio. Anteriormente, una cadena vacía era tratada como el valor por defecto del argumento.

### Ejemplos

Ejemplo #1 Ejemplo con str_getcsv()

    <?php

    $string = 'PHP,Java,Python,Kotlin,Swift';
    $data = str_getcsv($string, escape: '\\');

    var_dump($data);
    ?>

El ejemplo anterior mostrará:

    array(5) {
      [0]=>
      string(3) "PHP"
      [1]=>
      string(4) "Java"
      [2]=>
      string(6) "Python"
      [3]=>
      string(6) "Kotlin"
      [4]=>
      string(5) "Swift"
    }

Ejemplo #2 Ejemplo de str_getcsv() con una cadena vacía

Precaución

Con una cadena vacía, esta función devuelve `[null]` en lugar de un array vacío.

    <?php

    $string = '';
    $data = str_getcsv($string, escape: '\\');

    var_dump($data);
    ?>

El ejemplo anterior mostrará:

    array(1) {
      [0]=>
      NULL
    }

### Ver también

- fputcsv() - Formatea una línea en CSV y la escribe en un fichero
- fgetcsv() - Obtiene una línea desde un puntero de archivo y la analiza para campos CSV
- SplFileObject::fgetcsv() - Recupera una línea del archivo y la analiza como datos CSV
- SplFileObject::fputcsv() - Escribe un array en forma de línea CSV
- SplFileObject::setCsvControl() - Define las opciones CSV
- SplFileObject::getCsvControl() - Recupera las opciones para CSV

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open