Add configuration for cron key and document code style conventions

- Added cron key to config.php for scheduled tasks.
- Created code_style_and_conventions.md to outline PHP version, file naming, DI pattern, controller wiring, Medoo ORM pitfalls, test conventions, caching, and database structure.
- Added project_overview.md detailing the purpose, tech stack, architecture, entry points, and key classes of the shopPRO project.
- Introduced suggested_commands.md for testing and system utilities commands.
- Added task_completion_checklist.md for a structured approach to completing tasks.
- Included .DS_Store files in autoload and templates directories for macOS compatibility.
This commit is contained in:
2026-02-27 14:57:02 +01:00
parent 28f53b7998
commit 6434933dfb
9 changed files with 181 additions and 1 deletions

File diff suppressed because one or more lines are too long

View File

@@ -0,0 +1,47 @@
# Code Style and Conventions
## PHP Version
PHP 7.4 — no PHP 8.0+ features allowed.
## File Naming
- New classes: `ClassName.php` (no prefix)
- Legacy classes: `class.ClassName.php` (leave until migrated)
## DI Pattern (all new code)
```php
class ExampleRepository {
private $db;
public function __construct($db) {
$this->db = $db;
}
public function find(int $id): ?array {
return $this->db->get('pp_table', '*', ['id' => $id]);
}
}
```
## Controller Wiring
- Admin: `admin\App::getControllerFactories()`
- Frontend: `front\App::getControllerFactories()`
- API: `api\ApiRouter::getControllerFactories()`
## Medoo ORM Pitfalls
- `$mdb->delete($table, $where)` takes 2 arguments, NOT 3
- `$mdb->get()` returns `null` when no record, NOT `false`
- After `$mdb->insert()`, check `$mdb->id()` to confirm success
## Test Conventions
- Extend `PHPUnit\Framework\TestCase`
- Mock Medoo: `$this->createMock(\medoo::class)`
- AAA pattern: Arrange, Act, Assert
- Mirror source structure: `tests/Unit/Domain/{Module}/{Class}Test.php`
## Caching
- Redis via `\Shared\Cache\CacheHandler`
- Key pattern: `shop\product:{id}:{lang}:{permutation_hash}`
- Default TTL: 86400 (24h)
- Data serialized — use `unserialize()` after `get()`
## Database
- Table prefix: `pp_`
- Key tables: `pp_shop_products`, `pp_shop_orders`, `pp_shop_categories`, `pp_shop_clients`

View File

