Skip to content

Commit 795ffaf

Browse files
nlemoinenlemoine
authored
feat: Add the ability to disable dependency extraction
Add a `dependencyExtractionEnabled` property to `Script` & `ScriptModule` constructor that will disable automatic dependency extraction if set to `false`
1 parent 9bf2a42 commit 795ffaf

File tree

5 files changed

+231
-25
lines changed

5 files changed

+231
-25
lines changed

‎docs/assets.md‎

Lines changed: 40 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -21,22 +21,23 @@ Each instance requires a `string $handle`, `string $url` and `int $location`.
2121

2222
Following configurations are available:
2323

24-
| property | type | default | `Script` | `ScriptModule` | `Style` | description |
25-
|--------------|----------------|------------------------------------------------------------------------------|----------|----------------|---------|------------------------------------------------------------------------------------------|
26-
| filePath | string | `''` | x | x | x | optional path which can be set to autodiscover the Asset version |
27-
| dependencies | array | `[]` | x | x | x | all defined depending handles |
28-
| location | int | falls back to `Asset::FRONTEND` | x | x | x | depending on location of the `Asset`, it will be enqueued with different hooks |
29-
| version | string | `null` | x | x | x | version of the given asset |
30-
| enqueue | bool/callable | `true` | x | x | x | is the asset only registered or also enqueued |
31-
| data | array/callable | `[]` | x | | x | additional data assigned to the asset via `WP_Script::add_data` or `WP_Style::add_data` |
32-
| filters | callable[] | `[]` | x | | x | an array of `Inpsyde\Assets\OutputFilter` or callable values to manipulate the output |
33-
| handler | string | `ScriptHandler::class`, `StyleHandler::class`, `ScriptModuleHandler::class` | x | x | x | The handler which will be used to register/enqueue the Asset |
34-
| attributes | array | `[]` | x | | x | Allows to set additional attributes to the `script`- or `link`-tag |
35-
| media | string | `'all'` | | | x | type of media for the `Style` |
36-
| localize | array | `[]` | x | | | localized array of data attached to `Script` |
37-
| inFooter | bool | `true` | x | | | defines if the current `Script` is printed in footer |
38-
| inline | array | `[]` | x | | | allows you to add inline scripts to `Script`-class via `['before' => [], 'after' => []]` |
39-
| translation | array | `[]` | x | | | Load translation for `Script`-class via `['path' => string, 'domain' => string]` |
24+
| property | type | default | `Script` | `ScriptModule` | `Style` | description |
25+
|-----------------------------|----------------|------------------------------------------------------------------------------|----------|----------------|---------|------------------------------------------------------------------------------------------|
26+
| filePath | string | `''` | x | x | x | optional path which can be set to autodiscover the Asset version |
27+
| dependencies | array | `[]` | x | x | x | all defined depending handles |
28+
| location | int | falls back to `Asset::FRONTEND` | x | x | x | depending on location of the `Asset`, it will be enqueued with different hooks |
29+
| version | string | `null` | x | x | x | version of the given asset |
30+
| enqueue | bool/callable | `true` | x | x | x | is the asset only registered or also enqueued |
31+
| data | array/callable | `[]` | x | | x | additional data assigned to the asset via `WP_Script::add_data` or `WP_Style::add_data` |
32+
| filters | callable[] | `[]` | x | | x | an array of `Inpsyde\Assets\OutputFilter` or callable values to manipulate the output |
33+
| handler | string | `ScriptHandler::class`, `StyleHandler::class`, `ScriptModuleHandler::class` | x | x | x | The handler which will be used to register/enqueue the Asset |
34+
| attributes | array | `[]` | x | | x | Allows to set additional attributes to the `script`- or `link`-tag |
35+
| media | string | `'all'` | | | x | type of media for the `Style` |
36+
| localize | array | `[]` | x | | | localized array of data attached to `Script` |
37+
| inFooter | bool | `true` | x | | | defines if the current `Script` is printed in footer |
38+
| inline | array | `[]` | x | | | allows you to add inline scripts to `Script`-class via `['before' => [], 'after' => []]` |
39+
| translation | array | `[]` | x | | | Load translation for `Script`-class via `['path' => string, 'domain' => string]` |
40+
| dependencyExtractionEnabled | bool | `true` | x | x | | enable/disable automatic dependency extraction from `.asset.json` or `.asset.php` files |
4041

4142
## Using the public API (methods)
4243

@@ -177,11 +178,10 @@ $style = new Style('foo', 'www.example.com/style.css');
177178
$style->withDependencies('wp-elements');
178179
```
179180

180-
#### Automatic resolving of Script dependencies with Webpack
181+
#### Automatic resolving of dependencies with Webpack
181182

182-
The `Inpsyde\Assets\Script`-class has support for resolving dependencies and version which are generated
183-
by [dependency-extraction-webpack-plugin](https://github.com/WordPress/gutenberg/tree/master/packages/dependency-extraction-webpack-plugin)
184-
.
183+
The `Inpsyde\Assets\Script` and `Inpsyde\Assets\ScriptModule` classes have support for resolving dependencies and version which are generated
184+
by [dependency-extraction-webpack-plugin](https://github.com/WordPress/gutenberg/tree/master/packages/dependency-extraction-webpack-plugin).
185185

186186
This Webpack-Plugin will create an additional `{fileName}.assets.json` or `{fileName}.assets.php`-file which contains an
187187
array of dependencies parsed out of your JavaScript-file and a version string. To use that feature you can use
@@ -214,9 +214,28 @@ $script->dependencies(); // ["foo", "bar", "baz"]
214214
$script->version(); // "1234567"
215215
```
216216

