ACICRUD

Automatic CodeIgniter Create Read Update Delete

ACICRUD, est une librairie pour CodeIgniter permettant de s’affranchir de la création de modèles dans la plupart des cas.

En effet, ACICRUD fournit une collection de méthodes CRUD permettant de sélectionner, insérer, modifier, supprimer des éléments en base de données ainsi que d’autres fonctions utiles au développement d’un site web.

Concrètement, ACICRUD permet de s’affranchir du développement des méthodes classiques d’un modèle pour CodeIgniter. Depuis la version 1.1, Acicrud supporte la connexion multiple à plusieurs bases de données.

Licence

ACICRUD by Samuel Sanchez est mis à disposition selon les termes de la licence Creative Commons Paternité-Pas d’Utilisation Commerciale-Partage des Conditions Initiales à l’Identique 3.0 France.
Les autorisations au-delà du champ de cette licence peuvent être obtenues à https://nukium.com/.

Installation

ACICRUD nécessite PHP 5 ainsi que CodeIgniter 1.6.3 minimum (non testé sous version antérieure). La librairie est également pleinement compatible avec CodeIgniter 2.0.x.

L’installation de la librairie ACICRUD est classique, en effet elle s’installe comme n’importe qu’elle librairie CodeIgniter :

Téléchargez l’archive
Décompressez le fichier Acicrud.php dans le répertoire libraries de votre application (/application/libraries)
Ajoutez Acicrud à la liste des librairies auto-chargées via l’autoloader (facultatif)
C’est terminé ! Vos modèles peuvent désormais étendre la classe Acicrud.

Principe de fonctionnement

ACICRUD peux être vu comme un « meta modèle » pour CodeIgniter, en effet la librairie hérite de la classe Model de CodeIgniter. C’est pourquoi vos modèles ne devront plus hériter de la classe Model mais de la classe Acicrud.

Attention, pour utiliser ACICURD, vos tables SQL doivent obligatoirement être en première forme normale.

Description des méthodes

Voici une description (en cours de rédaction) des principales méthodes de la classe. La plupart de ces dernières lèvent des exceptions en cas d’erreur.

Object read(mixed $id) : Lis une ligne en base de donnée identifiée par son identifiant, retourne un objet fidèle à la ligne. Depuis la version 1.1, cette méthode accepte également un tableau associatif à la place d’un identifiant numérique permettant ainsi de lire une seule entrée avec une clause WHERE personnalisée.
Object readLast() : Tente de lire la dernière ligne en base de données et retourne un objet fidèle à la ligne.
int create(Object $o) : Créée une ligne en base de données à partir d’un objet fidèle à la ligne. Il n’est pas nécessaire de définir tous les attributs de la table dans l’Objet. Retourne l’identifiant numérique de la ligne insérée.
void delete(int $id) : Supprime une ligne en base de données à partir de son identifiant.
void update(Object $o) : Met à jour une ligne en base de données à partir de son objet fidèle, peux être appelé après read() sans fournir la valeur de l’identifiant (clé primaire) dans l’objet.
mixed getAll(int $limit = null, array $order = null, array $where = null) : Retourne une collection de lignes issues de la base de données. Peut optionellement limiter le nombre de résultats et les trier sur un champ et une direction spécifique. Effectue également les clauses WHERE si $where est fournit.
mixed get(mixed $what, int $id) : Retourne un champ identifié par son nom ainsi que par l’id de l’élément en base de données.
mixed getBy(mixed $by, mixed $value) : Retourne les éléments possédant le champ $by à la valeur $value. Cette méthode permet par exemple de lire des entrées sur un champ autre que la clé primaire.
mixed getter(mixed $what) : Accesseur classique, permet de récupérer la valeur d’un champ après avoir read() un élément.
int countAll(array $where) : Retourne le nombre de lignes de la table. Un tableau associatif peut être fournit à la méthode permettant ainsi d’utiliser une clause WHERE personnalisée.
int lastId() : Retourne l’id du dernier enregistrement effectué par la base de données.
int getMaxId() : Retourne la plus grande valeur de la clé primaire utilisée par la table ou 0 si la table est vide.
void checkId(int $id) : Vérifie que la valeur d’une clé primaire existe bien en base de données. Lève une exception CHECK_ID_TABLE_FAILLURE en cas d’échec.
Collection result() : Exécute une requête Active Record et retourne une collection d’Objets résultats.
Object row() : Exécute une requête Active Record et retourne un d’Objet résultat.
Void debug(Boolean $executeQuery = true, Boolean $die = true) : Stoppe l’exécution du script et affiche la dernière requête effectuée par la base de données.

