Skip to content

jeffsenso/prestashop-skills / skills/prestashop-module-development

prestashop-module-development

Verified

Complete PrestaShop module development workflow using modern architecture and best practices. Use when: creating new PrestaShop modules, updating legacy modules to modern code, implementing hooks and actions, setting up module configuration pages, adding front office features, handling database operations, implementing security measures, managing translations, creating cart rules and vouchers, building Symfony console commands, or modernizing existing PrestaShop modules from legacy patterns to current standards.

FileKindSize
CHANGELOG.mdmarkdown12.9 KB
README.mdmarkdown3.5 KB
SKILL.mdskill md21.7 KB
ps9-core-ai/CONTEXT.mdmarkdown6.4 KB
ps9-core-ai/Component/BackOfficeHelp/CONTEXT.mdmarkdown1.0 KB
ps9-core-ai/Component/Behat/CONTEXT.mdmarkdown7.7 KB
ps9-core-ai/Component/CQRS/CONTEXT.mdmarkdown6.8 KB
ps9-core-ai/Component/Configuration/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Component/Console/CONTEXT.mdmarkdown1.1 KB
ps9-core-ai/Component/Context/CONTEXT.mdmarkdown1.8 KB
ps9-core-ai/Component/ContextStateManager/CONTEXT.mdmarkdown2.0 KB
ps9-core-ai/Component/Controller/CONTEXT.mdmarkdown4.7 KB
ps9-core-ai/Component/Cookie/CONTEXT.mdmarkdown1.3 KB
ps9-core-ai/Component/Database/CONTEXT.mdmarkdown1.4 KB
ps9-core-ai/Component/Export/CONTEXT.mdmarkdown964 B
ps9-core-ai/Component/FacetedSearch/CONTEXT.mdmarkdown1.3 KB
ps9-core-ai/Component/Forms/CONTEXT.mdmarkdown6.1 KB
ps9-core-ai/Component/Grid/CONTEXT.mdmarkdown5.2 KB
ps9-core-ai/Component/Hook/CONTEXT.mdmarkdown1.1 KB
ps9-core-ai/Component/Import/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Component/Javascript/CONTEXT.mdmarkdown3.9 KB
ps9-core-ai/Component/Link/CONTEXT.mdmarkdown1.4 KB
ps9-core-ai/Component/Locale/CONTEXT.mdmarkdown1.7 KB
ps9-core-ai/Component/MailTemplate/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Component/Migration/CONTEXT.mdmarkdown10.6 KB
ps9-core-ai/Component/Playwright/CONTEXT.mdmarkdown6.4 KB
ps9-core-ai/Component/PositionUpdater/CONTEXT.mdmarkdown1.4 KB
ps9-core-ai/Component/Router/CONTEXT.mdmarkdown1.7 KB
ps9-core-ai/Component/Smarty/CONTEXT.mdmarkdown1.7 KB
ps9-core-ai/Component/TinyMCE/CONTEXT.mdmarkdown1.4 KB
ps9-core-ai/Component/Twig/CONTEXT.mdmarkdown3.9 KB
ps9-core-ai/Domain/Address/CONTEXT.mdmarkdown1.6 KB
ps9-core-ai/Domain/Alias/CONTEXT.mdmarkdown1.3 KB
ps9-core-ai/Domain/ApiClient/CONTEXT.mdmarkdown1.9 KB
ps9-core-ai/Domain/Attachment/CONTEXT.mdmarkdown1.2 KB
ps9-core-ai/Domain/AttributeGroup/CONTEXT.mdmarkdown1.9 KB
ps9-core-ai/Domain/Carrier/CONTEXT.mdmarkdown1.8 KB
ps9-core-ai/Domain/Cart/CONTEXT.mdmarkdown2.1 KB
ps9-core-ai/Domain/CartRule/CONTEXT.mdmarkdown1.6 KB
ps9-core-ai/Domain/CatalogPriceRule/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Domain/Category/CONTEXT.mdmarkdown1.8 KB
ps9-core-ai/Domain/CmsPage/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Domain/CmsPageCategory/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Domain/Combination/CONTEXT.mdmarkdown2.4 KB
ps9-core-ai/Domain/Configuration/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Domain/Contact/CONTEXT.mdmarkdown1.2 KB
ps9-core-ai/Domain/Country/CONTEXT.mdmarkdown1.8 KB
ps9-core-ai/Domain/CreditSlip/CONTEXT.mdmarkdown1.4 KB
ps9-core-ai/Domain/Currency/CONTEXT.mdmarkdown1.9 KB
ps9-core-ai/Domain/Customer/CONTEXT.mdmarkdown2.0 KB
ps9-core-ai/Domain/CustomerMessage/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Domain/CustomerService/CONTEXT.mdmarkdown2.3 KB
ps9-core-ai/Domain/Discount/CONTEXT.mdmarkdown2.4 KB
ps9-core-ai/Domain/Employee/CONTEXT.mdmarkdown2.3 KB
ps9-core-ai/Domain/Feature/CONTEXT.mdmarkdown1.6 KB
ps9-core-ai/Domain/Hook/CONTEXT.mdmarkdown1.1 KB
ps9-core-ai/Domain/ImageSettings/CONTEXT.mdmarkdown1.7 KB
ps9-core-ai/Domain/Language/CONTEXT.mdmarkdown1.7 KB
ps9-core-ai/Domain/MailTemplate/CONTEXT.mdmarkdown1.7 KB
ps9-core-ai/Domain/Manufacturer/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Domain/Meta/CONTEXT.mdmarkdown1.9 KB
ps9-core-ai/Domain/Module/CONTEXT.mdmarkdown1.6 KB
ps9-core-ai/Domain/Notification/CONTEXT.mdmarkdown1.3 KB
ps9-core-ai/Domain/Order/CONTEXT.mdmarkdown2.6 KB
ps9-core-ai/Domain/OrderMessage/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Domain/OrderReturn/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Domain/OrderReturnState/CONTEXT.mdmarkdown1.6 KB
ps9-core-ai/Domain/OrderState/CONTEXT.mdmarkdown1.9 KB
ps9-core-ai/Domain/Position/CONTEXT.mdmarkdown996 B
ps9-core-ai/Domain/Product/CONTEXT.mdmarkdown2.7 KB
ps9-core-ai/Domain/Profile/CONTEXT.mdmarkdown1.7 KB
ps9-core-ai/Domain/Search/CONTEXT.mdmarkdown1.6 KB
ps9-core-ai/Domain/SearchEngine/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Domain/Security/CONTEXT.mdmarkdown1.7 KB
ps9-core-ai/Domain/Shipment/CONTEXT.mdmarkdown1.8 KB
ps9-core-ai/Domain/Shop/CONTEXT.mdmarkdown2.0 KB
ps9-core-ai/Domain/ShowcaseCard/CONTEXT.mdmarkdown1.4 KB
ps9-core-ai/Domain/SqlManagement/CONTEXT.mdmarkdown1.6 KB
ps9-core-ai/Domain/State/CONTEXT.mdmarkdown1.7 KB
ps9-core-ai/Domain/Store/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Domain/Supplier/CONTEXT.mdmarkdown2.1 KB
ps9-core-ai/Domain/Tab/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Domain/Tag/CONTEXT.mdmarkdown1.4 KB
ps9-core-ai/Domain/Tax/CONTEXT.mdmarkdown1.6 KB
ps9-core-ai/Domain/TaxRulesGroup/CONTEXT.mdmarkdown1.7 KB
ps9-core-ai/Domain/Theme/CONTEXT.mdmarkdown1.7 KB
ps9-core-ai/Domain/Title/CONTEXT.mdmarkdown1.6 KB
ps9-core-ai/Domain/Webservice/CONTEXT.mdmarkdown1.9 KB
ps9-core-ai/Domain/Zone/CONTEXT.mdmarkdown1.3 KB
ps9-core-ai/GOTCHAS.mdmarkdown3.9 KB
ps9-core-ai/MULTISTORE.mdmarkdown3.1 KB
ps9-core-ai/STRUCTURE.mdmarkdown11.1 KB
ps9-core-ai/bin/generate-ai-index.shscript17.9 KB
ps9-core-ai/generated/cqrs.mdmarkdown16.1 KB
ps9-core-ai/generated/entities.mdmarkdown2.7 KB
ps9-core-ai/generated/hooks.mdmarkdown3.7 KB
ps9-core-ai/generated/routes.mdmarkdown88.8 KB
references/cart-rules.mdmarkdown8.9 KB
references/configuration-management.mdmarkdown11.9 KB
references/configuration-page.mdmarkdown11.0 KB
references/database-and-entities.mdmarkdown5.7 KB
references/debugging.mdmarkdown5.9 KB
references/entity-doctrine.mdmarkdown12.5 KB
references/forms.mdmarkdown8.5 KB
references/grid-system.mdmarkdown41.0 KB
references/hooks-and-front-office.mdmarkdown8.2 KB
references/legacy-conversion.mdmarkdown3.5 KB
references/module-class-and-installer.mdmarkdown13.7 KB
references/module-structure.mdmarkdown3.4 KB
references/security.mdmarkdown2.4 KB
references/services-and-di.mdmarkdown20.8 KB
references/services-split.mdmarkdown6.0 KB
references/theme-template-injection.mdmarkdown7.4 KB
references/translations.mdmarkdown8.6 KB
references/validation.mdmarkdown2.5 KB
scripts/grid.bundle.jsscript4.4 KB
scripts/translatable-form.bundle.jsscript9.8 KB

