csv_writer_task.md

CsvWriterTask

Writes each received array as a line of a CSV file. As a blocking task, it waits until all inputs have been received and then outputs the file path.

Task reference

• Service: CleverAge\ProcessBundle\Task\File\Csv\CsvWriterTask
• Code: csv_writer (task: csv_writer)
• Blocking task

Accepted inputs

array: an associative array whose keys match the headers and values are convertible to string. Values that are arrays are imploded using the split_character option. Underlying method is fputcsv.

Possible outputs

string: path of the written file (with placeholders replaced), once all inputs have been processed.

Options

Code	Type	Required	Default	Description
file_path	string	X		Path of the file to write to (absolute or relative to the current working directory). Placeholders {date}, {date_time}, {timestamp} and {unique_token} are replaced in the path
delimiter	string		;	CSV delimiter
enclosure	string		"	CSV enclosure character
escape	string		\	CSV escape character
headers	array|null		null	Static list of CSV headers. If null, the keys of the first input are used
mode	string		wb	File open mode (see fopen mode parameter)
split_character	string		|	Used to implode array values
write_headers	bool		true	Write the headers as first line, only if the file is empty (useful with an append mode); cast to bool
escape_formulas	bool		false	Prefix with a single quote the values and the headers starting with =, -, +, @, a tabulation, a carriage return or a line feed, so that a spreadsheet application does not interpret them as formulas (see notes)

Examples

• Write a CSV file with a date in its name

# Task configuration level
entry:
  task: constant_iterable_output
  options:
    output:
      - column1: value1-1
        column2: value2-1
      - column1: value1-2
        column2: value2-2
  outputs: [write]
write:
  task: csv_writer
  options:
    file_path: '%kernel.project_dir%/var/data/csv_writer_{date_time}.csv'

• Write a file opened by users in a spreadsheet application, with values coming from outside (CSV injection)

# Task configuration level
write:
  task: csv_writer
  options:
    file_path: '%kernel.project_dir%/var/data/customers.csv'
    escape_formulas: true

• Append lines to an existing file, with fixed headers

# Task configuration level
write:
  task: csv_writer
  options:
    file_path: '%kernel.project_dir%/var/data/export.csv'
    mode: 'ab'
    headers: [sku, name, price]

Notes

• {date} is replaced by Ymd, {date_time} by Ymd_His, {timestamp} by the Unix timestamp and {unique_token} by a uniqid('', true) value (23 characters, containing a dot).
• The parent directory of the file is created if needed.
• An input that is not an array throws an UnexpectedValueException.
• Each input must contain every header key (extra keys are not allowed: the number of columns must match the number of headers), otherwise an UnexpectedValueException is thrown. Columns are written in the headers order.
• A value starting with =, +, - or @ is interpreted as a formula when the file is opened in a spreadsheet application (CSV injection, see OWASP): it can display misleading data or exfiltrate data of the sheet through a link. When the values come from outside (user inputs, an API...) and the file is opened by users, enable escape_formulas (same characters as the csv_escape_formulas context of the Symfony Serializer CsvEncoder): the value is prefixed with a single quote, displayed as text (the quote is hidden by most spreadsheet applications, but kept by other readers of the file). Strings, numbers and Stringable objects are escaped, after the implode of the arrays: a negative number (-5) is then written as text ('-5).