<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
-<!-- English Revision: 1420377:1430656 (outdated) -->
+<!-- English Revision : 1430656 -->
<!-- French translation : Lucien GENTIS -->
<!-- Reviewed by : Vincent Deffontaines -->
</highlight>
<highlight language="lua">
- r:base64_encode(string) -- Encode une chaîne à l'aide du
+ r:base64_encode(string) -- Encode une chaîne à l'aide du
standard de codage Base64.
</highlight>
<highlight language="lua">
- r:base64_decode(string) -- Décode une chaîne codée en Base64.
+ r:base64_decode(string) -- Décode une chaîne codée en Base64.
</highlight>
<highlight language="lua">
- r:md5(string) -- Calcule et renvoie le condensé MD5 d'une chaîne
+ r:md5(string) -- Calcule et renvoie le condensé MD5 d'une chaîne
en mode binaire (binary safe).
</highlight>
<highlight language="lua">
- r:sha1(string) -- Calcule et renvoie le condensé SHA1 d'une chaîne
+ r:sha1(string) -- Calcule et renvoie le condensé SHA1 d'une chaîne
en mode binaire (binary safe).
</highlight>
<highlight language="lua">
- r:escape(string) -- Echappe une chaîne de type URL.
+ r:escape(string) -- Echappe une chaîne de type URL.
</highlight>
<highlight language="lua">
- r:unescape(string) -- Déséchappe une chaîne de type URL.
+ r:unescape(string) -- Déséchappe une chaîne de type URL.
</highlight>
<highlight language="lua">
- r:banner() -- Renvoie la bannière du serveur courant.
+ r:banner() -- Renvoie la bannière du serveur courant.
</highlight>
<highlight language="lua">
- r:port() -- Renvoie le port du serveur courant utilisé pour la
- requête.
+ r:port() -- Renvoie le port du serveur courant utilisé pour la
+ requête.
</highlight>
<highlight language="lua">
- r:mpm_query(number) -- Interroge le serveur à propos de son
- module MPM via la requête ap_mpm_query.
+ r:mpm_query(number) -- Interroge le serveur à propos de son
+ module MPM via la requête ap_mpm_query.
</highlight>
<highlight language="lua">
- r:expr(string) -- Evalue une cha
îne de type <a
+ r:expr(string) -- Evalue une cha
îne de type <a
href="../expr.html">expr</a>.
</highlight>
<highlight language="lua">
- r:scoreboard_process(a) -- Interroge le serveur à propos du
- processus à la position <code>a</code>.
+ r:scoreboard_process(a) -- Interroge le serveur à propos du
+ processus à la position <code>a</code>.
</highlight>
<highlight language="lua">
- r:scoreboard_worker(a, b) -- Interroge le serveur à propos du
+ r:scoreboard_worker(a, b) -- Interroge le serveur à propos du
thread <code>b</code>, dans le processus <code>a</code>.
</highlight>
<highlight language="lua">
- r:started() -- Renvoie l'heure du dernier (re)démarrage du
+ r:started() -- Renvoie l'heure du dernier (re)démarrage du
serveur.
</highlight>
<highlight language="lua">
- r:clock() -- Renvoie l'heure courante avec une précision d'une
+ r:clock() -- Renvoie l'heure courante avec une précision d'une
microseconde.
</highlight>
<highlight language="lua">
-r:requestbody(filename) -- Lit et renvoie le corps d'une requête. Si
-'filename' est spécifié, le corps de requête n'est pas renvoyé, mais
-sauvegardé dans le fichier correspondant.
+r:requestbody(filename) -- Lit et renvoie le corps d'une requête. Si
+'filename' est spécifié, le corps de requête n'est pas renvoyé, mais
+sauvegardé dans le fichier correspondant.
</highlight>
<highlight language="lua">
- r:add_input_filter(filter_name) -- Ajoute le filtre en entrée
+ r:add_input_filter(filter_name) -- Ajoute le filtre en entrée
'filter_name'.
</highlight>
<highlight language="lua">
- r:module_info(module_name) -- Interroge le serveur à propos d'un
+ r:module_info(module_name) -- Interroge le serveur à propos d'un
module.
</highlight>
<highlight language="lua">
- r:loaded_modules() -- Renvoie une liste des modules chargés par
+ r:loaded_modules() -- Renvoie une liste des modules chargés par
httpd.
</highlight>
<highlight language="lua">
-r:runtime_dir_relative(filename) -- Génère le nom d'un fichier run-time
-(par exemple la mémoire partagée "file") relativement au répertoire de
+r:runtime_dir_relative(filename) -- Génère le nom d'un fichier run-time
+(par exemple la mémoire partagée "file") relativement au répertoire de
run-time.
</highlight>
<highlight language="lua">
r:server_info() -- Renvoie une table contenant des informations
- à propos du serveur, comme le nom de l'exécutable httpd, le
- module mpm utilisé, etc...
+ à propos du serveur, comme le nom de l'exécutable httpd, le
+ module mpm utilisé, etc...
</highlight>
<highlight language="lua">
- r:set_document_root(file_path) -- Définit la racine des
- documents pour la requête à file_path.
+ r:set_document_root(file_path) -- Définit la racine des
+ documents pour la requête à file_path.
</highlight>
<highlight language="lua">
- r:add_version_component(component_string) -- Ajoute un élément à
- la bannière du serveur.
+ r:add_version_component(component_string) -- Ajoute un élément à
+ la bannière du serveur.
</highlight>
<highlight language="lua">
- r:set_context_info(prefix, docroot) -- Définit le préfixe et la
- racine des documents du contexte pour une requête.
+ r:set_context_info(prefix, docroot) -- Définit le préfixe et la
+ racine des documents du contexte pour une requête.
</highlight>
<highlight language="lua">
- r:os_escape_path(file_path) -- Convertit un chemin du système de
- fichiers en URL indépendamment du système d'exploitation.
+ r:os_escape_path(file_path) -- Convertit un chemin du système de
+ fichiers en URL indépendamment du système d'exploitation.
</highlight>
<highlight language="lua">
- r:escape_logitem(string) -- Echappe une chaîne pour
+ r:escape_logitem(string) -- Echappe une chaîne pour
journalisation.
</highlight>
<highlight language="lua">
-r:strcmp_match(string, pattern) -- Vérifie si 'string' correspond à
+r:strcmp_match(string, pattern) -- Vérifie si 'string' correspond à
'pattern' via la fonction strcmp_match (GLOBs). Par exemple, est-ce que
-'www.example.com' correspond à '*.example.com' ?
+'www.example.com' correspond à '*.example.com' ?
</highlight>
<highlight language="lua">
- r:set_keepalive() -- Définit l'état de persistance d'une
- requête. Renvoie true dans la mesure du possible, false dans le
+ r:set_keepalive() -- Définit l'état de persistance d'une
+ requête. Renvoie true dans la mesure du possible, false dans le
cas contraire.
</highlight>
<highlight language="lua">
- r:make_etag() -- Génère et renvoie le etag pour la requête
+ r:make_etag() -- Génère et renvoie le etag pour la requête
courante.
</highlight>
<highlight language="lua">
-r:send_interim_response(clear) -- Renvoie une réponse d'intérim (1xx) au
-client. Si 'clear' est vrai, les en-têtes disponibles seront envoyés et
-effacés.
+r:send_interim_response(clear) -- Renvoie une réponse d'intérim (1xx) au
+client. Si 'clear' est vrai, les en-têtes disponibles seront envoyés et
+effacés.
</highlight>
<highlight language="lua">
-r:custom_response(status_code, string) -- Génère et définit une réponse
-personnalisée pour un code d'état particulier. Le fonctionnement est
-très proche de celui de la directive ErrorDocument.
+r:custom_response(status_code, string) -- Génère et définit une réponse
+personnalisée pour un code d'état particulier. Le fonctionnement est
+très proche de celui de la directive ErrorDocument.
</highlight>
<highlight language="lua">
- r:exists_config_define(string) -- Vérifie si une définition de
+ r:exists_config_define(string) -- Vérifie si une définition de
configuration existe.
</highlight>
<highlight language="lua">
- r:state_query(string) -- Interroge le serveur à propos de son
- état.
+ r:state_query(string) -- Interroge le serveur à propos de son
+ état.
</highlight>
<highlight language="lua">
- r:stat(filename) -- Exécute stat() sur un fichier, et renvoie
- une table contenant des informations à propos de ce fichier.
+ r:stat(filename) -- Exécute stat() sur un fichier, et renvoie
+ une table contenant des informations à propos de ce fichier.
</highlight>
<highlight language="lua">
- r:regex(string, pattern) -- Exécute une recherche à base
- d'expression rationnelle sur une chaîne, et renvoie les
- éventuelles correspondances trouvées.
+ r:regex(string, pattern) -- Exécute une recherche à base
+ d'expression rationnelle sur une chaîne, et renvoie les
+ éventuelles correspondances trouvées.
</highlight>
<highlight language="lua">
- r:sleep(secondes) -- Interrompt l'exécution du script pendant le
- nombre de secondes spécifié.
+ r:sleep(secondes) -- Interrompt l'exécution du script pendant le
+ nombre de secondes spécifié.
+ </highlight>
+
+ <highlight language="lua">
+ r:dbacquire(dbType[, dbParams]) -- Acquiert une connexion à une
+base de données et renvoie une classe database. Voir '<a
+href="#databases">Connectivité aux bases de données</a>' pour plus de
+détails.
</highlight>
</dd>
</dl>
<section id="modifying_buckets">
<title>Modification de contenu avec les filtres lua</title>
<p>
- Les fonctions de filtrage implémentées via les directives <directive
+ Les fonctions de filtrage implémentées via les directives <directive
module="mod_lua">LuaInputFilter</directive> ou <directive
- module="mod_lua">LuaOutputFilter</directive> sont conçues comme des
- fonctions de 3ème phase non blocantes utilisant des sous-routines
- pour suspendre et reprendre l'exécution d'une fonction lorsque des
- paquets de données sont envoyés à la chaîne de filtrage. La
+ module="mod_lua">LuaOutputFilter</directive> sont conçues comme des
+ fonctions de 3ème phase non blocantes utilisant des sous-routines
+ pour suspendre et reprendre l'exécution d'une fonction lorsque des
+ paquets de données sont envoyés à la chaîne de filtrage. La
structure de base d'une telle fonction est :
</p>
<highlight language="lua">
function filter(r)
- -- Nous indiquons tout d'abord que nous sommes prêts à recevoir des
- -- blocs de données.
- -- Avant ceci, nous pouvons définir notre environnement, tester
- -- certaines conditions, et, si nous le jugeons nécessaire, refuser le
- -- filtrage d'une requête :
+ -- Nous indiquons tout d'abord que nous sommes prêts à recevoir des
+ -- blocs de données.
+ -- Avant ceci, nous pouvons définir notre environnement, tester
+ -- certaines conditions, et, si nous le jugeons nécessaire, refuser le
+ -- filtrage d'une requête :
if something_bad then
- return -- Le filtrage est sauté
+ return -- Le filtrage est sauté
end
- -- Sans se préoccuper des données que nous devons éventuellement ajouter, un arrêt est réalisé ici.
- -- Noter que les filtres de sortie sont les seuls capables d'ajouter des éléments au début des données.
- -- Les filtres en entrée peuvent ajouter des éléments à la fin des données au stade final.
+ -- Sans se préoccuper des données que nous devons éventuellement ajouter, un arrêt est réalisé ici.
+ -- Noter que les filtres de sortie sont les seuls capables d'ajouter des éléments au début des données.
+ -- Les filtres en entrée peuvent ajouter des éléments à la fin des données au stade final.
coroutine.yield([optional header to be prepended to the content])
- -- Après cet arrêt, nous allons recevoir d'autres blocs de données, un par un ;
- -- nous pouvons les traiter comme il nous plaît et procéder à la réponse.
- -- Ces blocs sont conservés dans la variable globale 'bucket', nous réalisons donc
- -- une boucle pour vérifier que 'bucket' n'est pas vide :
+ -- Après cet arrêt, nous allons recevoir d'autres blocs de données, un par un ;
+ -- nous pouvons les traiter comme il nous plaît et procéder à la réponse.
+ -- Ces blocs sont conservés dans la variable globale 'bucket', nous réalisons donc
+ -- une boucle pour vérifier que 'bucket' n'est pas vide :
while bucket ~= nil do
local output = mangle(bucket) -- Do some stuff to the content
coroutine.yield(output) -- Return our new content to the filter chain
end
- -- Une fois les blocs de données épuisés, 'bucket' est positionné à une valeur vide ('nil'),
- -- ce qui va nous faire sortir de cette boucle et nous amener à l'étape suivante.
- -- On peut ajouter ce qu'on veut à la fin des données à cette étape, qui constitue le dernier
- -- arrêt. Les filtres d'entrée comme de sortie peuvent servir à ajouter des éléments à la fin
- -- des données à cette étape.
+ -- Une fois les blocs de données épuisés, 'bucket' est positionné à une valeur vide ('nil'),
+ -- ce qui va nous faire sortir de cette boucle et nous amener à l'étape suivante.
+ -- On peut ajouter ce qu'on veut à la fin des données à cette étape, qui constitue le dernier
+ -- arrêt. Les filtres d'entrée comme de sortie peuvent servir à ajouter des éléments à la fin
+ -- des données à cette étape.
coroutine.yield([optional footer to be appended to the content])
end
</highlight>
</section>
+<section id="databases">
+ <title>Connectivité aux bases de données</title>
+ <p>Mod_lua implémente une fonctionnalité basique de connexion aux
+bases de données permettant d'envoyer des requêtes ou d'exécuter des
+commandes auprès des moteurs de base de données les plus courants
+(mySQL, PostgreSQL, FreeTDS, ODBC, SQLite, Oracle), ainsi que mod_dbd.
+ </p>
+ <p>L'exemple suivant montre comment se connecter à une base de
+données et extraire des informations d'une table :</p>
+ <highlight language="lua">
+function handler(r)
+ -- connexion à la base de données
+ local database, err = r:dbacquire("mysql", "server=localhost&user=root&database=mydb")
+ if not err then
+ -- Sélection de certaines informations
+ local results, err = database:select(r, "SELECT `name`, `age` FROM `people` WHERE 1")
+ if not err then
+ local rows = results(0) -- extrait tous les enregistrements en mode synchrone
+ for k, row in pairs(rows) do
+ r:puts( string.format("Name: %s, Age: %s<br/>", row[1], row[2]) )
+ end
+ else
+ r:puts("Database query error: " .. err)
+ end
+ database:close()
+ else
+ r:puts("Connexion à la base de données impossible : " .. err)
+ end
+end
+ </highlight>
+ <p>
+ Pour utiliser <module>mod_dbd</module>, spécifiez
+<code>mod_dbd</code> comme type de base de données, ou laissez le champ
+vide :
+ </p>
+ <highlight language="lua">
+ local database = r:dbacquire("mod_dbd")
+ </highlight>
+ <section id="database_object">
+ <title>L'objet database et ses méthodes</title>
+ <p>L'objet database renvoyé par <code>dbacquire</code> possède
+les méthodes suivantes :</p>
+ <p><strong>Sélection normale et requête vers une base de données
+:</strong></p>
+ <highlight language="lua">
+-- Exécution d'une requête et renvoie du nombre d'enregistrements
+affectés :
+local affected, errmsg = database:query(r, "DELETE FROM `tbl` WHERE 1")
+
+-- Exécution d'une requête et renvoie du résultat qui peut être utilisé
+en mode synchrone ou asynchrone :
+local result, errmsg = database:select(r, "SELECT * FROM `people` WHERE 1")
+ </highlight>
+ <p><strong>Utilisation de requêtes préparées (recommandé) :</strong></p>
+ <highlight language="lua">
+-- Création et exécution d'une requête préparée :
+local statement, errmsg = database:prepare(r, "DELETE FROM `tbl` WHERE `age` > %u")
+if not errmsg then
+ local result, errmsg = statement:query(20) -- exécute la requête pour age > 20
+end
+
+-- Extrait une requête préparée depuis une directive DBDPrepareSQL :
+local statement, errmsg = database:prepared(r, "someTag")
+if not errmsg then
+ local result, errmsg = statement:select("John Doe", 123) -- injecte les valeurs "John Doe" et 123 dans la requête
+end
+
+</highlight>
+ <p><strong>Echappement de valeurs, fermeture de la base données,
+etc...</strong></p>
+ <highlight language="lua">
+-- Echappe une valeur pour pouvoir l'utiliser dans une requête :
+local escaped = database:escape(r, [["'|blabla]])
+
+-- Ferme une base de données et libère les liens vers cette dernière :
+database:close()
+
+-- Vérifie si une connexion à une base de données est en service et
+opérationnelle :
+local connected = database:active()
+ </highlight>
+ </section>
+ <section id="result_sets">
+ <title>Travail avec les jeux d'enregistrements renvoyés par les requêtes</title>
+ <p>Les jeux d'enregistrements renvoyés par <code>db:select</code> ou par des
+requêtes préparées créées par <code>db:prepare</code> permettent de
+sélectionner des enregistrements en mode synchrone ou
+asynchrone, selon le nombre d'enregistrements spécifié :<br/>
+ <code>result(0)</code> sélectionne tous les enregistrements en mode
+synchrone en renvoyant une table d'enregistrements.<br/>
+ <code>result(-1)</code> sélectionne le prochain enregistrement disponible en
+mode asynchrone.<br/>
+ <code>result(N)</code> sélectionne l'enregistrement numéro
+<code>N</code> en mode asynchrone.
+ </p>
+ <highlight language="lua">
+-- extrait un jeu d'enregistrements via une requête régulière :
+local result, err = db:select(r, "SELECT * FROM `tbl` WHERE 1")
+
+local rows = result(0) -- sélectionne tous les enregistrements en mode synchrone
+local row = result(-1) -- sélectionne le prochain enregistrement disponible en mode asynchrone
+local row = result(1234) -- sélectionne l'enregistrement 1234 en mode asynchrone
+ </highlight>
+ <p>Il est possible de construire une fonction qui renvoie une
+fonction itérative permettant de traiter tous les enregistrement en mode
+synchrone ou asynchrone selon la valeur de l'argument async :
+ </p>
+ <highlight language="lua">
+function rows(resultset, async)
+ local a = 0
+ local function getnext()
+ a = a + 1
+ local row = resultset(-1)
+ return row and a or nil, row
+ end
+ if not async then
+ return pairs(resultset(0))
+ else
+ return getnext, self
+ end
+end
+
+local statement, err = db:prepare(r, "SELECT * FROM `tbl` WHERE `age` > %u")
+if not err then
+ -- sélectionne des enregistrements en mode asynchrone :
+ local result, err = statement:select(20)
+ if not err then
+ for index, row in rows(result, true) do
+ ....
+ end
+ end
+
+ -- sélectionne des enregistrements en mode synchrone :
+ local result, err = statement:select(20)
+ if not err then
+ for index, row in rows(result, false) do
+ ....
+ end
+ end
+end
+ </highlight>
+ </section>
+ <section id="closing_databases">
+ <title>Fermeture d'une connexion à une base de données</title>
+
+ <p>Lorsqu'elles ne sont plus utilisées, les connexions aux bases de
+données doivent être fermées avec <code>database:close()</code>. Si vous
+ne les fermez pas manuellement, mod_lua les fermera peut-être en tant
+que résidus collectés, mais si ce n'est pas le cas, vous pouvez finir
+pas avoir trop de connexions vers la base de données inutilisées. Les
+deux mesures suivantes sont pratiquement identiques :
+ </p>
+ <highlight language="lua">
+-- Méthode 1 : fermeture manuelle de la connexion
+local database = r:dbacquire("mod_dbd")
+database:close() -- c'est tout
+
+-- Méthode 2 : on laisse le collecteur de résidus la fermer
+local database = r:dbacquire("mod_dbd")
+database = nil -- on coupe le lien
+collectgarbage() -- fermeture de la connexion par le collecteur de résidus
+</highlight>
+ </section>
+ <section id="database_caveat">
+ <title>Précautions à prendre lorsque l'on travaille avec les bases
+de données</title>
+ <p>Bien que les fonctions <code>query</code> et <code>run</code>
+soient toujours disponibles, il est recommandé d'utiliser des requêtes
+préparées chaque fois que possible, afin d'une part d'optimiser les
+performances (si votre connexion reste longtemps en vie), et d'autre part
+minimiser le risque d'attaques par injection SQL. Les fonctions
+<code>run</code> et <code>query</code> ne doivent être utilisées que
+lorsque la requête ne contient pas de variables (requête statique). Dans
+le cas des requêtes dynamiques, utilisez <code>db:prepare</code> ou
+<code>db:prepared</code>.
+ </p>
+ </section>
+
+</section>
<directivesynopsis>
<name>LuaRoot</name>
projects / apache / commitdiff