مقدمة

Greph محرك بحث وإعادة هيكلة خالص بـ PHP لأشجار المصدر. ويشمل ثلاثة أوضاع مترابطة:

• البحث النصي بإخراج متوافق مع grep وسهولة استخدام على غرار ripgrep.
• بحث AST بأنماط بنيوية PHP ومتغيرات وصفية.
• إعادة كتابة AST لإعادة هيكلة بنيوية تحافظ على التنسيق.

كما يتضمن أوضاعًا مفهرسة مُحمّاة لأحمال العمل النصية وAST، وسياسات تحديث تراعي دورة الحياة، ومجموعات فهارس مُحمّاة مدعومة بالبيانات الوصفية، وأغلفة توافق rg / sg لبيئات الأدوات والوكلاء.

لماذا أُنشئ Greph

تلجأ تطبيقات PHP والوكلاء الذين يحتاجون إلى بحث سريع في الأكواد عادةً إلى أدوات أصلية عبر الصدفة (grep وripgrep وast-grep)، ما يقلل قابلية النقل ويزيد تعقيدات النشر. أما البحث البنيوي وإعادة الكتابة فأسوأ؛ إذ يتطلبان عادةً الخروج تمامًا من عملية PHP.

يسد Greph هذه الفجوة. يمكن لأكواد PHP إجراء عمليات البحث النصي والمطابقة البنيوية وإعادة الهيكلة باستخدام المكتبة القياسية وحدها، إضافةً إلى nikic/php-parser. ويتوافق الإخراج ورموز الخروج مع الأدوات القياسية، لذا لا تحتاج السكربتات والوكلاء الحاليون إلى التغيير.

ما الذي يقدمه

• البحث عن النصوص الثابتة والتعبيرات النمطية، مع أوضاع للكلمات كاملة، وعدم التمييز بين حالة الأحرف، والسياق، والعدد، والملفات فقط
• بحث AST بنيوي PHP باستخدام $VAR و$$$VARIADIC والمتغيرات الوصفية المتكررة
• إعادة كتابة AST تحافظ على التنسيق، مع أوضاع التشغيل التجريبي والتفاعلي والكتابة
• فهارس نصية مُحمّاة (ثلاثيات + قوائم ترابطات المعرّفات) لأحمال العمل المتكررة
• فهرس حقائق AST مُحمّى وبحث AST مخزّن مؤقتًا للاستعلامات البنيوية المتكررة
• فهارس مُحمّاة تراعي دورة الحياة: static وmanual-refresh وopportunistic-refresh وstrict-stale-check
• بحث متعدد الفهارس وبمجموعات مسماة عبر مخازن النص المُحمّى وحقائق AST وذاكرة AST المؤقتة
• تشخيصات المخطِّط باستخدام --trace-plan وتسميات مصدر الفهرس لعمليات البحث المُحمّاة
• أغلفة توافق ripgrep وast-grep CLI مدعومة بالمحرك نفسه
• مجموعة عمليات عاملة متوازية قائمة على pcntl مع خيار الرجوع إلى عملية واحدة
• أداة لاجتياز الملفات تراعي gitignore و.grephignore وتكشف الملفات الثنائية

المتطلبات

• PHP 8.2 أو أحدث
• ext-json وext-ctype وext-tokenizer، وهي مفعّلة في جميع إصدارات PHP تقريبًا
• ext-zlib لمخزن AST المؤقت (greph-index ast-cache)
• nikic/php-parser (اعتماد Composer الوحيد)

تعمل ميزات النص وAST الأساسية باستخدام PHP فقط. وتعتمد مقارنات الأداء الاختيارية على أدوات خارجية مثل rg وgrep وsg، لكن Greph نفسه لا يحتاج إليها. تستخدم عمليات المسح المتوازية ext-pcntl عند توفره، وتعود بسلاسة إلى التنفيذ في عملية واحدة عند غيابه. ويتناول قسم المضيفون المقيّدون بالعمليات المضيفين الذين يحظرون proc_open() وshell_exec().

مثال سريع

تحتاج الملفات التنفيذية لـ vendor/bin إلى Greph 0.2.3 أو أحدث عندما يُثبّت Greph باعتباره اعتمادًا لمشروعك.

# Text search
vendor/bin/greph -F "function" src

# Structural search
vendor/bin/greph -p 'new $CLASS()' src

# Structural rewrite preview
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src

use Greph\Greph;
use Greph\Ast\AstSearchOptions;
use Greph\Text\TextSearchOptions;

$matches = Greph::searchText(
    'function',
    'src',
    new TextSearchOptions(fixedString: true),
);

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

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

ابدأ بقسم البدء، ثم راجع CLI وAPI للتعرّف على بقية الإمكانات. وتشرح أقسام الأوضاع والمفهرس والتوافق مسارات عمل محددة بالتفصيل.