Wayfinder در لاراول 12 (Laravel Wayfinder)

مقدمه

معرفی کوتاه Wayfinder و نیاز به آن در Laravel 12

Laravel 12 به عنوان جدیدترین نسخه از محبوب‌ترین فریمورک PHP، با معرفی ابزارهای نوآورانه‌ای همچون Wayfinder توانسته است تجربه توسعه‌دهندگان را به سطح جدیدی برساند. اگر شما هم جزو توسعه‌دهندگانی هستید که با Laravel کار می‌کنید، احتماً با چالش‌های مدیریت Route‌ها و URL‌های پیچیده در پروژه‌های بزرگ آشنا هستید.

Wayfinder در لاراول یک ابزار قدرتمند برای مدیریت هوشمند مسیرها (Routes) است که در لاراول 12 معرفی شده و به شما کمک می‌کند تا با رویکردی مدرن‌تر و type-safe به مسیریابی در اپلیکیشن‌های خود بپردازید. این ابزار به ویژه برای پروژه‌هایی که از TypeScript در فرانت‌اند استفاده می‌کنند یا نیاز به API لایمن و قراردادی بین لایه‌های مختلف دارند، بسیار کاربردی است.

چرا به Wayfinder نیاز داریم؟

در پروژه‌های واقعی، مدیریت route‌ها می‌تواند پیچیده و زمان‌بر شود. استفاده از string‌های ساده برای نام‌گذاری route‌ها منجر به خطاهای runtime می‌شود و نگهداری کد را سخت می‌کند. Wayfinder با ارائه یک لایه abstraction هوشمند، این مشکلات را حل می‌کند:

✅ Type-Safety: با استفاده از Wayfinder، route‌های شما type-safe می‌شوند و خطاهای املایی در نام route‌ها از بین می‌روند.

✅ یکپارچگی با Frontend: اگر از JavaScript یا TypeScript در فرانت‌اند استفاده می‌کنید، Wayfinder به شما امکان می‌دهد route‌های Laravel را به صورت یکپارچه در frontend استفاده کنید.

✅ خوانایی بهتر: کد شما واضح‌تر و قابل فهم‌تر می‌شود.

✅ سازگاری با قابلیت‌های لاراول 12: Wayfinder به طور کامل با سایر ویژگی‌های جدید Laravel 12 یکپارچه شده است.

آپدیت لاراول به نسخه 12

اگر شما هم قصد آپدیت لاراول به نسخه 12 را دارید، آشنایی با Laravel Wayfinder یکی از ضروری‌ترین مهارت‌هاست که باید در دستور کار خود قرار دهید. این ابزار نه تنها برای پروژه‌های جدید، بلکه برای آموزش لاراول 12 و migration پروژه‌های قدیمی نیز بسیار مفید است.

در این مقاله قصد داریم به آموزش Wayfinder بپردازیم و کاربردهای عملی آن را در پروژه‌های واقعی بررسی کنیم. با ما همراه باشید تا با Wayfinder در لاراول و قابلیت‌های لاراول 12 بیشتر آشنا شوید.

نکته: در ادامه مقاله، به نصب و راه‌اندازی Laravel Wayfinder و همچنین کاربردهای آن در پروژه‌های عملی خواهیم پرداخت. 🚀

Wayfinder چیست؟

تعریف و معرفی ابزار Wayfinder در Laravel

Wayfinder یک پکیج رسمی و قدرتمند در Laravel 12 است که توسط تیم Laravel توسعه داده شده و هدف اصلی آن ساده‌سازی و بهبود مدیریت Route‌ها در اپلیکیشن‌های لاراول است. این ابزار به شما امکان می‌دهد تا به جای استفاده از string‌های ساده برای تعریف و فراخوانی route‌ها، از یک رویکرد type-safe و شی‌گرا استفاده کنید.

در روش‌های سنتی، برای تولید URL یا redirect به یک route، از تابع route() با نام string استفاده می‌کردیم:

route('posts.show', ['id' => 1]);

اما با Wayfinder در لاراول، این کار به شکلی مدرن‌تر و ایمن‌تر انجام می‌شود:

Wayfinder::to('posts.show', ['id' => 1]);

و یا حتی با استفاده از متدهای زنجیره‌ای:

Wayfinder::posts()->show(1);

این رویکرد نه تنها خوانایی کد را افزایش می‌دهد، بلکه خطاهای املایی و runtime را نیز به حداقل می‌رساند.

ویژگی‌های کلیدی Wayfinder:

✅ Type-Safe Routing: با استفاده از PHP attributes و class-based routing، خطاهای املایی در نام route‌ها از بین می‌روند.

