105 lines
3.9 KiB
Markdown
105 lines
3.9 KiB
Markdown
# 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).
|