README

Extension of the standard Nette/Application by some other features that are specific for use in the Interitty projects.

Requirements

• PHP >= 8.5

Installation

The best way to install interitty/application is using Composer:

composer require interitty/application

Features

Instead of using standard Nette\Application\* and Nette\Bootstrap\* classes, there are new Interitty\Application\* and Interitty\Bootstrap\* classes that provide some other features.

Parameters

In addition to the default parameters that come from Nette\Appliacation, the following parameters are available that can be used to make the application easier to configure.

parameters:
    applicationNamespace: 'App' # Can be used in code generators
    controlsDir: %appDir%/Controls # Can be used in code generators

Component Factory Locator

The Interitty\Application\Presenter is extended with the Component Factory Locator functionality, thanks to which it is possible to conveniently create and access all registered components without writing unnecessary code.

For more convenient use, an auxiliary helper trait is automatically generated when creating a DI container, which contains explicitly defined methods for each registered component that make IDE auto-complete and static code analysis work better.

Since this helper trait is directly related to a specific application, its namespace, and its autoloader, it is necessary to set its generation in the application config.neon file and add its use to BasePresenter. For production use and better code clarity, it is advisable to add generated helper as part of the project to the versioning system.

parameters:
    applicationNamespace: 'App' # Can be used in code generators

<?php

declare(strict_types=1);

namespace App\Presenters;

use Interitty\Application\UI\Presenter;
use Interitty\ComponentModel\ComponentLocatorHelperTrait;

abstract class BasePresenter extends Presenter
{
    use ComponentLocatorHelperTrait;
}

Template global parameters

Sometimes it can be useful to be able to set a variable in the template directly from the neon config. There is a TemplateGlobalParametersExtension for this purpose.

templateParameters:
    author: "Interitty <info@interitty.org>"
    description: "Description of the example application"
    keywords: ["application", "interitty"]
    name: "Example application"

Environment-controlled configuration

Some properties of applications are governed by the environment in which they run. The production behaviour may differ from the development behaviour and for this purpose Configurator is extended to set the type of environment by which it can automatically distinguish the debug mode.

// bootstrap.php
<?php

declare(strict_types=1);

use Interitty\Bootstrap\Configurator;
use Interitty\Utils\Strings;

require __DIR__ . '/../vendor/autoload.php';
$environment = Strings::lower(Configurator::getEnv('ENVIRONMENT', Configurator::ENVIRONMENT_LOCAL));

$configurator = new Configurator();
$configurator->setEnvironment($environment);
$configurator->setDebugMode($configurator::DEBUG_MODE_BY_ENVIRONMENT);
$configurator->enableEnvironmentParameters();
$configurator->enableTracy(__DIR__ . '/../logs');
$configurator->setTimeZone(Configurator::getEnv('TZ', 'Etc/UTC'));
$configurator->setTempDirectory(__DIR__ . '/../temp');
$configurator->setWwwDirectory(__DIR__ . '/../www');

$configurator->addConfig(__DIR__ . '/Config/config.neon');
if (PHP_SAPI === 'cli') {
    $configurator->addConfig(__DIR__ . '/Config/console.neon');
}
if (file_exists(__DIR__ . '/Config/local.neon') === true) {
    $configurator->addConfig(__DIR__ . '/Config/local.neon');
}

$container = $configurator->createContainer();
return $container;

Even building a dependency injection container can be object-oriented. The following is an example of such a typical application bootstrap:

// Bootstrap.php
<?php

declare(strict_types=1);

namespace Vendor\Application;

use Interitty\Bootstrap\Configurator;
use Interitty\Utils\Strings;

use function file_exists;

use const PHP_SAPI;

class Bootstrap
{
    /**
     * Application bootstrap
     *
     * @return Configurator
     */
    public static function boot(): Configurator
    {
        $environment = Strings::lower(Configurator::getEnv('ENVIRONMENT', Configurator::ENVIRONMENT_LOCAL));

        $configurator = new Configurator();
        $configurator->setEnvironment($environment);
        $configurator->setDebugMode(Configurator::DEBUG_MODE_BY_ENVIRONMENT);
        $configurator->enableEnvironmentParameters();
        $configurator->enableTracy(__DIR__ . '/../logs');
        $configurator->setTimeZone(Configurator::getEnv('TZ', 'Etc/UTC'));
        $configurator->setTempDirectory(__DIR__ . '/../temp');
        $configurator->setWwwDirectory(__DIR__ . '/../www');

        $configurator->addConfig(__DIR__ . '/Config/config.neon');
        if (PHP_SAPI === 'cli') {
            $configurator->addConfig(__DIR__ . '/Config/console.neon');
        }
        if (file_exists(__DIR__ . '/Config/local.neon') === true) {
            $configurator->addConfig(__DIR__ . '/Config/local.neon');
        }

        return $configurator;
    }
}

