Wzorce programowania w PHP

Wzorce programowania w PHP dla agentów AI to konfiguracja projektu, prompty i bramki, dzięki którym Claude Code, Codex i Cursor dostarczają kod w Laravelu 13 i Symfony przyjmowany na podstawie dowodów: kontekst frameworka z Laravel Boost, testy pisane przed kodem, Pint, PHPStan i PHPUnit jako definicja ukończenia, ścisły tryb Eloquenta przeciw N+1 oraz testy charakteryzujące przed przepisywaniem legacy.

Ta strona jest dla programistów PHP, za których większość funkcji pisze już agent, oraz dla tech leadów, którzy chcą, żeby w CI cały zespół podlegał tym samym bramkom. Sytuacja, którą rozwiązuje: pull request od agenta jest zielony, tyle że composer.json przypina PHPUnit 13 na PHP 8.3, połowa testów używa adnotacji @test, których PHPUnit 13 w ogóle nie uruchamia, lista produktów leniwie dociąga kategorię dla każdego wiersza, a „zmodernizowane” repozytorium legacy dalej wkleja $id prosto w SQL. Poniższe receptury sprawiają, że agent zderza się z tymi problemami w każdej turze, więc przeglądasz wyniki testów i bramek, a nie każdą linię kodu.

Co dają te receptury PHP

• Tabelę wersji z ograniczeniem PHP, którego naprawdę wymaga każdy aktualny pakiet.
• Laravel Boost podłączony do Claude Code, Codeksa i Cursora, razem z jego dwiema pułapkami.
• AGENTS.md dla aplikacji Laravel i prompt, który szkicuje go z twojego repozytorium.
• Pętlę „testy najpierw” dla endpointu Laravel z cienkim kontrolerem.
• Hook Stop w Claude Code i job GitHub Actions, które odrzucają „gotowe”, dopóki Pint, PHPStan i PHPUnit nie przejdą.
• Ścisły tryb Eloquenta i test liczby zapytań, dzięki którym N+1 kończy się błędem w testach, a nie na produkcji.
• Recepturę modernizacji legacy mysql_*, która najpierw przypina zachowanie, a na końcu sprawdza, czy SQL injection nie przetrwało.
• Test PHPUnit 13 bez ostrzeżeń o deprecjacji oraz testy mutacyjne w Infection, które pokazują, że testy potrafią się wywrócić.

Jakie wersje PHP, Laravela i Symfony zakładają te receptury?

Agenci mieszają API od Laravela 8 do 13 i od PHPUnit 9 do 13, bo tak wyglądają ich dane treningowe. Podaj agentowi wersje i pozwól, żeby przypiął je composer.lock. Tak wyglądały najnowsze stabilne wydania w Packagist pod koniec września 2026:

Pakiet	Najnowsze wydanie	Wymagane PHP
laravel/framework	13.33.0 (2026-09-22); 13.0.0 wyszedł 2026-03-17	^8.3
phpunit/phpunit	13.3.5 (2026-09-25)	>=8.4.1
symfony/symfony	8.1.7 (2026-09-15); 7.4.19 na gałęzi długoterminowego wsparcia (LTS)	>=8.4.1 (8.1), >=8.2 (7.4)
phpstan/phpstan · larastan/larastan	2.2.16 · 3.12.2	^7.4|^8.0 · ^8.2
laravel/pint	1.32.1	^8.3.0
laravel/boost	2.10.0 (2026-09-23)	^8.2
infection/infection	0.35.4 (2026-09-02)	^8.3

Wiersz, który gryzie: Laravel 13 działa na PHP 8.3, ale PHPUnit 13 wymaga PHP 8.4.1 lub nowszego. Dlatego świeży szkielet Laravela 13 przypina "phpunit/phpunit": "^12.5.12". Jeśli agent „podbije” PHPUnit do 13, a composer.json dalej mówi "php": "^8.3", Composer nie rozwiąże zależności na maszynie z PHP 8.3. Wybierz jedno: zostań na PHPUnit 12.5 dla PHP 8.3 albo wymagaj "php": "^8.4" i przejdź na PHPUnit 13.

Jak dać agentowi kontekst Laravela przez Laravel Boost?

Laravel Boost to oficjalny pakiet Laravela dla agentów AI. Zapisuje w repozytorium wytyczne frameworka i skille oraz uruchamia lokalny serwer MCP. Nowy szkielet Laravela 13 ma już AGENTS.md i CLAUDE.md, które każą agentowi zainstalować Boost, zanim zrobi cokolwiek innego, więc agent otwierający świeżą aplikację i tak o niego poprosi. Zainstaluj go w katalogu głównym aplikacji:

composer require laravel/boost --dev
php artisan boost:install

