Download the PHP package bfitech/zapcore without Composer

zapcore

A very simple PHP router and other utilities.

0. Reason

Yeah, why another framework?

These are a few (hopefully good enough) reasons:

0. web service-oriented

   zapcore and in general zap* packages are geared towards HTTP RESTful APIs with very little emphasis on traditional HTML document serving. If you are building the back end of a single page web application, you'll feel immediately at home.

1. performance

   zapcore performance is guaranteed to be much faster than any popular batteries-included monolithic frameworks, and is at least on par with other microframeworks. TODO: Benchmark result.

2. idiosyncracy

   This is just a fancy way of saying, "Because that's the way we like it."

1. Installation

Install it from Packagist:

2. Hello, World

Here's a bare-minimum index.php file:

Run it with PHP builtin web server and see it from your default browser:

3. Usage

3.0 Routing

Routing in zapcore is the responsibility of the method Router::route. Here's a simple route with /hello path, a regular function as the callback to handle the request data, applied to PUT request method.

which will produce:

We can use multiple methods for the same path:

Instead of letting globals floating around, we can use closure and inherited variable for the callback:

Callback can be a method instead of function:

And finally, you can subclass Router:

When request URI and request method do not match any route, a default 404 error page will be sent unless you configure shutdown to false (see below).

3.1 Dynamic Path

Apart from static path of the form /path/to/some/where, there are also two types of dynamic path built with enclosing pairs of symbols '<>' and '{}' that will capture matching strings from request URI and store them under $args['params']:

which will produce:

3.2 Request Headers

All request headers are available under $args['header']. These include custom headers:

which will produce:

NOTE: Custom request header keys will always be received in lower case, with all '-' changed into '_'.

3.3 Response Headers

You can send all kinds of response headers easily with the static method Header::header from the parent class:

which will produce:

For a more proper sequence of response headers, you can use Header::start_header static method:

which will produce:

3.4 Special Responses

There are wrappers specifically-tailored for error pages, redirect and static file serving:

which will produce:

3.5 Advanced

Router::config is a special method to finetune the router behavior, e.g.:

Available configuration items are:

• home and host

  Router attempts to infer your application root path from $_SERVER['SCRIPT_NAME'] which is mostly accurate when you deploy your application via Apache mod_php with mod_rewrite enabled. This most likely fails when $_SERVER['SCRIPT_NAME'] is no longer reliable, e.g. when you deploy your application under Apache Alias or Nginx location directives; or when you make it world-visible after a reverse-proxying. This is where home and host manual setup comes to the rescue.

• shutdown

  zapcore allows more than one Router instances in a single file. However, each instance executes a series of methods on shutdown if there is no matched route to ensure the routing doesn't end up in a blank page. In a multiple router situation, set shutdown config to false except for the last Router instance.

• logger

  All zap* packages use the same logging service provided by Logger class. By default, each Router instance has its own Logger instance, but you can share instance between Routers to avoid multiple log files.

4. Contributing

See CONTRIBUTING.md.

5. Documentation

If you have Doxygen installed, detailed generated documentation is available with: