vidok.com/.paul/codebase/conventions.md

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