Setup Wizard

The setup wizard guides administrators through package-specific setup after a package is installed or updated. Use it when a package needs required choices that cannot be safely guessed from defaults.

Register A Wizard

Register the wizard provider in package.xml:

<quiqqer>
    <package>
        <provider>
            <installationWizard src="\Vendor\Package\Installation\Wizard"/>
        </provider>
    </package>
</quiqqer>

QUIQQER reads installed package providers through the package manager and loads classes registered as installationWizard providers. The provider must implement QUI\InstallationWizard\InstallationWizardInterface.

Provider Class

A wizard provider implements QUI\InstallationWizard\InstallationWizardInterface. For package code, extend QUI\InstallationWizard\AbstractInstallationWizard.

namespace Vendor\Package\Installation;

use QUI;
use QUI\InstallationWizard\AbstractInstallationWizard;

class Wizard extends AbstractInstallationWizard
{
    public function getTitle(?QUI\Locale $Locale = null): string
    {
        return 'Package Setup';
    }

    public function getDescription(?QUI\Locale $Locale = null): string
    {
        return 'Configures required package settings.';
    }

    public function getSteps(): array
    {
        return [
            new Steps\Settings()
        ];
    }

    public function execute(array $data = []): void
    {
        // Persist validated setup data here.
    }
}

The provider exposes title, description, logo, priority, status, steps, and an execute() method. AbstractInstallationWizard supplies defaults for common behavior such as logo, status handling, output, and finish text.

Step Class

Wizard steps implement QUI\InstallationWizard\InstallationWizardStepInterface. For package code, extend QUI\InstallationWizard\AbstractInstallationWizardStep.

namespace Vendor\Package\Installation\Steps;

use QUI;
use QUI\InstallationWizard\AbstractInstallationWizardStep;

class Settings extends AbstractInstallationWizardStep
{
    public function getTitle(?QUI\Locale $Locale = null): string
    {
        return 'Settings';
    }

    public function getDescription(?QUI\Locale $Locale = null): string
    {
        return 'Select the required package settings.';
    }

    public function create(): string
    {
        return '<label>Setting <input name="setting" required></label>';
    }
}

create() returns the step markup. execute() can be implemented on the step when it needs its own server-side execution behavior.

JavaScript Step Controls

A step can return a JavaScript control through getJavaScriptControl(). The wizard loads the control and passes the current wizard instance to it.

public function __construct(array $attributes = [])
{
    parent::__construct($attributes);

    $this->setAttribute(
        'qui-class',
        'package/vendor/package/bin/Installation/Settings'
    );
}

Use a JavaScript step control when the step needs dynamic validation, Ajax checks, dependent fields, or custom navigation.

Execution

The wizard collects step form data and calls the provider's execute() method. Use write() inside execute() to append progress output while long-running setup work is running.

public function execute(array $data = []): void
{
    $this->write('Saving settings');

    // Validate and persist setup data.

    $this->write('Settings saved');
}

Practical Rules

• Use the setup wizard only for required setup decisions.
• Keep optional preferences in normal package settings.
• Validate all submitted data in PHP.
• Keep steps small and ordered by dependency.
• Make execute() repeat-safe where possible.