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:
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
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:
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 dodają własne metody do 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 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:
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ń:
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:
$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:
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('surround', function ($string, $wrapper = '"') {
return $wrapper . $string . $wrapper;
});
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:
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
- Organizuj Swoje Makra: Rejestruj różne typy makr w osobnych service providerach.
- Dokumentuj Swoje Makra: Dodaj komentarze PHPDoc, żeby IDE znało twoje metody:
/**
* @method \Illuminate\Support\Collection toUpper()
* @method \Illuminate\Support\Collection filterByStatus(string $status)
*/
- Używaj Mixinów dla Powiązanej Funkcjonalności: Grupuj powiązane makra w jednej klasie mixin.
- Testuj Swoje Makra: Testuj je jednostkowo jak każdy inny kod:
public function test_to_upper_macro()
{
$collection = collect(['hello', 'world']);
$result = $collection->toUpper();
$this->assertEquals(['HELLO', 'WORLD'], $result->toArray());
}
- 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,hasAnyivalidate, 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.