Cette classe va vous permettre de gérer de façon extrêmement simple , vos documents enregistrés en base couchDB. Pour plus d'infos sur ce que est couchDB , je vous invite à visiter ce site : http://couchdb.apache.org/
Comme à mon habitude , cette librairie est entièrement indépendante , vous pouvez donc l'utiliser sans le framework ou autre fichier distribué par le fw-OSCAR.
Commençons par inclure notre librairie:
require_once 'oscar/Oscar_couchDB.php';
Puis il ne reste qu'à récupérer l'instance :
$Ocdb = Oscar_couchDB::getInstance();
Le constructeur paramètre par défaut l'adresse ip host et le port avec les valeurs suivantes :
Ils sont modifiables grace aux accesseurs suivants :
$Ocdb->set_host('10.0.0.220'); $Ocdb->set_port(5999);
Voici la liste de méthodes que fournis à l'heure actuelle cette librairie :
Cette méthode vous permet de créer une nouvelle base de données , ou un nouveau document
mixed add($database, $id=null, $data=null)
Pour créer une nouvelle base , il suffit de ne pas remseigner $id et $data
Création d'une nouvelle base :
$Ocdb->add("mabase"); /* Retourne * * bool(true) */
Création d'un nouveau document
$doc = array("NOM"=>"Document A","TYPE"=>"Doc"); $Ocdb->add("mabase","0001",$doc); /* Retourne * * array(3) { ["ok"]=> bool(true) ["id"]=> string(4) "0001" ["rev"]=> string(34) "1-ed22a3bbcaa8b91dfbb08637f912a95c" } */ //un deuxième $Ocdb->add("mabase","0002",$doc);
Cette méthode permet de récupérer toutes les versions d'un document , car avec couchDB , la modification d'un document n'écrase pas l'ancienne version , mais créé une révision , jusqu'à ce que la base soit compactè .
array all_revs($database,$id)
- $database correspond au nom de la base de données dans laquelle nous travaillons - $id identifiant unique du document
Si notre document avait été modifié 2 fois:
$Ocdb->all_revs("mabase", "0001"); /* Retourne * * array(2) { ["actuel"]=> string(34) "2-1d921b35cfd263234e7b7287d69f19bb" * ["liste"]=> array(2) { * [0]=> array(2) { * ["rev"]=> string(34) "2-1d921b35cfd263234e7b7287d69f19bb" * ["status"]=> string(9) "available" } * [1]=> array(2) { * ["rev"]=> string(34) "1-ed22a3bbcaa8b91dfbb08637f912a95c" * ["status"]=> string(9) "available" } * } * } */
actuel correspond à la révision courante .
Comme expliqué plus haut , la modification de document ne supprime pas l'ancienne version , couchDB crée donc une révision , pour écraser toutes ces révisions , il nous faut compacter la base, pour se faire , la méthode ci-dessous s'en occupera simplement .
bool compact_database($database)
- $database correspond au nom de la base de données dans laquelle nous travaillons
$Ocdb->compact_database("mabase"); /* Retourne * * bool(true) */
Il est possible d'effectuer la copie d'un document vers un nouveau document , ou vers un document existant . Voici la façon de faire.
array copy($database,$idOrig,$idcible,$revcible=null)
- $database correspond au nom de la base de données dans laquelle nous travaillons - $idOrig correspond à l'identifiant du document d'origine - $idcible correspond à l'identifiant du document de destination - $revcible Si spécifié , correspond à la révision du document cible ( s'il existe déjà )
Vers un nouveau document :
$Ocdb->copy("mabase","0001","0002"); /* Retourne * * array(2) { ["id"]=> string(4) "0002" ["rev"]=> string(34) "1-872c3e4693b3e608148fb85b3f64df74" } */
Le retour correspond à l'id du nouveau document , et de sa révision , sinon en cas d'echec : false
Vers un document existant :
$Ocdb->copy("mabase","0001","0002","1-872c3e4693b3e608148fb85b3f64df74"); /* Retourne * * array(2) { ["id"]=> string(4) "0002" ["rev"]=> string(34) "1-872c3e4693b3e608148fb85b3f64df74" } */
La seule différence vient du fait que l'on spécifie la révision du document de destination .
Le retour correspond à l'id du nouveau document , et de sa révision , sinon en cas d'echec : false
Cette méthode , permet simplement de vérifier si un document existe ou non .
bool data_exists($database, $id, $rev=null)
- $database correspond au nom de la base de données dans laquelle nous travaillons - $id correspond à l'identifiant du document à rechercher - $rev Si renseigné , permet de vérifier une révision spécifique
$Ocdb->data_exists("mabase","0001"); /* Retourne * * bool(true) */
true le document existe , false il n'existe pas .
Cette méthode , permet simplement de vérifier si une base existe ou non .
bool database_exists($database)
- $database correspond au nom de la base de données à rechercher
$Ocdb->database_exists("mabase"); /* Retourne * * bool(true) */
true la base existe , false elle n'existe pas .
Cette méthode , permet de supprimer un document ou une base de données .
array delete($database,$id,$rev)
- $database correspond au nom de la base de données dans laquelle nous travaillons - $id identifiant unique du document - $database revision du document à supprimer
Pour supprimer un document :
$Ocdb->delete("mabase","0002","1-872c3e4693b3e608148fb85b3f64df74"); /* Retourne * * bool(true) */
true le document a bien été supprimé , false le document n'a pas été correctement supprimé .
Pour supprimer une base complète :
il suffot de ne pas spécifier l'id et la rev
$Ocdb->delete("mabase"); /* Retourne * * bool(true) */
true la base a bien été supprimé , false elle n'a pas été supprimé .
Cette méthode , permet de récupérer soit un document , soit des infos sur la base
array get($database,$id=null,$rev=null)
- $database correspond au nom de la base de données dans laquelle nous travaillons - $id identifiant unique du document - $database révision du document
Pour récupérer un document :
$Ocdb->get("mabase","0001"); /* Retourne * * array(4) { ["_id"]=> string(4) "0001" ["_rev"]=> string(34) "1-ed22a3bbcaa8b91dfbb08637f912a95c" ["NOM"]=> string(10) "Document A" ["TYPE"]=> string(3) "Doc" } */
Il n'est pas nécessaire de spécifier la révision si l'on souhaite la dernière version
Infos sur la tables :
$Ocdb->get("mabase"); /* Retourne * * array(9) { ["db_name"]=> string(6) "mabase" ["doc_count"]=> int(1) ["doc_del_count"]=> int(0) ["update_seq"]=> int(3) ["purge_seq"]=> int(0) ["compact_running"]=> bool(false) ["disk_size"]=> int(12377) ["instance_start_time"]=> string(16) "1261147399173383" ["disk_format_version"]=> int(4) } */
Cette méthode , permet de créer des requêtes personnalisées .
array send($type, $url="/", $data=null, $reponse="array")
- $type Type de requête au choix : “GET”,”PUT”,”POST”,”DELETE”,”COPY” - $url la requete proprement dite ( sans le http://host ) - $data les données à envoyées ( s'il y en a ) - $reponse format de la réponse , au choix “json” ou “array”
Pour récupérer les infos de couchDB :
$Ocdb->send("GET","/",null,"json"); /* Retourne * * string(41) "{"couchdb":"Welcome","version":"0.10.0"} " */
La même chose en array :
$Ocdb->send("GET","/",null,"array"); /* Retourne * * array(2) { ["couchdb"]=> string(7) "Welcome" ["version"]=> string(6) "0.10.0" } */
Cette méthode , permet de lister les bases de données de couchDB .
array show_databases()
$Ocdb->show_databases(); /* Retourne * * array(6) { [0]=> string(7) "baseAAA" [1]=> string(13) "test_suite_db" [2]=> string(26) "test_suite_db/with_slashes" [3]=> string(7) "membres" [4]=> string(6) "mabase" [5]=> string(6) "coucou" } */
Cette méthode , permet de lister les tables d'une base
array show_tables($database)
- $database Le nom de la base de données concernée
$Ocdb->show_tables("mabase"); /* Retourne * * array(3) { ["total_rows"]=> int(1) ["offset"]=> int(0) ["rows"]=> array(1) { [0]=> array(3) { ["id"]=> string(4) "0001" ["key"]=> string(4) "0001" ["value"]=> array(1) { ["rev"]=> string(34) "3-fffe706870491d0b152585d5c367252a" } } } } */
Cette méthode , permet modifier un document
array update($database,$id,$rev,$data)
- $database Le nom de la base de données dans laquelle nous travaillons - $id ID du document à modifier - $rev Révision du document à modifier - $data Les nouvelles données à enregistrer
$newdoc = array("NOM"=>"Document D","TYPE"=>"avi"); $Ocdb->update("mabase","0001","3-fffe706870491d0b152585d5c367252a",$newdoc); /* Retourne * * array(3) { ["ok"]=> bool(true) ["id"]=> string(4) "0001" ["rev"]=> string(34) "6-913c5fc9a6477cb66022ecaf0da6137f" } */
Le retour correspond à la nouvelle révision du document .
Cette méthode , permet la configuration de la réplication
bool set_replication(<adresse source>,<adresse cible>,<port cible>,<base source>=null,<base cible>=null,<verif>=false)
- adresse source Adresse du serveur source par exemple 127.0.0.1 - adresse cible Adresse du serveur cible par exemple 10.0.0.56 - port cible Port du serveur cible - base source Nom de la base de données à répliquer - base cible Nom de la base distante (replication) - verif Active ou non les vérifications des données
Note : Si la base cible et/ou la base source n'existent pas , Oscar tentera de les créer ( si “verif” est à TRUE )!
//sans vérifier la connexion aux serveurs et aux bases $Ocdb->set_replication('127.0.0.1','10.0.0.220','5984','baseSource','baseCible'); //avec les vérifications $Ocdb->set_replication('127.0.0.1','10.0.0.220','5984','baseSource','baseCible',TRUE);
set_replication retourne true en cas de succes , et false en cas d'ereur avec les messages d'erreurs
Note: la vérification est faite de façon systématique à l'appel de la méthode “replique”, ainsi qu'à la réplication automatique.
Cette méthode , permet le lancement de la réplication de façon immédiate . Cette tâche n'étant pas encore automatique , il vous faut le faire manuellement , sauf si auto_replique est à TRUE
bool replique(<base source>=null,<base cible>=null)
- base source Nom de la base de données à répliquer - base cible Nom de la base distante (replication)
Note : Si la base cible et/ou la base source n'existent pas , Oscar tentera de les créer !
Apres avoir fait un enregistrement / modification / suppression ,
Si les base source et cible ont été paramétrés via set_replication , il n'est pas nécessaire de les rappeler ici .
$Ocdb->replique();
Sinon :
$Ocdb->replique('baseSource','baseCible');
replique retourne un journal des modifications apportées .
Cette méthode vous permet d'activer la réplication automatiquement à chaque modification d'un enregistrement . Son utilisation est trés simple , il suffit de la passer à TRUE .
null auto_replique(<bool>)
- bool True⇒ active la réplication auto , False , désactive la réplication auto
Note: set_replication() doit être correctement configuré
Aprés avoir configuré la réplication via set_replication()
$Ocdb->auto_replique(TRUE);