60 lines
3.1 KiB
Markdown
60 lines
3.1 KiB
Markdown
# 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/`).
|