PHP API

Προβολή ως Markdown Επεξεργασία στο GitHub Τεκμηρίωση στο d105217

`Greph\Greph`

Η κλάση Greph\Greph είναι το στατικό σημείο εισόδου. Παρέχει όλες τις λειτουργίες αναζήτησης, επανεγγραφής και δημιουργίας ευρετηρίου. Όλες οι μέθοδοι δέχονται μία διαδρομή ή μια λίστα διαδρομών.

PHP

use Greph\Greph;

`walk`

PHP

public static function walk(string|array $paths, ?WalkOptions $options = null): FileList

Επιλύει το $paths σε μια επίπεδη λίστα FileList από απόλυτες διαδρομές αρχείων. Τηρεί τα gitignore, .grephignore, τα φίλτρα τύπων αρχείων, τα μοτίβα glob, τη συμπερίληψη κρυφών αρχείων, την παρακολούθηση συμβολικών συνδέσμων, τον εντοπισμό δυαδικών αρχείων και το ανώτατο όριο μεγέθους αρχείου.

PHP

use Greph\Walker\WalkOptions;
use Greph\Walker\FileTypeFilter;

$files = Greph::walk('src', new WalkOptions(
    fileTypeFilter: new FileTypeFilter(['php']),
));

foreach ($files->paths() as $path) {
    echo "$path\n";
}

`searchText`

PHP

public static function searchText(
    string $pattern,
    string|array $paths,
    ?TextSearchOptions $options = null,
): array

Εκτελεί αναζήτηση κειμένου και επιστρέφει ένα list<TextFileResult>. Κάθε TextFileResult παρέχει τη διαδρομή του αρχείου και μια λίστα αντικειμένων TextMatch (γραμμή, στήλη, περιεχόμενο, καταγραφές και προαιρετικό περιβάλλον).

PHP

use Greph\Greph;
use Greph\Text\TextSearchOptions;

$results = Greph::searchText(
    'function',
    'src',
    new TextSearchOptions(
        fixedString: true,
        caseInsensitive: true,
        beforeContext: 1,
        afterContext: 1,
        jobs: 4,
    ),
);

foreach ($results as $file) {
    foreach ($file->matches as $match) {
        echo "{$file->file}:{$match->line}:{$match->content}\n";
    }
}

Όταν ισχύει το jobs > 1 και ο αριθμός αρχείων ξεπερνά το όριο εργαζομένων, το searchText αναθέτει αυτόματα τη σάρωση σε ένα WorkerPool. Διαφορετικά, εκτελείται εντός της ίδιας διεργασίας.

`searchAst`

PHP

public static function searchAst(
    string $pattern,
    string|array $paths,
    ?AstSearchOptions $options = null,
): array

Εκτελεί δομική αναζήτηση AST και επιστρέφει ένα list<AstMatch>. Τα μοτίβα γράφονται ως πηγαίος κώδικας PHP με μεταβλητές μεταδεδομένων $VAR και $$$VARIADIC. Κάθε AstMatch περιλαμβάνει το αρχείο, το καταγεγραμμένο PhpParser\Node, τις καταγραφές, τις γραμμές και μετατοπίσεις byte αρχής και τέλους, καθώς και το τμήμα πηγαίου κώδικα που αντιστοιχίστηκε.

PHP

use Greph\Greph;
use Greph\Ast\AstSearchOptions;

$matches = Greph::searchAst(
    'new $CLASS()',
    'src',
    new AstSearchOptions(),
);

foreach ($matches as $match) {
    echo "{$match->file}:{$match->startLine}:{$match->code}\n";
}

`rewriteAst`

PHP

public static function rewriteAst(
    string $searchPattern,
    string $rewritePattern,
    string|array $paths,
    ?AstSearchOptions $options = null,
): array

