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

.. code-block:: php

	Application::set('setting_name', 'setting_value');
	
Using the :doc:`install/webinstall`, 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 :doc:`install/webinstall`:

.. code-block:: php

	<?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 [#f1]_.
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**:

.. code-block:: php

	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:

.. code::

	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.


.. rubric:: Footnotes

.. [#f1] 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).