references/cart-rules.md

View on GitHub
# PrestaShop Cart Rules (Vouchers)

## Overview

PrestaShop's `CartRule` class (`/classes/CartRule.php`) manages discount vouchers and promotional codes. Cart rules can offer percentage discounts, fixed amount discounts, free shipping, or free gifts.

## Creating Cart Rules Programmatically

### Basic Cart Rule Creation

```php
use CartRule;
use DateTime;
use Language;

$cartRule = new CartRule();

// Name (multilang field - required for all languages)
$languages = Language::getLanguages(true);
foreach ($languages as $language) {
    $cartRule->name[(int) $language['id_lang']] = 'My Cart Rule Name';
}

// Code (optional - if empty, cart rule applies automatically)
$cartRule->code = 'MYCODE2024';

// Dates (required)
$now = new DateTime();
$cartRule->date_from = $now->format('Y-m-d H:i:s');
$cartRule->date_to = $now->modify('+30 days')->format('Y-m-d H:i:s');

// Active state
$cartRule->active = true;

// Save
$cartRule->add();
```

## Voucher Code Generation

### PrestaShop's Official Character Set

PrestaShop uses a specific character set for voucher codes to avoid confusion:

```php
// Character set (no O or 0 to avoid confusion)
$chars = '123456789ABCDEFGHIJKLMNPQRSTUVWXYZ';

function generateCode(int $length = 8): string
{
    $chars = '123456789ABCDEFGHIJKLMNPQRSTUVWXYZ';
    $charsLength = strlen($chars);
    $code = '';
    
    for ($i = 0; $i < $length; ++$i) {
        $code .= $chars[random_int(0, $charsLength - 1)];
    }
    
    return $code;
}
```

