Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 433 lines (287 sloc) 14.707 kb
0873fa0 Upadte readme files titles
Fabrice Luraine authored
1 # Limonade: README
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
2
7538deb README file is now written in english
Fabrice Luraine authored
3 Limonade is a PHP micro framework for rapid web development and prototyping.
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
4
7538deb README file is now written in english
Fabrice Luraine authored
5 It's inspired by frameworks like [Sinatra](http://www.sinatrarb.com/) or [Camping](http://github.com/why/camping/tree/master) in Ruby, or [Orbit](http://orbit.luaforge.net/) in Lua. It aims to be simple, lightweight and extremly flexible.
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
6
4f37e74 Small correction
Fabrice Luraine authored
7 Limonade provides functions that complete the PHP basic set, while keeping consistency with native functions and sitting up on them.
7538deb README file is now written in english
Fabrice Luraine authored
8
9 Limonade is easy to learn and provides everything that you can expect from a modern framework (MVC, REST, ...)
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
10
11
12
bc6df0f Fixes Hello world code example
Fabrice Luraine authored
13 require_once 'lib/limonade.php';
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
14 dispatch('/', 'hello');
15 function hello()
16 {
17 return 'Hello world!';
18 }
19 run();
c75e9da Adding a "about this file" section in readme files
Fabrice Luraine authored
20
21 ## About this document ##
22
23 This document provides a quick but comprehensive guide of Limonade features.
24
fe8928f Fixing website, examples and code sources urls
Fabrice Luraine authored
25 For more informations, you can see the [website](http://limonade.sofa-design.net/), [examples](http://limonade.sofa-design.net/examples.htm) and of course, the [source code](http://github.com/sofadesign/limonade/blob/master/lib/limonade.php) which is still the best documentation.
c75e9da Adding a "about this file" section in readme files
Fabrice Luraine authored
26
27 A [discussion group](http://groups.google.fr/group/limonade) is also available for more exchanges.
28
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
29
30 ## Routes ##
31
7538deb README file is now written in english
Fabrice Luraine authored
32 Routes combine an HTTP method with an URL matching pattern and a function
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
33
34 dispatch('/', 'my_get_function');
7538deb README file is now written in english
Fabrice Luraine authored
35 # same as dispatch_get('my_get_function');
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
36 function my_get_function()
37 {
38 // Show something
39 }
40
41 dispatch_post('/', 'my_post_function');
42 function my_post_function()
43 {
44 // Create something
45 }
46
47 dispatch_update('/', 'my_update_function');
48 function my_update_function()
49 {
50 // Update something
51 }
52
53 dispatch_delete('/', 'my_delete_function');
54 function my_delete_function()
55 {
56 // Delete something
57 }
7538deb README file is now written in english
Fabrice Luraine authored
58
59
60 Routes are matched in order they are declared.
61 The search is performed with a path given through browser URL:
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
62
63 http://localhost/my_app/?u=/my/path
64 http://localhost/my_app/?uri=/my/path
65 http://localhost/my_app/index.php?/my/path
66 http://localhost/my_app/index.php/my/path
67 http://localhost/my_app/?/my/path
bfd97ef Adding a note about the _method parameter.
Fabrice Luraine authored
68
69 When `PUT` or `DELETE` methods are not supported (like in HTML form submision), you can use the `_method` parameter in `POST` requests: it will override the `POST` method.
70
71 <form action="<?=url_for('profile_update')?>" method="post">
72 <p><input type="hidden" name="_method" value="PUT" id="_method"></p>
73 <p>... your form fields</p>
74 <p><input type="submit" value="Update"></p>
75 </form>
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
76
77 *[TODO]: url rewriting*
78
7538deb README file is now written in english
Fabrice Luraine authored
79 Patterns may include named parameters. Associated values of those parameters are available with the `params()` function.
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
80
81 dispatch('/hello/:name', 'hello');
82 function hello()
83 {
84 $name = params('name');
85 return 'Hello $name';
86 }
87
7538deb README file is now written in english
Fabrice Luraine authored
88 Patterns may also include wildcard parameters. Associated values are available through numeric indexes, in the same order as in the pattern.
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
89
90 dispatch('/writing/*/to/*', 'my_letter');
91 function my_letter()
92 {
93 # Matches /writing/an_email/to/joe
94 $type = params(0); # "an_email"
95 $name = params(1); # "joe"
96 # ...
97 }
98
99 dispatch('/files/*.*', 'share_files');
100 function share_files()
101 {
102 # matches /files/readme.txt
103 $ext = params(1);
104 $filename = params(0).".".$ext;
105 # ...
106 }
7538deb README file is now written in english
Fabrice Luraine authored
107
108 Unlike the simple wildcard character `*`, the double wildcard character `**` specifies a string that may contain a `/`
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
109
110 dispatch('/files/**', 'share_files')
111 function share_files()
112 {
113 # Matches /files/my/own/file.txt
114 $filename = params(0); # my/own/file.txt
115 }
116
7538deb README file is now written in english
Fabrice Luraine authored
117 Pattern may also be a regular expression if it begins with a `^`
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
118
119 dispatch('^/my/own/(\d+)/regexp', 'my_func');
120 function my_func()
121 {
122 # matches /my/own/12/regexp
123 $num = params(0);
124 }
125
7538deb README file is now written in english
Fabrice Luraine authored
126 Wildcard parameters and regular expressions may be named too.
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
127
128 dispatch(array('/say/*/to/**', array("what", "name")), 'my_func');
129 function my_func()
130 {
131 # Matches /say/hello/to/joe
132 $what = params('what');
133 $name = params('name');
134 }
7538deb README file is now written in english
Fabrice Luraine authored
135
136 Functions called by routes can be written anywhere before the execution of the `run()` function. They can also be grouped in controllers files stored in a `controllers/` folder.
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
137
138 / # site root
139 - index.php # file with routes declarations and run()
140 + controllers/
82c0951 Refactoring error function
Fabrice Luraine authored
141 - blog.php # functions for blog: blog_index(), blog_show(),
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
142 # blog_post()...
143 - comments.php # comments_for_a_post(), comment_add()...
144
145
146
7538deb README file is now written in english
Fabrice Luraine authored
147 This folder location can be set with the `controllers_dir` option.
148
149 option('controllers_dir', dirname(__FILE__).'/other/dir/for/controllers');
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
150
151
7538deb README file is now written in english
Fabrice Luraine authored
152 ## Views and templates ##
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
153
7538deb README file is now written in english
Fabrice Luraine authored
154 Template files are located by default in `views/` folder.
155 Views folder location can be set with the `views_dir` option.
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
156
82c0951 Refactoring error function
Fabrice Luraine authored
157 option('views_dir', dirname(__FILE__).'/other/dir/for/views');
158
7538deb README file is now written in english
Fabrice Luraine authored
159 To pass variables to templates, we use the function `set ()`
82c0951 Refactoring error function
Fabrice Luraine authored
160
161 set('name', 'John Doe');
162 render('index.html.php');
163
7538deb README file is now written in english
Fabrice Luraine authored
164 Variables may also be passed directly:
82c0951 Refactoring error function
Fabrice Luraine authored
165
166 render('index.html.php', null, array('name' => 'John Doe' ));
167
7538deb README file is now written in english
Fabrice Luraine authored
168
169
170 `set_or_default` function allows passing a variable, and if it's empty, a default value. It is really useful for the assignment of optional parameters extracted from the url using the `params()` function.
82c0951 Refactoring error function
Fabrice Luraine authored
171
172 dispatch('/hello/:name', 'hello');
173 function hello()
174 {
175 # matching /hello/
176 set_or_default('name', params('name'),'John');
177 return render('Hello %s!'); // returns 'Hello John!' because params('name') was empty. Else it would have return params('name') value.
178 }
179
180
181
182
183
184 ### Layouts ###
185
7538deb README file is now written in english
Fabrice Luraine authored
186 Templates may be rendered inside an other template: a layout.
82c0951 Refactoring error function
Fabrice Luraine authored
187
7538deb README file is now written in english
Fabrice Luraine authored
188 Layout may be set with the `layout` function:
82c0951 Refactoring error function
Fabrice Luraine authored
189
190 layout('default_layout.php');
7538deb README file is now written in english
Fabrice Luraine authored
191
192 or directly with the template rendering function
82c0951 Refactoring error function
Fabrice Luraine authored
193
194 render('index.html.php', 'default_layout.php');
7538deb README file is now written in english
Fabrice Luraine authored
195
196
197 If layout value is `null`, rendering will be done without any layout.
82c0951 Refactoring error function
Fabrice Luraine authored
198
199 render('index.html.php', null);
200
7538deb README file is now written in english
Fabrice Luraine authored
201 ### Formatted strings and inline templates ###
82c0951 Refactoring error function
Fabrice Luraine authored
202
7538deb README file is now written in english
Fabrice Luraine authored
203 Formatted string can be used like with [`sprintf`](http://php.net/manual/function.sprintf.php):
82c0951 Refactoring error function
Fabrice Luraine authored
204
205 set('num', 5);
206 set('tree');
207 render('There are %d monkeys in the %s') // returns 'There are 5 monkeys in the tree'
208
7538deb README file is now written in english
Fabrice Luraine authored
209 It's also possible to provide a function name as a template. By this way, we can for example produce a single file application.
82c0951 Refactoring error function
Fabrice Luraine authored
210
211 function html_message($vars){ extract($vars);?>
212 <h1>Title: <?=h($title)?></h1>
213 <p>Message:<br>
214 <?=h($msg)?></p>
215 <?}
216
7538deb README file is now written in english
Fabrice Luraine authored
217 // in a request handling function
82c0951 Refactoring error function
Fabrice Luraine authored
218 set('title', 'Hello!');
219 set('msg', 'There are 100 monkeys in the Chennai and bangalore');
220 render('html_message');
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
221
7538deb README file is now written in english
Fabrice Luraine authored
222 ### HTML Templates ###
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
223
7538deb README file is now written in english
Fabrice Luraine authored
224 `html` function is used in the same way as `render`.
225 A header specifies the proper HTTP `Content-type` (`text/html`) and encoding setting defined through options (utf8 by default).
82c0951 Refactoring error function
Fabrice Luraine authored
226
227 html('my_template.html.php');
228
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
229 ### Templates XML ###
230
7538deb README file is now written in english
Fabrice Luraine authored
231 `xml` function is used in the same way as `render`.
232 A header specifies the proper HTTP `Content-type` (`text/xml`) and encoding setting defined through options (utf8 by default).
233
234 html('my_template.xml.php');
82c0951 Refactoring error function
Fabrice Luraine authored
235
236 ### Templates CSS ###
237
7538deb README file is now written in english
Fabrice Luraine authored
238 `css` function is used in the same way as `render`.
239 A header specifies the proper HTTP `Content-type` (`text/css`) and encoding setting defined through options (utf8 by default).
82c0951 Refactoring error function
Fabrice Luraine authored
240
241 css('screen.css.php');
242
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
243 ### Templates TXT ###
244
7538deb README file is now written in english
Fabrice Luraine authored
245 `txt` function is used in the same way as `render`.
246 A header specifies the proper HTTP `Content-type` (`text/plain`) and encoding setting defined through options (utf8 by default).
82c0951 Refactoring error function
Fabrice Luraine authored
247
248 txt('index.txt.php');
249
250 ### Templates JSON ###
251
7538deb README file is now written in english
Fabrice Luraine authored
252 `json` is used the same way as
253 [`json_encode`](http://php.net/manual/function.json-encode.php) function, and returns a string containing the JSON representation of a value.
254 A header specifies the proper HTTP `Content-type` (`application/x-javascript`) and encoding setting defined through options (utf8 by default).
82c0951 Refactoring error function
Fabrice Luraine authored
255
256 json($my_data);
257
7538deb README file is now written in english
Fabrice Luraine authored
258 ### Serving files ###
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
259
7538deb README file is now written in english
Fabrice Luraine authored
260 The `render_file` function can render a file directly to the ouptut buffer.
cb74ce2 Complete README file
Fabrice Luraine authored
261
262 render_file(option('public_dir').'foo.jpg');
263
7538deb README file is now written in english
Fabrice Luraine authored
264 A header specifies the proper HTTP `Content-type` depending on the file extension and, for text files, encoding setting defined through options (utf8 by default) .
cb74ce2 Complete README file
Fabrice Luraine authored
265
7538deb README file is now written in english
Fabrice Luraine authored
266 Output is temporized so that it can easily handle large files.
82c0951 Refactoring error function
Fabrice Luraine authored
267
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
268 ### Captures ###
269
cb74ce2 Complete README file
Fabrice Luraine authored
270 [TODO] `content_for($name); endcontent();`
271
7538deb README file is now written in english
Fabrice Luraine authored
272 ## Before and after request ##
cb74ce2 Complete README file
Fabrice Luraine authored
273
7538deb README file is now written in english
Fabrice Luraine authored
274 You can define a `before` function that will be executed before each request. This is very useful to define a default layout or passing common variables to the templates
cb74ce2 Complete README file
Fabrice Luraine authored
275
276 function before()
277 {
278 layout('default_layout.php');
279 set('site_title', 'My Website');
280 }
281
7538deb README file is now written in english
Fabrice Luraine authored
282
283 An `after` output filter is also available. It's executed after each request and can apply a transformation to the output (except for `render_file` outputs which are sent directly to the output buffer).
cb74ce2 Complete README file
Fabrice Luraine authored
284
285 function after($output){
286 $config = array('indent' => TRUE,
287 'output-xhtml' => TRUE,
288 'wrap' => 200);
289
290 $tidy = tidy_parse_string($output, $config, option('encoding'));
291 return $tidy->cleanRepair();
292 }
293
294 ## Configuration ##
295
7538deb README file is now written in english
Fabrice Luraine authored
296 You can define a `configure` that will be executed when application is launched (at the begining of the `run` execution ).
297 You can define options inside it, a connection to a database ...
cb74ce2 Complete README file
Fabrice Luraine authored
298
299 function configure()
300 {
301 $env = $_SERVER['HTTP_HOST'] == "localhost" ? ENV_DEVELOPMENT : ENV_PRODUCTION;
302 option('env', $env);
303 if(option('env') > ENV_PRODUCTION)
304 {
305 options('dsn', 'sqlite:db/development.db'));
306 }
307 else
308 {
309 options('dsn', 'sqlite:db/production.db'));
310 }
311 $GLOBALS['my_db_connexion'] = new PDO(option('dsn'));
312 }
313
7538deb README file is now written in english
Fabrice Luraine authored
314 PHP files contained in the `option('lib_dir')` folder (`lib/` by default) are loaded with [`require_once`](http://php.net/manual/function.require-once.php) just before executing `configure`. So you can place in this folder all your PHP librairies an functions so that they will be loaded and available at application launch.
cb74ce2 Complete README file
Fabrice Luraine authored
315
7538deb README file is now written in english
Fabrice Luraine authored
316 ## Options ##
cb74ce2 Complete README file
Fabrice Luraine authored
317
7538deb README file is now written in english
Fabrice Luraine authored
318 The `option` function allows you to define and access the options of the application.
cb74ce2 Complete README file
Fabrice Luraine authored
319
320 option('env', ENV_PRODUCTION);
321 option('env'); // return ENV_PRODUCTION value
322
7538deb README file is now written in english
Fabrice Luraine authored
323 If the name of option is not specified, it returns an array of all the options set.
cb74ce2 Complete README file
Fabrice Luraine authored
324
7538deb README file is now written in english
Fabrice Luraine authored
325 You can use it to manage Limonade options and your own custom options in your application.
cb74ce2 Complete README file
Fabrice Luraine authored
326
7538deb README file is now written in english
Fabrice Luraine authored
327 Default Limonade options have the following values:
cb74ce2 Complete README file
Fabrice Luraine authored
328
7538deb README file is now written in english
Fabrice Luraine authored
329 option('root_dir', $root_dir); // this folder contains your main application file
330 option('limonade_dir', dirname(__FILE__).'/'); // this folder contains limonade.php main file
cb74ce2 Complete README file
Fabrice Luraine authored
331 option('public_dir', option('root_dir').'/public/');
332 option('views_dir', option('root_dir').'/views/');
333 option('controllers_dir', option('root_dir').'/controllers/');
334 option('lib_dir', option('root_dir').'/lib/');
335 option('env', ENV_PRODUCTION);
336 option('debug', true);
337 option('encoding', 'utf-8');
338 option('x-sendfile', 0); // 0: disabled,
339 // X-SENDFILE: for Apache and Lighttpd v. >= 1.5,
340 // X-LIGHTTPD-SEND-FILE: for Apache and Lighttpd v. < 1.5
341
7538deb README file is now written in english
Fabrice Luraine authored
342 ## Halting and error handling ##
cb74ce2 Complete README file
Fabrice Luraine authored
343
344 ### Halt ###
345
7538deb README file is now written in english
Fabrice Luraine authored
346 You can stop immediatly the execution of the application with the `halt` function. Errors will be handled by default Limonade error handlers or those you have defined.
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
347
cb74ce2 Complete README file
Fabrice Luraine authored
348 halt(NOT_FOUND);
349 halt("En error occured in my app...");
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
350
cb74ce2 Complete README file
Fabrice Luraine authored
351 ### Not Found ###
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
352
7538deb README file is now written in english
Fabrice Luraine authored
353 By default, displays the `not_found` error output function and sends a _`404 NOT FOUND`_ HTTP header.
cb74ce2 Complete README file
Fabrice Luraine authored
354
355 halt(NOT_FOUND);
356 halt(NOT_FOUND, "This product doesn't exists.");
357
7538deb README file is now written in english
Fabrice Luraine authored
358 To define a new view for this error, you can simply declare a `not_found` function
cb74ce2 Complete README file
Fabrice Luraine authored
359
360 function not_found($errno, $errstr, $errfile=null, $errline=null)
361 {
362 set('errno', $errno);
363 set('errstr', $errstr);
364 set('errfile', $errfile);
365 set('errline', $errline);
366 return html("show_not_found_errors.html.php");
367 }
368
369 ### Server Error ###
370
7538deb README file is now written in english
Fabrice Luraine authored
371 By default, displays the `server_error` error output function and sends a _`500 INTERNAL SERVER ERROR`_ HTTP header.
cb74ce2 Complete README file
Fabrice Luraine authored
372
373 halt();
374 halt('Breaking bad!');
375 halt(SERVER_ERROR, "Not good...");
376 trigger_error("Wrong parameter", E_USER_ERROR);
377
7538deb README file is now written in english
Fabrice Luraine authored
378 PHP errors are also caught en sent to this error handler output.
cb74ce2 Complete README file
Fabrice Luraine authored
379
7538deb README file is now written in english
Fabrice Luraine authored
380 To define a new view for this error, you can simply declare a `server_error` function
cb74ce2 Complete README file
Fabrice Luraine authored
381
382 function server_error($errno, $errstr, $errfile=null, $errline=null)
383 {
384 $args = compact('errno', 'errstr', 'errfile', 'errline');
385 return html("show_server_errors.html.php", error_layout(), $args);
386 }
387
388 ### Error layout ###
389
7538deb README file is now written in english
Fabrice Luraine authored
390 Allows you to define and access a layout dedicated to errors.
cb74ce2 Complete README file
Fabrice Luraine authored
391
392 error_layout('error_layout.php');
393 error_layout(); // return 'error_layout.php'
394
7538deb README file is now written in english
Fabrice Luraine authored
395 ### Error handling ###
cb74ce2 Complete README file
Fabrice Luraine authored
396
7538deb README file is now written in english
Fabrice Luraine authored
397 In addition to the common `NOT_FOUND` and `SERVER_ERROR` errors displays, Limonade can redirect precisely errors to your own functions.
cb74ce2 Complete README file
Fabrice Luraine authored
398
399 error(E_USER_WARNING, 'my_notices')
400 function my_notices($errno, $errstr, $errfile, $errline)
401 {
402 // storing php warnings in a log file
403 // ...
404 status(SERVER_ERROR);
405 return html('<h1>Server Error</h1>');
406 }
407
7538deb README file is now written in english
Fabrice Luraine authored
408 `E_LIM_HTTP` means all HTTP errors
cb74ce2 Complete README file
Fabrice Luraine authored
409
410 error(E_LIM_HTTP, 'my_http_errors')
411 function my_http_errors($errno, $errstr, $errfile, $errline)
412 {
413 status($errno);
414 return html('<h1>'.http_response_status_code($errno).'</h1>');
415 }
416
7538deb README file is now written in english
Fabrice Luraine authored
417 `E_LIM_PHP` means all PHP errors (sended by PHP or raised by the user through [`trigger_error`](http://php.net/manual/function.trigger-error.php) function).
cb74ce2 Complete README file
Fabrice Luraine authored
418
419 ## Testing ##
420
421 [TODO]
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
422
77c05cd Small changes in readme
Fabrice Luraine authored
423 ## More ##
a4cbafb Adding project links
Fabrice Luraine authored
424
fe8928f Fixing website, examples and code sources urls
Fabrice Luraine authored
425 * [Limonade web site](http://limonade.sofa-design.net/)
77c05cd Small changes in readme
Fabrice Luraine authored
426 * [Issue tracking / release planning](http://sofadesign.lighthouseapp.com/projects/29612-limonade/overview)
365eb86 Fixing project links format
Fabrice Luraine authored
427 * [Support / Discussions](http://groups.google.fr/group/limonade)
a4cbafb Adding project links
Fabrice Luraine authored
428
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
429
430
431
432
433
Something went wrong with that request. Please try again.