Share services across Phalcon micro routes with the DI container

You boot a Phalcon micro application, add a route, and instantiate a new PDO connection inside the closure. It works locally, but under load every request opens a fresh database connection. The fix is usually one line: register the connection in Phalcon\Di\Di as a shared service so the container returns the same instance to every route. Phalcon 5 requires PHP 8.0 or later and is distributed as a C extension. That means its core classes, including Phalcon\Di\Di, are loaded into PHP when the extension starts, not autoloaded from userland files. A dependency injection container is an object that creates and holds services so your route handlers do not have to construct them manually.

Register services once in Phalcon\Di\Di

Create the container, register a closure, and pass it to Phalcon\Micro. The third argument to set() controls whether the service is shared.

use Phalcon\Di\Di;
use Phalcon\Micro;

$container = new Di();

$container->set('db', function () {
    return new PDO('sqlite::memory:');
}, true);

$container->set('logger', function () {
    return new \\Psr\\Log\\NullLogger();
});

$app = new Micro($container);

$app->get('/users', function () use ($container) {
    $db = $container->getShared('db');
    $logger = $container->get('logger');

    $logger->info('Handling /users');
    return $app->response->setJsonContent(['status' => 'ok']);
});

$app->handle();

set('db', ..., true) is equivalent to setShared('db', ...). Every call to getShared('db') returns the same PDO object. get('logger') returns a fresh instance each time unless you registered it as shared.

Shared versus non-shared behavior

Method	Result	Use case
getShared('db')	Same instance on every call	Database connections, loggers, configuration
get('logger')	New instance on every call	Request-scoped objects, short-lived helpers

Service names are case-sensitive strings. A typo in the key causes a runtime resolution error, not an autoloader warning.

Check the extension before you deploy

Because Phalcon is a C extension, upgrading PHP or the operating system may require reinstalling or recompiling it. There is no pure userland fallback. Verify the extension on the target server before deploying code that depends on it.

Run these commands in the application terminal as a user with read access to the PHP installation:

• php -m | grep phalcon — expected: phalcon appears in the module list. Risk: empty output means the extension is not loaded.
• php -r 'echo phpversion("phalcon");' — expected: a version string such as 5.x. Risk: a fatal error if the extension is missing.

Match the installed Phalcon package to your PHP version using your OS package manager or PECL before deploying to production.

Limitation: shared state survives across requests in long-running workers

If you run Phalcon under RoadRunner, Swoole, or another long-running worker, a shared service keeps its state across requests. A database connection left in a transaction, or a logger holding request-specific context, can leak into the next request. Reset shared services at the start of each request or avoid shared state for request-scoped data.

Verify shared behavior locally

Register a closure-based service, fetch it twice with getShared(), and compare the instances with ===. If they are identical, the container is sharing the instance as intended.

Register shared services for expensive resources, verify the C extension on every target server, and treat shared instances as potential state carriers in long-running workers.