# Repository Guidelines

## Zasady pisania kodu
- Kod ma być czytelny „dla obcego”: jasne nazwy, mało magii
- Brak „skrótów na szybko” typu logika w widokach, copy-paste, losowe helpery bez spójności
- Każda funkcja/klasa ma mieć jedną odpowiedzialność, zwykle do 30–50 linii (jeśli dłuższe – dzielić)
- max 3 poziomy zagnieżdżeń (if/foreach), reszta do osobnych metod
- Nazewnictwo:
  - klasy: PascalCase
  - metody/zmienne: camelCase
  - stałe: UPPER_SNAKE_CASE
- Zero „skrótologii” w nazwach (np. $d, $tmp, $x1) poza pętlami 2–3 linijki
- medoo + prepared statements bez wyjątków (żadnego sklejania SQL stringiem)
- XSS: escape w widokach (np. helper e())
- CSRF dla formularzy, sensowna obsługa sesji
- Kod ma mieć komentarze tylko tam, gdzie wyjaśniają „dlaczego”, nie „co”

## Project Structure & Module Organization
BackPRO is a custom PHP MVC application (no Laravel/Symfony). Main code lives in `src/` under PSR-4 namespace `App\\`.
- `src/Core/`: bootstrap, routing, base controller/model, config/auth helpers.
- `src/Controllers/`, `src/Models/`, `src/Services/`: HTTP actions, data access, external integrations.
- `templates/`: PHP view templates.
- `config/routes.php`: all route definitions.
- `cron/`: CLI jobs (`publish.php`, `semstorm.php`).
- `migrations/`: ordered SQL schema changes (`001_*.sql`, `002_*.sql`, ...).
- `assets/`: CSS/JS and WordPress theme files.
- `storage/logs/`: runtime logs.

## Build, Test, and Development Commands
- `composer install`: install PHP dependencies.
- `php -S localhost:8000 -t .`: run local dev server from repository root.
- `php cron/publish.php`: run publishing workflow manually.
- `php cron/semstorm.php`: sync SEO metrics manually.
- `php -l src\\Services\\PublisherService.php`: lint a PHP file (repeat per changed file).

## Coding Style & Naming Conventions
- Target PHP `>=8.1` (see `composer.json`), use strict typing where applicable.
- Follow PSR-4 and existing suffix patterns: `*Controller`, `*Service`, `*Model`.
- Use 4-space indentation and braces/newline style consistent with `src/Core/App.php`.
- Keep controllers thin; move API/business logic to `src/Services/`.
- Escape output in templates (`htmlspecialchars`) and use prepared statements via PDO/model layer.

## Testing Guidelines
There is currently no dedicated `tests/` suite in this repository. For each change:
- Lint modified PHP files with `php -l`.
- Run affected flows through UI endpoints and/or cron scripts.
- Verify database-impacting changes with the relevant migration and rollback plan.
- Document manual test steps in the PR.

## Commit & Pull Request Guidelines
Git history favors Conventional Commit-style prefixes, especially `feat:` (for example: `feat: Integrate DataForSEO...`). Use:
- `feat:`, `fix:`, `refactor:`, `docs:`, `chore:` with concise imperative summaries.
- One logical change per commit; include migration changes in the same commit as dependent code.

PRs should include:
- Clear scope and risk summary.
- Linked issue/task ID (if available).
- Setup/migration notes (`migrations/00x_*.sql`, `.env` changes).
- Screenshots for template/UI updates (`templates/`, `assets/`).