Documentation

Writer extends AbstractCsv
in package
implements TabularDataWriter

A class to insert records into a CSV Document.

Table of Contents

Interfaces

TabularDataWriter
A class to insert records into a CSV Document.

Constants

ENCLOSE_ALL  = 1
ENCLOSE_NECESSARY  = 0
ENCLOSE_NONE  = -1
STREAM_FILTER_MODE  = \STREAM_FILTER_WRITE

Properties

$delimiter  : string
$document  : SplFileObject|Stream
$enclose_all  : int
$enclosure  : string
$enclosure_replace  : array{0: string[], 1: string[]}
$escape  : string
$flush_counter  : int
$flush_threshold  : int|null
$formatters  : array<string|int, callable(array<string|int, mixed>): array<string|int, mixed>>
$input_bom  : Bom|null
$is_input_bom_included  : bool
$newline  : string
$output_bom  : Bom|null
$stream_filters  : array<string, bool>
$validators  : array<string|int, callable(array<string|int, mixed>): bool>

Methods

__clone()  : mixed
__toString()  : string
DEPRECATION WARNING! This method will be removed in the next major point release.
addFormatter()  : static
Adds a record formatter.
addStreamFilter()  : static
DEPRECATION WARNING! This method will be removed in the next major point release.
addValidator()  : self
Adds a record validator.
appendStreamFilterOnRead()  : static
Append a stream filter.
appendStreamFilterOnWrite()  : static
Append a stream filter.
chunk()  : Generator
Returns the CSV document as a Generator of string chunk.
createFromFileObject()  : static
DEPRECATION WARNING! This method will be removed in the next major point release.
createFromPath()  : static
DEPRECATION WARNING! This method will be removed in the next major point release.
createFromStream()  : static
DEPRECATION WARNING! This method will be removed in the next major point release.
createFromString()  : static
DEPRECATION WARNING! This method will be removed in the next major point release.
download()  : int
Outputs all data on the CSV file.
encloseAll()  : bool
Tells whether new entries will all be enclosed on writing.
encloseNecessary()  : bool
Tells whether new entries will be selectively enclosed on writing if the field content requires encoding.
encloseNone()  : bool
Tells whether new entries will never be enclosed on writing.
forceEnclosure()  : self
from()  : static
Returns a new instance from a file path.
fromString()  : static
Returns a new instance from a string.
getContent()  : string
Retrieves the CSV content.
getDelimiter()  : string
Returns the current field delimiter.
getEnclosure()  : string
Returns the current field enclosure.
getEndOfLine()  : string
Returns the current end of line sequence characters.
getEscape()  : string
Returns the current field escape character.
getFlushThreshold()  : int|null
Returns the flush threshold.
getInputBOM()  : string
Returns the BOM sequence of the given CSV.
getNewline()  : string
DEPRECATION WARNING! This method will be removed in the next major point release.
getOutputBOM()  : string
Returns the BOM sequence in use on Output methods.
getPathname()  : string
Returns the pathname of the underlying document.
getStreamFilterMode()  : int
DEPRECATION WARNING! This method will be removed in the next major point release.
hasStreamFilter()  : bool
Tells whether the specified stream filter is attached to the current stream.
includeInputBOM()  : static
Disables skipping Input BOM.
insertAll()  : int
Adds multiple records to the CSV document.
insertOne()  : int
Adds a single record to a CSV document.
isInputBOMIncluded()  : bool
Tells whether the BOM can be stripped if presents.
necessaryEnclosure()  : self
noEnclosure()  : self
output()  : int
DEPRECATION WARNING! This method will be removed in the next major point release.
prependStreamFilterOnRead()  : static
Prepend a stream filter.
prependStreamFilterOnWrite()  : static
Prepend a stream filter.
relaxEnclosure()  : self
DEPRECATION WARNING! This method will be removed in the next major point release.
setDelimiter()  : static
Sets the field delimiter.
setEnclosure()  : static
Sets the field enclosure.
setEndOfLine()  : self
Sets the end of line sequence.
setEscape()  : static
Sets the field escape character.
setFlushThreshold()  : self
Sets the flush threshold.
setNewline()  : self
DEPRECATION WARNING! This method will be removed in the next major point release.
setOutputBOM()  : static
Sets the BOM sequence to prepend the CSV on output.
skipInputBOM()  : static
Enables BOM Stripping.
supportsStreamFilter()  : bool
DEPRECATION WARNING! This method will be removed in the next major point release.
supportsStreamFilterOnRead()  : bool
Tells whether the stream filter read capabilities can be used.
supportsStreamFilterOnWrite()  : bool
Tells whether the stream filter write capabilities can be used.
toString()  : string
Retrieves the CSV content.
__construct()  : mixed
addRecord()  : int|false
DEPRECATION WARNING! This method will be removed in the next major point release.
consolidate()  : int
DEPRECATION WARNING! This method will be removed in the next major point release.
formatRecord()  : array<string|int, mixed>
DEPRECATION WARNING! This method will be removed in the next major point release.
insertRecord()  : int|false
resetProperties()  : void
Reset dynamic object properties to improve performance.
sendHeaders()  : void
DEPRECATION WARNING! This method will be removed in the next major point release.
validateRecord()  : void
Validates a record.

