Skip to content

AGENTS.md

Latest commit

 

History

History
94 lines (65 loc) · 2.54 KB

AGENTS.md

File metadata and controls

94 lines (65 loc) · 2.54 KB

Agent Guidelines

This document describes the conventions and guidelines for contributing to this repository.

Requirements

  • PHP: >=8.2
  • Laravel: ^11.0 | ^12.0 | ^13.0
    • Laravel 11 and 12 require PHP 8.2+
    • Laravel 13 requires PHP 8.3+

Code Style

Code style is enforced with Laravel Pint using the laravel preset. Imports are sorted by length. The fully_qualified_strict_types rule has phpdoc_tags set to [] so it only affects PHP type declarations, never docblocks. To run Pint locally, first install it (for example: composer require --dev laravel/pint), then run:

vendor/bin/pint

The CI workflow (.github/workflows/php-cs-fixer.yml) runs Pint automatically and commits any fixes.

Imports and Docblocks

  • Docblocks must use fully qualified class names (FQCNs) — e.g. @return \PulkitJalan\IPGeolocation\IPGeolocation, not @return IPGeolocation.
  • use statements must only be added for actual code usage — never add an import solely for a docblock reference. Use the FQCN directly in the docblock instead.
// Good
use PulkitJalan\IPGeolocation\IPGeolocation;

/**
 * @return \PulkitJalan\IPGeolocation\IPGeolocation
 */
public function getGeolocation(): IPGeolocation
{
    return $this->geolocation;
}

// Bad — import added only for docblock
use PulkitJalan\IPGeolocation\IPGeolocation;

/**
 * @return IPGeolocation
 */
public function getGeolocation(): IPGeolocation
{
    return $this->geolocation;
}

Testing

Tests are written with Pest (^3.8). Run the test suite with:

composer test
# or directly:
vendor/bin/pest

Run with coverage (requires Xdebug):

vendor/bin/pest --coverage

Dependencies

Runtime

Development

CI

The GitHub Actions workflow (.github/workflows/run-tests.yml) tests against:

PHP Laravel
8.2 11, 12
8.3 11, 12, 13
8.4 11, 12, 13

Both prefer-lowest and prefer-stable dependency versions are tested. Coverage is uploaded to Codecov for the PHP 8.3 / Laravel 11 / prefer-stable combination.

General

  • Keep changes surgical and limited to the issue being addressed.
  • Do not commit temporary files, dependencies, or build artifacts.