stolz/assets

一个超简单易用的资产管理库

维护者

详细信息

github.com/Stolz/Assets

源代码

问题

聊天

文档

安装: 452,383

依赖: 13

建议者: 0

安全: 0

星级: 292

关注者: 17

分支: 41

开放问题: 1

0.2.0 2020-01-30 16:10 UTC

Requires

Requires (Dev)

Suggests

  • laravel/laravel: Included ServiceProvider and Facade to work out of the box with Laravel

MIT e3b4d363a497cc18622f44ebb2bd929b31139bac

assetsjavascriptcssassetJSminifylaravelpipelineagnostic

This package is auto-updated.

Last update: 2024-08-29 03:52:45 UTC

README

一个超简单易用的PHP资产管理库。

Build Status Join the chat at https://gitter.im/Stolz/Assets

特性

  • 非常易于使用.
  • 自动生成HTML标签以包含您的JavaScript和CSS文件。
  • 自动检测资产类型（CSS、JavaScript或集合）。
  • 支持动态添加资产。
  • 支持本地（包括包）或远程资产。
  • 防止加载重复的资产。
  • 包含的资产 管道（将所有资产合并为单个文件并压缩）带有URL 时间戳和 gzip 支持。
  • 自动将本地资产前缀为可配置的文件夹名称或URL。
  • 支持安全（https）和无协议（//）链接。
  • 支持 集合（命名资产集合），可以嵌套，允许定义资产依赖关系。
  • 支持 多租户（多个独立配置）针对不同组的资产（此功能仅适用于Laravel >= 5.0）。
  • 允许默认自动加载预配置的资产和集合。

支持的框架

该库不依赖于框架，应该与任何框架或裸PHP应用程序良好协作。尽管如此，由于该库在Laravel用户中最受欢迎，以下说明已针对 Laravel 5 框架进行定制（仍在使用Laravel 4？）。如果您想在任何其他情况下使用该库，请阅读 非静态接口 说明。

安装

在您的项目基本目录中运行

composer require stolz/assets

如果您使用的是Laravel 5.5或更高版本，则无需执行其他操作。服务提供程序将自动为您加载。

如果您使用的是Laravel的较旧版本或您禁用了包发现功能，则必须手动编辑 config/app.php 文件，并在 providers 数组中添加服务提供程序。

'providers' => [
	//...
	'Stolz\Assets\Laravel\ServiceProvider',
	//...
],

无需添加Facade，该包将为您将其绑定到IoC。

使用

在您的视图/布局中

生成CSS <link rel="stylesheet"> 标签

echo Assets::css();

生成JavaScript <script> 标签

echo Assets::js();

在您的路由/控制器中

基本上，您要添加的资产类型，无论是CSS、JS还是两者的集合，都需要做的是

Assets::add('filename');

对于更高级的使用，请继续阅读，但请注意，这里没有记录一些其他方法。有关 所有可用方法的完整列表，请阅读提供的 API.md 文件。

一次添加多个资产

Assets::add(['another/file.js', 'one/more.css']);

从本地包添加资产

Assets::add('twitter/bootstrap:bootstrap.min.css');

注意，所有本地资产文件名都假定为相对于您的资产目录（可通过对 css_dir 和 js_dir 选项进行配置）进行配置，因此您无需每次都提供它，例如使用 js/file.js 或 css/file.css，只使用 file.js 或 file.css 就足够了。

您可以以相同的方式添加远程资产

Assets::add('//cdn.example.com/jquery.js');
Assets::add('http://example.com/style.css');

如果您的资产没有扩展名并且自动检测失败，则只需使用规范函数（它们也接受资产数组）。

Assets::addCss('CSSfile.foo');
Assets::addJs('JavaScriptFile.bar');

如果在某个时刻你发现自己添加了错误的资源，你可以重置它们并重新开始

Assets::reset();    // Reset both CSS and JS
Assets::resetCss(); // Reset only CSS
Assets::resetJs();  // Reset only JS

所有不生成输出的方法都支持链式调用

Assets::reset()->add('collection')->addJs('file.js')->css();