### Ensuring Uniqueness

```php
function generateUniqueCode(int $length = 8, int $maxAttempts = 10): string
{
    $attempt = 0;
    
    do {
        $code = generateCode($length);
        $exists = CartRule::getIdByCode($code);
        ++$attempt;
    } while ($exists && $attempt < $maxAttempts);
    
    if ($exists) {
        throw new \RuntimeException('Could not generate unique code');
    }
    
    return $code;
}
```

**Reference**: PrestaShop admin UI uses the same character set in `/js/admin.js` - `gencode()` function.

## Cart Rule Properties

### Essential Fields

```php
// Multilang name (required)
$cartRule->name = [
    1 => 'English Name',
    2 => 'French Name',
];

// Code (8 characters recommended)
$cartRule->code = 'ABC12345';

// Dates (both required)
$cartRule->date_from = '2024-01-01 00:00:00';
$cartRule->date_to = '2024-12-31 23:59:59';

// Active state
$cartRule->active = true; // or false
```

### Reduction Types

**Percentage discount:**
```php
$cartRule->reduction_percent = 10.0; // 10% discount
$cartRule->reduction_tax = true; // Include tax in calculation
```

**Fixed amount discount:**
```php
$cartRule->reduction_amount = 15.0; // €15 discount
$cartRule->reduction_currency = 1; // Currency ID
$cartRule->reduction_tax = true; // Include tax
```

