Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Cleanup of README

  • Loading branch information...
commit e3a11655285c44d5ce2ff915a5250666b6da7dc2 1 parent 6c5c89e
@kematzy authored
Showing with 156 additions and 153 deletions.
  1. +156 −153 README.mkd
View
309 README.mkd
@@ -12,10 +12,7 @@ Limonade is easy to learn and provides everything that you can expect from a mod
require_once 'lib/limonade.php';
dispatch('/', 'hello');
- function hello()
- {
- return 'Hello world!';
- }
+ function hello() { return 'Hello world!'; }
run();
## About this document ##
@@ -42,29 +39,29 @@ So they make the glue between an URL + a HTTP method, and the code provided in a
dispatch('/', 'my_get_function');
# same as dispatch_get('my_get_function');
- function my_get_function()
- {
- // Show something
- // with the code of this callback controller
- }
+ function my_get_function()
+ {
+ // Show something
+ // with the code of this callback controller
+ }
dispatch_post('/', 'my_post_function');
- function my_post_function()
- {
- // Create something
- }
+ function my_post_function()
+ {
+ // Create something
+ }
dispatch_put('/', 'my_update_function');
- function my_update_function()
- {
- // Update something
- }
+ function my_update_function()
+ {
+ // Update something
+ }
dispatch_delete('/', 'my_delete_function');
- function my_delete_function()
- {
- // Delete something
- }
+ function my_delete_function()
+ {
+ // Delete something
+ }
Routes are matched in the order they are declared.
@@ -78,9 +75,9 @@ The search is performed with a path given through browser URL:
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.
<form action="<?php echo url_for('profile_update'); ?>" method="post">
- <p><input type="hidden" name="_method" value="PUT" id="_method"></p>
- <p>... your form fields</p>
- <p><input type="submit" value="Update"></p>
+ <p><input type="hidden" name="_method" value="PUT" id="_method"></p>
+ <p>... your form fields</p>
+ <p><input type="submit" value="Update"></p>
</form>
### Routing patterns and parameters ###
@@ -88,68 +85,68 @@ When `PUT` or `DELETE` methods are not supported (like in HTML form submision),
Patterns may include named parameters. Associated values of those parameters are available with the `params()` function.
dispatch('/hello/:name', 'hello');
- function hello()
- {
- $name = params('name');
- return 'Hello $name';
- }
+ function hello()
+ {
+ $name = params('name');
+ return 'Hello $name';
+ }
Patterns may also include wildcard parameters. Associated values are available through numeric indexes, in the same order as in the pattern.
dispatch('/writing/*/to/*', 'my_letter');
- function my_letter()
- {
- # Matches /writing/an_email/to/joe
- $type = params(0); # "an_email"
- $name = params(1); # "joe"
- # ...
- }
+ function my_letter()
+ {
+ # Matches /writing/an_email/to/joe
+ $type = params(0); # "an_email"
+ $name = params(1); # "joe"
+ # ...
+ }
dispatch('/files/*.*', 'share_files');
- function share_files()
- {
- # matches /files/readme.txt
- $ext = params(1);
- $filename = params(0).".".$ext;
- # ...
- }
+ function share_files()
+ {
+ # matches /files/readme.txt
+ $ext = params(1);
+ $filename = params(0).".".$ext;
+ # ...
+ }
Unlike the simple wildcard character `*`, the double wildcard character `**` specifies a string that may contain a `/`
dispatch('/files/**', 'share_files')
- function share_files()
- {
- # Matches /files/my/own/file.txt
- $filename = params(0); # my/own/file.txt
- }
+ function share_files()
+ {
+ # Matches /files/my/own/file.txt
+ $filename = params(0); # my/own/file.txt
+ }
Pattern may also be a regular expression if it begins with a `^`
dispatch('^/my/own/(\d+)/regexp', 'my_func');
- function my_func()
- {
- # matches /my/own/12/regexp
- $num = params(0);
- }
+ function my_func()
+ {
+ # matches /my/own/12/regexp
+ $num = params(0);
+ }
Wildcard parameters and regular expressions may be named, too.
dispatch(array('/say/*/to/**', array("what", "name")), 'my_func');
- function my_func()
- {
- # Matches /say/hello/to/joe
- $what = params('what');
- $name = params('name');
- }
+ function my_func()
+ {
+ # Matches /say/hello/to/joe
+ $what = params('what');
+ $name = params('name');
+ }
You can also provide default parameter values that are merged with and overriden by the pattern parameters.
$options = array('params' => array('firstname'=>'bob'));
dispatch('/hello/:name', 'hello', $options);
- function hello($firstname, $name) # default parameters first
- {
- return 'Hello $firstname $name';
- }
+ function hello($firstname, $name) # default parameters first
+ {
+ return 'Hello $firstname $name';
+ }
### Callback controllers ###
@@ -179,12 +176,12 @@ Callback controllers return the rendered view output (see _Views and templates_)
They can take the pattern parameters as arguments
dispatch('/hello/:firstname/:name', 'hello');
- function hello($firstname, $name)
- {
- # $firstname parameter equals params('firstname');
- # and $name parameter equals params('name');
- return 'Hello $firstname $name';
- }
+ function hello($firstname, $name)
+ {
+ # $firstname parameter equals params('firstname');
+ # and $name parameter equals params('name');
+ return 'Hello $firstname $name';
+ }
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.
@@ -198,9 +195,9 @@ Callbacks called by routes can be written anywhere before the execution of the `
-This folder location can be set with the `controllers_dir` option.
+This folder location can be set with the `dir.controllers` option.
- option('controllers_dir', dirname(__FILE__).'/other/dir/for/controllers');
+ option('dir.controllers', dirname(__FILE__).'/other/dir/for/controllers');
You can also define `autoload_controller` function to load controllers in your own way:
@@ -210,9 +207,9 @@ You can also define `autoload_controller` function to load controllers in your o
# If $callback, the callback function defined in matching route,
# begins with 'admin_', then we load controllers from
# the admin sub-directory in the controllers directory.
- # Else we load controllers the normal way from 'controllers_dir'.
+ # Else we load controllers the normal way from 'dir.controllers'.
- $path = option('controllers_dir');
+ $path = option('dir.controllers');
if(strpos($callback, "admin_") === 0) $path = file_path($path, 'admin');
require_once_dir($path);
}
@@ -242,9 +239,9 @@ With a `.htaccess` in your app folder
# substitution string to the existing string, instead of replacing it.
</IfModule>
-And setting explicitly the `option('base_uri')` in your configure() function:
+And setting explicitly the `option('base.uri')` in your configure() function:
- option('base_uri', '/my_app'); # '/' or same as the RewriteBase in your .htaccess
+ option('base.uri', '/my_app'); # '/' or same as the RewriteBase in your .htaccess
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`.
@@ -270,12 +267,12 @@ Variables may also be passed directly:
`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.
dispatch('/hello/:name', 'hello');
- function hello()
- {
- # matching /hello/
- set_or_default('name', params('name'),'John');
- return render('Hello %s!'); // returns 'Hello John!' because params('name') was empty. Else it would have returned params('name') value.
- }
+ function hello()
+ {
+ # matching /hello/
+ set_or_default('name', params('name'),'John');
+ return render('Hello %s!'); // returns 'Hello John!' because params('name') was empty. Else it would have returned params('name') value.
+ }
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 ;-) )*
@@ -308,11 +305,14 @@ Formatted string can be used like with [`sprintf`](http://php.net/manual/functi
It's also possible to provide a function name as a template. By this way, for example, we can produce a single file application.
- function html_message($vars){ extract($vars);?>
+ function html_message($vars)
+ {
+ extract($vars);
+ ?>
<h1>Title: <?php echo h($title); ?></h1>
- <p>Message:<br>
- <?php echo h($msg); ?></p>
- <?}
+ <p>Message:<br><?php echo h($msg); ?></p>
+ <?
+ }
// in a request handling function
set('title', 'Hello!');
@@ -322,35 +322,35 @@ It's also possible to provide a function name as a template. By this way, for ex
### HTML Templates ###
`html` function is used in the same way as `render`.
-A header specifies the proper HTTP `Content-type` (`text/html`) and encoding setting defined through options (utf8 by default).
+A header specifies the proper HTTP `Content-type` (`text/html`) and encoding setting defined through options (UTF8 by default).
html('my_template.html.php');
### Templates XML ###
`xml` function is used in the same way as `render`.
-A header specifies the proper HTTP `Content-type` (`text/xml`) and encoding setting defined through options (utf8 by default).
+A header specifies the proper HTTP `Content-type` (`text/xml`) and encoding setting defined through options (UTF8 by default).
xml('my_template.xml.php');
### Templates CSS ###
`css` function is used in the same way as `render`.
-A header specifies the proper HTTP `Content-type` (`text/css`) and encoding setting defined through options (utf8 by default).
+A header specifies the proper HTTP `Content-type` (`text/css`) and encoding setting defined through options (UTF8 by default).
css('screen.css.php');
### Templates JS ###
`js` function is used in the same way as `render`.
-A header specifies the proper HTTP `Content-type` (`application/javascript`) and encoding setting defined through options (utf8 by default).
+A header specifies the proper HTTP `Content-type` (`application/javascript`) and encoding setting defined through options (UTF8 by default).
js('app.js.php');
### Templates TXT ###
`txt` function is used in the same way as `render`.
-A header specifies the proper HTTP `Content-type` (`text/plain`) and encoding setting defined through options (utf8 by default).
+A header specifies the proper HTTP `Content-type` (`text/plain`) and encoding setting defined through options (UTF8 by default).
txt('index.txt.php');
@@ -358,17 +358,17 @@ A header specifies the proper HTTP `Content-type` (`text/plain`) and encoding se
`json` is used the same way as
[`json_encode`](http://php.net/manual/function.json-encode.php) function, and returns a string containing the JSON representation of a value.
-A header specifies the proper HTTP `Content-type` (`application/x-javascript`) and encoding setting defined through options (utf8 by default).
+A header specifies the proper HTTP `Content-type` (`application/x-javascript`) and encoding setting defined through options (UTF8 by default).
json($my_data);
### Serving files ###
-The `render_file` function can render a file directly to the ouptut buffer.
+The `render_file` function can render a file directly to the output buffer.
- render_file(option('public_dir').'foo.jpg');
+ render_file(option('dir.public').'foo.jpg');
-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) .
+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) .
Output is temporized so that it can easily handle large files.
@@ -443,8 +443,8 @@ You can define a `before` function that will be executed before each request. Th
function before($route)
{
- layout('default_layout.php');
- set('site_title', 'My Website');
+ layout('default_layout.php');
+ set('site_title', 'My Website');
}
@@ -461,10 +461,13 @@ The current matching route is also passed to the before function, so you can tes
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).
- function after($output){
- $config = array('indent' => TRUE,
- 'output-xhtml' => TRUE,
- 'wrap' => 200);
+ function after($output)
+ {
+ $config = array(
+ 'indent' => TRUE,
+ 'output-xhtml' => TRUE,
+ 'wrap' => 200
+ );
$encoding = strtoupper(str_replace('-','', option('encoding')));
$tidy = tidy_parse_string($output, $config, $encoding);
@@ -500,31 +503,31 @@ You can define your own `autorender` function to make automatic rendering depen
dispatch('/', 'hello');
function hello()
{
- # process some stuff...
- set('name', 'Bob');
+ # process some stuff...
+ set('name', 'Bob');
- # but don't return anything
- # ( like if you were ending this function with return null; )
+ # but don't return anything
+ # ( like if you were ending this function with return null; )
}
function autorender($route)
{
- $view = $route['callback'] . ".html.php";
- return html($view);
+ $view = $route['callback'] . ".html.php";
+ return html($view);
}
In this example, when url `/` is called, `hello()` is executed and then `autorender()` renders the matching `hello.html.php` view.
### Before exit ###
-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).
+If you define a `before_exit`, it is called at the beginning of the stop/exit process (`stop_and_exit` function called automatically at Limonade application termination).
function before_exit($exit)
{
- # $exit is the same parameter as the one passed to `stop_and_exit`.
- # If it's false, the exit process will not be executed,
- # only the stop instructions
- # by default it is true
+ # $exit is the same parameter as the one passed to `stop_and_exit`.
+ # If it's false, the exit process will not be executed,
+ # only the stop instructions
+ # by default it is true
}
### Before sending a header ###
@@ -534,17 +537,17 @@ You can define a `before_sending_header` function that will be called before Lim
dispatch('/style.css', 'css');
function css()
{
- # Generate css file and output
- return css('style.css.php');
+ # Generate css file and output
+ return css('style.css.php');
}
function before_sending_header($header)
{
- if (strpos($header, 'text/css') !== false)
- {
- # intercept text/css content-type and add caching to the headers
- send_header("Cache-Control: max-age=600, public");
- }
+ if (strpos($header, 'text/css') !== false)
+ {
+ # intercept text/css content-type and add caching to the headers
+ send_header("Cache-Control: max-age=600, public");
+ }
}
__Caution__: Take care not to cause a loop by repeatedly calling `send_header()` from the `before_sending_header()` function!
@@ -557,20 +560,20 @@ You can define options inside it, a connection to a database ...
function configure()
{
- $env = $_SERVER['HTTP_HOST'] == "localhost" ? ENV_DEVELOPMENT : ENV_PRODUCTION;
- option('env', $env);
- if(option('env') > ENV_PRODUCTION)
- {
- options('dsn', 'sqlite:db/development.db'));
- }
- else
- {
- options('dsn', 'sqlite:db/production.db'));
- }
- $GLOBALS['my_db_connexion'] = new PDO(option('dsn'));
+ $env = $_SERVER['HTTP_HOST'] == "localhost" ? ENV_DEVELOPMENT : ENV_PRODUCTION;
+ option('env', $env);
+ if(option('env') > ENV_PRODUCTION)
+ {
+ options('dsn', 'sqlite:db/development.db'));
+ }
+ else
+ {
+ options('dsn', 'sqlite:db/production.db'));
+ }
+ $GLOBALS['my_db_connexion'] = new PDO(option('dsn'));
}
-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.
+PHP files contained in the `option('dir.lib')` 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.
## Options ##
@@ -586,8 +589,8 @@ You can use it to manage Limonade options and your own custom options in your ap
Default Limonade options have the following values:
option('dir.root', $root_dir); // this folder contains your main application file
- option('base_path', $base_path);
- option('base_uri', $base_uri); // set it manually if you use url_rewriting
+ option('base.path', $base_path);
+ option('base.uri', $base_uri); // set it manually if you use url_rewriting
option('dir.limonade', dirname(__FILE__).'/'); // this fiolder contains the limonade.php main file
option('dir.limonade.views', dirname(__FILE__).'/limonade/views/');
option('dir.limonade.public',dirname(__FILE__).'/limonade/public/');
@@ -645,12 +648,12 @@ See sources or api for more about all available helpers.
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.
- # with option('base_uri', '?')
+ # with option('base.uri', '?')
url_for('one', 'two', 'three'); # returns ?/one/two/three
url_for('one', 'two', array('page' => 1)); # returns ?/one/two&amp;page=2
-If you want to use url rewriting, you need to explicitly set the `base_uri` option ( default is `/your_file_path/?`)
+If you want to use url rewriting, you need to explicitly set the `base.uri` option ( default is `/your_file_path/?`)
## Halting and error handling ##
@@ -673,11 +676,11 @@ To define a new view for this error, you can simply declare a `not_found` functi
function not_found($errno, $errstr, $errfile=null, $errline=null)
{
- set('errno', $errno);
- set('errstr', $errstr);
- set('errfile', $errfile);
- set('errline', $errline);
- return html("show_not_found_errors.html.php");
+ set('errno', $errno);
+ set('errstr', $errstr);
+ set('errfile', $errfile);
+ set('errline', $errline);
+ return html("show_not_found_errors.html.php");
}
### Server Error ###
@@ -695,8 +698,8 @@ To define a new view for this error, you can simply declare a `server_error` fun
function server_error($errno, $errstr, $errfile=null, $errline=null)
{
- $args = compact('errno', 'errstr', 'errfile', 'errline');
- return html("show_server_errors.html.php", error_layout(), $args);
+ $args = compact('errno', 'errstr', 'errfile', 'errline');
+ return html("show_server_errors.html.php", error_layout(), $args);
}
### Error layout ###
@@ -711,22 +714,22 @@ Allows you to define and access a layout dedicated to errors.
In addition to the common `NOT_FOUND` and `SERVER_ERROR` error displays, Limonade can redirect precise errors to your own functions.
error(E_USER_WARNING, 'my_notices')
- function my_notices($errno, $errstr, $errfile, $errline)
- {
- // storing php warnings in a log file
- // ...
- status(SERVER_ERROR);
- return html('<h1>Server Error</h1>');
- }
+ function my_notices($errno, $errstr, $errfile, $errline)
+ {
+ // storing php warnings in a log file
+ // ...
+ status(SERVER_ERROR);
+ return html('<h1>Server Error</h1>');
+ }
`E_LIM_HTTP` means all HTTP errors
error(E_LIM_HTTP, 'my_http_errors')
- function my_http_errors($errno, $errstr, $errfile, $errline)
- {
- status($errno);
- return html('<h1>'.http_response_status_code($errno).'</h1>');
- }
+ function my_http_errors($errno, $errstr, $errfile, $errline)
+ {
+ status($errno);
+ return html('<h1>'.http_response_status_code($errno).'</h1>');
+ }
`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).
Please sign in to comment.
Something went wrong with that request. Please try again.