Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 731 lines (493 sloc) 25.512 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
ece681b Updating camping url in readme files
Fabrice Luraine authored
5 It's inspired by frameworks like [Sinatra](http://www.sinatrarb.com/) or [Camping](http://github.com/camping/camping) 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
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
23 This document provides a quick, but comprehensive, guide of Limonade features.
c75e9da Adding a "about this file" section in readme files
Fabrice Luraine authored
24
88dfe7c Updating limonade links with the new limonade-php.net domain
Fabrice Luraine authored
25 For more informations, you can see the [website](http://www.limonade-php.net/),
26 [public API documentation](http://www.limonade-php.net/api/), [examples](http://www.limonade-php.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
27
28 A [discussion group](http://groups.google.fr/group/limonade) is also available for more exchanges.
29
0906634 Add requirements in README [#50 state:resolved]
Fabrice Luraine authored
30 ## Requirements ##
31
32 * PHP 5.1.6 > (successfully tested with PHP 5.1.6 but it might work with older versions)
33
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
34 ## Routes ##
35
269903d Use explicitly 'callback' pseudo-type instead of 'function'.
Fabrice Luraine authored
36 Routes combine
37
38 * an HTTP method
39 * with an URL matching pattern
40 * and a callback parameter
41
42 So they make the glue between an URL + a HTTP method, and the code provided in a callback controller.
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
43
44 dispatch('/', 'my_get_function');
7538deb README file is now written in english
Fabrice Luraine authored
45 # same as dispatch_get('my_get_function');
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
46 function my_get_function()
47 {
48 // Show something
269903d Use explicitly 'callback' pseudo-type instead of 'function'.
Fabrice Luraine authored
49 // with the code of this callback controller
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
50 }
51
52 dispatch_post('/', 'my_post_function');
53 function my_post_function()
54 {
55 // Create something
56 }
57
744a4da Fixing README dispatch_put example
Fabrice Luraine authored
58 dispatch_put('/', 'my_update_function');
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
59 function my_update_function()
60 {
61 // Update something
62 }
63
64 dispatch_delete('/', 'my_delete_function');
65 function my_delete_function()
66 {
67 // Delete something
68 }
7538deb README file is now written in english
Fabrice Luraine authored
69
70
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
71 Routes are matched in the order they are declared.
7538deb README file is now written in english
Fabrice Luraine authored
72 The search is performed with a path given through browser URL:
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
73
74 http://localhost/my_app/?u=/my/path
75 http://localhost/my_app/?uri=/my/path
76 http://localhost/my_app/index.php?/my/path
77 http://localhost/my_app/?/my/path
bfd97ef Adding a note about the _method parameter.
Fabrice Luraine authored
78
79 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.
80
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
81 <form action="<?php echo url_for('profile_update'); ?>" method="post">
bfd97ef Adding a note about the _method parameter.
Fabrice Luraine authored
82 <p><input type="hidden" name="_method" value="PUT" id="_method"></p>
83 <p>... your form fields</p>
84 <p><input type="submit" value="Update"></p>
85 </form>
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
86
b987095 Add documentation and tests about route optional default parameters.
Fabrice Luraine authored
87 ### Routing patterns and parameters ###
269903d Use explicitly 'callback' pseudo-type instead of 'function'.
Fabrice Luraine authored
88
7538deb README file is now written in english
Fabrice Luraine authored
89 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
90
91 dispatch('/hello/:name', 'hello');
b987095 Add documentation and tests about route optional default parameters.
Fabrice Luraine authored
92 function hello()
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
93 {
94 $name = params('name');
95 return 'Hello $name';
96 }
97
7538deb README file is now written in english
Fabrice Luraine authored
98 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
99
100 dispatch('/writing/*/to/*', 'my_letter');
101 function my_letter()
102 {
103 # Matches /writing/an_email/to/joe
104 $type = params(0); # "an_email"
105 $name = params(1); # "joe"
106 # ...
107 }
108
109 dispatch('/files/*.*', 'share_files');
110 function share_files()
111 {
112 # matches /files/readme.txt
113 $ext = params(1);
114 $filename = params(0).".".$ext;
115 # ...
116 }
7538deb README file is now written in english
Fabrice Luraine authored
117
118 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
119
120 dispatch('/files/**', 'share_files')
121 function share_files()
122 {
123 # Matches /files/my/own/file.txt
124 $filename = params(0); # my/own/file.txt
125 }
126
7538deb README file is now written in english
Fabrice Luraine authored
127 Pattern may also be a regular expression if it begins with a `^`
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
128
129 dispatch('^/my/own/(\d+)/regexp', 'my_func');
130 function my_func()
131 {
132 # matches /my/own/12/regexp
133 $num = params(0);
134 }
135
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
136 Wildcard parameters and regular expressions may be named, too.
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
137
138 dispatch(array('/say/*/to/**', array("what", "name")), 'my_func');
139 function my_func()
140 {
141 # Matches /say/hello/to/joe
142 $what = params('what');
143 $name = params('name');
144 }
7538deb README file is now written in english
Fabrice Luraine authored
145
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
146 You can also provide default parameter values that are merged with and overriden by the pattern parameters.
b987095 Add documentation and tests about route optional default parameters.
Fabrice Luraine authored
147
148 $options = array('params' => array('firstname'=>'bob'));
149 dispatch('/hello/:name', 'hello', $options);
150 function hello($firstname, $name) # default parameters first
151 {
152 return 'Hello $firstname $name';
153 }
154
155
269903d Use explicitly 'callback' pseudo-type instead of 'function'.
Fabrice Luraine authored
156 ### Callback controllers ###
157
158 The callback can be a function, an object method, a static method or a closure.
159 See [php documentation](http://php.net/manual/en/language.pseudo-types.php#language.types.callback) to learn more about the callback pseudo-type.
160
161 # will call my_hello_function() function
162 dispatch('/hello', 'my_hello_function');
163
164 # Static class method call, MyClass::hello();
165 dispatch('/hello', array('MyClass', 'hello'));
166
167 # Object method call, $obj->hello();
168 dispatch('/hello', array($obj, 'hello'));
169
170 # Static class method call (As of PHP 5.2.3), MyClass::hello();
171 dispatch('/hello', 'MyClass::hello');
172
173 # Using lambda function (As of PHP 5.3.0)
174 dispatch('/hello', function(){
175 return 'Hello World!';
176 });
177
178 Callback controllers return the rendered view output (see _Views and templates_).
179
b987095 Add documentation and tests about route optional default parameters.
Fabrice Luraine authored
180 They can take the pattern parameters as arguments
181
182 dispatch('/hello/:firstname/:name', 'hello');
183 function hello($firstname, $name)
184 {
185 # $firstname parameter equals params('firstname');
186 # and $name parameter equals params('name');
187 return 'Hello $firstname $name';
188 }
189
190
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
191 Callbacks called by routes can be written anywhere before the execution of the `run()` function. They can also be grouped in controller files stored in a `controllers/` folder.
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
192
193 / # site root
194 - index.php # file with routes declarations and run()
195 + controllers/
82c0951 Refactoring error function
Fabrice Luraine authored
196 - blog.php # functions for blog: blog_index(), blog_show(),
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
197 # blog_post()...
198 - comments.php # comments_for_a_post(), comment_add()...
199
200
201
7538deb README file is now written in english
Fabrice Luraine authored
202 This folder location can be set with the `controllers_dir` option.
203
204 option('controllers_dir', dirname(__FILE__).'/other/dir/for/controllers');
d7a66f1 Explain autoload_controller user defined function in README
Fabrice Luraine authored
205
206
207 You can also define `autoload_controller` function to load controllers in your own way:
208
209 function autoload_controller($callback)
210 {
211 # If $callback, the callback function defined in matching route,
212 # begins with 'admin_', then we load controllers from
213 # the admin sub-directory in the controllers directory.
214 # Else we load controllers the normal way from 'controllers_dir'.
215
216 $path = option('controllers_dir');
217 if(strpos($callback, "admin_") === 0) $path = file_path($path, 'admin');
218 require_once_dir($path);
219 }
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
220
a25bd2f Update CHANGES and README files
Fabrice Luraine authored
221 ### Url rewriting ###
222
223 Since version 0.4.1, Limonade supports url rewriting.
224
225 With a `.htaccess` in your app folder
226
227 <IfModule mod_rewrite.c>
228 Options +FollowSymlinks
229 Options +Indexes
230 RewriteEngine on
ee119cf Fix htaccess in README: comments may not be included on a line after a c...
Fabrice Luraine authored
231
232 # if your app is in a subfolder
233 # RewriteBase /my_app/
a25bd2f Update CHANGES and README files
Fabrice Luraine authored
234
235 # test string is a valid files
236 RewriteCond %{SCRIPT_FILENAME} !-f
237 # test string is a valid directory
238 RewriteCond %{SCRIPT_FILENAME} !-d
239
a256b36 Improving htaccess rules to support clean urls with query string like
Fabrice Luraine authored
240 RewriteRule ^(.*)$ index.php?uri=/$1 [NC,L,QSA]
241 # with QSA flag (query string append),
242 # forces the rewrite engine to append a query string part of the
243 # substitution string to the existing string, instead of replacing it.
a25bd2f Update CHANGES and README files
Fabrice Luraine authored
244 </IfModule>
245
246 And setting explicitly the `option('base_uri')` in your configure() function:
247
248 option('base_uri', '/my_app'); # '/' or same as the RewriteBase in your .htaccess
249
250 You can access your site with urls like `http://your.new-website.com/my/limonade/path` instead of `http://your.new-website.com/?/my/limonade/path`.
251
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
252
7538deb README file is now written in english
Fabrice Luraine authored
253 ## Views and templates ##
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
254
7538deb README file is now written in english
Fabrice Luraine authored
255 Template files are located by default in `views/` folder.
256 Views folder location can be set with the `views_dir` option.
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
257
82c0951 Refactoring error function
Fabrice Luraine authored
258 option('views_dir', dirname(__FILE__).'/other/dir/for/views');
259
7538deb README file is now written in english
Fabrice Luraine authored
260 To pass variables to templates, we use the function `set ()`
82c0951 Refactoring error function
Fabrice Luraine authored
261
262 set('name', 'John Doe');
263 render('index.html.php');
264
7538deb README file is now written in english
Fabrice Luraine authored
265 Variables may also be passed directly:
82c0951 Refactoring error function
Fabrice Luraine authored
266
267 render('index.html.php', null, array('name' => 'John Doe' ));
268
7538deb README file is now written in english
Fabrice Luraine authored
269
270
271 `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
272
273 dispatch('/hello/:name', 'hello');
274 function hello()
275 {
276 # matching /hello/
277 set_or_default('name', params('name'),'John');
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
278 return render('Hello %s!'); // returns 'Hello John!' because params('name') was empty. Else it would have returned params('name') value.
82c0951 Refactoring error function
Fabrice Luraine authored
279 }
280
68ee608 Adding a note about controller output
Fabrice Luraine authored
281 As you can notice, final output is returned by your controller. So remember to explicitly return your view in your controller with the `return` keyword! *(This remark will be particularly helpful for rubyists ;-) )*
82c0951 Refactoring error function
Fabrice Luraine authored
282
283
284
285 ### Layouts ###
286
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
287 Templates may be rendered inside another template: a layout.
82c0951 Refactoring error function
Fabrice Luraine authored
288
7538deb README file is now written in english
Fabrice Luraine authored
289 Layout may be set with the `layout` function:
82c0951 Refactoring error function
Fabrice Luraine authored
290
291 layout('default_layout.php');
7538deb README file is now written in english
Fabrice Luraine authored
292
293 or directly with the template rendering function
82c0951 Refactoring error function
Fabrice Luraine authored
294
295 render('index.html.php', 'default_layout.php');
7538deb README file is now written in english
Fabrice Luraine authored
296
297
298 If layout value is `null`, rendering will be done without any layout.
82c0951 Refactoring error function
Fabrice Luraine authored
299
300 render('index.html.php', null);
301
7538deb README file is now written in english
Fabrice Luraine authored
302 ### Formatted strings and inline templates ###
82c0951 Refactoring error function
Fabrice Luraine authored
303
7538deb README file is now written in english
Fabrice Luraine authored
304 Formatted string can be used like with [`sprintf`](http://php.net/manual/function.sprintf.php):
82c0951 Refactoring error function
Fabrice Luraine authored
305
306 set('num', 5);
269903d Use explicitly 'callback' pseudo-type instead of 'function'.
Fabrice Luraine authored
307 set('where', 'tree');
68ee608 Adding a note about controller output
Fabrice Luraine authored
308 return render('There are %d monkeys in the %s') // returns 'There are 5 monkeys in the tree'
82c0951 Refactoring error function
Fabrice Luraine authored
309
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
310 It's also possible to provide a function name as a template. By this way, for example, we can produce a single file application.
82c0951 Refactoring error function
Fabrice Luraine authored
311
312 function html_message($vars){ extract($vars);?>
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
313 <h1>Title: <?php echo h($title); ?></h1>
82c0951 Refactoring error function
Fabrice Luraine authored
314 <p>Message:<br>
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
315 <?php echo h($msg); ?></p>
82c0951 Refactoring error function
Fabrice Luraine authored
316 <?}
317
7538deb README file is now written in english
Fabrice Luraine authored
318 // in a request handling function
82c0951 Refactoring error function
Fabrice Luraine authored
319 set('title', 'Hello!');
320 set('msg', 'There are 100 monkeys in the Chennai and bangalore');
68ee608 Adding a note about controller output
Fabrice Luraine authored
321 return render('html_message');
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
322
7538deb README file is now written in english
Fabrice Luraine authored
323 ### HTML Templates ###
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
324
7538deb README file is now written in english
Fabrice Luraine authored
325 `html` function is used in the same way as `render`.
326 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
327
328 html('my_template.html.php');
329
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
330 ### Templates XML ###
331
7538deb README file is now written in english
Fabrice Luraine authored
332 `xml` function is used in the same way as `render`.
333 A header specifies the proper HTTP `Content-type` (`text/xml`) and encoding setting defined through options (utf8 by default).
334
e4c8ee2 Fix wrong example for xml() section in the README [#54 state:resolved]
Fabrice Luraine authored
335 xml('my_template.xml.php');
82c0951 Refactoring error function
Fabrice Luraine authored
336
337 ### Templates CSS ###
338
7538deb README file is now written in english
Fabrice Luraine authored
339 `css` function is used in the same way as `render`.
340 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
341
342 css('screen.css.php');
343
7794b5f @kematzy Added support for js() output.
kematzy authored
344 ### Templates JS ###
345
346 `js` function is used in the same way as `render`.
347 A header specifies the proper HTTP `Content-type` (`application/javascript`) and encoding setting defined through options (utf8 by default).
348
349 js('app.js.php');
350
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
351 ### Templates TXT ###
352
7538deb README file is now written in english
Fabrice Luraine authored
353 `txt` function is used in the same way as `render`.
354 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
355
356 txt('index.txt.php');
357
358 ### Templates JSON ###
359
7538deb README file is now written in english
Fabrice Luraine authored
360 `json` is used the same way as
361 [`json_encode`](http://php.net/manual/function.json-encode.php) function, and returns a string containing the JSON representation of a value.
362 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
363
364 json($my_data);
365
7538deb README file is now written in english
Fabrice Luraine authored
366 ### Serving files ###
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
367
7538deb README file is now written in english
Fabrice Luraine authored
368 The `render_file` function can render a file directly to the ouptut buffer.
cb74ce2 Complete README file
Fabrice Luraine authored
369
370 render_file(option('public_dir').'foo.jpg');
371
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
372 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
373
7538deb README file is now written in english
Fabrice Luraine authored
374 Output is temporized so that it can easily handle large files.
82c0951 Refactoring error function
Fabrice Luraine authored
375
92734d3 Add tests and documentation for `partial` function
Fabrice Luraine authored
376 ### Partials ###
377
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
378 The `partial` function is a shortcut to render with no layout. Useful for managing reusable blocks and keeping them in separate files.
92734d3 Add tests and documentation for `partial` function
Fabrice Luraine authored
379
380 This code
381
382 partial('my_posts.php', array('posts'=>$posts));
383
384 is the same as
385
386 render('my_posts.php', null, array('posts'=>$posts));
387
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
388 ### Captures ###
389
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
390 The `content_for` function allows you to capture a block of text in a view. Then the captured block will be available for the layout. This is useful for management of layout regions like a sidebar or to set javascript or stylesheet files that are specific to a view.
1b93974 Add tests and documentation for captures in views
Fabrice Luraine authored
391
392
393 For example with this layout:
394
395 <div id="content">
396 <div id="main">
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
397 <?php echo $content; ?>
1b93974 Add tests and documentation for captures in views
Fabrice Luraine authored
398 </div>
399 <div id="side">
400 <?php if (isset($side)) echo $side; ?>
401 </div>
402 </div>
403
404 And in your view:
405
406 <p>My main content</p>
407
408 <?php content_for('side'); ?>
409 <ul>
410 <li><a href="<?php echo url_for('/pages/item1')?>">Item 1</a></li>
411 <li><a href="<?php echo url_for('/pages/item2')?>">Item 2</a></li>
412 </ul>
413 <?php end_content_for(); ?>
414
415 Rendered result is:
416
417 <div id="content">
418 <div id="main">
419 <p>My main content</p>
420 </div>
421 <div id="side">
422 <ul>
423 <li><a href="?/pages/item1">Item 1</a></li>
424 <li><a href="?/pages/item1">Item 2</a></li>
425 </ul>
426 </div>
427 </div>
428
429
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
430 The above example is detailed in [this tutorial](http://blog.limonade-php.net/post/438674987/how-to-use-content-for-and-partial).
cb74ce2 Complete README file
Fabrice Luraine authored
431
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
432 Use captures with partials, it will help you to organize your views and will keep you from having to copy/paste the same code many times.
92734d3 Add tests and documentation for `partial` function
Fabrice Luraine authored
433
8c01314 Initiate a "Hooks and filters" section in documentation.
Fabrice Luraine authored
434 ## Hooks and filters ##
435
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
436 Limonade allows the user to define some functions to enhance the Limonade behaviour with its own needs.
8c01314 Initiate a "Hooks and filters" section in documentation.
Fabrice Luraine authored
437
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
438 Some of those, like the `before` hook and the `after` filter are commonly used, and others are only for advanced usage that might require a good comprehension of Limonade internals.
8c01314 Initiate a "Hooks and filters" section in documentation.
Fabrice Luraine authored
439
cb74ce2 Complete README file
Fabrice Luraine authored
440
57d7632 Better autorender feature (option('autorender') is no longer required) +...
Fabrice Luraine authored
441 ### Before ###
442
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
443 You can define a `before` function that will be executed before each request. This is very useful to define a default layout or for passing common variables to the templates.
cb74ce2 Complete README file
Fabrice Luraine authored
444
3a6534a Passing $route to the after($output, $route) abstract function. Adding ...
Fabrice Luraine authored
445 function before($route)
cb74ce2 Complete README file
Fabrice Luraine authored
446 {
447 layout('default_layout.php');
448 set('site_title', 'My Website');
449 }
450
57d7632 Better autorender feature (option('autorender') is no longer required) +...
Fabrice Luraine authored
451
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
452 The current matching route is also passed to the before function, so you can test it. It's an array as returned by the internal `route_find` function, with these values:
3a6534a Passing $route to the after($output, $route) abstract function. Adding ...
Fabrice Luraine authored
453
454 * `method` (HTTP method)
455 * `pattern` (regexp pattern)
456 * `names` (params names)
269903d Use explicitly 'callback' pseudo-type instead of 'function'.
Fabrice Luraine authored
457 * `callback` (callback)
3a6534a Passing $route to the after($output, $route) abstract function. Adding ...
Fabrice Luraine authored
458 * `options` (route options)
459 * `params` (current params)
7538deb README file is now written in english
Fabrice Luraine authored
460
57d7632 Better autorender feature (option('autorender') is no longer required) +...
Fabrice Luraine authored
461 ### After ###
462
7538deb README file is now written in english
Fabrice Luraine authored
463 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
464
8202fee Fix after($output) example in README [#42 state:resolved]
Fabrice Luraine authored
465 function after($output){
466 $config = array('indent' => TRUE,
467 'output-xhtml' => TRUE,
468 'wrap' => 200);
469
470 $encoding = strtoupper(str_replace('-','', option('encoding')));
471 $tidy = tidy_parse_string($output, $config, $encoding);
472 $tidy->cleanRepair();
473 return $tidy;
cb74ce2 Complete README file
Fabrice Luraine authored
474 }
3a6534a Passing $route to the after($output, $route) abstract function. Adding ...
Fabrice Luraine authored
475
476 The current executed route is also available for `after` function.
cb74ce2 Complete README file
Fabrice Luraine authored
477
8c01314 Initiate a "Hooks and filters" section in documentation.
Fabrice Luraine authored
478 ### Before render ###
479
480 You can define a `before_render` function that will filter your view before rendering it.
481
482 The first three parameters are the same as those passed to the `render` function:
483
484 * `$content_or_func`: the view string
485 * `$layout`: current layout path
486 * `$locals`: variables passed directly to the `render` function
487
488 Last parameter, `$view_path` is by default `file_path(option('views_dir'), $content_or_func);`
489
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
490 function before_render($content_or_func, $layout, $locals, $view_path)
491 {
492 # Transform $content_or_func, $layout, $locals or $view_path.
493 # Then return there new values
494 return array($content_or_func, $layout, $locals, $view_path);
495 }
496
497 ### Autorender ###
498
499 You can define your own `autorender` function to make automatic rendering depending on current matching route. It will be executed if your controller returns a null output.
500
501 dispatch('/', 'hello');
502 function hello()
503 {
504 # process some stuff...
505 set('name', 'Bob');
506
507 # but don't return anything
508 # ( like if you were ending this function with return null; )
509 }
510
511 function autorender($route)
512 {
513 $view = $route['callback'] . ".html.php";
514 return html($view);
515 }
516
517 In this example, when url `/` is called, `hello()` is executed and then `autorender()` renders the matching `hello.html.php` view.
518
519 ### Before exit ###
520
521 If you define a `before_exit`, it is called at the begining of the stop/exit process (`stop_and_exit` function called automatically at Limonade application termination).
522
523 function before_exit($exit)
524 {
525 # $exit is the same parameter as the one passed to `stop_and_exit`.
526 # If it's false, the exit process will not be executed,
527 # only the stop instructions
528 # by default it is true
529 }
530
039e699 @CBeerta Add `inspect_header`to allow inspection of headers beeing sent.
CBeerta authored
531 ### Inspecting Headers that are being sent ###
532
533 You can define a `inspect_header` function that will be called before Limonade emits a header() call. This way you can add additional Headers:
534
535 dispatch('/style.css', 'css');
536 function css()
537 {
538 # Generate css file and output
539 return css('style.css.php');
540 }
541
542 function inspect_header($header)
543 {
544 if (strpos($header, 'text/css') !== false)
545 {
546 # intercept text/css content-type and add caching to the headers
547 header("Cache-Control: max-age=600, public");
548 }
549 }
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
550
551 ## Configuration ##
552
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
553 You can define a `configure` that will be executed when application is launched (at the begining of the `run` execution).
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
554 You can define options inside it, a connection to a database ...
555
556 function configure()
557 {
558 $env = $_SERVER['HTTP_HOST'] == "localhost" ? ENV_DEVELOPMENT : ENV_PRODUCTION;
559 option('env', $env);
560 if(option('env') > ENV_PRODUCTION)
561 {
562 options('dsn', 'sqlite:db/development.db'));
563 }
564 else
565 {
566 options('dsn', 'sqlite:db/production.db'));
567 }
568 $GLOBALS['my_db_connexion'] = new PDO(option('dsn'));
569 }
570
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
571 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 libraries and functions so that they will be loaded and available at application launch.
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
572
573 ## Options ##
574
575 The `option` function allows you to define and access the options of the application.
576
577 option('env', ENV_PRODUCTION);
578 option('env'); // return ENV_PRODUCTION value
579
580 If the name of option is not specified, it returns an array of all the options set.
581
582 You can use it to manage Limonade options and your own custom options in your application.
583
584 Default Limonade options have the following values:
585
586 option('root_dir', $root_dir); // this folder contains your main application file
587 option('base_path', $base_path);
588 option('base_uri', $base_uri); // set it manually if you use url_rewriting
589 option('limonade_dir', dirname(__FILE__).'/'); // this fiolder contains the limonade.php main file
590 option('limonade_views_dir', dirname(__FILE__).'/limonade/views/');
591 option('limonade_public_dir',dirname(__FILE__).'/limonade/public/');
592 option('public_dir', $root_dir.'/public/');
593 option('views_dir', $root_dir.'/views/');
594 option('controllers_dir', $root_dir.'/controllers/');
595 option('lib_dir', $root_dir.'/lib/');
596 option('error_views_dir', option('limonade_views_dir'));
597 option('env', ENV_PRODUCTION);
598 option('debug', true);
599 option('session', LIM_SESSION_NAME); // true, false or the name of your session
600 option('encoding', 'utf-8');
601 option('x-sendfile', 0); // 0: disabled,
602 // X-SENDFILE: for Apache and Lighttpd v. >= 1.5,
603 // X-LIGHTTPD-SEND-FILE: for Apache and Lighttpd v. < 1.5
604
605 ## Sessions ##
606
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
607 Session starts automatically by default. Then you can access session variables like you used to do, with `$_SESSION` array.
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
608
609 You can disable sessions with the `session` option.
610
611 ⌘ [see snippet example](http://gist.github.com/159327)
612
613 ### Flash ###
614
615 Flash is a special use of sessions. A flash value will be available only on next request and will be deleted after. It's very useful to raise errors on a form or to notice a successful action.
616
617 * `flash($name, $value...)` defines a flash for the next request
618 * in views, you can get current flash values with the `$flash` array or `flash_now($name)` function.
619
620 ⌘ [see snippet example](http://gist.github.com/162680)
621
622 ## Helpers ##
623
624 See sources or api for more about all available helpers.
625
626 ### url_for ###
627
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
628 You can use the `url_for` function for rendering limonade urls. They will be well formed from whatever folder in the document root your application is installed on your web server.
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
629
630 # with option('base_uri', '?')
631 url_for('one', 'two', 'three'); # returns ?/one/two/three
632 url_for('one', 'two', array('page' => 1)); # returns ?/one/two&amp;page=2
633
634
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
635 If you want to use url rewriting, you need to explicitly set the `base_uri` option ( default is `/your_file_path/?`)
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
636
637
638 ## Halting and error handling ##
639
640 ### Halt ###
641
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
642 You can stop immediately the execution of the application with the `halt` function. Errors will be handled by default Limonade error handlers or those you have defined.
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
643
644 halt(NOT_FOUND);
645 halt("En error occured in my app...");
646
647 ### Not Found ###
648
649 By default, displays the `not_found` error output function and sends a _`404 NOT FOUND`_ HTTP header.
650
651 halt(NOT_FOUND);
652 halt(NOT_FOUND, "This product doesn't exists.");
653
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
654 To define a new view for this error, you can simply declare a `not_found` function.
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
655
656 function not_found($errno, $errstr, $errfile=null, $errline=null)
657 {
658 set('errno', $errno);
659 set('errstr', $errstr);
660 set('errfile', $errfile);
661 set('errline', $errline);
662 return html("show_not_found_errors.html.php");
663 }
664
665 ### Server Error ###
666
667 By default, displays the `server_error` error output function and sends a _`500 INTERNAL SERVER ERROR`_ HTTP header.
668
669 halt();
670 halt('Breaking bad!');
671 halt(SERVER_ERROR, "Not good...");
672 trigger_error("Wrong parameter", E_USER_ERROR);
673
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
674 PHP errors are also caught and sent to this error handler output.
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
675
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
676 To define a new view for this error, you can simply declare a `server_error` function.
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
677
678 function server_error($errno, $errstr, $errfile=null, $errline=null)
679 {
680 $args = compact('errno', 'errstr', 'errfile', 'errline');
681 return html("show_server_errors.html.php", error_layout(), $args);
682 }
683
684 ### Error layout ###
685
686 Allows you to define and access a layout dedicated to errors.
687
688 error_layout('error_layout.php');
689 error_layout(); // return 'error_layout.php'
690
691 ### Error handling ###
692
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
693 In addition to the common `NOT_FOUND` and `SERVER_ERROR` error displays, Limonade can redirect precise errors to your own functions.
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
694
695 error(E_USER_WARNING, 'my_notices')
696 function my_notices($errno, $errstr, $errfile, $errline)
697 {
698 // storing php warnings in a log file
699 // ...
700 status(SERVER_ERROR);
701 return html('<h1>Server Error</h1>');
702 }
703
704 `E_LIM_HTTP` means all HTTP errors
705
706 error(E_LIM_HTTP, 'my_http_errors')
707 function my_http_errors($errno, $errstr, $errfile, $errline)
708 {
709 status($errno);
710 return html('<h1>'.http_response_status_code($errno).'</h1>');
711 }
712
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
713 `E_LIM_PHP` means all PHP errors (sent by PHP or raised by the user through [`trigger_error`](http://php.net/manual/function.trigger-error.php) function).
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
714
715 ## Other useful functions ##
716
717 Limonade also provides a useful set of functions that can help you managing files, HTTP… For more about those utilities, see the [source code](http://github.com/sofadesign/limonade/blob/master/lib/limonade.php) at section **7. UTILS**.
718
719 ## Testing ##
720
721 [TODO]
722
723 ## More ##
724
725 * [Limonade web site](http://www.limonade-php.net/)
726 * [Limonade blog](http://blog.limonade-php.net/)
727 * [Issue tracking / release planning](http://sofadesign.lighthouseapp.com/projects/29612-limonade/overview)
728 * [Support / Discussions](http://groups.google.fr/group/limonade)
729
cb74ce2 Complete README file
Fabrice Luraine authored
730
Something went wrong with that request. Please try again.