Prevents CSV Formula Injection

Available since version 9.1.0

The EscapeFormula Formatter formats CSV records to reduce CSV Formula Injection in imported Spreadsheet programs.

Since version 9.7.4 the default values from the class constructor were updated to comply with the latest recommendations from OWASP regarding CSV injection. As this is a security fix, the BC break should be minimal.

Usage with Writer objects

The EscapeFormula class uses the formatter capabilities of the Writer object to escape formula injection.

public function __construct(string $escape = "'", array $special_chars = [])
public function __invoke(array $record): array

The EscapeFormula::__construct method takes two (2) arguments:

• the $escape parameter which will be used to prepend the record field, which defaults to ';
• the $special_chars parameter which is an array with additional characters that need to be escaped. By default, the following characters at the start of any record field content will be escaped +,-,=,@, \t, \r;
• for more information see OWASP - CSV Injection

use League\Csv\EscapeFormula;
use League\Csv\Writer;

$writer = Writer::createFromPath('php://temp', 'r+');
$writer->addFormatter(new EscapeFormula());
$writer->insertOne(['2', '2017-07-25', 'Important Client', '=2+5', 240, null]);
$writer->getContent();
//outputting a CSV Document with all CSV Formula Injection escaped
//"2,2017-07-25,\"Important Client\",\"\t=2+5\",240,\n"

Usage with PHP stream resources

You can use the EscapeFormula to format your records before calling fputcsv or SplFileObject::fputcsv.

use League\Csv\EscapeFormula;

$resource = fopen('/path/to/my/file', 'r+');
$formatter = new EscapeFormula("`");
foreach ($iterable_data as $record) {
    fputcsv($resource, $formatter->escapeRecord($record));
}

Even though the EscapeFormula formatter is provided it must be stressed that this is in no way a bulletproof method. This prevention mechanism only works if you know how the CSV export will be consumed. In any other cases, you are better off leaving the filtering to the consuming client and report any found security concerns to their respective security channel.