Constants

ENCLOSE_ALL

protected mixed ENCLOSE_ALL = 1

ENCLOSE_NECESSARY

protected mixed ENCLOSE_NECESSARY = 0

ENCLOSE_NONE

protected mixed ENCLOSE_NONE = -1

STREAM_FILTER_MODE

protected mixed STREAM_FILTER_MODE = \STREAM_FILTER_WRITE

Properties

$document read-only

protected SplFileObject|Stream $document

$enclose_all

protected int $enclose_all = self::ENCLOSE_NECESSARY

$enclosure_replace

protected array{0: string[], 1: string[]} $enclosure_replace = [[], []]

$flush_counter

protected int $flush_counter = 0

$flush_threshold

protected int|null $flush_threshold = null

$formatters

protected array<string|int, callable(array<string|int, mixed>): array<string|int, mixed>> $formatters = []

collection of Closure to format the record before reading.

$is_input_bom_included

protected bool $is_input_bom_included = false

$newline

protected string $newline = "\n"

$stream_filters

protected array<string, bool> $stream_filters = []

collection of stream filters.

$validators

protected array<string|int, callable(array<string|int, mixed>): bool> $validators = []

callable collection to validate the record before insertion.

Methods

__toString()

DEPRECATION WARNING! This method will be removed in the next major point release.

public __toString() : string

since version 9.1.0

use League\Csv\AbstractCsv::toString() instead

Tags
see
AbstractCsv::toString
codeCoverageIgnore

Retrieves the CSV content

Return values
string

addFormatter()

Adds a record formatter.

public addFormatter(callable(array<string|int, mixed>): array<string|int, mixed> $formatter) : static
Parameters
$formatter : callable(array<string|int, mixed>): array<string|int, mixed>
Return values
static

addStreamFilter()

DEPRECATION WARNING! This method will be removed in the next major point release.

public addStreamFilter(string $filtername[, array<string|int, mixed>|null $params = null ]) : static

since version 9.22.0

use League\Csv\AbstractCsv::appendStreamFilterOnRead() or League\Csv\AbstractCsv::prependStreamFilterOnRead() instead

Parameters
$filtername : string
$params : array<string|int, mixed>|null = null
Tags
codeCoverageIgnore
see
AbstractCsv::appendStreamFilterOnRead()
see
AbstractCsv::appendStreamFilterOnWrite()

Append a stream filter.

throws
InvalidArgument

If the stream filter API can not be appended

throws
UnavailableFeature

If the stream filter API can not be used

Return values
static

addValidator()

Adds a record validator.

public addValidator(callable(array<string|int, mixed>): bool $validator, string $validator_name) : self
Parameters
$validator : callable(array<string|int, mixed>): bool
$validator_name : string
Return values
self

appendStreamFilterOnRead()

Append a stream filter.

public appendStreamFilterOnRead(string $filtername[, mixed $params = null ]) : static
Parameters
$filtername : string
$params : mixed = null
Tags
throws
InvalidArgument

If the stream filter API can not be appended

throws
UnavailableFeature

If the stream filter API can not be used

Return values
static

appendStreamFilterOnWrite()

Append a stream filter.

