{"id":15026052,"url":"https://github.com/headio/phalcon-bootstrap","last_synced_at":"2026-03-07T03:30:58.424Z","repository":{"id":62515230,"uuid":"233241165","full_name":"headio/phalcon-bootstrap","owner":"headio","description":"A flexible application bootstrap for Phalcon-based projects","archived":false,"fork":false,"pushed_at":"2022-03-02T09:06:24.000Z","size":175,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"5.x","last_synced_at":"2025-06-14T17:05:51.100Z","etag":null,"topics":["api","bootstrapping","cli","di-container","modular","mvc","phalcon","phalcon-bootstrap","phalcon4","phalcon5","php7","php72","php73","php74","php8","php80"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/headio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-01-11T14:04:27.000Z","updated_at":"2023-02-23T14:24:23.000Z","dependencies_parsed_at":"2022-11-02T13:03:28.072Z","dependency_job_id":null,"html_url":"https://github.com/headio/phalcon-bootstrap","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/headio/phalcon-bootstrap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/headio%2Fphalcon-bootstrap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/headio%2Fphalcon-bootstrap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/headio%2Fphalcon-bootstrap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/headio%2Fphalcon-bootstrap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/headio","download_url":"https://codeload.github.com/headio/phalcon-bootstrap/tar.gz/refs/heads/5.x","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/headio%2Fphalcon-bootstrap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30206562,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T03:24:23.086Z","status":"ssl_error","status_checked_at":"2026-03-07T03:23:11.444Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","bootstrapping","cli","di-container","modular","mvc","phalcon","phalcon-bootstrap","phalcon4","phalcon5","php7","php72","php73","php74","php8","php80"],"created_at":"2024-09-24T20:03:37.585Z","updated_at":"2026-03-07T03:30:58.405Z","avatar_url":"https://github.com/headio.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Phalcon application bootstrap\n\nA flexible application bootstrap for Phalcon-based projects  \n\n[![Build Status](https://travis-ci.com/headio/phalcon-bootstrap.svg?branch=5.x)](https://travis-ci.com/headio/phalcon-bootstrap) [![Coverage Status](https://coveralls.io/repos/github/headio/phalcon-bootstrap/badge.svg?branch=5.x)](https://coveralls.io/github/headio/phalcon-bootstrap?branch=5.x)\n\n## Description\n\nThis library provides flexible application bootstrapping, encapsulating module registration (or handler registration for micro applications), event management and middleware logic assignment for mvc, micro and cli-based applications.\nA simple factory instantiates the dependency injection container, encapsulating the registration of service dependency definitions defined in the configuration setttings.\n\n## Dependencies\n\n* PHP \u003e=8.0\n* Phalcon \u003e=5.0.0\n\nSee composer.json for more details  \n\n## Installation\n\n### Composer\n\nOpen a terminal window and run:\n\n```bash\ncomposer require headio/phalcon-bootstrap\n```\n\n## Usage\n\n### Micro applications (Api, prototype or micro service)\n\nFirst create a config definition file inside your Phalcon project. This file should include the configuration settings, service \u0026 middleware definitions and a path to your handlers.\n\nTo get started, let's assume the following project structure:\n\n```bash\n├── public\n│   ├── index.php\n├── src\n│   ├── Config\n│   │    │── Config.php\n│   │    │── Handlers.php\n│   │── Controller\n│   │── Domain\n│   │── Middleware\n│   │── Service\n│   │── Var\n│   │    │── Log\n├── tests\n├── vendor\n├── Boot.php\n├── codeception.yml\n├── composer.json\n├── .gitignore\n├── README.md\n└── .travis.yml\n```\n\nand your PSR-4 autoload declaration is:\n\n```json\n{\n    \"autoload\": {\n        \"psr-4\": {\n            \"Foo\\\\\": \"src/\"\n        }\n    }\n}\n```\n\nCreate a config file **Config.php** inside the **Config** directory and copy-\u0026-paste the following definition:\n\n```php\n\u003c?php\n\nnamespace Foo\\Config;\n\nuse Foo\\Middleware\\NotFoundMiddleware;\n\nreturn [\n    'applicationPath' =\u003e dirname(__DIR__) . DIRECTORY_SEPARATOR,\n    'debug' =\u003e true,\n    'locale' =\u003e 'en_GB',\n    'logPath' =\u003e dirname(__DIR__) .\n        DIRECTORY_SEPARATOR . 'Var' .\n        DIRECTORY_SEPARATOR . 'Log' .\n        DIRECTORY_SEPARATOR,\n    'handlerPath' =\u003e __DIR__ . DIRECTORY_SEPARATOR . 'Handlers.php',\n    'middleware' =\u003e [\n        NotFoundMiddleware::class =\u003e 'before'\n    ],\n    'services' =\u003e [\n        'Foo\\Service\\EventManager',\n        'Foo\\Service\\Logger',\n    ],\n    'timezone' =\u003e 'Europe\\London'\n];\n```\n\nThe **handlerPath** declaration must include your handlers; the best strategy is to utilize Phalcon collections. The contents of this file might look something like this:\n\n```php\n\u003c?php\nnamespace Foo\\Config;\n\nuse Foo\\Controller\\Index;\nuse Phalcon\\Mvc\\Micro\\Collection;\n\n$handler = new Collection();\n$handler-\u003esetHandler(Index::class, true);\n$handler-\u003esetPrefix('/');\n$handler-\u003eget('/', 'indexAction', 'apiIndex');\n$app-\u003emount($handler);\n```\n\nNow, create an index file inside the **public** directory and copy-\u0026-paste the following:\n\n```php\n\u003c?php\ndeclare(strict_types=1);\n\nchdir(dirname(__DIR__));\nrequire 'Boot.php';\n```\n\nFinally, paste the following bootstrap code inside the **Boot.php** file:\n\n```php\n\u003c?php\ndeclare(strict_types=1);\n\nuse Headio\\Phalcon\\Bootstrap\\Bootstrap;\nuse Headio\\Phalcon\\Bootstrap\\Di\\Factory as DiFactory;\nuse Phalcon\\Config\\Config;\n\nrequire_once __DIR__ . '/vendor/autoload.php';\n\n// Micro example\n(function () {\n    $config = new Config(\n        require __DIR__ . '/src/Config/Config.php'\n    );\n\n    $di = (new DiFactory($config))-\u003ecreateDefaultMvc();\n\n    // Environment\n    if (extension_loaded('mbstring')) {\n        mb_internal_encoding('UTF-8');\n        mb_substitute_character('none');\n    }\n\n    set_error_handler(\n        function ($severity, $message, $file, $line) {\n            if (!(error_reporting() \u0026 $severity)) {\n                // Unmasked error context\n                return;\n            }\n            throw new \\ErrorException($message, 0, $severity, $file, $line);\n        }\n    );\n\n    set_exception_handler(\n        function (Throwable $e) use ($di) {\n            $di-\u003eget('logger')-\u003eerror($e-\u003egetMessage(), ['exception' =\u003e $e]);\n\n            // Verbose exception handling for development\n            if ($di-\u003eget('config')-\u003edebug) {\n            }\n\n            exit(1);\n        }\n    );\n\n    // Run the application\n    return Bootstrap::handle($di)-\u003erun($_SERVER['REQUEST_URI'], Bootstrap::Micro);\n})();\n```\n\n### Mvc applications\n\nCreate a config definition file inside your Phalcon project. This file should include your configuration settings and service \u0026 middleware definitions.\n\nLet's assume the following mvc project structure:\n\n```bash\n├── public\n│   ├── index.php\n├── src\n│   ├── Config\n│   │    │── Config.php\n│   │── Controller\n│   │── Domain\n│   │── Middleware\n│   │── Module\n│   │    │── Admin\n│   │    │    │── Controller\n│   │    │    │── Form\n│   │    │    │── Task\n│   │    │    │── View\n│   │    │    │── Module.php\n│   │── Service\n│   │── Var\n│   │    │── Log\n├── tests\n├── vendor\n├── Boot.php\n├── codeception.yml\n├── composer.json\n├── .gitignore\n├── README.md\n└── .travis.yml\n```\n\nand your PSR-4 autoload declaration is:\n\n```json\n{\n    \"autoload\": {\n        \"psr-4\": {\n            \"Foo\\\\\": \"src/\"\n        }\n    }\n}\n```\n\nCreate a config file **Config.php** inside the **Config** directory and copy-\u0026-paste the following definition:\n\n```php\n\u003c?php\n\nnamespace Foo\\Config;\n\nreturn [\n    'annotations' =\u003e [\n        'adapter' =\u003e 'Apcu',\n        'options' =\u003e [\n            'lifetime' =\u003e 3600 * 24 * 30,\n            'prefix' =\u003e 'annotations',\n        ],\n    ],\n    'applicationPath' =\u003e dirname(__DIR__) . DIRECTORY_SEPARATOR,\n    'baseUri' =\u003e '/',\n    'debug' =\u003e true,\n    'dispatcher' =\u003e [\n        'defaultAction' =\u003e 'index',\n        'defaultController' =\u003e 'Admin',\n        'defaultControllerNamespace' =\u003e 'Foo\\\\Module\\\\Admin\\\\Controller',\n        'defaultModule' =\u003e 'admin'\n    ],\n    'locale' =\u003e 'en_GB',\n    'logPath' =\u003e dirname(__DIR__) .\n        DIRECTORY_SEPARATOR . 'Var' .\n        DIRECTORY_SEPARATOR . 'Log' .\n        DIRECTORY_SEPARATOR,\n    'modules' =\u003e [\n        'admin' =\u003e [\n            'className' =\u003e 'Foo\\\\Module\\\\Admin\\\\Module',\n            'path' =\u003e dirname(__DIR__) . '/Module/Admin/Module.php'\n        ],\n    ],\n    'middleware' =\u003e [\n        'Foo\\\\Middleware\\\\Bar'\n    ],\n    'routes' =\u003e [\n        'admin' =\u003e [\n            'Foo\\Module\\Admin\\Controller\\Admin' =\u003e '/admin',\n        ],\n    ],\n    'services' =\u003e [\n        'Foo\\Service\\EventManager',\n        'Foo\\Service\\Logger',\n        'Foo\\Service\\Annotation',\n        'Foo\\Service\\Router',\n        'Foo\\Service\\View'\n    ],\n    'timezone' =\u003e 'Europe\\London',\n    'useI18n' =\u003e true,\n    'view' =\u003e [\n        'defaultPath' =\u003e dirname(__DIR__) . '/Module/Admin/View/',\n        'compiledPath' =\u003e dirname(__DIR__) . '/Cache/Volt/',\n        'compiledSeparator' =\u003e '_',\n    ]\n];\n```\n\nNow, create an index file inside the **public** directory and paste the following:\n\n```php\n\u003c?php\ndeclare(strict_types=1);\n\nchdir(dirname(__DIR__));\nrequire 'Boot.php';\n```\n\nFinally, paste the following bootstrap code inside the **Boot.php** file:\n\n```php\n\u003c?php\ndeclare(strict_types=1);\n\nuse Headio\\Phalcon\\Bootstrap\\Bootstrap;\nuse Headio\\Phalcon\\Bootstrap\\Di\\Factory as DiFactory;\nuse Phalcon\\Config\\Config;\n\nrequire_once __DIR__ . '/vendor/autoload.php';\n\n// Mvc example\n(function () {\n    $config = new Config(\n        require __DIR__ . '/src/Config/Config.php'\n    );\n\n    $di = (new DiFactory($config))-\u003ecreateDefaultMvc();\n\n    // Environment\n    if (extension_loaded('mbstring')) {\n        mb_internal_encoding('UTF-8');\n        mb_substitute_character('none');\n    }\n\n    set_error_handler(\n        function ($severity, $message, $file, $line) {\n            if (!(error_reporting() \u0026 $severity)) {\n                // Unmasked error context\n                return;\n            }\n            throw new \\ErrorException($message, 0, $severity, $file, $line);\n        }\n    );\n\n    set_exception_handler(\n        function (Throwable $e) use ($di) {\n            $di-\u003eget('logger')-\u003eerror($e-\u003egetMessage(), ['exception' =\u003e $e]);\n\n            // Verbose exception handling for development\n            if ($di-\u003eget('config')-\u003edebug) {\n            }\n\n            exit(1);\n        }\n    );\n\n    // Run the application\n    return Bootstrap::handle($di)-\u003erun($_SERVER['REQUEST_URI']);\n})();\n```\n\n### Console application\n\nCreate a config definition file inside your Phalcon project. This file should include your configuration settings and service \u0026 middleware definitions.\n\nLet's assume the following project structure:\n\n```bash\n├── src\n│   ├── Config\n│   │    │── Config.php\n│   │── Domain\n│   │── Middleware\n│   │── Service\n│   │── Task\n│   │── Var\n│   │    │── Log\n├── tests\n├── vendor\n├── Cli.php\n├── codeception.yml\n├── composer.json\n├── .gitignore\n├── README.md\n└── .travis.yml\n```\n\nand your PSR-4 autoload declaration is:\n\n```json\n{\n    \"autoload\": {\n        \"psr-4\": {\n            \"Foo\\\\\": \"src/\"\n        }\n    }\n}\n```\n\nCreate a config file **Config.php** inside the **Config** directory and copy-\u0026-paste the following definition:\n\n```php\n\u003c?php\n\nnamespace Foo\\Config;\n\nreturn [\n    'applicationPath' =\u003e dirname(__DIR__) . DIRECTORY_SEPARATOR,\n    'locale' =\u003e 'en_GB',\n    'logPath' =\u003e dirname(__DIR__) .\n        DIRECTORY_SEPARATOR . 'Var' .\n        DIRECTORY_SEPARATOR . 'Log' .\n        DIRECTORY_SEPARATOR,\n    'debug' =\u003e true,\n    'dispatcher' =\u003e [\n        'defaultTaskNamespace' =\u003e 'Foo\\\\Task',\n    ],\n    'middleware' =\u003e [\n    ],\n    'services' =\u003e [\n        'Foo\\Service\\EventManager',\n        'Foo\\Service\\Logger',\n        'Foo\\Service\\ConsoleOutput',\n    ],\n    'timezone' =\u003e 'Europe\\London'\n];\n```\n\nFinally, paste the following bootstrap code inside the **Cli.php** file:\n\n```php\n\u003c?php\ndeclare(strict_types=1);\n\nuse Headio\\Phalcon\\Bootstrap\\Cli\\Bootstrap;\nuse Headio\\Phalcon\\Bootstrap\\Di\\Factory as DiFactory;\nuse Phalcon\\Config\\Config;\n\nrequire_once __DIR__ . '/vendor/autoload.php';\n\n// Cli example\n(function () {\n    $config = new Config(\n        require __DIR__ . '/src/Config/Config.php'\n    );\n\n    $di = (new DiFactory($config))-\u003ecreateDefaultCli();\n\n    // Environment\n    set_error_handler(\n        function ($severity, $message, $file, $line) {\n            if (!(error_reporting() \u0026 $severity)) {\n                // Unmasked error context\n                return;\n            }\n            throw new \\ErrorException($message, 0, $severity, $file, $line);\n        }\n    );\n\n    set_exception_handler(\n        function (Throwable $e) use ($di) {\n            $di-\u003eget('logger')-\u003eerror($e-\u003egetMessage(), ['exception' =\u003e $e]);\n            $output = $di-\u003eget('consoleOutput');\n            $output-\u003ewriteln('\u003cerror\u003e' . $e-\u003egetMessage() . '\u003c/error\u003e');\n\n            // Verbose exception handling for development\n            if ($di-\u003eget('config')-\u003edebug) {\n                $output-\u003ewriteln(sprintf(\n                    '\u003cerror\u003eException thrown in: %s at line %d.\u003c/error\u003e',\n                    $e-\u003egetFile(),\n                    $e-\u003egetLine())\n                );\n            }\n\n            exit(1);\n        }\n    );\n\n    // Run the application\n    return Bootstrap::handle($di)-\u003erun($_SERVER);\n})();\n```\n\n## DI container factory\n\nFrom the examples above you will have noticed that we instantiated Phalcon's factory default mvc or cli container services.\n\n```php\n$config = new Config(\n    require __DIR__ . '/src/Config/Config.php'\n);\n\n// Micro/Mvc\n$di = (new DiFactory($config))-\u003ecreateDefaultMvc();\n\n// Cli\n$di = (new DiFactory($config))-\u003ecreateDefaultCli();\n```\n\nNaturally, you can override the factory default services by simply defining a service definition in your config file, like so:\n\n```php\n\u003c?php\nnamespace Foo\\Config\n\nreturn [\n    'services' =\u003e [\n        'Foo\\Service\\Router'\n    ]\n]\n\n```\n\nThen create the respective service provider and modify its behaviour:\n\n```php\n\u003c?php\n/**\n * This source file is subject to the MIT License.\n *\n * For the full copyright and license information, please view\n * the LICENSE file that was distributed with this package.\n */\ndeclare(strict_types=1);\n\nnamespace Foo\\Service;\n\nuse Foo\\Exception\\OutOfRangeException;\nuse Phalcon\\Config\\Config;\nuse Phalcon\\Di\\ServiceProviderInterface;\nuse Phalcon\\Di\\DiInterface;\nuse Phalcon\\Cli\\Router as CliService;\nuse Phalcon\\Mvc\\Router as MvcRouter;\nuse Phalcon\\Mvc\\Router\\Annotations as MvcService;\n\nclass Router implements ServiceProviderInterface\n{\n    /**\n     * {@inheritDoc}\n     */\n    public function register(DiInterface $di) : void\n    {\n        $di-\u003esetShared(\n            'router',\n            function () use ($di) {\n                $config = $di-\u003eget('config');\n\n                if ($config-\u003eget('cli')) {\n                    $service = new CliService();\n                    $service-\u003esetDefaultModule($config-\u003edispatcher-\u003edefaultTaskModule);\n                    return $service;\n                }\n\n                if (!$config-\u003ehas('modules')) {\n                    throw new OutOfRangeException('Undefined modules');\n                }\n\n                if (!$config-\u003ehas('routes')) {\n                    throw new OutOfRangeException('Undefined routes');\n                }\n\n                $service = new MvcService(false);\n                $service-\u003eremoveExtraSlashes(true);\n                $service-\u003esetDefaultNamespace($config-\u003edispatcher-\u003edefaultControllerNamespace);\n                $service-\u003esetDefaultModule($config-\u003edispatcher-\u003edefaultModule);\n                $service-\u003esetDefaultController($config-\u003edispatcher-\u003edefaultController);\n                $service-\u003esetDefaultAction($config-\u003edispatcher-\u003edefaultAction);\n\n                foreach ($config-\u003eget('modules')-\u003etoArray() ?? [] as $module =\u003e $settings) {\n                    if (!$config-\u003eroutes-\u003eget($module, false)) {\n                        continue;\n                    }\n                    foreach ($config-\u003eget('routes')-\u003e{$module}-\u003etoArray() ?? [] as $key =\u003e $val) {\n                        $service-\u003eaddModuleResource($module, $key, $val);\n                    }\n                }\n\n                return $service;\n            }\n        );\n    }\n}\n```\n\nFor complete control over the registration of service dependencies, or more generally, the services available in the container, you have two options: firstly, you can use Phalcon's base DI container, which is an empty container; or you can create your own DI container by implementing Phalcon's **Phalcon\\Di\\DiInterface**. See the following for an example:\n\n```php\nuse Phalcon\\Di;\nuse Foo\\Bar\\MyDi;\n\n$config = new Config(\n    require __DIR__ . '/src/Config/Config.php'\n);\n\n// Empty DI container\n$di = (new DiFactory($config))-\u003ecreate(new Di);\n\n// Custom DI container\n$di = (new DiFactory($config))-\u003ecreate(new MyDi);\n```\n\nThe DI factory **create method** expects an instance of **Phalcon\\Di\\DiInterface**.\n\n## Application factory\n\nThe bootstrap factory will automatically instantiate a Phalcon application and return the response. If you want to bootstrap the application yourself, you can use the application factory directly.\n\n```php\n\u003c?php\n/**\n * This source file is subject to the MIT License.\n *\n * For the full copyright and license information, please view\n * the LICENSE file that was distributed with this package.\n */\ndeclare(strict_types=1);\n\nuse Headio\\Phalcon\\Bootstrap\\Application\\Factory as AppFactory;\nuse Headio\\Phalcon\\Bootstrap\\Di\\Factory as DiFactory;\nuse Phalcon\\Config\\Config;\n\nchdir(dirname(__DIR__));\n\nrequire_once 'vendor/autoload.php';\n\n$config = new Config(\n    require 'src/Config/Config.php'\n);\n\ntry {\n    $di = (new DiFactory($config))-\u003ecreateDefaultMvc();\n\n    /** @var Phalcon\\Mvc\\Application */\n    $app = (new AppFactory($di))-\u003ecreateForMvc();\n\n    // Do some stuff\n\n    /** @var Phalcon\\Mvc\\ResponseInterface|bool */\n    $response = $app-\u003ehandle($_SERVER['REQUEST_URI']);\n\n    if ($response instanceof \\Phalcon\\Mvc\\ResponseInterface) {\n        return $response-\u003esend();\n    }\n\n    return $response;\n} catch(\\Throwable $e) {\n    echo $e-\u003egetMessage();\n}\n```\n\n## Testing\n\nTo see the tests, run:\n\n```bash\nphp vendor/bin/codecept run -f --coverage --coverage-text\n```\n\n## License\n\nPhalcon bootstrap is open-source and licensed under [MIT License](http://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheadio%2Fphalcon-bootstrap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheadio%2Fphalcon-bootstrap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheadio%2Fphalcon-bootstrap/lists"}