بناء واجهة برمجة تطبيقات REST للتدقيق الإملائي العربي باستخدام FlightPHP و ArPHP

تقدم معالجة النصوص العربية تحديات فريدة، والتدقيق الإملائي ليس استثناءً. في هذا المقال، سنستكشف كيفية إنشاء واجهة برمجية من نوع REST للتدقيق الإملائي العربي باستخدام نسخة المُصحِّح المرافقة لمكتبة ArPHP القوية، وباستخدام إطار عمل FlightPHP المصغر.

مقدمة

توفر حزمة ASC (المُصحِّح) من مكتبة ArPHP قدرات ممتازة للتدقيق الإملائي باللغة العربية. يمكننا دمج التدقيق الإملائي العربي في مختلف التطبيقات، بدءًا من نماذج الويب وحتى أنظمة إدارة المحتوى والتطبيقات المحمولة، بواسطة تقديم هذه الميزات عبر واجهة برمجة تطبيقات REST.

المتطلبات الأساسية

للبدء تلزمنا المكونات التالية:

• PHP 7.4 أو أعلى
• Composer
• مكتبة ArPHP
• إطار عمل FlightPHP المصغر

إعداد المشروع

أولاً، لننشئ مشروعًا جديدًا ولنثبت المكونات المطلوبة:

mkdir arabic-spellcheck-api
cd arabic-spellcheck-api
composer require flightphp/core
composer require khaled.alshamma/ar-php

هيكل المشروع

ننشئ هيكل المجلدات كما يلي:

arabic-spellcheck-api/
├── index.php
├── vendor/
└── config/
    └── config.php

التكوين الأساسي

ولإدارة إعدادات FlightPHP ننشئ ملف تكوين بسيط في config/config.php:

<?php
return [
    'debug' => true,
    // أضف المزيد من معلمات التكوين حسب الحاجة
];

تهيئة FlightPHP ومكتبة ArPHP

أول خطوة الآن هي تمهيد كائني FlightPHP و ArPHP:

<?php
require 'vendor/autoload.php';

// تحميل التكوين
$config = require 'config/config.php';

// تهيئة Flight
Flight::set('flight.log_errors', $config['debug']);

// تهيئة كائن العربية
$Arabic = new \ArPHP\I18N\Arabic();
Flight::set('arabic', $Arabic);

// تعريف المسارات
require 'routes.php';

// بدء التطبيق
Flight::start();

تعريف مسارات الواجهة البرمجية

الآن، لننشئ ملف routes.php مع نقاط الواجهة البرمجية المختلفة. اخترنا في هذا المثال إضافة ثلاث نقاط للواجهة كما يُظهر الكود أدناه:

<?php
// التحقق من الكلمات المكتوبة بشكل خاطئ في النص
Flight::route('POST /api/spell/check', function() {
    $request = Flight::request();
    $Arabic = Flight::get('arabic');
    
    // الحصول على النص من جسم الطلب
    $text = $request->data->text;
    
    if (empty($text)) {
        Flight::json(['error' => 'لم يتم تقديم نص'], 400);
        return;
    }
    
    try {
        $misspelledWords = $Arabic->spellGetMisspelled($text);
        Flight::json([
            'status' => 'نجاح',
            'misspelled_words' => $misspelledWords
        ]);
    } catch (Exception $e) {
        Flight::json(['error' => $e->getMessage()], 500);
    }
});

// الحصول على اقتراحات للكلمات المكتوبة بشكل خاطئ
Flight::route('POST /api/spell/suggest', function() {
    $request = Flight::request();
    $Arabic = Flight::get('arabic');
    
    // الحصول على النص من جسم الطلب
    $text = $request->data->text;
    
    if (empty($text)) {
        Flight::json(['error' => 'لم يتم تقديم نص'], 400);
        return;
    }
    
    try {
        $suggestions = $Arabic->spellSuggestCorrections($text);
        Flight::json([
            'status' => 'نجاح',
            'suggestions' => $suggestions
        ]);
    } catch (Exception $e) {
        Flight::json(['error' => $e->getMessage()], 500);
    }
});

// الحصول على الكلمات المكتوبة بشكل خاطئ والاقتراحات في طلب واحد
Flight::route('POST /api/spell/check-and-suggest', function() {
    $request = Flight::request();
    $Arabic = Flight::get('arabic');
    
    // الحصول على النص من جسم الطلب
    $text = $request->data->text;
    
    if (empty($text)) {
        Flight::json(['error' => 'لم يتم تقديم نص'], 400);
        return;
    }
    
    try {
        $misspelledWords = $Arabic->spellGetMisspelled($text);
        $suggestions = $Arabic->spellSuggestCorrections($text);
        
        Flight::json([
            'status' => 'نجاح',
            'misspelled_words' => $misspelledWords,
            'suggestions' => $suggestions
        ]);
    } catch (Exception $e) {
        Flight::json(['error' => $e->getMessage()], 500);
    }
});

خطوة اختيارية: المصادقة

من الضروري إضافة منطق مصادقة للواجهات البرمجية المخصصة للإنتاج. نطبق أدناه طريقة بسيطة لمفتاح الواجهة البرمجية:

<?php
// أضف إلى routes.php

function getRequestHeaders() {
    $headers = array();
    foreach($_SERVER as $key => $value) {
        if (substr($key, 0, 5) <> 'HTTP_') {
            continue;
        }
        $header = str_replace(' ', '-', ucwords(str_replace('_', ' ', strtolower(substr($key, 5)))));
        $headers[$header] = $value;
    }
    return $headers;
}

// برمجية وسيطة لمفتاح واجهة برمجة التطبيقات
Flight::before('start', function() {
    // تخطي المصادقة لمسارات معينة إذا لزم الأمر
    if (Flight::request()->url == '/api/health') {
        return;
    }
    
    $headers = getRequestHeaders();
    $apiKey = isset($headers['Apikey']) ? $headers['Apikey'] : '';
    if (empty($apiKey) || $apiKey != 'YOUR_API_KEY') {    
        Flight::halt(401);
    }
});

// إضافة نقطة نهاية للتحقق من الحالة
Flight::route('GET /api/health', function() {
    Flight::json(['status' => 'ok']);
});

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

فيما يلي أمثلة على كيفية استخدام واجهة برمجة التطبيقات الخاصة بنا مع cURL:

التحقق من الكلمات المكتوبة بشكل خاطئ

curl -X POST \
  http://localhost:8000/api/spell/check \
  -H 'Apikey: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "والان وصلت الحوسبه الكمومية التي تعاتمد على فيزياء الكم. نعم هي في المرحلة التجريبية، ولكن إذا نجحت فستكون هذه الآلات قوية للغاية. لكن لو تركت تطبيقاتها بدون تتظيم وتم تطبيقها في على أرض الواقع، فربما تكون مصدرا لخظر آخر يهدد حياتنا وكوكبنا."
}'

النتيجة:

{
  "status": "نجاح",
  "misspelled_words": [
    "الحوسبه",
    "تعاتمد",
    "تتظيم",
    "لخظر"
  ]
}

اقتراح تصحيحات

curl -X POST \
  http://localhost:8000/api/spell/suggest \
  -H 'Apikey: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "والان وصلت الحوسبه الكمومية التي تعاتمد على فيزياء الكم."
}'

النتيجة:

{
  "status": "نجاح",
  "suggestions": [
    {
      "word": "الحوسبه",
      "suggestion": [
        "الحوسبة",
        "الحسبه"
      ]
    },
    {
      "word": "تعاتمد",
      "suggestion": [
        "تعتمد",
        "تعامد"
      ]
    }
  ]
}

تقييد معدل الاستخدام (request throttling)

للاستخدام في بيئة الإنتاج، يجب علينا تنفيذ تقييد معدل الاستخدام. كما في هذه الطريقة البسيطة باستخدام Redis:

<?php
// تثبيت عميل Redis: composer require predis/predis
$redis = new Predis\Client();

Flight::before('start', function() use ($redis) {
    $apiKey = Flight::request()->query->api_key;
    $ip = $_SERVER['REMOTE_ADDR'];
    
    $key = "ratelimit:{$apiKey}:{$ip}";
    $count = $redis->get($key);
    
    if ($count === null) {
        $redis->setex($key, 3600, 1); // انتهاء صلاحية بعد ساعة واحدة
    } else if ($count < 100) { // 100 طلب في الساعة
        $redis->incr($key);
    } else {
        Flight::json(['error' => 'تم تجاوز الحد المسموح. يرجى المحاولة مرة أخرى لاحقًا.'], 429);
        Flight::stop();
    }
});

اعتبارات الأداء

يمكن أن يكون التدقيق الإملائي العربي كثيف الاستخدام للموارد، لذا ضع في اعتبارك هذه التحسينات عند النشر في بيئات الانتاج:

1. التخزين المؤقت: تخزين نتائج التدقيق الإملائي للكلمات أو العبارات الشائعة
2. حدود حجم النص: تحديد الحجم الأقصى للنص في طلبات واجهة برمجة التطبيقات
3. المعالجة غير المتزامنة: للنصوص الكبيرة، يمكن تنفيذ نظام قوائم الانتظار
4. توزيع الحمل: نشر واجهة برمجة التطبيقات عبر عدة خوادم للتعامل مع الحركة المرورية العالية

خاتمة

في هذا المثال البسيط، أنشأنا واجهة برمجية كاملة الوظائف للتدقيق الإملائي العربي باستخدام FlightPHP و ArPHP.

من خلال الاستفادة من حزمة المُصحِّح ASC القوية من ArPHP، توفر واجهة برمجة التطبيقات الخاصة بنا تدقيقًا إملائيًا عالي الجودة خاصًا باللغة العربية، بما في ذلك اكتشاف الأخطاء الشائعة الخاصة باللغة العربية.