配置

要打开配置文件，请运行

php artisan vendor:publish

这将创建一个文件 config/assets.php，你可以用它来配置库。所有选项都有提供的注释，应该都是自解释的。

如果你使用的是 非静态接口，只需将配置设置的关联数组传递给类构造函数。

集合

集合是一组命名的资源，即一组JavaScript和CSS文件。任何集合都可以包含更多的集合，允许定义依赖关系和集合嵌套。集合可以在运行时或通过配置文件创建。

要注册一个在运行时用于后续使用的集合

Assets::registerCollection($collectionName, ['some', 'awesome', 'assets']);

使用配置文件预配置集合

// ... File: config/assets.php ...
'collections' => [
	'one'	=> 'one.css',
	'two'	=> ['two.css', 'two.js'],
	'external'	=> ['http://example.com/external.css', 'https://secure.example.com/https.css', '//example.com/protocol/agnostic.js'],
	'mix'	=> ['internal.css', 'http://example.com/external.js'],
	'nested' => ['one', 'two'],
	'duplicated' => ['nested', 'one.css','two.css', 'three.js'],
],

让我向您展示如何在不同的场景中使用上述集合

使用 Assets::add('two'); 将得到

<!-- CSS -->
<link type="text/css" rel="stylesheet" href="css/two.css" />
<!-- JS -->
<script type="text/javascript" src="js/two.js"></script>

使用 Assets::add('external'); 将得到

<!-- CSS -->
<link type="text/css" rel="stylesheet" href="http://example.com/external.css" />
<link type="text/css" rel="stylesheet" href="https://secure.example.com/https.css" />
<!-- JS -->
<script type="text/javascript" src="//example.com/protocol/agnostic.js"></script>

使用 Assets::add('mix'); 将得到

<!-- CSS -->
<link type="text/css" rel="stylesheet" href="css/internal.css" />
<!-- JS -->
<script type="text/javascript" src="http://example.com/external.js"></script>

使用 Assets::add('nested'); 将得到

<!-- CSS -->
<link type="text/css" rel="stylesheet" href="css/one.css" />
<link type="text/css" rel="stylesheet" href="css/two.css" />
<!-- JS -->
<script type="text/javascript" src="js/two.js"></script>

使用 Assets::add('duplicated'); 将得到

<!-- CSS -->
<link type="text/css" rel="stylesheet" href="css/one.css" />
<link type="text/css" rel="stylesheet" href="css/two.css" />
<!-- JS -->
<script type="text/javascript" src="js/two.js"></script>
<script type="text/javascript" src="js/three.js"></script>

注意，即使最后一个集合有重复的资源，它们也只被包含了一次。

管道

要启用管道，请使用 pipeline 配置选项

'pipeline' => true,

一旦启用，所有资源都将被连接并压缩成一个单一的文件，从而提高加载速度并减少浏览器渲染网页时发出的请求数量。

这个过程可能需要几秒钟，具体取决于资源的数量和您的连接速度，但它只会在您第一次加载一个之前从未使用管道的页面时触发。在随后的加载中，相同的页面（或使用相同资源的任何页面）将使用之前管道化的文件，从而提供更快的加载时间和更少的带宽使用。

注意：出于明显的原因，建议只在生产环境中使用管道。

如果自管道化以来您的资源已更改，请使用提供的 artisan 命令来清除管道缓存

php artisan asset:flush

或者，您可以将 pipeline 配置选项设置为字符串值，该值评估为 true。该值将用作管道哈希的盐。如果您使用 'auto' 作为值，则盐将根据您的资源最后修改时间自动计算。

示例

'pipeline' => 'version 1.0',

最后，如果您使用的是启用了 gzip_static 功能的 NGINX，请添加以下配置选项以自动创建适合的管道化资源的gzip版本

'pipeline_gzip' => true,

其他可配置选项

