-
-
Notifications
You must be signed in to change notification settings - Fork 333
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
13 changed files
with
649 additions
and
647 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,149 @@ | ||
| --- | ||
| layout: default | ||
| title: Records conversion in popular formats | ||
| --- | ||
|
|
||
| # Records conversion | ||
|
|
||
| The `League\Csv\Converter` is a class which convert any a collection of CSV records into a specified format. This collection can be: | ||
|
|
||
| - a [Reader](/9.0/reader/) object | ||
| - a [RecordSet](/9.0/reader/records/) object or any results from its extracting methods; | ||
| - any `Traversable` or `array` which represents a collection of records; | ||
|
|
||
| <p class="message-warning">A <code>Writer</code> object can not be converted.</p> | ||
|
|
||
| ## Convertion settings | ||
|
|
||
| ~~~php | ||
| <?php | ||
| public Converter::inputEncoding(string $charset): self | ||
| public Converter::xmlElements(string $root_name = 'csv', string $record_name = 'row', string $item_name = 'cell'): self | ||
| public Converter::xmlAttributes(string $offset_name = '', string $column_name = ''): self | ||
| public Converter::jsonOptions(bool $preserve_offset, int options = 0, int $depth = 512): self | ||
| ~~~ | ||
|
|
||
| Before convertion your records, you will want to configure your converter. | ||
|
|
||
| When building a `Converter` object, the methods do not need to be called in any particular order, and may be called multiple times. Because the `Converter` object is immutable, each time its setter methods are called they will return a new `Converter` object without modifying the current `Converter` object. | ||
|
|
||
| ### Records Input Encoding | ||
|
|
||
| <p class="message-warning">Out of the box, <code>League\Csv\Converter</code> assumes that your are submitting <code>UTF-8</code> encoded records. If your data is not <code>UTF-8</code> encoded some unexpected results or errors may be thrown when trying to convert your data.</p> | ||
|
|
||
| If the submitted records comes from a `Reader` object which supports PHP stream filters then it's recommended to use the library [stream filtering mechanism](/9.0/connections/filters/) to convert your data. Otherwise you can fallback to using the `Converter::inputEncoding` method. | ||
|
|
||
|
|
||
| ~~~php | ||
| <?php | ||
|
|
||
| use League\Csv\Converter; | ||
| use League\Csv\Reader; | ||
|
|
||
| $csv = new Reader::createFromFileObject(new SplFileObject('/path/to/french.csv', 'r')); | ||
| $converter = new Converter(); | ||
| if (!$csv->supportsStreamFilter()) { | ||
| $converter = $encoder->inputEncoding('iso-8859-15'); | ||
| } | ||
|
|
||
| $xml = $converter->toXML($csv); | ||
| ~~~ | ||
|
|
||
| ### XML and HTML element and attribute names | ||
|
|
||
| ~~~php | ||
| <?php | ||
|
|
||
| public Converter::xmlElements(string $root_name, string $record_name, string $item_name): self | ||
| public Converter::xmlAttributes(string $offset_name = '', string $column_name = ''): self | ||
| ~~~ | ||
|
|
||
| If you want to convert your CSV document into a `DOMDocument` you will need to set the XML element names using `Converter::xmlElements`: | ||
|
|
||
| - `$root_name` sets the XML root name which defaults to `csv`; | ||
| - `$record_name` sets the XML node element representing a CSV row which defaults to `row`; | ||
| - `$item_name` sets the XML node element for each CSV cell which defaults value is `cell`; | ||
|
|
||
| <p class="message-warning"><code>Converter::xmlElements</code> settings are not taken into account when converting your CSV into an HTML table.</p> | ||
|
|
||
| You can optionnaly sets the following XML element attributes using `Converter::xmlAttributes`. | ||
|
|
||
| - `$offset_name`, sets the XML/HTML node element attribute for each CSV record offset if a header was prodived which defaults value is `name`; | ||
| - `$column_name`, sets the XML/HTML node element attribute for each CSV cell name; | ||
|
|
||
| These attributes will only be used if their value differs from the empty string. | ||
|
|
||
| ### Json options | ||
|
|
||
| ~~~php | ||
| <?php | ||
| public Converter::jsonOptions(bool $preserve_offset, int options = 0, int $depth = 512): self | ||
| ~~~ | ||
|
|
||
| If you want to convert your CSV document into a json string you want to set the following json options: | ||
|
|
||
| - `$preserve_offset`, to preserve the CSV record offset; | ||
| - `$options`, to set `json_encode` optional `$options` argument; | ||
| - `$depth`, to set `json_encode` optional `$depth` argument; | ||
|
|
||
| ## Convertion methods | ||
|
|
||
| ~~~php | ||
| <?php | ||
| public Converter::toJson(iterable $records: string | ||
| public Converter::toXML(iterable $records): DOMDocument | ||
| public Converter::toHTML(iterable $records): string | ||
| ~~~ | ||
|
|
||
| All convertion methods only accepts an `iterable` which represents the records collection. | ||
|
|
||
| ~~~php | ||
| <?php | ||
|
|
||
| use League\Csv\Converter; | ||
| use League\Csv\Statement; | ||
| use League\Csv\Reader; | ||
|
|
||
| $csv = Reader::createFromPath('/path/to/prenoms.csv') | ||
| ->setDelimiter(';') | ||
| ->setHeaderOffset(0) | ||
| ->addStreamFilter('convert.iconv.ISO-8859-1/UTF-8') | ||
| ; | ||
|
|
||
| $stmt = (new Statement()) | ||
| ->where(function (array $record) { | ||
| return 'Anaïs' === $record['prenoms']; | ||
| }) | ||
| ->offset(0) | ||
| ->limit(2) | ||
| ; | ||
|
|
||
| $converter = (new Converter()) | ||
| ->xmlElements('csv', 'record', 'field') | ||
| ->xmlAttributes('offset', 'name') | ||
| ; | ||
|
|
||
| $records = $stmt->process($csv); | ||
| $records->preserveOffset(true); | ||
|
|
||
| $dom = $converter->toXML($records); | ||
| $dom->formatOutput = true; | ||
|
|
||
| echo '<pre>', PHP_EOL; | ||
| echo htmlentities($dom->saveXML()); | ||
| // <?xml version="1.0" encoding="UTF-8"?> | ||
| // <csv> | ||
| // <record offset="71"> | ||
| // <field name="prenoms">Anaïs</field> | ||
| // <field name="nombre">137</field> | ||
| // <field name="sexe">F</field> | ||
| // <field name="annee">2004</field> | ||
| // </record> | ||
| // <record offset="1099"> | ||
| // <field name="prenoms">Anaïs</field> | ||
| // <field name="nombre">124</field> | ||
| // <field name="sexe">F</field> | ||
| // <field name="annee">2005</field> | ||
| // </record> | ||
| // </csv> | ||
| ~~~ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.