public appendStreamFilterOnWrite(string $filtername[, mixed $params = null ]) : static
Parameters
$filtername : string
$params : mixed = null
Tags
throws
InvalidArgument

If the stream filter API can not be appended

throws
UnavailableFeature

If the stream filter API can not be used

Return values
static

chunk()

Returns the CSV document as a Generator of string chunk.

public chunk(int $length) : Generator
Parameters
$length : int
Tags
throws
Exception

if the number of bytes is less than 1

Return values
Generator

createFromFileObject()

DEPRECATION WARNING! This method will be removed in the next major point release.

public static createFromFileObject(SplFileObject $file) : static

since version 9.27.0

Returns a new instance from a SplFileObject.

use League\Csv\AbstractCsv::from() instead

Parameters
$file : SplFileObject
Tags
codeCoverageIgnore
Return values
static

createFromPath()

DEPRECATION WARNING! This method will be removed in the next major point release.

public static createFromPath(string $path[, non-empty-string $open_mode = 'r+' ][, resource|null $context = null ]) : static

since version 9.27.0

Returns a new instance from a file path.

use League\Csv\AbstractCsv::from() instead

Parameters
$path : string
$open_mode : non-empty-string = 'r+'
$context : resource|null = null

the resource context

Tags
codeCoverageIgnore
throws
UnavailableStream
Return values
static

createFromStream()

DEPRECATION WARNING! This method will be removed in the next major point release.

public static createFromStream(resource $stream) : static

since version 9.27.0

Returns a new instance from a PHP resource stream.

use League\Csv\AbstractCsv::from() instead

Parameters
$stream : resource
Tags
codeCoverageIgnore
Return values
static

createFromString()

DEPRECATION WARNING! This method will be removed in the next major point release.

public static createFromString([Stringable|string $content = '' ]) : static

since version 9.27.0

Returns a new instance from a string.

use League\Csv\AbstractCsv::fromString() instead

Parameters
$content : Stringable|string = ''
Tags
codeCoverageIgnore
Return values
static

download()

Outputs all data on the CSV file.

public download([string|null $filename = null ]) : int

Returns the number of characters read from the handle and passed through to the output.

Parameters
$filename : string|null = null
Tags
throws
InvalidArgumentException|Exception
Return values
int

encloseAll()

Tells whether new entries will all be enclosed on writing.

public encloseAll() : bool
Return values
bool

encloseNecessary()

Tells whether new entries will be selectively enclosed on writing if the field content requires encoding.

public encloseNecessary() : bool
Return values
bool

encloseNone()

Tells whether new entries will never be enclosed on writing.

public encloseNone() : bool
Return values
bool

forceEnclosure()

public forceEnclosure() : self
Return values
self

from()

Returns a new instance from a file path.

public static from(SplFileInfo|SplFileObject|resource|string $filename[, non-empty-string $mode = 'r+' ][, resource|null $context = null ]) : static
Parameters
$filename : SplFileInfo|SplFileObject|resource|string

an SPL file object, a resource stream or a file path

$mode : non-empty-string = 'r+'

the file path open mode used with a file path or a SplFileInfo object

$context : resource|null = null

the resource context used with a file pathor a SplFileInfo object

Tags
throws
UnavailableStream
Return values
static

fromString()

Returns a new instance from a string.

public static fromString([Stringable|string $content = '' ]) : static
Parameters
$content : Stringable|string = ''
Return values
static

getContent()

Retrieves the CSV content.

public getContent() : string

since version 9.7.0

use League\Csv\AbstractCsv::toString() instead

DEPRECATION WARNING! This method will be removed in the next major point release

Tags
see
AbstractCsv::toString
codeCoverageIgnore
Return values
string

getDelimiter()

Returns the current field delimiter.

public getDelimiter() : string
Return values
string

getEnclosure()

Returns the current field enclosure.

public getEnclosure() : string
Return values
string

getEndOfLine()

Returns the current end of line sequence characters.

public getEndOfLine() : string
Return values
string

getEscape()

Returns the current field escape character.

public getEscape() : string
Return values
string

getFlushThreshold()

Returns the flush threshold.

public getFlushThreshold() : int|null
Return values
int|null

getInputBOM()

Returns the BOM sequence of the given CSV.

public getInputBOM() : string
Return values
string

getNewline()

