Tutorial - INVO¶

composer create-project phalcon/invo invo
cd invo

INVO is ready (.env created from .env.example). Next steps:
  docker: docker compose up -d --build, then composer migrate
  local:  install the v5 extension via PIE, or run on the bundled phalcon/phalcon (v6) as-is - see the README
  tests:  vendor/bin/talon run

composer migrate

php -S localhost:8080 -t public .htrouter.php

cp .env.example .env
docker compose up -d --build

# Create the database schema (migrations are not run on boot)
docker compose exec app composer migrate

docker compose up -d --build                      # v5 (C extension, default)
PHALCON_VARIANT=v6 docker compose up -d --build   # v6 (phalcon/phalcon, alpha)

docker compose up -d --build                  # PHP 8.5 (default)
PHP_VERSION=8.2 docker compose up -d --build  # PHP 8.2

PHP_VERSION=8.2 PROJECT_PREFIX=invo82 docker compose -p invo82 up -d --build

invo/
    config
    public
        css
        img
        js
    resources
        docker
        migrations
    src
        Constants
        Controllers
        Forms
        Models
        Plugins
        Providers
    tests
        Browser
        Functional
        Support
        Unit
    themes
        invo
    var

/:controller/:action/:params

<?php

declare(strict_types=1);

use Dotenv\Dotenv;
use Invo\Application;

error_reporting(E_ALL);

$rootPath = dirname(__DIR__);

try {
    require_once $rootPath . '/vendor/autoload.php';

    Dotenv::createImmutable($rootPath)->load();

    echo (new Application($rootPath))->run();
} catch (Exception $e) {
    echo $e->getMessage() . '<br>';
    echo '<pre>' . $e->getTraceAsString() . '</pre>';
}

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

<?php

declare(strict_types=1);

namespace Invo;

use Phalcon\Di\DiInterface;
use Phalcon\Di\FactoryDefault;
use Phalcon\Http\ResponseInterface;
use Phalcon\Mvc\Application as MvcApplication;

class Application
{
    protected MvcApplication $app;
    protected DiInterface $di;
    protected string $rootPath;

    public function __construct(string $rootPath)
    {
        $this->rootPath = $rootPath;

        $this->di = new FactoryDefault();
        $this->di->offsetSet('rootPath', function () use ($rootPath) {
            return $rootPath;
        });

        $this->app = new MvcApplication($this->di);

        $this->initializeProviders();
    }

    public function getRootPath(): string
    {
        return $this->rootPath;
    }

    public function run(): string
    {
        /** @var ResponseInterface $response */
        $response = $this->app->handle($_SERVER['REQUEST_URI']);

        return (string) $response->getContent();
    }

    protected function initializeProviders(): void
    {
        $filename = $this->rootPath . '/config/providers.php';
        if (!file_exists($filename) || !is_readable($filename)) {
            throw new Exception('File providers.php does not exist or is not readable.');
        }

        $providers = require $filename;
        foreach ($providers as $providerClass) {
            $this->di->register(new $providerClass());
        }
    }
}

<?php

return [
    \Invo\Providers\ConfigProvider::class,
    \Invo\Providers\DatabaseProvider::class,
    \Invo\Providers\DispatcherProvider::class,
    \Invo\Providers\FlashProvider::class,
    \Invo\Providers\SessionProvider::class,
    \Invo\Providers\SessionBagProvider::class,
    \Invo\Providers\UrlProvider::class,
    \Invo\Providers\ViewProvider::class,
    \Invo\Providers\VoltProvider::class,
];

<?php

declare(strict_types=1);

namespace Invo\Providers;

use Phalcon\Di\DiInterface;
use Phalcon\Di\ServiceProviderInterface;

class ConfigProvider implements ServiceProviderInterface
{
    public function register(DiInterface $di): void
    {
        $configPath = $di->offsetGet('rootPath') . '/config/config.php';
        if (!file_exists($configPath) || !is_readable($configPath)) {
            throw new Exception('Config file does not exist: ' . $configPath);
        }

        $di->setShared('config', function () use ($configPath) {
            return require $configPath;
        });
    }
}

<?php

declare(strict_types=1);

use Phalcon\Config\Config;

