enjoys / assets-collector
Assets Collector CSS and JS
Installs: 1 494
Dependents: 2
Suggesters: 0
Security: 0
Stars: 1
Watchers: 2
Forks: 0
Open Issues: 0
Requires
- php: ^7.4 | ^8.0
- enjoys/functions: ^2.3
- enjoys/url-converter: *
- psr/http-client: ^1.0
- psr/http-factory: ^1.0
- psr/log: ^1.0 | ^2.0 | ^3.0
- symfony/polyfill-php80: ^1.0
- tedivm/jshrink: ^1.6.2 | ~1.5.0
- tubalmartin/cssmin: ^4.1
Requires (Dev)
- guzzlehttp/guzzle: ^7.2
- phpunit/phpunit: ^9.5
- symfony/var-dumper: ^5.4 | ^6.0
- twig/twig: ^3.2
- vimeo/psalm: ^4.8
- dev-master
- 2.x-dev
- 2.5.0
- 2.4.5
- 2.4.4
- 2.4.3
- 2.4.2
- 2.4.1
- 2.4.0
- 2.3.0
- 2.2.2
- 2.2.1
- 2.2.0
- 2.1.0
- 2.0.4
- 2.0.3
- 2.0.2
- 2.0.1
- 2.0.0
- 1.x-dev
- 1.1.6
- 1.1.5
- 1.1.4
- 1.1.3
- 1.1.2
- 1.1.1
- 1.1.0
- 1.0.10
- 1.0.9
- 1.0.8
- 1.0.7
- 1.0.6
- 1.0.5
- 1.0.4
- 1.0.3
- 1.0.2
- 1.0.1
- 1.0.0
- 0.9.91
- 0.9.9
- 0.9.8.4
- 0.9.8.3
- 0.9.8.2
- 0.9.8.1
- 0.9.8
- 0.9.7
- 0.9.6
- 0.9.5.2
- 0.9.5.1
- 0.9.5
- 0.9.4
- 0.9.3
- 0.9.2.1
- 0.9.2
- 0.9.1
- 0.9.0
- dev-dev
- dev-use-flysystem
This package is auto-updated.
Last update: 2024-04-15 18:10:07 UTC
README
Установка
composer require enjoys/assets-collector
Использование
Настройка окружения
use Enjoys\AssetsCollector\Assets; use Enjoys\AssetsCollector\Environment; //project directory $projectDir = __DIR__; //compile path relative project directory $assetsDir = $projectDir .'/assets'; //or relative project directory //$assetsDir = 'assets'; $environment = new Environment($assetsDir, $projectDir); //Base URL to compile path for Web $environment->setBaseUrl("/assets-collector/example/assets"); //Set strategy, default STRATEGY_MANY_FILES $environment->setStrategy(Assets::STRATEGY_ONE_FILE); //Assets::STRATEGY_MANY_FILES //Cache time for files in strategy STRATEGY_ONE_FILE $environment->setCacheTime(0); //cache time in seconds //Adds the output version, for example //example.php/style.css?v=123 $environment->setVersion(123); //You can change the parameter for the version $environment->setParamVersion('?ver='); /** * YYou can add a logger that implements \Psr\Log\LoggerInterface, for example, Monolog * @var \Psr\Log\LoggerInterface $logger */ $environment->setLogger($logger);
Инициализация класса
/** @var \Enjoys\AssetsCollector\Environment $environment */ $assets = new \Enjoys\AssetsCollector\Assets($environment);
Добавление в коллекцию
Если третьим параметрам передать namespace, то при выводе так же нужно его писать. Своего рода группировка
/** @var \Enjoys\AssetsCollector\Assets $assets */ $assets->add('css', [ 'style/style.css', //относительный путь, относительно текущей рабочей директории __DIR__ . '/style/style.css', //полный путь '//example.com/style.css', //сокращенная URL ссылка 'https://example.com/style.css', //URL ссылка 'url:/assets/css/style.css', // URL ссылка 'local:/assets/css/style.css', // URL ссылка (local: и url: идентичны) ['style.css', \Enjoys\AssetsCollector\AssetOption::MINIFY => false], //попускает минификацию конкретного файла ['goods/style.css', \Enjoys\AssetsCollector\AssetOption::REPLACE_RELATIVE_URLS => false], //не заменяет относительные ссылки - оставляет так как есть ]);
Дополнительные параметры
Можно передать ссылку на ресурс в качестве массива, где 1-й элемент массива — сам путь, а последующие элементы массива — это параметры
use Enjoys\AssetsCollector\AssetOption; /** @var \Enjoys\AssetsCollector\Assets $assets */ $assets->add('css', [ [ __DIR__.'/style.css', // По-умолчанию все ресурсы минифицируются, если указать явно false, этот ресурс пропустит минификацию AssetOption::MINIFY => false, // Если нужно создать дополнительные симлинки, то можно указать их в этом параметре, в качества массива, // где ключ - сама ссылка, а значение - исходный файл или директория (цель) // Это бывает необходимо если в ресурсе есть относительные ссылки, и чтобы был к ним доступ нужно прописать // явно все символические ссылки AssetOption::SYMLINKS => [ __DIR__.'/symlink' => __DIR__.'/../../../target', //... ], // При STRATEGY_MANY_FILES будут добавлены html-аттрибуты, // примерно это будет выглядеть так // <script attribute-key='attribute-value' attribute-without-value attribute-without-value src='...'> AssetOption::ATTRIBUTES => [ 'attribute-key' => 'attribute-value', 'attribute-without-value' => null, 'attribute-without-value-another-method', //... ], // При STRATEGY_ONE_FILE если будет установлена эта опция в true, то именно этот asset в сборку не попадет, // а выведется отдельно AssetOption::NOT_COLLECT => true, // При false - не заменяет относительные ссылки - оставляет так как есть. // По-умолчанию true, все относительные ссылки заменяются на абсолютные AssetOption::REPLACE_RELATIVE_URLS => false ], //... ]);
При сборке assets все собирается по порядку как пришли данные в коллекцию, так было раньше, и так стало сейчас по
умолчанию. Но можно выбрать способ вставки assets в коллекцию, изменив последний параметр
в \Enjoys\AssetsCollector\Assets::add push или unshift.
Это удобно использовать например в шаблонах twig, где например в самом главном шаблоне подключаются общие стили, а потом в дочерних шаблонах подключаются конкретные стили, так вот при push, общие стили будут подключены ниже чем конкретные, при unshift - подключены будут сначала стили общие, потом конкретные, хотя twig все равно их будет обрабатывать в обратном порядке - от дочерних шаблонов до общих
push- дефолтное значение вставляет данные в конецunshift- вставляет данные в начало коллекции.
/** @var \Enjoys\AssetsCollector\Assets $assets */ $assets->add($type = 'css|js', [], $namespace, $method = 'push|unshift');
Вывод
/** @var \Enjoys\AssetsCollector\Assets $assets */ $assets->get('css'); //get Css with default namespace $assets->get('js', 'admin_namespace'); //Get Js with namespace `admin_namespace`
При $environment->setStrategy(Assets::STRATEGY_ONE_FILE); происходит чтение всех файлов и запись в один файл. Вернет html строку для подключения стилей или скриптов
<link type='text/css' rel='stylesheet' href='/assets/3c2ea3240f78656c2e4ad2b7f64a5bc2.css?_ver=1610822303'/>
При $environment->setStrategy(Assets::STRATEGY_MANY_FILES); вернет стили или скрипты по отдельности, примерно так, удобно при разработке
<link type='text/css' rel='stylesheet' href='/assets/bootstrap.min.css?_ver=1610822303'/> <link type='text/css' rel='stylesheet' href='https://example.com/style.css?_ver=1610822303'/>
ДЛЯ JS ВСЕ АНАЛОГИЧНО, ЗА ИСКЛЮЧЕНИЕМ HTML В ВЫВОДЕ
Twig Extension
Подключение расширения
/** * @var \Twig\Environment $twig * @var \Enjoys\AssetsCollector\Assets $assets */ $twig->addExtension(new \Enjoys\AssetsCollector\Extensions\Twig\AssetsExtension($assets));
Добавление в коллекцию в шаблоне.
Ниже показаны примеры, как можно подключить ресурсы в шаблоне.
Стоит обратить внимание, что не полные пути будут относительно текущей рабочей директории, или относительно директории проекта
{{ asset('css', [{0: 'https://cdn.jsdelivr.net/npm/bootstrap@5.0.0-beta1/dist/css/bootstrap.css', 'minify': false}]) }}
{{ asset('css', 'https://cdn.jsdelivr.net/npm/bootstrap@5.0.0-beta1/dist/css/bootstrap.css') }}
{{ asset('js', ['path/script.js', 'script.js'], 'namespace') }}
С версии 2.2.1 поддерживаются пути twig
Необходимо при инициализации расширения передать загрузчик, который реализует \Twig\Loader\LoaderInterface,
например \Twig\Loader\FilesystemLoader
/** * @var \Enjoys\AssetsCollector\Extensions\Twig\AssetsExtension $extension * @var \Enjoys\AssetsCollector\Assets $assets * @var \Twig\Loader\LoaderInterface $loader */ $extension = new AssetsExtension($assets, $loader));
Вывод в шаблоне
{{ eCSS() }}
{{ eJS('namespace') }}
Настройки CSS Minify
По умолчанию в качестве минификатора используется NullMinify::class, то есть ничего не сжимается. Для установки минификатора, в Environment используется метод Environment::setMinifyCSS(MinifyInterface $minifyImpl)
Базовая реализация CSS Minify реализована с помощью библиотеки tubalmartin\CssMin Подробное описание параметров: https://github.com/tubalmartin/YUI-CSS-compressor-PHP-port#api
Легко можно реализовать минификацию с помощью других библиотек, реализовав интерфейс \Enjoys\AssetsCollector\Content\Minify\MinifyInterface::class
use Enjoys\AssetsCollector\Content\Minify\Adapters\CssMinify; /** @var \Enjoys\AssetsCollector\Environment $environment */ //необязательно передавать все параметры, можно только выборочно $environment->setMinifyCSS( new CssMinify([ 'keepSourceMapComment' => false, //bool 'removeImportantComments' => true, //bool 'setLineBreakPosition' => 1000, //int 'setMaxExecutionTime' => 60, //int 'setMemoryLimit' => '128M', 'setPcreBacktrackLimit' => 1000000, //int 'setPcreRecursionLimit' => 500000, //int ]) );
Настройки JS Minify
По умолчанию в качестве минификатора используется NullMinify::class, то есть ничего не сжимается. Для установки минификатора, в Environment используется метод Environment::setMinifyJS(MinifyInterface $minifyImpl)
Базовая реализация CSS Minify реализована с помощью библиотеки JShrink Подробнее про JShrink
Легко можно реализовать минификацию с помощью других библиотек, реализовав интерфейс \Enjoys\AssetsCollector\Content\Minify\MinifyInterface::class
use Enjoys\AssetsCollector\Content\Minify\Adapters\JsMinify; /** @var \Enjoys\AssetsCollector\Environment $environment */ // Необязательно передавать все параметры, можно только выборочно $environment->setJsMinifyOptions( new JsMinify([ 'flaggedComments' => false ]) );