Phalcon application bootstrap

A flexible application bootstrap for Phalcon-based projects

Description

This 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. A simple factory instantiates the dependency injection container, encapsulating the registration of service dependency definitions defined in the configuration setttings.

Dependencies

PHP >=8.0
Phalcon >=5.0.0

See composer.json for more details

Installation

Composer

Open a terminal window and run:

composer require headio/phalcon-bootstrap

Usage

Micro applications (Api, prototype or micro service)

First create a config definition file inside your Phalcon project. This file should include the configuration settings, service & middleware definitions and a path to your handlers.

To get started, let's assume the following project structure:

├── public
│   ├── index.php
├── src
│   ├── Config
│   │    │── Config.php
│   │    │── Handlers.php
│   │── Controller
│   │── Domain
│   │── Middleware
│   │── Service
│   │── Var
│   │    │── Log
├── tests
├── vendor
├── Boot.php
├── codeception.yml
├── composer.json
├── .gitignore
├── README.md
└── .travis.yml

and your PSR-4 autoload declaration is:

{
    "autoload": {
        "psr-4": {
            "Foo\\": "src/"
        }
    }
}

Create a config file Config.php inside the Config directory and copy-&-paste the following definition:

<?php

namespace Foo\Config;

use Foo\Middleware\NotFoundMiddleware;

return [
    'applicationPath' => dirname(__DIR__) . DIRECTORY_SEPARATOR,
    'debug' => true,
    'locale' => 'en_GB',
    'logPath' => dirname(__DIR__) .
        DIRECTORY_SEPARATOR . 'Var' .
        DIRECTORY_SEPARATOR . 'Log' .
        DIRECTORY_SEPARATOR,
    'handlerPath' => __DIR__ . DIRECTORY_SEPARATOR . 'Handlers.php',
    'middleware' => [
        NotFoundMiddleware::class => 'before'
    ],
    'services' => [
        'Foo\Service\EventManager',
        'Foo\Service\Logger',
    ],
    'timezone' => 'Europe\London'
];

The handlerPath declaration must include your handlers; the best strategy is to utilize Phalcon collections. The contents of this file might look something like this:

<?php
namespace Foo\Config;

use Foo\Controller\Index;
use Phalcon\Mvc\Micro\Collection;

$handler = new Collection();
$handler->setHandler(Index::class, true);
$handler->setPrefix('/');
$handler->get('/', 'indexAction', 'apiIndex');
$app->mount($handler);

Now, create an index file inside the public directory and copy-&-paste the following:

<?php
declare(strict_types=1);

chdir(dirname(__DIR__));
require 'Boot.php';

Finally, paste the following bootstrap code inside the Boot.php file:

<?php
declare(strict_types=1);

use Headio\Phalcon\Bootstrap\Bootstrap;
use Headio\Phalcon\Bootstrap\Di\Factory as DiFactory;
use Phalcon\Config\Config;

require_once __DIR__ . '/vendor/autoload.php';

// Micro example
(function () {
    $config = new Config(
        require __DIR__ . '/src/Config/Config.php'
    );

    $di = (new DiFactory($config))->createDefaultMvc();

    // Environment
    if (extension_loaded('mbstring')) {
        mb_internal_encoding('UTF-8');
        mb_substitute_character('none');
    }

    set_error_handler(
        function ($severity, $message, $file, $line) {
            if (!(error_reporting() & $severity)) {
                // Unmasked error context
                return;
            }
            throw new \ErrorException($message, 0, $severity, $file, $line);
        }
    );

    set_exception_handler(
        function (Throwable $e) use ($di) {
            $di->get('logger')->error($e->getMessage(), ['exception' => $e]);

            // Verbose exception handling for development
            if ($di->get('config')->debug) {
            }

            exit(1);
        }
    );

    // Run the application
    return Bootstrap::handle($di)->run($_SERVER['REQUEST_URI'], Bootstrap::Micro);
})();

Mvc applications