return new Config([
    'database' => [
        'adapter'  => $_ENV['DB_ADAPTER'] ?? 'Mysql',
        'host'     => $_ENV['DB_HOST'] ?? 'localhost',
        'username' => $_ENV['DB_USERNAME'] ?? 'root',
        'password' => $_ENV['DB_PASSWORD'] ?? 'secret',
        'dbname'   => $_ENV['DB_NAME'] ?? 'invo',
        'charset'  => $_ENV['DB_CHARSET'] ?? 'utf8',
        'options'  => [
            PDO::ATTR_EMULATE_PREPARES => true,
        ],
    ],
    'application' => [
        'viewsDir' => $_ENV['VIEWS_DIR'] ?? 'themes/invo',
        'baseUri'  => $_ENV['BASE_URI'] ?? '/',
    ],
]);

<?php

declare(strict_types=1);

namespace Invo\Providers;

use Phalcon\Di\DiInterface;
use Phalcon\Di\ServiceProviderInterface;
use Phalcon\Session\Adapter\Stream as SessionAdapter;
use Phalcon\Session\Manager as SessionManager;

class SessionProvider implements ServiceProviderInterface
{
    public function register(DiInterface $di): void
    {
        $di->setShared('session', function () {
            $session = new SessionManager();
            $files   = new SessionAdapter([
                'savePath' => sys_get_temp_dir(),
            ]);
            $session->setAdapter($files);
            $session->start();

            return $session;
        });
    }
}

<?php

declare(strict_types=1);

namespace Invo\Providers;

use Phalcon\Di\DiInterface;
use Phalcon\Di\ServiceProviderInterface;

class DatabaseProvider implements ServiceProviderInterface
{
    public function register(DiInterface $di): void
    {
        $dbConfig = $di->getShared('config')
                       ->get('database')
                       ->toArray()
        ;
        $di->setShared('db', function () use ($dbConfig) {
            $dbClass = 'Phalcon\Db\Adapter\Pdo\\' . $dbConfig['adapter'];
            unset($dbConfig['adapter']);

            return new $dbClass($dbConfig);
        });
    }
}

<?php

declare(strict_types=1);

namespace Invo\Forms;

use Phalcon\Filter\Validation\Validator\PresenceOf;
use Phalcon\Forms\Element\Password;
use Phalcon\Forms\Element\Text;
use Phalcon\Forms\Form;

class LoginForm extends Form
{
    public function initialize()
    {
        $email = new Text('email');
        $email->setLabel('Username/Email');
        $email->setFilters(['striptags', 'string']);
        $email->addValidators([
            new PresenceOf(['message' => 'Username/Email is required']),
        ]);

        $this->add($email);

        $password = new Password('password');
        $password->setLabel('Password');
        $password->addValidators([
            new PresenceOf(['message' => 'Password is required']),
        ]);

        $this->add($password);
    }
}

<?php

public function indexAction(): void
{
    $form = new LoginForm();

    // Set default Invo user credentials
    $form->get('email')->setDefault('demo');
    $form->get('password')->setDefault('phalcon');

    $this->view->form = $form;
}

<?php

declare(strict_types=1);

namespace Invo\Controllers;

use Invo\Constants\Status;
use Invo\Models\Users;

class SessionController extends ControllerBase
{
    // ...

    public function startAction(): void
    {
        if ($this->request->isPost()) {
            $email    = $this->request->getPost('email');
            $password = $this->request->getPost('password');

            /** @var Users $user */
            $user = Users::findFirst(
                [
                    'conditions' => '(email = :email: OR username = :email:) '
                        . 'AND active = :active:',
                    'bind'       => [
                        'email'  => $email,
                        'active' => Status::ACTIVE,
                    ],
                ]
            );

            if ($user && $this->security->checkHash($password, $user->password)) {
                $this->registerSession($user);
                $this->flash->success('Welcome ' . $user->name);

                $this->dispatcher->forward([
                    'controller' => 'invoices',
                    'action'     => 'index',
                ]);

                return;
            }

            $this->flash->error('Wrong email/password');
        }

        $this->dispatcher->forward([
            'controller' => 'session',
            'action'     => 'index',
        ]);
    }

    private function registerSession(Users $user): void
    {
        $this->session->set('auth', [
            'id'   => $user->id,
            'name' => $user->name,
        ]);
    }
}

<?php

if ($this->request->isPost()) {
    // ...
}

<?php

$email    = $this->request->getPost('email');
$password = $this->request->getPost('password');

<?php

$user = Users::findFirst(
    [
        'conditions' => '(email = :email: OR username = :email:) '
            . 'AND active = :active:',
        'bind'       => [
            'email'  => $email,
            'active' => Status::ACTIVE,
        ],
    ]
);

