eCert-MBIP/vendor/intervention/gif/AGENTS.md

Intervention Gif Agent Guide

This document provides a guide for software engineering agents working on the Intervention Gif codebase.

1. Project Overview

intervention/gif -- Native PHP GIF encoder/decoder library. Parses and generates GIF binary data. Part of the Intervention Image ecosystem.

• Language: PHP 8.3+ | Namespace: Intervention\Gif

1.1 Architecture

The codebase mirrors the GIF89a binary specification. Each GIF format block has three corresponding classes:

• src/Blocks/<Name>.php -- Data model (value object)
• src/Decoders/<Name>Decoder.php -- Binary stream reader
• src/Encoders/<Name>Encoder.php -- Binary stream writer

Encoder/decoder resolution is convention-based via CanDecode/CanEncode traits. All block models extend AbstractEntity (which implements Stringable).

2. Development Environment

The project uses Composer to manage dependencies. These dependencies are installed automatically when using the Docker test runners.

3. Build, Lint, and Test Commands

The following commands are used to ensure code quality and correctness.

3.1. Testing (PHPUnit)

The project uses PHPUnit for unit and feature testing.

• Run all tests:

  docker compose run --rm tests
  

• Run a single test file: To run a specific test file, provide the path to the file.

  docker compose run --rm tests tests/Unit/BuilderTest.php
  

• Run a single test method: Use the --filter option to run a specific test method by its name.

  docker compose run --rm tests tests/Unit/BuilderTest.php --filter testMethodName
  

• Check test coverage:

  docker compose run --rm coverage
  

3.2. Static Analysis (PHPStan)

PHPStan is used for static analysis to find potential bugs.

• Run static analysis:

  docker compose run --rm analysis
  

3.3. Coding Standards (PHP CodeSniffer)

The project adheres to the PSR-12 coding standard with additional rules. PHP CodeSniffer is used to enforce these standards.

• Check for coding standard violations:

  docker compose run --rm standards
  

4. Code Style and Conventions

Consistency is key. Adhere to the following guidelines when writing code.

4.1. Formatting

• PSR-12: The primary coding standard is PSR-12.
• Indentation: Use 4 spaces for indentation, not tabs.
• Line Endings: Use Unix-style line endings (LF).
• Strict Types: All PHP files must start with declare(strict_types=1);.
• Class Structure: Follow the ordering defined in phpcs.xml:
  1. uses
  2. enum cases
  3. constants
  4. static properties
  5. properties
  6. constructor
  7. static constructors
  8. methods
  9. magic methods

4.2. Naming Conventions

• Classes: PascalCase.
• Methods: camelCase.
• Variables: camelCase.
• Constants: UPPER_CASE with underscore separators.
• File Names: File names must match the class name they contain (e.g., MyClass.php for class MyClass).

4.3. Imports

• One class per use statement: Do not group multiple classes in a single use statement.
• No leading backslash: use statements must not start with a backslash.
• Order: use statements should be ordered alphabetically. Unused imports must be removed.

4.4. Types and Type Hinting

• Strict Typing: All code should be strictly typed.
• Parameter Types: All method parameters must have a type hint.
• Return Types: All methods must have a return type hint.
• Property Types: All class properties must have a type hint.
• Nullable Types: Use nullable types (?TypeName) when a null value is explicitly allowed.

4.5. Error Handling

• Exceptions should be used for error handling.
• When catching exceptions, be as specific as possible. Avoid catching generic \Exception or \Throwable.
• Exception messages should be clear and descriptive.

4.6. PHPDoc (DocBlocks)

• PHPDoc blocks are required for all classes, properties, and methods.
• Follow the annotation order defined in phpcs.xml.
• Use DocBlocks to provide context and explain complex logic. Do not restate the obvious from the code signature.