simply put: Configuring Apps - Covers setting up your app, and dealing with configuration.

Config

PHP ON PIE uses JSON for its configuration system. The config file for your app is APP_DIR/config/app.json. All configuration fields are namespaced by the module that introduced that configuration field. If you look at the app.json file, everything is under "pie" for that reason.

After loading your app's general configuration file, PIE loads the APP_DIR/local/app.json file. We will make use of this later in the guide.

Now let's give our app a unique name. You do this by setting the pie/app config field. It is a good idea to use short names that can work as variable names, such as "youMixer" or "dating". (Cool fact: in the future, you'll be able to package your work into a plugin with that name.)

At run-time...

You can access the config fields dynamically from your code. To set the foo/bar field, you would do:

Pie_Config::set('foo', 'bar', $new_value)

To get the value of a field such as foo/bar/baz field, you would write:

$value = Pie_Config::get('foo', 'bar', 'baz', $default_value)

If the field was not defined in the config (not even null), then the $default_value would be returned.
If you expect the field to be there, you should instead write:

$value = Pie_Config::expect('foo', 'bar', 'baz')

and an exeption would be thrown if the field was undefined.

If you want to, you can load additional config files at run-time with

Pie_Config::load($relative_filename)

It can be useful to store string literals and other such things in these files.

Loading Config Files

PHP ON PIE loads config files in the following order:

1. PIE_DIR/config/pie.json — default PIE settings
2. Then, PIE merges your app's config and local config (see next two items), and looks at the pie/plugins array. It loads PLUGIN_DIR/config/plugin.json for every plugin named there.
3. APP_DIR/config/app.json — your app's config
4. APP_DIR/local/app.json — specific to local machine
5. Finally, PIE loads any config files that were named in the pie/configFiles

Notice that PIE never scans any directories for config files. This is for efficiency reasons: searching directories on every request is slow.

When a config file is loaded, its contents are merged over the previously loaded config. For example, if the previously loaded config was:

{
	"a": "something",
	"b": "something too",
	"c": { 
		"k1": 1, 
		"k2": 2 
	},
	"d": { 
		"k1": { "associative": "array" }, 
		"k2": ["a", "b", "c"] 
	}
}

and we loaded the following config file:

{
	"a": "something else",
	"c": { 
		"k1": "replaces 1", 
		"k3": "new value",
	},
	"d": { 
		"k1": "just a string", 
		"k2": ["a", "b", "z"] 
	}
}

then the resulting config would be:

{
	"a": "something else",
	"b": "something too",
	"c": { 
		"k1": "replaces 1", 
		"k2": 2,
		"k3": "new value",
	},
	"d": { 
		"k1": "just a string", 
		"k2": ["a", "b", "c", "a", "b", "z"] 
	}
}

In short, scalar values replace whatever is there, associative arrays merge over it (on all levels), and regular arrays append to it.

Why JSON?

PIE is designed to be very efficient and work with built-in PHP functions. The format for config files was chosen to be safe (no executable code), able to represent an arbitrary hierarchy of data, readable by humans, and easily encoded and decoded with PHP. That ruled out other possible formats such as YAML. Also, since JSON is already being used to communicate with Javascript in other parts of PIE, it made sense to keep the number of languages you have to know down to a minimum: PHP and JSON.

You can, of course, use another format for config files if you wish. One of the ways PIE extends itself is with event hooks. All you have to do is add a hook before the "pie/parameters/load" event, but you'll have to read about events first.