Skip to content

AGENTS.md

Latest commit

 

History

History
88 lines (59 loc) · 3.3 KB

AGENTS.md

File metadata and controls

88 lines (59 loc) · 3.3 KB

Project: API Platform Core

You are an expert Core Contributor to API Platform, a PHP framework supporting Symfony and Laravel.

  1. Prime Directives (Behavioral Protocols)
  • Context Retrieval (VectorCode): Before writing new code or asking for clarification, ALWAYS use vectorcode if available to search for existing patterns, interfaces, or similar implementations in the codebase.
  • Test-First Mandate: Your primary output should be functional tests to expose bugs or verify features. Do not fix bugs unless explicitly requested.
  • Execution Restraint: NEVER run the full test suite (Behat or PHPUnit). It is too slow. Only run specific, filtered tests relevant to the current task.
  • Fixture Isolation: Do not modify existing fixtures (tests/Fixtures/...). Always create new Entities, DTOs, or Models to prevent regression in other tests.
  • Git Policy: Do not perform git commits unless explicitly asked.

Environment Awareness: You are working in a monorepo. Dependencies often need linking (composer link).

  1. Information Retrieval Strategy

Use VectorCode to ground your responses in the actual codebase reality.

  • Usage: vectorcode search "natural language query"

When to use:

  • Architecture: "How does the StateProvider interface work?"
  • Fixtures: "Find entities that use the OrderFilter."
  • Conventions: "Show me examples of custom DTOs."
  1. Testing Quick-Reference (Default/Symfony)

For advanced configurations (Event Listeners, MongoDB, Behat tuning), refer to tests/AGENTS.md.

Common Commands:

# symfony console
tests/Fixtures/app/console

# Clear cache (Critical when switching branches/modes)
rm -rf tests/Fixtures/app/var/cache/test

# Remove stale vendor dirs inside src/ (if PHPUnit hangs)
# Component packages under src/ may have leftover vendor/ directories
# from previous `composer link` runs. These cause PHPUnit to scan them
# indefinitely. Remove them before running tests:
find src -name vendor -exec rm -rf {} +

# PHPUnit (Preferred)
vendor/bin/phpunit --filter testMethodName

# Behat (Legacy)
vendor/bin/behat features/main/crud.feature:120 --format=progress

#Component Testing
cd src/Metadata
composer link ../../
./vendor/bin/phpunit
  1. Static Analysis (PHPStan)

Prerequisites: You must run at least one PHPUnit test to warm up the cache before running PHPStan. PHPStan relies on the generated cache (autoload, proxies, etc.) to resolve classes correctly.

vendor/bin/phpstan analyse src/YourComponent
  • MongoDB Stubs: PHPStan may fail with errors about missing MongoDB classes. Fix by installing the MongoDB ODM packages:
composer require --dev doctrine/mongodb-odm-bundle doctrine/mongodb-odm
  • Stale vendor directories: Nested vendor/ dirs inside src/ components can confuse PHPStan. Clean them up with:
find src -name vendor -exec rm -r {} \;
  1. Coding Standards & Conventions
  • Imports: Grouped by type (class, function, const), sorted alphabetically.
  • Modern PHP 8+
  • Static Providers: If DB persistence isn't required, use a static provider in the ApiResource (see Product.php pattern).
  • New Entities: If persistence is required, create a new Entity class (e.g., NewFeatureEntity.php) rather than adding fields to existing ones.
  1. Git & Contribution
  • Commit Messages: Follow Conventional Commits (type(scope): description).
  • Backwards Compatibility: Never break BC.