Micro Application

    Phalcon offers a very ‘thin’ application, so that you can create applications with minimal PHP code and overhead. Micro applications are suitable for small applications that will have very low overhead. Such applications are usually API ones, prototypes etc.

    The Phalcon\Mvc\Micro class is the one responsible for creating a Micro application.

    1. <?php
    3. use Phalcon\Mvc\Micro;
    5. $app = new Micro();

    Routing

    Defining routes in a Phalcon\Mvc\Micro application is very easy. Routes are defined as follows:

    1.    Application -> (method/verb) -> (route url/regex, callable PHP function)

    Routing is handled by the object. [Info]

    Usually, the starting route in an application is the route /, and in most cases it is accessed via the GET HTTP method:

    1. <?php
    3. // This is the start route
    4. $app->get(
    5.     '/',
    6.     function () {
    7.         echo '<h1>Welcome!</h1>';
    8.     }
    9. );

    Application object

    Routes can be set using the Phalcon\Mvc\Micro application object as follows:

    1. use Phalcon\Mvc\Micro;
    3. $app = new Micro();
    5. // Matches a GET request
    6. $app->get(
    7.     '/orders/display/{name}',
    8.     function ($name) {
    9.         echo "<h1>This is order: {$name}!</h1>";
    10.     }
    11. );

    Router object

    You can also create a Phalcon\Mvc\Router object, setting the routes there and then injecting it in the dependency injection container.

    1. use Phalcon\Mvc\Micro;
    2. use Phalcon\Mvc\Router;
    4. $router = new Router();
    6. $router->addGet(
    7.     '/orders/display/{name}',
    8.     'OrdersClass::display'
    9. );
    12. $app = new Micro();
    14. $app->setService('router', $router, true);

    Setting up your routes using the applications verb methods (get, post, etc.) is much easier than setting up a router object with relevant routes and then injecting it in the application.

    Each method has its advantages and disadvantages. It all depends on the design and needs of your application.

    Rewrite Rules

    In order for routes to work, certain configuration changes need to be made in your web server’s configuration for your particular site.

    Those changes are outlined in the .

    Handlers

    Handlers are callable pieces of code that get attached to a route. When the route is matched, the handler is executed with all the defined parameters. A handler is any callable piece of code that exists in PHP.

    Definitions

    Phalcon offers several ways to attach a handler to a route. Your application needs and design as well as coding style will be the factors influencing your choice of implementation.

    Anonymous Function

    Finally we can use an anonymous function (as seen above) to handle the request

    1. $app->get(
    2.     '/orders/display/{name}',
    3.     function ($name) {
    4.         echo "<h1>This is order: {$name}!</h1>";
    5.     }
    6. );

    Accessing the $app object inside the anonymous function can be achieved by injecting it as follows:

    1. $app->get(
    2.     '/orders/display/{name}',
    3.     function ($name) use ($app) {
    4.         $content = "<h1>This is order: {$name}!</h1>";
    6.         $app->response->setContent($content);
    8.         $app->response->send();
    9.     }
    10. );
    Function

    We can define a function as our handler and attach it to a specific route.

    1. // With a function
    2. function order_display($name) {
    3.     echo "<h1>This is order: {$name}!</h1>";
    4. }
    6. $app->get(
    7.     '/orders/display/{name}',
    8.     'orders_display'
    9. );
    Static Method

    We can also use a static method as our handler as follows:

    1. class OrdersClass
    2. {
    3.     public static function display($name) {
    4.         echo "<h1>This is order: {$name}!</h1>";
    5.     }
    6. }
    8. $app->get(
    9.     '/orders/display/{name}',
    10.     'OrdersClass::display'
    11. );
    Method in an Object

    We can also use a method in an object:

    1. class OrdersClass
    2. {
    3.     public function display($name) {
    4.         echo "<h1>This is order: {$name}!</h1>";
    5.     }
    6. }
    8. $orders = new OrdersClass();
    9. $app->get(
    10.     '/orders/display/{name}',
    11.     [
    12.         $orders,
    13.         'display',
    14.     ]
    15. );
    Controllers

    With the you can create micro or medium applications. Medium applications use the micro architecture but expand on it to utilize more than the Micro but less than the Full application.

    In medium applications you can organize handlers in controllers.

    1. <?php
    3. use Phalcon\Mvc\Micro\Collection as MicroCollection;
    5. $orders = new MicroCollection();
    7. // Set the main handler. ie. a controller instance
    8. $orders->setHandler(new OrdersController());
    10. // Set a common prefix for all routes
    11. $orders->setPrefix('/orders');
    13. // Use the method 'index' in OrdersController
    14. $orders->get('/', 'index');
    16. // Use the method 'show' in OrdersController
    17. $orders->get('/display/{slug}', 'show');
    19. $app->mount($orders);

    The OrdersController might look like this:

    1. <?php
    3. use Phalcon\Mvc\Controller;
    5. class OrdersController extends Controller
    6. {
    7.     public function index()
    8.     {
    9.         // ...
    10.     }
    12.     public function show($name)
    13.     {
    14.         // ...
    15.     }
    16. }

    Since our controllers extend the Phalcon\Mvc\Controller, all the dependency injection services are available with their respective registration names. For example:

    1. <?php
    3. use Phalcon\Mvc\Controller;
    5. class OrdersController extends Controller
    6. {
    7.     public function index()
    8.     {
    9.         // ...
    10.     }
    12.     public function show($name)
    13.     {
    14.         $content = "<h1>This is order: {$name}!</h1>";
    16.         $this->response->setContent($content);
    18.         return $this->response;
    19.     }
    20. }

    Lazy Loading

    In order to increase performance, you might consider implementing lazy loading for your controllers (handlers). The controller will be loaded only if the relevant route is matched.

    Lazy loading can be easily achieved when setting your handler in your Phalcon\Mvc\Micro\Collection:

    1. $orders->setHandler(\OrdersController::class, true);
    2. $orders->setHandler(\Blog\Controllers\OrdersController::class, true);
    Use case

    We are developing an API for an online store. The endpoints are /users, /orders and /products. Each of those endpoints are registered using handlers, and each handler is a controller with relevant actions.

    The controllers that we use as handlers are as follows:

    1. <?php
    3. use Phalcon\Mvc\Controller;
    5. class UsersController extends Controller
    6. {
    7.     public function get($id)
    8.     {
    9.         // ...
    10.     }
    12.     public function add($payload)
    13.     {
    14.         // ...
    15.     }
    16. }
    18. class OrdersController extends Controller
    19. {
    20.     public function get($id)
    21.     {
    22.         // ...
    23.     }
    25.     public function add($payload)
    26.     {
    27.         // ...
    28.     }
    29. }
    31. class ProductsController extends Controller
    32. {
    33.     public function get($id)
    34.     {
    35.         // ...
    36.     }
    38.     public function add($payload)
    39.     {
    40.         // ...
    41.     }
    42. }

    We register the handlers:

    1. <?php
    3. use Phalcon\Mvc\Micro\Collection as MicroCollection;
    5. // Users handler
    6. $users = new MicroCollection();
    8. $users->setHandler(
    9.     new UsersController()
    10. );
    12. $users->setPrefix('/users');
    14. $users->get('/get/{id}', 'get');
    15. $users->get('/add/{payload}', 'add');
    17. $app->mount($users);
    20. // Orders handler
    21. $orders = new MicroCollection();
    23. $orders->setHandler(
    24.     new OrdersController()
    25. );
    27. $orders->setPrefix('/users');
    29. $orders->get('/get/{id}', 'get');
    30. $orders->get('/add/{payload}', 'add');
    32. $app->mount($orders);
    35. // Products handler
    36. $products = new MicroCollection();
    38. $products->setHandler(
    39.     new ProductsController()
    40. );
    42. $products->setPrefix('/products');
    44. $products->get('/get/{id}', 'get');
    45. $products->get('/add/{payload}', 'add');
    47. $app->mount($products);

    This implementation loads each handler in turn and mounts it in our application object. The issue with this approach is that each request will result to only one endpoint and therefore one class method executed. The remaining methods/handlers will just remain in memory without being used.

    Using lazy loading we reduce the number of objects loaded in memory and as a result our application uses less memory.

    The above implementation changes if we want to use lazy loading as follows:

    1. <?php
    3. use Phalcon\Mvc\Micro\Collection as MicroCollection;
    5. // Users handler
    6. $users = new MicroCollection();
    8. $users->setHandler(new UsersController(), true);
    10. $users->setPrefix('/users');
    12. $users->get('/get/{id}', 'get');
    13. $users->get('/add/{payload}', 'add');
    15. $app->mount($users);
    18. // Orders handler
    19. $orders = new MicroCollection();
    21. $orders->setHandler(new OrdersController(), true);
    23. $orders->setPrefix('/users');
    25. $orders->get('/get/{id}', 'get');
    26. $orders->get('/add/{payload}', 'add');
    28. $app->mount($orders);
    31. // Products handler
    32. $products = new MicroCollection();
    34. $products->setHandler(new ProductsController(), true);
    36. $products->setPrefix('/products');
    38. $products->get('/get/{id}', 'get');
    39. $products->get('/add/{payload}', 'add');
    41. $app->mount($products);

    Using this simple change in implementation, all handlers remain uninstantiated until requested by a caller. Therefore whenever a caller requests /orders/get/2, our application will instantiate the OrdersController and call the get method in it. Our application now uses less resources than before.

    Not found (404)

    1. <?php
    3. $app->notFound(
    4.     function () use ($app) {
    5.         $app->response->setStatusCode(404, 'Not Found');
    6.         $app->response->sendHeaders();
    8.         $message = 'Nothing to see here. Move along....';
    9.         $app->response->setContent($message);
    11.         $app->response->send();
    12.     }
    13. );

    You can also handle routes that have not been matched (404) with Middleware discussed below.

    Methods - Verbs

    The Phalcon\Mvc\Micro application provides a set of methods to bind the HTTP method with the route it is intended to.

    delete

    Matches if the HTTP method is DELETE and the route is /api/products/delete/{id}

    1.     $app->delete(
    2.         '/api/products/delete/{id}',
    3.         'delete_product'
    4.     );

    get

    Matches if the HTTP method is GET and the route is /api/products

    1.     $app->get(
    2.         '/api/products',
    3.         'get_products'
    4.     );

    head

    Matches if the HTTP method is HEAD and the route is /api/products

    map

    Map allows you to attach the same endpoint to more than one HTTP method. The example below matches if the HTTP method is GET or POST and the route is /repos/store/refs

    1.     $app
    2.         ->map(
    3.             '/repos/store/refs',
    4.             'action_product'
    5.         )
    6.         ->via(
    7.             [
    8.                 'GET',
    9.                 'POST',
    10.             ]
    11.         );

    options

    Matches if the HTTP method is OPTIONS and the route is /api/products/options

    1.     $app->options(
    2.         '/api/products/options',
    3.         'info_product'
    4.     );

    patch

    Matches if the HTTP method is PATCH and the route is /api/products/update/{id}

    1.     $app->patch(
    2.         '/api/products/update/{id}',
    3.         'update_product'
    4.     );

    post

    Matches if the HTTP method is POST and the route is /api/products/add

    1.     $app->post(
    2.         '/api/products',
    3.         'add_product'
    4.     );

    put

    Matches if the HTTP method is PUT and the route is /api/products/update/{id}

    1.     $app->put(
    2.         '/api/products/update/{id}',
    3.         'update_product'
    4.     );

    Collections

    Collections are a handy way to group collections attached to a handler and a common prefix (if needed). For a hypothetical /orders endpoint we could have the following endpoints:

    1. /orders/get/{id}
    2. /orders/add/{payload}
    3. /orders/update/{id}
    4. /orders/delete/{id}

    All of those routes are handled by our OrdersController. We set up our routes with a collection as follows:

    1. <?php
    3. use Phalcon\Mvc\Micro\Collection as MicroCollection;
    5. $orders = new MicroCollection();
    6. $orders->setHandler(new OrdersController());
    8. $orders->setPrefix('/orders');
    10. $orders->get('/get/{id}', 'displayAction');
    11. $orders->get('/add/{payload}', 'addAction');
    12. $orders->get('/update/{id}', 'updateAction');
    13. $orders->get('/delete/{id}', 'deleteAction');
    15. $app->mount($orders);

    The name that we bind each route has a suffix of Action. This is not necessary, your method can be called anything you like.

    Parameters

    We have briefly seen above how parameters are defined in the routes. Parameters are set in a route string by enclosing the name of the parameter in brackets.

    1. $app->get(
    2.     '/orders/display/{name}',
    3.     function ($name) {
    4.         echo "<h1>This is order: {$name}!</h1>";
    5.     }

    We can also enforce certain rules for each parameter by using regular expressions. The regular expression is set after the name of the parameter, separating it with :.

    1. // Match the order id
    2. $app->get(
    3.     '/orders/display/{id:[0-9]+}',
    4.     function ($id) {
    5.         echo "<h1>This is order: #{$id}!</h1>";
    6.     }
    7. );
    9. // Match a numeric (4) year and a title (alpha)
    10. $app->get(
    11.     '/posts/{year:[0-9][4]}/{title:[a-zA-Z\-]+}',
    12.     function ($year, $title) {
    13.         echo '<h1>Title: $title</h1>';
    14.         echo '<h2>Year: $year</h2>';
    15.     }
    16. );

    Additional information: Info

    Redirections

    You can redirect one matched route to another using the Phalcon\Http\Response object, just like in a full application.

    1. $app->post('/old/url',
    2.     function () use ($app) {
    3.         $app->response->redirect('new/url');
    5.         $app->response->sendHeaders();
    6.     }
    7. );
    10.     function () use ($app) {
    11.         echo 'This is the new Welcome';
    12.     }
    13. );

    Note we have to pass the $app object in our anonymous function to have access to the request object.

    When using controllers as handlers, you can perform the redirect just as easy:

    1. <?php
    3. use Phalcon\Mvc\Controller;
    5. class UsersController extends Controller
    6. {
    7.     public function oldget($id)
    8.     {
    9.         return $this->response->redirect(
    10.             'users/get/' . $id
    11.         );
    12.     }
    14.     public function get($id)
    15.     {
    16.         // ...
    17.     }
    18. }

    Finally, you can perform redirections in your middleware (if you are using it). An example is below in the relevant section.

    URLs for Routes

    Another feature of the routes is setting up named routes and generating URLs for those routes. This is a two step process.

    • First we need to name our route. This can be achieved with the setName() method that is exposed from the methods/verbs in our application (get, post, etc.);
    1. // Set a route with the name 'show-order'
    2. $app
    3.     ->get(
    4.         '/orders/display/{id}',
    5.         function ($id) use ($app) {
    6.             // ... Find the order and show it
    7.         }
    8.     )
    9.     ->setName('show-order');
    • We need to use the Phalcon\Url component to generate URLs for the named routes.
    1. // Use the named route and produce a URL from it
    2. $app->get(
    3.     '/',
    4.     function () use ($app) {
    5.         $url = sprintf(
    6.             '<a href="%s">Show the order</a>',
    7.             $app->url->get(
    8.                 [
    9.                     'for' => 'show-order',
    10.                     'id'  => 1234,
    11.                 ]
    12.             )
    13.         );
    15.         echo $url;
    16.     }
    17. );

    When a micro application is created, a services container is create implicitly.

    1. <?php
    3. use Phalcon\Mvc\Micro;
    4. $app = new Micro();
    6. $app->get(
    7.     '/',
    8.     function () use ($app) {
    9.         $app->response->setContent('Hello!!');
    10.         $app->response->send();
    11.     }
    12. );

    You can also create a Di container yourself, and assign it to the micro application, therefore manipulating the services depending on the needs of your application.

    1. <?php
    3. use Phalcon\Mvc\Micro;
    4. use Phalcon\Di\FactoryDefault;
    5. use Phalcon\Config\Adapter\Ini as IniConfig;
    7. $di = new FactoryDefault();
    9. $di->set(
    10.     'config',
    11.     function () {
    12.         return new IniConfig('config.ini');
    13.     }
    14. );
    16. $app = new Micro();
    18. $app->setDI($di);
    20. $app->get(
    21.     '/',
    22.     function () use ($app) {
    23.         // Read a setting from the config
    24.         echo $app->config->app_name;
    25.     }
    26. );
    28. $app->post(
    29.     '/contact',
    30.     function () use ($app) {
    31.         $app->flash->success('What are you doing Dave?');
    32.     }
    33. );

    You can also use the array syntax to register services in the dependency injection container from the application object:

    1. <?php
    3. use Phalcon\Mvc\Micro;
    4. use Phalcon\Db\Adapter\Pdo\Mysql as MysqlAdapter;
    6. $app = new Micro();
    8. // Setup the database service
    9. $app['db'] = function () {
    10.     return new MysqlAdapter(
    11.         [
    12.             'host'     => 'localhost',
    13.             'username' => 'root',
    14.             'password' => 'secret',
    15.             'dbname'   => 'test_db',
    16.         ]
    17.     );
    18. };
    20. $app->get(
    21.     '/blog',
    22.     function () use ($app) {
    23.         $news = $app['db']->query('SELECT * FROM news');
    25.         foreach ($news as $new) {
    26.             echo $new->title;
    27.         }
    28.     }
    29. );

    Responses

    A micro application can return many different types of responses. Direct output, use a template engine, calculated data, view based data, JSON etc.

    Handlers may return raw responses using plain text, object or a custom built component that implements the Phalcon\Http\ResponseInterface.

    1. $app->get(
    2.     '/orders/display/{name}',
    3.     function ($name) {
    4.         echo "<h1>This is order: {$name}!</h1>";
    5.     }
    6. );

    Including another file

    1. $app->get(
    2.     '/orders/display/{name}',
    3.     function ($name) {
    4.         require 'views/results.php';
    5.     }
    6. );

    Direct output JSON

    1. $app->get(
    2.     '/orders/display/{name}',
    3.     function ($name) {
    4.         echo json_encode(
    5.             [
    6.                 'code' => 200,
    7.                 'name' => $name,
    8.             ]
    9.         );
    10.     }
    11. );

    New Response object

    You can use the setContent method of the response object to return the response back:

    1. $app->get(
    2.     '/show/data',
    3.     function () {
    4.         // Create a response
    5.         $response = new Phalcon\Http\Response();
    7.         // Set the Content-Type header
    8.         $response->setContentType('text/plain');
    10.         // Pass the content of a file
    11.         $response->setContent(
    12.             file_get_contents('data.txt')
    13.         );
    15.         // Return the response
    16.         return $response;
    17.     }
    18. );

    Application Response

    You can also use the object to return responses to the caller. The response object has a lot of useful methods that make returning responses much easier.

    Return Application Response

    A different approach returning data back to the caller is to return the response object directly from the application. When responses are returned by handlers they are automatically sent by the application.

    1. <?php
    3. use Phalcon\Mvc\Micro;
    4. use Phalcon\Http\Response;
    6. $app = new Micro();
    8. // Return a response
    9. $app->get(
    10.     '/welcome/index',
    11.     function () {
    12.         $response = new Response();
    14.         $response->setStatusCode(401, 'Unauthorized');
    15.         $response->setContent('Access is not authorized');
    17.         return $response;
    18.     }
    19. );

    JSON

    JSON can be sent back just as easy using the Phalcon\Http\Response object:

    1. $app->get(
    2.     '/welcome/index',
    3.     function () use ($app) {
    5.         $data = [
    6.             'code'    => 401,
    7.             'status'  => 'error',
    8.             'message' => 'Unauthorized access',
    9.             'payload' => [],
    10.         ];
    12.         $response->setJsonContent($data);
    14.         return $response;
    15.     }
    16. );

    A application works closely with a Phalcon\Events\Manager if it is present, to trigger events that can be used throughout our application. The type of those events is micro. These events trigger in our application and can be attached to relevant handlers that will perform actions needed by our application.

    Available events

    The following events are supported:

    1. <?php
    3. use Phalcon\Mvc\Micro;
    4. use Phalcon\Events\Event;
    5. use Phalcon\Events\Manager as EventsManager;
    7. // Create a events manager
    8. $eventsManager = new EventsManager();
    10. $eventsManager->attach(
    11.     'micro:beforeExecuteRoute',
    12.     function (Event $event, $app) {
    13.         if ($app->session->get('auth') === false) {
    14.             $app->flashSession->error("The user isn't authenticated");
    16.             $app->response->redirect('/');
    17.             $app->response->sendHeaders();
    19.             // Return (false) stop the operation
    20.             return false;
    21.         }
    22.     }
    23. );
    25. $app = new Micro();
    27. // Bind the events manager to the app
    28. $app->setEventsManager($eventsManager);

    Not found example

    You can easily check whether a user has been authenticated or not using the beforeExecuteRoute event.In the following example, we explain how to control the application security using events:

    1. <?php
    3. use Phalcon\Mvc\Micro;
    4. use Phalcon\Events\Event;
    5. use Phalcon\Events\Manager as EventsManager;
    7. // Create a events manager
    8. $eventsManager = new EventsManager();
    10. $eventsManager->attach(
    11.     'micro:beforeNotFound',
    12.     function (Event $event, $app) {
    13.         $app->response->redirect('/404');
    14.         $app->response->sendHeaders();
    16.         return $app->response;
    17.     }
    18. );
    20. $app = new Micro();
    22. // Bind the events manager to the app
    23. $app->setEventsManager($eventsManager);

    Middleware

    Middleware are classes that can be attached to your application and introduce another layer where business logic can exist. They run sequentially, according to the order they are registered and not only improve maintainability, by encapsulating specific functionality, but also performance. A middleware class can stop execution when a particular business rule has not been satisfied, thus allowing the application to exit early without executing the full cycle of a request.

    The presence of a Phalcon\Events\Manager is essential for middleware to operate, so it has to be registered in our Di container.

    Attached events

    Middleware can be attached to a micro application in 3 different events. Those are:

    EventDescription
    beforeBefore the handler has been executed
    afterAfter the handler has been executed
    finishAfter the response has been sent to the caller

    before

    This event is perfect for stopping execution of the application if certain criteria is not met. In the below example we are checking if the user has been authenticated and stop execution with the necessary redirect.

    1. <?php
    3. $app = new Phalcon\Mvc\Micro();
    5. // Executed before every route is executed
    6. // Return false cancels the route execution
    7. $app->before(
    8.     function () use ($app) {
    9.         if (false === $app['session']->get('auth')) {
    10.             $app['flashSession']->error("The user isn't authenticated");
    12.             $app['response']->redirect('/error');
    14.             // Return false stops the normal execution
    15.             return false;
    16.         }
    18.         return true;
    19.     }
    20. );

    after

    This event can be used to manipulate data or perform actions that are needed after the handler has finished executing. In the example below, we manipulate our response to send JSON back to the caller.

    1. $app->map(
    2.     '/api/robots',
    3.     function () {
    4.         return [
    5.             'status' => 'OK',
    6.         ];
    7.     }
    8. );
    10. $app->after(
    11.     function () use ($app) {
    12.         // This is executed after the route is executed
    13.         echo json_encode(
    14.             $app->getReturnedValue()
    15.         );
    16.     }
    17. );

    finish

    This even will fire up when the whole request cycle has been completed. In the example below, we use it to clean up some cache files.

    1. $app->finish(
    2.     function () use ($app) {
    3.         if (true === file_exists('/tmp/processing.cache')) {
    4.             unlink('/tmp/processing.cache');
    5.         }
    6.     }
    7. );

    Setup

    Attaching middleware to your application is very easy as shown above, with the before, after and finish method calls.

    1. $app->before(
    2.     function () use ($app) {
    3.         if (false === $app['session']->get('auth')) {
    4.             $app['flashSession']->error("The user isn't authenticated");
    6.             $app['response']->redirect('/error');
    8.             // Return false stops the normal execution
    9.             return false;
    10.         }
    12.         return true;
    13.     }
    14. );
    16. $app->after(
    17.     function () use ($app) {
    18.         // This is executed after the route is executed
    19.         echo json_encode(
    20.             $app->getReturnedValue()
    21.         );
    22.     }
    23. );

    Attaching middleware to your application as classes and having it listen to events from the events manager can be achieved as follows:

    1. <?php
    3. use Phalcon\Events\Manager;
    4. use Phalcon\Mvc\Micro;
    6. use Website\Middleware\CacheMiddleware;
    7. use Website\Middleware\NotFoundMiddleware;
    8. use Website\Middleware\ResponseMiddleware;
    10. /**
    11.  * Create a new Events Manager.
    12.  */
    13. $eventsManager = new Manager();
    14. $application   = new Micro();
    16. /**
    17.  * Attach the middleware both to the events manager and the application
    18.  */
    19. $eventsManager->attach(
    20.     'micro',
    21.     new CacheMiddleware()
    22. );
    24. $application->before(
    25.     new CacheMiddleware()
    26. );
    28. $eventsManager->attach(
    29.     'micro',
    30.     new NotFoundMiddleware()
    31. );
    33. $application->before(
    34.     new NotFoundMiddleware()
    35. );
    37. /**
    38.  * This one needs to listen on the `after` event
    39.  */
    40. $eventsManager->attach(
    41.     'micro',
    42.     new ResponseMiddleware()
    43. );
    45. $application->after(
    46.     new ResponseMiddleware()
    47. );
    49. /**
    50.  * Make sure our events manager is in the DI container now
    51.  */
    52. $application->setEventsManager($eventsManager);

    We need a Phalcon\Events\Manager object. This can be a newly instantiated object or we can get the one that exists in our DI container (if you have used the FactoryDefault one).

    We attach every middleware class in the micro hook in the Events Manager. We could also be a bit more specific and attach it to say the micro:beforeExecuteRoute event.

    We then attach the middleware class in our application on one of the three listening events discussed above (before, after, finish).

    Implementation

    Middleware can be any kind of PHP callable functions. You can organize your code whichever way you like it to implement middleware. If you choose to use classes for your middleware, you will need them to implement the Phalcon\Mvc\Micro\MiddlewareInterface

    1. <?php
    3. use Phalcon\Mvc\Micro;
    4. use Phalcon\Mvc\Micro\MiddlewareInterface;
    6. /**
    7.  * CacheMiddleware
    8.  *
    9.  * Caches pages to reduce processing
    10.  */
    11. class CacheMiddleware implements MiddlewareInterface
    12. {
    13.     /**
    14.      * Calls the middleware
    15.      *
    16.      * @param Micro $application
    17.      * @returns bool
    18.      */
    19.     public function call(Micro $application)
    20.     {
    21.         $cache  = $application['cache'];
    22.         $router = $application['router'];
    24.         $key = preg_replace(
    25.             '/^[a-zA-Z0-9]/',
    26.             '',
    27.             $router->getRewriteUri()
    28.         );
    30.         // Check if the request is cached
    31.         if ($cache->exists($key)) {
    32.             echo $cache->get($key);
    34.             return false;
    35.         }
    37.         return true;
    38.     }
    39. }

    Events in Middleware

    The events that are triggered for our application also trigger inside a class that implements the . This offers great flexibility and power for developers since we can interact with the request process.

    API example

    Assume that we have an API that we have implemented with the Micro application. We will need to attach different Middleware classes in the application so that we can better control the execution of the application.

    The middleware that we will use are:

    • Firewall
    • NotFound
    • Redirect
    • CORS
    • Request
    • Response

    Firewall Middleware

    This middleware is attached to the before event of our Micro application. The purpose of this middleware is to check who is calling our API and based on a whitelist, allow them to proceed or not

    1. <?php
    3. use Phalcon\Events\Event;
    4. use Phalcon\Mvc\Micro;
    5. use Phalcon\Mvc\Micro\MiddlewareInterface;
    7. /**
    8.  * FirewallMiddleware
    9.  *
    10.  * Checks the whitelist and allows clients or not
    11.  */
    12. class FirewallMiddleware implements MiddlewareInterface
    13. {
    14.     /**
    15.      * Before anything happens
    16.      *
    17.      * @param Event $event
    18.      * @param Micro $application
    19.      *
    20.      * @returns bool
    21.      */
    22.     public function beforeHandleRoute(Event $event, Micro $application)
    23.     {
    24.         $whitelist = [
    25.             '10.4.6.1',
    26.             '10.4.6.2',
    27.             '10.4.6.3',
    28.             '10.4.6.4',
    29.         ];
    31.         $ipAddress = $application->request->getClientAddress();
    33.         if (true !== array_key_exists($ipAddress, $whitelist)) {
    34.             $this->response->redirect('/401');
    35.             $this->response->send();
    37.             return false;
    38.         }
    40.         return true;
    41.     }
    43.     /**
    44.      * Calls the middleware
    45.      *
    46.      * @param Micro $application
    47.      *
    48.      * @returns bool
    49.      */
    50.     public function call(Micro $application)
    51.     {
    52.         return true;
    53.     }
    54. }

    Not Found Middleware

    When this middleware is processed, this means that the requesting IP is allowed to access our application. The application will try and match the route and if not found the beforeNotFound event will fire. We will stop the processing then and send back to the user the relevant 404 response. This middleware is attached to the before event of our Micro application

    1. <?php
    3. use Phalcon\Mvc\Micro;
    4. use Phalcon\Mvc\Micro\MiddlewareInterface;
    6. /**
    7.  * NotFoundMiddleware
    8.  *
    9.  * Processes the 404s
    10.  */
    11. class NotFoundMiddleware implements MiddlewareInterface
    12. {
    13.     /**
    14.      * The route has not been found
    15.      *
    16.      * @returns bool
    17.      */
    18.     public function beforeNotFound()
    19.     {
    20.         $this->response->redirect('/404');
    21.         $this->response->send();
    23.         return false;
    24.     }
    26.     /**
    27.      * Calls the middleware
    28.      *
    29.      * @param Micro $application
    30.      *
    31.      * @returns bool
    32.      */
    33.     public function call(Micro $application)
    34.     {
    35.         return true;
    36.     }
    37. }

    Redirect Middleware

    We attach this middleware again to the before event of our Micro application because we don’t want the request to proceed if the requested endpoint needs to be redirected.

    1. <?php
    3. use Phalcon\Events\Event;
    4. use Phalcon\Mvc\Micro;
    5. use Phalcon\Mvc\Micro\MiddlewareInterface;
    7. /**
    8.  * RedirectMiddleware
    9.  *
    10.  * Checks the request and redirects the user somewhere else if need be
    11.  */
    12. class RedirectMiddleware implements MiddlewareInterface
    13. {
    14.     /**
    15.      * Before anything happens
    16.      *
    17.      * @param Event $event
    18.      * @param Micro $application
    19.      *
    20.      * @returns bool
    21.      */
    22.     public function beforeHandleRoute(Event $event, Micro $application)
    23.     {
    24.         if ('github' === $application->request->getURI()) {
    25.             $application->response->redirect('https://github.com');
    26.             $application->response->send();
    28.             return false;
    29.         }
    31.         return true;
    32.     }
    34.     /**
    35.      * Calls the middleware
    36.      *
    37.      * @param Micro $application
    38.      *
    39.      * @returns bool
    40.      */
    41.     public function call(Micro $application)
    42.     {
    43.         return true;
    44.     }
    45. }

    CORS Middleware

    Again this middleware is attached to the before event of our Micro application. We need to ensure that it fires before anything happens with our application

    1. <?php
    3. use Phalcon\Events\Event;
    4. use Phalcon\Mvc\Micro;
    5. use Phalcon\Mvc\Micro\MiddlewareInterface;
    7. /**
    8.  * CORSMiddleware
    9.  *
    10.  * CORS checking
    11.  */
    12. class CORSMiddleware implements MiddlewareInterface
    13. {
    14.     /**
    15.      * Before anything happens
    16.      *
    17.      * @param Event $event
    18.      * @param Micro $application
    19.      *
    20.      * @returns bool
    21.      */
    22.     public function beforeHandleRoute(Event $event, Micro $application)
    23.     {
    24.         if ($application->request->getHeader('ORIGIN')) {
    25.             $origin = $application->request->getHeader('ORIGIN');
    26.         } else {
    27.             $origin = '*';
    28.         }
    30.         $application
    31.             ->response
    32.             ->setHeader('Access-Control-Allow-Origin', $origin)
    33.             ->setHeader(
    34.                 'Access-Control-Allow-Methods',
    35.                 'GET,PUT,POST,DELETE,OPTIONS'
    36.             )
    37.             ->setHeader(
    38.                 'Access-Control-Allow-Headers',
    39.                 'Origin, X-Requested-With, Content-Range, ' .
    40.                 'Content-Disposition, Content-Type, Authorization'
    41.             )
    42.             ->setHeader('Access-Control-Allow-Credentials', 'true');
    43.     }
    45.     /**
    46.      * Calls the middleware
    47.      *
    48.      * @param Micro $application
    49.      *
    50.      * @returns bool
    51.      */
    52.     public function call(Micro $application)
    53.     {
    54.         return true;
    55.     }
    56. }

    Request Middleware

    This middleware is receiving a JSON payload and checks it. If the JSON payload is not valid it will stop execution.

    1. <?php
    3. use Phalcon\Events\Event;
    4. use Phalcon\Mvc\Micro;
    5. use Phalcon\Mvc\Micro\MiddlewareInterface;
    7. /**
    8.  * RequestMiddleware
    9.  *
    10.  * Check incoming payload
    11.  */
    12. class RequestMiddleware implements MiddlewareInterface
    13. {
    14.     /**
    15.      * Before the route is executed
    16.      *
    17.      * @param Event $event
    18.      * @param Micro $application
    19.      *
    20.      * @returns bool
    21.      */
    22.     public function beforeExecuteRoute(Event $event, Micro $application)
    23.     {
    24.         json_decode(
    25.             $application->request->getRawBody()
    26.         );
    28.         if (JSON_ERROR_NONE !== json_last_error()) {
    29.             $application->response->redirect('/malformed');
    30.             $application->response->send();
    32.             return false;
    33.         }
    35.         return true;
    37.     }
    39.     /**
    40.      * Calls the middleware
    41.      *
    42.      * @param Micro $application
    43.      *
    44.      * @returns bool
    45.      */
    46.     public function call(Micro $application)
    47.     {
    48.         return true;
    49.     }
    50. }

    Response Middleware

    This middleware is responsible for manipulating our response and sending it back to the caller as a JSON string. Therefore we need to attach it to the after event of our Micro application.

    We are going to be using the call method for this middleware, since we have nearly executed the whole request cycle.

    1. <?php
    3. use Phalcon\Mvc\Micro;
    4. use Phalcon\Mvc\Micro\MiddlewareInterface;
    6. /**
    7. * ResponseMiddleware
    8. *
    9. * Manipulates the response
    10. */
    11. class ResponseMiddleware implements MiddlewareInterface
    12. {
    13.      /**
    14.       * Before anything happens
    15.       *
    16.       * @param Micro $application
    17.       *
    18.       * @returns bool
    19.       */
    20.     public function call(Micro $application)
    21.     {
    22.         $payload = [
    23.             'code'    => 200,
    24.             'status'  => 'success',
    25.             'message' => '',
    26.             'payload' => $application->getReturnedValue(),
    27.         ];
    29.         $application->response->setJsonContent($payload);
    30.         $application->response->send();
    32.         return true;
    33.     }
    34. }

    Models

    Models can be used in Micro applications, so long as we instruct the application how it can find the relevant classes with an autoloader.

    1. <?php
    3. $loader = new \Phalcon\Loader();
    4. $loader
    5.     ->registerDirs(
    6.         [
    7.             __DIR__ . '/models/',
    8.         ]
    9.     )
    10.     ->register();
    12. $app = new \Phalcon\Mvc\Micro();
    14. $app->get(
    15.     '/products/find',
    16.     function () {
    17.         $products = \MyModels\Products::find();
    19.         foreach ($products as $product) {
    20.             echo $product->name, '<br>';
    21.         }
    22.     }
    23. );
    25. $app->handle(
    26.     $_SERVER["REQUEST_URI"]
    27. );

    Inject model instances

    By using the class you can inject model instances into your routes:

    1. <?php
    3. $loader = new \Phalcon\Loader();
    5. $loader->registerDirs(
    6.     [
    7.         __DIR__ . '/models/',
    8.     ]
    9. )->register();
    11. $app = new \Phalcon\Mvc\Micro();
    13. $app->setModelBinder(
    14.     new \Phalcon\Mvc\Model\Binder()
    15. );
    17. $app->get(
    18.     "/products/{product:[0-9]+}",
    19.     function (Products $product) {
    20.         // do anything with $product object
    21.     }
    22. );
    24. $app->handle(
    25.     $_SERVER["REQUEST_URI"]
    26. );

    Since Binder object is using internally Reflection Api which can be heavy, there is ability to set a cache so as to speed up the process. This can be done by using the second argument of setModelBinder() which can also accept a service name or just by passing a cache instance to the Binder constructor.

    Currently the binder will only use the models primary key to perform a findFirst() on. An example route for the above would be /products/1.

    Phalcon\Mvc\Micro does not have inherently a view service. We can however use the component to render views.

    1. <?php
    3. $app = new Phalcon\Mvc\Micro();
    5. $app['view'] = function () {
    6.     $view = new \Phalcon\Mvc\View\Simple();
    8.     $view->setViewsDir('app/views/');
    10.     return $view;
    11. };
    13. // Return a rendered view
    14. $app->get(
    15.     '/products/show',
    16.     function () use ($app) {
    17.         // Render app/views/products/show.phtml passing some variables
    18.         echo $app['view']->render(
    19.             'products/show',
    20.             [
    21.                 'id'   => 100,
    22.                 'name' => 'Artichoke',
    23.             ]
    24.         );
    25.     }
    26. );

    The above example uses the Phalcon\Mvc\View\Simple component, which uses relative paths instead of controllers and actions. You can use the component instead, but to do so you will need to change the parameters passed to render().

    1. <?php
    3. $app = new Phalcon\Mvc\Micro();
    5. $app['view'] = function () {
    6.     $view = new \Phalcon\Mvc\View();
    8.     $view->setViewsDir('app/views/');
    10.     return $view;
    11. };
    13. // Return a rendered view
    14. $app->get(
    15.     '/products/show',
    16.     function () use ($app) {
    17.         // Render app/views/products/show.phtml passing some variables
    18.         echo $app['view']->render(
    19.             'products',
    20.             'show',
    21.             [
    22.                 'id'   => 100,
    23.                 'name' => 'Artichoke',
    24.             ]
    25.         );
    26.     }
    27. );

    Error Handling

    The application also has an error method, which can be used to trap any errors that originate from exceptions. The following code snippet shows basic usage of this feature: