Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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