larakit/lk-staticfiles

[Larakit] Библиотека для Laravel для управления статикой (сборка в один файл, сжатие JS/CSS, добавление хэша в URL для сброса кэша браузера)

dev-master 2018-03-01 03:36 UTC

This package is auto-updated.

Last update: 2021-09-15 18:12:14 UTC


README

Total Downloads Latest Stable Version Latest Unstable Version License License Gitter #[Larakit Staticfiles] Библиотека для управления статикой (сборка в один файл, сжатие JS/CSS, добавление хэша в URL для сброса кэша браузера)

Модуль был портирован с модуля для фреймворка Kohana, который служил мне верой и правдой более 5 лет ( и модуль, и Kohana :) ) (подробнее я описывал его тут https://habrahabr.ru/post/112852/)

Примечание: будем считать, что проект Laravel у вас уже создан

###1. Файл с правилами подключения статики

Для порядка добавим подключаемые стили и скрипты вынесем в отдельный файл, например

./app/Http/staticfiles.php

Затем в файле

./app/Http/routes.php

подключим его

<?php

Route::get('/', function () {
    return view('welcome');
});

require app_path('Http/staticfiles.php');

###2. Установим пакет

$composer require larakit/lk-staticfiles

Далее нужно либо воспользоваться рекомендациями пакета https://github.com/larakit/lk-boot и произвести две правки

./app/Http/Kernel.php

и

./config/app.php

либо руками зарегистрировать в

./config/app.php

сервис-провайдер "Larakit\StaticFiles\LarakitServiceProvider"

<?php

return [
   ...
   'providers' => [
      ...,
      Larakit\StaticFiles\LarakitServiceProvider::class
   ],
   ...
];

Проверим что все хорошо, для этого наберем в консоли команду:

php artisan | grep larastatic

Если вы видите текст:

larastatic
  larastatic:deploy    Выложить статику из зарегистрированных пакетов в DOCUMENT_ROOT

поздравляю, пакет был корректно установлен и инициализирован!

###3. Заполним staticfiles.php инструкциями по подключению CSS

Для начала посмотрим содержимое по-умолчанию главной страницы после установки фреймворка

68747470733a2f2f686162726173746f726167652e6f72672f66696c65732f3038632f3137652f3538632f30386331376535386365636434323764396639623237623362343961393062322e706e67

и постараемся воспроизвести его при помощи данного пакета

<?php
\Larakit\StaticFiles\Css::instance()
    ->add('https://fonts.googleapis.com/css?family=Lato:100')
    ->addInline('
        html, body {
            height: 100%;
        }
        
        body {
            margin: 0;
            padding: 0;
            width: 100%;
            display: table;
            font-weight: 100;
            font-family: "Lato";
        }
        
        .container {
            text-align: center;
            display: table-cell;
            vertical-align: middle;
        }
        
        .content {
            text-align: center;
            display: inline-block;
        }
        
        .title {
            font-size: 96px;
        }    
    ');

Чтобы добавленные стили и скрипты вставились во все страницы сайта надо в вашем шаблоне прописать вызов

68747470733a2f2f686162726173746f726167652e6f72672f66696c65732f3565352f3131622f3863302f35653531316238633036346234353934383561643965626262363635343935612e706e67

Получилось!

Примечание: результаты выполнения

\Larakit\StaticFiles\Css::instance()
    ->add('"https://fonts.googleapis.com/css?family=Lato:100')
    ->addInline('
        html, body {
            height: 100%;
        }
     ');

и

\Larakit\StaticFiles\Css::instance()
    ->add('"https://fonts.googleapis.com/css?family=Lato:100');
    
\Larakit\StaticFiles\Css::instance()
    ->addInline('
        html, body {
            height: 100%;
        }
     ');

будут одинаковы.

###4. Работа с JS Она не намного сложнее работы с JS.

Только помимо двух методов добавляющих стили по ссылке или методом inline-вставки как в CSS, здесь есть еще два метода:

  • добавление onLoad
  • добавление Noscript

Чтобы продемонстрировать функционал JS-менеджера - дополним пример: сделаем так, чтобы

  • после загрузки страницы вылетал алерт "привет!"
  • загружалась яндекс карта
  • при отключенном javascript показывался текст "Упс, включи JS!"

Напомню, все это мы делаем в файле

./app/Http/staticfiles.php

Итак, дополним его согласно новым требованиям

\Larakit\StaticFiles\Js::instance()
    //подключим jQuery
    ->add('https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.3/jquery.min.js')
    //подключим API яндекс карт
    ->add('//api-maps.yandex.ru/2.1/?lang=ru_RU')
    ->addInline('
        var myMap;
        // Дождёмся загрузки API и готовности DOM.
        ymaps.ready(init);
        function init () {
            // Создание экземпляра карты и его привязка к контейнеру с
            // заданным id ("map").
            myMap = new ymaps.Map("map", {
                // При инициализации карты обязательно нужно указать
                // её центр и коэффициент масштабирования.
                center: [55.76, 37.64], // Москва
                zoom: 10
            }, {
                searchControlProvider: "yandex#search"
            });
        }    
    ')
    //добавим привествие при загрузке страницы
    ->addOnload('alert("привет!")')
    //добавим сообщение при выключенном JS
    ->addNoscript('Упс, включи JS!');
//добавим необходиеы стили для карты
\Larakit\StaticFiles\Css::instance()
    ->addInline('
        #map {
            width: 100%;
            height: 200px;
        }   
    ');

Дополним и сам шаблон:

  • добавим вызов функции вставки скриптов
  • добавим контейнер для карты

68747470733a2f2f686162726173746f726167652e6f72672f66696c65732f3232332f6161382f3631342f32323361613836313431333434373038616131613435653634333530663765302e706e67

Обновляем страницу:

  1. alert при загрузке страницы вылетел

68747470733a2f2f686162726173746f726167652e6f72672f66696c65732f6164632f6566312f3034302f61646365663130343034373834616461623562623335346366633461333634612e706e67

  1. Яндекс.карта появилась

68747470733a2f2f686162726173746f726167652e6f72672f66696c65732f3039322f3065342f6363302f30393230653463633038313834663430626435313562313732393864366162622e706e67

  1. отключаем javascript в браузере и перезагружаем страницу - справа вверху видим надпись "Упс, включи JS!"

68747470733a2f2f686162726173746f726167652e6f72672f66696c65732f3966652f6330302f3336642f39666563303033366439636234623234386336346138653832306133316466392e706e67

Смотрим как были добавлены скрипты: 68747470733a2f2f686162726173746f726167652e6f72672f66696c65732f6630632f6363612f3163642f66306363636131636439653834663532613763616164393161333963633336362e706e67

###5. Способы распространения статики Их всего три:

  1. использование внешних ресурсов (простое подключение)
  2. использование статики из DOCUMENT_ROOT (простое подключение)
  3. использование статики из vendor-пакетов или node_modules (требует выкладки в DOCUMENT_ROOT)

Так вот для третьего пункта и существует команда, которая производит выкладку пакетов в директорию

./public/packages/...

запускается она так:

php artisan larastatic:deploy 

и после ее запуска будет произведена выкладка статики для каждого зарегистрированного пакета

Как использовать готовые пакеты со статикой:

  • заходите на github.com и вписываете в поле поиска "lk-staticfiles"
  • находите пакет, например, https://github.com/larakit/sf-bootstrap
  • внутри него уже есть подробнейшая документация по использованию
  • подключаете его в композере
  • и все!

он сам пропишется где надо и будет работать.

Понимаете? Никаких тебе танцев в написанием gulp/grunt-правил для каждого проекта. Просто прописал в composer записимость, он установился и автоматически подключился на страницу.

Причем с возможностью отключения/включения на определенных роутах по маске (см. ниже)

###6. Встроенные возможности по клиентской оптимизации

В пакете предусмотрены следующие возможности:

  • минимизация CSS [inline] - по умолчанию включена только на окружении "production"
  • минимизация CSS [external] - по умолчанию включена только на окружении "production"
  • минимизация JS [inline] - по умолчанию включена только на окружении "production"
  • минимизация JS [external] - по умолчанию включена только на окружении "production"
  • минимизация JS [onload] - по умолчанию включена только на окружении "production"
  • сборка всех CSS в один билд-файл [inline] - по умолчанию включена только на окружении "production"
  • сборка всех CSS в один билд-файл [external] - по умолчанию включена только на окружении "production"
  • сборка всех JS в один билд-файл [inline] - по умолчанию включена только на окружении "production"
  • сборка всех JS в один билд-файл [external] - по умолчанию включена только на окружении "production"
  • сборка всех JS в один билд-файл [onload] - по умолчанию включена только на окружении "production"
  • изменение хоста, с которого раздается статика - по умолчанию пустое значение, т.е. текущий домен

А теперь рассмотрим все по отдельности: для этого добавим еще стили и скрипты, размещенные внутри проекта

  • /js/js.js
  • /css/css.css
<?php
\Larakit\StaticFiles\Css::instance()
    ->add('https://fonts.googleapis.com/css?family=Lato:100')
    ->add('/css/css.css')
    ->add('/css/css2.css')
    ->add('/css/css3.css')
    ->add('/css/css4.css')
    ->add('/css/css5.css')
    ->addInline('
        html, body {
            height: 100%;
        }
        
        body {
            margin: 0;
            padding: 0;
            width: 100%;
            display: table;
            font-weight: 100;
            font-family: "Lato";
        }
        
        .container {
            text-align: center;
            display: table-cell;
            vertical-align: middle;
        }
        
        .content {
            text-align: center;
            display: inline-block;
        }
        
        .title {
            font-size: 96px;
        }    
    ');
\Larakit\StaticFiles\Js::instance()
    //подключим jQuery
    ->add('https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.3/jquery.min.js',null,true)
    //подключим API яндекс карт
    ->add('//api-maps.yandex.ru/2.1/?lang=ru_RU',null,true)
    ->add('/js/js.js')
    ->add('/js/js2.js')
    ->add('/js/js3.js')
    ->add('/js/js4.js')
    ->add('/js/js5.js')
    ->addInline('
        var myMap;
        // Дождёмся загрузки API и готовности DOM.
        ymaps.ready(init);
        function init () {
            // Создание экземпляра карты и его привязка к контейнеру с
            // заданным id ("map").
            myMap = new ymaps.Map("map", {
                // При инициализации карты обязательно нужно указать
                // её центр и коэффициент масштабирования.
                center: [55.76, 37.64], // Москва
                zoom: 10
            }, {
                searchControlProvider: "yandex#search"
            });
        }    
    ')
    //добавим привествие при загрузке страницы
    ->addOnload('alert("привет!")')
    //добавим сообщение при выключенном JS
    ->addNoscript('Упс, включи JS!');
//добавим необходимые стили для карты
\Larakit\StaticFiles\Css::instance()
    ->addInline('
        #map {
            width: 100%;
            height: 200px;
        }   
    ');

/js/js.js /js/js2.js /js/js3.js /js/js4.js /js/js5.js

confirm(
    "Выполнился скрипт js.js?"
);

/css/css.css /css/css2.css /css/css3.css /css/css4.css /css/css5.css

body{
    color : #EB6251;;
}

Сохраним показания YSlow перед началом оптимизации

Так выглядели подключенные стили до оптимизации

68747470733a2f2f686162726173746f726167652e6f72672f66696c65732f6638652f3336642f6462652f66386533366464626533383934363265396137613437366661633130636636342e706e67

А так скрипты

68747470733a2f2f686162726173746f726167652e6f72672f66696c65732f6333622f3736362f3938622f63336237363639386237643234613234616563313532326131656533303437352e706e67

###6.1 Включение сборки CSS и JS в билд-файлы Для этого в .env пропишем:

# включим сборку CSS [inline] в один файл
LARAKIT_STATIC_CSS_INLINE_BUILD=1

# включим сборку CSS [подключенные по ссылке] в один файл
LARAKIT_STATIC_CSS_EXTERNAL_BUILD=1

# включим сборку CSS [inline] в один файл
LARAKIT_STATIC_JS_INLINE_BUILD=1

# включим сборку CSS [подключенные по ссылке] в один файл
LARAKIT_STATIC_JS_EXTERNAL_BUILD=1

# включим сборку CSS [onload] в один файл
LARAKIT_STATIC_JS_ONLOAD_BUILD=1

Теперь код нашей странички стал намного компактнее:

68747470733a2f2f686162726173746f726167652e6f72672f66696c65732f3838352f3565302f6232642f38383535653062326434633834313466383034386361393864383165306431382e706e67

###6.3 Исключение из билд-файла некоторых CSS и JS Мы видим, что в билды попали файлы, которые не надо собирать в билды, а значит они должны отдаваться именно из того места, откуда были подключены:

Установим для них параметр no_build в true:

  • в CSS это четвертый параметр
  • в JS это третий параметр
\Larakit\StaticFiles\Css::instance()
    ->add(
        //внешний стиль
        'https://fonts.googleapis.com/css?family=Lato:100',
        //media - условие использования, например "all" или "print"
        null, 
        //условие подключения, например "if IE 6"
        null,
        //no_build
        true
    )
    ...
;

\Larakit\StaticFiles\Js::instance()
    //подключим jQuery
    ->add(
        'https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.3/jquery.min.js',
        //условие подключения, например "if IE 6"
        null,
        //no_build
        true
    )
    //подключим API яндекс карт
    ->add(
        '//api-maps.yandex.ru/2.1/?lang=ru_RU',
        //условие подключения, например "if IE 6"
        null,
        //no_build
        true
    )
    ...
;

Результат:

68747470733a2f2f686162726173746f726167652e6f72672f66696c65732f6334302f6361332f3637322f63343063613336373230376634393463626435303932613235666338336232312e706e67

###6.2 Включение минимизации CSS и JS Для этого в .env пропишем:

LARAKIT_STATIC_CSS_INLINE_MIN=1
LARAKIT_STATIC_CSS_EXTERNAL_MIN=1

Добавим в .env еще инструкций:

LARAKIT_STATIC_CSS_INLINE_MIN=1
LARAKIT_STATIC_CSS_INLINE_MIN=1
LARAKIT_STATIC_CSS_EXTERNAL_MIN=1
LARAKIT_STATIC_JS_INLINE_MIN=1
LARAKIT_STATIC_JS_EXTERNAL_MIN=1
LARAKIT_STATIC_JS_ONLOAD_MIN=1

Выложим статику еще раз,

php artisan larastatic:deploy

чтобы были перегенерированы ссылки на подключаемую статику для сброса кэша браузеров

Продемонстрируем результаты работы на примере CSS

Было

68747470733a2f2f686162726173746f726167652e6f72672f66696c65732f6335322f3736612f3261302f63353237366132613062343134376566393335653065353536623339623966642e706e67

Стало

68747470733a2f2f686162726173746f726167652e6f72672f66696c65732f6565632f3637372f6331612f65656336373763316134313034623463613136663537326239313330303631342e706e67

Продемонстрируем результаты работы на примере CSS

Было

68747470733a2f2f686162726173746f726167652e6f72672f66696c65732f3335332f6434322f3430642f33353364343234306464313134656537393866343064386335623264616636382e706e67

Стало

68747470733a2f2f686162726173746f726167652e6f72672f66696c65732f3966332f6133652f3534392f39663361336535343962636634663839386639386461633439393633383966372e706e67

###6.3 Отдача статики с другого домена

Имитируем перенос статики на CDN, для этого создадим домен "st1.staticfiles" и сделаем его алиасом для домена "staticfiles".

Затем добавим в .env еще инструкций:

LARAKIT_STATIC_PREFIX=http://st1.staticfiles

Результат: 68747470733a2f2f686162726173746f726167652e6f72672f66696c65732f6533612f3061322f6335342f65336130613263353430636334386230616637363963376264363165356434322e706e67

Смотрим показания YSlow перед началом оптимизации

68747470733a2f2f686162726173746f726167652e6f72672f66696c65732f6563372f3032352f6634302f65633730323566343030306134313633613662383831666135666565356130632e706e67

А теперь снова запускаем YSlow для проверки результатов нашей оптимизации:

68747470733a2f2f686162726173746f726167652e6f72672f66696c65732f3262332f6163312f3936332f32623361633139363339656534633930383939616534646633323231623764332e706e67

####Т.е. удалось поднять Overall performance score c 80 до 93

Смотрим показания YSlow перед началом оптимизации

68747470733a2f2f686162726173746f726167652e6f72672f66696c65732f3063362f3161352f6466312f30633631613564663163363634383666623464336631613437363636373264382e706e67

А теперь снова запускаем YSlow для проверки результатов нашей оптимизации:

68747470733a2f2f686162726173746f726167652e6f72672f66696c65732f3337332f3932342f6239312f33373339323462393162623834373761393637333034353236333230626362642e706e67

Результат был бы еще выше, если бы мы использовали полноценные большевесные стили и скрипты в большом количестве, а не несколько пустышек, взятых для примеров.

По-моему, не плохо для коробочного решения делающего это автоматически.

###7. Создание собственных пакетов

Ну и, пожалуй, самое главное: возможность оформлять свои пакеты. Сделаем два вида пакетов:

  • с использованием CDN
  • с распространением статики из пакета

Рекомендации:

  • (для удобного поиска на packagist) обязательно вписывайте следующие теги "laravel, lk-staticfiles"
  • (для удобного поиска на github) в Description репозитория на github вписывайте префикс "[Larakit][lk-staticfiles] "

68747470733a2f2f686162726173746f726167652e6f72672f66696c65732f3864622f6662362f3633652f38646266623636336534393534626132626237623433303165326331616535302e706e67

###7.1 Создание собственных пакетов с использованием CDN

Создаем composer.json

{
    "name": "larakit/sf-bootstrap",
    "description": "sf-bootstrap",
    "keywords": [
        "larakit",
        "laravel",
        "laravel 5",
        "bootstrap",
        "lk-staticfiles"
    ],      
    "license": "MIT",
    "version": "3.3.6",
    "require": {
        "larakit/sf-jquery": "*"
    },
    "autoload": {
        "files": [
            "init.php"
        ]
    }
}

В разделе require укажите статические пакеты, от которых зависит ваш пакет (например, если вам нужен jQuery), а если таких нет впишите зависимость от текущего пакета

{
    "require":{
            "larakit/lk-staticfiles":"*"
    },
}

В автоподключаемый файл init.php впишите инструкции по подключению и снова укажите зависимости от пакетов, чтобы они были подключены до создаваемого пакета

<?php
\Larakit\StaticFiles\Manager::package('larakit/sf-bootstrap')
    ->usePackage('larakit/sf-jquery')
    ->js('//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.5/js/bootstrap.min.js')
    ->css('//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.5/css/bootstrap.min.css');

Собственно все! Для использования вам достаточно прописать в композер проекта "require": "/sf-ваш_пакет"

###7.2 Создание собственных пакетов с распространением статики из пакета Точно также создаем composer.json и init.php. Единственное отличие: в init.php прописываем директорию со статикой, откуда будет производится ее выкладка в DOCUMENT_ROOT из vendor.

<?php
\Larakit\StaticFiles\Manager::package('larakit/sf-larakit-js')
    
    //из этого относительного пути внутри пакета будет произведена выкладка
    ->setSourceDir('public')
    
    //обязательно подключить указанный зависимый пакет ПЕРЕД текущим пакетом
    ->usePackage('larakit/sf-jquery')
    
    //искать JS внутри директории SOurceDir
    ->jsPackage('js/larakit.js');

это означает, что при выкладке будет взято содержимое директории

./vendor/larakit/sf-larakit-js/public

и выложено в

./public/packages/larakit/sf-larakit-js/

Сама выкладка напомню производится путем запуска команды:

php artisan larastatic:deploy

Эта команда выполняет следующие действия:

  • выкладывает в ./public/packages/ все зарегистрированные файлы из vendor пакетов
  • обновляет хэш статики, чтобы сбросился кэш браузера (изменяется URL подключаемых стилей и скриптов)

###8. Правила включения/выключения пакетов В процессе работы может возникнуть такая необходимость как точечное отключение или включение используемых пакетов. Например, нам надо отключить пакет "larakit/sf-jquery" в админке. Так как мы делали все роуты админки с префиксом "admin.", то у нас есть сейчас три роута:

  • admin
  • admin.users
  • admin.news
  • admin.pages

Инструкциию для управления подключением пакетов пишем в файле ./app/Http/staticfiles.php:

####8.1 Отключение пакета jQuery только на главной странице админки

\Larakit\StaticFiles\Manager::package('larakit/sf-jquery')
    ->setExclude('admin');

####8.2 Отключение пакета jQuery только на внутренних страницах админки

\Larakit\StaticFiles\Manager::package('larakit/sf-jquery')
    ->setExclude('admin.*');

####8.3 Отключение пакета jQuery во всей админке

\Larakit\StaticFiles\Manager::package('larakit/sf-jquery')
    ->setExclude('admin*');

####8.4 Отключение пакета jQuery во всей админке, кроме страницы управления пользователями

\Larakit\StaticFiles\Manager::package('larakit/sf-jquery')
    ->setExclude('admin*')
    ->setInclude('admin.users');

####8.5 Отключение пакета jQuery на всем сайте, кроме страницы управления пользователями

\Larakit\StaticFiles\Manager::package('larakit/sf-jquery')
    ->setExclude('*')
    ->setInclude('admin.users');

Указанные правила можно менять местами, будет применено правило, наиболее точно описывающее текущий роут, для которого производится попытка автоподключения пакетов статики.

###... ###Profit!