lucaj / php-rhino
Rhino is a php micro-framework for building fast and reliable http services and APIs.
Requires
- php: >=7.0.0
This package is not auto-updated.
Last update: 2024-09-24 10:33:30 UTC
README
Rhino is a php micro-framework for building fast and reliable http services, APIs, and to serve static content through an easy to configure php based routing service.
Find this project on packagist: php-rhino
Contents
- Quick Start
- Feature Tutorials
- Installation
- API Documentation
Quick Start
To get started quickly simply require or include one of the rhino.php
files
located in the base or lib/ folder of this framework in the index.php
file
of your application.
You can then call the exported rhino()
function to instantiate this
framework’s main application and assign the return to a variable -
conventionally named $app
.
Next use instance methods of the application object to register middleware and
routehandler. use()
registers a middleware with this application while
methods like get()
, post()
and delete()
register route handlers which
result in a final http response to the client.
Finally a call to the start()
method must be made after all components have
been registered on the application object.
<?php require_once (dirname(__FILE__) . "/lib/rhino.php"); $app = rhino(); $app->use($jsonparse); $app->post('/', function($req, $res) { $name = $req->body['name']; $res->send("Hello $name"); }); $app->get('/', function($req, $res) { $res->send("Hello, World!"); }); $app->get('/:name', function($req, $res) { $res->send("Hello " . $req->params['name']); }); $app->start();
To immediately test your application open a terminal in the root folder of your application and launch a php development server by entering:
php -S localhost:5001 .
Open your favorite browser and navigate to localhost:5001/Peter
to view the
results. If you want to test the registered POST route as well you can use an
external graphical tool like Postman or simply use cURL from the terminal
with the following command:
echo '{ "name": "Charlie" }' | curl -d @- http://localhost:5001/ --header "Content-Type:application/json"
Take a look in the examples/
folder for more advanced working prototype
applications.
Feature Tutorials
Regular Expressions In Resource Routes
Most regular expressions work with route handlers.
<?php // trigger this route handler as a middleware for all routes starting // with `/api/`. $app->use('/api/*', function($req, $res) { }); // trigger this route handler for any number entered after `/api/` $app->get('/api/[0-9]+', function($req, $res) { }); $app->get('/api/*/name/[A-Za-z ]+', function($req, $res) { });
Query Parameters
Query Parameters are automatically converted to key-value pairs and
stored in the query
property of the request object.
<?php $app->get('/', function($req, $res) { $orderBy = $req->query['orderBy']; $offset = $req->query['offset']; $limit = $req->query['limit']; });
Route Parameters
Route parameters are defined with a colon :
in the resource route.
Route parameters and strings entered by the client in place of the
route parameters are converted to key - value pairs and stored in the
params
property of the request object.
<?php $app->get('/api/users/:id', function($req, $res) { $res->send("Retrieving data for user with id: {$req->params['id']}"); }); $app->get('/api/users/:lastname/:firstname', function($req, $res) { $lastName = $req->params['lastname']; $firstName = $req->params['firstname']; $res->send("Loading data for $firstName $lastName"); }
Secondary Routers
Additional routers can be instantiated from the original Application
$app
instance. These routers hold most of the same methods that the
Application instance has. Secondary routers can be mounted on a
custom path on other routers or the main application.
Secondary routers are used to segment different resources into their own files and to later mount them on a common url resouce path.
// in users.php $router = $app->router(); $router->get('/', function($req, $res) { // do stuff }); $router->get('/:id', function($req, $res) { // do stuff }); // in index.php require_once (dirname(__file__) . '/routes/users.php'); $app->use('/api/users/', $router); // routes registered on $router are now available on /api/users/...
Middleware
Middleware is functionality that is executed as part of the
request-response cycle. The use()
method registers middleware
functions on a given path. Those middleware functions are defined like
regular route handlers but do not automatically terminate the request
response cycle after they are finished executing.
<?php // this middleware is used to check whether the client has the required // authentication and is executed on all routes of the 'users' resource. $app->use('/api/users/*', function($req, $res) { if (!$req->get('X-Token')) { $res->status(401)->send('Access denied. No token provided.'); $res->end(); } // authenticate some more });
Built-In Request Validation
To use the built-in validator you must import
/lib/addons/validation.php
in your main index.php file.
Installation
The recommended way of installing this framework is placing the lib/
folder
in the root or vendor/
folder of your project and then requiring the main
rhino.php
file in your app’s main index.php file. That’s it - you are ready
to go.
<?php require_once (dirname(__FILE__) . "/lib/rhino.php");
API Documentation
- rhino()
- Application
- router()
- start()
- Router
- get()
- post()
- put()
- delete()
- all()
- use()
- Request
- app
- headers
- get()
- body
- params
- queryString
- query
- originalUrl
- url
- method
- hostname
- port
- Response
- app
- set()
- send()
- json()
- end()
- status()
- sendStatus()
- type()
$jsonparse
rhino()
Generate the request and response objects used throughout the application and return a new instance of this framework’s main Application class.
@param $options Array - optional parameter mapping of settings (see api docs) @return Application
Application
Application is a router that can register middleware and route handlers and
mount other routers. It inherits all methods and properties from the Router
class.
The Application class inherits two additional methods. One to start the application by iterating over this applications route $queue and one to generate a new router.
start(): void
Start this application.
Iterate over all registered route queue collections, match routes and execute middleware and response callback functions.
router(): Router
Return a new router.
@return {Router} new router instance generated using this application.
Router
The Router serves as a collection to which route handlers, middleware and other routers can be registered to.
The objects registered to this router are stored in the $queue collection.
This collection is traversed by the main collection until all matching routes have been found or the request response cycle has been terminated.
Numerous functions to register routes to this router are available as instance methods on this class.
Use the .use(), .get(), .post(), .put(), .delete(), and .all() methods to register routes with a router. See the api documentation for examples.
use(…$args): void
Register the provided arguments with this router’s routing $queue either as middleware or as a router according to their data type.
Optionally a url string may be provided to specify the target route or resource direction. If no url string is provided the root location will be assumed as the default route.
@param $args Array - Array of a url string, closure functions or Router.
post, get, put, delete(…$args): void
Register provided arguments as middleware by calling the `registerRouteHandler()` function with the appropriate http method.
@param $args Array - Array of a url string and closure functions.
all(…$args): void
Register provided arguments as middleware by calling the `registerRouteHandler()` function with the appropriate http method.
@param $args Array - Array of a url string and closure functions.
Request
The Request class holds all relevant information about a received http request and a method to conveniently retrieve http header values.
$app
A reference to the Application instance this Request belongs to.
$headers
ArrayMap of all http headers sent with this request.
get($header): string
Returns the specified HTTP request header field. Argument header names and stored header keys are case-insensitive.
@param $header {string} - name of a http header. @return {string} return the value of a specific header or null if not set.
$body
The raw content of this request’s payload or request body represented as a
string. The request body can be automatically parsed as JSON by registering the
built-in $jsonparse
middleware on the desired routes.
$params
A map of route parameters to parameter values.
$queryString
Holds the query string sent with this request.
$query
A map of query string parameters to query string parameter values.
$originalUrl
The entire original recipient url used with this Request. Do not modify this url.
$url
A copy of the original url. This field may be modified and used for app internal routing by the programmer or third party middleware / plugins.
$method
The http method used to send this request.
$hostname
Name of the host that this Request is addressed to.
$port
The Port number that this Request is addressed to.
Response
The Response class provides useful methods to set http response codes, write to the http response stream, and to break out of the request response cycle by ending the http response.
$app
A reference to the Application instance this Request belongs to.
set($header, $value): Response
Set an http response header to a given value. This function can not be used after the http response body has been written to.
@param $header {string} http header @param $value {string} http header value @return Response - a reference to this response object to allow chaining.
send($body): Response
Write a given string to the http response stream.
@param $body {string} text to write to the http response body. @return Response - a reference to this response object to allow chaining.
json($body): Response
Automatically convert an object, array or map to a json formatted string, set the ‘Content-Type’ http header to ‘application/json’ and write the string to the http response stream.
@param $body object - object, array or map @return Response - a reference to this Response object to allow chaining.
end(): void
End the http response by throwing a new EndResponse Exception. The http output stream closes when this function is called.
status($code): Response
Set the http status code to the given value.
@param $code {int} http status code @return Response - a reference to this response object to allow chaining.
sendStatus($code): Response
Set the http status code to the given value and write the conventional status message to the response body.
@param $code {int} http status code @return Response - a reference to this response object to allow chaining.