Getting Started

A quick walkthrough to get started with BitFrame Microframework

Quickstart

Setup Project Directory:

It's always good to organize well and organize early. There's no hard and fast rule to setting up your project directory, and each project may or may not need special care, but here's a suggested directory setup for a project:

── project
| └── public_html
| └── routes
| └── src
| └── test
| └── tpl
| └── vendor

Or, perhaps:

── project
| └── app
| | └── ..
| | └── routes
| | └── tpl
| └── public_html
| └── test
| └── vendor
  • public_html / public / www:

    where all the public files/folders shall reside (such as our main controller, css files, js files, images, etc.)

  • src / app:

    where the dependencies, settings, middleware, helper functions, etc. shall reside

  • routes:

    (optionally, if your project requires defining specific routes) where the main routes shall reside

  • tpl:

    (optionally, if you're using a templating system) where all the template files shall reside

  • test:

    (optionally, if you're doing test-driven development) where all the test files shall reside

  • vendor:

    (optionally, if your application relies on external packages) where all our project packages will reside

See example projects for more examples.

Preventing Access To Sensitive Files & Folders:

It's important to setup files you don't want to be directly accessible by anyone in non-public folders. For instance, in our example directory structure only the public_html folder is publicly viewable which would naturally contain all publicly accessible files and folders.

Creating an Application:

Here's a simple `Hello World` example using \BitFrame\Application (we'll assume this code goes into index.php which resides in the public_html folder):

use \Psr\Http\Message\ServerRequestInterface as Request;
use \Psr\Http\Message\ResponseInterface as Response;

require '../vendor/autoload.php';

$app = new \BitFrame\Application;

$app->addMiddleware([
    \BitFrame\Message\DiactorosResponseEmitter::class,
    function (Request $request, Response $response, callable $next) {
        $response->getBody()->write('Hello World!');

        return $next($request, $response);
    }
]);

$app->run();

Now pointing your browser to http://localhost/your_project_name/public_html/index.php should show you a page that outputs `Hello World!`.

From the code above you may have noticed that we're using two middlewares:

  1. A closure used to write `Hello World!` to the http response;
  2. A PSR-15 based wrapper/service provider of Zend Diactoros that allows us to emit the http response to the requesting user-agent (such as a web browser).

BitFrame has a middleware dispatcher at its core, and by design it allows you to use any service provider you wish. This pattern also makes it very easy to add, update, replace, remove and debug individual modules.

In order to ouput the http response, you must include a response emitter (such as \BitFrame\Message\DiactorosResponseEmitter) as the first middleware.

Setting Up Routes:

We encourage you to use the front controller pattern (i.e. have a single entrance point for your web application, for example using index.php) to handle all of the http requests. It can be particularly useful because it encourages modular code and gives you a central place to easily control how the request/response must be handled.

To enable the front controller pattern on your web server, depending on which one you use, you may have to set a directive to redirect all http requests to index.php (where we can write our application code).

Example:

Here's a quick example setup for the front controller file (e.g. index.php):

require '../vendor/autoload.php';

$app = new \BitFrame\Application;

$app->get('/hello/{name}', function ($request, $response, $next) {
    $name = $request->getAttribute('name');
    $response->getBody()->write("Hello, $name");

    return $next($request, $response);
});

$app->run([
	\BitFrame\Message\DiactorosResponseEmitter::class,
	\BitFrame\Router\FastRouteRouter::class
]);

\BitFrame\Message\DiactorosResponseEmitter and \BitFrame\Router\FastRouteRouter are external packages and must be included in your application before you can use them. You are, of course, not bound to use these particular packages and can easily use other alternatives in their place.

Controllers:

In the example above we're using an anonymous function to handle the route. You could use other types of controllers to handle routes using either \BitFrame\Application or \BitFrame\Router\FastRouteRouter instance.

Setup Your Webserver For Front Controller Pattern:

The following, depending on the server you use, will set the directive in your webserver to redirect all http requests to index.php:

  1. Enable mod_rewrite module;
  2. Create an .htaccess file where your index.php file resides (for example in the public_html folder) with at least the following code:
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ index.php [QSA,L]

nginx does NOT use an .htaccess file, so you will need to add the following to your server configuration in the location block:

if (!-e $request_filename) {
    rewrite ^(.*)$ /index.php break;
}

Comments

Let us know if you have something to say or add