استخدام مكتبة Fractal في إطاري العمل Laravel و Lumen لإنشاء استجابات للواجهات البرمجية (API)

تُعتبر واجهات البرمجة التطبيقية (APIs) حجر الأساس في بنية البرمجيات الحديثة، خاصة في بيئات تعتمد على التفاعل بين الخوادم والعملاء، كتطبيقات الويب والجوال. وفي هذا السياق، يظهر الدور الحاسم لتنظيم وتنسيق الاستجابات الصادرة عن الواجهات البرمجية، من حيث البنية والمحتوى، بما يضمن الاتساق والقابلية للتوسع. مكتبة Fractal التي طورتها شركة The PHP League، تُعد من أبرز الأدوات التي تُستخدم مع إطاري Laravel وLumen لهذا الغرض، حيث تُساعد على تحويل البيانات من مصادرها الأولية (مثل الكيانات أو الكائنات أو المجموعات) إلى تمثيلات متناسقة ومهيكلة جيداً تصلح للنقل عبر HTTP كاستجابات JSON، كما توفر تحكماً دقيقاً في التضمين والتجميع والتنقيح.

يتناول هذا المقال الاستخدام الموسع لمكتبة Fractal ضمن بيئتي Laravel وLumen، موضحاً كيف تسهم هذه المكتبة في تعزيز جودة استجابات الواجهات البرمجية وتحقيق مبدأ فصل الاهتمامات (Separation of Concerns) في تصميم الواجهات البرمجية RESTful.

المفاهيم الأساسية في مكتبة Fractal

قبل الغوص في دمج Fractal مع Laravel أو Lumen، لا بد من استيعاب بعض المفاهيم الجوهرية التي تعتمد عليها هذه المكتبة:

1. التحويل (Transformation)

يقوم المحول (Transformer) بتحويل البيانات الخام (مثل نموذج Eloquent) إلى هيكل يمكن تقديمه كاستجابة API. هذا المحول يُعرّف الطريقة التي يتم بها عرض كل خاصية من خصائص النموذج.

2. المُدمَجَات (Includes)

تتيح مكتبة Fractal تضمين علاقات أو موارد أخرى ضمن نفس الاستجابة بشكل اختياري، مما يسمح بمرونة كبيرة في بناء الاستجابات، وفقًا لما يطلبه العميل.

3. التحزيم (Serialization)

بعد تحويل البيانات، تُحوَّل النتيجة إلى صيغة JSON باستخدام محول تسلسل (Serializer). Fractal توفر مجموعة من المحولات منها DataArraySerializer و ArraySerializer و JsonApiSerializer.

4. الإمكانيات المتقدمة

مثل دعم pagination، والـ meta data، والروابط (links) و الموارد المتداخلة nested resources.

دمج Fractal مع Laravel

Laravel هو إطار عمل غني يوفر دعماً متكاملاً للعديد من الميزات، ويمكن دمج Fractal فيه بسهولة من خلال عدة طرق، أشهرها استخدام حزمة spatie/laravel-fractal.

تثبيت الحزمة

bash
CopyEdit
composer require spatie/laravel-fractal

بعد التثبيت، يمكن نشر إعدادات الحزمة باستخدام:

bash
CopyEdit
php artisan vendor:publish --provider="Spatie\Fractal\FractalServiceProvider"

إعداد Transformer

php
CopyEdit
use League\Fractal\TransformerAbstract;

class UserTransformer extends TransformerAbstract
{
    public function transform(User $user)
    {
        return [
            'id'    => (int) $user->id,
            'name'  => $user->name,
            'email' => $user->email,
        ];
    }
}

استخدام Fractal في الـ Controller

php
CopyEdit
use App\Models\User;
use App\Transformers\UserTransformer;
use Spatie\Fractal\Facades\Fractal;

class UserController extends Controller
{
    public function index()
    {
        $users = User::all();
        return Fractal::collection($users, new UserTransformer())->respond();
    }

    public function show($id)
    {
        $user = User::findOrFail($id);
        return Fractal::item($user, new UserTransformer())->respond();
    }
}

دمج Fractal مع Lumen

رغم أن Lumen هو إطار عمل أخف وأبسط من Laravel، فإنه يدعم معظم مكتبات Laravel، بما في ذلك Fractal.

التثبيت في Lumen

أولاً، يجب تثبيت مكتبة Fractal الأساسية:

bash
CopyEdit
composer require league/fractal

ولعدم توفر دعم مباشر للحزمة الخاصة بـ Spatie في Lumen، يتم العمل مع Fractal بشكل يدوي أكثر.