Εκτελεί δομική επανεγγραφή και επιστρέφει ένα list<RewriteResult>. Κάθε RewriteResult παρέχει τη διαδρομή του αρχείου, το αρχικό περιεχόμενο, το περιεχόμενο μετά την επανεγγραφή και τον αριθμό αντικαταστάσεων. Οι επανεγγραφές διατηρούν τη μορφοποίηση: αντικαθίστανται μόνο οι περιοχές των κόμβων που αντιστοιχίστηκαν· το υπόλοιπο αρχείο μένει ανέπαφο.

PHP

$rewrites = Greph::rewriteAst(
    'array($$$ITEMS)',
    '[$$$ITEMS]',
    'src',
);

foreach ($rewrites as $result) {
    if ($result->changed()) {
        file_put_contents($result->file, $result->rewrittenContents);
    }
}

Το facade δεν γράφει στον δίσκο· ο καλών αποφασίζει αν θα εφαρμόσει τις αλλαγές. Το CLI τις εφαρμόζει, εκτός αν έχει οριστεί το --dry-run ή το --interactive.

Αναζήτηση σε ευρετηριασμένο κείμενο

`buildTextIndex`

PHP

public static function buildTextIndex(
    string $rootPath = '.',
    ?string $indexPath = null,
    IndexLifecycle|IndexLifecycleProfile|string|null $lifecycle = null,
): IndexBuildResult

Δημιουργεί νέο ευρετήριο τριγραμμάτων και εμφανίσεων αναγνωριστικών για το $rootPath. Το ευρετήριο αποθηκεύεται στο $indexPath (προεπιλογή: $rootPath/.greph-index). Το $lifecycle μπορεί να είναι static, manual-refresh, opportunistic-refresh ή strict-stale-check. Επιστρέφει ένα IndexBuildResult με τον αριθμό αρχείων, τον αριθμό τριγραμμάτων και τους αριθμούς προσθηκών/ενημερώσεων/διαγραφών/αμετάβλητων στοιχείων.

`refreshTextIndex`

PHP

public static function refreshTextIndex(
    string $rootPath = '.',
    ?string $indexPath = null,
    IndexLifecycle|IndexLifecycleProfile|string|null $lifecycle = null,
): IndexBuildResult

Ενημερώνει σταδιακά ένα υπάρχον ευρετήριο κειμένου. Τα αρχεία κατακερματίζονται ξανά και επανεγγράφονται μόνο οι καταχωρίσεις που έχουν αλλάξει.

`searchTextIndexed`

PHP

public static function searchTextIndexed(
    string $pattern,
    string|array $paths,
    ?TextSearchOptions $options = null,
    ?string $indexPath = null,
): array

Εκτελεί αναζήτηση κειμένου στο ήδη φορτωμένο ευρετήριο. Επιστρέφει σφάλμα χρόνου εκτέλεσης αν το ευρετήριο δεν υπάρχει (καλέστε πρώτα το buildTextIndex). Επιστρέφει ένα list<TextFileResult> με ακριβώς την ίδια δομή όπως το searchText.

PHP

Greph::buildTextIndex('.');
$results = Greph::searchTextIndexed('function', 'src');

`searchTextIndexedMany`

PHP

public static function searchTextIndexedMany(
    string $pattern,
    string|array $paths,
    array $indexPaths,
    ?TextSearchOptions $options = null,
): array

Εκτελεί αναζήτηση κειμένου σε ήδη φορτωμένα ευρετήρια σε αρκετούς καταλόγους. Το Greph αναζητά σε κάθε σχετικό ευρετήριο, αφαιρεί διπλότυπα με βάση την απόλυτη διαδρομή αρχείου και χρησιμοποιεί εγγενή σάρωση μόνο για διαδρομές εκτός όλων των δοσμένων ριζών ευρετηρίου.

`loadIndexSet`

PHP

public static function loadIndexSet(?string $manifestPath = null): IndexSet

Φορτώνει ένα μανιφέστο συνόλου ευρετηρίων, με προεπιλογή το .greph-index-set.json στον τρέχοντα κατάλογο εργασίας.

`searchTextIndexedSet`

PHP

public static function searchTextIndexedSet(
    string $pattern,
    string|array $paths,
    ?TextSearchOptions $options = null,
    ?string $manifestPath = null,
    array $entryNames = [],
): array