Create a config definition file inside your Phalcon project. This file should include your configuration settings and service & middleware definitions.

Let's assume the following mvc project structure:

├── public
│   ├── index.php
├── src
│   ├── Config
│   │    │── Config.php
│   │── Controller
│   │── Domain
│   │── Middleware
│   │── Module
│   │    │── Admin
│   │    │    │── Controller
│   │    │    │── Form
│   │    │    │── Task
│   │    │    │── View
│   │    │    │── Module.php
│   │── Service
│   │── Var
│   │    │── Log
├── tests
├── vendor
├── Boot.php
├── codeception.yml
├── composer.json
├── .gitignore
├── README.md
└── .travis.yml

and your PSR-4 autoload declaration is:

{
    "autoload": {
        "psr-4": {
            "Foo\\": "src/"
        }
    }
}

Create a config file Config.php inside the Config directory and copy-&-paste the following definition:

<?php

namespace Foo\Config;

return [
    'annotations' => [
        'adapter' => 'Apcu',
        'options' => [
            'lifetime' => 3600 * 24 * 30,
            'prefix' => 'annotations',
        ],
    ],
    'applicationPath' => dirname(__DIR__) . DIRECTORY_SEPARATOR,
    'baseUri' => '/',
    'debug' => true,
    'dispatcher' => [
        'defaultAction' => 'index',
        'defaultController' => 'Admin',
        'defaultControllerNamespace' => 'Foo\\Module\\Admin\\Controller',
        'defaultModule' => 'admin'
    ],
    'locale' => 'en_GB',
    'logPath' => dirname(__DIR__) .
        DIRECTORY_SEPARATOR . 'Var' .
        DIRECTORY_SEPARATOR . 'Log' .
        DIRECTORY_SEPARATOR,
    'modules' => [
        'admin' => [
            'className' => 'Foo\\Module\\Admin\\Module',
            'path' => dirname(__DIR__) . '/Module/Admin/Module.php'
        ],
    ],
    'middleware' => [
        'Foo\\Middleware\\Bar'
    ],
    'routes' => [
        'admin' => [
            'Foo\Module\Admin\Controller\Admin' => '/admin',
        ],
    ],
    'services' => [
        'Foo\Service\EventManager',
        'Foo\Service\Logger',
        'Foo\Service\Annotation',
        'Foo\Service\Router',
        'Foo\Service\View'
    ],
    'timezone' => 'Europe\London',
    'useI18n' => true,
    'view' => [
        'defaultPath' => dirname(__DIR__) . '/Module/Admin/View/',
        'compiledPath' => dirname(__DIR__) . '/Cache/Volt/',
        'compiledSeparator' => '_',
    ]
];

Now, create an index file inside the public directory and paste the following:

<?php
declare(strict_types=1);

chdir(dirname(__DIR__));
require 'Boot.php';

Finally, paste the following bootstrap code inside the Boot.php file:

<?php
declare(strict_types=1);

use Headio\Phalcon\Bootstrap\Bootstrap;
use Headio\Phalcon\Bootstrap\Di\Factory as DiFactory;
use Phalcon\Config\Config;

require_once __DIR__ . '/vendor/autoload.php';

// Mvc example
(function () {
    $config = new Config(
        require __DIR__ . '/src/Config/Config.php'
    );

    $di = (new DiFactory($config))->createDefaultMvc();

    // Environment
    if (extension_loaded('mbstring')) {
        mb_internal_encoding('UTF-8');
        mb_substitute_character('none');
    }

    set_error_handler(
        function ($severity, $message, $file, $line) {
            if (!(error_reporting() & $severity)) {
                // Unmasked error context
                return;
            }
            throw new \ErrorException($message, 0, $severity, $file, $line);
        }
    );

    set_exception_handler(
        function (Throwable $e) use ($di) {
            $di->get('logger')->error($e->getMessage(), ['exception' => $e]);

            // Verbose exception handling for development
            if ($di->get('config')->debug) {
            }

            exit(1);
        }
    );

    // Run the application
    return Bootstrap::handle($di)->run($_SERVER['REQUEST_URI']);
})();

