< and copy the device data file download URL
located at "API Data Files" -> "Device Identification" -> "Download Data" -> "ZIP"
#### Carrier Data File URL ####
Navigate to [deviceatlas.com/user](https://deviceatlas.com/user) and copy the carrier data file download URL
located at "API Data Files" -> "Carrier Identification" -> "Download Data" -> "ZIP"
### Basic Usage ###
To change the default download and load behaviour you must create an instance of the
`DataFile` class and pass it to the `downloadAndLoadDataFileFromUrl` method in either the
`DeviceApi` or `CarrierApi`:
__Device data file example usage__
```php
use DeviceAtlas\Device\DeviceApi;
use DeviceAtlas\DataFile;
$deviceDataFile = DataFile::Builder(<data file download URL>)->fileDirectory(<persistent download directory>)->buildDeviceDataFile();
$deviceApi = new DeviceApi();
$deviceApi->downloadAndLoadDataFileFromUrl($deviceDataFile);
```
__Carrier data file example usage__
```php
use DeviceAtlas\Carrier\CarrierApi;
use DeviceAtlas\DataFile;
$carrierDataFile = DataFile::Builder(<data file download URL>)->fileDirectory(<persistent download directory>)->buildCarrierDataFile();
$carrierApi = new CarrierApi();
$carrierApi->downloadAndLoadDataFileFromUrl($carrierDataFile);
```
### DataFile class ###
The DeviceAtlas `DataFile` class provides options to customize the frequency,
location and validation of the DeviceAtlas data file downloads.
* Download and load frequency
* Download file location
* Data file download read timeout
* Data file download validation
* Disabling automatic data file download and load
** When using download features ensure php has
zip (ZipArchive) or gzip (gzopen)
as extension or build lib supported in PHP environment.
#### Download and load frequency ####
The frequency in days to download and load the latest data file.
Note the minimum value is 1 day.
**DataFile methods**
```
downloadAndLoadFrequencyDays(<integer>)
```
**Default value**
1
#### Download file location ####
The file system directory where the data file will be downloaded to.
It is strongly recommended to set this to a persistent file path to
ensure there is always a data file on the system that can be loaded
immediately.
**DataFile methods**
```
fileDirectory(<string>)
```
**Default value**
The system's temporary directory.
#### Data file download read timeout ####
The time in milliseconds allowed to read data from the download server.
**DataFile methods**
```
downloadReadTimeoutMilliseconds(<integer>)
```
**Default value**
60000 (60 seconds)
#### Disabling automatic data file download and load ####
If for any reason it is necessary to prevent reload of the data file
this can be achieved by calling the`disableScheduledDownloadAndReload`
method with `true`.
**DataFile methods**
```
disableScheduledDownloadAndReload(<boolean>)
```
**Default value**
False
#### Dealing with scheduled background data file load failures ####
In the event that the background task that loads the data file into the
API fails you may implement the `DownloadAndLoadTaskFailureCallback` interface
and set it in the `DataFile` object. If an exception occurs the `handle` method
of the interface will be called and an object of class `Exception` is passed
as a parameter. An example use case for this callback would be to log the exception.
**DataFile methods**
```
downloadAndLoadTaskFailureCallback(<DataFileException>)
```
**Example usage**
```php
class DeviceAtlasDataFileFailure implements DownloadAndLoadTaskFailureCallback {
$logger = Logger::getLogger(basename(__FILE__));
public function handle($dataFileException) {
$logger->error("Error loading DeviceAtlas data file" . $dataFileException);
}
}
$dataFile = DataFile::Builder(<data file download URL>)->downloadAndLoadTaskFailureCallback(new DeviceAtlasDataFileFailure())->buildDeviceDataFile();
```
### Custom Endpoint Data File Provisioning ###
If you would like to provision the data files from a custom endpoint please
note the following:
#### Supported content types ####
For both the Device and Carrier data files, only GZIP compression is supported (without installation
of any additional php modules/extensions). For extended support for ZIP compression, php zip module
need to be installed. For ZIP files please provide "application/zip" as a "Content-Type" response
header. For GZIP files please provide "application/x-gzip" as a "Content-Type" response header.
Uncompressed data files are also supported. For uncompressed Device data files please provide
"application/json" as a "Content-Type" response header. For uncompressed Carrier data files
please provide "application/octet-stream" as a "Content-Type" response header.
#### Data file download validation ####
The data file download is validated by comparing the MD5 checksum of the data file
against the MD5 checksum header (Content-MD5) sent with the data file download.
It is recommended to provide an MD5 checksum of the data file as a "Content-MD5"
response header.
If you do not wish to send an MD5 checksum header this validation can be disabled by
passing `false` to the `validateMd5` method. The name of the header containing the MD5
checksum can also be modified using the `headerContentMd5` method.
**DataFile methods**
```
validateMd5(<boolean>)
headerContentMd5(<string>)
```
**Validate MD5 default value**
true
**MD5 header default value**
Content-MD5
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
_ Copyright (c) DeviceAtlas Limited 2023. All Rights Reserved. _
_ https://deviceatlas.com _
<!-- HTML+JS for document formatting when opened in browser -->
<div class="btn-group" id="main-menu" style="float:right"><a class="btn dropdown-toggle" data-toggle="dropdown" href="#">Menu<span class="caret"></span></a><ul class="dropdown-menu"><li><a href="README.html">Main</a></li><li class="disabled"><a href="README.DataFile.html">Data File Configuration</a></li><li><a href="README.DeviceApi.html">Device API Usage</a></li><li><a href="README.ClientHints.html">Client Hints Support</a></li><li><a href="README.DataFileOptimizer.html">Data File Optimizer</a></li><li><a href="README.Upgrade.html">Device API Upgrade</a></li><li><a href="README.CarrierApi.html">Carrier Identification API</a></li><li class="divider"></li><li><a href="./ApiDocs/index.html">DeviceAtlas API Docs</a></li></ul></div>]]>