Επιλύει τις επιλεγμένες καταχωρίσεις text από ένα μανιφέστο συνόλου ευρετηρίων και εκτελεί την ισοδύναμη λειτουργία του searchTextIndexedMany.

Αναζήτηση AST σε ευρετήριο

`buildAstIndex` / `refreshAstIndex`

PHP

public static function buildAstIndex(
    string $rootPath = '.',
    ?string $indexPath = null,
    IndexLifecycle|IndexLifecycleProfile|string|null $lifecycle = null,
): AstIndexBuildResult
public static function refreshAstIndex(
    string $rootPath = '.',
    ?string $indexPath = null,
    IndexLifecycle|IndexLifecycleProfile|string|null $lifecycle = null,
): AstIndexBuildResult

Δημιουργεί ή ενημερώνει σταδιακά το ευρετήριο γεγονότων AST. Αποθηκεύει τα εξαγόμενα γεγονότα στο $rootPath/.greph-ast-index από προεπιλογή.

`searchAstIndexed`

PHP

public static function searchAstIndexed(
    string $pattern,
    string|array $paths,
    ?AstSearchOptions $options = null,
    ?string $indexPath = null,
): array

Χρησιμοποιεί το ευρετήριο γεγονότων για να περιορίσει τους υποψήφιους πριν επαληθεύσει ξανά τις αντιστοιχίσεις στον πηγαίο κώδικα. Επιστρέφει δομή list<AstMatch> ίδια με εκείνη του searchAst.

`searchAstIndexedMany`

PHP

public static function searchAstIndexedMany(
    string $pattern,
    string|array $paths,
    array $indexPaths,
    ?AstSearchOptions $options = null,
): array

Εκτελεί αναζήτηση γεγονότων AST σε ήδη φορτωμένα ευρετήρια σε αρκετούς καταλόγους AST.

`searchAstIndexedSet`

PHP

public static function searchAstIndexedSet(
    string $pattern,
    string|array $paths,
    ?AstSearchOptions $options = null,
    ?string $manifestPath = null,
    array $entryNames = [],
): array

Επιλύει τις επιλεγμένες καταχωρίσεις ast-index από ένα μανιφέστο συνόλου ευρετηρίων και εκτελεί την ισοδύναμη λειτουργία του searchAstIndexedMany.

`buildAstCache` / `refreshAstCache`

PHP

public static function buildAstCache(
    string $rootPath = '.',
    ?string $indexPath = null,
    IndexLifecycle|IndexLifecycleProfile|string|null $lifecycle = null,
): AstCacheBuildResult
public static function refreshAstCache(
    string $rootPath = '.',
    ?string $indexPath = null,
    IndexLifecycle|IndexLifecycleProfile|string|null $lifecycle = null,
): AstCacheBuildResult

Δημιουργεί ή ενημερώνει σταδιακά την αποθηκευμένη συλλογή αναλυμένων δέντρων. Αποθηκεύει σειριοποιημένα δέντρα στο $rootPath/.greph-ast-cache από προεπιλογή.

`searchAstCached`

PHP

public static function searchAstCached(
    string $pattern,
    string|array $paths,
    ?AstSearchOptions $options = null,
    ?string $indexPath = null,
): array

Εκτελεί αναζήτηση AST στα αποθηκευμένα αναλυμένα δέντρα, παραλείποντας εντελώς τον αναλυτή. Επιστρέφει δομή list<AstMatch> ίδια με εκείνη του searchAst.

`searchAstCachedMany`

PHP

public static function searchAstCachedMany(
    string $pattern,
    string|array $paths,
    array $indexPaths,
    ?AstSearchOptions $options = null,
): array

Εκτελεί αναζήτηση AST σε αποθηκευμένη μνήμη cache σε αρκετούς καταλόγους cache.

`searchAstCachedSet`

PHP

public static function searchAstCachedSet(
    string $pattern,
    string|array $paths,
    ?AstSearchOptions $options = null,
    ?string $manifestPath = null,
    array $entryNames = [],
): array