Console application

Create a config definition file inside your Phalcon project. This file should include your configuration settings and service & middleware definitions.

Let's assume the following project structure:

├── src
│   ├── Config
│   │    │── Config.php
│   │── Domain
│   │── Middleware
│   │── Service
│   │── Task
│   │── Var
│   │    │── Log
├── tests
├── vendor
├── Cli.php
├── codeception.yml
├── composer.json
├── .gitignore
├── README.md
└── .travis.yml

and your PSR-4 autoload declaration is:

{
    "autoload": {
        "psr-4": {
            "Foo\\": "src/"
        }
    }
}

Create a config file Config.php inside the Config directory and copy-&-paste the following definition:

<?php

namespace Foo\Config;

return [
    'applicationPath' => dirname(__DIR__) . DIRECTORY_SEPARATOR,
    'locale' => 'en_GB',
    'logPath' => dirname(__DIR__) .
        DIRECTORY_SEPARATOR . 'Var' .
        DIRECTORY_SEPARATOR . 'Log' .
        DIRECTORY_SEPARATOR,
    'debug' => true,
    'dispatcher' => [
        'defaultTaskNamespace' => 'Foo\\Task',
    ],
    'middleware' => [
    ],
    'services' => [
        'Foo\Service\EventManager',
        'Foo\Service\Logger',
        'Foo\Service\ConsoleOutput',
    ],
    'timezone' => 'Europe\London'
];

Finally, paste the following bootstrap code inside the Cli.php file:

<?php
declare(strict_types=1);

use Headio\Phalcon\Bootstrap\Cli\Bootstrap;
use Headio\Phalcon\Bootstrap\Di\Factory as DiFactory;
use Phalcon\Config\Config;

require_once __DIR__ . '/vendor/autoload.php';

// Cli example
(function () {
    $config = new Config(
        require __DIR__ . '/src/Config/Config.php'
    );

    $di = (new DiFactory($config))->createDefaultCli();

    // Environment
    set_error_handler(
        function ($severity, $message, $file, $line) {
            if (!(error_reporting() & $severity)) {
                // Unmasked error context
                return;
            }
            throw new \ErrorException($message, 0, $severity, $file, $line);
        }
    );

    set_exception_handler(
        function (Throwable $e) use ($di) {
            $di->get('logger')->error($e->getMessage(), ['exception' => $e]);
            $output = $di->get('consoleOutput');
            $output->writeln('<error>' . $e->getMessage() . '</error>');

            // Verbose exception handling for development
            if ($di->get('config')->debug) {
                $output->writeln(sprintf(
                    '<error>Exception thrown in: %s at line %d.</error>',
                    $e->getFile(),
                    $e->getLine())
                );
            }

            exit(1);
        }
    );

    // Run the application
    return Bootstrap::handle($di)->run($_SERVER);
})();

DI container factory

From the examples above you will have noticed that we instantiated Phalcon's factory default mvc or cli container services.

$config = new Config(
    require __DIR__ . '/src/Config/Config.php'
);

// Micro/Mvc
$di = (new DiFactory($config))->createDefaultMvc();

// Cli
$di = (new DiFactory($config))->createDefaultCli();

Naturally, you can override the factory default services by simply defining a service definition in your config file, like so:

<?php
namespace Foo\Config

return [
    'services' => [
        'Foo\Service\Router'
    ]
]

Then create the respective service provider and modify its behaviour:

<?php
/**
 * This source file is subject to the MIT License.
 *
 * For the full copyright and license information, please view
 * the LICENSE file that was distributed with this package.
 */
declare(strict_types=1);

namespace Foo\Service;

use Foo\Exception\OutOfRangeException;
use Phalcon\Config\Config;
use Phalcon\Di\ServiceProviderInterface;
use Phalcon\Di\DiInterface;
use Phalcon\Cli\Router as CliService;
use Phalcon\Mvc\Router as MvcRouter;
use Phalcon\Mvc\Router\Annotations as MvcService;