@@ -0,0 +1,65 @@
# shopPRO — Project Overview
## Purpose
shopPRO is a PHP e-commerce platform with an admin panel, customer-facing storefront, and REST API.
## Tech Stack
- **Language**: PHP 7.4 (production runs PHP < 8.0 — do NOT use PHP 8.0+ syntax!)
- **ORM**: Medoo (`$mdb` global, injected via DI in new code)
- **Caching**: Redis via `\Shared\Cache\CacheHandler`
- **Testing**: PHPUnit 9.6 via `phpunit.phar`
- **Frontend**: Custom template engine (`\Shared\Tpl\Tpl`)
- **Database**: MySQL with `pp_` table prefix
- **Platform**: Windows (development), Linux (production)
## PHP 7.4 Constraint — CRITICAL
Do NOT use any PHP 8.0+ features:
- No `match` expressions (use ternary/if-else)
- No named arguments
- No union types (`int|string`)
- No `str_contains()`, `str_starts_with()`, `str_ends_with()`
## Architecture
Domain-Driven Design with Dependency Injection.
### Layers
1. **Domain** (`autoload/Domain/`) — Business logic repositories, 27 modules
2. **Admin** (`autoload/admin/`) — Admin panel controllers, support, validation, view models
3. **Frontend** (`autoload/front/`) — Customer-facing controllers and views
4. **API** (`autoload/api/`) — REST API controllers
5. **Shared** (`autoload/Shared/`) — Cache, Email, Helpers, Html, Image, Tpl
### Domain Modules
Article, Attribute, Banner, Basket, Cache, Category, Client, Coupon, Dashboard, Dictionaries, Integrations, Languages, Layouts, Newsletter, Order, Pages, PaymentMethod, Producer, Product, ProductSet, Promotion, Scontainers, Settings, ShopStatus, Transport, Update, User
### Entry Points
- `index.php` — Frontend
- `admin/index.php` — Admin panel
- `api.php` — REST API
- `ajax.php` — Frontend AJAX
- `admin/ajax.php` — Admin AJAX
- `cron.php` — CRON jobs
### Namespace Conventions (case-sensitive on Linux!)
- `\Domain\``autoload/Domain/` (uppercase D)
- `\admin\Controllers\``autoload/admin/Controllers/` (lowercase a)
- `\Shared\``autoload/Shared/`
- `\front\``autoload/front/`
- `\api\``autoload/api/`
### Autoloader
Custom autoloader (not Composer at runtime). Tries:
1. `autoload/{namespace}/class.{ClassName}.php` (legacy)
2. `autoload/{namespace}/{ClassName}.php` (PSR-4 style)
### Key Classes
- `\admin\App` — Admin router
- `\front\App` — Frontend router
- `\front\LayoutEngine` — Frontend layout engine
- `\Shared\Helpers\Helpers` — Utility methods
- `\Shared\Tpl\Tpl` — Template engine
- `\Shared\Cache\CacheHandler` — Redis cache
- `\api\ApiRouter` — REST API router
## Test Suite
765 tests, 2153 assertions. Tests mirror source structure in `tests/Unit/`.

View File

@@ -0,0 +1,41 @@
# Suggested Commands
## Testing
```bash
# Full test suite (recommended, PowerShell)
./test.ps1
# Specific test file
./test.ps1 tests/Unit/Domain/Product/ProductRepositoryTest.php
# Specific test method
./test.ps1 --filter testGetQuantityReturnsCorrectValue
# Via composer
composer test
```
## System Utilities (Windows with Git Bash)
```bash
# Use Unix-style commands (Git Bash shell)
ls # list directory
grep -r # search content (prefer Serena tools instead)
git status # git operations
git log --oneline -10
git diff
git add <file>
git commit -m "message"
git push
```
## Development
```bash
# No build step — PHP is interpreted
# No linting/formatting tool configured
# Entry points are served via web server (XAMPP)
```
## PHP binary
```
C:\xampp\php\php.exe
```

View File

@@ -0,0 +1,25 @@
# Task Completion Checklist
When user says "KONIEC PRACY", execute in order:
1. **Run tests**`./test.ps1`
2. **Update documentation if needed**:
- `docs/DATABASE_STRUCTURE.md`
- `docs/PROJECT_STRUCTURE.md`
- `docs/FORM_EDIT_SYSTEM.md`
- `docs/CHANGELOG.md`
- `docs/TESTING.md`
3. **SQL migrations** (if DB changes): place in `migrations/{version}.sql`
- NOT in `updates/` — build script reads from `migrations/` automatically
4. **Commit** changes
5. **Push** to remote
## Key Documentation Files
- `docs/MEMORY.md` — project memory, known issues
- `docs/PROJECT_STRUCTURE.md` — architecture
- `docs/DATABASE_STRUCTURE.md` — full DB schema
- `docs/TESTING.md` — test suite guide
- `docs/FORM_EDIT_SYSTEM.md` — form system
- `docs/CHANGELOG.md` — version history
- `docs/API.md` — REST API docs
- `docs/UPDATE_INSTRUCTIONS.md` — update packages

BIN
autoload/.DS_Store vendored Normal file

Binary file not shown.

BIN
autoload/front/.DS_Store vendored Normal file

Binary file not shown.

View File

@@ -17,4 +17,6 @@ $config['debug']['apilo'] = true;
$config['trustmate']['enabled'] = true;
$config['trustmate']['uid'] = '34eb36ba-c715-4cdc-8707-22376c9f14c7';
$config['cron_key'] = 'Gi7FzWtkry19hZ1BqT1LKEWfwokQpigh';
?>

BIN
templates/.DS_Store vendored Normal file

Binary file not shown.