<?php

if ($user && $this->security->checkHash($password, $user->password)) {
    // ...
}

<?php

if ($user && $this->security->checkHash($password, $user->password)) {
    $this->registerSession($user);
    $this->flash->success('Welcome ' . $user->name);

    $this->dispatcher->forward([
        'controller' => 'invoices',
        'action'     => 'index',
    ]);

    return;
}

<?php

declare(strict_types=1);

namespace Invo\Providers;

use Invo\Plugins\NotFoundPlugin;
use Invo\Plugins\SecurityPlugin;
use Phalcon\Di\DiInterface;
use Phalcon\Di\ServiceProviderInterface;
use Phalcon\Events\Manager as EventsManager;
use Phalcon\Mvc\Dispatcher;

class DispatcherProvider implements ServiceProviderInterface
{
    public function register(DiInterface $di): void
    {
        $di->setShared('dispatcher', function () {
            $eventsManager = new EventsManager();

            /**
             * Check if the user is allowed to access certain action using the SecurityPlugin
             */
            $eventsManager->attach('dispatch:beforeExecuteRoute', new SecurityPlugin());

            /**
             * Handle exceptions and not-found exceptions using NotFoundPlugin
             */
            $eventsManager->attach('dispatch:beforeException', new NotFoundPlugin());

            $dispatcher = new Dispatcher();
            $dispatcher->setDefaultNamespace('Invo\Controllers');
            $dispatcher->setEventsManager($eventsManager);

            return $dispatcher;
        });
    }
}

<?php

$eventsManager->attach(
    'dispatch:beforeExecuteRoute',
    new SecurityPlugin()
);

<?php

$eventsManager->attach(
    'dispatch:beforeException',
    new NotFoundPlugin()
);

<?php

declare(strict_types=1);

namespace Invo\Plugins;

use Phalcon\Di\Injectable;
use Phalcon\Events\Event;
use Phalcon\Mvc\Dispatcher;

class SecurityPlugin extends Injectable
{
    // ...

    public function beforeExecuteRoute(Event $event, Dispatcher $dispatcher)
    {
        // ...
    }
}

<?php

declare(strict_types=1);

namespace Invo\Plugins;

use Phalcon\Di\Injectable;
use Phalcon\Events\Event;
use Phalcon\Mvc\Dispatcher;

class SecurityPlugin extends Injectable
{
    public function beforeExecuteRoute(Event $event, Dispatcher $dispatcher)
    {
        $auth = $this->session->get('auth');
        if (!$auth) {
            $role = 'Guests';
        } else {
            $role = 'Users';
        }

        $controller = $dispatcher->getControllerName();
        $action     = $dispatcher->getActionName();

        $acl = $this->getAcl();

        if (!$acl->isComponent($controller)) {
            $dispatcher->forward([
                'controller' => 'errors',
                'action'     => 'show404',
            ]);

            return false;
        }

        $allowed = $acl->isAllowed($role, $controller, $action);
        if (!$allowed) {
            $dispatcher->forward([
                'controller' => 'errors',
                'action'     => 'show401',
            ]);

            $this->session->destroy();

            return false;
        }

        return true;
    }
}

<?php

use Phalcon\Acl\Adapter\Memory as AclList;
use Phalcon\Acl\Enum;
use Phalcon\Acl\Role;

$acl = new AclList();
$acl->setDefaultAction(Enum::DENY);

$roles = [
    'users'  => new Role(
        'Users',
        'Member privileges, granted after sign in.'
    ),
    'guests' => new Role(
        'Guests',
        'Anyone browsing the site who is not signed in is considered to be a "Guest".'
    ),
];

foreach ($roles as $role) {
    $acl->addRole($role);
}

<?php

use Phalcon\Acl\Component;

// ...

$privateResources = [
    'companies'    => ['index', 'search', 'new', 'edit', 'save', 'create', 'delete'],
    'products'     => ['index', 'search', 'new', 'edit', 'save', 'create', 'delete'],
    'producttypes' => ['index', 'search', 'new', 'edit', 'save', 'create', 'delete'],
    'invoices'     => ['index', 'profile'],
];
foreach ($privateResources as $resource => $actions) {
    $acl->addComponent(new Component($resource), $actions);
}