DEPRECATION WARNING! This method will be removed in the next major point release.

public getNewline() : string

Since version 9.10.0

use League\Csv\Writer::getEndOfLine()

Tags
see
Writer::getEndOfLine()
codeCoverageIgnore

Returns the current newline sequence characters.

Return values
string

getOutputBOM()

Returns the BOM sequence in use on Output methods.

public getOutputBOM() : string
Return values
string

getPathname()

Returns the pathname of the underlying document.

public getPathname() : string
Return values
string

getStreamFilterMode()

DEPRECATION WARNING! This method will be removed in the next major point release.

public getStreamFilterMode() : int

since version 9.7.0

use League\Csv\AbstractCsv::supportsStreamFilterOnRead() or League\Csv\AbstractCsv::supportsStreamFilterOnWrite() instead

Tags
see
AbstractCsv::supportsStreamFilterOnRead
see
AbstractCsv::supportsStreamFilterOnWrite
codeCoverageIgnore

Returns the stream filter mode.

Return values
int

hasStreamFilter()

Tells whether the specified stream filter is attached to the current stream.

public hasStreamFilter(string $filtername) : bool
Parameters
$filtername : string
Return values
bool

includeInputBOM()

Disables skipping Input BOM.

public includeInputBOM() : static
Return values
static

insertOne()

Adds a single record to a CSV document.

public insertOne(array<string|int, mixed> $record) : int

A record is an array that can contain scalar type values, NULL values or objects implementing the __toString method.

Parameters
$record : array<string|int, mixed>
Tags
throws
CannotInsertRecord

If the record can not be inserted

throws
Exception

If the record can not be inserted

Return values
int

isInputBOMIncluded()

Tells whether the BOM can be stripped if presents.

public isInputBOMIncluded() : bool
Return values
bool

necessaryEnclosure()

public necessaryEnclosure() : self
Return values
self

noEnclosure()

public noEnclosure() : self
Return values
self

output()

DEPRECATION WARNING! This method will be removed in the next major point release.

public output([string|null $filename = null ]) : int

since version 9.18.0

use League\Csv\AbstractCsv::download() instead

Parameters
$filename : string|null = null
Tags
codeCoverageIgnore
see
AbstractCsv::download()

Outputs all data on the CSV file.

Returns the number of characters read from the handle and passed through to the output.

throws
Exception
Return values
int

prependStreamFilterOnRead()

Prepend a stream filter.

public prependStreamFilterOnRead(string $filtername[, mixed $params = null ]) : static
Parameters
$filtername : string
$params : mixed = null
Tags
throws
InvalidArgument

If the stream filter API can not be appended

throws
UnavailableFeature

If the stream filter API can not be used

Return values
static

prependStreamFilterOnWrite()

Prepend a stream filter.

public prependStreamFilterOnWrite(string $filtername[, mixed $params = null ]) : static
Parameters
$filtername : string
$params : mixed = null
Tags
throws
InvalidArgument

If the stream filter API can not be appended

throws
UnavailableFeature

If the stream filter API can not be used

Return values
static

relaxEnclosure()

DEPRECATION WARNING! This method will be removed in the next major point release.

public relaxEnclosure() : self

Since version 9.22.0

use League\Csv\Writer::necessaryEnclosure()

Tags
see
Writer::necessaryEnclosure()
codeCoverageIgnore

Sets the enclosure threshold to only enclose necessary fields.

Return values
self

setDelimiter()

Sets the field delimiter.

public setDelimiter(string $delimiter) : static
Parameters
$delimiter : string
Tags
throws
InvalidArgument

If the Csv control character is not one character only.

Return values
static

setEnclosure()

Sets the field enclosure.

public setEnclosure(string $enclosure) : static
Parameters
$enclosure : string
Tags
throws
InvalidArgument

If the Csv control character is not one character only.

Return values
static

setEndOfLine()

Sets the end of line sequence.

public setEndOfLine(string $endOfLine) : self
Parameters
$endOfLine : string
Return values
self

setEscape()

Sets the field escape character.

public setEscape(string $escape) : static
Parameters
$escape : string
Tags
throws
InvalidArgument

If the Csv control character is not one character only.

Return values
static

setFlushThreshold()

Sets the flush threshold.

public setFlushThreshold(int|null $threshold) : self
Parameters
$threshold : int|null
Tags
throws
InvalidArgument

if the threshold is an integer less than 1

Return values
self

setNewline()

DEPRECATION WARNING! This method will be removed in the next major point release.

public setNewline(string $newline) : self

Since version 9.10.0

use League\Csv\Writer::setEndOfLine()

Parameters
$newline : string
Tags
see
Writer::setEndOfLine()
codeCoverageIgnore

Sets the newline sequence.

Return values
self

setOutputBOM()

Sets the BOM sequence to prepend the CSV on output.

public setOutputBOM(Bom|string|null $str) : static
Parameters
$str : Bom|string|null
Tags
throws
InvalidArgument

if the given non-empty string is not a valid BOM sequence

Return values
static

skipInputBOM()

Enables BOM Stripping.

public skipInputBOM() : static
Return values
static

supportsStreamFilter()

DEPRECATION WARNING! This method will be removed in the next major point release.

public supportsStreamFilter() : bool

since version 9.7.0

use League\Csv\AbstractCsv::supportsStreamFilterOnRead() or League\Csv\AbstractCsv::supportsStreamFilterOnWrite() instead

Tags
see
AbstractCsv::supportsStreamFilterOnRead
see
AbstractCsv::supportsStreamFilterOnWrite
codeCoverageIgnore

Tells whether the stream filter capabilities can be used.

Return values
bool

supportsStreamFilterOnRead()

Tells whether the stream filter read capabilities can be used.

public supportsStreamFilterOnRead() : bool
Return values
bool

supportsStreamFilterOnWrite()

Tells whether the stream filter write capabilities can be used.

public supportsStreamFilterOnWrite() : bool
Return values
bool

toString()

Retrieves the CSV content.

public toString() : string
Tags
throws
Exception

If the string representation cannot be returned

Return values
string

__construct()

protected __construct(SplFileObject|Stream $document) : mixed
Parameters
$document : SplFileObject|Stream
Tags
final

This method should not be overwritten in child classes

addRecord()

DEPRECATION WARNING! This method will be removed in the next major point release.

protected addRecord(array<string|int, mixed> $record) : int|false

Since version 9.9.0

no longer affecting the class behaviour

Parameters
$record : array<string|int, mixed>
Tags
codeCoverageIgnore

Adds a single record to a CSV Document using PHP algorithm.

see
https://php.net/manual/en/function.fputcsv.php
Return values
int|false

consolidate()

DEPRECATION WARNING! This method will be removed in the next major point release.

protected consolidate() : int

Since version 9.9.0

no longer affecting the class behaviour

Tags
codeCoverageIgnore

Applies post insertion actions.

Return values
int

formatRecord()

DEPRECATION WARNING! This method will be removed in the next major point release.

protected formatRecord(array<string|int, mixed> $record, callable $formatter) : array<string|int, mixed>

since version 9.8.0

no longer affecting the class behaviour

Parameters
$record : array<string|int, mixed>
$formatter : callable
Tags
codeCoverageIgnore

Format a record.

The returned array must contain

  • scalar types values,
  • NULL values,
  • or objects implementing the __toString() method.
Return values
array<string|int, mixed>

insertRecord()

protected insertRecord(array<string|int, mixed> $record) : int|false
Parameters
$record : array<string|int, mixed>
Return values
int|false

resetProperties()

Reset dynamic object properties to improve performance.

protected resetProperties() : void

sendHeaders()

DEPRECATION WARNING! This method will be removed in the next major point release.

protected sendHeaders(string $filename) : void

since version 9.17.0

the method no longer affect the outcome of the class, use League\Csv\HttpHeaders::forFileDownload instead

Parameters
$filename : string
Tags
throws
Exception

if the submitted header is invalid according to RFC 6266

see
HttpHeaders::forFileDownload()
see
https://tools.ietf.org/html/rfc6266#section-4.3
codeCoverageIgnore

Send the CSV headers.

Adapted from Symfony\Component\HttpFoundation\ResponseHeaderBag::makeDisposition

validateRecord()

Validates a record.

protected validateRecord(array<string|int, mixed> $record) : void
Parameters
$record : array<string|int, mixed>
Tags
throws
CannotInsertRecord

If the validation failed


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results