**Free shipping:**
```php
$cartRule->free_shipping = true;
```

**Free gift:**
```php
$cartRule->gift_product = 123; // Product ID
$cartRule->gift_product_attribute = 0; // Combination ID (0 = no combination)
```

### Quantity Settings

```php
// Total quantity available
$cartRule->quantity = 100;

// Quantity per user
$cartRule->quantity_per_user = 1;

// Priority (lower = higher priority)
$cartRule->priority = 1;
```

### Usage Options

```php
// Highlight in back office
$cartRule->highlight = true;

// Allow partial use (for amount-based discounts)
$cartRule->partial_use = true;
```

### Customer Restrictions

```php
// Restrict to specific customer
$cartRule->id_customer = 12345;

// OR restrict to customer groups
$cartRule->group_restriction = true;
// Then add groups via CartRule::addGroup() after save
```

### Cart Conditions

```php
// Minimum cart amount
$cartRule->minimum_amount = 50.0;
$cartRule->minimum_amount_tax = true; // Include tax
$cartRule->minimum_amount_currency = 1; // Currency ID
$cartRule->minimum_amount_shipping = false; // Include shipping in total
```

### Restriction Flags

All restriction flags default to `false` (no restriction):

```php
// Country restriction
$cartRule->country_restriction = false;

// Carrier restriction
$cartRule->carrier_restriction = false;

// Group restriction
$cartRule->group_restriction = false;

// Cart rule compatibility restriction
$cartRule->cart_rule_restriction = false;

// Product restriction
$cartRule->product_restriction = false;

// Shop restriction (multishop)
$cartRule->shop_restriction = false;
```

When set to `true`, you must configure the specific restrictions after saving the cart rule.

## Complete Example: Customer-Specific Voucher

