Skip to content
Newer
Older
100644 479 lines (315 sloc) 18.4 KB
0873fa0 Upadte readme files titles
Fabrice Luraine authored May 28, 2009
1 # Limonade: LISEZMOI
56383b5 French README is now a LISEZMOI.mkd file
Fabrice Luraine authored Apr 22, 2009
2
3 Limonade est un micro framework PHP qui permet le prototypage et le développement rapide d'applications web.
4
5 Prenant son inspiration de frameworks tels que [Sinatra](http://www.sinatrarb.com/) ou [Camping](http://github.com/why/camping/tree/master) en Ruby, ou encore [Orbit](http://orbit.luaforge.net/) en Lua, il se veut simple, léger et d'un usage extrêmement souple.
6
7 Limonade met en oeuvre un ensemble de fonctions complémentaires à l'API de base de PHP, en cohérence avec celle-ci, tout en se reposant au maximum sur ses fonctions natives.
8
9 Les fonctions mises à disposition par Limonade sont assimilables extrêmement rapidement, et fournissent tout ce qu'on est en droit d'attendre d'un framework moderne ( MVC, REST, ...).
10
11
bc6df0f Fixes Hello world code example
Fabrice Luraine authored Jun 5, 2009
12 require_once 'lib/limonade.php';
56383b5 French README is now a LISEZMOI.mkd file
Fabrice Luraine authored Apr 22, 2009
13 dispatch('/', 'hello');
14 function hello()
15 {
16 return 'Hello world!';
17 }
18 run();
c75e9da Adding a "about this file" section in readme files
Fabrice Luraine authored Apr 27, 2009
19
20 ## A propos de ce document ##
21
22 Ce document fournit un aperçu rapide mais complet des fonctionnalités de Limonade.
23
fe8928f Fixing website, examples and code sources urls
Fabrice Luraine authored Jun 22, 2009
24 Pour plus d'informations, vous pouvez également consulter le [site](http://limonade.sofa-design/), les [exemples](http://limonade.sofa-design.net/examples.htm) et bien sûr le [code source](http://github.com/sofadesign/limonade/blob/master/lib/limonade.php) de Limonade, qui reste encore sa meilleure documentation.
c75e9da Adding a "about this file" section in readme files
Fabrice Luraine authored Apr 27, 2009
25
26 Un [groupe de discussion](http://groups.google.fr/group/limonade) est également à disposition pour plus d'échanges.
27
56383b5 French README is now a LISEZMOI.mkd file
Fabrice Luraine authored Apr 22, 2009
28
29 ## Routes ##
30
d987176 Corrections and additions in the french LISEZMOI
Fabrice Luraine authored Apr 22, 2009
31 Dans Limonade, les routes associent une méthode HTTP et un masque de recherche d'URL à une fonction.
56383b5 French README is now a LISEZMOI.mkd file
Fabrice Luraine authored Apr 22, 2009
32
33 dispatch('/', 'my_get_function');
34 # identique à dispatch_get('my_get_function');
35 function my_get_function()
36 {
37 // Show something
38 }
39
40 dispatch_post('/', 'my_post_function');
41 function my_post_function()
42 {
43 // Create something
44 }
45
46 dispatch_update('/', 'my_update_function');
47 function my_update_function()
48 {
49 // Update something
50 }
51
52 dispatch_delete('/', 'my_delete_function');
53 function my_delete_function()
54 {
55 // Delete something
56 }
57
58 Les routes sont testées dans l'ordre dans lequel elle sont déclarées. Le chemin auquel les routes sont comparées peut être passé de plusieurs manière via l'url:
59
60 http://localhost/my_app/?u=/my/path
61 http://localhost/my_app/?uri=/my/path
62 http://localhost/my_app/index.php?/my/path
63 http://localhost/my_app/?/my/path
bfd97ef Adding a note about the _method parameter.
Fabrice Luraine authored May 11, 2009
64
65 Quand les méthodes `PUT` ou `DELETE` ne sont pas supportés (comme dans le cas d'une soumission de fomulaire HTML), on utilise le paramètre `_method` dans une requête `POST`: sa valeur surchargera la méthode `POST`.
66
67 <form action="<?=url_for('profile_update')?>" method="post">
68 <p><input type="hidden" name="_method" value="PUT" id="_method"></p>
69 <p>... your form fields</p>
70 <p><input type="submit" value="Update"></p>
71 </form>
56383b5 French README is now a LISEZMOI.mkd file
Fabrice Luraine authored Apr 22, 2009
72
73 Les masque peuvent contenir des paramètres nommés, dont la valeur seront ensuite accessible via la fonction `params()`
74
75 dispatch('/hello/:name', 'hello');
76 function hello()
77 {
78 $name = params('name');
79 return 'Hello $name';
80 }
81
82 Les masques peuvent également contenir des caractères joker. Les valeur correspondante seront accessibles via des index qui suivent leur ordre dans le masque.
83
84 dispatch('/writing/*/to/*', 'my_letter');
85 function my_letter()
86 {
87 # Matches /writing/an_email/to/joe
88 $type = params(0); # "an_email"
89 $name = params(1); # "joe"
90 # ...
91 }
92
93 dispatch('/files/*.*', 'share_files');
94 function share_files()
95 {
96 # matches /files/readme.txt
97 $ext = params(1);
98 $filename = params(0).".".$ext;
99 # ...
100 }
101
102 Contrairement au caractère joker simple `*`, le double caractère joker `**` permet de spécifier une chaîne de caractères qui peut comporter un `/`
103
104 dispatch('/files/**', 'share_files')
105 function share_files()
106 {
107 # Matches /files/my/own/file.txt
108 $filename = params(0); # my/own/file.txt
109 }
110
111 Le masque peut également être une expression régulière s'il commence par `^`
112
113 dispatch('^/my/own/(\d+)/regexp', 'my_func');
114 function my_func()
115 {
116 # matches /my/own/12/regexp
117 $num = params(0);
118 }
119
120 On peut également nommer les paramètres joker et les captures d'expression régulière en passant un tableau contenant les noms désirés.
121
122 dispatch(array('/say/*/to/**', array("what", "name")), 'my_func');
123 function my_func()
124 {
125 # Matches /say/hello/to/joe
126 $what = params('what');
127 $name = params('name');
128 }
129
130 Les fonctions appelées par les routes peuvent être écrites n'importe où avant l'éxécution de la fonction `run()`. Elles peuvent également être regroupées dans des fichiers controlleurs rangés dans un dossier `controllers/`.
131
132 / # site root
133 - index.php # file with routes declarations and run()
134 + controllers/
135 - blog.php # functions for blog: blog_index(), blog_show(),
136 # blog_post()...
137 - comments.php # comments_for_a_post(), comment_add()...
138
139 L'emplacement de ce dossier est modifiable grâce à l'option `controllers_dir`
140
141 option('controllers_dir', dirname(__FILE__).'/other/dir/for/controllers');
142
a25bd2f Update CHANGES and README files
Fabrice Luraine authored Oct 17, 2009
143 ### Url rewriting ###
144
145 Limonade supporte l'url rewriting depuis sa version 0.4.1
146
147 Avec un fichier `.htaccess` dans le dossier racine de votre application:
148
149 <IfModule mod_rewrite.c>
150 Options +FollowSymlinks
151 Options +Indexes
152 RewriteEngine on
153 # RewriteBase /my_app/ # Si votre application est dans un sous-dossier
154
155 # test string is a valid files
156 RewriteCond %{SCRIPT_FILENAME} !-f
157 # test string is a valid directory
158 RewriteCond %{SCRIPT_FILENAME} !-d
159
160 RewriteRule ^(.*)$ index.php?/$1 [NC,L]
161 </IfModule>
162
163 Et en renseignant explicitement `option('base_uri')` dans votre fonction configure():
164
165 option('base_uri', '/my_app'); # '/' ou identique à la valeur RewriteBase de votre .htaccess
166
167 Vous apouvez accéder à votre site avec des urls de type `http://your.new-website.com/my/limonade/path` au lieu de `http://your.new-website.com/?/my/limonade/path`.
168
56383b5 French README is now a LISEZMOI.mkd file
Fabrice Luraine authored Apr 22, 2009
169
170 ## Vues et templates ##
171
172
173 Les fichiers templates sont stockés par défaut dans le dossier `views/`.
174 L'emplacement de ce dossier est modifiable grâce à l'option `views_dir`
175
176 option('views_dir', dirname(__FILE__).'/other/dir/for/views');
177
178 Pour passer des variables au templates, on utilise la fonction `set()`
179
180 set('name', 'John Doe');
181 render('index.html.php');
182
183 On peut également passer des variables directement au template:
184
185 render('index.html.php', null, array('name' => 'John Doe' ));
186
187 La méthode `set_or_default` permet de passer une variable, et si elle est vide, une valeur par défaut. Elle se révèle particulièrement utile pour l'assignation de paramètres optionnels extrait de l'url avec la fonction `params()`.
188
189 dispatch('/hello/:name', 'hello');
190 function hello()
191 {
192 # matching /hello/
193 set_or_default('name', params('name'),'John');
194 return render('Hello %s!'); // returns 'Hello John!' because params('name') was empty. Else it would have return params('name') value.
195 }
196
197
198
199
200
201 ### Layouts ###
202
203
204 Les templates peuvent être rendus à l'intérieur d'un autre template appelé layout.
205
206 Ce layout est spécifié par la fonction `layout`
207
208 layout('default_layout.php');
209
210 ou directement via la fonction de rendu des templates
211
212 render('index.html.php', 'default_layout.php');
213
214 Si la valeur du layout est `null`, le template sera rendu sans layout
215
216 render('index.html.php', null);
217
218 ### Chaînes formatées et templates en ligne ###
219
220 Les chaînes formatées à la manière de [`sprintf`](http://php.net/manual/function.sprintf.php) sont autorisées:
221
222 set('num', 5);
223 set('tree');
224 render('There are %d monkeys in the %s') // returns 'There are 5 monkeys in the tree'
225
226 Il est également possible de faire appel à une fonction pour template. On peut ainsi inclure les templates dans un même fichier afin de produire, par exemple, une application dans un fichier unique.
227
228
229 function html_message($vars){ extract($vars);?>
230 <h1>Title: <?=h($title)?></h1>
231 <p>Message:<br>
232 <?=h($msg)?></p>
233 <?}
234
d987176 Corrections and additions in the french LISEZMOI
Fabrice Luraine authored Apr 22, 2009
235 // in a request handling function
56383b5 French README is now a LISEZMOI.mkd file
Fabrice Luraine authored Apr 22, 2009
236 set('title', 'Hello!');
237 set('msg', 'There are 100 monkeys in the Chennai and bangalore');
238 render('html_message');
239
240 ### Templates HTML ###
241
242 La fonction `html` permet de rendre un template de la même manière que `render`. Une en-tête HTTP précise le `Content-type` adéquat (`text/html`) et l'encodage défini dans les options (utf8 par défaut).
243
244 html('my_template.html.php');
245
246
247 ### Templates XML ###
248
249 La fonction `xml` permet de rendre un template de la même manière que `render`. Une en-tête HTTP précise le `Content-type` adéquat (`text/xml`) et l'encodage défini dans les options (utf8 par défaut).
250
251 ### Templates CSS ###
252
253 La fonction `css` permet de rendre un template de la même manière que `render`. Une en-tête HTTP précise le `Content-type` adéquat (`text/css`) et l'encodage défini dans les options (utf8 par défaut).
254
255 css('screen.css.php');
256
257 ### Templates TXT ###
258
259 La fonction `txt` permet de rendre un template de la même manière que `render`. Une en-tête HTTP précise le `Content-type` adéquat (`text/plain`) et l'encodage défini dans les options (utf8 par défaut).
260
261 txt('index.txt.php');
262
263 ### Templates JSON ###
264
d987176 Corrections and additions in the french LISEZMOI
Fabrice Luraine authored Apr 22, 2009
265 Comme la fonction [`json_encode`](http://php.net/manual/function.json-encode.php), retourne la réprésentation json d'une valeur. Une en-tête HTTP précise le `Content-type` adéquat (`application/x-javascript`) et l'encodage défini dans les options (utf8 par défaut).
56383b5 French README is now a LISEZMOI.mkd file
Fabrice Luraine authored Apr 22, 2009
266
267 json($my_data);
268
269 ### Servir des fichiers ###
270
271 La fonction `render_file` permet de rendre un fichier directement dans le tampon de sortie.
272
273 render_file(option('public_dir').'foo.jpg');
274
d987176 Corrections and additions in the french LISEZMOI
Fabrice Luraine authored Apr 22, 2009
275 Une en-tête HTTP précise le `Content-type` adéquat en fonction de l'extension du fichier et l'encodage défini dans les options (utf8 par défaut) pour les fichiers textes.
56383b5 French README is now a LISEZMOI.mkd file
Fabrice Luraine authored Apr 22, 2009
276
277 La sortie est temporisée afin de prendre en charge aisément des fichiers de grande taille.
278
279 ### Captures ###
280
281 [TODO] `content_for($name); endcontent();`
282
283 ## Avant et après la requête ##
284
285 Vous pouvez définir une fonction `before` qui sera executée avant chaque requête. Cela s'avère très utile pour définir un layout par défaut ou des variables à passer aux templates
286
287 function before()
288 {
289 layout('default_layout.php');
290 set('site_title', 'My Website');
291 }
292
293 Un filtre de sortie `after` est également disponible. Il est exécuté après chaque requête et permet d'appliquer une transformation à la sortie (sauf pour les sorties `render_file` qui sont envoyées directement au tampon de sortie).
294
295 function after($output){
296 $config = array('indent' => TRUE,
297 'output-xhtml' => TRUE,
298 'wrap' => 200);
299
300 $tidy = tidy_parse_string($output, $config, option('encoding'));
301 return $tidy->cleanRepair();
302 }
303
304 ## Configuration ##
305
306 Vous pouvez définir une fonction `configure` qui sera exécutée au début de l'application (au début de l'exécution de `run()`).
307 Vous pouvez notamment y définir les différentes options, une connexion à une base de donnée...
308
309 function configure()
310 {
311 $env = $_SERVER['HTTP_HOST'] == "localhost" ? ENV_DEVELOPMENT : ENV_PRODUCTION;
312 option('env', $env);
313 if(option('env') > ENV_PRODUCTION)
314 {
315 options('dsn', 'sqlite:db/development.db'));
316 }
317 else
318 {
319 options('dsn', 'sqlite:db/production.db'));
320 }
321 $GLOBALS['my_db_connexion'] = new PDO(option('dsn'));
322 }
323
d987176 Corrections and additions in the french LISEZMOI
Fabrice Luraine authored Apr 22, 2009
324 L'ensemble des fichiers PHP contenus dans le dossier défini par `option('lib_dir')` (`lib/` par défaut) sont chargés avec [`require_once`](http://php.net/manual/function.require-once.php) juste avant l'exécution de la méthode `configure`. Vous pouvez ainsi placer vos propres fonction et bibliothèques dans ce dossier afin qu'ils soit chargés et disponibles au démarrage de l'application.
56383b5 French README is now a LISEZMOI.mkd file
Fabrice Luraine authored Apr 22, 2009
325
d987176 Corrections and additions in the french LISEZMOI
Fabrice Luraine authored Apr 22, 2009
326 ## Options ##
56383b5 French README is now a LISEZMOI.mkd file
Fabrice Luraine authored Apr 22, 2009
327
328 La fonction `option` permet de définir et d'accéder aux options de l'application
329
330 option('env', ENV_PRODUCTION);
331 option('env'); // return ENV_PRODUCTION value
332
333 Si le nom de l'option n'est pas précisé, retourne un tableau de toutes les options définies.
334
335 Vous pouvez l'utiliser pour gérer les options propres à Limonade mais aussi des options personnalisées pour votre application.
336
337 Les options utilisées par Limonade ont par défaut les valeurs suivantes:
338
339 option('root_dir', $root_dir); // le dossier qui contient le fichier de lancement de l'application
d87f108 Update README files with current default options, session and flash f…
Fabrice Luraine authored Aug 5, 2009
340 option('base_path', $base_path);
341 option('base_uri', $base_uri); // à spécifier si vous utiliser l'url rewriting.
342 option('limonade_dir', dirname(__FILE__).'/'); // dossier contenant le fichier principal limonade.php
343 option('limonade_views_dir', dirname(__FILE__).'/limonade/views/');
344 option('limonade_public_dir',dirname(__FILE__).'/limonade/public/');
345 option('public_dir', $root_dir.'/public/');
346 option('views_dir', $root_dir.'/views/');
347 option('controllers_dir', $root_dir.'/controllers/');
348 option('lib_dir', $root_dir.'/lib/');
349 option('error_views_dir', option('limonade_views_dir'));
350 option('env', ENV_PRODUCTION);
351 option('debug', true);
352 option('session', LIM_SESSION_NAME); // true, false or the name of your session
353 option('encoding', 'utf-8');
354 option('x-sendfile', 0); // 0: disabled,
355 // X-SENDFILE: for Apache and Lighttpd v. >= 1.5,
356 // X-LIGHTTPD-SEND-FILE: for Apache and Lighttpd v. < 1.5
357
358 ## Sessions ##
359
360 Une session démarre automatiquement par défaut. Vous puvez ensuite accéder aux variable des session comme d'habitude avec le tableau `$_SESSION`.
361
362 Vous pouvez désactiver les sessions avec l'option `session`
363
364 ⌘ [voir un exemple de code](http://gist.github.com/159327)
365
366 ### Flash ###
367
368 Flash est une fonctionnalit particulière des sessions. Une valeur flash sera disponible pour la preochaine requête puis effacée. Cette fonctionnalité est particulièrement utile pour l'affiche des erreurs de retours après la soumission d'un formulaire ou pour notifier l'utilisateur du bon déroulement d'une action.
369
370 * `flash($name, $value...)` définit une valeur flash pour la prochaine requête
371 * dans les vues HTML, vous pouvez accéder aux valeurs flash disponible grâce au tableau `$flash` ou à la fonction `flash_now($name)`.
372
373 ⌘ [voir un exemple de code](http://gist.github.com/162680)
56383b5 French README is now a LISEZMOI.mkd file
Fabrice Luraine authored Apr 22, 2009
374
5ae91ce Small addons to README files. Update CHANGES
Fabrice Luraine authored Jul 31, 2009
375 ## Helpers ##
376
377 Consultez le code source et l'API pour de plus amples informations sur les helpers disponibles.
378
379 ### url_for ###
380
381 Utilisez la fonction `url_for` afin de créer automatiquement des urls bien formées quel que soit le dossier dans lequel est installée votre application sur le serveur web.
382
383 Si vous utilisez l'url rewriting, vous devez spécifier explicitement l'option `base_uri` (par défaut `/chemin_de_mon_appli/?`).
384
385
56383b5 French README is now a LISEZMOI.mkd file
Fabrice Luraine authored Apr 22, 2009
386 ## Gestion des erreurs ##
387
388 ### Halt ###
389
390 Vous pouvez interrompre l'execution de l'application avec la fonction `halt`
391 Les erreurs seront prises en charge par les gestionnaires d'erreur par défaut de Limonade ou par ceux que vous aurez définis.
392
393 halt(NOT_FOUND);
394 halt("En error occured in my app...");
395
396 ### Not Found ###
397
d987176 Corrections and additions in the french LISEZMOI
Fabrice Luraine authored Apr 22, 2009
398 Par défaut, renvoie sur le gestionnaire d'erreur `not_found` et envoie un _`404 NOT FOUND`_ dans les en-têtes HTTP.
56383b5 French README is now a LISEZMOI.mkd file
Fabrice Luraine authored Apr 22, 2009
399
400 halt(NOT_FOUND);
401 halt(NOT_FOUND, "This product doesn't exists.");
402
d987176 Corrections and additions in the french LISEZMOI
Fabrice Luraine authored Apr 22, 2009
403 Pour définir un nouvel affichage de ce erreurs, il suffit de déclarer une fonction `not_found`
56383b5 French README is now a LISEZMOI.mkd file
Fabrice Luraine authored Apr 22, 2009
404
405 function not_found($errno, $errstr, $errfile=null, $errline=null)
406 {
407 set('errno', $errno);
408 set('errstr', $errstr);
409 set('errfile', $errfile);
410 set('errline', $errline);
411 return html("show_not_found_errors.html.php");
412 }
413
414 ### Server Error ###
415
d987176 Corrections and additions in the french LISEZMOI
Fabrice Luraine authored Apr 22, 2009
416 Par défaut, renvoie sur le gestionnaire d'erreur `server_error` et envoie un _`500 INTERNAL SERVER ERROR`_ dans les en-têtes HTTP.
56383b5 French README is now a LISEZMOI.mkd file
Fabrice Luraine authored Apr 22, 2009
417
418 halt();
419 halt('Breaking bad!');
420 halt(SERVER_ERROR, "Not good...");
421 trigger_error("Wrong parameter", E_USER_ERROR);
422
423 Les erreurs php sont également capturées et envoyées à ce gestionnaire d'erreur.
424
d987176 Corrections and additions in the french LISEZMOI
Fabrice Luraine authored Apr 22, 2009
425 Pour définir un nouvel affichage de ce erreurs, il suffit de déclarer une fonction `server_error`
56383b5 French README is now a LISEZMOI.mkd file
Fabrice Luraine authored Apr 22, 2009
426
427 function server_error($errno, $errstr, $errfile=null, $errline=null)
428 {
429 $args = compact('errno', 'errstr', 'errfile', 'errline');
430 return html("show_server_errors.html.php", error_layout(), $args);
431 }
432
433 ### Error layout ###
434
435 Permet de définir et d'accéder à un layout dédié à l'affichage d'erreurs
436
437 error_layout('error_layout.php');
438 error_layout(); // return 'error_layout.php'
439
440 ### Capture des erreurs ###
441
442 En plus de la personnalisation de l'affichage des erreurs courantes `NOT_FOUND` et `SERVER_ERROR`, limonade permet de rediriger de manière précise les erreurs vers vos propres fonctions.
443
444 error(E_USER_WARNING, 'my_notices')
445 function my_notices($errno, $errstr, $errfile, $errline)
446 {
447 // storing php warnings in a log file
448 // ...
449 status(SERVER_ERROR);
450 return html('<h1>Server Error</h1>');
451 }
452
453 La constante `E_LIM_HTTP` désigne toutes les erreurs HTTP
454
455 error(E_LIM_HTTP, 'my_http_errors')
456 function my_http_errors($errno, $errstr, $errfile, $errline)
457 {
458 status($errno);
459 return html('<h1>'.http_response_status_code($errno).'</h1>');
460 }
461
d987176 Corrections and additions in the french LISEZMOI
Fabrice Luraine authored Apr 22, 2009
462 La constante `E_LIM_PHP` désigne toutes les erreurs PHP (renvoyé par PHP ou via [`trigger_error`](http://php.net/manual/function.trigger-error.php)).
56383b5 French README is now a LISEZMOI.mkd file
Fabrice Luraine authored Apr 22, 2009
463
464 ## Testing ##
465
466 [TODO]
467
77c05cd Small changes in readme
Fabrice Luraine authored Apr 27, 2009
468 ## More ##
56383b5 French README is now a LISEZMOI.mkd file
Fabrice Luraine authored Apr 22, 2009
469
fe8928f Fixing website, examples and code sources urls
Fabrice Luraine authored Jun 22, 2009
470 * [Limonade web site](http://limonade.sofa-design.net/)
77c05cd Small changes in readme
Fabrice Luraine authored Apr 27, 2009
471 * [Issue tracking / release planning](http://sofadesign.lighthouseapp.com/projects/29612-limonade/overview)
56383b5 French README is now a LISEZMOI.mkd file
Fabrice Luraine authored Apr 22, 2009
472 * [Support / Discussions](http://groups.google.fr/group/limonade)
473
474
475
476
477
d987176 Corrections and additions in the french LISEZMOI
Fabrice Luraine authored Apr 22, 2009
478
Something went wrong with that request. Please try again.