Επιλύει τις επιλεγμένες καταχωρίσεις ast-cache από ένα μανιφέστο συνόλου ευρετηρίων και εκτελεί την ισοδύναμη λειτουργία του searchAstCachedMany.

`Greph\Text\TextSearchOptions`

Αμετάβλητο αντικείμενο επιλογών για αναζήτηση κειμένου.

PHP

new TextSearchOptions(
    bool $fixedString = false,
    bool $caseInsensitive = false,
    bool $wholeWord = false,
    bool $invertMatch = false,
    ?int $maxCount = null,
    int $beforeContext = 0,
    int $afterContext = 0,
    bool $countOnly = false,
    bool $filesWithMatches = false,
    bool $filesWithoutMatches = false,
    bool $jsonOutput = false,
    bool $tracePlan = false,
    int $jobs = 1,
    bool $respectIgnore = true,
    bool $includeHidden = false,
    bool $followSymlinks = false,
    bool $skipBinaryFiles = true,
    bool $includeGitDirectory = false,
    ?FileTypeFilter $fileTypeFilter = null,
    int $maxFileSizeBytes = 10485760,
    array $globPatterns = [],
    bool $showLineNumbers = true,
    bool $showFileNames = true,
)

Επικύρωση:

jobs >= 1
beforeContext, afterContext >= 0
maxCount === null || maxCount >= 1

Χρησιμοποιήστε το walkOptions() για να παράγετε το αντίστοιχο WalkOptions, αν θέλετε να περιηγηθείτε ξεχωριστά στο δέντρο αρχείων.

Το tracePlan χρησιμοποιείται από μηχανές αναζήτησης σε ήδη φορτωμένα ευρετήρια και οι ροές greph-index CLI για την παραγωγή διαγνωστικών του σχεδιαστή στο stderr. Η εγγενής λειτουργία searchText δεν το χρησιμοποιεί.

`Greph\Ast\AstSearchOptions`

Αμετάβλητο αντικείμενο επιλογών για αναζήτηση και επανεγγραφή AST.

PHP

new AstSearchOptions(
    string $language = 'php',
    int $jobs = 1,
    bool $respectIgnore = true,
    bool $includeHidden = false,
    bool $followSymlinks = false,
    bool $skipBinaryFiles = true,
    bool $includeGitDirectory = false,
    ?FileTypeFilter $fileTypeFilter = null,
    int $maxFileSizeBytes = 10485760,
    array $globPatterns = [],
    bool $skipParseErrors = true,
    bool $dryRun = false,
    bool $interactive = false,
    bool $jsonOutput = false,
    bool $tracePlan = false,
)

Το προεπιλεγμένο φίλτρο τύπων αρχείων για τη λειτουργία AST είναι php. Όταν το skipParseErrors είναι true (προεπιλογή), τα αρχεία που δεν αναλύονται παραλείπονται σιωπηρά· αλλάξτε το σε false για να εμφανίζονται τα σφάλματα ανάλυσης ως εξαιρέσεις. Το tracePlan χρησιμοποιείται από μηχανές αναζήτησης AST σε ήδη φορτωμένα ευρετήρια και το greph-index ast-index|ast-cache search για την παραγωγή διαγνωστικών περιορισμού υποψήφιων.

`Greph\Walker\WalkOptions`

Αμετάβλητο αντικείμενο επιλογών για τον περιηγητή αρχείων.

PHP

new WalkOptions(
    bool $respectIgnore = true,
    bool $includeHidden = false,
    bool $followSymlinks = false,
    bool $skipBinaryFiles = false,
    bool $includeGitDirectory = false,
    ?FileTypeFilter $fileTypeFilter = null,
    int $maxFileSizeBytes = 10485760,
    array $globPatterns = [],
)

`Greph\Walker\FileTypeFilter`

Επιλύει ονομασμένους τύπους αρχείων σε λίστες επεκτάσεων. Ενσωματωμένα ψευδώνυμα:

