AGENTS.md

1# Intervention Image Agent Guide
2 
3This document provides a guide for software engineering agents working on the Intervention Image codebase.
4 
5## 1. Project Overview
6 
7Intervention Image is a PHP image manipulation library. It provides an expressive, fluent interface to create, edit, and compose images. The library supports both the GD library and Imagick as underlying drivers.
8 
9The source code is located in the `src` directory, and the project follows the PSR-4 autoloading standard.
10 
11## 2. Development Environment
12 
13The project uses Composer to manage dependencies. These dependencies are installed automatically when using the Docker development environment.
14 
15## 3. Build, Lint, and Test Commands
16 
17The following commands are used to ensure code quality and correctness.
18 
19### 3.1. Testing (PHPUnit)
20 
21The project uses PHPUnit for unit and feature testing.
22 
23- **Run all tests:**
24```bash
25  docker compose run --rm tests
26```
27 
28- **Run a single test file:**
29  To run a specific test file, provide the path to the file.
30```bash
31  docker compose run --rm tests tests/Unit/ImageManagerTest.php
32```
33 
34- **Run a single test method:**
35  Use the `--filter` option to run a specific test method by its name.
36```bash
37  docker compose run --rm tests tests/Unit/ImageManagerTest.php --filter testMethodName
38```
39 
40- **Check test coverage:**
41```bash
42  docker compose run --rm coverage
43```
44 
45### 3.2. Static Analysis (PHPStan)
46 
47PHPStan is used for static analysis to find potential bugs.
48 
49- **Run static analysis:**
50```bash
51  docker compose run --rm analysis
52```
53 
54### 3.3. Coding Standards (PHP CodeSniffer)
55 
56The project adheres to the PSR-12 coding standard with additional rules. PHP CodeSniffer is used to enforce these standards.
57 
58- **Check for coding standard violations:**
59```bash
60  docker compose run --rm standards
61```
62 
63## 4. Code Style and Conventions
64 
65Consistency is key. Adhere to the following guidelines when writing code.
66 
67### 4.1. Formatting
68 
69- **PSR-12:** The primary coding standard is PSR-12.
70- **Indentation:** Use 4 spaces for indentation, not tabs.
71- **Line Endings:** Use Unix-style line endings (LF).
72- **Strict Types:** All PHP files must start with `declare(strict_types=1);`.
73- **Class Structure:** Follow the ordering defined in `phpcs.xml.dist`:
74    1. `uses`
75    2. `enum cases`
76    3. `constants`
77    4. `static properties`
78    5. `properties`
79    6. `constructor`
80    7. `static constructors`
81    8. `methods`
82    9. `magic methods`
83 
84### 4.2. Naming Conventions
85 
86- **Classes:** `PascalCase`.
87- **Methods:** `camelCase`.
88- **Variables:** `camelCase`.
89- **Constants:** `UPPER_CASE` with underscore separators.
90- **File Names:** File names must match the class name they contain (e.g., `MyClass.php` for `class MyClass`).
91 
92### 4.3. Imports
93 
94- **One class per `use` statement:** Do not group multiple classes in a single `use` statement.
95- **No leading backslash:** `use` statements must not start with a backslash.
96- **Order:** `use` statements should be ordered alphabetically. Unused imports must be removed.
97 
98### 4.4. Types and Type Hinting
99 
100- **Strict Typing:** All code should be strictly typed.
101- **Parameter Types:** All method parameters must have a type hint.
102- **Return Types:** All methods must have a return type hint.
103- **Property Types:** All class properties must have a type hint.
104- **Nullable Types:** Use nullable types (`?TypeName`) when a `null` value is explicitly allowed.
105 
106### 4.5. Error Handling
107 
108- Exceptions should be used for error handling.
109- When catching exceptions, be as specific as possible. Avoid catching generic `\Exception` or `\Throwable`.
110- Exception messages should be clear and descriptive.
111 
112### 4.6. PHPDoc (DocBlocks)
113 
114- PHPDoc blocks are required for all classes, properties, and methods.
115- Follow the annotation order defined in `phpcs.xml.dist`.
116- Use DocBlocks to provide context and explain complex logic. Do not restate the obvious from the code signature.
117 
118## 5. Branching and Commits
119 
120- **Branching:** Create new branches from the `develop` branch. Name branches descriptively (e.g., `feature/new-filter`, `bugfix/fix-resize-issue`).
121- **Commits:** Write clear and concise commit messages. The first line should be a short summary (max 50 chars). A more detailed explanation can follow after a blank line. Always write the message in imperative and do NOT use any useless prefixes like "chore" or other.
122- **Pull Requests:** Target the `develop` branch for all pull requests. Ensure all checks (tests, linting, analysis) are passing before submitting.
123