README

这是一个用于管理***-assets包类型的Composer插件。要开始使用，请查看http://assetsmanager.ateliers-pierrot.fr/。

它是如何工作的？

此Composer插件的目标是像Composer管理PHP源代码一样管理包的资产文件（JavaScript库、CSS样式表或视图）。资产文件会被下载并存储在特定的vendor目录中，一个内部系统允许像PHP类一样检索和加载资产（一种资产自动加载器）。可以在包的配置中定义一些预设，以构建一组按类型、库或用途分组的资产文件。

与任何标准Composer功能一样，所有名称或配置变量都是可配置的。

安装

要安装此插件，请将包添加到您的composer.json中的需求

"atelierspierrot/assets-manager": "1.*"

用法

如何通知扩展您的包资产？

扩展处理任何类型为***-assets的包，如果您不使用扩展（将作为任何其他经典库包一样安装），它将被视为Composer的标准库。

项目生命周期中的使用方案

Composer的安装/更新/移除

\AssetsManager\Composer\Installer安装"***-assets"包

将资产移动到特定的www/vendor/目录
向内部assets_db表中添加条目
最后，将内部assets_db表写入文件vendor/assets.json

项目生命周期

\AssetsManager\Loader读取内部assets_db并管理资产包和预设

读取assets.json db文件
查找一些资产包文件（实路径和Web URL）
管理资产预设

结构

假设您的项目基于以下结构，其中src/包含您的PHP源代码，www/是您的Web文档根目录

| composer.json
| src/
| www/

默认情况下，Composer将在vendor/目录中安装您的依赖项并构建一个autoload.php文件

| composer.json
| src/
| vendor/
| ------- autoload.php
| www/

插件将复制依赖项的资产到www/vendor/目录，并在原始vendor/中构建JSON映射

| composer.json
| src/
| vendor/
| ------- autoload.php
| ------- assets.json
| www/
| ---- vendor/

资产管理器的使用

这部分将尝试解释如何在您的脚本中使用资产管理器。

资产加载器对象

\AssetsManager\Loader类设计用于根据已安装包的表（安装/更新/删除过程中的生成的json文件）管理一组资产。

该类基于三个路径

base_dir：包根目录，必须是包含composer.json文件的目录
assets_dir：与base_dir相关的包资产目录
document_root：Web资产根目录在文件系统中的路径；用于构建所有相关资产HTTP URL。

对于这三个路径，默认值定义在默认包结构上

package_name/
|----------- src/
|----------- www/

$loader->base_dir = realpath(package_name)
$loader->assets_dir = www
$loader->document_root = www or the server DOCUMENT_ROOT

注意 - 这些路径存储在对象中，不带尾随斜杠。

使用示例

安装过程完成后，您可以使用\AssetsManager\Loader对象访问任何资产包或加载包的预设

$loader = \AssetsManager\Loader::getInstance(
    __DIR__.'/..',      // this is the project root directory
    'www',              // this is your assets root directory
    __DIR__             // this is your web document root
);

// to get a package
$package = $loader->getPackage( package name );
// to retrieve a package asset file URL
echo $package->find( file name );

// to get a preset
$preset = $loader->getPreset( preset name );
// to write a preset dependencies
echo $preset->__toHtml();

如下文“配置”部分所述，调用预设将自动加载其内部文件（例如一些JavaScript文件）及其依赖的其他预设或文件。随后，__toHtml()方法的结果将是一个字符串，包含文件和脚本定义，功能齐全且可写入HTML。

示例

例如，如果您安装了其assets-installer版本的Gentleface sprites包，您将拥有

// calling ...
echo $loader->getPreset('gentleface-sprites')->__toHtml();
// will render something like:
<link src="vendor/atelierspierrot/gentleface-sprites/gentleface-sprites.min.css" type="text/css" rel="stylesheet" media="all" />

配置

以下是使用默认值的包配置示例

