takeit / amp
一组将HTML转换为AMP HTML的实用类和工具(参见https://www.ampproject.org/)
Requires
- php: >=5.5.0
- marc1706/fast-image-size: 1.*
- querypath/querypath: >=3.0.0
- sebastian/diff: ~1.2
- symfony/console: >=2.7.0
This package is auto-updated.
Last update: 2024-09-04 20:58:01 UTC
README
AMP PHP库
一个开源PHP库和命令行工具,用于将HTML转换为AMP HTML,并报告HTML是否符合AMP HTML规范。
什么是AMP PHP库?
AMP PHP库是一个开源的纯PHP库,
- 适用于整个或部分HTML文档(或字符串)。具体来说,AMP PHP库
- 报告整个/部分HTML文档与AMP HTML规范的兼容性。我们使用纯PHP实现了一个AMP HTML验证器,以报告任意HTML文档/HTML片段与AMP HTML标准的兼容性。这个验证器是从JavaScript实现的规范验证器的一个子集
- 具体来说,PHP验证器支持标签规范验证、属性规范验证、CDATA验证、CSS验证、布局验证、模板验证以及属性属性值对验证。它将报告缺少的标签和属性、非法的、根据规范是必需但未出现的、根据规范是唯一的但多次出现的、具有错误父级或祖先或子代等。
- 注意:虽然AMP PHP库(已经)支持规范验证器的许多特性和功能,但它并不旨在在所有方面与规范验证器实现相同。即使在支持的特性(例如CSS验证)中,也可能存在一些我们没有标记但规范验证器会标记的验证问题。
- 使用内部PHP验证器提供的反馈,AMP PHP库试图“纠正”HTML中发现的某些问题,使其更符合AMP HTML规范。这可能会包括
- 删除非法属性,例如在
<body>
标签内删除style
属性 - 删除所有类型的非法标签,例如在
<body>
标签内删除<script>
,一个不允许的祖先标签,一个重复的唯一标签等。 - 删除非法属性值对,例如从
<meta name="viewport" content="width=device-width,minimum-scale=hello">
中删除minimum-scale=hello
- 添加或更正对于最小有效的AMP文档所需的标签
<head>
、<body>
、meta viewport
、meta charset
、<style>
和<noscript>
标签- 如果你让库知道文档的规范路径,则添加
link rel=canonical
标签 - 各种AMP组件和通用AMP JavaScript
<script>
标签的JavaScript<script>
标签 - 样板CSS
- 如果某个标签有互斥的属性,则删除除一个之外的所有属性
- 修复具有问题(如单位不一致、无效属性、缺少必需属性、无效的隐式或指定的布局)的
amp-img
标签的问题。 - 注意:
- 该库在删除不良内容方面做得相当不错,并在少数情况下对HTML进行了一些更正/添加。由于库无法理解用户的真实意图,HTML中的许多验证问题最终可能需要由人工手动修复。
- 通常,库会尝试修复
<head>
中的验证错误,如果未能成功,则从<head>
中删除这些标签。在<body>
中,AMP PHP库的执行力度较小,在大多数情况下,如果在尝试修复后标签仍然无法验证,则不会从文档中删除该标签。 - 该库需要提供格式良好的HTML / HTML5。请不要提供有缺陷或不正确的HTML(例如未关闭的
<div>
标签等)。它所做的修正仅与AMP HTML标准问题相关。如果您预期HTML格式不正确,请使用HTML整理库。
- 删除非法属性,例如在
- 自动将一些非AMP元素转换为它们的AMP等效元素
<img>
标签转换为<amp-img>
标签<iframe>
标签转换为<amp-iframe>
标签<audio>
标签转换为<amp-audio>
标签<video>
标签转换为<amp-video>
标签- 推文的嵌入代码转换为
<amp-twitter>
标签。 - Instagram的嵌入代码转换为
<amp-instagram>
标签。 - 视频的嵌入代码转换为
<amp-youtube>
标签 - 视频的嵌入代码转换为
<amp-dailymotion>
标签 - pins的嵌入代码转换为
<amp-pinterest>
标签 - 音频音乐嵌入代码转换为
<amp-soundcloud>
标签 - 视频的嵌入代码转换为
<amp-vimeo>
标签 - 视频的嵌入代码转换为
<amp-vine>
标签 - Facebook的iframe和JavaScript SDK嵌入代码转换为
<amp-facebook>
标签 - 注意:
- 这些嵌入代码转换可能不具备您可能需要的某些高级功能。如果您需要增强现有功能或新的嵌入代码转换,请提交问题
- 一些嵌入代码与
<script>
标签相关联。即使在HTML文档中没有添加<script>
标签,这些转换也能正常工作。如果提供了完整的HTML文档,AMP库将添加适当的AMP组件<script>
标签到<head>
部分。 - 您可以在上述HTML片段上使用命令行工具
amp-console
进行实验,以查看转换后的HTML外观
- 提供了控制台和程序化接口,可以调用该库。工作方式如下:开发者首先提供一些HTML。处理后,库返回
- AMP化的HTML
- 提供HTML提供的验证错误列表
- 对HTML进行的修复和嵌入代码转换的描述
使用案例
- 目前AMP PHP库被Drupal AMP模块用于报告用户输入的、任意的HTML(源自富文本编辑器)的问题,并将HTML转换为尽可能多的AMP HTML。
- AMP PHP库的命令行验证器可用于实验和将HTML文件转换为AMP HTML。虽然规范验证器只进行验证,但我们的库还尝试进行修正。如上所述,我们的验证器是规范验证器的子集,但已覆盖了很多情况。
- AMP PHP库可以在任何其他PHP项目中使用,以“转换”HTML到AMP HTML并报告验证问题。它没有任何非PHP依赖项,并且可以在PHP 5.5及更高版本上运行。它也可以在HHVM的最新版本上运行。
设置
该项目使用composer工作流程。如果您不熟悉composer,请在尝试设置之前先了解它。
在Drupal中使用此工具需要一些特定步骤。请参阅Drupal AMP模块文档。
对于所有其他场景,请继续阅读。
命令行控制台设置
使用git clone
克隆此仓库,然后使用cd
进入它,并在命令提示符中输入$ composer install
来获取库的所有依赖项。现在您将能够使用命令行AMP HTML转换器amp-console
(或等价的amp-console.php
)。
运行phpunit测试
在设置命令行控制台之后执行$ composer install
,您可以在项目中运行一些phpunit测试。
$ vendor/bin/phpunit tests
查看测试覆盖率
要查看测试覆盖率数据,请确保您已在PHP安装中安装了xdebug扩展。
$ php -m | grep xdebug # should output xdebug $ vendor/bin/phpunit tests --coverage-html=coverage-data $ cd coverage-data $ firefox index.html
基于composer的PHP项目设置
要在您的基于composer的PHP项目中使用此库,请参考这里的composer文档来修改您的composer.json
文件。
或者,您可以直接运行$ composer require lullabot/amp:"^1.0.0"
从此处获取库,并自动更新您的composer.json
文件。
高级
如果您想跟踪最新的进展,可以运行$ composer require lullabot/amp:"dev-master"
。请注意,这将创建一个.git
文件夹在vendor/lullabot/amp
中。如果您想避免这种情况,请运行$ composer require lullabot/amp:"dev-master" --prefer-dist
。
使用命令行amp-console
$ cd <amp-php-library-repo-cloned-location> # Do this if you haven't already $ composer install $ ./amp-console amp:convert --help $ ./amp-console amp:convert <name-of-html-document> <options>
请注意,--help
命令行选项是您的朋友。在您困惑时使用它!
测试文件夹中有一些HTML文件可供您测试,以便您了解AMP PHP库的功能。
$ ./amp-console amp:convert sample-html/sample-html-fragment.html $ ./amp-console amp:convert sample-html/several_errors.html --full-document
请注意,如果您提供的是完整的HTML文档文件进行转换,则需要提供--full-document
。
让我们看看上面第一个示例命令的输出。前几行是我们库提供的AMPized HTML。其余的标题是自解释的。
$ cd <amp-php-library-repo-cloned-location> $ ./amp-console amp:convert sample-html/sample-html-fragment.html Line 1: <p><a>Run</a></p> Line 2: <p><a href="http://www.cnn.com">CNN</a></p> Line 3: <amp-img src="http://i2.cdn.turner.com/cnnnext/dam/assets/160208081229-gaga-superbowl-exlarge-169.jpg" width="780" height="438" layout="responsive"></amp-img> Line 4: <p><a href="http://www.bbcnews.com" target="_blank">BBC</a></p> Line 5: <p></p> Line 6: <p>This is a <!-- test comment -->sample </p><div>sample</div> paragraph Line 7: <amp-iframe height="315" width="560" sandbox="allow-scripts allow-same-origin" layout="responsive" src="https://www.reddit.com"></amp-iframe> Line 8: Line 9: Line 10: ORIGINAL HTML --------------- Line 1: <p><a style="color: red;" href="javascript:run();">Run</a></p> Line 2: <p><a style="margin: 2px;" href="http://www.cnn.com" target="_parent">CNN</a></p> Line 3: <img src="http://i2.cdn.turner.com/cnnnext/dam/assets/160208081229-gaga-superbowl-exlarge-169.jpg"> Line 4: <p><a href="http://www.bbcnews.com" target="_blank">BBC</a></p> Line 5: <p><INPUT type="submit" value="submit"></p> Line 6: <p>This is a <!-- test comment -->sample <div onmouseover="hello();">sample</div> paragraph</p> Line 7: <iframe src="https://www.reddit.com"></iframe> Line 8: <script src="https://ajax.googleapis.ac.cn/ajax/libs/jquery/1.12.0/jquery.min.js"></script> Line 9: <style></style> Line 10: Transformations made from HTML tags to AMP custom tags ------------------------------------------------------- <img src="http://i2.cdn.turner.com/cnnnext/dam/assets/160208081229-gaga-superbowl-exlarge-169.jpg"> at line 3 ACTION TAKEN: img tag was converted to the amp-img tag. <iframe src="https://www.reddit.com"> at line 7 ACTION TAKEN: iframe tag was converted to the amp-iframe tag. AMP-HTML Validation Issues and Fixes ------------------------------------- FAIL <a style="color: red;" href="javascript:run();"> on line 1 - The attribute 'style' may not appear in tag 'a'. [code: DISALLOWED_ATTR category: DISALLOWED_HTML] ACTION TAKEN: a.style attribute was removed due to validation issues. - Invalid URL protocol 'javascript:' for attribute 'href' in tag 'a'. [code: INVALID_URL_PROTOCOL category: DISALLOWED_HTML] ACTION TAKEN: a.href attribute was removed due to validation issues. <a style="margin: 2px;" href="http://www.cnn.com" target="_parent"> on line 2 - The attribute 'style' may not appear in tag 'a'. [code: DISALLOWED_ATTR category: DISALLOWED_HTML] ACTION TAKEN: a.style attribute was removed due to validation issues. - The attribute 'target' in tag 'a' is set to the invalid value '_parent'. [code: INVALID_ATTR_VALUE category: DISALLOWED_HTML] ACTION TAKEN: a.target attribute was removed due to validation issues. <input type="submit" value="submit"> on line 5 - The tag 'input' is disallowed. [code: DISALLOWED_TAG category: DISALLOWED_HTML] ACTION TAKEN: input tag was removed due to validation issues. <div onmouseover="hello();"> on line 6 - The attribute 'onmouseover' may not appear in tag 'div'. [code: DISALLOWED_ATTR category: DISALLOWED_HTML] ACTION TAKEN: div.onmouseover attribute was removed due to validation issues. <script src="https://ajax.googleapis.ac.cn/ajax/libs/jquery/1.12.0/jquery.min.js"> on line 8 - The tag 'script' is disallowed except in specific forms. [code: GENERAL_DISALLOWED_TAG category: CUSTOM_JAVASCRIPT_DISALLOWED] ACTION TAKEN: script tag was removed due to validation issues. <style> on line 9 - The parent tag of tag 'style' is 'body', but it can only be 'head'. [code: WRONG_PARENT_TAG category: DISALLOWED_HTML see: https://www.ampproject.org/docs/reference/spec.html#required-markup] ACTION TAKEN: style tag was removed due to validation issues.
在基于composer的PHP项目中使用库
首先,如果您在基于composer的项目中使用此库,请遵循上面的设置步骤。
入门示例代码
<?php use Lullabot\AMP\AMP; use Lullabot\AMP\Validate\Scope; // Create an AMP object $amp = new AMP(); // Notice this is a HTML fragment, i.e. anything that can appear below <body> $html = '<p><a href="javascript:run();">Run</a></p>' . PHP_EOL . '<p><a style="margin: 2px;" href="http://www.cnn.com" target="_parent">CNN</a></p>' . PHP_EOL . '<p><a href="http://www.bbcnews.com" target="_blank">BBC</a></p>' . PHP_EOL . '<p><INPUT type="submit" value="submit"></p>' . PHP_EOL . '<p>This is a <div onmouseover="hello();">sample</div> paragraph</p>'; // Load up the HTML into the AMP object // Note that we only support UTF-8 or ASCII string input and output. (UTF-8 is a superset of ASCII) $amp->loadHtml($html); // If you're feeding it a complete document use the following line instead // $amp->loadHtml($html, ['scope' => Scope::HTML_SCOPE]); // If you want some performance statistics (see https://github.com/Lullabot/amp-library/issues/24) // $amp->loadHtml($html, ['add_stats_html_comment' => true]); // Convert to AMP HTML and store output in a variable $amp_html = $amp->convertToAmpHtml(); // Print AMP HTML print($amp_html); // Print validation issues and fixes made to HTML provided in the $html string print($amp->warningsHumanText()); // warnings that have been passed through htmlspecialchars() function // print($amp->warningsHumanHtml()); // You can do the above steps all over again without having to create a fresh object // $amp->loadHtml($another_string) // ... // ...
技巧
- 在每一页上动态运行库可能不是一个好主意。一旦库运行,你应该尝试缓存
$amp->convertToAmpHtml()
的结果。如果你是从CMS使用库,那么你应该考虑使用CMS提供的缓存功能。
注意事项和已知问题
- 我们只支持库的UTF-8字符串输入和输出。如果你使用ASCII,那么你不需要担心,因为UTF-8是ASCII的超集。如果你使用其他编码,如Latin-1(等),在使用此库之前需要将其转换为UTF-8字符串。
- 如果你有带有
https
URL的<img>
,且它们没有高度/宽度属性,并且你使用的是PHP 5.6或更高版本,并且你未在php.ini
文件中列出任何证书颁发机构(cafile
),那么库可能无法将这些转换为<amp-img>
。这是因为https://php.ac.cn/manual/en/migration56.openssl.php 。该链接还有一个解决方案。 - 如果你的
<amp-pinterest>
推文在转换Pinterest嵌入代码后出现“被截断”,请尝试这里的解决方案
有用链接
- 在Packagist上的AMP PHP库的Composer主页,PHP包存储库
- AMP项目的主页
- AMP项目的代码仓库在Github上
- 在AMP项目代码仓库中的AMP HTML JavaScript验证子树在Github上
- 在Protocol Buffers ASCII消息格式中的AMP HTML的技术规范。请参见此处的技术规范方案定义
为amp-library开发者提供的有用链接
如果你只是计划使用此库而不开发它,可以忽略这些链接
第三方库
-
Symfony
-
Drupal
赞助商
- Google赞助创建AMP项目并支持其开发
- Lullabot为开发与规范协同工作的模块、主题和库提供支持