docs: map existing codebase
- stack.md - Technologies and dependencies - architecture.md - System design and patterns - structure.md - Directory layout - conventions.md - Code style and patterns - testing.md - Test structure (none) - integrations.md - External services - concerns.md - Technical debt and issues - db_schema.md - Database schema and relationships Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
144
.paul/codebase/conventions.md
Normal file
144
.paul/codebase/conventions.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user