84 lines
3.7 KiB
Markdown
84 lines
3.7 KiB
Markdown
---
|
||
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. |