لاراول Macro چیست؟ آشنایی عمیق با Laravel Macro

لاراول یک فریمورک محبوب PHP است که به دلیل ظرافت و ویژگی‌های مناسب برای توسعه‌دهندگان شناخته می‌شود. یکی از این ویژگی‌ها که انعطاف‌پذیری لاراول را افزایش می‌دهد، ماکروها هستند. ماکروهای لاراول به شما این امکان را می دهند که متد های اصلی را گسترش دهید و متدهای سفارشی را برای کلاس هایی مانند مدل ها و مجموعه های Eloquent ایجاد کنید. در این راهنمای گام به گام، ما دنیای ماکروهای لاراول را بررسی می کنیم و به شما نشان می دهیم که چگونه از قدرت آنها برای پروژه های خود استفاده کنید.

ماکروهای لاراول چیست؟

قبل از استفاده از ماکروها، درک مفهوم آنها ضروری است. ماکروها شما را قادر می سازند تا متد های سفارشی را به کلاس های لاراول موجود بدون تغییر کد منبع آن ها اضافه کنید. این به ویژه برای تمیز نگه داشتن پایگاه کد و حفظ سازگاری با به‌روزرسانی‌های آینده لاراول مفید است. ماکروهای لاراول اساساً تکنیکی برای گسترش عملکرد کلاس‌های لاراول موجود هستند. آنها را ترفندهای جادویی کوچکی در نظر بگیرید که قابلیت های اجزای اصلی لاراول را بدون تغییر کد منبع افزایش می دهد. ماکروهای لاراول به ما این امکان را می دهند که قابلیت های سفارشی را به اجزا یا کلاس های اصلی لاراول اضافه کنیم. به عبارت دیگر، آنها به ما اجازه می دهند کلاس های لاراول را گسترش دهیم.

چرا به Laravel Macros نیاز داریم؟

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

Macroable Trait چیست؟

Trait Macroable ستون فقرات Laravel Macros است. به هر کلاسی اجازه می دهد تا متدهای سفارشی را در زمان اجرا ثبت کند. این کار با استفاده از متد ماکرو انجام می شود.

مروری بر کلاس های ماکرو در لاراول

در اینجا برخی از کلاس های کلیدی لاراول که از Macroable trait استفاده می کنند آورده شده است:

Collection (Illuminate\Support\Collection)
Request (Illuminate\Http\Request)
Eloquent Builder (Illuminate\Database\Eloquent\Builder)
Response (Illuminate\Http\Response)
Route (Illuminate\Support\Facades\Route)
Validator (Illuminate\Support\Facades\Validator)
Cache (Illuminate\Support\Facades\Cache)
Blade (Illuminate\Support\Facades\Blade)

حال که با ماکروها آشنا شدیم بیاید با هم دیگر یک مثال عملی از ماکروهای لاراول را پیاده سازی کنیم.

برای آشنایی با هنر اعتبارسنجی در لاراول این مقاله را بررسی کنید.

با لاراول 11 چقدر آشنا هستید؟ برای آشنایی با ویژگی های لاراول 11 این مقاله را بررسی کنید.

مثال عملی با ماکرو لاراول

بیایید با استفاده از یک مثال عملی به صورت قدم به قدم به مفهوم ماکروها بپردازیم.

یک پروژه جدید لاراول ایجاد کنید یا از یک پروژه موجود برای دنبال کردن این مقاله استفاده کنید. با اجرای دستور زیر می توانید لاراول را نصب کنید:

composer create-project --prefer-dist laravel/laravel your-project-name

ایجاد یک ماکرو

اکنون، بیایید اولین ماکرو خود را ایجاد کنیم. برای این مثال، کلاس Illuminate\Support\Collection را برای اضافه کردن یک متد سفارشی برای فیلتر کردن اعداد زوج گسترش می‌دهیم. در ترمینال خود، دستور زیر را برای ایجاد یک ارائه service provider ماکرو جدید اجرا کنید:

MacrosServiceProvider را ایجاد کنید

ابتدا یک service provider اختصاص داده شده به ماکروها ایجاد کنید:

php artisan make:provider MacrosServiceProvider

این دستور یک فایل جدید به نام MacrosServiceProvider.php در دایرکتوری app/Providers ایجاد می کند. لاراول به طور خودکار service provider جدید شما را در فایل bootstrap/providers.php برنامه شما ثبت می کند:

ساختار service provider ایجاد شده :

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;

class MacrosServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     *
     * @return void
     */
    public function register()
    {
        //
    }

    /**
     * Bootstrap any application services.
     *
     * @return void
     */
    public function boot()
    {
        //
    }
}

بیاید یک بار دیگر متد های داخل service provider را بررسی کنیم.

