Add importmap to AssetManager and AssetBundle #173

Gerych1984 · 2026-01-20T15:32:59Z

Q	A
Is bugfix?	❌
New feature?	✔️
Breaks BC?	❌
Fixed issues	comma-separated list of tickets # fixed by the PR, if any

codecov · 2026-01-20T15:34:47Z

Codecov Report

❌ Patch coverage is 98.71795% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 98.45%. Comparing base (9525966) to head (e2fa4b1).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
src/Importmap.php	95.23%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master     #173      +/-   ##
============================================
+ Coverage     98.42%   98.45%   +0.03%     
- Complexity      263      289      +26     
============================================
  Files            10       11       +1     
  Lines           634      711      +77     
============================================
+ Hits            624      700      +76     
- Misses           10       11       +1

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

samdark

Overall it looks like a very good feature, but you need to address the documentation and also mention the feature in the readme and change log.

src/AssetRegistrar.php

src/AssetManager.php

src/AssetRegistrar.php

samdark · 2026-01-22T20:52:48Z

By docs I've meant both https://github.com/yiisoft/assets/tree/master/docs/guide/en and phpdoc.

Gerych1984 · 2026-01-23T12:35:39Z

By docs I've meant both https://github.com/yiisoft/assets/tree/master/docs/guide/en and phpdoc.

Done

samdark

Is it a good idea to use it in yiisoft/app layout by default? If so, please create an issue there.

docs/guide/en/asset-bundles.md

src/AssetManager.php

src/AssetRegistrar.php

vjik

What about scopes?

https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap#scoped_module_specifier_maps

src/AssetBundle.php

Co-authored-by: Sergei Predvoditelev <sergei@predvoditelev.ru>

src/AssetBundle.php

src/AssetManager.php

src/Importmap.php

samdark · 2026-02-03T16:25:30Z

src/AssetManager.php

    }

