# Coding Conventions

**Analysis Date:** 2026-05-10

## Naming Patterns

**Files:**
- PHP class files: PascalCase matching class — `classes/Product.php`, `classes/Cart.php`
- Module entry file: lowercase, matches directory — `modules/crosssellpro/crosssellpro.php`
- Smarty templates: camelCase per module — `cartCrossSell.tpl`, `checkoutCrossSell.tpl`
- Asset files: camelCase — `cartCrossSell.css`, `cartCrossSell.js`

**Functions / Methods:**
- camelCase — `buildCrossSellProducts()`, `collectAccessoryIds()`, `getCombinationFlags()`, `presentProducts()` (`modules/crosssellpro/crosssellpro.php`)
- Hook handlers: literal prefix `hook` + PascalCase hook name — `hookDisplayShoppingCartFooter()`, `hookActionFrontControllerSetMedia()`

**Variables:**
- New custom code: `$camelCase` — `$cartProducts`, `$inCartProductIds`, `$productId`
- Legacy / DB-driven code: `$snake_case` — `$id_product`, `$id_cart`, `$id_shop` (mirrors PrestaShop column names; expected when interacting with ObjectModel data)

**Classes:**
- PascalCase, suffixed `Core` for PrestaShop core — `class ProductCore extends ObjectModel` (`classes/Product.php`)
- Module classes: PascalCase matching folder — `class Crosssellpro extends Module`

**Hook names (string identifiers):**
- camelCase, registered as strings — `displayShoppingCartFooter`, `displayHeader`, `actionFrontControllerSetMedia`

## Code Style

**PHP Formatting:**
- 4-space indentation (no tabs)
- PSR-12-compatible style for new custom code
- Opening braces on same line: `class Crosssellpro extends Module {`
- Single quotes preferred for strings
- Escape filter pattern in templates: `{$product.name|escape:'htmlall':'UTF-8'}`

**JavaScript Formatting:**
- 2-space indentation
- Legacy ES5 in custom module JS (`var` declarations) — `modules/crosssellpro/views/js/cartCrossSell.js`
- camelCase for functions/variables
- Data-attribute targeting: `[data-crosssellpro-block="1"]`

**Smarty:**
- `{$variable|filter:'arg':'arg'}` for output with escaping
- `{if}…{/if}`, `{foreach}…{/foreach}`, `{assign}` block syntax

**Linting:**
- No root-level `.php-cs-fixer.php` or `phpstan.neon`
- Per-module PHPStan/PHP-CS-Fixer config available in some PrestaShop modules (`modules/<m>/tests/phpstan/phpstan.neon`)

## Import Organization

**PHP:**
- `<?php` opener with no namespace declared in custom modules (PrestaShop legacy autoloader convention)
- `use` statements for Symfony / vendor classes when needed
- No enforced ordering — follow existing file's pattern

**JS:**
- Vanilla DOM manipulation in custom module JS — no module bundler
- Theme JS bundled in `themes/leo_gstore/assets/cache/`

## Error Handling

**Patterns:**
- PrestaShop convention: input via `Tools::getValue('key')` (sanitizes; preferred over raw `$_GET`/`$_POST`)
- DB queries via `Db::getInstance()` with `pSQL()` for sanitization (legacy pattern; not parameterized)
- `try/catch` rare — exceptions surfaced via `Tools::displayError()` or logged
- Hook methods generally return rendered output; failure typically silent (returns empty string)

**Custom-code observations:**
- `import-product.php` has minimal error handling, no transaction wrapping
- `buy-by-phone.php` accesses `$_POST` directly without `Tools::getValue()` — see `concerns.md`

## Logging

**Framework:**
- Symfony Monolog (admin layer) via `app/AppKernel.php`
- File logs at `errors.log` (root) and `iadmin/errors.log`
- No structured/contextual logging in custom code

**Patterns:**
- PrestaShop core `PrestaShopLogger::addLog()` — used in some modules
- Custom code prefers `error_log()` or no logging

## Comments

**When to Comment:**
- PHPDoc blocks above public methods (recommended)
- Inline `//` for non-obvious business logic

**PHPDoc style (used in custom module):**
```php
/**
 * Builds presented products list from accessories of products currently in cart.
 *
 * @return array
 */
protected function buildCrossSellProducts()
```
Parameter form:
```php
/**
 * @param int[] $productIds
 * @return array<int, bool>
 */
protected function getCombinationFlags(array $productIds)
```
Property form:
```php
/** @var int Manufacturer identifier */
public $id_manufacturer;
```

**TODO Comments:**
- Format varies (`// TODO`, `// FIXME`, `// HACK`) — found in core, rare in custom code

## Function Design

**Size:**
- Module hook methods kept short; logic delegated to private helpers (e.g. `buildCrossSellProducts()`, `presentProducts()`)
- Long legacy scripts exist (`import-product.php` 813 lines) — anti-pattern

**Parameters:**
- Hook method signatures match PrestaShop dispatcher: `hookXxx(array $params)` where `$params` carries context

## Module Design (PrestaShop-specific)

**Module class skeleton:**
- Constructor sets `$this->name`, `$this->tab`, `$this->version`, `$this->author`, `$this->bootstrap`, then `parent::__construct()`
- `install()` calls `parent::install()` and chains `$this->registerHook(...)` calls
- `uninstall()` calls `parent::uninstall()` (cleans hook table)
- Hook handlers named `hook<HookName>()`

**Template overrides:**
- Module ships defaults in `modules/<m>/views/templates/hook/`
- Theme overrides resolved at `themes/<theme>/modules/<m>/views/templates/hook/`

**Assets:**
- Registered in `hookActionFrontControllerSetMedia()` via `$this->context->controller->registerStylesheet()` / `registerJavascript()`

## Override Design

- Place in `override/classes/<ClassName>.php` or `override/classes/controller/<Name>.php`
- Extend the core class verbatim and add/override methods only
- Document the *why* of each override (currently undocumented in this project — see `concerns.md`)

---

*Convention analysis: 2026-05-10*
*Update when patterns change*