README

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

Requirements

PHP >= 8.3

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 = getenv('ENVIRONMENT');
$configurator = new Configurator();
$configurator->setEnvironment(Strings::lower($environment === false ? $configurator::ENVIRONMENT_LOCAL : $environment));
$configurator->setDebugMode($configurator::DEBUG_MODE_BY_ENVIRONMENT);
$configurator->enableTracy(__DIR__ . '/../logs');
$configurator->setTempDirectory(__DIR__ . '/../temp');
$configurator->addConfig(__DIR__ . '/Config/config.neon');
$container = $configurator->createContainer();
return $container;

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
{
    /** @persistent */
    public $parameter;

    /**
     * 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) => $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 $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);
    }
}

interitty / application

Maintainers

Details