217-
Based on your `Asset::filePath` the `Script` automatically searches in the same folder for `{fileName}.assets.json|php`
217+
Based on your `Asset::filePath` the `Script` and `ScriptModule` automatically search in the same folder for `{fileName}.assets.json|php`
218218
and will load the data.
219219

220+
#### Disabling dependency extraction
221+
222+
If you want to disable the automatic dependency extraction, you can pass `false` as the fourth constructor parameter:
223+
224+
```php
225+
<?php
226+
use Inpsyde\Assets\Script;
227+
use Inpsyde\Assets\ScriptModule;
228+
use Inpsyde\Assets\Asset;
229+
230+
// Disable dependency extraction for Script
231+
$script = new Script('foo', 'www.example.com/script.js', Asset::FRONTEND, false);
232+
233+
// Disable dependency extraction for ScriptModule
234+
$module = new ScriptModule('@my-plugin/main', 'www.example.com/module.js', Asset::FRONTEND, false);
235+
```
236+
237+
This is useful when you want to manage dependencies manually or when the `.asset.json`/`.asset.php` file should be ignored.
238+
220239
:warning: This will not overwrite your existing settings:
221240

222241
**script.assets.php**

‎src/Script.php‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,19 @@ class Script extends BaseAsset implements Asset, DataAwareAsset, FilterAwareAsse
3535
'path' => null,
3636
];
3737

38+
protected bool $dependencyExtractionEnabled = false;
39+
40+
public function __construct(
41+
string $handle,
42+
string $url,
43+
int $location = Asset::FRONTEND | Asset::ACTIVATE,
44+
bool $dependencyExtractionEnabled = true
45+
) {
46+
47+
parent::__construct($handle, $url, $location);
48+
$this->dependencyExtractionEnabled = $dependencyExtractionEnabled;
49+
}
50+
3851
/**
3952
* @return array<string, mixed>
4053
*/
@@ -199,7 +212,7 @@ public function useDependencyExtractionPlugin(): Script
199212
*/
200213
public function version(): ?string
201214
{
202-
$this->resolveDependencyExtractionPlugin();
215+
$this->dependencyExtractionEnabled and $this->resolveDependencyExtractionPlugin();
203216

204217
return parent::version();
205218
}
@@ -209,7 +222,7 @@ public function version(): ?string
209222
*/
210223
public function dependencies(): array
211224
{
212-
$this->resolveDependencyExtractionPlugin();
225+
$this->dependencyExtractionEnabled and $this->resolveDependencyExtractionPlugin();
213226

214227
return parent::dependencies();
215228
}

‎src/ScriptModule.php‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,19 @@ class ScriptModule extends BaseAsset implements Asset
1515
*/
1616
protected array $data = [];
1717

18+
protected bool $dependencyExtractionEnabled = false;
19+
20+
public function __construct(
21+
string $handle,
22+
string $url,
23+
int $location = Asset::FRONTEND | Asset::ACTIVATE,
24+
bool $dependencyExtractionEnabled = true
25+
) {
26+
27+
parent::__construct($handle, $url, $location);
28+
$this->dependencyExtractionEnabled = $dependencyExtractionEnabled;
29+
}
30+
1831
/**
1932
* @return array<string, mixed>
2033
*/
@@ -48,7 +61,7 @@ protected function defaultHandler(): string
4861
*/
4962
public function version(): ?string
5063
{
51-
$this->resolveDependencyExtractionPlugin();
64+
$this->dependencyExtractionEnabled and $this->resolveDependencyExtractionPlugin();
5265

5366
return parent::version();
5467
}
@@ -58,7 +71,7 @@ public function version(): ?string
5871
*/
5972
public function dependencies(): array
6073
{
61-
$this->resolveDependencyExtractionPlugin();
74+
$this->dependencyExtractionEnabled and $this->resolveDependencyExtractionPlugin();
6275

6376
return parent::dependencies();
6477
}

