Laravel 12 Makra: Kompletny Przewodnik

4 min. czytaniaZaktualizowano

Makra pozwalają dodawać własne metody do podstawowych klas Laravela bez ruszania kodu źródłowego frameworka. Poniżej: jak je rejestrować w Laravel 12 i jakich rodzajów faktycznie używam.

Czym Są Makra?

Makra wykorzystują magiczną metodę PHP __call do dodawania własnych metod do klas, które używają traitu Macroable.

Tworzenie Podstawowych Makr

Najczęstszym miejscem rejestracji makr jest metoda boot service providera. Zacznijmy od prostego przykładu:

php
use Illuminate\Support\Str;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Str::macro('toSnakeCase', function (string $value) {
            return strtolower(preg_replace('/(?<!^)[A-Z]/', '_$0', $value));
        });
    }
}

Teraz możesz użyć tego makra w dowolnym miejscu swojej aplikacji:

php
echo Str::toSnakeCase('HelloWorld'); // wyświetla: hello_world

Rodzaje Makr

Większość podstawowych klas Laravela używa Macroable. Oto te, po które sięgam najczęściej:

Makra Response

Makra response dają wielokrotnego użytku format odpowiedzi:

php
use Illuminate\Support\Facades\Response;

Response::macro('success', function ($data, $message = 'Success') {
    return Response::json([
        'success' => true,
        'message' => $message,
        'data' => $data,
    ]);
});

Response::macro('error', function ($message, $code = 400) {
    return Response::json([
        'success' => false,
        'message' => $message,
    ], $code);
});

Użycie w kontrolerach:

php
public function index()
{
    $users = User::all();
    return response()->success($users, 'Users retrieved successfully');
}

public function show($id)
{
    $user = User::find($id);
    
    if (!$user) {
        return response()->error('User not found', 404);
    }
    
    return response()->success($user);
}

Makra Collection

Makra collection dodają własne metody do manipulacji danymi:

php
use Illuminate\Support\Collection;

Collection::macro('toUpper', function () {
    return $this->map(function ($value) {
        return strtoupper($value);
    });
});

Collection::macro('filterByStatus', function ($status) {
    return $this->filter(function ($item) use ($status) {
        return $item->status === $status;
    });
});

Używanie makr collection:

php
$collection = collect(['hello', 'world']);
$result = $collection->toUpper(); // ['HELLO', 'WORLD']

$users = User::all()->filterByStatus('active');

Makra Request

Makra request dodają własne metody pobierania danych lub walidacji. Laravel ma już w requeście validate() i hasAny(), więc poniższe przykłady używają innych nazw:

php
use Illuminate\Support\Facades\Request;

Request::macro('ids', function (string $key = 'ids'): array {
    return array_map('intval', array_filter((array) $this->input($key)));
});

Request::macro('validateOrNull', function (array $rules): ?array {
    $validator = validator($this->all(), $rules);

    return $validator->fails() ? null : $validator->validated();
});

Makra Query Builder

Rozszerz query builder o niestandardowe metody zapytań:

php
use Illuminate\Database\Query\Builder;

Builder::macro('whereContains', function ($column, $value) {
    return $this->where($column, 'LIKE', "%{$value}%");
});

Builder::macro('whereStatus', function ($status) {
    return $this->where('status', $status);
});

Użycie:

php
$users = DB::table('users')->whereContains('name', 'John')->get();
$activeUsers = DB::table('users')->whereStatus('active')->get();

Makra Eloquent Builder

Podobne do makr query builder, ale specyficznie dla Eloquent:

php
use Illuminate\Database\Eloquent\Builder;

Builder::macro('active', function () {
    return $this->where('status', 'active');
});

Builder::macro('recent', function ($days = 7) {
    return $this->where('created_at', '>=', now()->subDays($days));
});

Używanie makr Eloquent:

php
$activeUsers = User::active()->get();
$recentPosts = Post::recent(14)->get();

Makra String

Rozszerz helper Str o niestandardowe metody manipulacji stringami:

php
use Illuminate\Support\Str;

Str::macro('prefix', function ($string, $prefix) {
    return $prefix . $string;
});

Str::macro('surround', function ($string, $wrapper = '"') {
    return $wrapper . $string . $wrapper;
});
php
echo Str::prefix('world', 'hello '); // hello world
echo Str::surround('quoted'); // "quoted"

Zaawansowane Techniki Makr

Makra z Wieloma Parametrami

Makro to closure, więc przyjmuje dowolne parametry:

php
Collection::macro('groupByMultiple', function (array $keys) {
    return $this->groupBy(function ($item) use ($keys) {
        return implode('-', array_map(fn($key) => $item[$key], $keys));
    });
});

Makra Zwracające Instancję

Dla łańcuchowych makr zwróć $this:

php
Collection::macro('debug', function () {
    dump($this->toArray());
    return $this;
});

// Użycie
collect([1, 2, 3])
    ->debug()
    ->map(fn($n) => $n * 2)
    ->debug();

Klasy Mixin

Do organizowania wielu powiązanych makr użyj klas mixin:

php
namespace App\Mixins;

class ResponseMixin
{
    public function success()
    {
        return function ($data, $message = 'Success') {
            return response()->json([
                'success' => true,
                'message' => $message,
                'data' => $data,
            ]);
        };
    }

    public function error()
    {
        return function ($message, $code = 400) {
            return response()->json([
                'success' => false,
                'message' => $message,
            ], $code);
        };
    }
}

Zarejestruj mixin w swoim service providerze:

php
use Illuminate\Support\Facades\Response;
use App\Mixins\ResponseMixin;

public function boot(): void
{
    Response::mixin(new ResponseMixin());
}

Najlepsze Praktyki

  1. Organizuj Swoje Makra: Rejestruj różne typy makr w osobnych service providerach.
  2. Dokumentuj Swoje Makra: Dodaj komentarze PHPDoc, żeby IDE znało twoje metody:
php
/**
 * @method \Illuminate\Support\Collection toUpper()
 * @method \Illuminate\Support\Collection filterByStatus(string $status)
 */
  1. Używaj Mixinów dla Powiązanej Funkcjonalności: Grupuj powiązane makra w jednej klasie mixin.
  2. Testuj Swoje Makra: Testuj je jednostkowo jak każdy inny kod:
php
public function test_to_upper_macro()
{
    $collection = collect(['hello', 'world']);
    $result = $collection->toUpper();
    
    $this->assertEquals(['HELLO', 'WORLD'], $result->toArray());
}
  1. Unikaj Konfliktów Nazw: Nie używaj nazw istniejących metod Laravela ani takich, które może dodać przyszła wersja. Makro jest wywoływane tylko przez __call, więc natywna metoda o tej samej nazwie wygrywa, a twoje makro jest po cichu ignorowane (dlatego przykłady powyżej unikają whereLike, wrap, hasAny i validate, które już istnieją w Laravelu).

Podsumowanie

Trzymaj makra małe, rejestruj je w service providerze i nadawaj nazwy, których Laravel jeszcze nie zajmuje.

Powiązane artykuły

Wsparcie istniejącego systemu

Potrzebujesz pomocy z działającą aplikacją?

Pomagam firmom rozwijać działające systemy, porządkować wdrożenia i dodawać nowe funkcje bez dokładania chaosu do projektu.

Komentarze (0)
Zaloguj się, aby dodać komentarz

Musisz być zalogowany, aby dodać komentarz.

Zaloguj się

Potrzebujesz kogoś, kto weźmie odpowiedzialność za kolejny krok?

Porozmawiajmy o Twoim projekcie i określmy zakres, który ma sens dla Twoich celów.