متد ها:
 

()register: این متد برای اتصال چیزها به سرویس کانتینر استفاده می شود. می‌توانید از این متد برای راه‌اندازی هر گونه سرویس یا پیوندهایی که برنامه شما نیاز دارد استفاده کنید. برای آشنایی با سرویس کانتینر و تزریق وابستگی در لاراول این مقاله را بررسی کنید.

()boot: این تابع برای راه اندازی هر سرویس کاربردی استفاده می شود. پس از ثبت نام تمام service provider های دیگر فراخوانی می شود، به این معنی که شما به سایر سرویس ثبت شده با استفاده از متد register دسترسی دارید.

حال یک دایرکتوری به نام Macros در دایرکتوری app ایجاد کنید، بنابراین به صورت app\Macros خواهد بود.

سپس برای هر نوع ماکرو در این دایرکتوری کلاس های جداگانه ایجاد کنید. مثلا:

مجموعه ماکروها (CollectionMacros) :

ایجاد یک فایل app/Macros/CollectionMacros.php:

namespace App\Macros;

use Illuminate\Support\Collection;

class CollectionMacros
{
    public static function register()
    {
        // Macro to convert all items in a collection to uppercase
        Collection::macro('toUpper', function () {
            return $this->map(function ($value) {
                return strtoupper($value);
            });
        });


        // Macro to calculate the average length of strings in a collection
        Collection::macro('averageLength', function () {
            return $this->map(function ($item) {
                return strlen($item);
            })->avg();
        });
    }
}

RequestMacros :

برای ایجاد یک ماکرو درخواست ها با ایجاد فایل App\Macros\RequestMacros.php:

namespace App\Macros;

use Illuminate\Http\Request;

class RequestMacros
{
    public static function register()
    {
         // Macro to check if the authenticated user is an admin
        Request::macro('isAdmin', function () {
            return $this->user() && $this->user()->isAdmin();
        });

        // Macro to check if the request is an AJAX request
        Request::macro('isAjax', function () {
            return $this->ajax();
        });
    }
}

BuilderMacros:

با ایجاد یک فایل app/Macros/BuilderMacros.php:

namespace App\Macros;

use Illuminate\Database\Eloquent\Builder;

class BuilderMacros
{
    public static function register()
    {
        // Macro to scope query to only active records
        Builder::macro('active', function () {
            return $this->where('status', 'active');
        });

        // Macro to scope query to only recent records created in the last 30 days
        Builder::macro('recent', function () {
            return $this->where('created_at', '>=', now()->subDays(30));
        });
    }
}

ResponseMacros :

با ایجاد یک فایل app/Macros/ResponseMacros.php:

namespace App\Macros;

use Illuminate\Http\Response;

class ResponseMacros
{
    public static function register()
    {
        // Macro to return a standardized JSON response for API
        Response::macro('api', function ($data, $status = 200) {
            return response()->json([
                'data' => $data,
                'status' => $status,
            ], $status);
        });
    }
}

RouteMacros

با ایجاد یک فایل app/Macros/RouteMacros.php:

namespace App\Macros;

use Illuminate\Support\Facades\Route;

class RouteMacros
{
    public static function register()
    {
        // Macro to define standard CRUD routes for a resource
        Route::macro('crud', function ($name, $controller) {
            Route::get("$name", [$controller, 'index'])->name("$name.index");
            Route::get("$name/create", [$controller, 'create'])->name("$name.create");
            Route::post("$name", [$controller, 'store'])->name("$name.store");
            Route::get("$name/{id}", [$controller, 'show'])->name("$name.show");
            Route::get("$name/{id}/edit", [$controller, 'edit'])->name("$name.edit");
            Route::put("$name/{id}", [$controller, 'update'])->name("$name.update");
            Route::delete("$name/{id}", [$controller, 'destroy'])->name("$name.destroy");
        });
    }
}

ValidatorMacros :

یک فایل جدید به اسم ValidatorMacros.php در دایرکتوری Macros :

namespace App\Macros;

use Illuminate\Support\Facades\Validator;

class ValidatorMacros
{
    public static function register()
    {  
        // Macro to add a UUID validation rule
        Validator::extend('uuid', function ($attribute, $value, $parameters, $validator) {
            return preg_match('/^\{?[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}\}?$/', $value);
        });
    }
}

CacheMacros :

با ایجاد فایل CacheMacros.php در دایرکتوری Macros :

namespace App\Macros;

use Illuminate\Support\Facades\Cache;

class CacheMacros
{
    public static function register()
    {
        // Macro to remember a cache value once and return it   
        Cache::macro('rememberOnce', function ($key, $ttl, $callback) {
            if (Cache::has($key)) {
                return Cache::get($key);
            }

            $value = $callback();
            Cache::put($key, $value, $ttl);

            return $value;
        });
    }
}

