CommonMark PHP 解析器使用教程

1、项目介绍

league/commonmark 是一个高度可扩展的 PHP Markdown 解析器，完全支持 CommonMark 和 GFM（GitHub Flavored Markdown）规范。该项目由 Colin O'Dell 创建，基于 John MacFarlane 的 CommonMark JS 参考实现。它旨在提供一个强大且灵活的工具，用于将 Markdown 转换为 HTML。

2、项目快速启动

安装

首先，确保你的 PHP 版本为 7.4 或更高，并且安装了 mbstring 扩展。然后，使用 Composer 安装 league/commonmark：

composer require league/commonmark

基本使用

以下是一个简单的示例，展示如何将 Markdown 转换为 HTML：

use League\CommonMark\CommonMarkConverter;

$converter = new CommonMarkConverter([
    'html_input' => 'strip',
    'allow_unsafe_links' => false,
]);

echo $converter->convert('# Hello World!');
// 输出: <h1>Hello World!</h1>

如果你需要使用 GitHub Flavored Markdown (GFM)，可以使用 GithubFlavoredMarkdownConverter：

use League\CommonMark\GithubFlavoredMarkdownConverter;

$converter = new GithubFlavoredMarkdownConverter([
    'html_input' => 'strip',
    'allow_unsafe_links' => false,
]);

echo $converter->convert('# Hello World!');
// 输出: <h1>Hello World!</h1>

3、应用案例和最佳实践

应用案例

1. 博客系统：许多博客系统使用 Markdown 作为内容输入格式，league/commonmark 可以轻松地将 Markdown 转换为 HTML 供前端展示。
2. 文档生成：在生成项目文档时，Markdown 是一种非常流行的格式。league/commonmark 可以帮助你将 Markdown 文档转换为 HTML 或其他格式。
3. CMS 系统：内容管理系统（CMS）通常支持多种内容输入格式，league/commonmark 可以作为 Markdown 解析器集成到 CMS 中。

最佳实践

1. 安全设置：在处理用户输入时，建议设置 html_input 为 'strip' 或 'escape'，以防止 XSS 攻击。
2. 性能优化：对于大型文档，可以考虑使用缓存机制来减少解析时间。
3. 自定义扩展：league/commonmark 支持自定义扩展，可以根据项目需求添加额外的功能，如 Emoji 支持、表格解析等。

4、典型生态项目

相关项目

1. CakePHP 3：league/commonmark 可以集成到 CakePHP 3 中，用于处理 Markdown 内容。
2. Drupal：Drupal 社区提供了 league/commonmark 的模块，方便 Drupal 用户使用。
3. Laravel：Laravel 社区有许多包可以与 league/commonmark 集成，提供更便捷的 Markdown 处理功能。
4. Symfony：Symfony 框架可以通过扩展轻松集成 league/commonmark。

社区扩展

1. Emoji 扩展：支持 UTF-8 表情符号和 GitHub 标签。
2. Sup Sub 扩展：添加对上标和下标的支持。
3. YouTube iframe 扩展：将 YouTube 链接自动转换为嵌入式 iframe。
4. Lazy Image 扩展：为图片添加懒加载功能。

通过这些扩展，你可以根据项目需求定制 league/commonmark 的功能，使其更加符合你的使用场景。