awonderphp/notreallypsrresourcemanager

一个关于网络应用JS/CSS资源管理器的提案

维护者

详细信息

github.com/AliceWonderMiscreations/NotReallyPsrResourceManager

主页

源代码

问题

安装: 4

依赖: 0

建议者: 0

安全: 0

星标: 0

关注者: 3

分支: 0

开放问题: 0

dev-master 2018-03-15 11:52 UTC

Requires

  • php: ~7.1.0 || ~7.2.0

Requires (Dev)

MIT 221aee59014fabb14659579251196fd56ef923ec

  • Alice Wonder <paypal.woop@domblogger.net>

This package is not auto-updated.

Last update: 2024-09-18 05:51:00 UTC

README

这是一个PHP库可以使用的接口集合，用于提供网络应用中使用的第三方JavaScript和CSS资源的合理管理。

当前的命名空间 \AWonderPHP\NotReallyPsrResourceManager 很糟糕，将会更改。它从未打算作为永久命名空间。我希望能有一个标准机构想要采用这个想法，并创建一些带有花哨术语的标准接口，包括 RFC 2119。

虽然不是强制性的，但强烈建议实现这些接口的类扩展 \AwonderPHP\FileResource 命名空间内的抽象类。

这使得生成的对象可以被任何了解如何服务 FileResource 对象的类所服务。

还打算通过本文档中描述的方式从JSON配置文件生成JavaScriptResource和CssResource对象。

  1. FileResource 方法
  2. JavaScriptResource 接口方法
  3. CssResource 接口方法
  4. ResourceManager 接口
  5. JSON配置文件
  6. JavaScript JSON
  7. CSS JSON
  8. 文件系统和配置文件命名
  9. 包装脚本

FileResource 方法

这些方法在 JavaScriptResource 和 CssResource 接口中指定，并且与抽象 \AwonderPHP\FileResource\FileResource 类中同名方法相同

  • public function getMimeType()
    返回 $mime 属性。

  • public function getChecksum()
    返回 $checksum 属性。

  • public function getCrossOrigin()
    返回 $crossorigin 属性。

  • public function getFilePath()
    返回 $filepath 属性。

  • public function validateFile()
    如果 $checksum 属性已设置 并且 $filepath 属性已设置 并且 文件存在，则如果文件与校验和匹配，返回 true，如果不匹配，返回 false。

  • public function getSrcAttribute($prefix = null)
    构建嵌入资源到网页所需的 src 或 href 属性的内容。注意，如果 $urlscheme 属性为 http 并且文件没有使用 $validIntegrityAlgo 属性中的算法的 $checksum 属性，则将返回 null。可选参数 $prefix 是一个文件系统路径，用于在 $urlpath 属性之前添加，对于使用包装器提供文件的Web应用程序很有用。

  • public function getIntegrityAttribute()
    如果 $checksum 属性使用合适的算法，构建 integrity 属性的内容。

  • public function getTimestamp()
    如果 $lastmode 属性不为空，返回UNIX时间戳（自UNIX纪元以来的秒数）。

JavaScriptResource 接口方法

这些方法在JavaScriptResource接口中，但不在之前提到的FileResource抽象类中定义。

  • getTypeAttribute()
    放入<script>节点type属性的值。通常是MIME类型，但不总是如此。

  • getAsyncAttribute()
    布尔async属性是否存在。

  • getDeferAttribute();
    布尔defer属性是否存在。

  • getNoModuleAttribute()
    布尔nomodule属性是否存在。

  • generateScriptDomNode($dom, $nonce = null)
    创建一个具有可选nonce的\DOMNode <script>节点。

  • generateScriptString(bool $xml = false, $nonce = null)
    创建一个字符串，可以是HTML或XHTML，用于具有可选nonce的脚本节点。如果$xml参数为true，则返回一个符合XML规范的字符串（每个属性都是key="value"对，布尔属性通常是只是key="key"，但这并不重要。脚本节点是自闭合的）。当$xml参数为false时（默认值），生成一个符合HTML规范的字符串（布尔属性可能只是key，并且不需要有="value"，并且自闭合的脚本标签不被认为是闭合的，所以需要一个闭合的</script>）。

