Laravel 12 Makra: Kompletny Przewodnik

Makra w Laravel są jedną z najpotężniejszych, a jednocześnie często niedocenianych funkcji frameworka. Pozwalają one rozszerzać podstawowe klasy Laravel o niestandardową funkcjonalność bez modyfikowania kodu źródłowego frameworka. W tym kompleksowym przewodniku zbadamy, jak tworzyć i używać makr w Laravel 12 oraz przeanalizujemy różne dostępne typy.

Czym Są Makra?

Makra wykorzystują magiczną metodę PHP __call do dodawania niestandardowych metod do klas, które używają traitu Macroable. Oznacza to, że możesz dynamicznie wstrzykiwać własną funkcjonalność do podstawowych komponentów Laravel, czyniąc swój kod bardziej ekspresyjnym i wielokrotnego użytku.

Tworzenie Podstawowych Makr

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

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:

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

Rodzaje Makr

Laravel 12 obsługuje makra w różnych komponentach. Przyjrzyjmy się najbardziej powszechnie używanym:

Makra Response

Makra response pozwalają tworzyć niestandardowe formaty odpowiedzi, których możesz używać wielokrotnie w całej aplikacji:

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:

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 są szczególnie przydatne do dodawania niestandardowych metod manipulacji danymi:

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:

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

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

Makra Request

Makra request pomagają dodawać niestandardowe metody walidacji lub pobierania danych:

use Illuminate\Support\Facades\Request;

Request::macro('hasAny', function (array $keys) {
    foreach ($keys as $key) {
        if ($this->has($key)) {
            return true;
        }
    }
    return false;
});

Request::macro('validate', function (array $rules) {
    return validator($this->all(), $rules)->validate();
});

Makra Query Builder

Rozszerz query builder o niestandardowe metody zapytań:

use Illuminate\Database\Query\Builder;

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

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

Użycie:

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

Makra Eloquent Builder

Podobne do makr query builder, ale specyficznie dla Eloquent:

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:

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

Makra String

Rozszerz helper Str o niestandardowe metody manipulacji stringami:

use Illuminate\Support\Str;

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

Str::macro('wrap', function ($string, $wrapper = '"') {
    return $wrapper . $string . $wrapper;
});

Zaawansowane Techniki Makr

Makra z Wieloma Parametrami

Makra mogą przyjmować wiele parametrów i używać zamknięć:

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:

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:

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:

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

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

Najlepsze Praktyki

Pracując z makrami w Laravel 12, pamiętaj o tych najlepszych praktykach:

  1. Organizuj Swoje Makra: Twórz dedykowane service providery dla różnych typów makr, aby utrzymać porządek w kodzie.
  2. Dokumentuj Swoje Makra: Dodawaj komentarze PHPDoc, aby pomóc IDE zrozumieć twoje niestandardowe metody:
/**
 * @method static \Illuminate\Support\Collection toUpper()
 * @method static \Illuminate\Support\Collection filterByStatus(string $status)
 */
  1. Używaj Mixinów dla Powiązanej Funkcjonalności: Grupuj powiązane makra w klasy mixin dla lepszej organizacji.
  2. Testuj Swoje Makra: Pisz testy jednostkowe dla swoich niestandardowych makr, aby upewnić się, że działają zgodnie z oczekiwaniami:
public function test_to_upper_macro()
{
    $collection = collect(['hello', 'world']);
    $result = $collection->toUpper();
    
    $this->assertEquals(['HELLO', 'WORLD'], $result->toArray());
}
  1. Unikaj Konfliktów Nazw: Uważaj, aby nie nadpisywać istniejących metod Laravel ani nie tworzyć makr o nazwach, które mogą kolidować z przyszłymi wersjami Laravel.

Podsumowanie

Makra są potężną funkcją w Laravel 12, która pozwala elegancko rozszerzać funkcjonalność frameworka. Niezależnie od tego, czy dodajesz niestandardowe formaty odpowiedzi, metody collection czy helpery query buildera, makra pomagają pisać czystszy, bardziej ekspresyjny kod. Rozumiejąc różne typy makr i przestrzegając najlepszych praktyk, możesz wykorzystać tę funkcję do tworzenia bardziej łatwej w utrzymaniu i przyjaznej dla programistów aplikacji.

Komentarze (0)
Zostaw komentarz

© 2026 Wszelkie prawa zastrzeżone.