Building Lightweight REST APIs with Phalcon Micro

Reducing Overhead with the Micro Application

When building a REST API, the full Model-View-Controller (MVC) pattern often introduces unnecessary directory nesting and routing overhead. Phalcon Micro allows you to bypass the heavy dispatcher and controller architecture, mapping HTTP methods directly to handlers. This reduces the execution path and memory footprint, making it ideal for microservices or high-throughput endpoints.

Core Mechanism: Routing and Dependency Injection

The Phalcon\Mvc\Micro class acts as both the router and the application kernel. Instead of defining routes in a separate configuration file that the dispatcher then parses to find a controller, you bind the URI directly to a callable (an anonymous function or a class method). To maintain clean code, you use the Dependency Injector (DI) to provide shared services like database connections or JSON response formatters to these handlers.

Implementation Example

The following example demonstrates a basic API structure. This assumes you have the Phalcon extension installed and enabled in your php.ini. Run php -m | grep phalcon in your terminal to verify the extension is loaded before proceeding.

setShared('response', function () {
    return new Response();
});

$app = new Micro($di);

// 2. Define a GET route with a closure
$app->get('/api/status', function () use ($app) {
    return $app->response
        ->setStatusCode(200, 'OK')
        ->setJsonContent(['status' => 'online', 'version' => '1.0']);
});

// 3. Define a POST route that accepts parameters
$app->post('/api/echo', function () use ($app) {
    $data = $app->request->getJsonRawBody();
    
    if (empty($data)) {
        return $app->response
            ->setStatusCode(400, 'Bad Request')
            ->setJsonContent(['error' => 'No data provided']);
    }

    return $app->response
        ->setJsonContent(['received' => $data]);
});

// 4. Handle the request
// Note: $_GET['_url'] or $_SERVER['_url'] depends on your rewrite rules
$app->handle($_SERVER['_url'] ?? '/');

Scaling Logic with Handler Classes

A common mistake in Micro applications is placing all business logic inside the index.php file, leading to "fat" route files that are difficult to test. To avoid this, delegate the logic to separate handler classes.

Instead of a closure, pass an array containing the object and the method name:

$userHandler = new UserHandler();
$app->get('/api/users/{id}', [$userHandler, 'getUserAction']);

Limitations and Performance Risks

• Extension Dependency: Because Phalcon is delivered as a C-extension, you cannot simply composer install the core framework. Version mismatches between the PHP runtime (e.g., PHP 8.1 vs 8.2) and the compiled extension will result in a fatal segmentation fault.
• Memory Leaks: While the C-extension manages its own memory efficiently, using large closures that capture heavy objects via the use keyword in long-running processes (like RoadRunner or Swoole) can lead to PHP-level memory leaks.
• Routing Complexity: Micro is not designed for complex nested routing or deep URI hierarchies. If your API requires complex grouping and middleware stacks for dozens of endpoints, the full MVC stack's Router and Dispatcher are more maintainable.

Verification and Diagnostics

To verify the application is routing correctly, use curl to check the response headers and body. Ensure your web server (Nginx or Apache) is configured to forward all requests to index.php.

Test Command:
curl -X GET http://localhost/api/status

Expected Result:
HTTP/1.1 200 OK
Content-Type: application/json
{"status":"online","version":"1.0"}

If you receive a 404 from the web server rather than the application, check your .htaccess or Nginx try_files directive to ensure the _url parameter is being passed to the PHP script.