Téléchargement / Download

La librairie est désormais en version stable, elle est actuellement utilisée en production sur plus d’une quinzaine d’applications.

La compatibilité ascendante étant assurée, pour mettre à jour Acicrud à partir d’une ancienne version, il vous suffit de remplacer le fichier Acicrud.php de votre application par la nouvelle version.

2011-03-21 : Acicrud-b6602b8889da7f18519a07678a5c935a4b118371.zip (v1.2)
2010-05-05 : Acicrud-0c28279ee917f5c37007072c090f2bbfb8795e62.zip (v1.1)
2009-12-30 : Acicrud-86ef21a05a4c9697ae01fb9b17736ef24704cbf8.zip (v1.0)
2009-05-17 : Acicrud-81c77e249d3852ab7e04580955410e61c89d7d34.zip
2009-05-08 : Acicrud-5b2f33362f587cc3c253846bf776dc409ee8f158.zip

Feedback

N’hésitez pas à poster vos impressions, vos remarques, ou vos demandes d’ajout de fonctionnalités.

Installation de la librairie ACICRUD et création d’un modèle

Dans ce premier tutoriel sur l’utilisation de la librairie ACICRUD pour CodeIgniter nous allons voir comment installer la librairie dans votre application et comment créer un modèle utilisant la librairie.

Installation d’ACICRUD

L’installation d’ACICRUD est relativement classique, téléchargez la dernière version de la librairie, décompressez l’archive et placez le fichier Acicrud.php dans le répertoire system/application/libraries.

Je vous conseille d’autocharger ACICURD ainsi que la librairie de base de données afin de ne plus s’en préoccuper, pour cela rajouter dans le fichier system/application/config/autoload.php

$autoload['libraries'] = array('database', 'acicrud');

À partir de là, la librairie est installée et sera disponible dans l’ensemble de votre application.

Création d’un modèle

La création d’un modèle est relativement simple, il suffit de faire hériter le modèle de la classe Acicrud au lieu de Model.

* @copyright © 2008-2009 Samuel Sanchez - All rights reserved / Tous droits réservés
* @tutorial Set the class name and the constructor method name to your model name, then rename 'table_name' into your sql table name.
*
*/
class Exemple extends Acicrud {

	//CONSTRUCTOR
	public function Exemple()
	{
		parent::Acicrud('table_name');
	}

	//CUSTOM METHODS

}

Il suffit d’indiquer dans le constructeur le nom de la table que le modèle doit utiliser. Le modèle pourra bien-sûr accéder à n’importe qu’elle table de la base de données dans une custom method.

Chargement du modèle

Il ne reste plus qu’à charger le modèle dans votre application :

$this>load>model('exemple');

Support and feedback are both available in English and in French.

Lire facilement des données avec Acicrud

Dans ce deuxième tutoriel sur l’utilisation de la librairie Acicrud nous allons voir comment lire des données depuis la base de données.

Comme précédemment expliqué, le principe d’Acicrud est d’ajouter une couche applicative objet dans les modèles afin de générer des objets fidèles au modèle de données représenté par la base de données.

Concrètement, Acicrud permet d’interagir avec la base de données en manipulant directement des objets PHP.

Prérequis

Nous supposerons utiliser le modèle exemple précédemment créé.

Nous supposerons également que notre table SQL est bâtie sur le modèle de donnée suivant :

Exemple { idExemple, title, description, date }

Lecture d’une ligne en base de données

La lecture d’une ligne se fait à partir de son identifiant (clé primaire) ou à partir d’un tableau associatif représentant la clause WHERE à utiliser (attention read est volontairement prévu pour lire une et une seule entrée), la méthode read() retourne un objet fidèle à la ligne en base de données :

$this->load>model('exemple');

try {
	$o = $this>exemple>read(1); //Primary key id
} catch(Exception $e) {
	echo "Wrong ID";
}

var_dump($o);

//Produces
/*
object(stdClass) (4) {
  ["idExemple"]=>
  string(2) "1"
  ["title"]=>
  string(8) "title..."
  ["description"]=>
  string(15) "description..."
  ["date"]=>
  string(19) "2009-04-30 21:00:00"
}
*/

try {
	//Associative array method produces a custom WHERE clause. Be careful, read is intended to read one unique entry.
	$o = $this>exemple>read(array('title' => 'title...')); 
} catch(Exception $e) {
	echo "No result found.";
}

var_dump($o);

//Produces
/*
object(stdClass) (4) {
  ["idExemple"]=>
  string(2) "1"
  ["title"]=>
  string(8) "title..."
  ["description"]=>
  string(15) "description..."
  ["date"]=>
  string(19) "2009-04-30 21:00:00"
}
*/

L’objet $o représente physiquement l’élément lu en base de données. Ses attributs portent les noms de champs et ses valeurs sont les données de la ligne.

Lecture de toutes les lignes d’une table en base de données

Il est très fréquent de devoir récupérer l’ensemble des données d’une table. Acicrud fournit une méthode pour cela s’appelant getAll().

Cette méthode prend trois paramètres optionnels qui sont $limit, $order et $where.

$limit permet d’effectuer un LIMIT SQL afin de limiter le nombre de lignes retournées par la requête, il suffit de passer un nombre.

$order est un tableau associatif qui permet de trier les données, par exemple pour trier par title ascendant, il faudra passer un tableau associatif :

array(‘title’ => ‘ASC’).

Il est également possible d’indiquer plusieurs tris : array(‘date’ => ‘DESC’, ‘title’ => ‘ASC’ ).

Le paramètre $where permet d’ajouter une clause WHERE personnalisée, il suffit de passer un tableau indexé de la même manière qu’avec la librairie Active Record de CodeIgniter.

La métode getAll() va retourner un tableau d’objets fidèles qui peuvent par exemple être facilement passés à une vue pour affichage.

$this->load>model('exemple');

try {
	
	//Retrieve an array of objects, this array can be passed to a view for displaying data
	foreach($this>exemple>getAll(10, array('date' => 'DESC')) as $row) {
	
		var_dump($row); 
		
		//Produces
		/*
		object(stdClass) (4) {
		  ["idExemple"]=>
		  string(2) "the id"
		  ["title"]=>
		  string(8) "the title"
		  ["description"]=>
		  string(15) "the description"
		  ["date"]=>
		  string(19) "the date"
		}
		*/
	}
	
} catch(Exception $e) {
	echo $e>getMessage();
}

Insérer des données avec Acicrud

Dans ce tutoriel, nous allons voir comment créer une ligne en base de données grâce à la fonction create() de la librairie ACICRUD pour CodeIgniter.

Pour cela, nous allons imaginer que nous disposons d’une page HTML contenant un formulaire permettant de renseigner le titre ainsi que la description de notre exemple.

Pour rappel : Exemple { idExemple, title, description, date }

Nous allons donc créer le code permettant de récupérer les données du formulaire et de créer la ligne en base de données dans un contrôleur CodeIgniter. Notez qu’il n’est pas nécessaire de définir l’objet temporaire $o ni de préciser qu’il possède un attribut représentant la clé primaire. ACICRUD n’a besoin que des données à insérer pour exécuter la fonction create().

	
class Form extends Controller {
		