boost:install pyta, jakich agentów używasz i które części zainstalować (--guidelines, --skills i --mcp wybierają je bez pytań). Domyślne ścieżki według kodu Boost 2.10.0, każdą można zmienić w config/boost.php:

Agent	Serwer MCP rejestrowany w	Wytyczne zapisywane do	Skille zapisywane do
Claude Code	.mcp.json	AGENTS.md	.claude/skills
Codex	.codex/config.toml	AGENTS.md	.agents/skills
Cursor	.cursor/mcp.json	AGENTS.md	.cursor/skills

Serwer MCP (php artisan boost:mcp) daje agentowi narzędzia, które czytają schemat bazy, wykonują SQL tylko do odczytu, przeszukują dokumentację dokładnie dla wersji pakietów z twojego pliku composer.lock, czytają ostatni wyjątek i log aplikacji oraz wykonują PHP przez Tinkera. Najwięcej zmienia narzędzie schematu: generowane migracje, casty i fabryki przestają zgadywać nazwy kolumn. Po aktualizacji Laravela lub Boosta uruchom php artisan boost:update, żeby odświeżyć wytyczne i skille.

Dwie rzeczy, których dokumentacja Boosta nie stawia na pierwszym planie:

• Boost startuje tylko w środowisku lokalnym albo przy APP_DEBUG=true. Na stagingu lub hoście zbliżonym do produkcji, gdzie APP_ENV nie jest local, a APP_DEBUG=false, serwer MCP nie rejestruje narzędzi, więc agent działający tam nie ma dostępu do schematu. To właściwe zachowanie; nie włączaj debugu, żeby je „naprawić”.
• Narzędzie SQL jest tylko do odczytu, Tinker nie. Narzędzie zapytań Boosta odrzuca wszystko poza SELECT, SHOW, EXPLAIN, DESCRIBE i WITH … SELECT i wykonuje zapytanie w transakcji, którą wycofuje. Narzędzie Tinker wykonuje dowolny PHP w twojej aplikacji, łącznie z Product::query()->delete(). Skieruj .env na jednorazową lokalną bazę, nigdy na kopię produkcji z danymi klientów.

W Symfony odpowiednika Boosta nie ma. Napisz poniższy AGENTS.md ręcznie i podłącz serwer bazodanowy tylko do odczytu z serwerów MCP dla baz danych, żeby agent czytał prawdziwy schemat.

Co wpisać do AGENTS.md w aplikacji Laravel?

Wytyczne Boosta obejmują konwencje Laravela. Twój plik dodaje to, co wie tylko twój kod: polecenia, które agent musi uruchomić, w kolejności, w jakiej ma je uruchomić, oraz kilka reguł, które ogólny model w tym repozytorium myli. Pomiń wszystko, co już egzekwuje Pint lub PHPStan. Wpisz to do pliku, do którego pisze Boost, nad lub pod wygenerowanym przez niego blokiem.

AGENTS.md

# Shop (Laravel 13, PHP 8.4, MySQL 8, PHPUnit 13)

## Commands (run from the repo root)
- One test: `php artisan test --filter=ProductIndexTest`
- Style check: `vendor/bin/pint --test` (fix with `vendor/bin/pint --dirty`)
- Static analysis: `vendor/bin/phpstan analyse` (Larastan, level 8)
- Full gate: `vendor/bin/pint --test && vendor/bin/phpstan analyse && php artisan test`

## Definition of done
The full gate passes. Report the command you ran and its last lines.

## Rules
- Create classes with `php artisan make:*`, never by hand; every model gets a migration and a factory.
- Controllers only validate (Form Request), call one service method and return an API Resource.
- Tests are the specification. If a test fails, fix app/, not tests/. Ask before changing an assertion.
- Test attributes (`#[Test]`, `#[DataProvider]`), never doc-comment annotations.
- Every query that feeds a collection eager-loads with `with()`; strict mode throws on lazy loading.
- Raw SQL only through bound parameters; never interpolate a variable into a query string.
- Money is integer cents (`*_cents`), never float.

Każde narzędzie wczytuje ten plik inaczej:

Claude Code

Utwórz CLAUDE.md, którego pierwsza linia importuje wspólny plik, a pod nią dopisz linie tylko dla Claude’a:

CLAUDE.md

@AGENTS.md

CLAUDE.md ze szkieletu zawiera wyłącznie tekst startowy Boosta, więc po boost:install zastąp go. Claude Code 2.1.277 i nowsze czytają też AGENTS.md bezpośrednio, gdy projekt nie ma CLAUDE.md (sesje first-party, oba kanały wydań, stan na 2026-10-12); import działa w każdej wersji i na każdym kanale.

Codex

