# Coding Conventions

**Analysis Date:** 2026-04-26

## Naming Patterns

**Files:**
- `class.{ClassName}.php` — All PHP class files (e.g., `class.Tickets.php`, `class.S.php`)
- `kebab-case.php` — Template files (e.g., `main-view.php`, `order-data-table.php`)
- No test file pattern — no test files exist

**Methods/Functions:**
- `snake_case` — Older/dominant style: `main_view()`, `get_session()`, `basket_view()`
- `camelCase` — Newer additions: `buildPurchaseDataLayer()`, `sendPaidOrderSummaryEmail()`, `isValidTestPriceSecret()`
- Action-oriented names mapping to URL: `ticket_add()`, `order_confirm()`, `login_check()`

**Variables:**
- `$snake_case` — All variables
- `$mdb`, `$user`, `$settings` — Global shorthand names
- `$orderArr`, `$ticketsArr` — Array suffix pattern

**Classes:**
- PascalCase: `Tickets`, `Apanel`, `Users`, `Scanner`
- Namespaced: `\controls\Tickets`, `\factory\Tickets`, `\view\Site`

## Code Style

**Formatting:**
- 2-space indentation (spaces, not tabs)
- CRLF line endings (Windows)
- Spaces inside parentheses: `function method( $param )`, `if ( $x === '' )`
- Spaces around `->`: `$this -> key` (unusual; vs `$this->key` standard)
- Spaces around operators: `$x === ''`, `$x != null`

**Method Visibility:**
- `static public` order (reversed from PSR standard): `static public function main_view()`
- Mix of `static public` and `public static` — inconsistent
- Private helpers: `private static function _helper()`

**Visibility Note:** PHP allows both orderings; the existing codebase uses `static public`.

**Type Usage:**
- Explicit type casting: `(float)$val`, `(int)$id`, `(string)$hash`
- Null coalescing: `$_SESSION[$var] ?? null`
- No strict types declaration (`declare(strict_types=1)` not used)

**Linting/Formatting:**
- No ESLint, Prettier, PHP-CS-Fixer, or similar configured
- Style enforced only by convention

## Import Organization

- No `use` statements or `import` — classes referenced by full namespace inline: `\controls\Tickets::method()`
- Globals declared at method start: `global $settings, $mdb, $user;`
- Libraries loaded in entry points (`index.php`, `ajax.php`) with `require_once`

## Template Patterns

**Rendering:**
```php
return \Tpl::view('tickets/main-view', [
  'tickets' => $ticketsArr,
  'basket'  => $basket,
]);
```

**Variable access in templates:**
```php
$tickets = $this->tickets;   // via __get magic
echo $this->order_price;
```

**Output escaping:**
- `htmlspecialchars()` used inconsistently — not universally applied
- Short echo: `<?= $this->name ?>` (no escaping — common pattern)
- Short if: `<? if ($condition): ?>` (deprecated short tags — present in older templates)

## AJAX Response Pattern

All AJAX actions follow this pattern:
```php
echo json_encode([
  'basket_html' => \Tpl::view('tickets/basket-view', ['basket' => $basket]),
  'count'       => count($basket),
]);
exit;
```
- `exit` always follows `json_encode` output
- Response keys are snake_case
- Often includes rendered HTML fragments for DOM replacement

## Error Handling Conventions

- No exceptions thrown in application code
- Factories return `[]` or `false` on failure (no consistent return type)
- No try/catch blocks except in `autoload/factory/class.Tickets.php` (calendar transactions)
- Errors suppressed via `error_reporting(E_ALL ^ E_NOTICE ^ E_STRICT ^ E_WARNING ^ E_DEPRECATED)` in entry points

## Documentation Style

- Minimal comments overall
- Inline comments use `//*` prefix (non-standard): `//* Zapisywanie do DB bilety`
- Language: mix of Polish and English in comments and variable names
- No PHPDoc blocks on custom application methods
- Vendored libraries (e.g., Excel.php) have `/** @author */` blocks

## Common Patterns

**Global Access (every controller method):**
```php
static public function some_action() {
  global $settings, $mdb;
  global $user;
  // ...
}
```

**Session via S class:**
```php
\S::set_session('basket', $basket);
$basket = \S::get_session('basket') ?? [];
\S::del_session('alert');
\S::alert('Błąd - brak zamówienia');
```

**DB queries via Medoo:**
```php
$order = $mdb->get('orders', '*', ['hash' => $hash]);
$tickets = $mdb->select('order_tickets', '*', ['order_id' => $id]);
$mdb->insert('orders', ['name' => $name, 'email' => $email]);
$mdb->update('orders', ['payment_status' => 1], ['id' => $id]);
```

**Config access:**
```php
$settings['ticket'][$product_id]['name']
$settings['p24_merchant_id']
$settings['admin-password']
```

---

*Conventions analysis: 2026-04-26*
*Update when major style changes are introduced*