Overview

INI files are a common format for configuration data. They are used extensively throughout Sitellite, as they are very efficient to parse, easy to write to, and much more readable than the equivalent XML file. They also have the benefit of being easily made "private" which XML files do not, which I'll explain below.

Compared to simply using define() statements in a PHP include script, INI files are easier to read and write in a programmatic fashion (via Sitellite's ini_parse() and ini_write() functions), whereas PHP's syntax is much more varied, which makes it more of a challenge to read and write reliably for the purposes of editing it via an HTML form.

An INI file takes on of two forms, either a simple key/value list, or a series of "blocks" that contain key/value lists. These are akin to one-dimensional and two-dimensional associative arrays in PHP, which is how they are represented when returned from the ini_parse() function.

Syntax

Key/value pairs are each written on a single line, and are separated by the equal sign (=).

Block names are surrounded by square braces, for example: [Block]. If blocks are used, no key/value pairs may appear before the first block.

Comments can be added to the file via the semi-colon (;) followed by the comment text. Comments can appear on a line unto themselves, or at the end of a key/value pair line.

Blank lines are ignored.

Most non-alphanumeric characters are not allowed in the keys, values, or block names. A value must be enclosed in double-quotes ("") if it contains invalid characters. Invalid characters will generate a parsing error.

Characters which are allowed include:

• Forward-slash (/)
• Colon (:)
• Hyphen (-)
• Underscore (_)
• ...

Security

In Sitellite, all INI files end in the .php suffix, and many of them have special lines included as the first and last line of the file contents, which protect them from being viewed through ordinary browser requests. These are:

; <?php /*

; INI data...

; */ ?>

This encloses the entire file in a PHP comment tag, which will then be stripped out, so that a request for an INI file from within a browser will yield only the initial semi-colon as output and nothing more.

Types of INI files used in Sitellite

Global:

• inc/conf/config.ini.php
• inc/conf/cache.php
• inc/html/*/modes.php
• inc/lang/languages.php

In Apps:

• conf/config.ini.php
• lang/languages.php
• boxes/access.php
• boxes/boxname/settings.php
• forms/access.php
• forms/formname/settings.php

Examples

A simple example:

; This is a simple example.

name = Lux
email = "lux@simian.ca"

An example with blocks and security features in place:

; <?php /*

[Form]

error_mode = all
title = Contact Us
message = Please use this form to contact us.

[name]

type = text
alt = Your Name
rule 1 = not empty, You must enter your name.

[email]

type = text
alt = Email Address
rule 1 = "contains '@', Your email address is invalid."

[comments]

type = textarea
alt = Comments
labelPosition = left

[submit_button]

type = submit
setValues = Send

; */ ?>