Codex czyta AGENTS.md, zanim zacznie pracę. Od codex-cli 0.150.0 projekt, któremu Codex nie ufa, nie dostarcza swojego AGENTS.md, więc gdy Codex zapyta, oznacz repozytorium jako zaufane.

Cursor

Dodaj zawsze stosowaną regułę projektu (format opisuje strona reguły projektu w Cursorze), która powtarza sekcje Commands i Rules z pliku powyżej, i ją zacommituj. Potem poproś agenta, żeby zacytował ci Definition of done; to dowód, że reguła się wczytała.

Prompt do skopiowania: szkic AGENTS.md z istniejącej aplikacji PHP

Read composer.json, composer.lock, phpunit.xml, phpstan.neon (or phpstan.neon.dist), pint.json if present, .env.example, and list the directories under app/ (or src/), tests/ and database/. Write AGENTS.md with: (1) a one-line description naming the PHP, framework and PHPUnit versions from composer.lock and the database; (2) the exact commands for one test, the style check, static analysis and the full gate, as they work in THIS repo; (3) a "Definition of done" line; (4) at most eight rules, each a convention this codebase visibly follows that a generic Laravel or Symfony model would get wrong. Do not restate what Pint or PHPStan already enforce. Run every command you list and tell me which ones failed and why.

Wspólne reguły agentów wyjaśniają, jak utrzymać jedno źródło prawdy, gdy zespół używa wszystkich trzech narzędzi.

Jak zbudować endpoint Laravel z cienkim kontrolerem, którego agent nie oszuka?

Prośba o „API produktów” kończy się 200-liniowym kontrolerem z budowaniem zapytań, walidacją i kształtowaniem odpowiedzi w jednym miejscu, a do tego testami dopisanymi po fakcie tak, żeby pasowały do tego, co robi kod. Odwróć kolejność. Spisz kryteria akceptacji, każ agentowi zamienić je w padające testy funkcjonalne, przejrzyj tylko testy, a potem pozwól mu implementować pod testy, których nie wolno mu edytować. Samo pisanie kryteriów opisuje strona kryteria akceptacji.

Prompt do skopiowania: padające testy funkcjonalne z kryteriów akceptacji

Acceptance criteria for GET /api/v1/products:
- Returns 15 products per page by default; ?per_page accepts 1-100, anything else is a 422.
- ?search filters by name, case-insensitive.
- Each item has id, name, price_cents and category {id, name}.
- Anonymous requests get 401; more than 60 requests a minute from one user get 429.
Write tests/Feature/ProductIndexTest.php with one test per criterion using PHPUnit attributes, RefreshDatabase and model factories. Create the factories if they are missing, with php artisan make:factory. Do not write any application code. Run php artisan test --filter=ProductIndexTest and show me that every test fails for the right reason (404 or missing class), not because of a typo in the test.

Czytasz testy, a nie implementację, która po nich przyjdzie. Następnie:

Prompt do skopiowania: endpoint z cienkim kontrolerem pod zablokowane testy

Make every test in tests/Feature/ProductIndexTest.php pass without modifying anything under tests/. Generate classes with php artisan make:* (model with migration and factory, controller with --api, form request, resource). The controller validates through a Form Request, calls ProductService::paginate() and returns ProductResource::collection(). The service owns the query, including with('category'). Register the route under /api/v1 with auth:sanctum and throttle:60,1 (run php artisan install:api first if Sanctum is not installed). When done, run vendor/bin/pint --test, vendor/bin/phpstan analyse and php artisan test, and paste the last lines of each.

Akceptujesz kontroler, który wyłącznie deleguje:

app/Http/Controllers/Api/V1/ProductController.php

final class ProductController extends Controller
{
    public function __construct(private readonly ProductService $products) {}

    public function index(IndexProductRequest $request): AnonymousResourceCollection
    {
        return ProductResource::collection(
            $this->products->paginate(
                perPage: $request->integer('per_page', 15),
                search: $request->string('search')->toString(),
            ),
        );
    }
}

RefreshDatabase uruchamia migracje przed testami, więc model wygenerowany bez migracji pada tutaj, a nie na produkcji.

Jak powstrzymać agenta przed ogłoszeniem „gotowe”, zanim bramka przejdzie?

Instrukcja w AGENTS.md to rada, a hook albo check w CI to bramka. Claude Code dostaje lokalną bramkę z poniższego hooka Stop. Codex też ma hooki ze zdarzeniem Stop (codex-cli 0.157.1, wymagają utrwalonego zaufania), a Cursor ma Hooks, ale poniższe konfiguracje dają tym dwóm narzędziom prompt i regułę, więc dla nich bramką jest job CI pod zakładkami.

Claude Code

Hook Stop uruchamia się, gdy Claude kończy odpowiedź. Kod wyjścia 2 blokuje zakończenie i pokazuje Claude’owi stderr hooka, więc Claude pracuje dalej:

.claude/hooks/php-gate.sh

#!/usr/bin/env bash
# Refuse "done" until Pint, PHPStan and PHPUnit pass.
input=$(cat)
# Already continuing because of this hook: stop and report instead of looping.
[ "$(echo "$input" | jq -r '.stop_hook_active')" = "true" ] && exit 0
cd "$CLAUDE_PROJECT_DIR" || exit 0
# Skip only when the branch has no code, test or schema changes against its base,
# committed, uncommitted or untracked: committing during the turn does not hide work.
dirs="app src tests database config routes"
base=$(git merge-base HEAD origin/HEAD 2>/dev/null || git merge-base HEAD origin/main 2>/dev/null || git rev-parse HEAD)
if git diff --quiet "$base" -- $dirs && [ -z "$(git ls-files --others --exclude-standard -- $dirs)" ]; then exit 0; fi
if ! out=$(vendor/bin/pint --test 2>&1); then
  echo "Pint found style violations. Run vendor/bin/pint --dirty:" >&2
  echo "$out" | tail -20 >&2; exit 2
fi
if ! out=$(vendor/bin/phpstan analyse --no-progress --error-format=raw 2>&1); then
  echo "PHPStan failed. Fix the code; never add ignoreErrors or @phpstan-ignore:" >&2
  echo "$out" | head -30 >&2; exit 2
fi
if ! out=$(php artisan test 2>&1); then
  echo "Tests failed. Fix app/, never tests/:" >&2
  echo "$out" | tail -40 >&2; exit 2
fi
exit 0

Skrypt potrzebuje jq; w Symfony zamień php artisan test na vendor/bin/phpunit. Warunek pominięcia porównuje gałąź z jej bazą (origin/HEAD, a w razie braku origin/main), więc praca, którą agent zacommituje w trakcie tury, i tak zostanie sprawdzona. Koszt: na gałęzi, która ma już zmiany w PHP, bramka uruchamia się w każdej turze, także przy samych pytaniach. Jeśli żadna z tych referencji zdalnych nie istnieje, skrypt wraca do sprawdzania tylko niezacommitowanych zmian. Ponieważ kończy się kodem 0, gdy stop_hook_active ma wartość true, padająca bramka wymusza jedną ponowną próbę, a potem Claude się zatrzymuje i raportuje, zamiast kręcić się w pętli na teście, który nie może przejść. Zarejestruj skrypt w .claude/settings.json i nadaj mu prawo wykonania (chmod +x):

.claude/settings.json