Ψευδώνυμο	Επεκτάσεις
`css`	`css`, `sass`, `scss`
`html`	`htm`, `html`, `phtml`
`js`	`cjs`, `js`, `mjs`
`json`	`json`
`md`	`markdown`, `md`
`php`	`inc`, `php`, `php3`, `php4`, `php5`, `php7`, `php8`, `phpt`, `phtml`
`txt`	`txt`
`ts`	`ts`, `tsx`
`xml`	`xml`
`yaml`	`yaml`, `yml`

PHP

new FileTypeFilter(includeTypes: ['php'], excludeTypes: ['md']);

Αντικείμενα αποτελεσμάτων

`Greph\Text\TextFileResult`

PHP

final readonly class TextFileResult
{
    public string $file;
    /** @var list<TextMatch> */
    public array $matches;

    public function matchCount(): int;
    public function hasMatches(): bool;
}

`Greph\Text\TextMatch`

PHP

final readonly class TextMatch
{
    public string $file;
    public int $line;
    public int $column;
    public string $content;
    public string $matchedText;
    /** @var array<int|string, string> */
    public array $captures;
    /** @var list<array{line: int, content: string}> */
    public array $beforeContext;
    /** @var list<array{line: int, content: string}> */
    public array $afterContext;
}

`Greph\Ast\AstMatch`

PHP

final readonly class AstMatch
{
    public string $file;
    public PhpParser\Node $node;
    /** @var array<string, mixed> */
    public array $captures;
    public int $startLine;
    public int $endLine;
    public int $startFilePos;
    public int $endFilePos;
    public string $code;
}

`Greph\Ast\RewriteResult`

PHP

final readonly class RewriteResult
{
    public string $file;
    public string $originalContents;
    public string $rewrittenContents;
    public int $replacementCount;

    public function changed(): bool;
}

`Greph\Index\IndexBuildResult`

PHP

final readonly class IndexBuildResult
{
    public string $rootPath;
    public string $indexPath;
    public int $fileCount;
    public int $trigramCount;
    public int $addedFiles;
    public int $updatedFiles;
    public int $deletedFiles;
    public int $unchangedFiles;
}

Τα AstIndexBuildResult και AstCacheBuildResult ακολουθούν την ίδια μορφή, με τα factCount και cachedTreeCount να αντικαθίστανται αντίστοιχα.

Εξαιρέσεις

Το Greph προκαλεί τρεις τυποποιημένες εξαιρέσεις, όλες στο Greph\Exceptions:

Εξαίρεση	Πότε προκαλείται
`WalkerException`	Σφάλματα συστήματος αρχείων κατά τη διάσχιση (διαδρομή που λείπει, κατάλογος χωρίς δικαίωμα ανάγνωσης)
`PatternException`	Μη έγκυρη κανονική έκφραση ή μοτίβο AST
`ParseException`	Δεν ήταν δυνατή η ανάλυση του πηγαίου κώδικα PHP (μόνο όταν ισχύει το `skipParseErrors: false`)

Οι μέθοδοι αναζήτησης με ευρετήριο προκαλούν \RuntimeException όταν δεν υπάρχει ευρετήριο στην τοποθεσία που ζητήθηκε. Το greph-index CLI παρέχει μια επιλογή --fallback scan που παγιδεύει αυτές τις εξαιρέσεις και, αντί γι' αυτό, εκτελεί σάρωση χωρίς ευρετήριο.

PHP API

Greph\Greph

walk

searchText

searchAst

rewriteAst

Αναζήτηση σε ευρετηριασμένο κείμενο

buildTextIndex

refreshTextIndex

searchTextIndexed

searchTextIndexedMany

loadIndexSet

searchTextIndexedSet

Αναζήτηση AST σε ευρετήριο

buildAstIndex / refreshAstIndex

searchAstIndexed

searchAstIndexedMany

searchAstIndexedSet

buildAstCache / refreshAstCache

searchAstCached

searchAstCachedMany

searchAstCachedSet

Greph\Text\TextSearchOptions

Greph\Ast\AstSearchOptions

Greph\Walker\WalkOptions

Greph\Walker\FileTypeFilter