L'API est concue pour developper des modifications compatibles avec les anciennes et futures versions du script. Si vous utilisez l'API pour recuperer des donnees depuis la base, vous pouvez etre certain que ce code fonctionnera egalement dans les futures versions du script, ce qui facilite la verification et l'adaptation du code a la sortie d'une nouvelle version. De plus, lors de l'utilisation de l'API, il n'est pas necessaire d'ecrire vos propres fonctions de selection de donnees ni de connecter et declarer les classes requises pour travailler avec la base de donnees. Il suffit d'inclure le fichier API et de commencer a utiliser ses fonctions ; elle se charge du reste.
Pour utiliser l'API dans votre module, vous devez l'inclure avec la ligne suivante :
include ('engine/api/api.class.php');En meme temps, vous n'avez pas besoin de vous demander si la connexion a la base existe ni si les classes necessaires sont chargees. Ce code peut etre utilise aussi bien a l'interieur des fichiers du script DLE que dans d'autres scripts sans rapport avec DLE. Cela permet d'organiser des integrations standardisees entre DLE et d'autres scripts, par exemple des forums.
Liste des fonctions de l'API :
$dle_api->take_user_by_id( int $id [, string $select_list] );Recupere un tableau d'informations sur l'utilisateur par son ID. Le parametre optionnel $select_list indique la liste des champs de base de donnees a recuperer ou * pour tous les champs. Retourne un tableau d'informations sur l'utilisateur ou false si l'utilisateur n'est pas trouve.
$dle_api->take_user_by_name( string $name [, string $select_list]);Recupere un tableau d'informations sur l'utilisateur a partir de son identifiant. Le parametre optionnel $select_list indique la liste des champs de base de donnees a recuperer ou * pour tous les champs. Retourne un tableau d'informations ou false si l'utilisateur n'est pas trouve.
$dle_api->take_user_by_email( string $email [, string $select_list]);Recupere un tableau d'informations sur l'utilisateur a partir de son e-mail. Le parametre optionnel $select_list indique la liste des champs de base de donnees a recuperer ou * pour tous les champs. Retourne un tableau d'informations ou false si l'utilisateur n'est pas trouve.
$dle_api->take_users_by_group( int $group_id [, string $select_list [, int $limit]]);Recupere un tableau d'informations sur les utilisateurs d'un groupe donne. Le parametre optionnel $select_list indique la liste des champs de base de donnees a recuperer. Le parametre optionnel $limit definit la limite du nombre d'utilisateurs retournes. Retourne un tableau d'informations ou false si aucun utilisateur n'est trouve.
$dle_api->take_users_by_ip( string $ip, [, bool $like [, string $select_list [, int $limit]]]);Recupere une liste d'utilisateurs par adresse IP. Le second parametre $like indique s'il faut utiliser une correspondance exacte ou partielle. Le parametre optionnel $select_list indique la liste des champs de base de donnees a recuperer. Le parametre optionnel $limit definit la limite du nombre d'utilisateurs retournes. Retourne un tableau d'informations ou false si aucun utilisateur n'est trouve.
$dle_api->change_user_name( int $user_id, string $new_name);Modifie l'identifiant de l'utilisateur. user_id est l'ID de l'utilisateur dont l'identifiant doit etre change. new_name est le nouvel identifiant. Valeurs de retour : true en cas de succes, false si le nouveau nom est deja utilise par un autre utilisateur.
$dle_api->change_user_pass( int $user_id, string $new_pass);Modifie le mot de passe de l'utilisateur. user_id est l'ID de l'utilisateur dont le mot de passe doit etre change. new_pass est le nouveau mot de passe.
$dle_api->change_user_email( int $user_id, string $new_email);Modifie l'e-mail de l'utilisateur. user_id est l'ID de l'utilisateur dont l'e-mail doit etre change. new_email est la nouvelle adresse e-mail. Valeurs de retour : 1 - succes, -1 - la nouvelle adresse e-mail existe deja, -2 - e-mail invalide.
$dle_api->change_user_group( int $user_id, int $new_group);Modifie le groupe de l'utilisateur. user_id est l'ID de l'utilisateur dont le groupe doit etre change. new_group est l'ID du nouveau groupe. Valeurs de retour : true en cas de succes, false si un ID de groupe inexistant est indique.
$dle_api->external_auth( string $login, string $password);Authentification par identifiant et mot de passe. Valeurs de retour : true - authentification reussie, false - identifiant ou mot de passe incorrect.
$dle_api->external_register( string $login, string $password, string $email, int $group);Enregistre un utilisateur dans la base de donnees. La fonction recoit : l'identifiant, le mot de passe, l'e-mail et le numero du groupe dans lequel l'utilisateur doit etre enregistre. Valeurs de retour : 1 - succes, -1 - le nouvel identifiant existe deja, -2 - la nouvelle adresse e-mail existe deja, -3 - e-mail invalide, -4 - groupe inexistant.
$dle_api->send_pm_to_user ( int $user_id, string $subject, string $text, string $from);Envoie un message prive a un utilisateur. $user_id ID du destinataire. $subject sujet du message. $text texte du message. $from identifiant de l'expediteur. Valeurs de retour : 1 - succes, -1 - destinataire introuvable, 0 - erreur de base de donnees.
$dle_api->load_table ( string $table [, string $fields [, string $where [, bool $multirow [, int $start [, int $limit [, string $sort [, string $sort_order]]]]]]]);Recupere des informations depuis une table de base de donnees.
$table - nom de la table
$fields - champs requis separes par des virgules ou * pour tous
$where - condition de selection
$multirow - indique s'il faut recuperer une seule ligne ou plusieurs
$start - valeur de depart de la selection
$limit - nombre d'enregistrements a recuperer, 0 - tout recuperer
$sort - champ utilise pour le tri
$sort_order - sens du tri
Retourne un tableau de donnees ou false si rien n'est trouve dans la base pour les parametres indiques.
$dle_api->save_to_cache ( string $fname, mixed $vars);Ecrit des donnees dans un fichier de cache. Le parametre $fname indique le nom du fichier cache sans son extension. $vars correspond aux donnees a ecrire dans le cache.
$dle_api->load_from_cache ( string $fname, [, int $timeout [, string $type]]);Lit des donnees depuis un fichier de cache. Le parametre $fname indique le nom du fichier cache sans son extension. Le parametre optionnel $timeout precise pendant combien de secondes les donnees en cache sont considerees comme valides. Si le fichier de cache est perime, la fonction retourne false. Le parametre optionnel $type indique le type de donnees stockees dans le cache ; s'il n'est pas egal a 'text', il est suppose qu'un tableau a ete stocke et un tableau de donnees est retourne.
$dle_api->clean_cache ( [string $name] );Supprime le cache. Le parametre optionnel $name precise le nom exact du fichier, sans extension, a supprimer.
$dle_api->get_cached_files();Recupere un tableau contenant les noms des fichiers de cache.
$dle_api->edit_config ( mixed $key, [, string $new_value]);Modifie et enregistre les parametres du script.
Le parametre $key est une chaine ou un tableau. Si c'est une chaine, il s'agit du nom du parametre ; si c'est un tableau, il s'agit d'un tableau associatif de parametres.
Le parametre $new_value represente la valeur du parametre. Il n'est pas utilise si $key est un tableau.
$dle_api->take_news ( string $cat, [, string $fields [, int $start [, int $limit [, string $sort [, string $sort_order]]]]]);Recupere des publications.
$cat - categories de publications, separees par des virgules
$fields - liste des champs de publication a recuperer ou * pour tous
$start - valeur de depart de la selection
$limit - nombre de publications a recuperer, 0 - recuperer toutes les publications
$sort - champ utilise pour le tri
$sort_order - sens du tri
Retourne un tableau associatif bidimensionnel contenant les publications.
$dle_api->checkGroup ( int $group );Verifie si le groupe indique existe ou non. Valeurs de retour : true si le groupe existe, false s'il n'existe pas.
$dle_api->install_admin_module ( string $name, string $title, string $descr, string $icon [, string $perm] );Installe un module tiers dans le panneau d'administration du script.
$name - nom du module, c'est-a-dire le nom du fichier .php situe dans le dossier engine/inc/ sans l'extension
$title - titre du module
$descr - description du module
$icon - nom de l'icone du module, sans indiquer le chemin.
$perm - informations sur les groupes autorises a voir ce module. Ce champ peut prendre les valeurs suivantes : all ou des ID de groupes separes par des virgules, par exemple 1,2,3. Si la valeur all est indiquee, le module sera affiche a tous les utilisateurs ayant acces au panneau d'administration.
$dle_api->uninstall_admin_module ( string $name );Supprime un module tiers du panneau d'administration du script.
$name - nom du module a supprimer
$dle_api->change_admin_module_perms ( string $name, string $perm );Modifie les groupes d'utilisateurs autorises a voir le module tiers dans le panneau d'administration du script.
$name - nom du module
$perm - informations sur les groupes autorises a voir ce module. Ce champ peut prendre les valeurs suivantes : all ou des ID de groupes separes par des virgules, par exemple 1,2,3. Si la valeur all est indiquee, le module sera affiche a tous les utilisateurs ayant acces au panneau d'administration.