# مقدمة
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` عند توفره، وتعود بسلاسة إلى التنفيذ في عملية واحدة عند غيابه. ويتناول قسم [المضيفون المقيّدون بالعمليات](https://greph.inline0.dev/ar/docs/advanced/process-restricted-hosts) المضيفين الذين يحظرون `proc_open()` و`shell_exec()`.

## مثال سريع

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

```bash
# 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
```

```php
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',
);
```

ابدأ بقسم [البدء](https://greph.inline0.dev/ar/docs/getting-started)، ثم راجع [CLI](https://greph.inline0.dev/ar/docs/cli) و[API](https://greph.inline0.dev/ar/docs/api) للتعرّف على بقية الإمكانات. وتشرح أقسام [الأوضاع](https://greph.inline0.dev/ar/docs/modes/text) و[المفهرس](https://greph.inline0.dev/ar/docs/indexed/text) و[التوافق](https://greph.inline0.dev/ar/docs/compatibility/rg) مسارات عمل محددة بالتفصيل.