+    /**
+     * @return Importmap instance


Suggested change

* @return Importmap instance

* @return Importmap Current import map.

Copilot

Pull request overview

Adds first-class importmap support to the asset system, allowing asset bundles to define ESM module mappings that can be collected and rendered as an HTML <script type="importmap">…</script> payload.

Changes:

Introduces Importmap and exposes it via AssetManager::getImportmap() / AssetRegistrar::getImports().
Adds AssetBundle::$imports and registration/validation logic in AssetRegistrar.
Adds PHPUnit coverage via new test cases + invalid-config stubs and updates user guide docs.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
src/Importmap.php	New `Importmap` value object implementing `JsonSerializable`.
src/AssetRegistrar.php	Collects bundle `imports` into `Importmap` and validates configuration.
src/AssetManager.php	Exposes collected importmap via `getImportmap()`.
src/AssetBundle.php	Adds new `$imports` property with documentation/examples.
src/AssetLoader.php	Docblock import cleanup (`WebView::…` reference).
tests/AssetManagerTest.php	Adds importmap and invalid-import configuration tests.
tests/stubs/ImportmapAsset.php	Stub bundle used to test customized imports.
tests/stubs/InvalidConfig/*.php	New stubs for invalid import configurations.
docs/guide/en/asset-bundles.md	Documents `$imports` and importmap usage.
docs/guide/pt-BR/asset-bundles.md	Documents `$imports` and importmap usage (pt-BR).
CHANGELOG.md	Records the new feature entry.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-03T16:35:40Z

src/AssetRegistrar.php

+    ) {
+        $this->imports = new Importmap();
+    }



AssetRegistrar is cloned in AssetManager::withConverter() / withLoader(). Since $imports is an object, the shallow clone will cause multiple AssetManager instances to share the same Importmap state, breaking immutability (registering bundles on one manager mutates the other’s importmap). Consider implementing __clone() to deep-clone/reset $imports, or explicitly cloning $imports inside withConverter() / withLoader().

Suggested change

public function __clone(): void

{

$this->imports = clone $this->imports;

}

Copilot · 2026-02-03T16:35:40Z

src/AssetRegistrar.php

+            $module = array_key_first($import);
+            $scopes = $import['scopes'] ?? null;
+
+            match (true) {
+                is_string($module) => $integrity = $import[$module],
+                is_int($module) => $module = $import[$module],
+                default => throw new InvalidConfigException('Module should be a not empty array.'),
+            };
+


array_key_first($import) makes parsing order-dependent. If a user defines the array with 'scopes' first (e.g. ['scopes' => [...], 'module.js' => 'hash']), it will be treated as the module key and produce the wrong error/behavior. Consider explicitly skipping the 'scopes' entry and selecting the first non-'scopes' key/value as the module definition.

Suggested change

$module = array_key_first($import);

$scopes = $import['scopes'] ?? null;

match (true) {

is_string($module) => $integrity = $import[$module],

is_int($module) => $module = $import[$module],

default => throw new InvalidConfigException('Module should be a not empty array.'),

};

$scopes = $import['scopes'] ?? null;

$module = null;

foreach ($import as $k => $value) {

if ($k === 'scopes') {

continue;

}

if (is_string($k)) {

$module = $k;

$integrity = $value;

} elseif (is_int($k)) {

$module = $value;

}

break;

}

if ($module === null) {

throw new InvalidConfigException('Module should be a not empty array.');

}

Copilot · 2026-02-03T16:35:40Z

src/AssetRegistrar.php

+        if (is_int($key)) {
+            $key = $module;
+        }
+


$key can be an empty string when provided as an associative array key in AssetBundle::$imports. Currently it will be passed through to Importmap::addImport() without validation, producing an invalid importmap entry. Consider validating that $key is a non-empty string (and throwing InvalidConfigException otherwise) before calling addImport().

Suggested change

if (!is_string($key)) {

throw new InvalidConfigException(

sprintf(

'Import key should be string. Got %s.',

get_debug_type($key),

),

);

}

if ($key === '') {

throw new InvalidConfigException('Import key should be a not empty string.');

}

Copilot · 2026-02-03T16:35:41Z

src/AssetRegistrar.php

+        if ($integrity) {
+
+            if (!is_string($integrity)) {
+                throw new InvalidConfigException(
+                    sprintf(
+                        'Integrity should be string. Got %s.',
+                        get_debug_type($integrity),
+                    ),
+                );
+            }
+
+            $this->imports->addIntegrity($url, $integrity);
+        }


The integrity check uses if ($integrity) which silently ignores empty-string integrity values. Since other config validations reject empty strings (e.g. CSS/JS URLs), consider using an explicit null check ($integrity !== null) and separately validating non-empty string integrity, so misconfiguration doesn't get skipped.

Copilot · 2026-02-03T16:35:41Z

src/AssetRegistrar.php

+        if ($scopes) {
+
+            if (!is_array($scopes)) {
+                throw new InvalidConfigException(
+                    sprintf(
+                        'Scopes should be array. Got %s.',
+                        get_debug_type($scopes),
+                    ),
+                );
+            }


The scopes check uses if ($scopes) which skips validation when scopes is provided as an empty array. If empty scopes are considered invalid, this should throw; if they are valid, consider using an explicit null check ($scopes !== null) for clearer intent and consistent validation behavior.

Copilot · 2026-02-03T16:35:42Z

docs/guide/pt-BR/asset-bundles.md

 Neste exemplo, os caminhos para os arquivos `img/image.png` e `js/script.js` serão exportados,
 mas o caminho para o arquivo `css/style.css` não será exportado.
+```
+


The export example code block is closed too late: the explanatory text lines end up inside the ```php block (the closing fence appears after the prose). Close the code fence immediately after the AppAsset class example and keep the prose outside the code block.

Copilot · 2026-02-03T16:35:42Z

docs/guide/pt-BR/asset-bundles.md

 mas o caminho para o arquivo `css/style.css` não será exportado.
+```
+
+### Pacote de registo com importmap


In pt-BR docs, the section title uses "registo"; for Brazilian Portuguese it should be "registro".

Suggested change

### Pacote de registo com importmap

### Pacote de registro com importmap

Copilot · 2026-02-03T16:35:42Z

docs/guide/pt-BR/asset-bundles.md

+Em algum lugar no topo do layout você deve usar o seguinte:
+
+```php
+$impormap = Script::tag()


The example variable $impormap appears to be a typo; it should likely be $importmap for clarity/consistency with the feature name.

Suggested change

$impormap = Script::tag()

$importmap = Script::tag()

Copilot · 2026-02-03T16:35:42Z

tests/AssetManagerTest.php

+     * @param array|string|null $import
+     * @param array $imports
+     * @param string|int $key
+     * @return void
+     */
+    public function testImportmap(array|string $import, array $imports = [], string|int $key = 0): void
+    {


Docblock says $import can be array|string|null, but the method signature is array|string (no null). Please align the docblock with the actual accepted types to avoid misleading users/static analysis.

Copilot · 2026-02-03T16:35:43Z

CHANGELOG.md

 ## 5.1.3 under development

 - Enh #172: Explicitly import classes and constants in "use" section (@mspirkov)
+- New #173: Add `AssetManager::getImportmap()`, `AssetRegistrar::getImports()` methods and `AssetBundle::imports` property (@Gerych1984) 


Trailing whitespace at end of the changelog entry line (after the closing parenthesis). Please remove it to keep markdown diffs clean.

Suggested change

- New #173: Add `AssetManager::getImportmap()`, `AssetRegistrar::getImports()` methods and `AssetBundle::imports` property (@Gerych1984)

- New #173: Add `AssetManager::getImportmap()`, `AssetRegistrar::getImports()` methods and `AssetBundle::imports` property (@Gerych1984)

importmap

6cc9456

Gerych1984 force-pushed the importmap branch from 6a09883 to d3ed914 Compare January 20, 2026 17:01

importmap

7dc4bcf

Gerych1984 force-pushed the importmap branch from 0994f9a to 7dc4bcf Compare January 20, 2026 17:07

Gerych1984 and others added 8 commits January 20, 2026 17:08

Apply PHP CS Fixer and Rector changes (CI)

e1dc87b

Resolve conflicts

368c838

Merge branch 'importmap' of github.com:Gerych1984/assets into importmap

cab9c77

Resolve conflicts

3eab77c

Resolve conflicts

bca72cf

Apply PHP CS Fixer and Rector changes (CI)

05f5bea

Resolve conflicts

a3d3a63

Merge branch 'importmap' of github.com:Gerych1984/assets into importmap

428d0fe

Gerych1984 marked this pull request as ready for review January 20, 2026 20:03

samdark requested changes Jan 20, 2026

View reviewed changes

src/AssetRegistrar.php Outdated Show resolved Hide resolved

src/AssetManager.php Outdated Show resolved Hide resolved

samdark added the type:feature New feature label Jan 20, 2026

Gerych1984 added 3 commits January 21, 2026 10:19

Add documentation

5dbb793

Resolve conflicts

b2e5705

Resolve conflicts

b363ce3

samdark requested changes Jan 22, 2026

View reviewed changes

src/AssetManager.php Outdated Show resolved Hide resolved

src/AssetRegistrar.php Outdated Show resolved Hide resolved

Add documentation

87d69e9

samdark requested changes Jan 24, 2026

View reviewed changes

Gerych1984 and others added 2 commits January 27, 2026 13:04

Fix documentation

ef34d11

Apply PHP CS Fixer and Rector changes (CI)

f7f3f61

vjik reviewed Jan 27, 2026

View reviewed changes

src/AssetBundle.php Show resolved Hide resolved

samdark and others added 3 commits January 28, 2026 13:42

Update src/AssetBundle.php

63bc703

Co-authored-by: Sergei Predvoditelev <sergei@predvoditelev.ru>

Resolve converstion

cb4eeb6

Resolve conflicts

8a2aa41

Apply PHP CS Fixer and Rector changes (CI)

f3986d8

Gerych1984 marked this pull request as draft February 2, 2026 11:00

samdark and others added 3 commits February 2, 2026 14:01

Merge branch 'master' into importmap

2928278

Resolve conflicts

ff3d600

Apply PHP CS Fixer and Rector changes (CI)

6685f33

Gerych1984 marked this pull request as ready for review February 2, 2026 12:20

samdark requested changes Feb 3, 2026

View reviewed changes

Gerych1984 added 2 commits February 3, 2026 15:25

Resolve conversations

3bce3d8

Merge branch 'importmap' of github.com:Gerych1984/assets into importmap

e2fa4b1

samdark approved these changes Feb 3, 2026

View reviewed changes

samdark requested a review from Copilot February 3, 2026 16:26

Copilot started reviewing on behalf of samdark February 3, 2026 16:27 View session

Copilot AI reviewed Feb 3, 2026

View reviewed changes

	* @return Importmap instance
	* @return Importmap Current import map.

+    public function __clone(): void
+    {
+        $this->imports = clone $this->imports;
+    }

-            $module = array_key_first($import);
-            $scopes = $import['scopes'] ?? null;
-            match (true) {
-                is_string($module) => $integrity = $import[$module],
-                is_int($module) => $module = $import[$module],
-                default => throw new InvalidConfigException('Module should be a not empty array.'),
-            };
+            $scopes = $import['scopes'] ?? null;
+            $module = null;
+            foreach ($import as $k => $value) {
+                if ($k === 'scopes') {
+                    continue;
+                }
+                if (is_string($k)) {
+                    $module = $k;
+                    $integrity = $value;
+                } elseif (is_int($k)) {
+                    $module = $value;
+                }
+                break;
+            }
+            if ($module === null) {
+                throw new InvalidConfigException('Module should be a not empty array.');
+            }

+        if (!is_string($key)) {
+            throw new InvalidConfigException(
+                sprintf(
+                    'Import key should be string. Got %s.',
+                    get_debug_type($key),
+                ),
+            );
+        }
+        if ($key === '') {
+            throw new InvalidConfigException('Import key should be a not empty string.');
+        }

	### Pacote de registo com importmap
	### Pacote de registro com importmap

	- New #173: Add `AssetManager::getImportmap()`, `AssetRegistrar::getImports()` methods and `AssetBundle::imports` property (@Gerych1984)
	- New #173: Add `AssetManager::getImportmap()`, `AssetRegistrar::getImports()` methods and `AssetBundle::imports` property (@Gerych1984)

Uh oh!

Add importmap to AssetManager and AssetBundle #173

Are you sure you want to change the base?

Add importmap to AssetManager and AssetBundle #173

Uh oh!

Conversation

Gerych1984 commented Jan 20, 2026

Uh oh!

codecov bot commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

samdark left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

samdark commented Jan 22, 2026

Uh oh!

Gerych1984 commented Jan 23, 2026

Uh oh!

samdark left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vjik left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

samdark Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

codecov bot commented Jan 20, 2026 •

edited

Loading