README.md

Installer

Composer installer and configurator for Orisai CMF / Nette packages

Content

• Setup
• Quickstart
• Config files
  • Load config if dependency is available
  • Load config if requested
  • Loading order and priority
• Loader
  • Regenerating loader
  • Custom loader
• Schema location
• Configurator integration
• Tests

Setup

Install with Composer

In project

composer require orisai/installer

In library

composer require --dev orisai/installer

Quickstart

Create file Orisai.php in root of your project with following content to activate plugin

use Orisai\Installer\Schema\ModuleSchema;

$schema = new ModuleSchema();

return $schema;

Add config files (these which are used in Bootstrap.php)

$schema->addConfigFile(__DIR__ . '/src/wiring.neon');

Regenerate loader

composer orisai:install

Use loader with custom configurator in Bootstrap.php

namespace App;

+use OriNette\DI\AutomaticConfigurator;
-use OriNette\DI\ManualConfigurator;
use Orisai\Installer\Loader\DefaultLoader;
use function dirname;

final class Bootstrap
{

-	public static function boot(): ManualConfigurator
+	public static function boot(): AutomaticConfigurator
	{
-		$configurator = new ManualConfigurator(dirname(__DIR__));
+		$configurator = new AutomaticConfigurator(dirname(__DIR__), new DefaultLoader());
-
-		$configurator->addConfig(__DIR__ . '/wiring.neon');
		// Other options

		return $configurator;
	}

}

And now all config files from application and all Composer packages with orisai/installer support are loaded automatically.

Config files

Each module can provide its configuration files to be loaded into app via Loader

$schema->addConfigFile(__DIR__ . '/src/wiring.neon');

Load config if dependency is available

Config file is loaded only if all required packages are installed

// package required to be installed to include this config file
$objectMapperConfig = $schema->addConfigFile(__DIR__ . '/src/object-mapper.neon');
$objectMapperConfig->addRequiredPackage('orisai/object-mapper');

Load config if requested

Config files could be loaded based on a runtime switch

Preferred way is to require switch to be turned on (set to true)

$httpsConfig = $schema->addConfigFile(__DIR__ . '/src/https.neon');
$httpsConfig->addRequiredSwitch('httpsOnly');

But we may also add config only if switch is turned off (set to false)

$httpsConfig = $schema->addConfigFile(__DIR__ . '/src/https.neon');
$httpsConfig->addForbiddenSwitch('httpOnly');

Each switch must be defined by schema and have a default value

$schema->addSwitch('httpsOnly', false);

Switch can be turned on/off in runtime via loader

use OriNette\DI\AutomaticConfigurator;
use Orisai\Installer\Loader\DefaultLoader;

$loader = new DefaultLoader();
$loader->configureSwitch('httpsOnly', true);

$configurator = new AutomaticConfigurator($rootDir, $loader);

Loading order and priority

To load config files from all packages in correct order, installer orders packages by dependencies. For example if our application depends on A, A depends on B and B depends on C, then config files are loaded in order C, B, A, application – from packages with no dependencies to packages with most dependencies.

We may be rarely need to load config before or after configs loaded in normal order:

use Orisai\Installer\Schema\ConfigFilePriority;

$loadFirstConfig = $schema->addConfigFile(__DIR__ . '/src/loadFirst.neon');
$loadFirstConfig->setPriority(ConfigFilePriority::first());

$loadLastConfig = $schema->addConfigFile(__DIR__ . '/src/loadLast.neon');
$loadLastConfig->setPriority(ConfigFilePriority::last());

Loader

Loader is the class responsible for providing config files and metadata about packages using the installer.

It is automatically generated by installer and by default is implemented by Orisai\Installer\DefaultLoader.

Regenerating loader

After modifying schema, we have to regenerate loader manually

composer orisai:install

After installing, updating or removing Composer packages, loader is updated automatically

Custom loader

We may set loader to generate with different class name and location

$schema->setLoader(
	__DIR__ . '/src/Loader.php',
	\App\Loader::class,
);

Schema location

Schema of each package is located automatically. To be loaded it must be one of:

• Orisai.php
• src/Orisai.php
• app/Orisai.php

Configurator integration

Automatic configurator is a replacement for nette/bootstrap Configurator and orisai/nette-di ManualConfigurator, for compatibility with installer's loader.

API is exactly same as for ManualConfigurator, except the addConfig() method which is replaced by internal calls to Loader. Check the orisai/nette-di documentation first to learn how to use the configurator.

use OriNette\DI\AutomaticConfigurator;
use Orisai\Installer\Loader\DefaultLoader;

$configurator = new AutomaticConfigurator($rootDir, new DefaultLoader());

In DI are available additional parameters in modules key. They contain useful info about installed modules.

Installer also configures predefined switches consoleMode and debugMode accordingly to value of parameters of same name.

Tests

For testing our application we may utilize InstallerTester. It generates the same loader as is generated for application runtime and on top of that allows us to provide test-specific schema.

use OriNette\DI\AutomaticConfigurator;
use Orisai\Installer\Schema\ModuleSchema;
use Orisai\Installer\Tester\InstallerTester;

$tester = new InstallerTester();
$schema = new ModuleSchema();
$schema->addConfigFile(__DIR__ . '/testConfig.neon');

$loader = $tester->generateLoader($schema);
$configurator = new AutomaticConfigurator($rootDir, $loader);
// ...