```php
use CartRule;
use Configuration;
use DateTime;
use Language;

function createCustomerVoucher(
    int $customerId,
    string $firstname,
    string $lastname,
    float $reductionPercent,
    int $durationDays
): CartRule {
    $cartRule = new CartRule();
    
    // Multilang name
    $name = sprintf('Auto Reduction %.0f%% - %s %s', $reductionPercent, $firstname, $lastname);
    $languages = Language::getLanguages(true);
    foreach ($languages as $language) {
        $cartRule->name[(int) $language['id_lang']] = $name;
    }
    
    // Generate unique code
    $cartRule->code = generateUniqueCode(8);
    
    // Dates
    $now = new DateTime();
    $cartRule->date_from = $now->format('Y-m-d H:i:s');
    $cartRule->date_to = $now->modify(sprintf('+%d days', $durationDays))->format('Y-m-d H:i:s');
    
    // Customer restriction
    $cartRule->id_customer = $customerId;
    
    // Reduction
    $cartRule->reduction_percent = $reductionPercent;
    $cartRule->reduction_tax = true;
    
    // Options
    $cartRule->highlight = true;
    $cartRule->partial_use = true;
    $cartRule->active = true;
    
    // Quantities
    $cartRule->quantity = 1;
    $cartRule->quantity_per_user = 1;
    $cartRule->priority = 1;
    
    // No other restrictions
    $cartRule->country_restriction = false;
    $cartRule->carrier_restriction = false;
    $cartRule->group_restriction = false;
    $cartRule->cart_rule_restriction = false;
    $cartRule->product_restriction = false;
    $cartRule->shop_restriction = false;
    
    // No other discounts
    $cartRule->free_shipping = false;
    $cartRule->reduction_amount = 0;
    $cartRule->reduction_currency = 0;
    $cartRule->reduction_product = 0;
    $cartRule->gift_product = 0;
    $cartRule->gift_product_attribute = 0;
    
    // No minimum amount
    $cartRule->minimum_amount = 0;
    $cartRule->minimum_amount_tax = false;
    $cartRule->minimum_amount_currency = 0;
    $cartRule->minimum_amount_shipping = false;
    
    // Save
    $cartRule->add();
    
    return $cartRule;
}
```

## CartRule Methods

### Checking Existence

```php
// Check if code exists
$idCartRule = CartRule::getIdByCode('MYCODE');
if ($idCartRule) {
    // Code already exists
}

// Check if customer already used a cart rule
$cartRule = new CartRule($id);
$used = $cartRule->usedByCustomer($customerId);
```

### Getting Cart Rules

```php
// Get cart rules for a customer
$cartRules = CartRule::getCustomerCartRules(
    $languageId,
    $customerId,
    $active = true,
    $includeGeneric = true,
    $inStock = true,
    Cart $cart = null,
    $freeShippingOnly = false,
    $highlight = false
);
```

## Field Validation

PrestaShop's CartRule class validates:

- **name**: Required multilang field
- **date_from** and **date_to**: Required, must be valid dates
- **code**: Optional, max 254 characters, cleaned HTML
- **reduction_percent**: Must be between 0 and 100
- **reduction_amount**: Must be >= 0
- **quantity**: Must be unsigned int
- **id_customer**: Must be valid customer ID or 0

## Common Patterns

### Auto-Apply Cart Rule (No Code)

```php
$cartRule->code = ''; // Empty code = auto-apply
$cartRule->group_restriction = true; // Restrict to specific group
// Add groups after save
```

### Limited-Time Flash Sale

```php
$cartRule->highlight = true; // Highlight in back office
$cartRule->date_to = (new DateTime())->modify('+24 hours')->format('Y-m-d H:i:s');
$cartRule->quantity = 100; // Limited quantity
```

### First Order Discount

```php
$cartRule->quantity_per_user = 1; // One use per customer
$cartRule->minimum_amount = 0; // No minimum
// Check customer order count before applying
```

## Best Practices

1. **Always generate unique codes** - Use `CartRule::getIdByCode()` to check before creating
2. **Use PrestaShop's character set** - Avoid O/0 confusion with `123456789ABCDEFGHIJKLMNPQRSTUVWXYZ`
3. **Set multilang names** - Required for all active languages
4. **Set appropriate dates** - Always include time (H:i:s), not just date
5. **Test cart rule application** - Use PrestaShop's cart simulator before deploying
6. **Set priority correctly** - Lower numbers = higher priority when multiple rules apply
7. **Use highlight flag** - Makes cart rules easy to find in back office
8. **Consider partial_use** - For amount-based discounts that can be used multiple times

## Reference

- CartRule class: `/classes/CartRule.php`
- Admin controller: `/controllers/admin/AdminCartRulesController.php`
- Code generation: `/js/admin.js` - `gencode()` function
- Front display: `/classes/Cart.php` - cart rule application logic
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall