diff --git a/README.md b/README.md index 2bdf217..52a80f6 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,22 @@ # What is Flight? -Flight is a fast, simple, extensible framework for PHP. -Flight enables you to quickly and easily build RESTful web applications. +Flight is a fast, simple, extensible framework for PHP. Flight enables you to quickly and easily build RESTful web applications. - require 'flight/Flight.php'; +```php +require 'flight/Flight.php'; - Flight::route('/', function(){ - echo 'hello world!'; - }); +Flight::route('/', function(){ + echo 'hello world!'; +}); - Flight::start(); +Flight::start(); +``` [Learn more](http://flightphp.com/learn) # Requirements -Flight requires PHP 5.3 or greater. +Flight requires `PHP 5.3` or greater. # License @@ -27,83 +28,101 @@ Flight is released under the [MIT](http://www.opensource.org/licenses/mit-licens 2\. Configure your webserver. -For *Apache*, edit your .htaccess file with the following: +For *Apache*, edit your `.htaccess` file with the following: - RewriteEngine On - RewriteCond %{REQUEST_FILENAME} !-f - RewriteCond %{REQUEST_FILENAME} !-d - RewriteRule ^(.*)$ index.php [QSA,L] +``` +RewriteEngine On +RewriteCond %{REQUEST_FILENAME} !-f +RewriteCond %{REQUEST_FILENAME} !-d +RewriteRule ^(.*)$ index.php [QSA,L] +``` For *Nginx*, add the following to your server declaration: - server { - location / { - try_files $uri $uri/ /index.php; - } +``` +server { + location / { + try_files $uri $uri/ /index.php; } - -3\. Create your index.php file. +} +``` +3\. Create your `index.php` file. First include the framework. - require 'flight/Flight.php'; +```php +require 'flight/Flight.php'; +``` Then define a route and assign a function to handle the request. - Flight::route('/', function(){ - echo 'hello world!'; - }); +```php +Flight::route('/', function(){ + echo 'hello world!'; +}); +``` Finally, start the framework. - Flight::start(); +```php +Flight::start(); +``` # Routing Routing in Flight is done by matching a URL pattern with a callback function. - Flight::route('/', function(){ - echo 'hello world!'; - }); +```php +Flight::route('/', function(){ + echo 'hello world!'; +}); +``` The callback can be any object that is callable. So you can use a regular function: - function hello(){ - echo 'hello world!'; - } +```php +function hello(){ + echo 'hello world!'; +} - Flight::route('/', 'hello'); +Flight::route('/', 'hello'); +``` Or a class method: - class Greeting { - public static function hello() { - echo 'hello world!'; - } +```php +class Greeting { + public static function hello() { + echo 'hello world!'; } +} - Flight::route('/', array('Greeting','hello')); +Flight::route('/', array('Greeting','hello')); +``` Routes are matched in the order they are defined. The first route to match a request will be invoked. ## Method Routing -By default, route patterns are matched against all request methods. You can respond to specific -methods by placing an identifier before the URL. +By default, route patterns are matched against all request methods. You can respond to specific methods by placing an identifier before the URL. - Flight::route('GET /', function(){ - echo 'I received a GET request.'; - }); +```php +Flight::route('GET /', function(){ + echo 'I received a GET request.'; +}); - Flight::route('POST /', function(){ - echo 'I received a POST request.'; - }); +Flight::route('POST /', function(){ + echo 'I received a POST request.'; +}); +``` You can also map multiple methods to a single callback by using a `|` delimiter: - Flight::route('GET|POST /', function(){ - echo 'I received either a GET or a POST request.'; - }); +```php +Flight::route('GET|POST /', function(){ + echo 'I received either a GET or a POST request.'; +}); +``` Method specific routes have precedence over global routes. @@ -111,36 +130,44 @@ Method specific routes have precedence over global routes. You can use regular expressions in your routes: - Flight::route('/user/[0-9]+', function(){ - // This will match /user/1234 - }); +```php +Flight::route('/user/[0-9]+', function(){ + // This will match /user/1234 +}); +``` ## Named Parameters You can specify named parameters in your routes which will be passed along to your callback function. - Flight::route('/@name/@id', function($name, $id){ - echo "hello, $name ($id)!"; - }); +```php +Flight::route('/@name/@id', function($name, $id){ + echo "hello, $name ($id)!"; +}); +``` You can also include regular expressions with your named parameters by using the `:` delimiter: - Flight::route('/@name/@id:[0-9]{3}', function($name, $id){ - // This will match /bob/123 - // But will not match /bob/12345 - }); +```php +Flight::route('/@name/@id:[0-9]{3}', function($name, $id){ + // This will match /bob/123 + // But will not match /bob/12345 +}); +``` ## Optional Parameters You can specify named parameters that are optional for matching by wrapping segments in parentheses. - Flight::route('/blog(/@year(/@month(/@day)))', function($year, $month, $day){ - // This will match the following URLS: - // /blog/2012/12/10 - // /blog/2012/12 - // /blog/2012 - // /blog - }); +```php +Flight::route('/blog(/@year(/@month(/@day)))', function($year, $month, $day){ + // This will match the following URLS: + // /blog/2012/12/10 + // /blog/2012/12 + // /blog/2012 + // /blog +}); +``` Any optional parameters that are not matched will be passed in as NULL. @@ -148,15 +175,19 @@ Any optional parameters that are not matched will be passed in as NULL. Matching is only done on individual URL segments. If you want to match multiple segments you can use the `*` wildcard. - Flight::route('/blog/*', function(){ - // This will match /blog/2000/02/01 - }); +```php +Flight::route('/blog/*', function(){ + // This will match /blog/2000/02/01 +}); +``` To route all requests to a single callback, you can do: - Flight::route('*', function(){ - // Do something - }); +```php +Flight::route('*', function(){ + // Do something +}); +``` # Extending @@ -166,128 +197,146 @@ Flight is designed to be an extensible framework. The framework comes with a set To map your own custom method, you use the `map` function: - // Map your method - Flight::map('hello', function($name){ - echo "hello $name!"; - }); +```php +// Map your method +Flight::map('hello', function($name){ + echo "hello $name!"; +}); - // Call your custom method - Flight::hello('Bob'); +// Call your custom method +Flight::hello('Bob'); +``` ## Registering Classes To register your own class, you use the `register` function: - // Register your class - Flight::register('user', 'User'); +```php +// Register your class +Flight::register('user', 'User'); - // Get an instance of your class - $user = Flight::user(); +// Get an instance of your class +$user = Flight::user(); +``` The register method also allows you to pass along parameters to your class constructor. So when you load your custom class, it will come pre-initialized. You can define the constructor parameters by passing in an additional array. Here's an example of loading a database connection: - // Register class with constructor parameters - Flight::register('db', 'Database', array('localhost','mydb','user','pass')); +```php +// Register class with constructor parameters +Flight::register('db', 'Database', array('localhost','mydb','user','pass')); - // Get an instance of your class - // This will create an object with the defined parameters - // - // new Database('localhost', 'mydb', 'user', 'pass'); - // - $db = Flight::db(); +// Get an instance of your class +// This will create an object with the defined parameters +// +// new Database('localhost', 'mydb', 'user', 'pass'); +// +$db = Flight::db(); +``` If you pass in an additional callback parameter, it will be executed immediately after class construction. This allows you to perform any set up procedures for your new object. The callback function takes one parameter, an instance of the new object. - // The callback will be passed the object that was constructed - Flight::register('db', 'Database', array('localhost', 'mydb', 'user', 'pass'), function($db){ - $db->connect(); - }); +```php +// The callback will be passed the object that was constructed +Flight::register('db', 'Database', array('localhost', 'mydb', 'user', 'pass'), function($db){ + $db->connect(); +}); +``` By default, every time you load your class you will get a shared instance. To get a new instance of a class, simply pass in `false` as a parameter: - // Shared instance of Database class - $shared = Flight::db(); +```php +// Shared instance of Database class +$shared = Flight::db(); - // New instance of Database class - $new = Flight::db(false); +// New instance of Database class +$new = Flight::db(false); +``` -Keep in mind that mapped methods have precedence over registered classes. If you declare both -using the same name, only the mapped method will be invoked. +Keep in mind that mapped methods have precedence over registered classes. If you declare both using the same name, only the mapped method will be invoked. # Overriding Flight allows you to override its default functionality to suit your own needs, without having to modify any code. -For example, when Flight cannot match a URL to a route, it invokes the `notFound` method which sends a generic HTTP 404 response. +For example, when Flight cannot match a URL to a route, it invokes the `notFound` method which sends a generic `HTTP 404` response. You can override this behavior by using the `map` method: - Flight::map('notFound', function(){ - // Display custom 404 page - include 'errors/404.html'; - }); +```php +Flight::map('notFound', function(){ + // Display custom 404 page + include 'errors/404.html'; +}); +``` Flight also allows you to replace core components of the framework. For example you can replace the default Router class with your own custom class: - // Register your custom class - Flight::register('router', 'MyRouter'); +```php +// Register your custom class +Flight::register('router', 'MyRouter'); - // When Flight loads the Router instance, it will load your class - $myrouter = Flight::router(); +// When Flight loads the Router instance, it will load your class +$myrouter = Flight::router(); +``` Framework methods like `map` and `register` however cannot be overridden. You will get an error if you try to do so. # Filtering -Flight allows you to filter methods before and after they are called. There are no predefined hooks -you need to memorize. You can filter any of the default framework methods as well as any custom methods that -you've mapped. +Flight allows you to filter methods before and after they are called. There are no predefined hooks you need to memorize. You can filter any of the default framework methods as well as any custom methods that you've mapped. A filter function looks like this: - function(&$params, &$output) { - // Filter code - } +```php +function(&$params, &$output) { + // Filter code +} +``` Using the passed in variables you can manipulate the input parameters and/or the output. You can have a filter run before a method by doing: - Flight::before('start', function(&$params, &$output){ - // Do something - }); +```php +Flight::before('start', function(&$params, &$output){ + // Do something +}); +``` You can have a filter run after a method by doing: - Flight::after('start', function(&$params, &$output){ - // Do something - }); +```php +Flight::after('start', function(&$params, &$output){ + // Do something +}); +``` -You can add as many filters as you want to any method. They will be called in the order -that they are declared. +You can add as many filters as you want to any method. They will be called in the order that they are declared. Here's an example of the filtering process: - // Map a custom method - Flight::map('hello', function($name){ - return "Hello, $name!"; - }); - - // Add a before filter - Flight::before('hello', function(&$params, &$output){ - // Manipulate the parameter - $params[0] = 'Fred'; - }); - - // Add an after filter - Flight::after('hello', function(&$params, &$output){ - // Manipulate the output - $output .= " Have a nice day!"; - } +```php +// Map a custom method +Flight::map('hello', function($name){ + return "Hello, $name!"; +}); + +// Add a before filter +Flight::before('hello', function(&$params, &$output){ +// Manipulate the parameter + $params[0] = 'Fred'; +}); - // Invoke the custom method - echo Flight::hello('Bob'); +// Add an after filter +Flight::after('hello', function(&$params, &$output){ +// Manipulate the output + $output .= " Have a nice day!"; +} + +// Invoke the custom method +echo Flight::hello('Bob'); +``` This should display: @@ -295,62 +344,74 @@ This should display: If you have defined multiple filters, you can break the chain by returning `false` in any of your filter functions: - Flight::before('start', function(&$params, &$output){ - echo 'one'; - }); +```php +Flight::before('start', function(&$params, &$output){ + echo 'one'; +}); - Flight::before('start', function(&$params, &$output){ - echo 'two'; +Flight::before('start', function(&$params, &$output){ + echo 'two'; - // This will end the chain - return false; - }); +// This will end the chain + return false; +}); - // This will not get called - Flight::before('start', function(&$params, &$output){ - echo 'three'; - }); +// This will not get called +Flight::before('start', function(&$params, &$output){ + echo 'three'; +}); +``` -Note, core methods such as `map` and `register` cannot be filtered because they are called -directly and not invoked dynamically. +Note, core methods such as `map` and `register` cannot be filtered because they are called directly and not invoked dynamically. # Variables Flight allows you to save variables so that they can be used anywhere in your application. - // Save your variable - Flight::set('id', 123); - - // Elsewhere in your application - $id = Flight::get('id'); +```php +// Save your variable +Flight::set('id', 123); +// Elsewhere in your application +$id = Flight::get('id'); +``` To see if a variable has been set you can do: - if (Flight::has('id')) { - // Do something - } +```php +if (Flight::has('id')) { + // Do something +} +``` You can clear a variable by doing: - // Clears the id variable - Flight::clear('id'); +```php +// Clears the id variable +Flight::clear('id'); - // Clears all variables - Flight::clear(); +// Clears all variables +Flight::clear(); +``` Flight also uses variables for configuration purposes. - Flight::set('flight.log_errors', true); +```php +Flight::set('flight.log_errors', true); +``` # Views Flight provides some basic templating functionality by default. To display a view template call the `render` method with the name of the template file and optional template data: - Flight::render('hello.php', array('name' => 'Bob')); +```php +Flight::render('hello.php', array('name' => 'Bob')); +``` The template data you pass in is automatically injected into the template and can be reference like a local variable. Template files are simply PHP files. If the content of the `hello.php` template file is: - Hello, ''! +```php +Hello, ''! +``` The output would be: @@ -358,250 +419,275 @@ The output would be: You can also manually set view variables by using the set method: - Flight::view()->set('name', 'Bob'); +```php +Flight::view()->set('name', 'Bob'); +``` The variable `name` is now available across all your views. So you can simply do: - Flight::render('hello'); +```php +Flight::render('hello'); +``` -Note that when specifying the name of the template in the render method, you can leave out the .php extension. +Note that when specifying the name of the template in the render method, you can leave out the `.php` extension. By default Flight will look for a `views` directory for template files. You can set an alternate path for your templates by setting the following config: - Flight::set('flight.views.path', '/path/to/views'); +```php +Flight::set('flight.views.path', '/path/to/views'); +``` ## Layouts It is common for websites to have a single layout template file with interchanging content. To render content to be used in a layout, you can pass in an optional parameter to the `render` method. - Flight::render('header', array('heading' => 'Hello'), 'header_content'); - Flight::render('body', array('message' => 'World'), 'body_content'); +```php +Flight::render('header', array('heading' => 'Hello'), 'header_content'); +Flight::render('body', array('message' => 'World'), 'body_content'); +``` Your view will then have saved variables called `header_content` and `body_content`. You can then render your layout by doing: - Flight::render('layout', array('title' => 'Home Page')); +```php +Flight::render('layout', array('title' => 'Home Page')); +``` If the template files looks like this: -header.php: +`header.php`: -
+```php + +``` -body.php: +`body.php`: - +```php + +``` -layout.php: +`layout.php`: - - -