Instanciation and prerequisites

Altitude uses PHP's PDO extension to work.
So you must ensure of its activation within the php.ini file of your server.

Both objects Listing and Infos use an instance of PDO object to communicate with database server.
This instance is created automatically, with some default options, when instantiating Listing or Infos
object. However, if you want to set specific options, it can be defined outside, then passed to the object when created.
Anyway, in order to use a connection with the database, it is imperative to define the following five constants:

By default the PDO instance is created with the option PDO::ATTR_ERRMODE on PDO::ERRMODE_EXCEPTION.
For MySQL only, the attribute PDO::ATTR_PERSISTENT is set to True, and a request "SET NAMES 'utf8'" is done
when instanciating. (see static protected function newPDO() line 426 of class "Listing").

In short, when the five constants are defined with the right connection settings for the database, you're good to use objects
Listing and Infos.

Important concepts

IDENTIFICATION: We assume that all the tables of the database contain a column named "id" (lowercase).

JOINTS :
The joints can work even with the 'MyISAM' type of table. For this reason we don't use the SQL command 'JOIN', but a quick system of
detection, defined in the configuration.
In order to retreive the joints, the constant FOREIGNKEYS_PREFIX must be defined. You can give the prefix you want.
For example:

define ("FOREIGNKEYS_PREFIX", "FK_");

Then, an array describing the relationships between columns of different tables is needed. This array must be named
$RELATIONS (uppercase). For instance:

DATES :
Altitude also needs to know which columns could contain dates, in order to reformat them with ISO 8601 format. So we must define the array
$DATE_FIELDS in the configuration, containing a list of names for the fields which may be dates. Example:

$DATE_FIELDS = Array(
"date",
"last_action",
"date_creation"
);

Next, it's possible to automatically update two columns when we save an entry. These columns correspond to the
creation date, and the last update date. For that you need to define the two contants DATE_CREATION and
LAST_UPDATE, containing the names of the wolumns to update. For instance:

Returns

ARRAY — A tuple (key, value) of the joint found. Key is the joint's alias (see important concepts),
and value is an array containing data of the joint entry found. FALSE if no joint found.

Exceptions

Here is a list of exceptions which can be thrown when using Listing object, and their signification.

Exceptions for getList()

Table '$table' doesn't exists

This means that the specified table doesn't exists in the database.
Check the parameter $table you give to getList().

Exceptions for addFilter()

Listing::addFilter() : Missing column name for filter

This means that the column name for filter is missing.
Choose a column in the current table, and give its name for parameter $filter_key of addFilter().

Listing::addFilter() : Missing value for filter search

This means that the value to search in filter for the specified column in current table is missing.
Give a value for parameter $filter_val of addFilter().

Exceptions for addFilterRaw()

Listing::addFilterRaw() : Missing column name for filter

This means that the column name for filter is missing.
Choose a column in the current table, and give its name for parameter $filter_key of addFilterRaw().

Listing::addFilterRaw() : Missing value for filter search

This means that the value to search in filter for the specified column in current table is missing.
Give a value for parameter $filter_val of addFilterRaw().

Exceptions for reindexList()

Listing::reindexList() : '$wantedIndex' is not an unique index for table '$this->table'

This means that the choosen column for reindexation has no unique index. It may overwrite some values in the
returned array, so Altitude throw an exception to avoid that. Choose a column which have a unique index (like 'ID'
for instance) and give its name for parameter $wantedIndex of reindexList().

Other exceptions may appear, they are probably thrown by PDO himself.

L'objet "INFOS"

Below are the properties and methods specific to the object Infos:

Properties

The class Infos inherits properties and methods of the class Listing, so it's
useless to remind them here.

$data

ARRAY — Array containing data of the entry found.

$loaded

BOOLEAN — TRUE if database has already been read (to check before 'update' or 'insert' -> see method save()).

Methods

__construct()

GETTING content of an entry of an SQL table: Initialization

__construct(
STRING $table, OBJECT $pdoInstance = false)

Parameters

STRING

$table

SQL table name

OBJECT

$pdoInstance

Predefined PDO instance (optional)

setTable()

Definition of the table where to find / add an entry.

setTable(
STRING $table)

Parameters

STRING

$table

SQL table name

getTable()

Get the current table name.

getTable() : STRING

Returns

STRING — Name of the current table.

loadInfos()

Load an entry according to a basic filter. Throws an error if several entries found (and not only one).

Exceptions for loadInfos()

This means that more than one entry were found for the search. The 'Infos' object have been designed to work on a precise
entry of a table, it throw an exception when the result is multiple.
Choose a more precise filtering to find the entry, changing the parameters $filtreKey and $filtreVal
for loadInfos().

Exceptions for getInfo()

Infos::getInfo() : Missing column name

This means that the column name is missing, and it's needed to get a specific value of the current entry.
Choose a column in the current entry's table, and give its name to parameter $column of getInfo().

Exceptions for setManyInfos()

Infos::setManyInfos() : 'newInfos' must be an array ($type found)

This means that the variable type of parameter $newInfos is not an array. To modify the current entry with
method setManyInfos(), you must give an associative array, which contain the values to change. Each array's key
being the column name, and its value being the new value for the column.

When parameter $checkMissing of setManyInfos() is True, the method will perform a verficiation
on the list of the $newInfos array's keys to check if some are missing.
This exception is thrown when some columns are missing in the array, and give a list of those missing columns.

Exceptions for save()

Infos::save() : Duplicate entry for `$key`="$val" in table '$table'.

This means that one of the values of the entry to be saved already exists in the database, because of a column that has a unique index.
Change the new value of the entry before calling save().

Infos::save() : table '$table' -> $msg.

Infos::save() : '.$error

These two exceptions are thrown when PDO encounter an error. Detail of this error is specified in the message.

Exceptions for addNewCol()

Infos::addNewCol() : Missing table name

This means that the table's name is missing to add a column into.

Infos::addNewCol() : Missing column name

This means that the column's name to add in table is missing.

Infos::addNewCol() : This column already exists

This means that the column is already present in the table. Choose another name for the column.

Exceptions for removeCol()

Infos::removeCol() : SQLite3 limitation: you can't drop a column from a table with 'ALTER TABLE' statement.

This exception is thrown when PDO driver 'sqlite' is in use. Because of a limitation in ALTER functions in SQLite,
DROP being unavailable, this method is at the moment unusable. You'll have to do this operation "by hand" on and SQLite console.

Other exceptions may appear, they are probably thrown by PDO himself.

Licence

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.