$publicResources = [
    'index'    => ['index'],
    'about'    => ['index'],
    'register' => ['index'],
    'errors'   => ['show401', 'show404', 'show500'],
    'session'  => ['index', 'register', 'start', 'end'],
    'contact'  => ['index', 'send'],
];
foreach ($publicResources as $resource => $actions) {
    $acl->addComponent(new Component($resource), $actions);
}

<?php

// Grant access to public areas to both users and guests
foreach ($roles as $role) {
    foreach ($publicResources as $resource => $actions) {
        foreach ($actions as $action) {
            $acl->allow($role->getName(), $resource, $action);
        }
    }
}

// Grant access to private area to role Users
foreach ($privateResources as $resource => $actions) {
    foreach ($actions as $action) {
        $acl->allow('Users', $resource, $action);
    }
}

invo/
    src/
        Controllers/
            ProductsController.php
        Forms/
            ProductsForm.php
        Models/
            Products.php
    themes/
        invo/
            products/
                edit.volt
                index.volt
                new.volt
                search.volt

<?php

class ProductsController extends ControllerBase
{
    public function createAction(): void;

    public function deleteAction($id): void;

    public function editAction($id): void;

    public function indexAction(): void;

    public function newAction(): void;

    public function saveAction(): void;

    public function searchAction(): void;
}

<?php

public function indexAction(): void
{
    $this->persistent->searchParams = null;

    $this->view->form = new ProductsForm();
}

<?php

declare(strict_types=1);

namespace Invo\Forms;

use Invo\Models\ProductTypes;
use Phalcon\Filter\Validation\Validator\Numericality;
use Phalcon\Filter\Validation\Validator\PresenceOf;
use Phalcon\Forms\Element\Select;
use Phalcon\Forms\Element\Text;
use Phalcon\Forms\Form;

class ProductsForm extends Form
{
    use IdAndNameFieldsTrait;

    public function initialize($entity = null, array $options = [])
    {
        $this->addIdAndNameFields($options);

        /**
         * Product Type Id Select
         */
        $type = new Select(
            'product_types_id',
            ProductTypes::find(),
            [
                'using'      => ['id', 'name'],
                'useEmpty'   => true,
                'emptyText'  => '...',
                'emptyValue' => '',
            ]
        );
        $type->setLabel('Type');

        $this->add($type);

        /**
         * Price text field
         */
        $price = new Text('price');
        $price->setLabel('Price');
        $price->setFilters(['float']);
        $price->addValidators([
            new PresenceOf(['message' => 'Price is required']),
            new Numericality(['message' => 'Price is required']),
        ]);

        $this->add($price);
    }
}

<?php

use Phalcon\Filter\Validation\Validator\PresenceOf;
use Phalcon\Forms\Element\Text;

$name = new Text('name');
$name->setLabel('Name');
$name->setFilters(
    [
        'striptags',
        'string',
    ]
);
$name->addValidators(
    [
        new PresenceOf(
            [
                'message' => 'Name is required',
            ]
        ),
    ]
);

$this->add($name);

<?php

use Invo\Models\ProductTypes;
use Phalcon\Forms\Element\Select;

$type = new Select(
    'product_types_id',
    ProductTypes::find(),
    [
        'using'      => ['id', 'name'],
        'useEmpty'   => true,
        'emptyText'  => '...',
        'emptyValue' => '',
    ]
);

<div class="row mb-3">
    <div class="col-xs-12 col-md-6">
        <h2>Search products</h2>
    </div>
    <div class="col-xs-12 col-md-6 text-right">
        {{ link_to("products/new", "Create Product", "class": "btn btn-primary") }}
    </div>
</div>

<form action="/products/search" role="form" method="get">
    {% for element in form %}
        {% if is_a(element, 'Phalcon\Forms\Element\Hidden') %}
            {{ element }}
        {% else %}
            <div class="form-group">
                {{ element.label() }}
                <div class="controls">
                    {{ element.setAttribute("class", "form-control") }}
                </div>
            </div>
        {% endif %}
    {% endfor %}

    {{ submit_button("Search", "class": "btn btn-primary") }}
</form>

<?php

public function searchAction(): void
{
    if ($this->request->isPost()) {
        // POST
    } else {
        // GET
    }

    // ...
}

<?php

$query = Criteria::fromInput(
    $this->di,
    'Products',
    $this->request->getPost()
);

<?php

$this->persistent->searchParams = $query->getParams();

<?php

$products = Products::find($parameters);

if (count($products) === 0) {
    $this->flash->notice('The search did not find any products');

    $this->dispatcher->forward([
        'controller' => 'products',
        'action'     => 'index',
    ]);
}