有关所有可用配置选项的 完整列表，请阅读提供的 API.md 文件。

  • 'autoload' => [],

    在此处设置默认加载的资产（CSS文件、JavaScript文件或集合）。

  • 'css_dir' => 'css',

  • 'js_dir' => 'js',

    覆盖资产的默认基础URL/文件夹。不要使用尾部斜杠！它们将被附加到您的所有本地资产。支持相对路径或完整URL。

  • 'pipeline_dir' => 'min',

    覆盖管道化资产的默认文件夹。不要使用尾部斜杠！

可以通过传递设置数组到 config() 方法来 动态更改任何配置选项。如果某些资产使用不同的基本目录或如果您想管道化一些资产而跳过其他资产，这非常有用。例如

echo Assets::reset()->add('do-not-pipeline-this.js')->js(),
     Assets::reset()->add('please-pipeline-this.js')->config(['pipeline' => true])->js();

多租户

注意： 此功能仅适用于 Laravel >= 5.0。

通过使用组来实现多租户。组是库的独立容器。每个组与其他组完全独立，因此使用自己的设置和资源流。如果你需要对不同类型的资源使用不同的方法（例如，你可能需要一些资源进行管道化处理，而其他资源则不需要），这非常有用。因此，当使用多个组时，你的责任是确保相互依赖的不同组的资源按正确的顺序加载。

默认情况下，如果没有定义组，将使用默认组。要定义一个组，只需在配置文件中将正常设置嵌套在数组中。数组键将是组名。例如

// ... File: config/assets.php ...

// Default group
'default' => [
	'pipeline' => true,
	'js_dir' => 'js',
	// ... more options for default group
],

// Other group
'group1' => [
	'pipeline' => false,
	'public_dir' => '/foo',
	// ... more options for group1
],

// Another group
'group2' => [
	'pipeline' => false,
	'css_dir' => 'css/admin',
	// ... more options for group2
],

要选择你想要交互的组，请使用 group() 方法。如果没有指定组，将使用 'default' 组。

Assets::add('foo.js')->js(); // Uses default group
Assets::group('group1')->add('bar.css')->css(); // Uses the 'group1' group.

请注意，group() 方法是 Facade 的一部分，因此它不接受链式调用，并且每次与库交互时都必须在开头使用。

非静态接口

你可以不使用静态方法来使用库。所有方法签名与上述描述相同，但使用类的实例。

// Load the library with composer
require __DIR__ . '/vendor/autoload.php';

// Set config options
$config = [
	'collections' => [...],
	'autoload' => [...],
	'pipeline' => true,
	'public_dir' => '/absolute/path/to/your/webroot/public/dir'
	...
];

// Instantiate the library
$assets = new \Stolz\Assets\Manager($config);

// Add some assets
$assets->add('style.css')->add('script.js');

// Generate HTML tags
echo $assets->css(),$assets->js();

示例集合

// jQuery (CDN)
'jquery-cdn' => ['//ajax.googleapis.ac.cn/ajax/libs/jquery/2.1.4/jquery.min.js'],

// jQuery UI (CDN)
'jquery-ui-cdn' => [
	'jquery-cdn',
	'//ajax.googleapis.ac.cn/ajax/libs/jqueryui/1.11.4/jquery-ui.min.js',
	// Uncomment to load all languages '//ajax.googleapis.ac.cn/ajax/libs/jqueryui/1.11.4/i18n/jquery-ui-i18n.min.js',
	// Uncomment to load a single language '//ajax.googleapis.ac.cn/ajax/libs/jqueryui/1.11.4/i18n/jquery.ui.datepicker-es.min.js',
	// Uncomment to load a theme' //ajax.googleapis.ac.cn/ajax/libs/jqueryui/1.11.4/themes/smoothness/jquery-ui.min.css',
],

// Zurb Foundation (CDN)
'foundation-cdn' => [
	'jquery-cdn',
	'//cdn.jsdelivr.net.cn/foundation/5.5.1/css/normalize.css',
	'//cdn.jsdelivr.net.cn/foundation/5.5.1/css/foundation.min.css',
	'//cdn.jsdelivr.net.cn/foundation/5.5.1/js/foundation.min.js',
	'app.js'
],