"extra": {
    # ...

    "assets-dir": "www",
    "assets-vendor-dir": "vendor",
    "document-root": "www",
    "assets-config-class": "AssetsManager\\Config\\DefaultConfig",
    "assets-package-class": "AssetsManager\\Package\\AssetsPackage",
    "assets-preset-class": "AssetsManager\\Package\\Preset",
    "assets-package-installer-class": "AssetsManager\\Composer\\Installer\\AssetsInstaller",
    "assets-autoload-generator-class": "AssetsManager\\Composer\\Autoload\\AssetsAutoloadGenerator",

    # this part is just for the example, no asset is embedded with the package
    "assets-presets": {
        "jquery.tablesorter": {
            "css": "vendor_assets/blue/style.css",
            "jsfiles_footer": [
                "vendor_assets/jquery.metadata.js",
                "min:vendor/jquery.tablesorter.min.js"
            ]
        },
        "jquery.highlight": {
            "css": "vendor_assets/jquery.highlight.css",
            "jsfiles_footer": "vendor_assets/jquery.highlight.js"
        }
    }
}

`assets-dir`：字符串

这定义了包中资产的相对路径。此目录必须存在且必须是唯一的（其值必须为字符串）。

`assets-vendor-dir`：字符串

这定义了从上述assets-dir目录中相对于包的资产的路径。如果不存在，此目录将被创建，并且必须是唯一的（其值必须为字符串）。此值最终与assets-dir连接，以构建依赖资产相对最终目录路径。

`document-root`：字符串（仅根目录）

这定义了用于构建包含包资产的URL的相对路径；这必须是HTTP根的基本目录。此目录必须存在且是唯一的（其值必须为字符串）。它仅适用于根包。

示例

例如，如果CSS样式的绝对路径为/home/www/project/www/assets/package/styles.css，并且您的document-root定义为/home/www/project/www/，则样式表标签将被渲染为

<link src="www/assets/package/styles.css" type="text/css" rel="stylesheet" />

`assets-presets`：数组的数组

资产预设是一组预定义的CSS或JavaScript文件，用于使用特定工具（例如jQuery插件等）。每个预设都可以在视图文件中写入时使用。

echo $assets_loader->getPreset( preset name )->__toHtml();

预设定义为key => array对的集合，其中key是预设名称（您将使用getPreset()方法调用的名称），相应的数组定义了要在整个模板中包含的所需资产文件。此数组可以在"css"、"js"、"jsfiles_header"、"jsfiles_footer"和"require"中具有索引。

`css`：字符串|数组

预设的CSS条目是包含一个或多个CSS文件的列表。这必须是一系列现有文件，文件路径必须相对于包assets目录。每个条目也可以是一个有效的URL，带有或不带有HTTP协议。

`js`、`jsfiles_header`和`jsfiles_footer`：字符串|数组

这些JavaScript条目分别定义了要在页面头部或页脚中包含的一些脚本。这必须是一系列现有文件，文件路径必须相对于包assets目录。每个条目也可以是一个有效的URL，带有或不带有HTTP协议。

`require`：字符串|数组

如果您的预设需要另一个预设，请使用此条目来定义一个或多个所需的另一个预设。这些预设必须在您的包或其依赖项中存在。

特定规则

您可以通知如果您的预设文件之一已经压缩或打包。为此，您可以在文件路径前加前缀min:或pack:。

示例

"jsfiles_footer": [
    "vendor/jquery.metadata.js",
    "min:vendor/jquery.tablesorter.min.js"
]

这样，库可以将已压缩文件与其他文件区分开来。

您还可以在全局资产文件堆栈中为您的资产文件定义一个位置。例如，如果您的预设定义了两个jQuery插件A和B，并且B需要A才能工作，这将非常有用。在这种情况下，您可能需要为A定义比B更高的位置，以确保A文件在B文件之前加载。

位置是一个范围在[-1; 100]之间的整数，其中100是堆栈的顶部文件，而-1是最后一个文件。如果您真的不在乎，可以简单地写first或last，它们分别被视为100和-1。

示例

"jsfiles_footer": [
    "first:vendor/jquery.metadata.js",
    "last:min:vendor/jquery.tablesorter.min.js"
]
// or
"jsfiles_footer": [
    "10:vendor/jquery.metadata.js",
    "11:min:vendor/jquery.tablesorter.min.js"
]

