---
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.