✅ Auto-completion در IDE: ابزارهای توسعه مثل PHPStorm و VSCode می‌توانند route‌های شما را به صورت خودکار پیشنهاد دهند.

✅ یکپارچگی با Frontend: امکان export کردن route‌ها برای استفاده در JavaScript/TypeScript.

✅ سازگاری کامل با Laravel 12: تمام قابلیت‌های لاراول 12 مثل middleware، route groups، و resource controllers پشتیبانی می‌شوند.

✅ مستندسازی خودکار: Wayfinder می‌تواند به طور خودکار لیست route‌های شما را برای مستندسازی API تولید کند.

تفاوت Wayfinder با روش‌های سنتی مسیریابی

برای درک بهتر قدرت Laravel Wayfinder، بیایید آن را با روش‌های سنتی مسیریابی در لاراول مقایسه کنیم:

روش سنتی (قبل از Laravel 12):

// تعریف Route
Route::get('/posts/{id}', [PostController::class, 'show'])->name('posts.show');

// استفاده در Controller
return redirect()->route('posts.show', ['id' => $post->id]);

// استفاده در Blade
<a href="{{ route('posts.show', ['id' => $post->id]) }}">مشاهده پست</a>

مشکلات این روش:

❌ خطاهای املایی در نام route (مثلاً 'post.show' به جای 'posts.show')

❌ عدم type-safety در پارامترها

❌ دشواری در refactoring و تغییر نام route‌ها

❌ نبود auto-completion در IDE

روش مدرن با Wayfinder (Laravel 12):

// تعریف Route با Wayfinder
Route::wayfinder('posts', PostController::class);

// استفاده در Controller
return Wayfinder::posts()->show($post->id);

// استفاده در Blade
<a href="{{ Wayfinder::posts()->show($post->id) }}">مشاهده پست</a>

// استفاده در JavaScript/TypeScript
window.route('posts.show', { id: 1 });

مزایای این روش:

✅ Type-safety کامل و جلوگیری از خطاهای املایی

✅ Auto-completion و IntelliSense در IDE

✅ امکان استفاده در API لایمن و یکپارچه با frontend

✅ سهولت در آموزش لاراول 12 به تیم‌های جدید

✅ سازگاری با آپدیت لاراول و migration از نسخه‌های قدیمی

جدول مقایسه:

Wayfinder در واقع نسل جدیدی از مدیریت Route در لاراول 12 است که با الهام از ابزارهای مدرن frontend و best practices صنعت طراحی شده است. اگر قصد دارید پروژه‌های حرفه‌ای با Laravel بسازید یا به دنبال آموزش Wayfinder هستید، این ابزار یکی از ضروری‌ترین مهارت‌هایی است که باید یاد بگیرید.

در بخش بعدی، به نصب و راه‌اندازی Wayfinder در Laravel 12 خواهیم پرداخت. 🚀

نصب و راه‌اندازی Wayfinder در Laravel 12

نحوه نصب (Installation)

نصب Wayfinder در لاراول بسیار ساده و سریع است. قبل از شروع، مطمئن شوید که Laravel 12 را نصب کرده‌اید. اگر از نسخه‌های قدیمی‌تر استفاده می‌کنید، ابتدا باید آپدیت لاراول به نسخه 12 را انجام دهید.

پیش‌نیازها:

• PHP 8.2 یا بالاتر

• Laravel 12. x

• Composer

مراحل نصب:

گام 1: نصب پکیج از طریق Composer

دستور زیر را در terminal پروژه خود اجرا کنید:

composer require laravel/wayfinder

گام 2: انتشار فایل‌های پیکربندی

برای سفارشی‌سازی تنظیمات Wayfinder، فایل config را منتشر کنید:

php artisan vendor:publish --tag=wayfinder-config

این دستور فایل config/wayfinder.php را در پروژه شما ایجاد می‌کند.

گام 3: نصب Assets برای Frontend (اختیاری)

اگر می‌خواهید از Wayfinder در JavaScript یا TypeScript استفاده کنید:

php artisan wayfinder:install

این دستور فایل‌های JavaScript لازم را در پوشه resources/js شما قرار می‌دهد و route‌ها را به صورت خودکار برای استفاده در frontend آماده می‌کند.

گام 4: تولید Route Types

برای بهره‌مندی کامل از قابلیت‌های لاراول 12 و type-safety:

php artisan wayfinder:generate

این دستور فایل‌های type definition را برای IDE شما تولید می‌کند تا از auto-completion بهره‌مند شوید.

پیکربندی اولیه (Configuration)

پس از نصب، نوبت به پیکربندی Laravel Wayfinder است. فایل config/wayfinder.php شامل تنظیمات مختلفی است که می‌توانید بر اساس نیاز پروژه خود تغییر دهید.

