update

.paul/codebase/conventions.md

@@ -0,0 +1,104 @@
+# Coding Conventions
+
+CLAUDE.md documents the conventions; actual code matches ~95%. Specific patterns:
+
+## Naming
+
+- **Files:** `class.{ClassName}.php` (consistent across 40+ classes).
+- **Namespaces:** `\controls`, `\factory`, `\services`, `\view`. Root-namespace utilities live at `autoload/class.{Name}.php` (e.g. `\S`, `\Tpl`, `\DbModel`, `\Cache`, `\Chunk`, `\Cron`, `\Excel`, `\Html`).
+- Mapping enforced by `spl_autoload_register` in [index.php](index.php) lines 3-12.
+
+## Methods
+
+- Heavy reliance on **static methods** in controllers, factories, services. ~99% of public API.
+- Static modifier ordering inconsistent (`static public` vs `public static`).
+
+## Database access
+
+- Always via global `$mdb` (Medoo). Never `new` a connection.
+- Initialized once in [index.php](index.php) lines 24-31.
+- Raw SQL only for complex joins via `$mdb->query(':sql', [':param' => $value])->fetch()`.
+- **Exception:** [api.php](api.php) and [cron.php](cron.php) use RedBeanPHP (`\R::`). See [concerns.md](concerns.md) for the inconsistency.
+
+## Reading params
+
+```php
+$id = (int) \S::get('client_id');
+```
+
+`\S::get($name)` reads POST first, then GET. Defined in [autoload/class.S.php](autoload/class.S.php) lines 198-217.
+
+**Violations found** (use `$_POST` / `$_GET` directly):
+- [autoload/controls/class.Api.php](autoload/controls/class.Api.php) line 47 — API token fallback
+- [autoload/controls/class.Products.php](autoload/controls/class.Products.php) — DataTables `$_POST['order'][0]['dir']`/`['name']`
+
+## Response patterns
+
+```php
+// AJAX
+echo json_encode([...]);
+exit;
+
+// Page
+return \Tpl::view('module/template', ['var' => $value]);
+```
+
+100% consistent across controllers.
+
+## Flash messages
+
+```php
+\S::alert('Nazwa klienta jest wymagana.');
+header('Location: /clients');
+exit;
+```
+
+`\S::alert()` writes to `$_SESSION['alert']`; layout reads it.
+
+## Currency formatting
+
+`\S::number_display($value)` → `"1 234,56 zł"` (Polish locale: space thousands separator, comma decimal). Defined at [autoload/class.S.php](autoload/class.S.php) lines 51-54.
+
+## Localization
+
+- All UI strings in **Polish**.
+- Timezone fixed to `Europe/Warsaw` (`date_default_timezone_set` in [index.php](index.php) line 14, [ajax.php](ajax.php) line 13).
+- Polish slug helper: `\S::seo($val)`. ASCII transliteration: `\S::noPL($val)`.
+
+## Code style
+
+- 2-space indent, no tabs.
+- K&R braces (open on same line).
+- No `declare(strict_types=1);` anywhere.
+- No type hints on signatures.
+- Explicit casting (`(int)`, `(string)`, `(float)`) used liberally for normalization.
+
+## Comments
+
+- Density low (~5%). No `@param`/`@return` docblocks in production code.
+- Only [autoload/class.Chunk.php](autoload/class.Chunk.php) (vendored) has docblocks.
+- Section headers occasionally in Polish (e.g. `// --- Autoryzacja ---`).
+
+## Error handling
+
+- Try/catch present in newer modules ([class.Clients.php](autoload/controls/class.Clients.php) lines 58-75, [class.Cron.php](autoload/controls/class.Cron.php)).
+- Catches generic `\Throwable`; no custom exception classes.
+- Errors persisted as DB settings (e.g. `google_ads_last_error`).
+- No central logger; ad-hoc `error_log` and DB `logs` table.
+- Global `error_reporting` suppresses `E_NOTICE | E_STRICT | E_WARNING` (set in [ajax.php](ajax.php) line 1).
+
+## Templates
+
+- Data injected via `\Tpl::view('module/file', ['k' => $v])`.
+- Inside templates: `<?php echo $this->k ?>` (magic `__get`).
+- Output buffering wraps each `include`.
+- User overrides: `templates_user/` is searched before `templates/`.
+
+## Adding a new module
+
+1. Create `autoload/controls/class.{Module}.php` (namespace `\controls`).
+2. Create `autoload/factory/class.{Module}.php` (namespace `\factory`).
+3. Optionally create `autoload/view/class.{Module}.php` (namespace `\view`).
+4. Create `templates/{module}/main_view.php` and other actions.
+5. Add to `$route_aliases` in [index.php](index.php) if clean URL needed.
+6. Add sidebar link in [templates/site/layout-logged.php](templates/site/layout-logged.php).