	public function index()
	{	
		//Form_validation stuff
		$this--->load->library('form_validation');
				
		$this->form_validation->set_rules('title', 'Title', 'required');
		$this->form_validation->set_rules('description', 'Description', 'required');
	
		if ($this->form_validation->run() == FALSE)
		{
			$this->load->view('myform');
		}
		else
		{
			//Validation success
			$this->load->model('exemple');
				
			$o->title = $this->input->post('title');
			$o->description = $this->input->post('description');
			$o->date = date("Y-m-d H:i:s");
				
			//Creating the row in the database
			$this->exemple->create($o);
		}
	}
}

Supprimer des données avec ACICRUD

Dans ce quatrième tutoriel d’utilisation de la librairie ACICURD pour CodeIgniter, nous verrons tout d’abord comment supprimer une ligne en base de données, puis comment supprimer un ensemble de données grâce à la méthode delete().

Pour supprimer un élement, nous allons simplement lire une ligne identifiée par son id (en utilisant la méthode read() afin que les processus de vérification de l’existence de l’identifiant soient exécutés) puis appliquer sur l’instance de notre modèle la méthode delete().

Pour cela voici le code d’un contrôleur CodeIgniter qui possède une méthode deleteElement($id) prenant comme paramètre d’entrée l’identifiant de la ligne à supprimer :

class Element extends Controller {

	public function __construct()
	{
		parent::__construct();	
		$this--->load->model('elementModel');
	}
	
	public function deleteElement($id)
	{
		try {
			
			//Try to read the row identified by $id
			$element = $this->elementModel->read($id);
			
			//Delete the database row
			$this->elementModel->delete($element->id);
			
		} catch(Exception $e) {
			
			die('Wrong id');
	
		}
	}
	
}

La suppression de plusieurs lignes en base de données est également possible avec la méthode delete(), pour cela il suffit de fournir à la méthode un tableau associatif représentant les données Active Record de la clause WHERE à utiliser pour la suppression.

L’exemple ci-dessous supprimera les données pour lesquelles le champ is_valid est différent de 1.

class Element extends Controller {

	public function __construct()
	{
		parent::__construct();	
		$this--->load->model('elementModel');
	}
	
	public function deleteInvalidRows()
	{
		//Delete rows via a custom WHERE clause
		$this->elementModel->delete(array( 'is_valid !=' => 1) );

	}
	
}

Tutoriel Acicrud : ajouter des custom methods à vos modèles

Nous allons voir comment définir de nouvelles méthodes dans les modèles utilisant ACICRUD et comment profiter de certaines méthodes de la librairie.

Création d’une méthode spécifique

Imaginons que vous désiriez sélectionner un champ username dans une table user à partir de l’identifiant de l’utilisateur id. Nous allons pour cela ajouter une nouvelle méthode dans notre modèle ayant exactement le fonctionnement que nous désirons et s’appuyant sur la méthode $this->row() qui exécute la requête Active Record et retourne un objet résultat.

Notez qu’il serait également possible d’utiliser la méthode getAll() d’ACICRUD pour arriver à ce résultat.

Voici le code du fichier user.php à placer dans le répertoire models :

class User extends Acicrud {
 
	//CONSTRUCTOR
	public function __construct()
	{
		parent::__construct('user');
	}

	//CUSTOM METHODS
	
	/**
	 * Return the username of an user identified by his id
	 *
	 * @param int $id
	 * @return Object
	 */
	public function get_username($id = null) {
		
		try {
			
			// Checking if $id is a valid primary key value
			$this--->checkId($id);
			
			// Building the query
			$this->db->select('username')->from($this->table)->where($this->key, $id);
			
			// Returning the result
			return $this->row();		
					
		} catch(Exception $e) {
			
			throw($e); // Throws the ACICRUD's exception
			
		}
	}
 
}

