Пакети ресурсів

Компонент Ресурс управляє ресурсами через пакети. Пакет групує всі ресурси з загальними влластивостями: стратегією версіонування, базовим шляхом, хостами CDN, і т.д. В наступному базовому прикладі, пакет створюється для керування ресурсом без версіонування:

1
2
3
4
5
6
7
8
9
10
11
12

use Symfony\Component\Asset\Package;
use Symfony\Component\Asset\VersionStrategy\EmptyVersionStrategy;

$package = new Package(new EmptyVersionStrategy());

// Абсолютний шлях
echo $package->getUrl('/image.png');
// результат: /image.png

// Відносний шлях
echo $package->getUrl('image.png');
// результат: image.png

Пакети реалізують PackageInterface, який визначає наступні два методи:

getVersion()

Повертає версію ресурсу для ресурсу.

getUrl()

Повертає абсолютний або публічний відносний кореневий шлях.

З пакетом ви можете:

A) версіонувати ресурси ; B) встановлювати загальний базовий шлях (наприклад, /css) для пакетів; C) конфігурувати CDN для ресурсів

Версіоновані ресурси

Однією з основних функцій компонента Ресурс є можливість керувати версіонуванням ресурсів додатку. Версії ресурсів часто використовуються для контролювання того, як ці ресурси кешуються.

Замість того, щоб покладатися на простий механізм версії, компонент Ресурс дозволяє вам визначати просунуті стратегії версіонування через PHP-класи. Дві вбудовані стратегії: EmptyVersionStrategy, яка не додає версії у ресурс, та StaticVersionStrategy, яка дозволяє вам встановити версію за допомогою рядку формату.

У цьому прикладі, StaticVersionStrategy використовується щоб прикріпити суфікс v1 до будь-якого шляху ресурсу:

1
2
3
4
5
6
7
8
9
10
11
12

use Symfony\Component\Asset\Package;
use Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy;

$package = new Package(new StaticVersionStrategy('v1'));

// Абсолютний шлях
echo $package->getUrl('/image.png');
// результат: /image.png?v1

// Відносний шлях:
echo $package->getUrl('image.png');
// результат: image.png?v1

У випадку, якщо ви хочете змінити формат версії, передайте рядок формату, сумісного з sprintf в якості другого аргументу конструктора StaticVersionStrategy:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// розміщує слово 'version' перед значенням версії
$package = new Package(new StaticVersionStrategy('v1', '%s?version=%s'));

echo $package->getUrl('/image.png');
// результат: /image.png?version=v1

// розміщує версію ресурсу перед його шляхом
$package = new Package(new StaticVersionStrategy('v1', '%2$s/%1$s'));

echo $package->getUrl('/image.png');
// результат: /v1/image.png

echo $package->getUrl('image.png');
// результат: v1/image.png

1
2
3
4
5
6

// rev-manifest.json
{
    "css/app.css": "build/css/app.b916426ea1d10021f3f17ce8031f93c2.css",
    "js/app.js": "build/js/app.13630905267b809161e71d0f8a0c017b.js",
    "...": "..."
}

1
2
3
4
5
6
7

use Symfony\Component\Asset\Package;
use Symfony\Component\Asset\VersionStrategy\JsonManifestVersionStrategy;

$package = new Package(new JsonManifestVersionStrategy(__DIR__'./rev-manifest.json'));

echo $package->getUrl('css/app.css');
// result: build/css/app.b916426ea1d10021f3f17ce8031f93c2.css

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

use Symfony\Component\Asset\VersionStrategy\VersionStrategyInterface;

class DateVersionStrategy implements VersionStrategyInterface
{
    private $version;

    public function __construct()
    {
        $this->version = date('Ymd');
    }

    public function getVersion($path)
    {
        return $this->version;
    }

    public function applyVersion($path)
    {
        return sprintf('%s?v=%s', $path, $this->getVersion($path));
    }
}

Згруповані ресурси

Часто багато ресурсів живуть за загальним шляхом (наприклад, /static/images). Якщо це ваш випадок, змініть клас за замовчуванням Package на PathPackage, щоб уникнути повторення цього шшляху знову і знову:

1
2
3
4
5
6
7
8
9
10
11

use Symfony\Component\Asset\PathPackage;
// ...

$pathPackage = new PathPackage('/static/images', new StaticVersionStrategy('v1'));

echo $pathPackage->getUrl('logo.png');
// результат: /static/images/logo.png?v1

// Базовий шлях ігнорується при використанні абсолютних шляхів
echo $pathPackage->getUrl('/logo.png');
// результат: /logo.png?v1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

use Symfony\Component\Asset\PathPackage;
use Symfony\Component\Asset\Context\RequestStackContext;
// ...

