CSV 文字列をパースして配列に格納する

# str_getcsv

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

str_getcsv — CSV 文字列をパースして配列に格納する

### 説明

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

CSV 形式の文字列入力のフィールドをパースして、 読み込んだフィールドの内容を配列で返します。

> 注意: この関数はロケール設定を考慮します。 例えば、`LC_CTYPE` が `en_US.UTF-8` の場合、 1 バイトエンコーディングでエンコードされたデータが 間違って処理されるかもしれません。

### パラメータ

`string`

  パースする文字列。

`separator`

  `separator` パラメータで、フィールドのデリミタを設定します。 シングルバイト文字 1 文字のみでなければなりません。

`enclosure`

  オプションの `enclosure` パラメータで、フィールド囲いこみ文字を設定します。 シングルバイト文字 1 文字のみでなければなりません。

`escape`

  オプションの `escape` パラメータで、エスケープ文字を設定します。 シングルバイト文字 1 文字のみ、または空文字列でなければなりません。 空文字列(`""`) を指定すると、(RFC 4180 に準拠していない) 独自仕様のエスケープ機構が無効になります。

  警告

  入力ストリームにおいて、`enclosure` 文字は クォートされた文字列の中で2回連続させることで常にエスケープでき、 パース結果では単一の `enclosure` 文字になります。 `escape` 文字の動作は異なります: 入力中に `escape` と `enclosure` 文字の並びが出現した場合、 パース結果には両方の文字がそのまま残ります。 よって、デフォルトのパラメータの場合、 `"a""b","c\"d"` のような CSV の行は それぞれ `a"b` と `c\"d` にパースされます。

  警告

  PHP 8.4.0 以降では、`escape` のデフォルト値に依存することは非推奨となりました。 位置指定の引数か、名前付き引数 を使用して明示的に指定する必要があります。

警告

`escape` が空の文字列(`""`)以外に設定されているとき、 » RFC 4180 に準拠しない CSV が生成されたり、PHP の CSV 関数を介してラウンドトリップ(往復変換)でデータが壊れる可能性があります。 `escape`のデフォルト値は`"\\"` なので、明示的に空の文字列を指定することを推奨します。デフォルト値は、PHP 9.0 以降の将来のバージョンで変更予定です。

### 戻り値

読み込んだフィールドの内容を配列で返します。

### エラー / 例外

`separator` または `enclosure` が 1 バイト長ではない場合、ValueError をスローします。

`escape` が 1 バイト長、または空文字列ではない場合、 ValueError をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `escape` のデフォルト値に依存することは、 非推奨になりました。
8.4.0 | `separator`、`enclosure`、 または `escape` が不正な場合、 ValueError をスローするようになりました。 これは、fgetcsv() と fputcsv() の動作に倣ったものとなります。
8.3.0 | 最後のフィールドが、 閉じられていないフィールド囲いこみ文字だけの場合、 null バイト 1 つの文字列ではなく、空文字列を返すようになりました。
7.4.0 | `escape` 引数は、 空文字列を、(RFC 4180 に準拠していない) 独自仕様のエスケープ機構を無効にするシグナルとして解釈するようになりました。 これより前のバージョンでは、空文字列はデフォルト値のように扱われていました。

### 例

例1 str_getcsv() の例

    <?php

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

    var_dump($data);
    ?>

上の例の出力は以下となります。

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

例2 str_getcsv() に空文字列を指定した例

警告

この関数に空文字列を指定すると、 空の配列ではなく 値 `[null]` を返します。

    <?php

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

    var_dump($data);
    ?>

上の例の出力は以下となります。

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

### 参考

- fputcsv() - 行を CSV 形式にフォーマットし、ファイルポインタに書き込む
- fgetcsv() - ファイルポインタから行を取得し、CSVフィールドを処理する
- SplFileObject::fgetcsv() - ファイルから行を取り出し CSV フィールドとして処理する
- SplFileObject::fputcsv() - フィールドの配列を CSV の行として書き出す
- SplFileObject::setCsvControl() - CSV の区切り文字、囲み文字、エスケープ文字をセットする
- SplFileObject::getCsvControl() - CSV の区切り、囲み文字、エスケープ文字を取得する

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