إنشاء واجهة برمجية بسيطة باستخدام إطار العمل المصغّر Lumen

Lumen هو إطار عمل مصغّر Micro-framework مبني باستخدام إطار العمل Laravel، وهما من صنع Taylor Otwell. صُمّم Lumen لتطوير الخدمات المصغّرة مثل التطبيقات الصغيرة أو خدمات الويب، والهدف من تطويره هو الحصول على أقصى قدر من السرعة، فقد تم استبدال مكوّن التوجيه Symfony في Laravel بـ FastRoute في Lument لتحسين الأداء وزيادة السرعة. في هذا الدرس سننشئ واجهة برمجية بنمط RESTful، وستعمل هذه الواجهة البرمجية على تخزين وعرض المعلومات الخاصّة بالكتب.

تثبيت Lumen

سنستخدم Composer لتثبيت lumen، لذا سنتحقّق من وجود هذه المكتبة في النظام، وذلك بكتابة الأمر التالي في الطرفية أو في سطر الأوامر:

composer

إن ظهرت أوامر Composer فهذا يعني أنّه مثبت في الجهاز، أمّا في حالة عدم تثبيت Composer يمكنك الاطلاع على طريقة التثبيت في هذا المقال. بعد تثبيت composer توجّه إلى المجلّد الجذر في الخادوم:

cd /var/www/html 

لمستخدمي نظام ويندوز سنفترض أن المستخدم يمتلك نسخة من خادوم Wamp في الجهاز، لذا يمكن التوجّه إلى المجلّد الجذر في الخادوم بواسطة الأمر التالي:

cd wamp\www

والآن سنخبر composer بأنّ ينشئ مشروع Lumen باسم “lumen_rest_ce” باستخدام حزمة “laravel/lumen”:

composer create-project laravel/lumen lumen_rest_ce

سينشئ هذا الأمر مجلّدًا باسم “lumen_rest_ce” ويثبت جميع ملفّات إطار العمل Lumen إضافة إلى جميع الاعتماديات المتعلّقة به. أداة Artisan موجودة في Lumen كما هو الحال في Laravel، ولكنّها تدعم عددًا أقلّ من الأوامر، ويمكنك الاطلاع على قائمة الأوامر بكتابة الأمر التالي في سطر الأوامر:

php artisan

لاحظ أنّ الأمر serve والمسؤول عن تشغيل التطبيق على الخادوم غير متوفّر في Lumen لذا سنستعين بخادوم التطوير الخاصّ بلغة PHP لتشغيل Lumen وكما يلي:

php -S localhost:8000 -t public

افتح المتصفّح الآن وتوجّه إلى العنوان localhost:8000. إن ظهر لك رقم الإصدار الخاص بـ Lumen فهذا يعني أنّ عملية التثبيت قد تمّت بنجاح.

الإعدادات

أنشئ قاعدة بيانات mysql باستخدام phpmyadmin أو أي عميل Mysql آخر، ثمّ عدّل ملف إعدادات Lumen في مجلد المشروع والذي يحمل الاسم “lumen_rest_ce/.env” بالصورة التالية:

DB_CONNECTION=mysql
DB_HOST=localhost
DB_DATABASE=lumen_rest_ce
DB_USERNAME=root
DB_PASSWORD=your_password

افتح الملف lumen_rest_ce/bootstrap/app.php وأزل علامات التعليق من السطرين التاليين:

$app->withFacades();

$app->withEloquent();

إزالة التعليق عن هذين السطرين يسمح لنا باستخدام فئة Facade و Eloquent ORM في مشروعنا.

التهجير Migration

سنكتب الآن مخطّط قاعدة البيانات ونهيّئه لعملية التهجير، حيث سننشئ جدولًا باسم book يتضمّن ستة أعمدة. المعرّف id (قيمته رقمية int وتتزايد تلقائيًا)، العنوان title (من نوع varchar) الكاتب author (من نوع varchar)، الرقم المعياري الدولي للكتاب isbn (من نوع varchar) وحقلي تاريخ الإنشاء وتاريخ التعديل. سنستخدم عملية التهجير والتي هي بمثابة نظام إدارة نسخ خاصّ بقواعد البيانات.

