---
title: 'الترقية من الإصدار 2'
description: 'انقل موقع LaRecipe 2 إلى LaRecipe 3 بأمر واحد وتقرير، ثم أكمل البنود اليدوية مع وكيل البرمجة والمهارة larecipe-upgrade-v2.'
url: 'https://larecipe.saleem.dev/ar/3.x/upgrade'
version: 3.x
locale: ar
last_updated: '2026-10-19'
---
> Docs index: https://larecipe.saleem.dev/3.x/llms.txt · MCP: https://larecipe.saleem.dev/mcp · Skill: https://larecipe.saleem.dev/skill.md
# الترقية من الإصدار 2
يحوّل `php artisan larecipe:upgrade` موقع LaRecipe 2 إلى LaRecipe 3: إعداداتك، والشريط الجانبي لكل إصدار، وكل صفحة. يبدأ بتشغيل تجريبي لا يكتب إلا تقريرًا. وحين تبدو الخطة صحيحة، يكتب `--apply` تلك الخطة بالضبط، ويكمل وكيل البرمجة الباقي بالمهارة `larecipe-upgrade-v2`.
ابدأ من شجرة عمل نظيفة، لتكون الترقية diff واحدًا تستطيع قراءته والتراجع عنه. يحتاج LaRecipe 3 إلى PHP 8.3 و Laravel 12.62 أو أحدث، راجع [التثبيت](https://larecipe.saleem.dev/ar/3.x/get-started/installation.md).
1. **أضف LaRecipe 3**
```bash
composer require larecipe/larecipe
```
تقرأ الترقية ملفات الإصدار 2 لديك، لا حزمة الإصدار 2. فإن كان تطبيقك يستدعي أصناف `BinaryTorch\LaRecipe` أثناء إقلاعه، مثل `LaRecipe::script()` في مزوّد خدمة، فأبقِ `binarytorch/larecipe` مثبّتة حتى تُشغَّل الترقية. وإن لم يستطع Composer تثبيت الحزمتين معًا، فاحذف حزمة الإصدار 2 أولًا وعلّق تلك الاستدعاءات.
2. **اقرأ التشغيل التجريبي**
```bash
php artisan larecipe:upgrade
```
لا يتغيّر شيء في تطبيقك. يكتب الأمر `larecipe-upgrade-report.md` ونسخته بصيغة JSON في جذر مشروعك. شغّله كلما شئت.
3. **طبّقه**
```bash
php artisan larecipe:upgrade --apply --move-to=docs --relative-links
```
الخياران اختياريان. ينقل `--move-to=docs` التوثيق من `resources/docs/` إلى `docs/`، حيث يحفظه الإصدار 3. ويحوّل `--relative-links` روابط `/docs/{{version}}/page` إلى روابط `.md` نسبية، فاستخدمه حين ستتغيّر بادئة المسار لديك.
4. **استبدل الحزمة**
```bash
composer remove binarytorch/larecipe
```
ثم غيّر `BinaryTorch\LaRecipe\` إلى `LaRecipe\` في الكود لديك و[حدّث البوابة (gate) viewLarecipe](https://larecipe.saleem.dev/ar/3.x/upgrade#update-the-viewlarecipe-gate). ويسرد التقرير كل سطر عليك تغييره.
5. **أكمل مع وكيل البرمجة**
ثبّت مهارات LaRecipe، ثم اطلب من وكيلك أن يكمل:
```bash
php artisan larecipe:agents
```
```text
Use the larecipe-upgrade-v2 skill to finish the LaRecipe upgrade.
```
6. **تحقّق من النتيجة**
```bash
php artisan larecipe:validate
```
ثم مرّ على [التحقق بعد الترقية](https://larecipe.saleem.dev/ar/3.x/upgrade#check-after-the-upgrade)، وافتح التوثيق في متصفحك، وأضف التغييرات إلى git.
وقد مرّ هذا الموقع بالترقية نفسها: [توثيق 2.x](https://larecipe.saleem.dev/2.x) فيه هو توثيق LaRecipe 2 بعد تحويله.
## حدّث البوابة viewLarecipe
تحتفظ البوابة باسمها، لكن وسائطها تغيّرت. كان الإصدار 2 يمرّر كائن صفحة التوثيق. أما الإصدار 3 فيمرّر ملخص الصفحة ومفتاح المجموعة:
```php
// LaRecipe 2
Gate::define('viewLarecipe', function ($user, $documentation) {
return $user->isAdmin();
});
```
```php
// LaRecipe 3
use App\Models\User;
use Illuminate\Support\Facades\Gate;
use LaRecipe\Domains\Content\DTOs\PageSummary;
Gate::define('viewLarecipe', function (?User $user, ?PageSummary $page = null, ?string $set = null) {
return $user?->isAdmin() ?? false;
});
```
اجعل نوع المستخدم قابلًا للقيمة الفارغة إن كان ينبغي للزوّار أن يمرّوا في أي وقت: وإلا فإن Laravel يرفض الزوّار قبل أن تعمل الدالة. وفي الإصدار 3 تحرس البوابة كل الواجهات، لا صفحة HTML وحدها. وتشرح صفحة [كتل الصلاحيات والتوثيق الخاص](https://larecipe.saleem.dev/ar/3.x/writing/gate-blocks.md) الوسائط، وأوضاع الوصول، والبوابات الأخرى.
## أكمل بالمهارة larecipe-upgrade-v2
يثبّت `php artisan larecipe:agents` المهارة في `.claude/skills/` و `.agents/skills/`، بجوار مهارات LaRecipe الأخرى، ويكتب تعليمات LaRecipe في `AGENTS.md`. ومع Laravel Boost، شغّل `php artisan boost:update` بدلًا منه.
يقرأ الوكيل التقرير ونسخته بصيغة JSON، ثم يعمل على البنود اليدوية: ما يكسر التصيير أولًا، ثم المحتوى، ثم الشكل.
- **Blade في Markdown** يصبح مكوّنات، أو تضمين مقتطفات (`<<< @/path#region`)، أو نصًا عاديًا. والقيم التي كانت تأتي من الإعدادات تصبح نصًا يسمّي المفتاح، لا القيمة أبدًا.
- **مكوّنات Vue المخصّصة** تصبح مكوّنات React مبنية بـ `@larecipe/vite`، ويُسجَّل كلٌّ منها بـ `LaRecipe::component()`. وإلى أن يُعاد بناء أحدها، يستبدل الوكيل الوسم بـ Markdown عادي. راجع [المكوّنات المخصّصة](https://larecipe.saleem.dev/ar/3.x/customize/custom-components.md).
- **المظاهر و CSS المخصّص** تنتقل إلى رموز المظهر في `larecipe.json` (اللون المميّز، والخطوط، ونصف قطر الحواف)، والباقي يوضع في `theme.css` مُدرج تحت `assets.css`. راجع [المظهر](https://larecipe.saleem.dev/ar/3.x/customize/theme.md#add-your-own-stylesheet).
- **كل صفحة** تحصل على `description`، وعلى `sources:` حيث تشرح كودًا. وروابط المسارات أو تواقيع الأوامر الملصوقة تصبح [مراجع حية](https://larecipe.saleem.dev/ar/3.x/writing/live-references.md).
ينتهي الوكيل حين ينجح `php artisan larecipe:validate`، ويترك لك إضافة التغييرات إلى git، وفق وضع المراجعة في `AGENTS.md`.
## تحقّق بعد الترقية
المحوّل حتمي، لا مثالي. مرّ على قائمة "Left for you" في التقرير، ثم تحقّق من هذه:
- **الشارات والأزرار.** الشارة أو الزر في الإصدار 2 حين يكون في سطر مستقل يصبح `Completed` أو ``. والنوع في الإصدار 2 الذي لا مقابل له في الإصدار 3، والأيقونات، وسمات التنسيق، تُحذف وتُسرد في التقرير، والشارة التي لا نص فيها تُزال. انظر إلى كلٍّ منها في المتصفح.
- **الروابط التي احتفظت بـ `{{version}}`.** يبقى الرابط `/docs/{{version}}/...` كما كان ما لم تمرّر `--relative-links`. ويظل يعمل ما دامت البادئة فيه صحيحة. جِد ما تبقّى منها بالأمر `grep -rn '{{' docs/`، وأعد كتابة كلٍّ منها رابط `.md` نسبيًا إن تغيّرت بادئتك.
- **الروابط القديمة.** إن تغيّرت بادئة المسار لديك، فأبقِ الروابط القديمة ونتائج البحث تعمل بإعادات التوجيه.
**كيف يُبقي هذا الموقع روابط الإصدار 2 تعمل**
نقل هذا الموقع توثيق الإصدار 2 من `/docs/{version}/{page}` إلى `/2.x/{page}`، ويحوي ملف `routes/web.php` فيه:
```php title="routes/web.php"
Route::permanentRedirect('/docs', '/');
Route::permanentRedirect('/docs/{version}', '/2.x');
Route::permanentRedirect('/docs/{version}/{page}', '/2.x/{page}');
```
استخدم مسارات تطبيقك لبادئة قديمة كاملة. أما داخل بادئة واحدة، فاستخدم `redirects` في `larecipe.json` بدلًا من ذلك، راجع [التنقل](https://larecipe.saleem.dev/ar/3.x/writing/navigation.md).
## ما الذي تغيّره الترقية
التفاصيل وراء التقرير، لحين تريد أن تعرف بالضبط ما الذي حدث لملف ما.
**ما الذي يكتبه الأمر**
| التشغيل | ما يكتبه |
| --- | --- |
| `php artisan larecipe:upgrade` | التقرير فقط: `larecipe-upgrade-report.md` و `larecipe-upgrade-report.json`. |
| `php artisan larecipe:upgrade --apply` | ملف `config/larecipe.php` الجديد (ويُحفظ ملف الإصدار 2 باسم `config/larecipe.v2.php.bak`)، و `larecipe.json`، وملف `navigation.json` لكل إصدار، وكل صفحة محوّلة، والتقرير. |
يكتب `--apply` الملفات الجديدة والمحوّلة أولًا ويحذف القديمة أخيرًا، فلا يضيع أي صفحة إن انقطع التشغيل. ومع `--move-to`، يجب أن يكون المجلد الهدف فارغًا أو غير موجود، ويُحذف المجلد القديم حين لا يبقى فيه شيء.
يتوقف الأمر مبكرًا حين لا يكون هناك ما يُرقّى: حين لا يوجد `config/larecipe.php`، أو حين يحوي ذلك الملف أصلًا المفتاح `sets` الخاص بالإصدار 3، أو حين لا يوجد مجلد التوثيق الذي يسمّيه. وبعد `--apply` تصبح إعداداتك للإصدار 3، فلتشغّل الترقية مرة أخرى، استعد ملفات الإصدار 2 من git أولًا.
**الإعدادات: ملف واحد يصبح ملفين**
تصبح إعدادات الإصدار 2 لديك ملفين: البنية التحتية في `config/larecipe.php`، والمحتوى والعرض في `larecipe.json`. راجع [أساسيات الإعداد](https://larecipe.saleem.dev/ar/3.x/get-started/configuration.md).
| الإصدار 2 | الإصدار 3 |
| --- | --- |
| `docs.route` | `sets.docs.route.prefix` |
| `docs.path` | `sets.docs.source.path` (أو مجلد `--move-to`) |
| `docs.middleware` و `settings.middleware` | `sets.docs.route.middleware` |
| `settings.auth` | `access.mode` بالقيمة `auth` |
| البوابة `viewLarecipe` في الكود لديك | `access.mode` بالقيمة `gate` (وإلا فـ `public`) |
| `versions.published` و `versions.default` | `versions` في `larecipe.json` |
| `docs.landing` | `landing` في `larecipe.json` |
| `ui.fav` | `favicon` في `larecipe.json` |
| `ui.colors.primary` | `theme.accent` في `larecipe.json` |
| `seo.description` | `description` في `larecipe.json` |
| `settings.ga_id` | تكامل GA4 تحت `integrations.analytics` في `larecipe.json` |
يأتي `name` في ملف التعريف من `APP_NAME` لديك. ولا تحوي الإعدادات المكتوبة إلا المجموعة `docs`، وكل مفتاح آخر يحتفظ بالقيمة الافتراضية للحزمة. وانشر الملف كاملًا بالأمر `php artisan vendor:publish --tag=larecipe-config` فقط إن أردته في تطبيقك.
**التنقل: الشريط الجانبي للإصدار 2 يصبح navigation.json**
كان `index.md` في كل إصدار هو شريطه الجانبي في الإصدار 2. تحلّل الترقية عناوين `## Group` والروابط فيه إلى ملف `navigation.json` لذلك الإصدار، وتحتفظ بتسمية الرابط حين تختلف عن عنوان الصفحة، وتُبقي الروابط الخارجية روابط، وتحذف `index.md` القديم. ويُبلَّغ عن أي سطر في الشريط الجانبي ليس عنوان مجموعة ولا رابطًا. والإصدار الذي لا `index.md` فيه يحصل على [تنقل من مجلداته](https://larecipe.saleem.dev/ar/3.x/writing/navigation.md).
**الصفحات: ما الذي يصبحه كل سطر**
تُعاد كتابة كل صفحة سطرًا بسطر. ولا تُمسّ كتل الكود أبدًا.
| الإصدار 2 | الإصدار 3 |
| --- | --- |
| `> {warning} text` و `> {info} text` وأنواع التنبيهات الأخرى | تنبيهات GitHub: `primary` يصبح `IMPORTANT`، و `secondary` و `info` يصبحان `NOTE`، و `success` يصبح `TIP`، و `warning` يبقى `WARNING`، و `danger` يصبح `CAUTION` |
| `` قبل عنوان | معرّف عنوان `{#x}`، فتظل الروابط القديمة `#x` تصل |
| `` | `` |
| `` و `` في سطر مستقل | `Text` و ``، مع تحويل نوع الإصدار 2 إلى `tone` أو `variant` |
| `` و `` داخل جملة | نصّهما |
| روابط `/{{route}}/{{version}}/page#anchor` | روابط نسبية: `page.md#anchor` |
| روابط `/docs/{{version}}/page` | تبقى، لأن الإصدار 3 ما زال يملأ `{{version}}`، وتصبح نسبية مع `--relative-links` |
| قوائم `