klein.php is a fast & flexible router for PHP 5.3+
- Flexible regular expression routing (inspired by Sinatra)
- A set of boilerplate methods for rapidly building web apps
- Almost no overhead => 2500+ requests/second
- PHP 5.3.x is required
- Install Klein using Composer (recommended) or manually
- Setup URL rewriting so that all requests are handled by index.php
- (Optional) Throw in some APC for good measure
- Get Composer
- Require Klein with
php composer.phar require klein/klein - Add the following to your application's main PHP file:
require 'vendor/autoload.php';
Hello World - Obligatory hello world example
<?phprequire_once__DIR__ . '/vendor/autoload.php'; $klein = new \Klein\Klein(); $klein->respond('GET', '/hello-world', function (){return'Hello World!'}); $klein->dispatch();Example 1 - Respond to all requests
$klein->respond(function (){return'All the things'});Example 2 - Named parameters
$klein->respond('/[:name]', function ($request){return'Hello ' . $request->name});Example 3 - So RESTful
$klein->respond('GET', '/posts', $callback); $klein->respond('POST', '/posts', $callback); $klein->respond('PUT', '/posts/[i:id]', $callback); $klein->respond('DELETE', '/posts/[i:id]', $callback); $klein->respond('OPTIONS', null, $callback); // To match multiple request methods:$klein->respond(array('POST','GET'), $route, $callback); // Or you might want to handle the requests in the same place$klein->respond('/posts/[create|edit:action]?/[i:id]?', function ($request, $response){switch ($request->action){// } });Example 4 - Sending objects / files
$klein->respond(function ($request, $response, $service){$service->xml = function ($object){// Custom xml output function } $service->csv = function ($object){// Custom csv output function } }); $klein->respond('/report.[xml|csv|json:format]?', function ($request, $response, $service){// Get the format or fallback to JSON as the default$send = $request->param('format', 'json'); $response->$send($report)}); $klein->respond('/report/latest', function ($request, $response, $service){$response->file('/tmp/cached_report.zip')});Example 5 - All together
$klein->respond(function ($request, $response, $service, $app) use ($klein){// Handle exceptions => flash the message and redirect to the referrer$klein->onError(function ($klein, $err_msg){$klein->service()->flash($err_msg); $klein->service()->back()}); // The fourth parameter can be used to share scope and global objects$app->db = newPDO(...); // $app also can store lazy services, e.g. if you don't want to// instantiate a database connection on every response$app->register('db', function(){returnnewPDO(...)})}); $klein->respond('POST', '/users/[i:id]/edit', function ($request, $response, $service, $app){// Quickly validate input parameters$service->validateParam('username', 'Please enter a valid username')->isLen(5, 64)->isChars('a-zA-Z0-9-'); $service->validateParam('password')->notNull(); $app->db->query(...); // etc.// Add view properties and helper methods$service->title = 'foo'; $service->escape = function ($str){returnhtmlentities($str); // Assign view helpers }; $service->render('myview.phtml')}); // myview.phtml: <title><?phpecho$this->escape($this->title) ?></title>$klein->with('/users', function () use ($klein){$klein->respond('GET', '/?', function ($request, $response){// Show all users }); $klein->respond('GET', '/[:id]', function ($request, $response){// Show a single user })}); foreach(array('projects', 'posts') as$controller){// Include all routes defined in a file under a given namespace$klein->with("/$controller", "controllers/$controller.php")}Included files are run in the scope of Klein ($klein) so all Klein methods/properties can be accessed with $this
Example file for: "controllers/projects.php"
// Routes to "/projects/?"$this->respond('GET', '/?', function ($request, $response){// Show all projects });Services can be stored lazily, meaning that they are only instantiated on first use.
<?php$klein->respond(function ($request, $response, $service, $app){$app->register('lazyDb', function(){$db = newstdClass(); $db->name = 'foo'; return$db})}); //Later$klein->respond('GET', '/posts', function ($request, $response, $service, $app){// $db is initialised on first request// all subsequent calls will use the same instancereturn$app->lazyDb->name});To add a custom validator use addValidator($method, $callback)
$service->addValidator('hex', function ($str){returnpreg_match('/^[0-9a-f]++$/i', $str)});You can validate parameters using is<$method>() or not<$method>(), e.g.
$service->validateParam('key')->isHex();Or you can validate any string using the same flow..
$service->validate($username)->isLen(4,16);Validation methods are chainable, and a custom exception message can be specified for if/when validation fails
$service->validateParam('key', 'The key was invalid')->isHex()->isLen(32);[match_type:param_name]
Some examples
* // Match all request URIs [i] // Match an integer [i:id] // Match an integer as 'id' [a:action] // Match alphanumeric characters as 'action' [h:key] // Match hexadecimal characters as 'key' [:action] // Match anything up to the next / or end of the URI as 'action' [create|edit:action] // Match either 'create' or 'edit' as 'action' [*] // Catch all (lazy) [*:trailing] // Catch all as 'trailing' (lazy) [**:trailing] // Catch all (possessive - will match the rest of the URI) .[:format]? // Match an optional parameter 'format' - a / or . before the block is also optional Some more complicated examples
/posts/[*:title][i:id] // Matches "/posts/this-is-a-title-123" /output.[xml|json:format]? // Matches "/output", "output.xml", "output.json" /[:controller]?/[:action]? // Matches the typical /controller/action format Note - all routes that match the request URI are called - this allows you to incorporate complex conditional logic such as user authentication or view layouts. e.g. as a basic example, the following code will wrap other routes with a header and footer
$klein->respond('*', function ($request, $response, $service){$service->render('header.phtml')}); //other routes$klein->respond('*', function ($request, $response, $service){$service->render('footer.phtml')});Routes automatically match the entire request URI. If you need to match only a part of the request URI or use a custom regular expression, use the @ operator. If you need to negate a route, use the ! operator
// Match all requests that end with '.json' or '.csv'$klein->respond('@\.(json|csv)$', ... // Match all requests that _don't_ start with /admin$klein->respond('!@^/admin/', ...You can send properties or helpers to the view by assigning them to the $service object, or by using the second arg of $service->render()
$service->escape = function ($str){returnhtmlentities($str)}; $service->render('myview.phtml', array('title' => 'My View')); // Or just: $service->title = 'My View';myview.phtml
<title><?php echo $this->escape($this->title) ?></title>Views are compiled and run in the scope of $service so all service methods can be accessed with $this
$this->render('partial.html') // Render partials$this->sharedData()->get('myvar') // Access stored service variablesecho$this->query(array('page' => 2)) // Modify the current query stringBelow is a list of the public methods in the common classes you will most likely use. For a more formal source of class/method documentation, please see the PHPdoc generated documentation.
$request-> id($hash = true) // Get a unique ID for the request paramsGet() // Return the GET parameter collection paramsPost() // Return the POST parameter collection paramsNamed() // Return the named parameter collection cookies() // Return the cookies collection server() // Return the server collection headers() // Return the headers collection files() // Return the files collection body() // Get the request body params() // Return all parametersparams($mask = null) // Return all parameters that match the mask array - extract() friendlyparam($key, $default = null) // Get a request parameter (get, post, named) isSecure() // Was the request sent via HTTPS? ip() // Get the request IP userAgent() // Get the request user agent uri() // Get the request URI pathname() // Get the request pathname method() // Get the request methodmethod($method) // Check if the request method is $method, i.e. method('post') => truequery($key, $value = null) // Get, add to, or modify the current query string <param> // Get / Set (if assigned a value) a request parameter$response-> protocolVersion($protocol_version = null) // Get the protocol version, or set it to the passed valuebody($body = null) // Get the response body's content, or set it to the passed value status() // Get the response's status object headers() // Return the headers collection cookies() // Return the cookies collectioncode($code = null) // Return the HTTP response code, or set it to the passed valueprepend($content) // Prepend a string to the response bodyappend($content) // Append a string to the response body isLocked() // Check if the response is locked requireUnlocked() // Require that a response is unlocked lock() // Lock the response from further modification unlock() // Unlock the responsesendHeaders($override = false) // Send the HTTP response headerssendCookies($override = false) // Send the HTTP response cookies sendBody() // Send the response body's content send() // Send the response and lock it isSent() // Check if the response has been sentchunk($str = null) // Enable response chunking (see the wiki)header($key, $value = null) // Set a response headercookie($key, $value = null, $expiry = null) // Set a cookiecookie($key, null) // Remove a cookie noCache() // Tell the browser not to cache the responseredirect($url, $code = 302) // Redirect to the specified URLdump($obj) // Dump an objectfile($path, $filename = null) // Send a filejson($object, $jsonp_prefix = null) // Send an object as JSON or JSONP by providing padding prefix$service-> sharedData() // Return the shared data collection startSession() // Start a session and return its ID flash($msg, $type = 'info', $params = array() // Set a flash messageflashes($type = null) // Retrieve and clears all flashes of $type markdown($str, $args, ...) // Return a string formatted with markdownescape($str) // Escape a string refresh() // Redirect to the current URL back() // Redirect to the refererquery($key, $value = null) // Modify the current query stringquery($arr) layout($layout) // Set the view layoutyieldView() // Call inside the layout to render the view contentrender($view, $data = array()) // Render a view or partial (in the scope of $response)partial($view, $data = array()) // Render a partial without a layout (in the scope of $response)addValidator($method, $callback) // Add a custom validator methodvalidate($string, $err = null) // Validate a string (with a custom error message)validateParam($param, $err = null) // Validate a param <callback>($arg1, ...) // Call a user-defined helper <property> // Get a user-defined property$app-> <callback>($arg1, ...) //Call a user-defined helper$validator-> notNull() // The string must not be nullisLen($length) // The string must be the exact lengthisLen($min, $max) // The string must be between $min and $max length (inclusive) isInt() // Check for a valid integer isFloat() // Check for a valid float/decimal isEmail() // Check for a valid email isUrl() // Check for a valid URL isIp() // Check for a valid IP isAlpha() // Check for a-z (case insensitive) isAlnum() // Check for alphanumeric characterscontains($needle) // Check if the string contains $needleisChars($chars) // Validate against a character listisRegex($pattern, $modifiers = '') // Validate against a regular expressionnotRegex($pattern, $modifiers ='') is<Validator>() // Validate against a custom validator not<Validator>() // The validator can't match <Validator>() // Alias for is<Validator>()Unit tests are a crucial part of developing a routing engine such as Klein. Added features or bug-fixes can have adverse effects that are hard to find without a lot of testing, hence the importance of unit testing.
This project uses PHPUnit as its unit testing framework.
The tests all live in /tests and each test extends an abstract class AbstractKleinTest
To test the project, simply run php composer.phar install --dev to download a common version of PHPUnit with composer and run the tests from the main directory with ./vendor/bin/phpunit
See the contributing guide for more info
See the wiki for more information
(MIT License)
Copyright (c) 2010 Chris O'Hara [email protected]
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.