This bootstrap can then be loaded using the comoser autoloader

// index.php
<?php

declare(strict_types=1);

use Nette\Application\Application;
use Vendor\Application\Bootstrap;

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

$configurator = Bootstrap::boot();
$container = $configurator->createContainer();
/** @var Application $application */
$application = $container->getByType(Application::class);
$application->run();

Ajax redirects

The Naja library brings AJAX support to the Nette Framework.

This makes it possible to replace part of an HTML document or change the current URL without having to redraw the entire page. In most cases, this can be considered the preferred behavior, so support for Ajax redirection has been added and set as default when calling the redirect method in Presenter or Component.

For the rare cases where a full redirect is really desirable, including redrawing the entire page, for example, after a user logs in or logs out, the redirect method is extended with an optional force parameter.

$this->redirect('this', force: true);

Extended base control

All Interitty graphic components work with Translator from the ground up. They work in a uniform way with a template, where the source file is searched for in the default location relative to the component class definition file and with the default name.

• /[control-name].latte
• /[ControlClassName].latte
• /default.latte
• /template/[control-name].latte
• /template/[ControlClassName].latte
• /template/default.latte

At the same time, however, it may be useful to have the ability to overload the default template in a particular application.

services:
    ControlFactory:
        implement: Vendor\Namespace\Controls\Control\ControlFactoryInterface
        setup:
            - setTemplateFile(%appDir%/Controls/Control/ControlCustom.latte)

Extended base form

All Interitty forms work with Translator from the ground up. The processing of the form base is extended to handle exceptions and situations of sending without a button. The processFormSetup method has been added to the form life cycle, which is used for adding form elements and their settings.

The form has a preset submit button. However, it may be useful to be able to change its wording if necessary:

    /**
     * @inheritDoc
     */
    public function processFormSetup(): void
    {
        // ... Add another form controls
        parent::processFormSetup();
        $this->getComponentButtonSubmit()->setCaption('Send');
    }

Flash message control

To make working with flash messages as easy as possible, the interitty/flash-message-control is integrated. This adds helper methods to Presenter that take care of the entire lifecycle, including ajax redraw.

Generic form error handler

Very often there is a need to take all possible errors that may occur on the form and render them as FlashMessages directly in the Presenter. For this purpose, a helper function processFormError has been added to take care of exactly this.

<?php

declare(strict_types=1);

namespace App\Presenters;

use Interitty\Application\UI\Presenter;

abstract class BasePresenter extends Presenter
{
    /**
     * ExampleForm control factory
     *
     * @param string $name [OPTIONAL]
     * @return ExampleForm
     */
    public function createComponentExampleForm(string $name = self::CONTROL_EXAMPLE_FORM): ExampleForm
    {
        $form = parent::createComponentExampleForm($name);
        $form->onError[] = fn(Form $form): void => $this->processFormError($form);
        return $form;
    }
}

Safe persistent parameters

Persistent parameters make it very easy to transfer value between requests. In principle, however, this is a potential attack vector, as the value is passed via a parameter in the URL and as such can be changed by the user. Therefore, it should be validated.

The best way to do this is to use an appropriate setter in which the necessary validation can take place. The interitty/application package extends the functionality of persistent parameters such that if an appropriate setter exists, this is used instead of setting it directly.

<?php

declare(strict_types=1);

namespace App\Presenters;

use Interitty\Application\UI\Presenter;

abstract class BasePresenter extends Presenter
{
    /** @persistent */
    public string $parameter;

    /**
     * Parameter setter
     *
     * @param string $parameter
     * @return static Provides fluent interface
     */
    protected function setParameter(string $parameter): static
    {
        // Any additional validation can be here
        $this->parameter = $parameter;
        return $this;
    }
}

SendFile helper

Very often, applications need to provide the user with a downloadable file. Therefore, an extension sendFile has been added to Presenter to standardize this operation and simplify further testing.

<?php

declare(strict_types=1);

namespace App\Presenters;

use Interitty\Application\UI\Presenter;

class FilePresenter extends Presenter
{
    /**
     * Download action handler
     *
     * @return void
     */
    public function actionDownload(): void
    {
        $assetsDir = __DIR__ . DIRECTORY_SEPARATOR . '..' . DIRECTORY_SEPARATOR . 'assets';
        $file = assetsDir . DIRECTORY_SEPARATOR . 'file.pdf';
        $fileName = 'filename.pdf';
        $contentType = ''application/pdf';
        $this->sendFile($file, $fileName, $contentType);
    }
}