PHP类（仅限根目录）

您还可以覆盖用于管理配置、包、预设和资产安装的默认类。

`assets-config-class`：字符串

这定义了用作根包默认配置值的类。该类必须存在并实现\AssetsManager\Config\ConfiguratorInterface接口。

默认为\AssetsManager\Config\DefaultConfig。

`assets-package-class`：字符串

这定义了用于在安装和资产加载期间处理每个资产包的类。该类必须存在并实现\AssetsManager\Package\AssetsPackageInterface接口。

默认为\AssetsManager\Package\AssetsPackage。

`assets-preset-class`：字符串

这定义了用于处理每个资产预设的类。该类必须存在并实现\AssetsManager\Package\AssetsPresetInterface接口。

默认为\AssetsManager\Package\Preset。

`assets-package-installer-class`：字符串

这定义了用于Composer安装包的类。该类必须存在并实现\AssetsManager\Composer\Installer\AssetsInstallerInterface接口。

默认为\AssetsManager\Composer\Installer\AssetsInstaller。

`assets-autoload-generator-class`：字符串

这定义了用于资产数据库JSON文件生成器的类。该类必须存在并扩展抽象类\AssetsManager\Composer\Autoload\AbstractAssetsAutoloadGenerator。

默认为\AssetsManager\Composer\Autoload\AssetsAutoloadGenerator。

开发与文档

整个包都嵌入在AssetsManager命名空间中。

要安装所有开发PHP包，只需运行

~$ composer install --dev

可以通过运行Sami生成开发文档

~$ php vendor/sami/sami/sami.php render sami.config.php

此开发文档的最新版本可在网上找到，地址为http://docs.ateliers-pierrot.fr/assets-manager/。

作者与许可证

资产管理器

http://github.com/atelierspierrot/assets-manager

版权所有 (ↄ) 2013-2016，Pierre Cassat和贡献者

根据GPL版本3许可证授权。

https://open-source.org.cn/licenses/GPL-3.0

Les Ateliers Pierrot - 巴黎，法国

http://www.ateliers-pierrot.fr/ - contact@ateliers-pierrot.fr

atelierspierrot / assets-manager

维护者

详细信息

README

它是如何工作的？

安装

用法

如何通知扩展您的包资产？

项目生命周期中的使用方案

结构

资产管理器的使用

资产加载器对象

使用示例

配置

`assets-dir`：字符串

`assets-vendor-dir`：字符串

`document-root`：字符串（仅根目录）

`assets-presets`：数组的数组

`css`：字符串|数组

`js`、`jsfiles_header`和`jsfiles_footer`：字符串|数组

`require`：字符串|数组

特定规则

PHP类（仅限根目录）

`assets-config-class`：字符串

`assets-package-class`：字符串

`assets-preset-class`：字符串

`assets-package-installer-class`：字符串

`assets-autoload-generator-class`：字符串

开发与文档

作者与许可证

atelierspierrot / assets-manager

维护者

详细信息

README

它是如何工作的？

安装

用法

如何通知扩展您的包资产？

项目生命周期中的使用方案

结构

资产管理器的使用

资产加载器对象

使用示例

配置

assets-dir：字符串

assets-vendor-dir：字符串

document-root：字符串（仅根目录）

assets-presets：数组的数组

css：字符串|数组

js、jsfiles_header和jsfiles_footer：字符串|数组

require：字符串|数组

特定规则

PHP类（仅限根目录）

assets-config-class：字符串

assets-package-class：字符串

assets-preset-class：字符串

assets-package-installer-class：字符串

assets-autoload-generator-class：字符串

开发与文档

作者与许可证

`assets-dir`：字符串

`assets-vendor-dir`：字符串

`document-root`：字符串（仅根目录）

`assets-presets`：数组的数组

`css`：字符串|数组

`js`、`jsfiles_header`和`jsfiles_footer`：字符串|数组

`require`：字符串|数组

`assets-config-class`：字符串

`assets-package-class`：字符串

`assets-preset-class`：字符串

`assets-package-installer-class`：字符串

`assets-autoload-generator-class`：字符串