اكتب الأمر التالي في سطر الأوامر:

php artisan make:migration create_books_table --create=books

سينشئ هذا الأمر ملف تهجير في المجلد dbaatase/migration. يتضمّن هذا الملف صنفًا يحمل الاسم CreateBooksTable والذي يضمّ بدوره تابعين الأول هو up حيث سنكتب مخطّط البيانات، أما الآخر فهو down وهو التابع المسؤول عن حذف الجدول.

عدّل الملف ليصبح بالصورة التالية:

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Migrations\Migration;

class CreateBooksTable extends Migration {

    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::create('books', function(Blueprint $table)
        {
            $table->increments('id');
            $table->string('title');
            $table->string('author');
            $table->string('isbn');
            $table->timestamps();
        });
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Schema::drop('books');
    }

}

لإنشاء الجدول في قاعدة البيانات سنحتاج إلى تهجير أو تنفيذ ملف التهجير الذي أنشأناه قبل قليل وذلك بواسطة الأمر التالي:

php artisan migrate

النموذج Model

أنشئ الآن نموذج Book ضمن الملف app/Book.php وأضف إليه الشيفرة التالية:

<?php namespace App;

use Illuminate\Database\Eloquent\Model;

class Book extends Model
{

     protected $fillable = ['title', 'author', 'isbn'];

}
?>

أنشئ كذلك ملفّ المتحكّم BookController.php في المجلد app/Http/Controllers وأضف إليه الشيفرة التالية:

<?php

namespace App\Http\Controllers;

use App\Book;
use App\Http\Controllers\Controller;
use Illuminate\Http\Request;


class BookController extends Controller{

 .....
 .....

}
?>

التوجيه Routing

افتح الملف web.php في المجلد routes وستجد أنّه يتضمن مسارًا معرّفًا مسبقًا:

$app->get('/', function() use ($app) {

لغرض كتابة واجهة برمجية بنمط RESTful سنحتاج إلى كتابة المزيد من المسارات وتوابع المتحكّمات المرتبطة بها، وحسب الجدول التالي:

لاحظ أنّنا أضفنا v1 إلى جميع المسارات ونقصد به الإصدار الأول، وهذا من الممارسات التي ينصح باتباعها عند إنشاء خدمات الويب.

حسب الجدول السابق فإن ملف web.php سيبدو كالتالي:

$app->get('/', function() use ($app) {
    return 'Lumen RESTful API By Hsoub Academy  (<a class="vglnk" href="https://academy.hsoub.com" rel="nofollow"><span>https</span><span>://</span><span>academy.hsoub</span><span>.</span><span>com</span></a>)';
});


$app->get('api/v1/book','App\Http\Controllers\BookController@index');

$app->get('api/v1/book/{id}','App\Http\Controllers\BookController@getbook');

$app->post('api/v1/book','App\Http\Controllers\BookController@createBook');

$app->put('api/v1/book/{id}','App\Http\Controllers\BookController@updateBook');

$app->delete('api/v1/book/{id}','App\Http\Controllers\BookController@deleteBook');

يمكننا كذلك تجميع المسارات حسب لاحقة معيّنة أو حسب نطاقات الأسماء، وبهذا لن نكون بحاجة إلى إضافة api/vi ولا إلى كتابة App\Http\Controllers في جميع المسارات.

عدّل الشيفرة السابقة لتصبح بالصورة التالية:

$app->get('/', function() use ($app) {
    return 'Lumen RESTful API By Hsoub Academy  (<a class="vglnk" href="https://academy.hsoub.com" rel="nofollow"><span>https</span><span>://</span><span>academy.hsoub</span><span>.</span><span>com</span></a>)';
});

$app->group(['prefix' => 'api/v1','namespace' => 'App\Http\Controllers'], function($app)
{
    $app->get('book','BookController@index');

    $app->get('book/{id}','BookController@getbook');

    $app->post('book','BookController@createBook');

    $app->put('book/{id}','BookController@updateBook');

    $app->delete('book/{id}','BookController@deleteBook');
});

المتحكّم

والآن عدّل الملف BookController.php وأضف إليه التوابع التي عرّفناها في ملف web.php السابق:

<?php

namespace App\Http\Controllers;

use App\Book;
use App\Http\Controllers\Controller;
use Illuminate\Http\Request;


class BookController extends Controller{


    public function index(){

        $Books  = Book::all();

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

    }

    public function getBook($id){

        $Book  = Book::find($id);

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

    public function createBook(Request $request){

        $Book = Book::create($request->all());

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

    }

    public function deleteBook($id){
        $Book  = Book::find($id);
        $Book->delete();

        return response()->json('deleted');
    }

    public function updateBook(Request $request,$id){
        $Book  = Book::find($id);
        $Book->title = $request->input('title');
        $Book->author = $request->input('author');
        $Book->isbn = $request->input('isbn');
        $Book->save();

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

}

اختبار الواجهة البرمجية

أصبحت الواجهة البرمجية جاهزة الآن للاختبار، وسنستخدم الأداة CURL لإجراء الاختبار:

curl -I <a class="vglnk" href="http://localhost:8000/api/v1/book" rel="nofollow"><span>http</span><span>://</span><span>localhost</span><span>:</span><span>8000</span><span>/</span><span>api</span><span>/</span><span>v1</span><span>/</span><span>book</span></a>

curl -v -H "Accept:application/json" <a class="vglnk" href="http://localhost:8000/api/v1/book/2" rel="nofollow"><span>http</span><span>://</span><span>localhost</span><span>:</span><span>8000</span><span>/</span><span>api</span><span>/</span><span>v1</span><span>/</span><span>book</span><span>/</span><span>2</span></a>

curl -i -X POST -H "Content-Type:application/json" <a class="vglnk" href="http://localhost:8000/api/v1/book" rel="nofollow"><span>http</span><span>://</span><span>localhost</span><span>:</span><span>8000</span><span>/</span><span>api</span><span>/</span><span>v1</span><span>/</span><span>book</span></a> -d '{"title":"Test Title","author":"test author","isbn":"12345"}'

curl -v -H "Content-Type:application/json" -X PUT <a class="vglnk" href="http://localhost:8000/api/v1/book" rel="nofollow"><span>http</span><span>://</span><span>localhost</span><span>:</span><span>8000</span><span>/</span><span>api</span><span>/</span><span>v1</span><span>/</span><span>book</span></a> -d '{"title":"Test updated title","author":"test upadted author","isbn":"1234567"}'

curl -i -X DELETE <a class="vglnk" href="http://localhost:8000/api/v1/book/2" rel="nofollow"><span>http</span><span>://</span><span>localhost</span><span>:</span><span>8000</span><span>/</span><span>api</span><span>/</span><span>v1</span><span>/</span><span>book</span><span>/</span><span>2</span></a>

تتيح الإضافة Postman إجراء الاختبارات على الواجهات البرمجية بنمط RESTful وبسهولة. بعد تثبيت هذه الإضافة توجّه في متصفح Chrome إلى العنوان chrome://apps/ لعرض الإضافات المثبّتة وتشغيل POSTMAN.

ختامًا

ها قد أصبحت الواجهة البرمجية البسيطة التي أنشأناها جاهزة، ولكن لا زال ينقصها الكثير من الخصائص كالاستثياق والتحقّق من البيانات ومعالجة الأخطاء وغير ذلك الكثير.

ترجمة - وبتصرّف - للمقال RESTful API in Lumen, A Laravel Micro Framework لصاحبه Arkaprava Majumder.