إعداد Transformer يدوي في Lumen

php
CopyEdit
use League\Fractal\TransformerAbstract;

class ArticleTransformer extends TransformerAbstract
{
    public function transform(Article $article)
    {
        return [
            'id'      => (int) $article->id,
            'title'   => $article->title,
            'content' => $article->body,
        ];
    }
}

استخدام Fractal في Controller داخل Lumen

php
CopyEdit
use League\Fractal\Resource\Item;
use League\Fractal\Resource\Collection;
use League\Fractal\Manager;
use App\Models\Article;
use App\Transformers\ArticleTransformer;

class ArticleController extends Controller
{
    public function show($id)
    {
        $article = Article::findOrFail($id);

        $fractal = new Manager();
        $resource = new Item($article, new ArticleTransformer());
        $data = $fractal->createData($resource)->toArray();

        return response()->json($data);
    }

    public function index()
    {
        $articles = Article::all();

        $fractal = new Manager();
        $resource = new Collection($articles, new ArticleTransformer());
        $data = $fractal->createData($resource)->toArray();

        return response()->json($data);
    }
}

دعم الاستجابات القابلة للتوسعة (Includes)

يمكن لمكتبة Fractal دعم العلاقات المرتبطة مثل user->posts باستخدام خاصية الـ includes:

مثال:

php
CopyEdit
class UserTransformer extends TransformerAbstract
{
    protected $defaultIncludes = [
        'posts'
    ];

    public function transform(User $user)
    {
        return [
            'id'   => (int) $user->id,
            'name' => $user->name,
        ];
    }

    public function includePosts(User $user)
    {
        $posts = $user->posts;

        return $this->collection($posts, new PostTransformer);
    }
}

وعند استدعاء البيانات، يمكن تمكين علاقات اختيارية:

php
CopyEdit
$fractal = new Manager();
$fractal->parseIncludes('posts.comments');

إدارة Pagination في Fractal

Fractal يوفر تكامل سلس مع صفحات Laravel باستخدام IlluminatePaginatorAdapter.

مثال في Laravel:

php
CopyEdit
use League\Fractal\Pagination\IlluminatePaginatorAdapter;

$users = User::paginate(10);
$resource = new Collection($users->getCollection(), new UserTransformer());
$resource->setPaginator(new IlluminatePaginatorAdapter($users));
$data = fractal()->createData($resource)->toArray();

return response()->json($data);

مثال عملي شامل

فيما يلي نموذج عملي يوضح تسلسل الاستخدام:

php
CopyEdit
class ProductTransformer extends TransformerAbstract
{
    public function transform(Product $product)
    {
        return [
            'id'          => $product->id,
            'name'        => $product->name,
            'price'       => (float) $product->price,
            'description' => $product->description,
        ];
    }
}

class ProductController extends Controller
{
    public function index()
    {
        $products = Product::paginate(15);
        $resource = new Collection($products->getCollection(), new ProductTransformer());
        $resource->setPaginator(new IlluminatePaginatorAdapter($products));

        return response()->json(fractal()->createData($resource)->toArray());
    }
}

مقارنة مبسطة بين الطرق التقليدية وFractal

فوائد اعتماد Fractal في بيئات إنتاجية

1. تنظيم بنية الاستجابات بشكل منهجي ومتناسق، مما ينعكس إيجاباً على تجربة المستهلك للواجهة البرمجية.

2. تحقيق مبدأ فصل المسؤوليات، حيث يتم فصل منطق التحويل عن وحدات التحكم.

3. سهولة الصيانة والتوسع في المستقبل، خاصةً عند نمو الكود أو تعدد نقاط النهاية.

4. مرونة كبيرة في تضمين البيانات المرتبطة، مع تحكم ديناميكي في المحتوى المعاد.

5. دعم متكامل للتقسيم الصفحي (Pagination)، والبيانات الوصفية (Meta data).

الخاتمة

إن استخدام مكتبة Fractal في Laravel وLumen يُعد نهجاً احترافياً لتنظيم وتحسين استجابات الواجهات البرمجية، حيث تُمكّن المطور من التحكم الكامل في شكل ومحتوى الاستجابة مع الحفاظ على قابلية التوسع وسهولة الصيانة. هذا الأسلوب يُعتبر معياراً فعّالاً في بناء واجهات برمجية RESTful عالية الجودة، ويُسهّل العمل الجماعي وتكامل الأنظمة على نطاق واسع.

المراجع:

1. League Fractal: https://fractal.thephpleague.com

2. Spatie Laravel Fractal: https://github.com/spatie/laravel-fractal