README

UrlLinker是一个PHP模块，用于将纯文本片段转换为HTML，并将文本中的任何网页地址转换为HTML超链接。

安装

1. 使用[Composer](https://getcomposer.org.cn/)下载库

   ` composer require kwi/urllinker `

2. 在你的PHP文件中，需要Composer的自动加载器

   ``` <?php

   require_once __DIR__.'/vendor/autoload.php'; ```

使用（过程式API）

print(htmlEscapeAndLinkUrls($text));

更长的示例，请参阅 UrlLinker-example.php.

UrlLinker假定输入的是纯文本，并返回HTML。如果您的输入已经是HTML，但其中包含未标记的URL，UrlLinker也可以处理这种情况

print(linkUrlsInTrustedHtml($html));

警告：后一个函数必须仅用于受信任的输入，因为渲染恶意用户提供的HTML可能导致系统通过跨站脚本被入侵。另一方面，htmlEscapeAndLinkUrls函数可以安全地用于不受信任的输入。（您可以通过PHP的strip_tags函数从不受信任的输入中删除现有标签。）

使用（面向对象API）

``` $urlLinker = new KwiUrlLinker();

$urlLinker->linkUrlsAndEscapeHtml($text);

$urlLinker->linkUrlsInTrustedHtml($html); ```

在您的函数中，您可以依赖UrlLinkerInterface

``` class Example {

private $urlLinker;

public function __construct(KwiUrlLinkerInterface $urlLinker) {

$this->urlLinker = $urlLinker;

}

public function doStuff($text) {

// 对 $text 做些处理…

return $this->urlLinker->linkUrlsAndEscapeHtml($text);

}

}

您可以通过将选项传递给UrlLinker的构造函数来配置不同的URL解析选项

``` // 允许FTP地址如 "ftp://example.com"：$urlLinker = new KwiUrlLinker(true);

// 允许大写URL方案如 "HTTP://exmaple.com"：$urlLinker = new KwiUrlLinker(false, true); ```

识别的地址

• 网页地址
  • 识别的URL方案："http" 和 "https"
    • 前缀 "http://" 是可选的。
    • 支持添加额外的方案，例如“ftp”，可以通过调整$rexScheme轻松实现。
    • 方案必须小写。通过在$rexUrlLinker中添加一个i（即PCRE_CASELESS修饰符）可以取消此要求。
  • 可以使用域名或IPv4地址指定主机。
    • 不支持IPv6地址。
  • 允许端口数字。
  • 允许国际化资源标识符（IRI）。请注意，将IRI转换为URI的任务留给用户的浏览器。
  • 为了减少误报，UrlLinker会验证顶级域名是否在官方IANA有效TLD列表中。
    • 随着TLD列表的扩展，UrlLinker会不时进行更新。
    • 在未来，这种方法可能因为ICANN不恰当的新政策——以大量现金出售任意TLD而崩溃，但目前它是一种有效的拒绝无效URL的方法。
    • 为了识别，国际化顶级域名必须用Punycode编写。
    • 如果您需要支持无限定域名，例如localhost，可以通过以下方法禁用TLD检查：1）在$rexDomain值中将+替换为*，2）将“检查TLD是否有效”注释下的if语句替换为if (true)。这显然是一个快速简单的解决方案，可能会导致误报。
• 电子邮件地址
  • 支持常见的地址格式范围，包括“加号地址”（如Gmail推广的那样）。
  • 不识别RFC允许但实践中从未见过的更复杂的地址变体。
  • 简单的垃圾邮件保护：将at符号转换为HTML实体，以阻止简单的电子邮件地址收集者。
• 在正常句子环境中正确识别地址。例如，在“访问stackoverflow.com。”中，最后的句点不是URL的一部分。
• 用户输入经过适当清理，以防止跨站脚本（XSS），URL中的ampersands正确地转义为&（这不适用于linkUrlsInTrustedHtml函数，该函数假定其输入是有效的HTML）。

测试

单元测试使用[PHPUnit](https://phpunit.de）编写。

` $ cd PATH_TO_URL_LINKER $ composer install $ phpunit `

背景

一个Stackoverflow.com问题促使我考虑这个任务的难度。最初，这似乎很简单，但就像一个你必须挠的痒，我一直回过头来做这件事，只是修复一个小问题。

如果您觉得这段代码有用，请随意为我点赞。

还有Antoine Sottiau的C#实现。

公共领域奉献

在法律允许的范围内，作者已放弃UrlLinker的所有版权和相关或邻近权利。

更多信息请参阅：http://creativecommons.org/publicdomain/zero/1.0/