$pathPackage = new PathPackage(
    '/static/images',
    new StaticVersionStrategy('v1'),
    new RequestStackContext($requestStack)
);

echo $pathPackage->getUrl('logo.png');
// результат: /somewhere/static/images/logo.png?v1

// Як "base path", так і "base url" ігнорується при використанні абсолютного шляху для ресурсу
echo $pathPackage->getUrl('/logo.png');
// результат: /logo.png?v1

Абсолютні ресурси та CDN

Додатки, які розміщують свої ресурси на різних доменах та CDN (Мережі доправлення контенту) мають використовувати клас UrlPackage, щоб згенерувати абсолютні URL для своїх ресурсів:

1
2
3
4
5
6
7
8
9
10

use Symfony\Component\Asset\UrlPackage;
// ...

$urlPackage = new UrlPackage(
    'http://static.example.com/images/',
    new StaticVersionStrategy('v1')
);

echo $urlPackage->getUrl('/logo.png');
// результат: http://static.example.com/images/logo.png?v1

Ви також можете пердати URL схем-агностиків:

1
2
3
4
5
6
7
8
9
10

use Symfony\Component\Asset\UrlPackage;
// ...

$urlPackage = new UrlPackage(
    '//static.example.com/images/',
    new StaticVersionStrategy('v1')
);

echo $urlPackage->getUrl('/logo.png');
// результат: //static.example.com/images/logo.png?v1

Це корисно, так як ресурси будуть автоматично запитані через HTTPS, якщо відвідувач переглядає ваш сайт на https. Просто перконайтеся в тому, що ваш CDN хост підтримує https.

У випадку, якщо ви надаєте ресурси більше, ніж з одного домену, щоб покращити ефективність додатку, передайте масив URL в якості першого аргументу конструктора UrlPackage:

1
2
3
4
5
6
7
8
9
10
11
12
13

use Symfony\Component\Asset\UrlPackage;
// ...

$urls = array(
    '//static1.example.com/images/',
    '//static2.example.com/images/',
);
$urlPackage = new UrlPackage($urls, new StaticVersionStrategy('v1'));

echo $urlPackage->getUrl('/logo.png');
// результат: http://static1.example.com/images/logo.png?v1
echo $urlPackage->getUrl('/icon.png');
// результат: http://static2.example.com/images/icon.png?v1

Для кожного ресурсу один з URL має бути використано рандомно. Але визначення детерміновано, що означає, що кожний ресурс завжди буде подано одним і тим самим доменом. Ця поведінка спрощує управління HTTP-кешем.

1
2
3
4
5
6
7
8
9
10
11
12
13

use Symfony\Component\Asset\UrlPackage;
use Symfony\Component\Asset\Context\RequestStackContext;
// ...

$package = new UrlPackage(
    array('http://example.com/', 'https://example.com/'),
    new StaticVersionStrategy('v1'),
    new RequestStackContext($requestStack)
);

echo $package->getUrl('/logo.png');
// припускаючи, що RequestStackContext повідомляє, що ми на захищеному хості
// результат: https://example.com/logo.png?v1

Іменовані пакети

Додатки, які управляють багатьма різними ресурсами, можуть захотіти згрупувати їх в пакети з однаковою стратегією версіонування та базовим шляхом. Копомнент Ресурс включає в себе клас Packages, щоб спростити управління декількома пакетами.

У наступному прикладі всі пакети використовують одну стратегію версіонування, але вони всі мають різні базові шляхи:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

use Symfony\Component\Asset\Package;
use Symfony\Component\Asset\PathPackage;
use Symfony\Component\Asset\UrlPackage;
use Symfony\Component\Asset\Packages;
// ...

$versionStrategy = new StaticVersionStrategy('v1');

$defaultPackage = new Package($versionStrategy);

$namedPackages = array(
    'img' => new UrlPackage('http://img.example.com/', $versionStrategy),
    'doc' => new PathPackage('/somewhere/deep/for/documents', $versionStrategy),
);

$packages = new Packages($defaultPackage, $namedPackages)

Клас Packages дозволяє визначатим пакет за замовчуванням, який буде застосовано до ресурсів, які не визначають імʼя пакету для використання. Крім того, цей додаток визначає пакет під іменем img для подачі зображень з зовнішнього домену, та пакет doc, щоб уникнути поовторення довгих шляхів при посиланні на документ всередині шаблону:

1
2
3
4
5
6
7
8

echo $packages->getUrl('/main.css');
// результат: /main.css?v1

echo $packages->getUrl('/logo.png', 'img');
// результат: http://img.example.com/logo.png?v1

echo $packages->getUrl('resume.pdf', 'doc');
// результат: /somewhere/deep/for/documents/resume.pdf?v1