✨feature: Initial commit

.github/github_copilot-instructions.md

@@ -0,0 +1,84 @@
+---
+description: "Custom instructions for a PHP project without a framework, using Clean Code principles and phpcs PEAR standards (with exceptions from phpcs.xml). Enforce 4-space indentation, require docblocks for all classes, functions, and files."
+applyTo: "**/*.php"
+---
+
+# GitHub Copilot Instructions for This PHP Project
+
+Follow these guidelines to ensure code consistency and maintainability in this custom PHP project:
+
+## 1. Coding Standards
+
+- **Base Standard:** Adhere to [PHP_CodeSniffer (phpcs)](https://.com/squizlabs/PHP_CodeSniffer) PEAR coding standards as the default.
+- **Custom Rules:** Where `phpcs.xml` is present, ensure all exceptions and overrides specified in that file take priority over default PEAR rules.
+- **Indentation:** Always use **4 spaces** for indentation. Do not use tabs.
+- **Line Endings:** Use Unix-style (`\n`) line endings.
+- **Max Line Length:** Follow the PEAR default or any overrides set in `phpcs.xml`.
+
+## 2. Clean Code Practices
+
+- Write clear, self-explanatory, and intention-revealing code.
+- Use meaningful variable, function, and class names. Avoid abbreviations and single-letter names except for loop counters and trivial cases.
+- Functions should do one thing and be as short as practical.
+- Avoid deep nesting; use early returns where possible.
+- Minimize code duplication.
+- Keep classes and functions focused on a single responsibility.
+
+## 3. Documentation Standards
+
+- **File-level Docblocks:** Every PHP file must start with a file-level docblock that describes the file’s purpose. Example:
+  ```php
+  /**
+   * Short file description.
+   *
+   * Detailed description (if applicable).
+   *
+   * @package   ProjectName
+   */
+  ```
+- **Class Docblocks:** Each class must have a docblock describing its purpose, usage, and any relevant details.
+  ```php
+  /**
+   * Class Description.
+   *
+   * Detailed explanation of what the class does.
+   *
+   * @package   ProjectName
+   */
+  ```
+- **Function/Method Docblocks:** All functions and methods must have docblocks that describe the purpose, parameters, return values, exceptions thrown, and side effects.
+  ```php
+  /**
+   * Brief summary of what the function does.
+   *
+   * @param  type  $param  Description of parameter.
+   * @return type         Description of return value.
+   */
+  ```
+- **Parameter and Return Types:** Where possible, use type declarations and annotate types in docblocks.
+
+## 4. General PHP Practices
+
+- Use strict types where possible: add `declare(strict_types=1);` at the top of files if project policy allows.
+- Initialize variables before use.
+- Avoid using global variables.
+- Prefer `require_once` or `include_once` over their non-once counterparts.
+- Use visibility (`public`, `protected`, `private`) for all class properties and methods; do not rely on defaults.
+- Use namespaces if the project is organized into multiple logical components.
+- Always sanitize and validate user input.
+- Handle errors gracefully; avoid suppressing errors with `@`.
+
+## 5. Testing
+
+- There is **no testing framework** configured for this project. If writing test code, use clear assertions and keep test code separate from production code.
+
+## 6. File and Project Structure
+
+- Organize files logically by feature or responsibility.
+- Name files and folders using `CamelCase` or `snake_case` consistently, based on existing codebase conventions.
+- Avoid unnecessary dependencies or framework-specific constructs.
+
+---
+
+**Remember:**  
+These instructions are specific to a non-framework PHP project using Clean Code principles, enforcing 4-space indentation, and following phpcs PEAR standards with project-specific exceptions in `phpcs.xml`. Ensure all code, including classes, functions, and files, includes complete and correct docblocks. Apply these guidelines to all PHP files in the repository.