// Twitter Bootstrap (CDN)
'bootstrap-cdn' => [
	'jquery-cdn',
	'//netdna.bootstrap.ac.cn/bootstrap/3.3.5/css/bootstrap.min.css',
	'//netdna.bootstrap.ac.cn/bootstrap/3.3.5/css/bootstrap-theme.min.css',
	'//netdna.bootstrap.ac.cn/bootstrap/3.3.5/js/bootstrap.min.js'
],

// Flags of all countries in one sprite (CDN)
'flags-16px' => ['//cloud.github.com/downloads/lafeber/world-flags-sprite/flags16.css'],
'flags-32px' => ['//cloud.github.com/downloads/lafeber/world-flags-sprite/flags32.css'],

许可

MIT 许可证 © Stolz

请阅读提供的 LICENSE 文件以获取详细信息。

故障排除 / 常见问题解答

我在哪里可以寻求帮助/支持？

首先，请确保您已经阅读了 常见问题解答 和 API 文档，并且如果您仍然需要帮助，请在我们的 Gitter 聊天 中解释您的问题。

我应该将我的资源文件复制到哪里？

它们应该复制到您使用 css_dir 和 js_dir 配置选项指定的子文件夹中。这两个文件夹都是相对于您的 webroot/public 文件夹的。对于包资源，也是相同的，但相对于您的 webroot/public 文件夹内的 packages 文件夹。

例如：假设以下场景

  • 您正在使用默认设置。
  • 您的 webroot/public 文件夹是 /myproject/public
  • 您的 webroot/public 包含
    • /myproject/public/css/foo.css
    • /myproject/public/js/bar.js
    • /myproject/public/packages/somevendor/somepackage/css/lorem.css
    • /myproject/public/packages/anothervendor/anotherpackage/js/ipsum.js

然后要加载资源，你应该运行

Assets::add([
	'foo.css',
	'bar.js',
	'somevendor/somepackage:lorem.css',
	'anothervendor/anotherpackage:ipsum.js'
]);

为什么资源在主页上工作，但在子页面上不工作？

如果您的资源似乎在 http://example.com 上工作得很好，但在 http://example.com/some/other/place 上不工作，您很可能会使用相对链接。如果您在一个不是您根 URI 的 URI 中使用相对于您的根 URI 的链接，并且要使它们工作，您必须使用指向您的根 URI 的 <base> HTML 标签。这种行为与库或框架无关，而是与 HTML 标准 本身相关。在报告错误之前，请确保您理解 相对链接的语义。

管道不起作用

确保已设置 public_dir 配置选项，并且它指向 webroot/public 文件夹的 绝对 路径，并且运行库的用户对该文件夹具有写入权限。

如果您使用大量的资源，请确保您的连接足够快，并且您的计算机足够强大，能够在 PHP 最大执行时间到达之前下载和压缩所有资源。

我可以使用库的多个实例吗？

当然可以，但没必要。您最好使用多租户功能（仅适用于Laravel >= 5.0）。

我能否即时更改设置？

可以。有一个公开的config()方法可以即时更改设置。这允许您使用具有不同设置的相同库实例。例如：

echo Assets::add('jquery-cdn')->js();
echo Assets::reset()->add(['custom.js', 'main.js'])->config(['pipeline' => true])->js();

如果您想将不同的设置永久保存，请使用多租户功能。

我能否过滤/预处理我的资产？

该库不包含任何内置的过滤/预处理功能，但当启用管道时，它提供了一个提供您自定义方法的方式。只需使用fetch_command配置选项来应用自定义过滤即可。

我该如何贡献？

向develop分支发送拉取请求。阅读下一个问题，以增加您PR被接受的机会。

为什么我的拉取请求没有被接受？

请记住，该库存在的主要原因是为了使用方便。如果您的PR涉及更改这一点，并使库变得难以使用，则它不会被接受。

这是一个与框架无关的库，如果您的PR使用了与您框架相关的代码，则它不会被接受。

如果您贡献添加了新功能，请确保为它包含适当的PHPUnit测试。

请使用PHP_CodeSniffer确保您的代码遵循项目编码标准（这是PSR-2的略微变化）。