اینها چندین نوع استفاده از ماکروها هستند.

لاراول Octane چیست؟ برای آشنای با لاراول اوکتان این مقاله را بررسی کنید.

مستند سازی API در لاراول با سواگر

ثبت ماکروها در MacrosServiceProvider

در app/Providers/MacrosServiceProvider.php، کلاس های ماکرو را ثبت کنید:

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use App\Macros\CollectionMacros;
use App\Macros\RequestMacros;
use App\Macros\BuilderMacros;
use App\Macros\ResponseMacros;
use App\Macros\RouteMacros;
use App\Macros\ValidatorMacros;
use App\Macros\CacheMacros;

class MacrosServiceProvider extends ServiceProvider
{
    public function boot()
    {
        // Registering all macros
        CollectionMacros::register();
        RequestMacros::register();
        BuilderMacros::register();
        ResponseMacros::register();
        RouteMacros::register();
        ValidatorMacros::register();
        CacheMacros::register();
    }

    public function register()
    {
        //
    }
}

MacrosServiceProvider را ثبت کنید

هنگام ایجاد MacrosServiceProvider اشاره کردیم که به صورت پیش فرض لاراول این سرویس پرووایدر را  در دایرکتوری bootstrap/providers.php ثبت می کند. ولی اگر از ورژن لاراول 10 و به پایین استفاده می کنید نیاز است که در دایرکتوری config/app.php این کار را انجام دهید.

'providers' => [
    // Other service providers...

    App\Providers\MacrosServiceProvider::class,
],

استفاده از ماکروها در لاراول

اکنون می توانید از ماکروها در برنامه خود به صورت زیر استفاده کنید:

ماکروهای مجموعه :

$collection = collect(['hello', 'world', 'Laravel']);
$averageLength = $collection->averageLength(); // 6
$uppercased = $collection->toUpper(); // ['HELLO', 'WORLD', 'LARAVEL']

// averageLength: Calculates the average length of strings in the collection
// toUpper: Converts all items in the collection to uppercase

Request Macros :

if ($request->isAdmin()) {
     // isAdmin: Checks if the authenticated user is an admin
    // Do something for admin user
}

if ($request->isAjax()) {
    // isAjax: Checks if the request is an AJAX request
    // Handle AJAX request
}

بهترین اقدامات در استفاده از ماکرو های لاراول

تضادهای ماکرو (Macro Conflicts): مطمئن شوید که نام های ماکرو انتخابی با متدهای موجود در کلاس تضاد ندارند.
تست ماکروها: همیشه برای ماکروهای خود تست بنویسید تا مطمئن شوید که مطابق انتظار رفتار می کنند.
ملاحظات عملکرد: در حالی که ماکروها راحت هستند، استفاده بیش از حد از آنها می تواند منجر به مشکلات عملکرد شود. از آنها عاقلانه استفاده کنید.

دقت کنید، ماکروها در لاراول برای افزودن متدهای اضافی به کلاس ها بدون تغییر کد اصلی استفاده می شوند. آنها نمی توانند مستقیماً متد های فعلی را تغییر دهند. با این حال، می‌توانید متد های موجود را با گسترش کلاس‌ها و استفاده از ماکروها تغییر دهید.

ماکروها ابزار قدرتمندی هستند، اما با قدرت زیاد، مسئولیت بزرگی به همراه دارد. این اقدامات احتیاطی را برای اطمینان از ایمنی پایگاه کد خود دنبال کنید:

ماکروهای خود را مستند کنید: هدف، پارامترها و نتایج مورد انتظار هر ماکرو را برای کمک به توسعه دهندگان آینده ثبت کنید.
محدود کردن دامنه: ماکروهایی را در service provider تعریف کنید که فقط در صورت نیاز به جای provider های گلوبال بارگیری می شوند.

برای آشنایی با معماری ماژولار در لاراول این مقاله جذاب از آنوفل را از دست ندهید.

نتیجه

ماکروهای لاراول ابزاری قدرتمند برای گسترش عملکرد لاراول بدون تغییر کد اصلی آن هستند. در این راهنما از آنوفل، نحوه ایجاد و استفاده از ماکروها را در پروژه های لاراول خود، هم برای مجموعه ها و هم برای مدل های Eloquent، یاد گرفته اید. این قابلیت سفارشی سازی می تواند به طور قابل توجهی پایگاه کد شما را ساده کرده و تجربه توسعه شما را افزایش دهد. بنابراین، ادامه دهید و از ماکروهای لاراول برای باز کردن امکانات جدید در پروژه های توسعه وب خود استفاده کنید.