Skip to content

GEMINI.md

Latest commit

 

History

History
86 lines (71 loc) · 2.98 KB

GEMINI.md

File metadata and controls

86 lines (71 loc) · 2.98 KB

Gemini Context File

Project Overview

Name: php-docker-api-client Type: PHP Library / CLI Application Description: A PHP Docker API client generated from the official Docker API OpenAPI specification using Jane PHP. It provides a type-safe and strictly typed interface to interact with the Docker daemon.

Key Technologies

  • Language: PHP ~8.3+
  • Core Library: Jane PHP (OpenAPI Client Generator)
  • Frameworks/Libs: Symfony Console, Symfony HTTP Client
  • Testing: Codeception
  • Code Style: PHP-CS-Fixer

Architecture

The project follows a split architecture between generated code and application logic:

  • generated/: Contains the raw API client, endpoints, and models generated by Jane PHP. Do not modify these files manually unless debugging generation issues.
  • src/: Contains the manually written application logic, wrapper services, factories, and CLI commands.
  • spec/: Contains the Docker OpenAPI specifications (.yaml).

Namespaces

  • Generated Code: WebProject\DockerApi\Library\Generated
  • Application Code: WebProject\DockerApiClient

Build & Run Commands

Installation

composer install

Code Generation

Regenerate the API client from the OpenAPI spec:

composer generate
# Maps to: XDEBUG_MODE=off jane-openapi generate

Testing

Run the Codeception test suite:

composer tests
# Maps to: vendor/bin/codecept run

Run tests with coverage (CI style):

vendor/bin/codecept build -c .
vendor/bin/codecept run -c . -vvv --coverage --coverage-xml=coverage.xml --xml

CLI Usage

The project includes a CLI tool bin/docker-api.

# List containers
bin/docker-api docker:list-containers

# Listen for events
bin/docker-api docker:events:listen

Development Conventions

Coding Style

The project enforces a strict coding style using php-cs-fixer.

  • Config: .php-cs-fixer.php
  • Key Rules:
    • declare(strict_types=1); is mandatory.
    • Global functions should be imported (e.g., use function implode;).
    • null type in unions is always placed first (e.g., ?string or null|string).
    • Binary operators are aligned.
    • Classes are often final.

Code Generation Workflow

  1. Update the OpenAPI spec in spec/ (e.g., docker-v1.51-patched.yaml).
  2. Run composer generate.
  3. The configuration is defined in .jane-openapi.

Testing

  • Tests are located in tests/.
  • The Unit suite is configured in tests/Unit.suite.yml.
  • Coverage reporting includes files in src/.
  • Mocking Final Classes: Since many classes are final, avoid mocking them directly. Instead, instantiate the final class and inject mocked dependencies (e.g., the generated Client) into its constructor.

Continuous Integration

  • Workflows are defined in .github/workflows/.
  • php-tests.yml runs validation, installation, and tests with coverage on multiple PHP versions.