Gyorsítótárazott AST-keresés

A gyorsítótárazott AST-keresés a tényindex kiegészítő, bemelegített gyorsítótáras módja. A kinyert tények tárolása és az egyező fájlok újraelemzése helyett a gyorsítótár sorosított, elemzett fákat tárol a lemezen. A következő lekérdezések deszerializálják a fákat, és közvetlenül futtatják az egyeztetőt, így a PHP-Parser folyamat teljes egészében kimarad.

A gyorsítótár a greph-index ast-cache CLI alparancs és a Greph::buildAstCache() / Greph::searchAstCached() homlokzatmetódusok alatt érhető el. Több indexben végzett keresést és jegyzék által kezelt készletkeresést is támogat.

A gyorsítótár létrehozása

# Full build at the current directory
./vendor/bin/greph-index ast-cache build .

# Use a non-default cache directory
./vendor/bin/greph-index ast-cache build . --index-dir /tmp/greph-ast-cache

# Build a cache that may refresh automatically for small changes
./vendor/bin/greph-index ast-cache build . \
  --lifecycle opportunistic-refresh \
  --auto-refresh-max-files 32 \
  --auto-refresh-max-bytes 1048576

A gyorsítótár alapértelmezés szerint itt tárolódik: <root>/.greph-ast-cache/. A gyorsítótár felépítése jellemzően a három indexmód közül a leglassabb, mert minden fájlt egyszer elemezni kell.

A sikeres létrehozás egyetlen soros összefoglalót ír ki:

Built AST cache for 2547 files in .greph-ast-cache (2541 cached trees, +2541 ~0 -0 =0)

A gyorsítótárazott fák száma általában valamivel kisebb a fájlok számánál, mert az elemzési hibát okozó, csendben kihagyott fájlokhoz nem jön létre gyorsítótár-bejegyzés. Ha azt szeretné, hogy az elemzési hibák megjelenjenek, adja meg a --strict-parse kapcsolót a keresési parancsnál.

A gyorsítótár frissítése

./vendor/bin/greph-index ast-cache refresh .

A refresh újra bejárja az indexelt gyökérkönyvtárat, újraelemzi a módosult fájlokat, és csak az áthelyezett gyorsítótárazott fákat írja újra.

Az életciklus-profilok megegyeznek a többi bemelegített módéval:

• static: soha nem ellenőrzi automatikusan az aktualitást, és nem módosít automatikusan
• manual-refresh: jelzi az elavult állapotot a stats kimenetében, de keresés közben soha nem frissít
• opportunistic-refresh: keresés közben csak akkor frissít, ha a módosult fájlok száma a beállított küszöb alatt van
• strict-stale-check: frissítés helyett elutasítja az elavult gyorsítótárral végzett kereséseket

Lekérdezés a gyorsítótárban

./vendor/bin/greph-index ast-cache search 'new $CLASS()' src
./vendor/bin/greph-index ast-cache search '$obj->$method($$$ARGS)' src
./vendor/bin/greph-index ast-cache search --json 'array($$$ITEMS)' src
./vendor/bin/greph-index ast-cache search --fallback scan 'new $CLASS()' src
./vendor/bin/greph-index ast-cache search --trace-plan 'array($$$ITEMS)' src

A kapcsolókészlet megegyezik a ast-index search kapcsolóival, beleértve a hiányzó gyorsítótárakhoz tartozó --fallback scan kapcsolót is.

Keresés több gyorsítótárban

A --index-dir ismételt megadásával egy hívásban több bemelegített gyorsítótárban is kereshet:

./vendor/bin/greph-index ast-cache search \
  --index-dir ../wordpress/.greph-ast-cache \
  --index-dir ./.greph-ast-cache \
  --show-index-origin \
  'array($$$ITEMS)' .

Jegyzék által kezelt gyorsítótár-készletek

Ha már használ elnevezett, bemelegített készleteket, ugyanaz a jegyzék a gyorsítótárazott AST-keresést is vezérelheti:

./vendor/bin/greph-index set build --mode ast-cache
./vendor/bin/greph-index set stats --mode ast-cache --dry-refresh
./vendor/bin/greph-index set search --mode ast-cache --show-index-origin 'array($$$ITEMS)' .

Tervezői diagnosztika

A --trace-plan a gyorsítótárazott AST tervezői döntéseit a stderr fájlba írja, többek között a következőket:

• mely bemelegített gyorsítótárakban történt keresés
• lefutott-e az elavultságot kezelő frissítési logika
• a fájlszintű szűkítés utáni jelöltfájl-számok
• a pontos strukturális egyezéshez deszerializált gyorsítótárazott fák száma

Gyorsítótár és tényindex

Mindkét mód gyorsítja az AST-keresést, de eltérő munkafolyamatokra van optimalizálva.

A gyakorlatban a tényindex teszi lehetővé a leggyorsabb hideg lekérdezést, a gyorsítótár pedig a leggyorsabb bemelegített lekérdezést. Válassza azt, amelyik illik a munkaterheléséhez, vagy építse fel mindkettőt, és hagyja, hogy az eszköz kiválassza a megfelelőt.

Programozott használat

use Greph\Greph;
use Greph\Ast\AstSearchOptions;
use Greph\Index\IndexLifecycleProfile;

Greph::buildAstCache('.', lifecycle: IndexLifecycleProfile::Static);

$matches = Greph::searchAstCached(
    'array($$$ITEMS)',
    'src',
    new AstSearchOptions(jobs: 4, tracePlan: true),
);

A searchAstCached ugyanazt a AstSearchOptions fogadja el, mint a natív AST-keresés, és ugyanolyan alakú list<AstMatch> eredményt ad vissza. Csak annyi a különbség, hogy a már gyorsítótárazott fájloknál kimarad az elemzési folyamat. Több indexet vagy jegyzékfájlt használó munkafolyamatokhoz használja a searchAstCachedMany(...) és a searchAstCachedSet(...) lehetőséget.

Mikor használja

A gyorsítótárazott AST-mód a megfelelő eszköz, ha:

• Ugyanazon a kódbázison ismételten futtat strukturális lekérdezéseket.
• A korábbi futások szűk keresztmetszete a PHP-Parser volt (a profilokban a lexerrel és az elemzővel töltött idő látható).
• Rendelkezésére áll a szerializált fához szükséges lemezterület.

Ha a lekérdezései általában a kódbázis kis részét érintik, és a találatok felismerhető hívásnevek vagy osztálynevek köré csoportosulnak, a tényindex általában jobb választás. Ha a lekérdezések a kódbázis nagy részét érintik, és belefér az egyszeri elemzés költsége, a gyorsítótár a jobb.