Il vous est donc tout à fait possible d’ajouter vos propres comportements au sein d’un modèle héritant de la librairie ACICRUD. Notez que dans cet exemple, la méthode s’appuie également sur le système d’exceptions géré par ACICRUD. Je vous conseille donc d’inclure l’appel de la méthode get_username dans votre contrôleur au sein d’un bloc try/catch.

Utiliser plusieurs bases de données

Depuis la version 1.1, Acicrud est capable de se connecter à n’importe qu’elle base de données configurée dans le fichier system/application/database.php.

Veuillez noter que cette fonctionnalité est totalement facultative et que la librairie travaillera avec votre base de données par défaut si vous ne définissez aucune base de travail dans votre modèle.

Afin d’utiliser une base de données différente de votre base de données par défaut, il suffit de spécifier le group à utiliser au constructeur d’ACICRUD. Dans notre exemple il s’agira d’une base de données nommée « rescue_database« .

class Exemple_Model extends Acicrud { //CONSTRUCTOR public function __construct() { parent::__construct('table_name', 'rescue_database'); } //CUSTOM METHODS }

Résolution d’erreurs

CodeIgniter & Acicrud : Erreur ‘DB_driver.php on line 837’

Il s’agit ici de parler d’une erreur très spécifique qui peut survenir avec la version 2.0.2 de CodeIgniter lors de l’utilisation d’Acicrud.

Le cas de figure est le suivant, vous tentez de lire une entrée en base de données avec la méthode read($primary_key) (par exemple) et une erreur fatale est levée :

Call to a member function result_array() on a non-object in /system/database/DB_driver.php on line 837

La cause probable de cette erreur est une mauvaise configuration au niveau de la base de données ou au niveau d’Acicrud.

Voici une procédure de vérification qui vous permettra très certainement de corriger l’erreur :

Si vous utilisez un préfixe de table, vous devez l’indiquer dans /application/config/database.php dans $db[‘default’][‘dbprefix’], assurez-vous d’avoir spécifié l’underscore final, par exemple « mon_prefixe_ ».
Vérifiez ensuite que le modèle incriminé instancie bien la librairie Acicrud avec le nom de la table liée sans le préfixe et que le nom de la table est correct. Par exemple, pour une table nommée « my_prefix_users », l’appel du constructeur doit être le suivant : parent::__construct(‘users’);
Dernière possibilité, vérifiez que la requête SQL générée par le driver de CodeIgniter est correcte, pour cela ouvrez /system/database/DB_driver.php et faîtes un echo de $sql en ligne 833 juste avant le $query = $this->query($sql);

Changelog

The changelog of the 86ef21a05a4c9697ae01fb9b17736ef24704cbf8 is available below :

readLast() method added : try to read the latest entry in the table.
getMaxId() method added : return the largest currently used ID in the table or 0 if the table is empty.
create() now return the inserted row’s id.
CI instance added ($this>CI). Can be useful to load Models inside an Acicrud Model.
_where() method added. getAll() now accept a third parameter to manage where clauses.
delete() now accept an array instead of an int to manage where clauses.
__toString() magical method added.

The changelog of the 0c28279ee917f5c37007072c090f2bbfb8795e62 (v 1.1) is available below :

Fixed a bug in the get($what, $id) method that died instead of throwing the Exception.
Fixed : the last inserted ID is now correctly updated when several create() are called.
Multi database support added.
An associative array can now be given to the read() method to read an entry with a custon WHERE clause.
The model creation code have been optimized (see the new exemple tutorial).
An associative array can now be given to the countAll() method to count entries with a custon WHERE clause.
The deprecated method getFrenchDate() have been definitively removed.
The getBy($by, $value) method have been added (see the API documentation).

The changelog of the b6602b8889da7f18519a07678a5c935a4b118371 (v 1.2) is available below :

Added support for CodeIgniter 2.0.x