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_json/issues).

Keeping the developer happy 

If you appreciate this extension, don't hesitate to mention it around you.

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

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.

The paginator architecture has changed to allow for more flexibility. The calling connector is passed to the paginator in the constructor, making it available inside the paginator. Merging the paging parameter inside the query parameters is thus delegated to the paginator. As such the getNextPage() method has to call the mergePagingParameter() method. See the Developer's manual for reference and the implementation in the \Cobweb\SvconnectorJson\Paginator\HydraPaginator class as an example.

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 than "GET" when querying data.

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 "accept" and "useragent" configuration properties have been removed. They have been replaced by a more general "headers" property. You will need to update your configurations if you used any of these two properties.

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.

uri 

Type

string

Description

URI of the JSON resource to read. This may be any of the following syntaxes:

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

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

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.

Note

This makes sense only when using fully qualified URLs in the uri parameter.

Example

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

'requestOptions' => [
   'body' => '{"page": 1}',
   'headers' => [
      'Accept' => 'application/json',
   ],
],

Copied!

headers 

Type

array

Description

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

Warning

This parameter has been deprecated. It will be removed in the next major version. Use requestOptions instead.

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' => 'application/json',
]

Copied!

method 

Type

string

Description

Method to use for querying the external data source. Optional, defaults to GET.

queryParameters 

Type

array

Description

Key-value pairs of query parameters that should be added to the URI. This will only when the URI is a fully qualified URL and not in any of the other possibilities described above.

Example

Assuming that the uri parameter is "https://example.com", with the following quey parameters:

'queryParameters' => [
   'foo' => 'bar',
]

Copied!

the full URI to be queried will be "https://example.com?foo=bar".

paginator 

Type

string

Description

Many APIs present results that are paginated. Since these pagination mechanisms can be quite diverse, this extension cannot provide a solution that fits all situations.

Out of the box, the JSON-Hydra pagination format is supported, with the use of the "hydra" keyword.

For any other pagination mechanism, you will need to develop your own Paginator class.

The results are aggregated as if all data had been fetched in a single call.

Important

This works only with fetchArray() and fetchXMLl(). Since fetchRaw returns the original JSON data as a string, it only ever returns the result of the first page.

Warning

If you use pagination, you need to pass any other quey parameter from the uri with the queryParameters and not have them directly in the uri.

Example

To enable pagination for a Hydra data source:

'paginator' => 'hydra'

Copied!

To enable pagination for another type of data source with a custom Paginator:

'paginator' => \MyVendorName\MyExtension\Paginator\FooPaginator::class

Copied!

Using the connector 

Reading JSON data using the JSON connector service is a simple task. The first step is to get the proper service object with the desired parameters:

$parameters = [
   'uri' => 'http://forge.typo3.org/projects/extension-external_import/issues.json',
   'encoding' => 'utf-8',
];
$registry = GeneralUtility::makeInstance(\Cobweb\Svconnector\Registry\ConnectorRegistry::class);
$connector = $registry->getServiceForType('json', $parameters);

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

$data = $connector->fetchArray();

This will return a PHP array from the decoded JSON data. The fetchRaw() method will return the JSON data as a string.

The fetchXML() method returns a XML version of the PHP array transformed using TYPO3CMSCoreUtilityGeneralUtility::array2xml.

Custom paginators 

As explained in the Configuration chapter, only the JSON-Hydra pagination mechanism is covered out of the box by this extension. For any other mechanism, you need to develop your own paginator. This is done by extending the \Cobweb\SvconnectorJson\Paginator\AbstractPaginator class.

The following things need to be defined (or known):

Start page

Member variable $startPage defines the number of the page at the start of the pagination. By default, it is 1. In case it should be 0 (or some other value), you will need to override the constructor from the abstract class and set a different value for $startPage.

Paging parameter

Member variable $pagingParameter defines the name of the query parameter passed for pagination. By default, it is page. If this is not the case for you, you will need to override the constructor from the abstract class and set a different value for $pagingParameter.

Data

Member variable $data contains the data from the current page of results, as an array (i.e. it has gone through json_decode()). Nothing to do here, it is loaded into the paginator for each page call and at your disposal for determining the next page.

Connector

The calling connector object is available as member variable $connector.

getNextPage()

This method is at the heart of the pagination mechanism. Based on the data from the current result set, it needs to send back the number of the next page to call. It is expected to fall back on the start page, if the next page cannot be defined.

This method also needs to merge the page parameter with the connector's query parameters. The \Cobweb\SvconnectorJson\Paginator\AbstractPaginator class provides the utility method mergePagingParameter() for this, but you are of course free to use whatever custom code you need.

aggregate()

Once all pages of data have been fetched, the results must be aggregated. Again, this will be very different from one data source to another, and is thus implemented as a method of the custom paginator. The expected result of the call to aggregate() is a data structure as if all data had been fetched in a single call.

The existing \Cobweb\SvconnectorJson\Paginator\HydraPaginator is obviously a good reference for how this all works.