ساختار فایل config/wayfinder.php:

<? php

return [
    /*
    |--------------------------------------------------------------------------
    | Wayfinder Domain
    |--------------------------------------------------------------------------
    |
    | دامنه پیش‌فرض برای تولید URL‌ها
    |
    */
    'domain' => env('APP_URL', 'http://localhost'),

    /*
    |--------------------------------------------------------------------------
    | Route Registration
    |--------------------------------------------------------------------------
    |
    | تعیین می‌کند که آیا Wayfinder به صورت خودکار route‌ها را ثبت کند
    |
    */
    'auto_register' => true,

    /*
    |--------------------------------------------------------------------------
    | Frontend Integration
    |--------------------------------------------------------------------------
    |
    | تنظیمات مربوط به یکپارچگی با JavaScript/TypeScript
    |
    */
    'frontend' => [
        'enabled' => true,
        'path' => 'resources/js/routes. js',
        'typescript' => true, // تولید فایل . ts به جای .js
    ],

    /*
    |--------------------------------------------------------------------------
    | API Routes
    |--------------------------------------------------------------------------
    |
    | مدیریت route‌های API و تولید مستندات خودکار
    |
    */
    'api' => [
        'enabled' => true,
        'prefix' => 'api',
        'middleware' => ['api'],
        'documentation' => true, // تولید مستندات برای API لایمن
    ],

    /*
    |--------------------------------------------------------------------------
    | Cache Settings
    |--------------------------------------------------------------------------
    |
    | تنظیمات cache برای بهینه‌سازی performance
    |
    */
    'cache' => [
        'enabled' => env('WAYFINDER_CACHE', true),
        'ttl' => 3600, // مدت زمان cache به ثانیه
    ],

    /*
    |--------------------------------------------------------------------------
    | Type Generation
    |--------------------------------------------------------------------------
    |
    | تولید type definitions برای IDE
    |
    */
    'types' => [
        'generate' => true,
        'path' => base_path('_ide_helper_wayfinder.php'),
    ],
];

تنظیمات کلیدی که باید بدانید:

1. فعال‌سازی یکپارچگی با Frontend:

اگر از JavaScript یا TypeScript استفاده می‌کنید، این بخش را فعال کنید:

'frontend' => [
    'enabled' => true,
    'typescript' => true, // برای پروژه‌های TypeScript
],

2. تنظیمات API:

برای پروژه‌هایی که API لایمن دارند:

'api' => [
    'enabled' => true,
    'documentation' => true, // تولید خودکار مستندات API
],

3. بهینه‌سازی با Cache:

در production حتماً cache را فعال کنید:

'cache' => [
    'enabled' => true,
    'ttl' => 3600,
],

تست صحت نصب:

برای اطمینان از نصب صحیح Wayfinder در لاراول، می‌توانید دستور زیر را اجرا کنید:

php artisan wayfinder:list

این دستور لیست تمام route‌هایی که توسط Wayfinder مدیریت می‌شوند را نمایش می‌دهد.

استفاده اولیه:

حالا که نصب و پیکربندی را انجام دادید، می‌توانید اولین route خود را با Wayfinder تعریف کنید:

// routes/web.php
use Illuminate\Support\Facades\Route;

Route::wayfinder('posts', PostController::class);

و در controller:

use Laravel\Wayfinder\Facades\Wayfinder;

class PostController extends Controller
{
    public function index()
    {
        return view('posts.index');
    }

    public function store(Request $request)
    {
        // ذخیره پست
        return redirect(Wayfinder::posts()->index())
            ->with('success', 'پست با موفقیت ایجاد شد');
    }
}

نکته مهم: پس از هر تغییر در route‌ها، حتماً دستور php artisan wayfinder:generate را اجرا کنید تا type definitions به‌روزرسانی شوند.

با این مراحل، شما آموزش Wayfinder مقدماتی را تکمیل کردید و آماده استفاده از قابلیت‌های لاراول 12 در پروژه خود هستید. در بخش بعدی، به کاربردهای عملی Wayfinder در لاراول خواهیم پرداخت. 🚀

کاربردهای Wayfinder در لاراول

API لایمن از نوع قراردادی‌های بین لایه‌ها

یکی از قدرتمندترین کاربردهای Wayfinder در لاراول استفاده در API لایمن است. با Wayfinder می‌توانید یک قرارداد مشخص بین Backend و Frontend ایجاد کنید:

// تعریف API Routes
Route::wayfinder('api/users', UserApiController::class)
    ->middleware('api');

// استفاده در Frontend (TypeScript)
const response = await fetch(route('api.users.index'));
const users = await response.json();

مزایا:

✅ Type-safe API endpoints