两个generateScriptDomNode()和generateScriptString()方法都应该调用getSrcAttribute()方法，所以实现类的构造函数应该有一个默认为null但可以由构造函数设置的$prefix属性。

CssResource 接口方法

  • getTypeAttribute()
    CSS <link>节点的type属性中包含的内容。这应该始终返回text/css

  • getMediaAttribute()
    返回CSS <link>节点的media属性中包含的内容。这很少使用，但非常强大，我认为应该更频繁地使用，因为它可以减少客户端成功使用Web应用所需的带宽。

  • getHreflangAttribute()
    返回hreflang属性中包含的内容。当不为null时，它必须是BCP47字符串。

  • getReferrerPolicyAttribute()
    返回CSS <link>节点的referrerpolicy属性中包含的内容。我怀疑它不会使用很多，但它是存在的。

  • getRelAttribute()
    rel属性的内容，应该返回stylesheet。

ResourceManager 接口

这是定义Web应用如何交互以获取它们所需的JavaScriptResource和CssResource对象的一个接口。

它描述了两个公共方法

  • getJavaScript(string $vendor, string $product, string $name, $version, $variant = null);

  • getCSS(string $vendor, string $product, string $name, $version, $variant = null);

Web应用调用这些方法，这些方法将返回null，如果实现类无法创建对象，或者根据调用哪个方法返回一个JavaScriptResource或CssResource实现对象。

参数

  • $vendor 字符串
    小写供应商字符串，用于打包JavaScript或CSS的人，类似于PSR-4 PHP类的第一级命名空间，但小写。在Composer术语中，它将是Composer创建的Web应用vendor目录中的顶级目录。

  • $product 字符串
    小写产品字符串，JavaScript或CSS是其中的一部分，类似于PSR-4 PHP类的第二级命名空间，但小写。在Composer术语中，它将是之前提到的目录。

  • $name 字符串
    JavaScript或CSS的名称，不带版本和其他信息，例如jquery或jquery-ui或normalize。

  • $version 字符串或整数
    所需的版本，例如3.3.1以特别要求jQuery 3.3.1或3.3以特别要求3.3分支的最新版本，或者简单地3以要求3分支的最新版本。

  • $variant 字符串或 Null
    所需JavaScript的变体，例如min用于压缩或slim或slim.min。

有了这些信息，实现ResourceManager的类就能够找到描述该对象的JSON文件并将其加载到对象中。

实现类的构造函数应定义资源安装到的Base目录，以便方法可以找到所需的配置文件，并使用getSrcAttribute()方法指定$prefix。

示例用法

$base = "/whatever/path";
$RM = new \namespace\whatever\ImplementingClass($base);
$jsObj = $RM->getJavaScript('flossjs', 'jquery', 'jquery', 3, "min");

然后从$jsObj，Web应用程序可以创建所需的<script>节点。

JSON配置文件

ResourceManager将寻找与Web应用程序请求的资源匹配的JSON配置文件，然后根据JSON文件创建要返回的对象。这需要一个标准的JSON文件格式。

JavaScript和CSS的常见JSON元素

  • name 字符串，必需
    脚本或CSS的名称（不带版本和变体），例如jquery。
  • homepage 字符串，非必需
    项目的URL主页
  • version 字符串，必需
    所描述脚本的版本。
  • license 数组，必需
    包含一个或多个适用于脚本的许可证的数组。数组的每个元素应包含许可证名称和许可证的URL。