{
  "hooks": {
    "Stop": [
      { "hooks": [ { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/php-gate.sh", "timeout": 600 } ] }
    ]
  }
}

Automatyzacja hookami opisuje liczenie ponownych prób i pozostałe zdarzenia.

Codex

composer install potrzebuje sieci, a sandbox workspace-write jej nie ma, dopóki jej nie włączysz. Najpierw zainstaluj zależności poza agentem, potem uruchom pętlę:

composer install
codex exec --sandbox workspace-write "Make every test in tests/Feature/ProductIndexTest.php pass without modifying tests/. Finish only when vendor/bin/pint --test, vendor/bin/phpstan analyse and php artisan test all pass; print the last lines of each."

phpunit.xml ze szkieletu uruchamia testy na SQLite w pamięci, co działa w sandboksie. Jeśli testy potrzebują serwera MySQL, do którego sandbox nie sięga, uruchamiaj je w CI. Gdy zadaniem jest dodanie pakietu, włącz sieć tylko na to jedno uruchomienie przez -c sandbox_workspace_write.network_access=true.

Cursor

Wklej prompt implementacyjny do agenta, najpierw w Plan Mode, jeśli zmiana dotyka jednocześnie modeli, kontrolerów i migracji. Definition of done w regule projektu każe agentowi uruchomić pełną bramkę przed raportem, ale reguła to wciąż tylko rada. Mechaniczną bramką dla Cursora jest poniższy job CI, plus Bugbot, jeśli twój zespół używa go do review.

Niezależnie od tego, co działa lokalnie, decyduje CI. Ten job działa z tokenem tylko do odczytu i nie przechodzi, gdy pull request zmienia istniejący test bez etykiety od recenzenta:

.github/workflows/php-gates.yml

name: php-gates
on:
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled]
permissions:
  contents: read
jobs:
  gates:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
          fetch-depth: 2   # the PR merge commit and its base parent
      - name: Existing tests unchanged
        if: ${{ !contains(github.event.pull_request.labels.*.name, 'test-change-approved') }}
        run: |
          changed=$(git diff --name-only --diff-filter=MDR HEAD^1 HEAD -- tests/)
          if [ -n "$changed" ]; then
            echo "Existing tests modified, moved or deleted; a reviewer must add the test-change-approved label:"
            echo "$changed"; exit 1
          fi
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.4'
          coverage: none
      - run: composer install --no-interaction --no-progress --prefer-dist
      - run: composer audit
      - run: vendor/bin/pint --test
      - run: vendor/bin/phpstan analyse --no-progress
      - run: cp .env.example .env && php artisan key:generate
      - run: php artisan test

Nowe pliki testów przechodzą krok „Existing tests unchanged”; edycje, zmiany nazw i usunięcia w tests/ powodują, że ten krok nie przechodzi, dopóki człowiek ich nie przejrzy i nie doda etykiety test-change-approved, która startuje nowe uruchomienie. Krok jest bramką tylko wtedy, gdy pull request nie może go usunąć: GitHub uruchamia plik workflow z samego pull requesta, więc obejmij /.github/ regułą CODEOWNERS i wymuś tę recenzję przez ochronę gałęzi lub ruleset. Ochrona wyroczni idzie dalej: reguły deny w ogóle nie pozwalają agentowi edytować testów.

Jak wyłapać zapytania N+1 w Eloquencie pisanym przez agenta?

Typowa regresja w Laravelu pisanym przez agenta to resource albo pętla w Blade, która leniwie dociąga relację dla każdego wiersza: szybko przy pięciu wierszach na demo, timeout przy 500 na produkcji. Zamień to w wyjątek wszędzie poza produkcją:

app/Providers/AppServiceProvider.php

use Illuminate\Database\Eloquent\Model;

public function boot(): void
{
    // Throws on lazy loading, on assigning non-fillable attributes and on reading missing attributes.
    Model::shouldBeStrict(! $this->app->isProduction());
}

Przy włączonym trybie ścisłym każdy test, który dotyka leniwie ładowanej relacji, rzuca LazyLoadingViolationException, a hook Stop i job CI powyżej zamieniają to w wywróconą bramkę. Tryb ścisły nie złapie zapytania na wiersz, które nie jest relacją, na przykład count() w akcesorze, więc przypnij też liczbę zapytań każdego endpointu z listą:

Prompt do skopiowania: udowodnij, że liczba zapytań nie rośnie

For GET /api/v1/products, add a test to tests/Feature/ProductIndexTest.php that seeds 3 products, records the query count with DB::enableQueryLog(), then seeds 40 more and asserts the count is identical. Then add a second test that uses $this->expectsDatabaseQueryCount() with the count you measured. If the count grows with rows, fix the query in ProductService (with(), withCount(), loadMissing()) and never the test. Show me the SQL from the query log before and after your fix.

Jak dodać cache i nie serwować nieaktualnych danych?

Naiwny prompt o cache rozsiewa Cache::remember() po całym kodzie bez żadnego unieważniania, a strona produktu pokazuje cenę sprzed tygodnia. Niech unieważnianie i test, który je udowadnia, będą częścią prośby:

Prompt do skopiowania: cache w Redisie z przetestowanym unieważnianiem

Add caching to ProductService::find(int $id) with the Laravel Cache facade on the redis store: key "product:{id}", TTL one hour, tagged "products" and "category:{category_id}". Do not cache null. Invalidate in exactly one place: a ProductObserver handling saved and deleted, which forgets the item key and flushes the category tag. Write a feature test that reads a product, updates its price through the API, reads it again and asserts the new price. Tell me which reads can still be stale after your change and for how long.

Tagi cache działają tylko w magazynach, które je obsługują, takich jak Redis i Memcached; magazyny file i database rzucają wyjątek. Uruchom test na magazynie, którego używasz na produkcji, a nie na magazynie array, który domyślnie ustawia phpunit.xml.

Jak zmodernizować legacy z mysql_* przy pomocy agenta?

Rozszerzenie mysql_* usunięto w PHP 7.0, więc kod, który wciąż go wywołuje, działa tylko na PHP 5.x. Konwersja składni jest mechaniczna, więc agent robi ją szybko; ryzyko leży gdzie indziej. Agent może „unowocześnić” składnię, zostawiając "... WHERE id = $id" wewnątrz wywołania PDO, albo po cichu zmienić to, co funkcja zwraca w przypadku brzegowym, na którym polegają wywołujący. Dlatego najpierw przypnij dzisiejsze zachowanie testami charakteryzującymi i zablokuj je przed przepisaniem. Starego kodu nie uruchomisz na PHP 8.4, którego używa reszta tej strony, więc nagraj jego zachowanie tam, gdzie wciąż działa: wywołaj funkcję dla każdego przypadku w kontenerze z PHP 5.6 (oficjalny obraz php:5.6-cli plus docker-php-ext-install mysql, podłączony do jednorazowej kopii bazy) i zapisz zwracane wartości jako fixture w JSON. Testy działają potem na PHP 8.4 i sprawdzają, że nowy kod zwraca to, co zapisano w fixture.

Claude Code

Uruchom z katalogu głównego repozytorium, żeby Claude Code przeszukał wszystkich wywołujących, a nie tylko otwarty plik:

claude "Modernize get_user() in legacy/users.php. First record its current behaviour: write scripts/record-get-user.php, which calls get_user() for an existing id, a missing id, id 0 and a non-numeric string and writes the return values to tests/Characterization/fixtures/get_user.json; run it in a php:5.6-cli container with the mysql extension against a disposable copy of the test database, and show me the fixture. Then write tests/Characterization/GetUserTest.php, which runs on PHP 8.4 and asserts that the new code returns data equivalent to those recorded values (same fields, same result for a missing id). Then create App\\Repository\\UserRepository::findById(int \$id): ?User using PDO prepared statements with bound parameters, wrap PDOException in RepositoryException, update every caller repo-wide, and make the characterization tests pass against the new code without editing them. Finish with vendor/bin/phpstan analyse and the full test suite."

Codex

Uruchom nieinteraktywnie w sandboksie workspace, żeby zmiana została w repozytorium, dopóki nie przejrzysz diffu:

codex exec --sandbox workspace-write "Modernize get_user() in legacy/users.php. First record its current behaviour: write scripts/record-get-user.php, which calls get_user() for an existing id, a missing id, id 0 and a non-numeric string and writes the return values to tests/Characterization/fixtures/get_user.json; run it in a php:5.6-cli container with the mysql extension against a disposable copy of the test database, and show me the fixture. Then write tests/Characterization/GetUserTest.php, which runs on PHP 8.4 and asserts that the new code returns data equivalent to those recorded values (same fields, same result for a missing id). Then create App\\Repository\\UserRepository::findById(int \$id): ?User with PDO prepared statements and bound parameters, wrap PDOException in RepositoryException, update every caller, and make the characterization tests pass without editing them. Finish with vendor/bin/phpstan analyse and the full test suite."

Cursor

Otwórz legacy/users.php, przełącz agenta w Plan Mode i wklej prompt z zakładki Claude Code. Zanim agent zacznie pisać kod, przejrzyj w planie listę wywołujących: typowa porażka to pominięte wywołanie w pliku, którego agent nie otworzył. Potem pozwól mu wykonać plan i uruchomić testy.

Docelowy kształt ma związany parametr i typowany zwrot:

app/Repository/UserRepository.php

declare(strict_types=1);

namespace App\Repository;

use App\Entity\User;
use PDO;
use PDOException;

final class UserRepository
{
    public function __construct(private readonly PDO $connection) {}

    public function findById(int $id): ?User
    {
        try {
            $statement = $this->connection->prepare(
                'SELECT id, email, name, created_at FROM users WHERE id = :id'
            );
            $statement->execute(['id' => $id]);
            $row = $statement->fetch(PDO::FETCH_ASSOC);

            return $row === false ? null : User::fromArray($row);
        } catch (PDOException $e) {
            throw new RepositoryException("Failed to fetch user {$id}", 0, $e);
        }
    }
}

Przed merge’em zrób wstępne przeszukanie pod kątem SQL, który wciąż buduje zapytanie ze zmiennej. Ten grep oznacza wywołania budujące zapytania (PDO, mysqli i metody surowego SQL w Laravelu), których lista argumentów zawiera zmienną ($). Konkatenacji ze stałą albo wywołaniem funkcji nie oznacza:

grep -rnE '(query|prepare|exec|select|statement|whereRaw|selectRaw|orderByRaw)\s*\([^)]*\$' app/ src/ legacy/

Trafienie to linia do poprawienia albo uzasadnienia; pusty wynik nie jest dowodem. Grep nie widzi zapytania zbudowanego linię wcześniej, heredoca ani wartości przekazanej z innej funkcji. Prawdziwą bramką jest analiza przepływu danych w CI: analiza taint w Psalmie (vendor/bin/psalm --taint-analysis) śledzi dane z żądania aż do miejsc wykonujących SQL, takich jak PDO::exec(), a reguła Semgrep robi to samo dla twoich helperów zapytań. Razem z testami charakteryzującymi powyżej to dowód, który recenzent przyjmuje. Szerszą strategię (seamy typu strangler, kolejność dużego przepisywania) opisuje strona modernizacja legacy.

Skąd wiesz, że testy PHPUnit od agenta złapałyby błąd?

Agenci piszą testy, które przechodzą. To, czy padają, gdy kod jest błędny, to osobne pytanie, a dwie zmiany w PHPUnit sprawiają, że testy agenta są po cichu słabsze, niż wyglądają:

• Adnotacje już się nie uruchamiają. PHPUnit 12 usunął metadane w komentarzach dokumentujących. Metoda annotation_only() z samym /** @test */ nad nią nie jest w PHPUnit 13 testem: runner pomija ją bez błędu, więc liczba testów po prostu spada.
• Prophecy nie jest w zestawie. PHPUnit 10 i nowsze nie mają integracji z Prophecy; ProphecyTrait pochodzi z pakietu phpspec/prophecy-phpunit. Bez niego klasa testu się nie wczyta. Własne createMock() i createStub() z PHPUnit nie potrzebują niczego dodatkowego.

Proś o poniższy kształt. Order to tutaj zwykły obiekt wartości z domeny z konstruktorem (int $id, OrderStatus $status), a nie model Eloquenta, którego konstruktor przyjmuje tablicę atrybutów. Z taką klasą test przechodzi na PHPUnit 13.3.5 bez żadnej deprecjacji. Zwróć uwagę na expects() przed with() przy find: PHPUnit 13 oznacza with() na mocku bez expects() jako przestarzałe, a PHPUnit 14 je odrzuci.

tests/Unit/OrderServiceTest.php

declare(strict_types=1);

namespace Tests\Unit;

use App\Domain\Order;
use App\Enums\OrderStatus;
use App\Exceptions\InvalidOrderStateException;
use App\Repositories\OrderRepository;
use App\Services\{NotificationService, OrderService};
use PHPUnit\Framework\Attributes\{DataProvider, Test};
use PHPUnit\Framework\TestCase;

final class OrderServiceTest extends TestCase
{
    #[Test]
    public function it_completes_a_processing_order_and_notifies_once(): void
    {
        $order = new Order(123, OrderStatus::Processing);
        $orders = $this->createMock(OrderRepository::class);
        $orders->expects($this->once())->method('find')->with(123)->willReturn($order);
        $orders->expects($this->once())->method('save')->with($order);
        $notifications = $this->createMock(NotificationService::class);
        $notifications->expects($this->once())->method('sendOrderCompleted')->with($order);

        $result = (new OrderService($orders, $notifications))->completeOrder(123);

        $this->assertSame(OrderStatus::Completed, $result->status);
    }

    #[Test]
    #[DataProvider('nonCompletableStatuses')]
    public function it_refuses_to_complete_from(OrderStatus $status): void
    {
        $orders = $this->createStub(OrderRepository::class);
        $orders->method('find')->willReturn(new Order(123, $status));
        $notifications = $this->createMock(NotificationService::class);
        $notifications->expects($this->never())->method('sendOrderCompleted');

        $this->expectException(InvalidOrderStateException::class);
        (new OrderService($orders, $notifications))->completeOrder(123);
    }

    public static function nonCompletableStatuses(): array
    {
        return [
            'completed' => [OrderStatus::Completed],
            'cancelled' => [OrderStatus::Cancelled],
            'refunded' => [OrderStatus::Refunded],
        ];
    }
}

Testy mutacyjne odpowiadają na to pytanie wprost. Infection zmienia twój kod (odwraca warunek, usuwa wywołanie) i ponownie uruchamia testy; mutant, który przeżyje, to błąd, którego twoje testy nie złapią. Potrzebuje sterownika pokrycia (PCOV lub Xdebug). Uruchom go na liniach zmienionych przez agenta:

vendor/bin/infection --git-diff-filter=AM --git-diff-base=origin/main --min-msi=80 --threads=max

Prompt do skopiowania: zabij ocalałe mutanty

Run vendor/bin/infection --git-diff-filter=AM --git-diff-base=origin/main --threads=max --show-mutations=max. For each escaped mutant, explain which behaviour it changes and add or strengthen a test in tests/ so the mutant is killed. Do not change any file under app/ and do not delete or weaken an existing assertion. Rerun Infection and report the Mutation Score Indicator before and after.

Tech lead zatwierdza zmiany w testach i próg wyniku mutacyjnego, a nie każdą linię implementacji. Jak dobrać ten próg, opisuje strona siła wyroczni.

Co się zmienia w Symfony?

Receptury się przenoszą, zmieniają się prymitywy. Symfony 8.1 wymaga PHP 8.4.1, a 7.4 to gałąź długoterminowego wsparcia dla zespołów, które nie nadążają za wydaniami co pół roku. Generuj kod przez php bin/console make:* (z symfony/maker-bundle) zamiast pisać go ręcznie, a migracje generuj z różnicy encji przez php bin/console doctrine:migrations:diff, zamiast pozwalać agentowi pisać SQL. Leniwe ładowanie w Doctrine nie rzuca wyjątku tak jak ścisły Eloquent, więc test liczby zapytań jest twoją jedyną bramką na N+1. Sprawdzaj ją w teście funkcjonalnym przez kolektor Doctrine w profilerze:

tests/Controller/ProductIndexTest.php

use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;

final class ProductIndexTest extends WebTestCase
{
    public function testListQueryCountStaysFlat(): void
    {
        $client = static::createClient();
        // Seed 40+ products here with your fixtures or factories.
        $client->enableProfiler();
        $client->request('GET', '/api/products');

        self::assertResponseIsSuccessful();
        $profile = $client->getProfile();
        self::assertNotFalse($profile, 'The profiler is not enabled in the test environment.');
        self::assertLessThanOrEqual(3, $profile->getCollector('db')->getQueryCount());
    }
}

getProfile() zwraca false, jeśli profiler nie jest włączony w środowisku test; recepta symfony/web-profiler-bundle ustawia tam framework.profiler.collect: false, a enableProfiler() włącza zbieranie danych tylko dla następnego żądania. Granicę (tu 3) wyznacz, mierząc endpoint przy kilku wierszach, potem utwórz ich znacznie więcej i zostaw asercję bez zmian. Testy uruchamia się przez vendor/bin/phpunit, więc wstaw to polecenie do hooka Stop i joba CI zamiast php artisan test.

Co się psuje, gdy agenci piszą PHP?

Typowe awarie i wyjście z nich

Composer nie rozwiązuje zależności po podbiciu PHPUnit. Objaw: phpunit/phpunit 13.x requires php >=8.4.1 na maszynie z PHP 8.3. Wyjście: wróć do ^12.5 albo podnieś "php" do ^8.4 w composer.json i jednocześnie php-version w CI.

Liczba testów spadła i nikt tego nie zauważył. Przyczyna: agent napisał metody z /** @test */ bez prefiksu test, które PHPUnit 12 i nowsze pomijają. Wyjście: każ agentowi zamienić wszystkie adnotacje na atrybuty i porównuj liczbę testów przed każdą zmianą i po niej.

Trait "Prophecy\PhpUnit\ProphecyTrait" not found. Wyjście: przepisz na createMock() albo dodaj phpspec/prophecy-phpunit do require-dev, jeśli zespół chce Prophecy.

LazyLoadingViolationException w testach po włączeniu trybu ścisłego. To tryb ścisły, który działa. Wyjście: eager loading w zapytaniu serwisu, a nie load() wewnątrz resource’a.

Brakuje migracji od agenta. Objaw: no such table w testach funkcjonalnych. Wyjście: generuj przez php artisan make:model Product --migration --factory i zostaw RefreshDatabase w testach funkcjonalnych, żeby luka wychodziła na jaw lokalnie.

Wielkość liter w PSR-4 działa na Macu i psuje się w CI. Agent pisze App\services\OrderService w app/Services/. Systemy plików macOS domyślnie nie rozróżniają wielkości liter, Linux tak. Wyjście: composer dump-autoload --optimize --strict-psr kończy się błędem przy takiej niezgodności, więc dodaj go do bramki.

SQL injection przetrwało modernizację. Przyczyna: zapytanie zbudowano linię wcześniej albo przez konkatenację, czego grep nie widzi. Wyjście: przy każdej zmianie w legacy uruchamiaj w CI analizę taint Psalma albo regułę Semgrep, grep zostaw jako szybki test lokalny i odrzucaj każde prepare(), którego napis zawiera $.

Agent nie ma narzędzi Boosta na stagingu ani na hostach zbliżonych do produkcji. Boost nie startuje, gdy APP_ENV ma wartość inną niż local, a APP_DEBUG=false. Job CI, który kopiuje .env.example ze szkieletu (jak ten powyżej), dostaje APP_ENV=local, więc Boost może tam wystartować. Wyjście: nic nie naprawiaj; pracę zależną od schematu wykonuj lokalnie.

composer install pada wewnątrz codex exec. Sandbox workspace-write domyślnie nie ma sieci. Wyjście: instaluj przed sesją, a sieć włączaj tylko na jedno uruchomienie, gdy zadaniem jest dodanie pakietu.

Dokąd dalej z PHP i agentami

Wzorce tworzenia API Kontrakty, wersjonowanie i kształty błędów dla endpointów REST z tej strony

Serwery MCP dla baz danych Dostęp agenta do prawdziwego schematu tylko do odczytu w Symfony i innych stosach

Testy charakteryzujące Przypnij zachowanie legacy, zanim agent zacznie je refaktoryzować

Przepływy testów jednostkowych Testy jednostkowe od agenta, które padają, gdy kod jest błędny