File: properties.md

package info (click to toggle)
php-league-csv 9.23.0%2Bdfsg-1
  • links: PTS, VCS
  • area: main
  • in suites: sid, trixie
  • size: 39,720 kB
  • sloc: php: 13,345; javascript: 80; makefile: 29; xml: 29
file content (267 lines) | stat: -rw-r--r-- 8,144 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
---
layout: default
title: Setting and Accessing CSV settings
redirect_from: /properties/
---

# CSV properties

Once your object is [instantiated](/8.0/instantiation/) you can optionally set several CSV properties. The following methods works on both the `Reader` and the `Writer` class.

<p class="message-notice">Since version <code>8.1.1</code> The underlying CSV controls from the submitted CSV are inherited by the return <code>AbstractCsv</code> object.</p>

```php
$file = new SplTempFileObject();
$file->setFlags(SplFileObject::READ_CSV);
$file->setCsvControl('|');

$csv = Reader::createFromFileObject($file);

echo $csv->getDelimiter(); //display '|'
```

<p class="message-warning">Of note, The escape character is only inherited starting with <code>PHP 5.6.25</code> in the PHP5 line and <code>7.0.10</code> in the PHP7 version.</p>

## Accessing and Setting CSV properties

### The CSV delimiter character

#### Description

```php
public AbstractCsv::setDelimiter(string $delimiter): AbstractCsv
public AbstractCsv::getDelimiter(void): string
```

#### Example

```php
use League\Csv\Reader;

$csv = Reader::createFromPath('/path/to/file.csv', 'r');
$csv->setDelimiter(';');
$delimiter = $csv->getDelimiter(); //returns ";"
```

#### Notes

The default delimiter character is `,`.

### The enclosure character

#### Description

```php
public AbstractCsv::setEnclosure(string $delimiter): AbstractCsv
public AbstractCsv::getEnclosure(void): string
```

#### Example

```php
use League\Csv\Writer;

$csv = Writer::createFromPath('/path/to/file.csv');
$csv->setEnclosure('|');
$enclosure = $csv->getEnclosure(); //returns "|"
```

#### Notes

The default enclosure character is `"`.

### The escape character

<p class="message-warning"><strong>Warning:</strong> The library depends on PHP <code>SplFileObject</code> class. Since this class exhibits <a href="https://bugs.php.net/bug.php?id=55413" target="_blank">a reported bug</a>, <strong>Data using the escape character are correctly escaped but the escape character is not removed from the CSV content</strong>.<br>
A possible workaround to this issue while waiting for a PHP bug fix is <a href="/8.0/reading/">to register a callable to your extracting method when possible.</a></p>

#### Description

```php
public AbstractCsv::setEscape(string $delimiter): AbstractCsv
public AbstractCsv::getEscape(void): string
```

#### Example

```php
use League\Csv\Reader;

$csv = Reader::createFromPath('/path/to/file.csv', 'r');
$csv->setEscape('\\');
$escape = $csv->getEscape(); //returns "\"
```

#### Notes

The default escape character is `\`.

### fetchDelimitersOccurrence

This method allow you to find the occurrences of some delimiters in a given CSV object.

```php
public AbstractCsv::fetchDelimitersOccurrence(
    array $delimiters,
    int $nbRows = 1
): array
```

The method takes two arguments:

- an array containing the delimiters to check;
- an integer which represents the number of rows to scan (defaults to `1`);

```php
use League\Csv\Reader;

$reader = Reader::createFromPath('/path/to/your/csv/file.csv', 'r');
$reader->setEnclosure('"');
$reader->setEscape('\\');

$delimiters_list = $reader->fetchDelimitersOccurrence([' ', '|'], 10);
// $delimiters_list can be the following
// [
//     '|' => 20,
//     ' ' => 0,
// ]
// This seems to be a consistent CSV with:
// - the delimiter "|" appearing 20 times in the 10 first rows
// - the delimiter " " never appearing
```

<p class="message-warning"><strong>Warning:</strong> This method only test the delimiters you gave it.</p>

## Writing mode only properties

The following properties only affect the CSV object when you are writing and/or saving data to it.

<p class="message-notice">The <code>Reader</code> class still have access to them.</p>

### The newline sequence

To improve interoperability with programs interacting with CSV, the newline sequence is appended to each CSV newly inserted line.

#### Description

```php
public AbstractCsv::setNewline(string $sequence): AbstractCsv
public AbstractCsv::getNewline(void): string
```

#### Example

```php
use League\Csv\Writer;

