trouver_table

The trouver_table() function (base_trouver_table_dist) is declared in ecrire/base/trouver_table.php and is used to obtain a description for an SQL table. It provides a mechanism to retrieve the list of columns, keys, declared joins and some other information details.

As an overloadable function, it is used with charger_fonction:

$trouver_table = charger_fonction('trouver_table', 'base');
$desc = $trouver_table($table, $serveur);

Its parameters are:

$table: the name of the table (’spip_articles’ or ’articles’)
$serveur: optional, the name of the SQL connection, which is by default the same as that for the SPIP installation itself.

The $desc table returned is structured as follows:

array(
	'field' => array('column' => 'description'),
	'key' => array(
		'PRIMARY KEY' => 'column',
		'KEY name' => 'column' // or 'column1, column2'
	),
	'join' => array('column' => 'column'),
	'table' => 'spip_tables'
	'id_table' => $table,
	'connexion' => 'connection_name',
	'titre' => 'column_title AS titre, column_language AS lang'
);

The field key is an associative table listing all of the table’s columns and their SQL descriptions,
key is another table listing the primary and secondary keys,
join lists the columns of any joins, if declared in the descriptions of the principal or auxiliary tables
table is the actual name of the table (without prefix: if the table prefix is different from "spip", then it will be "spip_tables" that will be returned),
id_table is the given $table parameter,
connexion is the name of the connection file, if different from that of the installation,
titre is an SQL SELECT declaration indicating where is the column title or where is the column language (used amongst other things to calculate the URLs); e.g. "titre, lang", or "name AS title, '' AS lang"

This function caches the result of the analysis in order to avoid repetitive disruptive access to the SQL server. To force a recalculation of this cache, the function must be called with an empty string:

$trouver_table = charger_fonction('trouver_table', 'base');
$desc = $trouver_table('');

Note: Whenever a table is requested without the "spip" prefix, it is the name of the table with the prefix assigned for the site that will be returned (so long as the table is declared in SPIP). Requesting a "spip_tables" table will look for the real existence of that table (the prefix is not replaced by that used for the site). In the future, an option will probably be added to the trouver_table() function, as there is already for sql_showtable in order to be able to automatically modify the prefix.

Example

The creer_champs_extras() function from the "Champs Extras" plugin is used to create SQL columns described by the "ChampExtra" object instances passed ($c->table is the name of the SQL table, $c->champ is that of the column). The function returns false if a column has not been created:

function creer_champs_extras($champs) {
	// the function updates the tables in question using maj_tables() 
	// [...] 
	// It then tests if the new fields have actually been created:
	// for each column to be created, check that is actually exists now!
	$trouver_table = charger_fonction('trouver_table','base');
	$trouver_table(''); // recreate the description of the tables.
	$retour = true;
	foreach ($champs as $c){ 
		if ($table = table_objet_sql($c->table)) {
			$desc = $trouver_table($table);
			if (!isset($desc['field'][$c->champ])) {
				extras_log("Le champ extra '" . $c->champ . "' sur $table n'a pas ete cree :(", true);
				$retour = false;
			}
		} else {
			$retour = false;
		}
	}
	return $retour;
}

Author Mark Baber Published : 16/05/10 Updated : 12/05/17

Translations : English, français, Nederlands