这些字段不被类使用，但是对系统管理员有用的元数据。JS和CSS的通用字段

  • mime 字符串，必需
    在提供文件时应使用的MIME类型。
  • checksum 字符串，推荐
    FileResource抽象类中描述的algo:checksum。
  • filepath 字符串，可选
    如果文件在服务器上存在，则文件系统路径到该文件。
  • lastmod 字符串，推荐
    可以被strtotime()解析的字符串，以创建表示文件最后修改时间的UNIX时间戳。对于许多项目，这个字符串指定在文件的注释标题中，在这些情况下，应使用该字符串。
  • srcurl 字符串，必需
    应放在src或href属性中的内容。必须由parse_url函数解析，并且国际化域名应使用punycode。
  • minified 布尔值，可选
    此字段的用途可能被某些实现使用，但不是必需的。它定义了文件中的JS/CSS是否被压缩。

JavaScript JSON

JavaScript JSON的示例

{
    "name": "jquery",
    "homepage": "https://jqueryjs.cn/",
    "version": "3.3.1",
    "license": [
        {
            "name": "MIT",
            "url": "https://jquery.org/license/"
        }
    ],
    "mime": "application/javascript",
    "checksum": "sha256:160a426ff2894252cd7cebbdd6d6b7da8fcd319c65b70468f10b6690c45d02ef",
    "filepath": "flossjs/jquery/js/jquery-3.3.1.min.js",
    "lastmod": "2018-01-20T17:24Z",
    "minified": true,
    "srcurl": "/js/jquery-3.3.1.min.js"
}

JavaScript特定字段

  • async 布尔值，可选
    只有在需要该属性时才需要，然后设置为true。
  • defer 布尔值，可选
    只有在需要该属性时才需要，然后设置为true。
  • nomodule 布尔值，可选
    只有在需要该属性时才需要，然后设置为true。
  • ??type?? 需要探索
    在大多数情况下，将type属性设置为MIME类型，但可能需要将其设置为modular以用于ES6模块功能，我还需要学习这方面的知识。

CSS JSON

CSS JSON的示例需要编写。

CSS特定字段

  • media 数组，可选
    包含CSS文件应用的媒体类型的数组，当它不适用于所有人时（浏览器在没有指定时假定all）
  • hreflang 字符串，可选
    适用于CSS文件的BCP47语言字符串。
  • referrerpolicy 字符串，可选
    当存在时，必须是以下之一：no-referrer、no-referrer-when-downgrade、origin、origin-when-cross-origin、unsafe-url -- 浏览器假定no-referrer-when-downgrade是CSS样式表的最好策略。我认为unsafe-url绝对不应该使用，因为它可能会泄露信息。它只在远程服务器不使用TLS但您的Web应用程序使用TLS的情况下才有意义，并且这种情况应该由浏览器阻止。

文件系统和配置文件命名

所有脚本都应该按照$base/VendorName/ProductName的层次结构安装，其中VendorName和ProductName都是小写，这与PHP库的Composer约定一致。

在Composer安装JS/CSS库的情况下，Composer的vendor目录将是$base目录。

在ProductName目录中，必须存在一个包含JSON配置文件的etc目录，并且建议实际的JavaScript文件位于js目录中，CSS文件位于css目录中。

以下是一个示例：AliceWonderMiscreations/CommonJS

默认配置文件命名使用

ScriptName-Version-Variant.json.dist

其中ScriptName是脚本的名称（例如jquery），Version是脚本的版本（例如3.3.1），如果存在，Variant将是脚本的变体（例如min或slim或slim.min）。

默认配置应该将srcurl指向本地URL，例如

"srcurl": "/js/jquery-3.3.1.min.js",

当系统管理员想要自定义配置中的内容时，他们只需复制文件，使其不再以.dist结尾，然后就可以修改它（例如将srcurl设置为CDN）。

ResourceManager在找到时必须优先使用不带.dist的配置文件。

使用major.minor.point版本方案，应存在一个配置文件，用于匹配最新的major.minor.point的major.minor和major，并且与默认配置文件相同。

包装脚本

实现此功能的Web应用程序必须能够处理对默认的/js/和/css/位置的请求。

这可以通过包装脚本实现。已经编写了一个扩展FileWrapper类的抽象类，该抽象类是AWonderPHP\FileResource命名空间的一部分。

此命名空间中存在一个接口，可用于定义一个扩展上述FileResource对象的类的类。

EOF