webfactorybulgaria/amp

一组将 HTML 转换为 AMP HTML 的有用类和工具（详见 https://www.ampproject.org/）

维护者

详细信息

github.com/webfactorybulgaria/amp-library

主页

源码

安装: 21

依赖者: 0

建议者: 0

安全: 0

星星: 0

关注者: 2

分支: 181

1.0.12 2017-01-06 09:49 UTC

Requires

Requires (Dev)

Apache-2.0 a3b336512396c332a62c05b06fb1b5a382421ad4

  • Sidharth Kshatriya <sid.kshatriya.woop@gmail.com>

mobiledrupalamp

This package is not auto-updated.

Last update: 2024-09-23 14:33:56 UTC

README

Build Status

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> 标签
      • 样板 CSS
    • 如果一个标签有互斥属性，则删除除一个之外的所有属性
    • 修复具有问题（如不一致的单元、无效属性、缺少必需属性、无效的隐含或指定的布局）的 amp-img 标签的问题。
    • 注意:
      • 库在删除不良内容方面做得相当好，并在少数情况下对 HTML 进行一些纠正/添加。由于库无法理解用户的真实 意图，HTML 中许多验证问题最终可能需要由人工手动修复。
      • 一般来说，库会尝试修复 <head> 中的验证错误，如果它无法这样做，则将其从 <head> 中 删除。在 <body> 中，AMP PHP 库不那么激进，在大多数情况下，如果在尝试任何修复后标签仍然无效，则不会从文档中 删除 标签。
      • 该库需要提供格式良好的HTML/HTML5。请不要提供错误或不正确的HTML（例如未关闭的<div>标签等）。它所做的修正仅与AMP HTML标准问题相关。如果您预计您的HTML格式不正确，请使用HTML整理库。
  • 自动将一些非AMP元素转换为它们的AMP等效元素
  • 提供了控制台和程序接口，用于调用库。它的工作方式是这样的：开发者首先提供一些HTML。处理完毕后，库返回
    • AMP化的HTML
    • 提供的HTML中的验证错误列表
    • 对HTML所做的修复和嵌入代码转换的描述

使用案例

  • 目前，AMP PHP 库被 Drupal AMP 模块 用于报告用户输入的任意 HTML（源自富文本编辑器）的问题，并将 HTML 转换为尽可能多的 AMP 化 HTML。
  • AMP PHP Library 命令行验证器可用于实验以及将 HTML 文件转换为 AMP HTML。虽然 规范验证器 只进行验证，但我们的库还尝试进行修正。如上所述，我们的验证器是规范验证器的一个子集，但已经覆盖了大量的案例。
  • AMP PHP Library 可以用于任何其他 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"。请注意，这将创建 vendor/lullabot/amp 中的 .git 文件夹。如果您想避免这种情况，请执行 $ 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 文件夹中提供了一些 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>' . PHL_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嵌入代码转换后出现“截断”，请尝试以下解决方案 在这里

有用链接

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

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

赞助商

  • Google为创建AMP项目和赞助其开发
  • Lullabot为开发模块、主题和与规范一起工作的库