CSV Connector Service

CSV Connector Service 

Language

en

Version

6.0

Description

Connector service for reading a CSV or similar flat file.

Keywords

CSV, data import, fetch data

Copyright

2009-2026

Author

François Suter (Idéative)

Email

typo3@ideative.ch

License

This document is published under the Creative Commons BY 4.0 license.

Rendered

Wed, 22 Apr 2026 10:18:40 +0000

The content of this document is related to TYPO3, a GNU/GPL CMS/Framework available from www.typo3.org.

Introduction 

This extension implements a specific connector service for reading flat files, in particular in CSV format. Although PHP provides standard functions for reading flat files, using a connector services provides a developer with a standardized way of accessing such files.

Questions and support 

If you have any questions about this extension, please ask them in the TYPO3 English mailing list, so that others can benefit from the answers. Please use the bug tracker on GitHub to report problem or suggest features (https://github.com/cobwebch/svconnector_csv/issues).

Keeping the developer happy 

Every encouragement keeps the developer ticking, so don't hesitate to send thanks or share your enthusiasm about the extension. If you really want to give something back, you may consider my Amazon wish list: http://www.amazon.co.uk/registry/wishlist/G7DI2AN99Y4F

You may also take a step back and reflect about the beauty of sharing. Think about how much you are benefiting and how much yourself is giving back to the community.

Installation 

Install this extension and you can start using its API for reading flat files inside your own code. It requires extension “svconnector” which provides the base for all connector services.

André Wuttig has developed a variant for reading large files line per line. If this sounds like something you may need, please take a look at https://github.com/portrino/svconnector_csv_extended

Updating to 6.0.0 

Version 6.0.0 adds support for TYPO3 14 and PHP 8.5, while dropping support for TYPO3 12 and PHP 8.1.

A new parameter requestOptions is available. It makes it possible to use any of the request options supported by Guzzle HTTP. The "headers" parameter has been deprecated. Headers should be passed as part of the "requestOptions" instead.

Hooks have been entirely removed. Use only events.

Updating to 5.0.0 

Version 5.0.0 adds support for TYPO3 13 and PHP 8.4, while dropping support for TYPO3 11 and PHP 7.4 and 8.0.

Events have been introduced to replace hooks. Existing hooks are still in place, but are deprecated and events should now be used instead (see the svconnector manual for reference).

It is now possible to choose another method that "GET" when querying data, as well as passing any number of headers as array.

Updating to 4.0.0 

Version 4.0.0 adds support for TYPO3 12 and PHP 8.1, while dropping support for TYPO3 10. It adapts to the new way of registering Connector Services. The update process should be smooth with "svconnector" version 5.0.0.

Updating to 3.0.0 

Version 3.0.0 adds support for TYPO3 11 and PHP 8.0, while dropping support for TYPO3 8 and 9. Apart from that it does not contain other changes and the update process should be smooth.

Updating to version 2.4.0 

The "encoding" configuration property has changed behavior. It used to accept all known encoding values plus all the synonyms defined in array \TYPO3\CMS\Core\Charset\CharsetConverter::$synonyms. This array does not exist in TYPO3 v10 anymore, thus usage of synonyms has been dropped. Check your configuration and verify that you use encoding names as defined in https://www.php.net/manual/en/mbstring.supported-encodings.php.

Configuration 

This chapter describes the parameters that can be used to configure the CSV connector service.

filename 

Type
string
Description

This is the name of the file to read. The reference to the file can use any of the following syntaxes:

  • absolute file path: /var/foo/web/fileadmin/import/bar.csv (within the TYPO3 root path or TYPO3_CONF_VARS[BE][lockRootPath])
  • file path relative to the TYPO3 root: fileadmin/import/foo.csv
  • file path using EXT:: EXT:foo/Resources/Private/Data/bar.csv
  • fully qualified URL, e.g. http://www.example.com/foo.csv
  • FAL reference with storage ID and file identifier: FAL:2:/foo.csv
  • custom syntax: MYKEY:whatever_you_want, see Connector Services

method 

Type
string
Description
Method used to get the file (GET, POST, or whatever else is relevant). This parameter is optional and the method defaults to GET.

requestOptions 

Type
array
Description

Key-value pairs of options that can be passed to the request. Any of the request options supported by Guzzle HTTP may be used.

Example

Passing a "page" information in the body and setting an accepted mime type in the headers.

'requestOptions' => [
   'body' => '{"page": 1}',
   'headers' => [
      'Accept' => 'text/csv',
   ],
],
Copied!

headers 

Type
array
Description

Key-value pairs of headers that should be sent along with the request.

Example

Example headers for setting an alternate user agent and defining what reponse format to accept.

'headers' => [
   'User-Agent' => 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:75.0) Gecko/20100101 Firefox/75.0',
   'Accept' => 'text/csv',
]
Copied!

