layout: default title: Bundled Writer helpers description: Bundled insertion helpers to format and validate records before insertion

Bundled insertion helpers

Column consistency validator

The League\Csv\ColumnConsistency class validates the inserted record column count consistency.

This class constructor accepts a single argument $column_count which sets the column count value and validates each record length against the given value. If the value differs, a CannotInsertRecord exception will be thrown.

If $column_count equals -1, the object will lazy set the column count value according to the next inserted record and therefore will also validate it. On the next insert, if the given value differs, a CannotInsertRecord exception is triggered. At any given time you can retrieve the column count value using the ColumnConsistency::getColumnCount method.

use League\Csv\Writer;
use League\Csv\ColumnConsistency;

$validator = new ColumnConsistency();
$writer = Writer::from('/path/to/your/csv/file.csv');
$writer->addValidator($validator, 'column_consistency');
$validator->getColumnCount(); //returns -1
$writer->insertOne(["foo", "bar", "baz"]);
$validator->getColumnCount(); //returns 3
$writer->insertOne(["foo", "bar"]); //will trigger a CannotInsertRecord exception

Charset formatter

League\Csv\CharsetConverter will help you encode your records depending on your settings.

Enum Formatter

The League\Csv\EnumFormatter class is an immutable formatter designed to convert PHP enums (UnitEnum), introduced in PHP8.1, into scalar or serializable values suitable for CSV export (or similar flat formats).

It can be used directly as a callable and supports multiple exclusive formatting strategies. Those strategies are exclusive and are chosen via named constructors.

Encoding a Single Enum

You can encode a single enum manually using the encode() method:

use League\Csv\EnumFormatter;

$value = EnumFormatter::useJson()->encode(Pure::Foo);
// returns "foo"

When using EnumFormatter::useJson(), internally the Pure Enum must implement the JsonSerializable interface, the formatter encode() method will return the call to the jsonSerialize() method. If an enum cannot be serialized using the selected strategy, a TypeError is thrown:

use League\Csv\EnumFormatter;

$formatter = EnumFormatter::usingValue();
$value = $formatter->encode(Pure::Foo);
// Enum `Pure` cannot be serialized for CSV.

In this case the Pure Enum is not a Backed enum so the value property does not exist and can not be called resulting in a TypeError being thrown.

Encoding Enum in Records

The class can be used as a callable to convert enum found in a array.

use League\Csv\EnumFormatter;

enum Status: int
{
    case Active = 1;
    case Inactive = 0;
}

$record = [
    'id' => 1,
    'status' => Status::Active,
];

$formatter = EnumFormatter::usingName();
$result = $formatter($record);
// ['id' => 1, 'status' => 'Active']

The class can also be used as a Formatter by the Writer as follows:

use League\Csv\Writer;
use League\Csv\EnumFormatter;

enum Pure implements JsonSerializable
{
    case Foo;
    case Bar;

    public function jsonSerialize(): string
    {
        return strtolower($this->name);
    }
}

$arr = ['city' => Pure::Foo, 'habitants' => 7_000_000];
$doc = Writer::fromString();
$doc->addFormatter(EnumFormatter::usingCallback(fn (UnitEnum $value) => 'forty-two'));
$doc->insertOne($arr);

$doc->toString();
// returns "forty-two,7000000 \n",

When using the usingCallback() named constructor the callback takes a single argument a UnitEnum and is expected to return a value suitable for CSV encoding or any encoding you want to use.