‎tests/phpunit/Unit/Asset/ScriptModuleTest.php‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace Inpsyde\Assets\Tests\Unit\Asset;
6+
7+
use Inpsyde\Assets\Asset;
8+
use Inpsyde\Assets\Handler\ScriptModuleHandler;
9+
use Inpsyde\Assets\ScriptModule;
10+
use Inpsyde\Assets\Tests\Unit\AbstractTestCase;
11+
use org\bovigo\vfs\vfsStream;
12+
13+
class ScriptModuleTest extends AbstractTestCase
14+
{
15+
/**
16+
* @var \org\bovigo\vfs\vfsStreamDirectory
17+
*/
18+
private $root;
19+
20+
public function setUp(): void
21+
{
22+
$this->root = vfsStream::setup('tmp');
23+
parent::setUp();
24+
}
25+
26+
/**
27+
* @test
28+
*/
29+
public function testBasic(): void
30+
{
31+
$scriptModule = new ScriptModule('foo', 'foo.js');
32+
33+
static::assertSame(ScriptModuleHandler::class, $scriptModule->handler());
34+
static::assertSame(Asset::FRONTEND | Asset::ACTIVATE, $scriptModule->location());
35+
}
36+
37+
/**
38+
* @test
39+
*/
40+
public function testWithData(): void
41+
{
42+
$scriptModule = new ScriptModule('handle', 'script.js');
43+
44+
static::assertEmpty($scriptModule->data());
45+
46+
$expectedData = ['foo' => 'bar', 'baz' => 'qux'];
47+
$scriptModule->withData($expectedData);
48+
49+
static::assertSame($expectedData, $scriptModule->data());
50+
}
51+
52+
/**
53+
* @test
54+
*/
55+
public function testDependencyExtractionCanBeDisabled(): void
56+
{
57+
$expectedDependencies = ['foo', 'bar', 'baz'];
58+
$expectedVersion = '1.0';
59+
60+
vfsStream::newFile('script.asset.json')
61+
->withContent(
62+
json_encode(
63+
[
64+
'dependencies' => $expectedDependencies,
65+
'version' => $expectedVersion,
66+
]
67+
)
68+
)
69+
->at($this->root);
70+
71+
$expectedFile = vfsStream::newFile('script.js')->at($this->root);
72+
73+
$testee = new ScriptModule('script', $expectedFile->url(), Asset::FRONTEND, false);
74+
$testee->withFilePath($expectedFile->url());
75+
76+
// Dependencies should not be loaded from the .asset.json file
77+
static::assertEmpty($testee->dependencies());
78+
79+
// Version is still autodiscovered from file modification time, not from .asset.json
80+
// To verify it's not from .asset.json, we check it's not the expected version
81+
static::assertNotEquals($expectedVersion, $testee->version());
82+
}
83+
84+
/**
85+
* @test
86+
*/
87+
public function testDependencyExtractionEnabledByDefault(): void
88+
{
89+
$expectedDependencies = ['foo', 'bar', 'baz'];
90+
91+
vfsStream::newFile('script.asset.json')
92+
->withContent(json_encode(['dependencies' => $expectedDependencies]))
93+
->at($this->root);
94+
95+
$expectedFile = vfsStream::newFile('script.js')->at($this->root);
96+
97+
$testee = new ScriptModule('script', $expectedFile->url());
98+
$testee->withFilePath($expectedFile->url());
99+
100+
// Should load dependencies by default
101+
static::assertEqualsCanonicalizing(
102+
$expectedDependencies,
103+
$testee->dependencies()
104+
);
105+
}
106+
}

‎tests/phpunit/Unit/Asset/ScriptTest.php‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -404,4 +404,59 @@ public function provideVersions(): \Generator
404404
'1.0',
405405
];
406406
}
407+
408+
/**
409+
* @test
410+
*/
411+
public function testDependencyExtractionCanBeDisabled(): void
412+
{
413+
$expectedDependencies = ['foo', 'bar', 'baz'];
414+
$expectedVersion = '1.0';
415+
416+
vfsStream::newFile('script.asset.json')
417+
->withContent(
418+
json_encode(
419+
[
420+
'dependencies' => $expectedDependencies,
421+
'version' => $expectedVersion,
422+
]
423+
)
424+
)
425+
->at($this->root);
426+
427+
$expectedFile = vfsStream::newFile('script.js')->at($this->root);
428+
429+
$testee = new Script('script', $expectedFile->url(), Asset::FRONTEND, false);
430+
$testee->withFilePath($expectedFile->url());
431+
432+
// Dependencies should not be loaded from the .asset.json file
433+
static::assertEmpty($testee->dependencies());
434+
435+
// Version is still autodiscovered from file modification time, not from .asset.json
436+
// To verify it's not from .asset.json, we check it's not the expected version
437+
static::assertNotEquals($expectedVersion, $testee->version());
438+
}
439+
440+
/**
441+
* @test
442+
*/
443+
public function testDependencyExtractionEnabledByDefault(): void
444+
{
445+
$expectedDependencies = ['foo', 'bar', 'baz'];
446+
447+
vfsStream::newFile('script.asset.json')
448+
->withContent(json_encode(['dependencies' => $expectedDependencies]))
449+
->at($this->root);
450+
451+
$expectedFile = vfsStream::newFile('script.js')->at($this->root);
452+
453+
$testee = new Script('script', $expectedFile->url());
454+
$testee->withFilePath($expectedFile->url());
455+
456+
// Should load dependencies by default
457+
static::assertEqualsCanonicalizing(
458+
$expectedDependencies,
459+
$testee->dependencies()
460+
);
461+
}
407462
}

0 commit comments

Comments
 (0)