The CONFIG module

Because the FW App System is designed so that it can be used in many different ways, it comes with a Config module that is used to handle user configuration of FW Api itself and of specific applications within the system. Its primary function is to parse and hold on to the configuration parameters from the application, allowing the rest of FW to access said parameters to configure the app for each need.

Default Config Setup

By default, FW comes with a basic api/app configuration setup that is designed to be easy to use and understand. The FW Api installation comes with a file: global.php which is used for storing global or default configuration variables common to all of the applications. By default, the provided global.php is empty. However, it can be edited to provide any variables necessary.


// global.php
return array();

However, some applications may use a different value for a specific configuration parameter. For that there are specific application configuration files. Each app (if built from FW Kit or FW Kit (GC)) comes with an app.php, which handles app-specific configuration variables, such as the application namespace and definition of custom module implementations. To allow for application-specific overrides of global config variables, the variables in application-specific configs will override those of the global FW Api config file.

Another purpose of configuration is to store sensitive data such as api keys or database connection parameters. Because it is sensitive data, it is considered unwise to commit such config variables into source control. Because of this, the FW Api and each FW App come with a file called local.php. This file serves as a place for sensitive, installation-specific data. This file contains no variables by default, and is designed to be configured per-application so that a user can fill in the variables themselves.

If the local.php file does not exist (in the same folder as either global.php or app.php), then you can create it and paste this code into it:


return array();

You can then fill it with whatever data you choose.

Because there are config files in several locations, there is a config "inheritance" structure in the sense that some config files override the values of other ones.

The default inheritance structure is as follows:

  • global.php is loaded first
  • the FW Api's local.php is loaded second, and values in this file will override those in global.php,
  • 'app.php' is loaded for an application and overrides any values in the previous two files
  • the app's local.php is loaded and overrides any values in the previous three.

Each module in FW Api can have their own specific configuration values, and each specifies what config values it needs in its documentation. However, there are some nonspecific configuration values that merit listing (they are all optional by default):

  • "main" - This config value tells the app loader what the main App class is called (by default it is "App", which maps to the App.php file)
  • "namespace" - This is set to the namespace of your application (by default it is determined by the name of the application in the package.json file, meaning that an app name of 'group-control' would be automatically converted into a namespace of 'GroupControl')

Configuration Data Types

The Config module stores its config data in a Php array (which can be as many dimensions as there is necessary). However, retrieving the configuration data can be done in multiple ways. Currently the Configuration modules supports retrieving it in two different formats: Php files (that return a php array) and JSON.

To store data in a Php array, create a file with a .php extension that looks something like this:

NOTE: all of the default generated config files in an FW App look like this to start with

return array(

);

Pretty simple, right? Values in that array are stored based on how Php handles arrays. Read more about that here.

Additional Note: Php docs say you can use the short array syntax as of Php 5.4. Ensure your installation is running on Php 5.4 or later, or just keep the default array() syntax for safety.

To store data as JSON, create a file with a .json extension. Then just put raw JSON data in there, like so:

{
    "key": "value",
    "anotherkey": [
        "a",
        "b",
        "c"
    ],
    "subobject": {
        "subkey": "subvalue"
    }
}

The Config module will take it and convert it to a Php array. See the JSON tutorial linked above for more information on JSON if you need it.

IMPORTANT NOTE ABOUT JSON

If you use JSON, it is imperative that you install FW Api outside of the publicly accessible web server document root. Because JSON files contain just strings, it is possible to reach them (and get the data from them) with a browser. Php files do not have this same problem because the web-server will render them as PHP, and not output anything.