encoding 

Type
string
Description
Encoding of the data found in the file. This value must match any of the encoding values recognized by the PHP libray "mbstring". See https://www.php.net/manual/en/mbstring.supported-encodings.php

delimiter 

Type
string
Description
The character used to separate the various fields on each line of the file.
Default
, (comma)

text_qualifier 

Type
string
Description
The character used to wrap text fields.
Default
" (double quote)

skip_rows 

Type
int
Description

The number of rows to ignore at the beginning of the file.

This has an additional special meaning if larger than 0. The CSV connector will take the first line and read column labels from it. These labels will then be used as keys in the array of data returned. The other skipped lines are totally ignored.

Default
0

locale 

Type
int
Description

A locale string, according to the locales available on the server.

This may not be necessary. However it may happen to be needed to handle badly-encoded files for example. The symptom is special characters – like umlauts – disappearing in the imported data.

Special considerations 

Encoding 

Once the data is read, it is converted from the encoding given as a parameter to the current encoding (either FE or BE, as stored in TYPO3CMSLangLanguageService::$charSet), if they are not the same. If the encoding parameter is left empty, no conversion takes place.

CSV data structure 

Beware of incomplete data in the CSV file. It will generate variable results depending on the position of the missing data. Consider the following CSV data:

foo;12;aaa
bar;42
baz;;bbb
 ;;ccc
36
Copied!

Empty columns before the last one will be returned as empty strings. Missing columns at the end of each row simply do not exist. The above data will be returned as the following PHP array:

'result' => [
   [
      'foo',
      '12',
      'aaa'
   ],
   // Missing columns at the end are totally missing in the result
   [
      'bar',
      '42'
   ],
   // Missing columns before the last one are returned as empty strings...
   [
      'baz',
      '',
      'bbb'
   ],
   // ...but spaces are preserved
   [
      ' ',
      '',
      'ccc'
   ],
   [
      '36'
   ]
)
Copied!

Developer's manual 

Reading a flat file using the CSV connector service becomes a really easy task. The first step is to get the proper service object with the desired parameters:

$parameters = [
   'filename' => 'path/to/your/file',
   'delimiter' => "\t",
   'text_qualifier' => '',
   'encoding' => 'utf-8',
   'skip_rows' => 1,
];
$registry = GeneralUtility::makeInstance(\Cobweb\Svconnector\Registry\ConnectorRegistry::class);
$connector = $registry->getServiceForType('csv');
Copied!

The next step is simply to call the appropriate method from the API depending on which format you want to have in return. For a PHP array:

$data = $connector->fetchArray($parameters);
Copied!

In the above example we declare the file as using tabs as delimiter and no text qualifier. Furthermore the file is declared as being encoded in UTF-8 and its first line should be ignored.

Let's assume the file looks something like this:

last_name	first_name
Wellington	Nicholas
Oshiro	Ki
Duncan	Dwayne
Copied!

The resulting array stored in $data will be:

last_name first_name
Wellington Nicholas
Oshiro Ki
Duncan Dwayne

The fetchRaw() method returns a two-dimensional array with one entry per line in the file and in each of these an entry per column. The fetchXML() method returns the array created by fetchArray() transformed to XML using TYPO3CMSCoreUtilityGeneralUtility::array2xml_cs().

Sitemap