انتقل إلى المحتوى

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 الملتقط والالتقاطات وإزاحات بايتات وسطور البداية والنهاية ومقطع المصدر المطابق.

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);
    }
}

لا تكتب الواجهة إلى القرص؛ فالمتصل هو من يقرر تطبيق التغييرات. ويطبقها 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.

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 المُحمّل عبر عدة مجلدات للتخزين المؤقت.

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 لإظهار أخطاء التحليل كاستثناءات. يستخدم الباحثون المُحمّلون في AST tracePlan، كما تستخدمه 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 لالتقاط هذه الاستثناءات والرجوع إلى فحص غير مفهرس.