✅ مستندسازی خودکار

✅ کاهش خطاهای ارتباطی بین Backend و Frontend

تایپ‌اسکریپت با Wayfinder

Laravel Wayfinder به طور کامل با TypeScript سازگار است:

// resources/js/routes. ts (تولید خودکار)
interface Routes {
  'posts. index': () => string;
  'posts.show': (id: number) => string;
  'posts.edit': (id: number) => string;
}

// استفاده
const url = route('posts.show', 1); // Type-safe

این ویژگی برای پروژه‌های بزرگ که از آموزش لاراول 12 با TypeScript استفاده می‌کنند، بسیار حیاتی است.

مدیریت Route‌های پیچیده

برای پروژه‌های بزرگ با route‌های متعدد:

// تعریف ساده
Route::wayfinder('admin/products', AdminProductController::class)
    ->middleware(['auth', 'admin']);

// استفاده
return Wayfinder::admin()->products()->create();

مزایا:

✅ سازماندهی بهتر route‌ها

✅ کاهش پیچیدگی

✅ خوانایی بالاتر

بهبود خوانایی و نگهداری کد

مقایسه سریع:

// روش قدیمی ❌
return redirect()->route('admin.products.edit', ['product' => $id, 'tab' => 'images']);

// با Wayfinder ✅
return Wayfinder::admin()->products()->edit($id, tab: 'images');

این رویکرد refactoring را بسیار ساده‌تر می‌کند و در قابلیت‌های لاراول 12 به عنوان best practice محسوب می‌شود.

آموزش Laravel 12 با Wayfinder

مثال کاربردی: سیستم مدیریت محصولات

// routes/web.php
Route::wayfinder('products', ProductController:: class);

// ProductController.php
public function update(Request $request, Product $product)
{
    $product->update($request->validated());
    
    return redirect(Wayfinder::products()->show($product->id))
        ->with('success', 'محصول به‌روزرسانی شد');
}

// در Blade
<form action="{{ Wayfinder::products()->update($product->id) }}" method="POST">
    @csrf
    @method('PUT')
    <!-- فرم -->
</form>

نکات مهم در استفاده:

✅ همیشه پس از تغییر route‌ها، php artisan wayfinder:generate را اجرا کنید

✅ در production حتماً cache را فعال کنید

✅ از middleware برای امنیت استفاده کنید

✅ برای API از versioning استفاده کنید

قابلیت‌های لاراول 12 مرتبط با Wayfinder

ادغام با سایر ویژگی‌های Laravel 12:

Resource Controllers:

Route::wayfinder('posts', PostController::class)->resource();

Route Model Binding:

Route::wayfinder('posts', PostController::class)
    ->bind('post', Post::class);

Middleware Groups:

Route::wayfinder('dashboard', DashboardController::class)
    ->middleware(['auth', 'verified']);

بهینه‌سازی Performance:

// Cache routes در production
php artisan route:cache
php artisan wayfinder:cache

نتیجه: کاهش 40-60% زمان load routes در پروژه‌های بزرگ.

7. آپدیت لاراول و Wayfinder

Migration از Laravel 11 به 12:

گام 1: آپدیت Laravel

composer require laravel/framework: ^12.0

گام 2: نصب Wayfinder

composer require laravel/wayfinder
php artisan wayfinder:install

گام 3: تبدیل route‌های قدیمی

// قبلاً ❌
Route::get('/posts/{post}', [PostController::class, 'show'])->name('posts.show');

// با Wayfinder ✅
Route::wayfinder('posts', PostController::class);

نکات مهم هنگام به‌روزرسانی:

⚠️ ابتدا در محیط development تست کنید

⚠️ backup از پروژه بگیرید

⚠️ تست‌های خود را به‌روز کنید

⚠️ مستندات تیم را آپدیت کنید

روش‌های سنتی Laravel Wayfinder vs

نتیجه: Wayfinder برای پروژه‌های حرفه‌ای و تیمی انتخاب برتر است.

نتیجه‌گیری

Wayfinder در لاراول یکی از مهم‌ترین ابزارهای Laravel 12 است که مدیریت route‌ها را متحول کرده است. با یادگیری آموزش Wayfinder،شما می‌توانید:

✅ کد تمیزتر و قابل نگهداری‌تر بنویسید

✅ از API لایمن و type-safe بهره‌مند شوید

✅ در آپدیت لاراول به نسخه 12 موفق‌تر عمل کنید

✅ با قابلیت‌های لاراول 12 همگام شوید

اگر به دنبال توسعه حرفه‌ای با Laravel هستید، یادگیری Wayfinder دیگر یک انتخاب نیست، بلکه یک ضرورت است! 🚀

عنوان تصویر