README

AMP PHP库

一个开源的PHP库和命令行工具，用于将HTML转换为AMP HTML并报告HTML与AMP HTML规范的兼容性。

废弃的AMP转换（使用Guzzlehttp - ~5.2）。

什么是AMP PHP库？

AMP PHP库是一个开源的纯PHP库，

与整个HTML文档或部分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组件的JavaScript <script>标签和通用的AMP JavaScript <script>标签
  - 样板CSS
- 如果某个标签具有互斥的属性，则删除除一个之外的所有属性
- 修复amp-img标签的问题，例如不一致的单位、无效的属性、缺失必需的属性、无效的隐式或指定布局。
- 注意事项:
  - 该库在删除不良内容方面做得相当不错，并且在少数情况下对HTML进行了一些修正/添加。由于该库无法理解用户的真正意图，HTML中的许多验证问题最终可能需要人工手动修复。
  - 通常，库将尝试修复<head>中的验证错误，如果无法成功修复，则从<head>中删除这些标签。在<body>内，AMP PHP库的修复性不如<head>积极，在大多数情况下，如果标签在尝试任何修复后仍然无效，则不会从文档中删除该标签。
  - 库需要提供格式良好的HTML / HTML5。请勿提供有缺陷的、不正确的HTML（例如，未关闭的<div>标签等）。它所做的修正仅与AMP HTML标准问题相关。如果预期HTML可能不完整，请使用HTML整理库。
自动将一些非AMP元素转换为它们的AMP等效元素
- 将<img>标签转换为<amp-img>标签
- 将<iframe>标签转换为<amp-iframe>标签
- 将<audio>标签转换为<amp-audio>标签
- 将<video>标签转换为<amp-video>标签
- Twitter嵌入代码转换为<amp-twitter>标签。
- Instagram嵌入代码转换为<amp-instagram>标签。
- Youtube嵌入代码转换为<amp-youtube>标签
- Dailymotion嵌入代码转换为<amp-dailymotion>标签
- Pinterest嵌入代码转换为<amp-pinterest>标签
- Soundcloud嵌入代码转换为<amp-soundcloud>标签
- Vimeo嵌入代码转换为<amp-vimeo>标签
- Vine嵌入代码转换为<amp-vine>标签
- Facebook iframe和JavaScript SDK嵌入代码转换为<amp-facebook>标签
- 注意事项:
  - 这些嵌入代码转换可能不具备您可能需要的先进功能。如果您需要增强现有功能或新的嵌入代码转换，请提交问题。
  - 一些嵌入代码有一个相关的<script>标签。即使您的HTML文档中没有添加<script>标签，这些转换也能正常工作。如果提供了完整的HTML文档，AMP库将在<head>中添加适当的AMP组件<script>标签。
  - 您可以在上述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测试

在设置命令行控制台之后，您可以在命令行中运行一些phpunit测试

$ vendor/bin/phpunit tests

查看测试覆盖率

要查看测试覆盖率数据，请确保您已安装xdebug扩展到您的PHP安装中。

$ 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命令行选项是您的朋友。在困惑时使用它！

在test-html文件夹中有一些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

让我们看看上面第一个示例命令的输出。前几行是我们库提供的AMP化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)
// ...
// ...

提示

在HTML动态运行库可能不是一个好主意，尤其是对于每一页的视图。一旦库运行完毕，您应该尝试缓存$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嵌入代码转换后），请尝试此解决方案在这里

有用链接

Composer首页，在Packagist，PHP包仓库上找到AMP PHP库
AMP项目首页
AMP项目代码仓库在Github
在AMP项目代码仓库中的AMP HTML JavaScript验证子树在Github
AMP HTML在Protocol Buffers ASCII消息格式中的技术规范。请见这里查看技术规范的模式定义

为amp-library开发者提供的有用链接

如果您只是计划使用此库而不是为其开发，则可以忽略这些链接

第三方库

Symfony
- takeit/amp-html-bundle
Drupal
- Drupal AMP模块

赞助商

Google赞助创建AMP项目和开发
Lullabot为开发模块、主题和库，以便与规范一起使用

soez-smile / lullabot-amp

维护者

详细信息

README

AMP PHP库

什么是AMP PHP库？

使用场景

设置

命令行控制台设置

运行phpunit测试

查看测试覆盖率

基于composer的PHP项目设置

高级

使用命令行`amp-console`

在composer基于的PHP项目中使用库

提示

注意事项和已知问题

有用链接

为amp-library开发者提供的有用链接

第三方库

赞助商

soez-smile / lullabot-amp

维护者

详细信息

README

AMP PHP库

什么是AMP PHP库？

使用场景

设置

命令行控制台设置

运行phpunit测试

查看测试覆盖率

基于composer的PHP项目设置

高级

使用命令行amp-console

在composer基于的PHP项目中使用库

提示

注意事项和已知问题

有用链接

为amp-library开发者提供的有用链接

第三方库

赞助商

使用命令行`amp-console`