Twig هو محرك قوالب مخصص لعرض HTML عند تطوير تطبيقات الويب باستخدام Symfony.
ومع ذلك، تمتد مرونة Twig إلى ما هو أبعد من إنشاء صفحات HTML فقط. يمكن أن تكون أداة قوية لتوصيل المحتوى عبر قنوات متعددة، مثل إنشاء ملفات Markdown، ومخرجات JSON، وحتى النص العادي، كل ذلك من نفس مجموعة المحتوى.

تتيح لك هذه القدرة على التكيف إنشاء محتوى لقنوات مختلفة.

يمكنك استخدام Twig لإنشاء HTML وMarkdown وJSON والنص وما إلى ذلك

حالة الاستخدام: جلب وصفة وعرضها كـ Markdown باستخدام Symfony

في هذا المثال، نستخدم عميل HTTP الخاص بـ Symfony لجلب وصفة من واجهة برمجة تطبيقات خارجية (https://dummyjson.com/recipes/1) وعرضها كمستند Markdown باستخدام Twig.
يوضح هذا الأسلوب كيف يمكنك الجمع بين حزم Symfony القوية، مثل عميل Symfony HTTP لاسترداد البيانات الخارجية وTwig لعرض طرق العرض، لتقديم المحتوى عبر قنوات متعددة، مثل تقارير Markdown في أداة سطر الأوامر.

يقوم الأمر/البرنامج النصي الذي سنقوم بإنشائه بجلب بيانات الوصفة (العنوان والوصف والمكونات والتعليمات) من واجهة برمجة التطبيقات (API)، ومعالجتها، ثم استخدام Twig لإخراج المحتوى بتنسيق Markdown منظم. توضح حالة الاستخدام العملي هذه كيفية استخدام Twig خارج قوالب الويب، مما يجعله متعدد الاستخدامات لإنشاء محتوى بتنسيقات مختلفة.

لذا، سنستخدم:

• Symfony Console المكون https://symfony.com/doc/current/components/console.html لبناء أداة سطر الأوامر
• عميل Symfony HTTP https://symfony.com/doc/current/http_client.html لجلب واستخدام HTTP API
• Symfony Twig https://twig.symfony.com/doc/3.x/intro.html#installation لعرض البيانات
• الوصفات API : سنختار وصفة "وهمية" https://dummyjson.com/recipes/1 لإظهار وتوضيح عملية استرداد JSON منظم وتحويله إلى ملف تخفيض السعر .

تثبيت مكونات Symfony الضرورية

تأكد من تثبيت المكونات المطلوبة لطلبات HTTP وإنشاء الأوامر:

composer require symfony/http-client symfony/console twig/twig

قم بإنشاء أمر Symfony

أولاً، لنقم بإنشاء أمر Symfony جديد.

إذا كنت تريد قراءة المزيد حول كيفية إنشاء أداة سطر أوامر باستخدام مكون Symfony Command، فقد كتبت مقالة محددة حول هذا: https://dev.to/robertobutti/building-a-command-line-tool -مع-php-and-symfony-console-4n6g

فئات الأوامر، عادةً ما تنتقل إلى دليل src/Commands.

# create a new empty directory
mkdir -p src/Commands
# create a new empty file
touch src/Commands/FetchRecipeCommand.php

فئة الأوامر (على سبيل المثال، src/Commands/FetchRecipeCommand.php):

setName('recipe')
            ->setDescription('Prints a recipe in Markdown')
            ->setHelp('This command prints a simple recipe in Markdown.');
        // Step 1: loading the Twig environment
        $loader = new \Twig\Loader\FilesystemLoader(__DIR__ . '/../resources/views');
        $twig = new \Twig\Environment(
            $loader,
            // Optional: Enable caching for better performance
            /*[
                'cache' => __DIR__ . '/../../cache',
            ]*/
        );

        $this->twig = $twig;
        parent::__construct();
    }

    protected function configure()
    {
        $this->setDescription('Fetches a recipe from an API and renders it as Markdown');
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        // Step 2: Initialize the HTTP client and fetch the recipe
        $client = HttpClient::create();
        $response = $client->request('GET', 'https://dummyjson.com/recipes/1');

        // Step 3: obtain the array of info
        $recipeData = $response->toArray();

        // Step 4: Render the template using Twig, returning a string
        $markdownOutput = $this->twig->render('recipe.md.twig', $recipeData);

        // Step 5: Output the generated Markdown
        $output->writeln($markdownOutput);

        return Command::SUCCESS;
    }
}

إليك شرح تفصيلي لكل خطوة في مثال FetchRecipeCommand.

تفصيل خطوة بخطوة

الخطوة 1: تحميل بيئة الغصين

لاستخدام Twig خارج سياق الويب النموذجي، كما هو الحال في أداة سطر أوامر PHP، تحتاج أولاً إلى تهيئته يدويًا عبر فئة Twig\Environment. فيما يلي مثال لإعداد Twig في أمر وحدة التحكم:

$loader = new \Twig\Loader\FilesystemLoader(__DIR__ . '/../resources/views');
$twig = new \Twig\Environment(
    $loader,
    // Optional: Enable caching for better performance
    /*[
        'cache' => __DIR__ . '/../../cache',
    ]*/
);
$this->twig = $twig;

توضيح:

• تتم تهيئة بيئة twig عن طريق إنشاء FilesystemLoader الذي يخبر Twig بمكان العثور على القوالب. تشير هذه الحالة إلى مجلد src/resources/views حيث يتم تخزين قوالب Twig الخاصة بك.
• بعد ذلك، يتم إنشاء بيئة $twig وتكون مسؤولة عن عرض القوالب. يمكن تمكين التخزين المؤقت الاختياري لتحسين الأداء عن طريق تخزين القوالب المترجمة مسبقًا.
• أخيرًا، تم تعيين بيئة $twig التي تمت تهيئتها إلى $this->twig لاستخدامها لاحقًا (في طريقة التنفيذ ()).