class Router implements ServiceProviderInterface
{
    /**
     * {@inheritDoc}
     */
    public function register(DiInterface $di) : void
    {
        $di->setShared(
            'router',
            function () use ($di) {
                $config = $di->get('config');

                if ($config->get('cli')) {
                    $service = new CliService();
                    $service->setDefaultModule($config->dispatcher->defaultTaskModule);
                    return $service;
                }

                if (!$config->has('modules')) {
                    throw new OutOfRangeException('Undefined modules');
                }

                if (!$config->has('routes')) {
                    throw new OutOfRangeException('Undefined routes');
                }

                $service = new MvcService(false);
                $service->removeExtraSlashes(true);
                $service->setDefaultNamespace($config->dispatcher->defaultControllerNamespace);
                $service->setDefaultModule($config->dispatcher->defaultModule);
                $service->setDefaultController($config->dispatcher->defaultController);
                $service->setDefaultAction($config->dispatcher->defaultAction);

                foreach ($config->get('modules')->toArray() ?? [] as $module => $settings) {
                    if (!$config->routes->get($module, false)) {
                        continue;
                    }
                    foreach ($config->get('routes')->{$module}->toArray() ?? [] as $key => $val) {
                        $service->addModuleResource($module, $key, $val);
                    }
                }

                return $service;
            }
        );
    }
}

For 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:

use Phalcon\Di;
use Foo\Bar\MyDi;

$config = new Config(
    require __DIR__ . '/src/Config/Config.php'
);

// Empty DI container
$di = (new DiFactory($config))->create(new Di);

// Custom DI container
$di = (new DiFactory($config))->create(new MyDi);

The DI factory create method expects an instance of Phalcon\Di\DiInterface.

Application factory

The 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.

<?php
/**
 * This source file is subject to the MIT License.
 *
 * For the full copyright and license information, please view
 * the LICENSE file that was distributed with this package.
 */
declare(strict_types=1);

use Headio\Phalcon\Bootstrap\Application\Factory as AppFactory;
use Headio\Phalcon\Bootstrap\Di\Factory as DiFactory;
use Phalcon\Config\Config;

chdir(dirname(__DIR__));

require_once 'vendor/autoload.php';

$config = new Config(
    require 'src/Config/Config.php'
);

try {
    $di = (new DiFactory($config))->createDefaultMvc();

    /** @var Phalcon\Mvc\Application */
    $app = (new AppFactory($di))->createForMvc();

    // Do some stuff

    /** @var Phalcon\Mvc\ResponseInterface|bool */
    $response = $app->handle($_SERVER['REQUEST_URI']);

    if ($response instanceof \Phalcon\Mvc\ResponseInterface) {
        return $response->send();
    }

    return $response;
} catch(\Throwable $e) {
    echo $e->getMessage();
}

Testing

To see the tests, run:

php vendor/bin/codecept run -f --coverage --coverage-text

License

Phalcon bootstrap is open-source and licensed under MIT License.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Phalcon application bootstrap

Description

Dependencies

Installation

Composer

Usage

Micro applications (Api, prototype or micro service)

Mvc applications

Console application

DI container factory

Application factory

Testing

License

About

Releases

Packages

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 41 Commits
.ci		.ci
src		src
tests		tests
.gitignore		.gitignore
.php-cs-fixer.php		.php-cs-fixer.php
.travis.yml		.travis.yml
LICENSE		LICENSE
README.md		README.md
codeception.yml		codeception.yml
composer.json		composer.json
psalm.xml		psalm.xml

License

headio/phalcon-bootstrap

Folders and files

Latest commit

History

Repository files navigation

Phalcon application bootstrap

Description

Dependencies

Installation

Composer

Usage

Micro applications (Api, prototype or micro service)

Mvc applications

Console application

DI container factory

Application factory

Testing

License

About

Topics

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages