使用 Twig 透過 PHP 渲染 Markdown

發佈於2024-11-08

Using Twig for rendering Markdown with PHP

Twig 是使用 Symfony 开发 Web 应用程序时渲染 HTML 的首选模板引擎。
然而，Twig 的灵活性不仅仅限于生成 HTML 页面。它可以成为跨多个渠道交付内容的强大工具，例如生成 Markdown 文件、JSON 输出，甚至纯文本，所有这些都来自同一组内容。

这种适应性允许您为不同的渠道创建内容。

您可以使用 Twig 生成 HTML、Markdown、JSON、文本等

用例：使用 Symfony 获取并渲染配方为 Markdown

在此示例中，我们使用 Symfony 的 HTTP 客户端从外部 API (https://dummyjson.com/recipes/1) 获取配方，并使用 Twig 将其呈现为 Markdown 文档。
这种方法展示了如何结合 Symfony 强大的包（例如用于外部数据检索的 Symfony HTTP 客户端和用于渲染视图的 Twig）来跨多个渠道交付内容，例如命令行工具中的 Markdown 报告。

我们要构建的命令/脚本从 API 中获取食谱数据（标题、描述、成分和说明），对其进行处理，然后使用 Twig 以结构化 Markdown 格式输出内容。这个实际用例说明了如何在 Web 模板之外使用 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 并将其转换为 Markdown 文件的过程.

安装必要的 Symfony 组件

确保您已安装 HTTP 请求和创建命令所需的组件：

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

创建 Symfony 命令

首先，让我们创建一个新的 Symfony 命令。

如果您想了解有关如何使用 Symfony Command 组件创建命令行工具的更多信息，我写了一篇关于此的具体文章：https://dev.to/robertobutti/building-a-command-line-tool -with-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环境

要在典型的 Web 上下文之外使用 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 来初始化的，该 FilesystemLoader 告诉 Twig 在哪里可以找到模板。本例指向存储 Twig 模板的 src/resources/views 文件夹。
然后，$twig 环境被实例化并负责渲染模板。可以启用可选缓存，通过存储预编译模板来提高性能。
最后将初始化的$twig环境赋值给$this->twig供以后使用（在execute()方法中）。

第 2 步：初始化 HTTP 客户端并获取配方

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

解释：

Symfony HTTP 客户端是使用 HttpClient::create() 方法创建的，该方法允许命令执行 HTTP 请求。
要获取菜谱，request() 方法会对指定的 URL (https://dummyjson.com/recipes/1) 执行 GET 请求。
API 返回存储在 $response 变量中的 JSON 响应。

第三步：获取信息数组

$recipeData = $response->toArray();

解释：

toArray() 方法将来自 API 的 JSON 响应转换为 PHP 数组。该数组包含食谱的数据（例如名称、成分、说明），这些数据将用于在下一步中填充 Twig 模板。

第四步：使用Twig渲染模板

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

解释：

Twig 环境的 render() 方法生成 Markdown 输出。它从 src/resources/views 文件夹加载模板 (recipe.md.twig)。
从 API 获取的菜谱数据 ($recipeData) 被传递到模板中，它将替换菜谱名称、成分和说明等占位符，创建一个完全格式化的 Markdown 文件。
渲染后的 Markdown 内容（render() 方法返回的字符串）存储在 $markdownOutput 变量中。

第 5 步：为生成的 Markdown 生成输出

$output->writeln($markdownOutput);

解释：

最终的 Markdown 内容使用 $output->writeln() 方法打印到控制台。该方法将字符串输出到控制台，允许用户以 Markdown 格式查看格式化的菜谱（最终，您可以将输出重定向到 shell 中的文件中）。

创建启动文件

您必须创建一个启动文件以允许用户直接从 shell 启动您的 Symfony 命令。（在本文中，我们不是创建 Symfony 应用程序；我们正在使用 Symfony 包构建 PHP 脚本。）
在项目目录中，您有composer.json文件和src目录，您可以创建一个my-app文件。

#!/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 模板/视图来呈现 API 检索到的数据。

为菜谱创建一个 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 格式呈现菜谱，其中包含菜谱名称、成分和说明部分。