الخطوة 2: تهيئة عميل HTTP وإحضار الوصفة

$client = HttpClient::create();
$response = $client->request('GET', 'https://dummyjson.com/recipes/1');

توضيح:

• يتم إنشاء عميل Symfony HTTP باستخدام طريقة HttpClient::create()، والتي تسمح للأمر بتنفيذ طلبات HTTP.
• لجلب وصفة، تقوم طريقة request() بتنفيذ طلب GET إلى عنوان URL المحدد (https://dummyjson.com/recipes/1).
• ترجع واجهة برمجة التطبيقات استجابة JSON المخزنة في متغير الاستجابة $.

الخطوة 3: الحصول على مجموعة من المعلومات

$recipeData = $response->toArray();

توضيح:

• تقوم طريقة toArray () بتحويل استجابة JSON من واجهة برمجة التطبيقات (API) إلى مصفوفة PHP. تحتوي هذه المصفوفة على بيانات الوصفة (مثل الاسم والمكونات والتعليمات)، والتي سيتم استخدامها لملء قالب Twig في الخطوة التالية.

الخطوة 4: عرض القالب باستخدام Twig

$markdownOutput = $this->twig->render('recipe.md.twig', $recipeData);

توضيح:

• تنشئ طريقة render() الخاصة ببيئة Twig مخرجات Markdown. يقوم بتحميل القالب (recipe.md.twig) من المجلد src/resources/views.
• يتم تمرير بيانات الوصفة التي تم جلبها من واجهة برمجة التطبيقات (بيانات الوصفة) إلى القالب، حيث ستحل محل العناصر النائبة مثل اسم الوصفة والمكونات والتعليمات، مما يؤدي إلى إنشاء ملف Markdown منسق بالكامل.
• يتم تخزين محتوى Markdown المعروض (السلسلة التي يتم إرجاعها بواسطة طريقة render()) في المتغير $markdownOutput.

الخطوة 5: إنشاء مخرجات لـ Markdown الذي تم إنشاؤه

$output->writeln($markdownOutput);

توضيح:

• تتم طباعة محتوى Markdown النهائي على وحدة التحكم باستخدام طريقة $output->writeln(). تقوم هذه الطريقة بإخراج السلسلة إلى وحدة التحكم، مما يسمح للمستخدمين برؤية الوصفة المنسقة بتنسيق Markdown (في النهاية، يمكنك إعادة توجيه الإخراج إلى ملف في الصدفة).

إنشاء ملف البداية

يجب عليك إنشاء ملف بداية للسماح للمستخدم بتشغيل أمر Symfony مباشرة من الصدفة. (في هذه المقالة، نحن لا نقوم بإنشاء تطبيق Symfony؛ بل نقوم ببناء برنامج نصي PHP باستخدام حزم Symfony.)
في دليل المشروع، حيث يوجد ملف الملحن.json وحيث يوجد دليل src، يمكنك إنشاء ملف تطبيقي.

#!/usr/bin/env php
setDefaultCommand("recipe");

$app->add(new FetchRecipeCommand());


$app->run();

لاستخدام مساحات الأسماء والفئات بشكل صحيح تأكد من تعيين قسم التحميل التلقائي في ملف Composer.json:

{
    "require": {
        "symfony/http-client": "^7.1",
        "symfony/console": "^7.1",
        "twig/twig": "^3.14"
    },
    "autoload": {
        "psr-4": {
            "MyExample\\": "src/"
        }
    }
}

إذا قمت بتغيير قسم التحميل التلقائي أقترح تفريغ ملف التحميل التلقائي:

composer dump-autoload

الآن، عليك إنشاء قالب/عرض Twig لعرض البيانات التي تم استردادها بواسطة واجهة برمجة التطبيقات.

قم بإنشاء قالب/عرض Twig للوصفة

بعد ذلك، قم بإنشاء قالب/عرض Twig لعرض الوصفة بتنسيق Markdown.
يجب أن يوضع هذا القالب في دليل العروض (على سبيل المثال، src/resources/view/recipe.md.twig).

# Recipe: {{ name }}

- Preparation time: {{ prepTimeMinutes }} minutes
- Cooking time {{ cookTimeMinutes }} minutes
- Difficulty level: {{ difficulty }}
- Cuisine: {{ cuisine }}
- Servings {{ servings }} people, with {{ caloriesPerServing }} calories per person

## Ingredients:

{% for ingredient in ingredients %}
- {{ ingredient }}
{% endfor %}

## Instructions:

{% for instruction in instructions %}
- {{ instruction }}
{% endfor %}

Enjoy!

سيعرض ملف عرض Twig هذا الوصفة بتنسيق Markdown، مع أقسام لاسم الوصفة والمكونات والتعليمات.

تشغيل الأمر

لتنفيذ الأمر، قم بتشغيل ما يلي في المحطة:

php my-app

في حالة وجود أكثر من أمر، يمكنك تشغيل:

php m-app recipe

لرؤية جميع الأوامر المتوفرة:

php my-app list

خاتمة

باستخدام هذا الأسلوب، يمكنك بسهولة استرداد البيانات من واجهة برمجة التطبيقات الخارجية باستخدام عميل HTTP الخاص بـ Symfony، ومعالجة الاستجابة، وتقديم الإخراج بتنسيق منظم باستخدام Twig. في هذه الحالة، يُخرج الأمر وصفة كـ Markdown، ولكن يمكن تكييف هذه التقنية مع أي محتوى أو نوع بيانات آخر تحتاج إلى معالجته.
استمتع بوصفتك!