$csv = Writer::createFromPath('/path/to/file.csv');
$csv->setNewline("\r\n");
$newline = $csv->getNewline(); //returns "\r\n"
```

#### Notes

The default newline sequence is `\n`;

### The BOM sequence

To improve interoperability with programs interacting with CSV, you can manage the presence of the <abbr title="Byte Order Mark">BOM</abbr> sequence in your CSV content.

#### Detect the currently used BOM sequence

<p class="message-warning"><strong>BC Break:</strong> <code>getInputBOM</code> always return a string</p>

```php
public AbstractCsv::getInputBOM(void): string
```

Detect the current BOM character is done using the `getInputBOM` method. This method returns the currently used BOM character or an empty string if none is found or recognized.

```php
use League\Csv\Writer;

$csv = Writer::createFromPath('/path/to/file.csv');
$bom = $csv->getInputBOM();
```

#### Set the outputting BOM sequence

```php
public AbstractCsv::setOutputBOM(string $sequence): AbstractCsv
public AbstractCsv::getOutputBOM(void): string
```

- `setOutputBOM`: sets the outputting BOM you want your CSV to be associated with.
- `getOutputBOM`: get the outputting BOM you want your CSV to be associated with.

<p class="message-warning"><strong>BC Break:</strong> <code>getOutputBOM</code> always return a string</p>

```php
use League\Csv\Reader;

$csv = Reader::createFromPath('/path/to/file.csv', 'r');
$csv->setOutputBOM(Reader::BOM_UTF8);
$bom = $csv->getOutputBOM(); //returns "\xEF\xBB\xBF"
```

#### Notes

- The default output `BOM` character is set to an empty string.
- The `AbstractCsv` class provide constants to ease BOM sequence manipulation.

<p class="message-info">Please refer to <a href="/8.0/bom/">the BOM character dedicated documentation page</a> for more information on how the library helps you manage this feature.</p>

## Conversion only properties

<p class="message-notice">The following properties and method only works when converting your CSV document into other available formats.</p>

To convert your CSV document into another format it must be encoded in `UTF-8`.

When this is not the case, you should transcode it first using the <a href="/8.0/filtering/">library stream filtering mechanism</a>. When this is not applicable you should provide the CSV original encoding charset to the CSV object using the following methods.

### methods

<p class="message-notice">These methods are introduced in version <code>8.1.0</code></p>

```php
public AbstractCsv::setInputEncoding(string $sequence): AbstractCsv
public AbstractCsv::getInputEncoding(void): string
```

<p class="message-warning">The following methods are deprecated since version <code>8.1.0</code> and will be remove in the next major release</p>

```php
public AbstractCsv::setEncodingFrom(string $sequence): AbstractCsv
public AbstractCsv::getEncodingFrom(void): string
```

- `AbstractCsv::setEncodingFrom` is replaced by `AbstractCsv::setInputEncoding`
- `AbstractCsv::getInputEncoding` is replaced by `AbstractCsv::getEncodingFrom`

#### Example

```php
use League\Csv\Reader;

$csv = Reader::createFromPath('/path/to/file.csv', 'r');
$csv->setInputEncoding('iso-8859-15');
echo $csv->getInputEncoding(); //returns iso-8859-15;
```

#### Notes

By default `getInputEncoding` returns `UTF-8` if `setInputEncoding` was not used.

<div class="message-warning">The encoding properties have no effect when reading or writing to a CSV document. You should instead use <a href="/8.0/filtering/">the Stream Filter API</a> or <a href="/8.0/inserting/#row-formatting">the Writing Formatter API</a>.</div>

```php
use League\Csv\Reader;

$reader = Reader::createFromFileObject(new SplFileObject('/path/to/bengali.csv'));
//we are using the setInputEncoding method to transcode the CSV into UTF-8
$reader->setInputEncoding('iso-8859-15');
echo json_encode($reader);
//the CSV is transcoded from iso-8859-15 to UTF-8
//before being converted to JSON format;
echo $reader; //outputting the data is not affected by the conversion
```