# Technical Development Standards

my_module/
├── config.xml
├── my_module.php (main module file)
├── index.php (directory protection)
├── views/
│   ├── index.php
│   ├── templates/
│   └── js/
├── controllers/
├── override/ (if absolutely necessary)
├── docs/ (documentation)
└── .htaccess (security protection)

<?php
if (!defined('_PS_VERSION_')) {
    exit;
}

public function __construct()
{
    $this->name = 'my_module';
    $this->version = '1.0.0';
    $this->author = 'Your Company';

    // Critical: Declare exact compatibility range
    $this->ps_versions_compliancy = array(
        'min' => '8.0.0',
        'max' => '9.99.99' // Never use _PS_VERSION_ here
    );

    parent::__construct();
}

// ❌ FORBIDDEN: Altering core tables
ALTER TABLE ps_customer ADD COLUMN my_field VARCHAR(255);

// ✅ CORRECT: Create your own table with foreign key
CREATE TABLE ps_my_module_data (
    id_customer INT UNSIGNED NOT NULL,
    my_field VARCHAR(255),
    PRIMARY KEY (id_customer),
    FOREIGN KEY (id_customer) REFERENCES ps_customer(id_customer) ON DELETE CASCADE
);

// ❌ FORBIDDEN: Modifying other modules
include_once(_PS_MODULE_DIR_.'other_module/other_module.php');
$other_module = new OtherModule();
$other_module->some_method = 'modified'; // NEVER DO THIS

// ✅ CORRECT: Use hooks to interact
$this->context->hook->exec('actionMyModuleProcess', array('data' => $my_data));

// Test your module with these settings:
define('_PS_MODE_DEV_', true);
ini_set('display_errors', 'on');
error_reporting(E_ALL);

// ✅ CORRECT: English comments and code
/**
 * Process customer registration data
 * @param array $customer_data Customer information
 * @return bool Success status
 */
public function processCustomerRegistration($customer_data)
{
    // Validate email format
    if (!Validate::isEmail($customer_data['email'])) {
        return false;
    }
    // Process registration...
}

// ❌ FORBIDDEN: Non-English comments
/**
 * Traite les données d'inscription client
 */

// ✅ CORRECT: String sanitization
$sql = 'SELECT * FROM `' . _DB_PREFIX_ . 'orders`
        WHERE `reference` = "' . pSQL($reference) . '"';

// ✅ CORRECT: Integer sanitization
$sql = 'SELECT * FROM `' . _DB_PREFIX_ . 'orders`
        WHERE `id_order` = ' . (int)$id_order;

// ✅ CORRECT: Array sanitization
$product_ids = array_map('intval', $product_ids);
$sql = 'SELECT * FROM `' . _DB_PREFIX_ . 'product`
        WHERE `id_product` IN (' . implode(',', $product_ids) . ')';

// ✅ CORRECT: Table/field name sanitization
$table = bqSQL($table_name);
$sql = 'SELECT * FROM `' . _DB_PREFIX_ . $table . '`';

// ❌ FORBIDDEN: Unsanitized variables
$sql = 'SELECT * FROM `' . _DB_PREFIX_ . 'orders`
        WHERE `reference` = "' . $reference . '"'; // DANGEROUS!

<?php
// index.php content for directory protection
header('Expires: Mon, 26 Jul 1997 05:00:00 GMT');
header('Last-Modified: '.gmdate('D, d M Y H:i:s').' GMT');
header('Cache-Control: no-store, no-cache, must-revalidate');
header('Cache-Control: post-check=0, pre-check=0', false);
header('Pragma: no-cache');
header('Location: ../');
exit;

class MyModuleFrontController extends ModuleFrontController
{
    public function __construct()
    {
        parent::__construct();

        // Generate and verify security token
        if (!$this->verifyToken()) {
            die('Access denied');
        }
    }

    private function verifyToken()
    {
        $expected_token = Tools::hash($this->module->name . Configuration::get('MY_MODULE_SECRET'));
        $received_token = Tools::getValue('token');

        return hash_equals($expected_token, $received_token);
    }
}

