arkonsoft / ps-module-core
Core utilities for PrestaShop module
Requires
- php: >= 7.0
README
Introduction
Creating modules for Presta is a real horror story. This package contains basic tools to make development a little less masochistic.
Table of Contents
Requirements
- PHP >= 7.0
Installation
Install package with composer:
composer require arkonsoft/ps-module-core
Basic usage
AbstractModule
Inherit the AbstractModule class from your module class. Now you have access to the $this->canBeUpgraded() method, which can be used to display a warning about module updates or anything else.
You can also use the ModuleCategory dictionary to set $this->tab, which contains the module category (it has meaning on the module list page).
<?php if (!defined('_PS_VERSION_')) { exit; } use Arkonsoft\PsModule\Core\Module\AbstractModule; class MyModule extends AbstractModule { public function __construct() { $this->name = 'mymodule'; // ps-module-core $this->tab = ModuleCategory::FRONT_OFFICE_FEATURES; $this->version = '1.0.0'; $this->author = 'Firstname Lastname'; $this->need_instance = 0; $this->ps_versions_compliancy = [ 'min' => '1.7.0.0', 'max' => '8.99.99', ]; $this->bootstrap = true; parent::__construct(); $this->displayName = $this->trans('My module', [], 'Modules.Mymodule.Admin'); $this->description = $this->trans('Description of my module.', [], 'Modules.Mymodule.Admin'); $this->confirmUninstall = $this->trans('Are you sure you want to uninstall?', [], 'Modules.Mymodule.Admin'); // ps-module-core if ($this->canBeUpgraded()) { $this->warning = $this->trans('The module %s needs to be updated. Use the "update" option in the list of modules. The module without an update may not work properly.', [ $this->name ], 'Modules.Mymodule.Admin'); } } }
AbstractAdminSettingsController
Inherit from the AbstractAdminSettingsController class on your module AdminController class. Now all you need to do is define the fields of the settings form in HelperForm format and you're done!
Data writing and reading operations happen in the abstract class so you can focus only on defining the fields.
<?php use Arkonsoft\PsModule\Core\Controller\AbstractAdminSettingsController; if (!defined('_PS_VERSION_')) { exit; } class AdminMyModuleSettingsController extends AbstractAdminSettingsController { public function prepareOptions(): void { $form = [ 'form' => [ 'tabs' => [ 'general' => $this->module->getTranslator()->trans('General', [], 'Modules.MyModule.Admin'), 'other1' => $this->module->getTranslator()->trans('Other 1', [], 'Modules.MyModule.Admin'), 'other2' => $this->module->getTranslator()->trans('Other 2', [], 'Modules.MyModule.Admin'), ], 'legend' => [ 'title' => $this->module->getTranslator()->trans('Settings', [], 'Modules.MyModule.Admin'), 'icon' => 'icon-cogs' ], 'submit' => [ 'title' => $this->module->getTranslator()->trans('Save', [], 'Modules.MyModule.Admin'), 'class' => 'btn btn-default pull-right' ], ], ]; $form['form']['input'][] = [ 'label' => $this->module->getTranslator()->trans('Example field 1', [], 'Modules.MyModule.Admin'), 'type' => 'text', 'name' => $this->module->name . 'example_field_1', 'lang' => true, 'tab' => 'general' ]; $form['form']['input'][] = [ 'label' => $this->module->getTranslator()->trans('Example field 2', [], 'Modules.MyModule.Admin'), 'type' => 'text', 'name' => $this->module->name . 'example_field_2', 'lang' => true, 'tab' => 'general' ]; $this->forms[] = $form; } }
AbstractAdminObjectModelController Class
The AbstractAdminObjectModelController class extends the PrestaShop ModuleAdminController class and provides a streamlined way to create admin controllers for ObjectModel-based entities.
Abstract Methods
/** * Returns the fully qualified class name of the ObjectModel * * @return string */ abstract public function getObjectModelClassName(): string; /** * Determines if a shop context is required for this controller * * @return bool */ abstract public function isShopContextRequired(): bool; /** * Defines the columns to display in the list view * * @return array */ abstract public function getListColumns(): array; /** * Defines the form fields for creating/editing objects * * @return array */ abstract public function getFormFields(): array;
Example Usage
<?php use Arkonsoft\PsModule\Core\Controller\AbstractAdminObjectModelController; if (!defined('_PS_VERSION_')) { exit; } class AdminMyModuleItemsController extends AbstractAdminObjectModelController { public function getObjectModelClassName(): string { return MyModuleItem::class; } public function isShopContextRequired(): bool { return true; } public function getListColumns(): array { return [ 'id_my_module_item' => [ 'title' => $this->module->getTranslator()->trans('ID', [], 'Modules.MyModule.Admin'), 'width' => 'auto', 'type' => 'text', ], 'name' => [ 'title' => $this->module->getTranslator()->trans('Name', [], 'Modules.MyModule.Admin'), 'width' => 'auto', 'type' => 'text', ], 'position' => [ 'title' => $this->module->getTranslator()->trans('Position', [], 'Modules.MyModule.Admin'), 'width' => 'auto', 'position' => 'position', 'align' => 'center', ], ]; } public function getFormFields(): array { return [ 'legend' => [ 'title' => $this->module->getTranslator()->trans('Item', [], 'Modules.MyModule.Admin'), ], 'input' => [ [ 'type' => 'text', 'label' => $this->module->getTranslator()->trans('Name', [], 'Modules.MyModule.Admin'), 'name' => 'name', 'required' => true, 'lang' => true, ], [ 'type' => 'switch', 'label' => $this->module->getTranslator()->trans('Active', [], 'Modules.MyModule.Admin'), 'name' => 'active', 'required' => false, 'is_bool' => true, 'values' => [ [ 'id' => 'active_on', 'value' => 1, 'label' => $this->module->getTranslator()->trans('Yes', [], 'Modules.MyModule.Admin'), ], [ 'id' => 'active_off', 'value' => 0, 'label' => $this->module->getTranslator()->trans('No', [], 'Modules.MyModule.Admin'), ], ], ], ], 'submit' => [ 'title' => $this->module->getTranslator()->trans('Save', [], 'Modules.MyModule.Admin'), ], ]; } }
The AbstractAdminObjectModelController provides the following features:
- Automatic handling of position management with drag-and-drop functionality
- Built-in image management support through
ObjectModelImageManager - Automatic multishop support with proper JOIN handling
- Automatic multilang support detection and handling
- Built-in image preview and deletion functionality
Image Management
The controller includes built-in support for image management through the ObjectModelImageManager. You can use the following methods in your form fields:
protected function getImagePreviewHtml(string $type, string $extension, string $widthInPx = '200px'): string
This method generates HTML for image preview in your forms. Example usage in form fields:
[
'type' => 'file',
'label' => $this->module->getTranslator()->trans('Image', [], 'Modules.MyModule.Admin'),
'name' => 'image',
'display_image' => true,
'image' => $this->getImagePreviewHtml('default', 'jpg'),
'delete_url' => $this->getDeleteImageUrl('default'),
]
To handle image saving in your controller, you can use the processImagesSave method. Here's an example of how to implement it:
private function processImagesSave(): void { if (!\Tools::isSubmit('submitAdd' . $this->table)) { return; } $object = $this->loadObject(); if (!$object) { return; } $id = (int) $object->id; // Save desktop image with jpg and webp formats $this->objectModelImageManager->saveImage('image', $id, 'default', ['jpg', 'webp']); }
This method should be called in your controller's postProcess method to handle image uploads when the form is submitted. The saveImage method takes the following parameters:
- Field name from the form
- Object ID
- Image type identifier
- Array of allowed file extensions
To integrate image saving in your controller, override the postProcess method like this:
public function postProcess() { parent::postProcess(); $this->processImagesSave(); }
Multishop Support
The controller automatically handles multishop functionality. It will:
- Detect if multishop is active
- Add appropriate JOIN clauses for shop context
- Handle shop-specific data properly
Multilang Support
The controller automatically detects if your ObjectModel supports multiple languages by checking the model's definition. This is used to:
- Set proper language flags in forms
- Handle multilang fields correctly
- Manage translations appropriately
Position Management
The controller provides built-in support for position management with:
- Drag-and-drop reordering
- Automatic position updates
- Position field in list view
- AJAX-based position updates
Example of position field in list columns:
'position' => [ 'title' => $this->module->getTranslator()->trans('Position', [], 'Modules.MyModule.Admin'), 'width' => 'auto', 'position' => 'position', 'align' => 'center', ]
Definitions
AbstractModule Class
The AbstractModule class extends the PrestaShop Module class and provides common functionalities for PrestaShop modules.
getDatabaseVersion Method
/** * Returns the database version of the module * * @return ?string */ protected function getDatabaseVersion()
This method retrieves the database version of the module from the PrestaShop database.
canBeUpgraded Method
/** * Checks if the database version is lower than the specified version for potential upgrade. * * @return bool */ protected function canBeUpgraded(): bool
This method checks if the database version of the module is lower than the specified version, indicating a potential need for upgrade.
Example usage:
public function __construct() { // other code if ($this->canBeUpgraded()) { $this->warning = $this->trans('The module %s needs to be updated. Use the "update" option in the list of modules. The module without an update may not work properly.', [ $this->name ], 'Modules.Mymodule.Admin'); } }
ModuleCategory Interface
The ModuleCategory interface defines constants representing different categories of PrestaShop modules.
Constants
ADMINISTRATION: Modules related to administration.ADVERTISING_MARKETING: Modules related to advertising and marketing.ANALYTICS_STATS: Modules for analytics and statistics.BILLING_INVOICING: Modules for billing and invoicing.CHECKOUT: Modules related to the checkout process.CONTENT_MANAGEMENT: Modules for content management.DASHBOARD: Modules for dashboard functionalities.EMAILING: Modules related to emailing.EXPORT: Modules for exporting data.FRONT_OFFICE_FEATURES: Modules providing features for the front office.I18N_LOCALIZATION: Modules for internationalization and localization.MARKET_PLACE: Modules related to marketplaces.MERCHANDIZING: Modules for merchandizing.MIGRATION_TOOLS: Modules for migration tools.MOBILE: Modules optimized for mobile devices.OTHERS: Other miscellaneous modules.PAYMENTS_GATEWAYS: Modules for payments and gateways.PAYMENT_SECURITY: Modules for payment security.PRICING_PROMOTION: Modules for pricing and promotions.QUICK_BULK_UPDATE: Modules for quick bulk updates.SEARCH_FILTER: Modules for search and filtering.SEO: Modules for search engine optimization.SHIPPING_LOGISTICS: Modules for shipping and logistics.SLIDESHOWS: Modules for creating slideshows.SMART_SHOPPING: Modules for smart shopping.SOCIAL_NETWORKS: Modules integrating with social networks.
Example usage:
public function __construct() { // other code $this->tab = ModuleCategory::FRONT_OFFICE_FEATURES; }
TabDictionary Interface
The TabDictionary interface contains constants that represent various tabs in the PrestaShop admin panel. Each constant is a string that corresponds to an admin section.
Constants
Example Constants
ACCESS: Represents the "AdminAccess" tab.ADDONS_CATALOG: Represents the "AdminAddonsCatalog" tab.ADDRESSES: Represents the "AdminAddresses" tab.ADVANCED_PARAMETERS: Represents the "AdminAdvancedParameters" tab.ATTACHMENTS: Represents the "AdminAttachments" tab.ATTRIBUTES_GROUPS: Represents the "AdminAttributesGroups" tab.BACKUP: Represents the "AdminBackup" tab.CARRIERS: Represents the "AdminCarriers" tab.CART_RULES: Represents the "AdminCartRules" tab.CARTS: Represents the "AdminCarts" tab.CATALOG: Represents the "AdminCatalog" tab.CATEGORIES: Represents the "AdminCategories" tab.
Example usage:
public function installTab(): bool { if (Tab::getIdFromClassName($this->settingsAdminController)) { return true; } $tab = new Tab(); $parentTabClassName = TabDictionary::CATALOG; // other code }
AbstractAdminSettingsController Class
The AbstractAdminSettingsController class extends the PrestaShop ModuleAdminController class and provides functionalities for managing module settings in the admin panel better than native OptionsAPI.
Constructor
public function __construct()
The constructor method initializes the AbstractAdminSettingsController class by setting up the context, bootstrapping, and calling the prepareOptions method.
prepareOptions Method
abstract public function prepareOptions();
This abstract method is used to prepare options for the settings controller. Subclasses must implement this method.
initContent Method
public function initContent()
This method initializes the content of the settings controller by rendering the form.
postProcess Method
public function postProcess()
This method handles post-processing tasks after form submission, such as saving form data.
dispatchAction Method
public function dispatchAction()
This method dispatches actions based on form submissions.
renderForm Method
public function renderForm()
This method renders the form using the HelperForm class.
loadFormValues Method
public function loadFormValues(HelperForm $helper)
This method loads form values from the database.
saveForm Method
public function saveForm()
This method saves form data to the database.
Other Helper Methods
loadField: Loads a field value from the database.loadCategoryField: Loads values for a category field from the database.saveField: Saves a field value to the database.saveLangField: Saves a multilingual field value to the database.saveCategoryField: Saves values for a category field to the database.isHTMLAllowed: Checks if HTML is allowed for a field type.isNestedArray: Checks if an array is nested.