mirror of
https://github.com/Vateron-Media/XC_VM.git
synced 2026-10-15 12:02:46 +02:00
chore(github): add composer to dependabot, fix stale AI instructions
dependabot.yml: the comment claimed "no Composer/npm manifests committed", but src/composer.json + composer.lock ARE committed. Added a grouped composer ecosystem (directory /src) so the 4 prod deps and the dev tools get advisory monitoring; noted the production-only vendor recommit step. instructions/php-conventions + architecture-rules: rewritten to the current Composer PSR-4 architecture. They previously described the pre-migration state and misdirected Copilot: - "No autoloading via Composer — custom src/autoload.php" (file removed) and "Do NOT introduce Composer dependencies" → Composer PSR-4, vendor committed production-only, dump-autoload workflow - lowercase paths (src/cli, src/core, src/modules, …) → real PascalCase (src/Cli, src/Core, src/Modules, src/Streaming, …) - setDb() / $r-prefix (both gone from the codebase) → DatabaseAware + self::db(); dropped the dead $r naming rule - inverted namespace guidance → new code is namespaced; legacy coexists, don't mass-migrate - dangling ARCHITECTURE.md ref → docs/en/development/architecture.md (which exists), src/config/modules.php path fixed
This commit is contained in:
Divarion_D
@@ -3,67 +3,51 @@ applyTo: "**/*.php"
|
||||
---
|
||||
# PHP Conventions — XC_VM
|
||||
|
||||
XC_VM is a PHP 8.1+ modular monolith **migrated to Composer PSR-4** (`XcVm\` → `src/`).
|
||||
The application root is `src/` (composer.json, vendor/, bootstrap.php all live there).
|
||||
`short_open_tag=1` is on — view templates use `<?` / `<?=`.
|
||||
|
||||
## Formatting
|
||||
- **Brace style:** K&R (opening brace on same line)
|
||||
- **Indentation:** Tabs (1 tab per level), NOT spaces
|
||||
- **Brace style:** K&R (opening brace on the same line)
|
||||
- **Indentation:** tabs (1 tab per level), NOT spaces
|
||||
- **No trailing whitespace**
|
||||
|
||||
## Comment Language
|
||||
- **New code:** write all comments and DocBlocks in **English** (keep PHPDoc tags
|
||||
`@param`, `@return`, `@package`, etc. in English as they already are).
|
||||
- **Legacy files:** the existing codebase has Russian-language DocBlocks in ~23%
|
||||
of files (notably `src/cli/`, `src/core/Auth/`, `src/public/Controllers/`).
|
||||
Do NOT mass-translate. Translate Russian comments to English only when you are
|
||||
already editing that file for another reason, or when explicitly asked.
|
||||
- **Do not mix languages** within a single new comment block.
|
||||
## Autoloading & dependencies
|
||||
- **Composer PSR-4:** `XcVm\` maps to `src/` (e.g. `XcVm\Core\Database\DatabaseHandler` = `src/Core/Database/DatabaseHandler.php`). Modules load via their own namespace autoloader, not the Composer PSR-4 map.
|
||||
- **`vendor/` is committed and PRODUCTION-ONLY.** Never run `composer install` on a deploy path. To change the autoload map, run `composer dump-autoload` from `src/`. After changing deps, re-commit a `composer install --no-dev` vendor and `composer.lock`.
|
||||
- **Don't add dependencies casually** — a new Composer package means a lockfile update and a production-only vendor recommit. Prefer the standard library or existing vendored libs.
|
||||
|
||||
## Typing and Declarations
|
||||
- **`declare(strict_types=1)`:** legacy code (controllers, `cli/`, most of `core/`) omits it — do NOT add it there. New code already uses it (e.g. `src/core/Auth/*`, `src/core/Enum/*`, `src/core/Events/ListensTo.php`) — follow the pattern of neighbouring files.
|
||||
- **Namespaces:** legacy first-party code has none — do NOT add namespaces to it. The module system *is* namespaced (`src/modules/*/`…`Module.php`), as are bundled parsers (`core/Parsing/M3uParser`, `core/Parsing/PhpM3u8`) — match the surrounding file when working there.
|
||||
- Do NOT add PHP docblocks or type annotations to existing code unless explicitly asked
|
||||
- Parameter type hints: use when writing new service/repository methods, omit when editing legacy code
|
||||
## Namespaces & strict types (new code)
|
||||
- **New PHP files** declare a namespace under `XcVm\…` matching their path, and start with `declare(strict_types=1)`.
|
||||
- **Legacy first-party files** that are not yet namespaced (roughly half the tree) still exist. Do NOT mass-migrate them: only add a namespace / `strict_types` when you are already rewriting that file for another reason. Match the surrounding file when editing.
|
||||
- Modules are namespaced `XcVm\Module\{Pascal}` with the class `{Pascal}Module` in `src/Modules/{name}_{hash5}/`.
|
||||
|
||||
## Database access
|
||||
- **New code** uses the `DatabaseAware` trait: `use \XcVm\Infrastructure\Database\DatabaseAware;` then call `self::db()` (it resolves the connection from the `DatabaseFactory` singleton). Do NOT reintroduce per-class `setDb()` wiring.
|
||||
- `Core/Database/DatabaseHandler` is the PDO wrapper. Query with `?` placeholders, never named parameters: `self::db()->query('SELECT * FROM streams WHERE id = ?;', $id)`. Terminate the SQL string with a semicolon.
|
||||
- Legacy superglobals (`$db`, `$rSettings`, `$rUserInfo`, `$rServers`) are still bridged by `LegacyInitializer` for legacy code — preserve them when editing legacy files, but never introduce new global state in new code.
|
||||
|
||||
## Naming
|
||||
- **Classes:** PascalCase (`StreamService`, `Database`, `FileLogger`)
|
||||
- **Methods:** camelCase (`getById`, `processStream`, `closeConnection`)
|
||||
- **Variables:** `$r` prefix for data arrays and results: `$rData`, `$rArray`, `$rReturn`, `$rRow`, `$rStreamID`
|
||||
- **Constants:** UPPER_SNAKE_CASE (`STATUS_SUCCESS`, `GIT_OWNER`); for typed sets prefer enums (`BootContext`, `ModuleState`) over new string constants
|
||||
- **Database columns in queries:** snake_case as stored in DB
|
||||
- **Classes:** PascalCase (`StreamService`, `DatabaseHandler`)
|
||||
- **Methods:** camelCase (`getById`, `processStream`)
|
||||
- **Constants:** UPPER_SNAKE_CASE; for typed sets prefer enums (`BootContext`, `ModuleState`) over new string constants
|
||||
- **DB columns in queries:** snake_case as stored
|
||||
|
||||
## Class Patterns
|
||||
- Services use `public static` methods in current codebase (legacy pattern)
|
||||
- New domain code follows Controller → Service → Repository pattern per `docs/en/development/architecture.md`
|
||||
- Constructor injection for new services; legacy code still uses `global $db`, `global $rSettings`
|
||||
## Class patterns
|
||||
- New domain code follows **Controller → Service → Repository** (see `docs/en/development/architecture.md`).
|
||||
- Prefer constructor injection for collaborators; use the `DatabaseAware` trait for the shared connection.
|
||||
|
||||
## Global Variables (legacy — do NOT introduce new ones)
|
||||
- `$db` — Database instance
|
||||
- `$rSettings` — System settings array
|
||||
- `$rUserInfo` — Current user info
|
||||
- `$rServers` — Servers configuration
|
||||
- `$_TITLE` — Page metadata
|
||||
## Comments
|
||||
- **New code:** English comments and DocBlocks (keep `@param`, `@return`, `@package` tags in English).
|
||||
- **Legacy files** carry Russian-language DocBlocks in some files. Do NOT mass-translate; translate only a file you are already editing for another reason, or when asked. Don't mix languages within one comment block.
|
||||
|
||||
When editing legacy files that use globals, preserve the pattern. Do NOT refactor globals unless explicitly asked.
|
||||
## Error handling
|
||||
- Prefer typed exceptions from the `XcVmException` hierarchy for new code.
|
||||
- For fatal API responses the codebase uses `exit(json_encode(...))` — match the surrounding handler.
|
||||
- Do NOT wrap existing code in try-catch "just in case".
|
||||
|
||||
## SQL
|
||||
- Use PDO prepared statements with `?` placeholders: `$db->query('SELECT * FROM streams WHERE id = ?;', $rID)`
|
||||
- Do NOT use named parameters (`:name` style)
|
||||
- Terminate SQL strings with semicolon inside the query string
|
||||
|
||||
## Error Handling
|
||||
- Use try-catch + `exit(json_encode(...))` for fatal API errors
|
||||
- Use status constants (`STATUS_SUCCESS`, etc.) for validation flows
|
||||
- Do NOT add exception handling to code that doesn't have it unless asked
|
||||
|
||||
## File Structure
|
||||
- No autoloading via Composer — project uses custom `src/autoload.php`
|
||||
- Admin pages: `src/public/Views/admin/*.php` — mixed PHP/HTML templates (legacy-compatible)
|
||||
- Domain services: `src/domain/{Context}/{ContextService}.php`
|
||||
- Core utilities: `src/core/{Subsystem}/*.php`
|
||||
|
||||
## What NOT to Do
|
||||
- Do NOT add `use` / `namespace` to legacy first-party code (controllers, `cli/`, legacy `core/`) — but keep namespaces when editing the module system (`src/modules/*`), which is already namespaced
|
||||
- Do NOT introduce Composer dependencies
|
||||
- Do NOT restructure legacy files into PSR-4 layout (modules are already namespaced / PSR-4-like)
|
||||
- Do NOT convert existing `global` usage to DI without explicit request
|
||||
- Do NOT add PHPDoc to unchanged code
|
||||
- Do NOT wrap existing code in try-catch "just in case"
|
||||
## What NOT to do
|
||||
- Do NOT run `composer install` on a deploy path, and do NOT add Composer dependencies casually.
|
||||
- Do NOT reintroduce `setDb()` static injection or new `global` usage in new code.
|
||||
- Do NOT mass-migrate legacy files to namespaces / `strict_types` / DI without an explicit request — keep changes surgical.
|
||||
- Do NOT add PHPDoc or type annotations to unchanged code.
|
||||
|
||||
Reference in New Issue
Block a user