// ❌ FORBIDDEN: serialize/unserialize (RCE risk)
$data = serialize($user_input); // DANGEROUS!
$object = unserialize($user_data); // EXTREMELY DANGEROUS!

// ✅ CORRECT: Use JSON instead
$data = json_encode($user_input, JSON_HEX_TAG | JSON_HEX_AMP);
$object = json_decode($user_data, true);

// ❌ FORBIDDEN: eval() function
eval($user_code); // NEVER USE THIS!

// ❌ FORBIDDEN: Unrestricted file operations
file_get_contents($_GET['file']); // Path traversal risk!
include($_POST['file']); // RCE risk!

// ✅ OPTIMIZED: Early exit for irrelevant contexts
public function hookDisplayAdminAfterHeader()
{
    // Exit early if not the target controller
    if ($this->context->controller->controller_name !== 'AdminProducts') {
        return '';
    }

    // Only load assets when needed
    $this->context->controller->addJquery();
    $this->context->controller->addJS($this->_path . 'js/admin-products.js');

    return $this->display(__FILE__, 'admin-header.tpl');
}

// ❌ INEFFICIENT: Processing on every page
public function hookDisplayAdminAfterHeader()
{
    // This runs on EVERY admin page - wasteful!
    $products = Product::getProducts($this->context->language->id, 0, 100);
    $this->context->smarty->assign('products', $products);
    return $this->display(__FILE__, 'admin-header.tpl');
}

// ✅ OPTIMIZED: Single query with joins
$sql = 'SELECT o.*, c.firstname, c.lastname
        FROM `' . _DB_PREFIX_ . 'orders` o
        LEFT JOIN `' . _DB_PREFIX_ . 'customer` c ON (o.id_customer = c.id_customer)
        WHERE o.date_add >= "' . pSQL($date_from) . '"
        AND o.date_add <= "' . pSQL($date_to) . '"
        LIMIT 0, 50';

// ❌ INEFFICIENT: Multiple queries in loop
foreach ($orders as $order) {
    $customer = new Customer($order['id_customer']); // N+1 query problem!
}

// In module constructor
public function __construct()
{
    // ... other initialization ...

    // Only register assets for relevant pages
    if (Tools::getValue('controller') === 'product') {
        $this->context->controller->registerStylesheet(
            'module-mymodule-product',
            'modules/' . $this->name . '/views/css/product.css',
            ['media' => 'all', 'priority' => 150]
        );
    }
}

// ✅ CORRECT: Prefixed configuration keys
Configuration::updateValue('MYMODULE_API_KEY', $api_key);
Configuration::updateValue('MYMODULE_WEBHOOK_URL', $webhook_url);
Configuration::updateValue('MYMODULE_ENABLED_FEATURES', json_encode($features));

// ❌ CONFLICT RISK: Generic keys
Configuration::updateValue('API_KEY', $api_key); // Could conflict!
Configuration::updateValue('ENABLED', true); // Too generic!

// ✅ PREFERRED: Hook-based approach
public function hookDisplayProductAdditionalInfo($params)
{
    $product = $params['product'];
    $additional_info = $this->getAdditionalProductInfo($product['id_product']);

    $this->context->smarty->assign([
        'additional_info' => $additional_info,
        'product' => $product
    ]);

    return $this->display(__FILE__, 'product-additional-info.tpl');
}

// ⚠️ USE SPARINGLY: Override only when absolutely necessary
// override/classes/Product.php
class Product extends ProductCore
{
    // Only override if no hook exists for your specific need
    // Document WHY this override is technically unavoidable
}

public function processApiRequest($data)
{
    try {
        $response = $this->callExternalApi($data);

        if (!$response || isset($response['error'])) {
            throw new PrestaShopException('API call failed: ' . ($response['error'] ?? 'Unknown error'));
        }

        return $response;

    } catch (Exception $e) {
        // Log error for debugging
        PrestaShopLogger::addLog(
            'MyModule API Error: ' . $e->getMessage(),
            PrestaShopLogger::LOG_SEVERITY_LEVEL_ERROR,
            null,
            'MyModule',
            null,
            true
        );

        // Return graceful fallback
        return ['success' => false, 'message' => $this->l('Service temporarily unavailable')];
    }
}