Prestashop Module Configuration

1. About
2. Installation
3. Usage

About

This small library provides a simple and declarative way to generate a Prestashop module configuration page.

A module configuration page is commonly generated by using the Prestashop Helper Form. Prestashop Documentation itself advices to use it. But Prestashop also provides an Helper Options, "used to generate a configuration form, the values of which are stored in the configuration table", which is actually a much convenient tool to use when the only need is to get/set options stored in ps_configuration, as it will automatically validate and store options values in database, and will display with convenient error/success messages.

Warning: this module relies on a pending PR.

Installation

This library should be installed with Composer.

cd to your Prestashop root directory and composer init your project.

Edit your composer.json file:

"repositories": [
  {
    "type": "git",
    "url": "https://github.com/creativewave/ps-module-configuration"
  }
],
"require": {
  "creativewave/ps-module-configuration": "^1"
}

Include the autoloader generated by Composer at the top of <MyModuleMainClass>:

require_once _PS_ROOT_DIR_.'/vendor/autoload.php';

class MyModule extends Module
{
    //...
}

Register an instance of CW\Module\Configuration by giving it an instance of <MyModule>.

public function __construct()
{
    parent::__construct();
    // ...

    $this->configuration = new CW\Module\Configuration($this);
}

Register and add this hook:

/**
 * @see \CW\Module\Configuration::hookActionAdminModulesOptionsModifier()
 */
public function hookActionAdminModulesOptionsModifier(array $params)
{
    $this->configuration->hookActionAdminModulesOptionsModifier($params);
}

Finally, display configuration form with:

/**
 * Get content of module admin configuration page.
 */
public function getContent(): string
{
    return $this->configuration->getContent();
}

Usage

Describing module options

All module options should be declared in <MyModule>::OPTIONS.

    const OPTIONS = [
        'OPTION_1'[
            'type'       => 'bool',
            'title'      => 'My module option 1', /* ->l('My module option 1') */
            'validation' => 'isBool',
            'cast'       => 'intval',
        ],
        // other options
    ];

See the Prestashop Doc for other option types and parameters.

Important: in order to get your title/description/choices translated, you should use the same comment format as above. This may be improved in a future version.

Important: all options will be automatically saved in database by using a name prefixed with the module name (eg.: MYMODULENAME_OPTION_1). But you should not be concerned about that (see next section about fetching an option value).

Fetching a module option value

Module option(s) value(s) may be fetched by using either CW\Module\Configuration::getOptionValue() or \CW\Module\Configuration::getOptionsValues().

Following the previous exemple:

    $this->configuration->getOptionValue('OPTION_1');

Set default options values

Module default option(s) value(s) may be set (eg. when installing the module) by passing as arguments to CW\Module\Configuration::setOptionsDefaultValues().

Following the previous exemple:

    $this->configuration->setOptionsDefaultValues(array_keys(static::OPTIONS));

It will automatically detect which options have a default value.

Optional: set an option list/choices at run time

Select or radio options fields may need to have their authorized values defined from data stored in database, like products or categories ids.

But it's not possible to call a function at parse time (as in a PHP constant), so <MyModule> may implement one of the following callbacks to set them at run time, which should return an array describing the option list or choices:

    public function getOptionList(string $option): array
    {
        switch ($option) {
            case 'OPTION_1':
                return [
                  ['id' => 'value_1', 'name' => 'Option value 1'],
                  ['id' => 'value_2', 'name' => 'Option value 2'],
                  ['id' => 'value_3', 'name' => 'Option value 3'],
                ];
            case 'OPTION_2':
                // ...
        }
    }

    public function getOptionChoices(string $option): array
    {
        switch ($option) {
            case 'OPTION_3':
                return ['Option value 1', 'Option value 2', 'Option value 3'];
            case 'OPTION_4':
                // ...
        }
    }

They will be automatically called if the corresponding $option name (eg. OPTION_1) defines a 'list' or choices parameter with a falsy value (null, [], false, etc...).

Todo

• Improvement: options fields translations
• Improvement: determine if for performances reasons, it's better to use this library as a module, hooking itself to actionAdminModulesOptionsModifier alone, instead of registering it and using one Configuration instance for each module. Other modules would somehow declare themselves as using this module. It would also allow to remove 50% of the boilerplate
• Unit tests
• Integrating PHPCS