# Coding Conventions

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

## Naming Patterns

**PHP Class Files:**
- Pattern: `class.ClassName.php` (PascalCase class name)
- Examples: `class.Articles.php`, `class.Authors.php`, `class.Users.php`
- Namespace mirrors directory path: `autoload/admin/factory/class.Articles.php` → `namespace admin\factory;`

**PHP Functions & Variables:**
- Functions: `snake_case` exclusively (`duplicate_article()`, `gallery_order_save()`, `article_save()`)
- Variables: `snake_case` (`$article_id`, `$image_id`, `$output_file`, `$file_type`)
- Class properties: `snake_case` (`$this->article['languages']`)

**CSS/HTML:**
- CSS classes: `kebab-case` (`.sidebar-menu`, `.menu-left`, `.google-title`)
- No BEM methodology — flat class names with some nesting

**SCSS Variables:**
- Colors: `$c` prefix + PascalCase (`$cWhite`, `$cBlack`, `$cGrayDarkBg`, `$cYellow`)
- Fonts: `$f` prefix (`$font1`, `$font2`, `$font3`, `$fLeagueSpartan`)
- Defined in: `layout/style-scss/_variables.scss`

**JavaScript:**
- Variables: camelCase
- Functions: camelCase
- jQuery patterns throughout: `$(document).ready()`, `$('body').on(event, selector, handler)`

**Templates:**
- PHP templates: `kebab-case` in directory/feature structure
- Examples: `article-edit.php`, `articles-browse-list.php`, `page-contact-v5.php`

**Database Tables:**
- Prefix: `pp_` on all tables
- Pattern: `pp_[module]` and `pp_[module]_[subresource]`
- Examples: `pp_articles`, `pp_articles_langs`, `pp_articles_images`

## Code Style

**PHP:**
- Indentation: 2 spaces
- Braces: opening brace on same line as control structure/function
- Spaces: around operators (`=`, `==`, `!=`), within array parentheses
- PHP tags: short tags `<?` and `?>` used in templates (not `<?php`)
- Array formatting: multi-line with aligned assignment operators

**SCSS:**
- Indentation: 2 spaces
- Compilation directive at file top: `// out: ../style-css/style.css, compress: true, sourceMap: true`
- Responsive mixins in `layout/style-scss/_mixins.scss` (breakpoints: xxs, xs, sm, md, lg, xl, xxl, xxxl)
- Vendor prefixes included manually (`-webkit-`, `-moz-`)

**JavaScript:**
- jQuery as primary library (not vanilla JS for DOM)
- ES6 template literals used (`#${boxHref}`)
- No module system — all global scope

**Linting:**
- No ESLint configured
- No Prettier configured
- No PHP CodeSniffer
- No StyleLint
- Code style enforced only by convention/habit

## Architecture Conventions

**MVC Layer Separation:**
- Controls handle requests and call factories — no direct DB queries in controls
- Factories contain all DB queries (Medoo) — static methods
- Views generate HTML and call `Tpl::view()` — no DB queries
- Templates are pure HTML+PHP interpolation — minimal logic

**Namespace Usage:**
- `namespace admin\controls;` / `namespace admin\factory;` / `namespace admin\view;`
- `namespace front\controls;` / `namespace front\factory;` / `namespace front\view;`
- Cross-layer calls use fully qualified names: `\admin\factory\Articles::duplicate_article()`

**Global Helpers:**
- `\S::get()` — parameter retrieval with optional sanitization
- `\S::alert()` — admin notification system
- `\Html::` — HTML generation utilities

## Comments & Documentation

**Comment style:**
- Line comments: `// comment` (mix of Polish and English)
- Block markers: `/* sekcja */` used to label code sections
- Examples from `autoload/admin/factory/class.Articles.php`:
  - `/* tłumaczenia */` (translations section)
  - `/* parametry bez wersji językowych */` (params without language versions)
  - `/* pliki */` (files section)

**Documentation:**
- No PHPDoc blocks
- No `@param` / `@return` / `@throws` annotations
- No type hints in function signatures
- Comments describe sections, not individual functions

## Import / Include Patterns

**PHP:**
- Classes auto-loaded via custom autoloader (not Composer)
- Libraries included directly in entry points: `require 'libraries/medoo/medoo.php'`
- No `use` statements for namespaced imports — always fully qualified calls

**JavaScript:**
- All libraries loaded via `<script>` tags in templates
- No import/require (no module bundler)
- Load order defined in `admin/templates/site/main-layout.php`

## Function Design

**PHP Factory methods:**
- Static methods named after the operation: `article_save()`, `article_delete()`
- No return type declarations
- Return: Medoo result (array), `true`/`false`, or void

**AJAX Handlers:**
- `$_POST` / `$_GET` retrieved via `\S::get()` at top of handler
- JSON response at end: `echo json_encode($output)` and `die()`

---

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