Iconify API configuration

This tutorial is a part of Iconify API installation instructions for PHP. This part of tutorial explains API configuration options.

Configuration is stored in file config.php. It is used only for customized values, so you do not need to store entire configuration.

Default configuration is stored in config-default.php.

Main options

region and env-region

Region is used as server identification. If you are running multiple Iconify API instances, by setting different region values you can check which server you are connected to.

How to check region? Open /version end point in browser: https://api.iconify.design/version. That page will show you API version, language (Node or PHP) and region.

Additionally, region can be set using environment variable "region".


Directory where custom icon sets are stored.

Icon sets must be stored in Iconify JSON format.

Filename must match prefix, for example awesome-icons:home should be stored in awesome-icons.json.

Default directory name is "json" relative to root directory.


If disabled, API will not load the default Iconify icon sets.


URL to redirect browser to when browsing /. Redirection is permanent.


Directory for caching files. This cache is used to speed up loading icon sets.

Cache directory must be writable by PHP process!


$config = [
   'cache-dir' => __DIR__ . '/cache'

Browser cache

Cache configuration is stored in cache array.

Array properties:

  • timeout, number. Cache timeout in seconds.
  • min-refresh, number. Minimum page refresh timeout. Usually the same as timeout value.
  • private, boolean. Set to true if page cache should be treated as private.


$config = [
   'cache' => [
       'timeout' => 604800,
       'min-refresh' => 604800,
       'private' => false

Synchronizing icon sets with Git

API can pull collections from Git service. This can be used to push collections to server whenever it is updated without manual work.

There are two collections available: "iconify" and "custom".

All configuration options are in sync object.

To synchronize repository send GET request to /sync?repo=iconify&key=your-sync-key Replace repo with "custom" to synchronize custom repository and key with value of sync.secret.

Server will respond identically with "ok" message after small delay regardless of status to prevent visitors from trying to guess your secret key.

Sync function is meant to be used with GitHub web hooks function. To avoid synchronizing icon sets too often, synchronization is delayed by 60 seconds (configure sync.sync-delay option to change it). This way when there are multiple commits submitted within a minute, synchronization is done only once 60 seconds after the first commit.

Sync object properties:

  • secret, string. Secret key. This is a required option.
  • versions, string. Location of versions.json file that stores information about the latest synchronized repositories.
  • storage, string. Location of directory where repositories will be stored.
  • git, string. Git command. You can change it if you need to customize command that is executed to clone repository. "{repo}" will be replaced with repository URL, "{target}" will be replaced with target directory.
  • iconify, string. URL of Iconify repository.
  • custom, string. URL of the custom repository.
  • custom-dir, string. Location of JSON files in custom repository, relative to root directory of repository.

Never change sync configuration in config-default.php! Change it only in config.php. Otherwise, it might be committed by mistake to a public repository, allowing everyone to see your secret words.


$config = [
   'sync' => [
       'custom' => 'https://github.com/cyberalien/animated-icons.git',
       'custom-dir' => 'final',
       'secret' => 'test' // Do not store this in config.php !!!


Property sync.custom-dir points to the location of JSON files in custom repository, relative to root directory of repository.

For example, if JSON files are located in directory "json" in your repository (like they are in Iconify repository), set sync.custom-dir value to "json".