<?php

use Phalcon\Paginator\Adapter\Model as Paginator;

// ...

$paginator = new Paginator(
    [
        'data'  => $products,
        'limit' => 5,
        'page'  => $numberPage,
    ]
);

$page = $paginator->paginate();

<?php

$this->view->page = $page;

{% for product in page.items %}
    <tr>
        <td>{{ product.id }}</td>
        <td>{{ product.getProductTypes().name }}</td>
        <td>{{ product.name }}</td>
        <td>${{ "%.2f"|format(product.price) }}</td>
        <td>{{ product.getActiveDetail() }}</td>
        <td width="7%">
            {{ link_to("products/edit/" ~ product.id, "Edit", "class": "btn btn-default") }}
        </td>
        <td width="7%">
            {{ link_to("products/delete/" ~ product.id, "Delete", "class": "btn btn-default") }}
        </td>
    </tr>
{% else %}
    No products are recorded
{% endfor %}

{% for product in page.items %}
    {% if loop.first %}
        // Executed before the first product in the loop
    {% endif %}

    // Executed for every product on `page.items`

    {% if loop.last %}
        // Executed after the last product in the loop
    {% endif %}
{% else %}
    // Executed if `page.items` does not have any products
{% endfor %}

<?php

declare(strict_types=1);

namespace Invo\Models;

use Invo\Constants\Status;
use Phalcon\Mvc\Model;

class Products extends Model
{
    // ...

    public function getActiveDetail(): string
    {
        return $this->active == Status::ACTIVE ? 'Yes' : 'No';
    }

    public function initialize()
    {
        $this->belongsTo(
            'product_types_id',
            ProductTypes::class,
            'id',
            [
                'reusable' => true,
                'alias'    => 'productTypes',
            ]
        );
    }
}

<td>{{ product.getProductTypes().name }}</td>

<td>${{ "%.2f"|format(product.price) }}</td>

<?php echo sprintf('%.2f', $product->price) ?>

<td>{{ product.getActiveDetail() }}</td>

<?php

public function createAction(): void
{
    if (true !== $this->request->isPost()) {
        $this->dispatcher->forward([
            'controller' => 'products',
            'action'     => 'index',
        ]);
    }

    $form    = new ProductsForm();
    $product = new Products();

    $product->id               = $this->request->getPost('id', 'int');
    $product->product_types_id = $this->request->getPost('product_types_id', 'int');
    $product->name             = $this->request->getPost('name', 'striptags');
    $product->price            = $this->request->getPost('price', 'double');
    $product->active           = $this->request->getPost('active');

    // ...
}

<?php

$form = new ProductsForm();
$product = new Products();

$data = $this->request->getPost();

if (true !== $form->isValid($data, $product)) {
    $messages = $form->getMessages();

    foreach ($messages as $message) {
        $this->flash->error($message->getMessage());
    }

    $this->dispatcher->forward([
        'controller' => 'products',
        'action'     => 'new',
    ]);
}

<?php

if ($product->save() === false) {
    $messages = $product->getMessages();

    foreach ($messages as $message) {
        $this->flash->error($message->getMessage());
    }

    $this->dispatcher->forward([
        'controller' => 'products',
        'action'     => 'new',
    ]);
}

$form->clear();

$this->flash->success('Product was created successfully');

$this->dispatcher->forward([
    'controller' => 'products',
    'action'     => 'index',
]);

<?php

public function editAction($id): void
{
    if (true !== $this->request->isPost()) {
        $product = Products::findFirstById($id);

        if (null === $product) {
            $this->flash->error('Product was not found');

            $this->dispatcher->forward([
                'controller' => 'products',
                'action'     => 'index',
            ]);
        }

        $this->view->form = new ProductsForm(
            $product,
            [
                'edit' => true,
            ]
        );
    }
}

<?php

class ProductsController extends ControllerBase
{
    public function initialize()
    {
        parent::initialize();

        $this->tag->title()
                  ->set('Manage your products')
        ;
    }

    // ...
}

<?php

declare(strict_types=1);

namespace Invo\Controllers;

use Phalcon\Mvc\Controller;

class ControllerBase extends Controller
{
    protected function initialize()
    {
        $this->tag->title()
                  ->prepend('INVO | ')
        ;
        $this->view->setTemplateAfter('main');
    }

    // ...
}

<head>
    <meta charset="utf-8">
    {{ title('') }}
    <!-- ... -->
</head>