AI-FFL/.github/github_copilot-instructions.md

description, applyTo

description	applyTo
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.	**/*.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) 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:

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

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

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