The configuration file

The configuration file allows you to specify how PiAnoS connects to the database, and change a few settings to enable/disable some features and/or alter how some work.

The configuration file is named settings-local.php and lives in the backend/ directory. Note that this directory is not directly visible to the clients, thanks to a .htaccess file.

All options have defaults that are defined in Pianos4.php, but you are not supposed to edit this file (in fact, if you do, you will not be able to upgrade PiAnoS because this would overwrite your changes). Instead, open settings-local.php and add a line of the form

Application::set('setting_name', 'setting_value');

Using the Web Installer, a configuration file was created. It contains the database parameters and a couple of other site-specific settings. You can change or remove these, or add new settings at any time. Those changes take immediate effect.

For the record, here is a simple configuration file produced by the Web Installer:

<?php
function setLocalSettings()
{
        // Database connection
        Application::set('db_host', 'localhost');
        Application::set('db_port', '5432');
        Application::set('db_name', 'pianos');
        Application::set('db_user', 'pianos');
        Application::set('db_password', '<password-goes-here>');

        // Misc settings
        Application::set('cookie_params', '/');
        Application::set('session_timeout', 3600);
        Application::set('backend_app_settings', array('hasSearchBox' => true));

}
?>

Settings reference

Following is the reference list of all settings that you can safely modify. There are other settings, defined in Pianos4.php, but they are considered internal settings for the time being.

Setting	Default	Explanation
db_host	‘localhost’	Hostname to connect to
db_port	5432	Port
db_name	‘pianos4’	Name of the database
db_user	‘pianos’	Username of the database role
db_password	‘pianos’	Password for this role
cookie_params	NULL	Session cookie parameters. While these can be left to NULL on development servers production installation should set them appropriately. There is a security risk if they are not set: 2 installations on the same server and/or domain will potentially use the same cookie (e.g. log on as ‘admin’ on /pianos-a, go to /pianos-b and you are still logged on as admin!) This can be set to: NULL (development only): no session cookie parameters are set a string: the base path of the installation (e.g. /pianos4) an array of 2 strings: the base path and the domain (e.g. array('/pianos4','.unil.ch'))
session_lifetime	NULL	Session timeout. If not set (i.e. set to NULL), let PHP manage the session lifetime (set through the session.gc_maxlifetime parameter). If set to a value, (number of seconds), overrides the session lifetime locally, using session variables and access timestamps. Since the session might be let unmodified for a long time while the user is working, setting this is a preferred method over configuring PHP to manage the session lifetime.
shibboleth_login	false	Use Shibboleth login mechanism. Set to false or NULL to disable. Set to an array to enable. The detailed structure of the expected array is given in the next table.
use_minified_pianos4	false	Minified scripts. Set these to the name of the minified versions of PiAnoS 4 (main and backend) javascript files. Note that in released versions this needs to be defined in your local configuration, and point to the appropriate .min.js file 1.
use_minified_pianos4_backend	false	Same as above for the backend javascript file.
user_manual_url	NULL	URL to the user manual. If left to NULL, no link to the user manual will be shown. Otherwise, it will appear under the help menu.
imagick	NULL	Some features require ImageMagick, which can be provided by PHP itself, or by external scripts (e.g. convert[.exe], mogrify[.exe], etc.). If this variable is unset, or set to anything else but a string, it means that PHP Imagick is to be used. If set to a string, it is the base path to the utilities of ImageMagick (e.g. c:\\program files\\imagemagick)
convert_images	false	Convert image types before storage. This is needed e.g. because although PiAnoS can accept TIFFs on upload, some browsers (Firefox!) will not accept them (but IE will). Set to false to disable image conversion. Set to an associative array to enable - keys are “from” mimetypes, and values are “to” extensions. E.g. to enable on-the-fly conversion for TIFFs to PNGs, set to array('image/tiff'=>'png'). Note that this feature requires ImageMagick PHP extension (see the ‘imagick’ option above) Implementation note: the values will be used as argument to ImageMagick::setImageFormat
archive_results	false	There exist the possibility to log ALL saved results to a dedicated table named result_history. By default (set to false), this table will not be used. If set to true, results will be continuously inserted into the table. It is your responsibility to manage this table (delete rows, etc.)

Single sign-on using Shibboleth

PiAnoS supports a primitive form of single sign-on. Because UNIL uses Shibboleth, an adapter has been written for PiAnoS so our students can log-in using their institutional credentials.

Supporting other external authentication mechanism is feasible but requires modifying the source code.

Settings

Key	Value
url	URL to the shibboleth-protected area. The file pointed to must perform the appropriate redirect once the login has been performed (i.e. returning to index.php). Note: use ‘shibboleth-simulate.php’ to simulate a login on a development machine that is not Shibboleth-enabled.
login_prompt	title of the login form e.g. ‘Students login with Shibboleth’
login_image	URL to the image to display in the login box itself. Do not set or set to NULL when no image should be displayed
login_text	text inside the login form. Do not set or set to NULL when no text should be displayed
username	the $_SERVER field containing the username
display_name	array of 2 $_SERVER fields containing the first and last names
email	the $_SERVER field containing the email
groups	array of 3-tuples: ($_SERVER field, regexp, target group name). If this is set, users will be accepted only if the specified field matches the regexp, and they will be assigned the target group.
return	the URL to return to after successfull authentication

Example:

Application::set('shibboleth_login',array(
        'login_text' => 'Follow the link to use your ORG crendentials',
        'login_prompt' => 'ORG student login',
        'login_image' => 'shibboleth_buttonflat.gif',
        'url' => 'shibboleth_auth/',
        'username' => 'Shib-SwissEP-UniqueID',
        'display_name' => array('Shib-InetOrgPerson-givenName','Shib-Person-surname'),
        'email' => 'Shib-InetOrgPerson-mail',
        'groups' => array(
                array('Shib-EP-Entitlement', '/http:\\/\\/groups.org.ch\\/etu-bachelor/', 'Bachelor 2012'),
                array('Shib-EP-Entitlement', '/http:\\/\\/groups.org.ch\\/etu-master/', 'Master 2012'),
        ),
        'return' => '../index.php',
));

Note the weird syntax of the groups patterns - this is because our organization uses URLs to define subgroups, which uses slashes /, and those need to be escaped to be recognized by PHP.

Apache configuration

For all of the above to be effective, due to how Shibboleth works, we need to:

• create a subdirectory (sibling of backend, js, etc.) named shibboleth_auth

• tell Apache that shibboleth_auth is protected by Shibboleth using a .htaccess file:

Order allow,deny
Allow from all

AuthType shibboleth
ShibRequireSession On
ShibRedirectToSSL 443
require valid-user

And of course, all of this only works if Shibboleth is set-up properly on your system, and already integrated into Apache.

The apache rewrite module shall be enabled to activate the use of the .htaccess file; if not, the .htaccess file will not be loaded and the shibboleth authentication will not be triggered. In this situation, the shibboleth_auth/index.php page will try to load without triggering the AuthType shibboleth access restribtion, and will not be able to find the shibboleth related $_SERVER variables.

Footnotes

1

These settings are mandatory in released versions because you would otherwise need the debugging versions of individual files (that you don’t have), that are grouped together in the .min.js files (that you do have).