Add support for prioritized asset

[nlemoine]

Please check if the PR fulfills these requirements

• The commit message follows our guidelines
• Tests for the changes have been added (for bug fixes/features)
• Docs have been added/updated (for bug fixes/features)

What kind of change does this PR introduce? (Bug fix, feature, docs update, ...)

Feature

What is the current behavior? (You can also link to an open issue here)

Preambule

This feature is not to be confused with:

• dependency management: it's not a matter of an asset that depend of another
• browser asset processing order: I'm not referring to async, defer, etc.

This must be considered all asset location/attributes equal.

Problem

WordPress provides no straightforward (besides hook priority) way to control asset output order. Further more, this library abstract enqueue related actions where hook priority isn't reachable.

When multiple scripts or styles are enqueued, their order in the HTML depends on registration order, which can be hard to manage when scattered across plugins, themes, etc.

Example:

// Plugin A
add_action(AssetManager::ACTION_SETUP, function(AssetManager $assetManager) {
    $assetManager->register($someScript);
});

// Plugin B 
add_action(AssetManager::ACTION_SETUP, function(AssetManager $assetManager) {
    $assetManager->register($someOtherScript);
});

// Theme
add_action(AssetManager::ACTION_SETUP, function(AssetManager $assetManager) {
    $assetManager->register($themeScript);
});

Although adding different priorities to AssetManager::ACTION_SETUP will work, it's not very convenient and will eventually fail or become unmaintainable when registering multiple assets with different priorities within the same hook.

Having priority defined per asset feels way more natural and maintainable approach.

What is the new behavior (if this is a feature change)?

This PR adds a priority property to assets (lower = earlier, WP style). The AssetCollection now sorts assets by priority before returning them, ensuring predictable output order regardless of registration timing.

Does this PR introduce a breaking change? (What changes might users need to make in their application due to this PR?)

No. I created a PrioritizedAsset interface to avoid changing the Asset interface. So this feature is completely backward compatible.

Other information

You can take a look at Capo.js for ideal head order as a reason for this feature.

[widoz]

Hi @nlemoine

I get your concerns and the implementation is not so complex in terms of maintanance but I do have some problems to the fact that the Priority implementation reach the BaseAssets in relation to the new ScriptModule.

Another concerns is the false assumption that scripts would load in that particular order due to the async and defer attributes, but also, some scripts requires other scripts and the dependencies will change place in the head. We also have to consider the footer case imo.

The order in case of elements of the same priority isn't guarantee in php version lower than 8.0.0.

In particular, related to the ScriptModule they cannot have a priority because they might not rendered like normal scripts as dependencies are moved into the importmap.

I'm not against the changes but I think make sense to document the fact that the order cannot be guaranteed due to the aforementioned characteristics of browsers, php and WordPress.

Other than that, if the changes are fine for @Chrico are also fine for me.

[nlemoine]

Thank you @widoz for your thorough review!

I hear your concerns and I thought I anticipated most of them with the "preamble" in my PR comment but I realize it wasn't crystal clear, sorry about that. Let me address each point more clearly.

---

Another concerns is the false assumption that scripts would load in that particular order due to the async and defer attributes

To clarify: this feature controls HTML output order (the order <style> and <script> tags appear in the DOM), not browser loading/execution order.

These are distinct concepts. A developer may want critical CSS to appear before other styles in the markup, or need specific tag ordering for non-deferred scripts. That's a valid use case independent of how browsers handle async/defer.

However, I recognize the naming can be confusing and lead to misunderstanding. Would renaming the method/prop help clarifying the intent?

• renderPriority/withRenderPriority?
• outputOrder/withOutputOrder?
• printOrder/withPrintOrder?

but also, some scripts requires other scripts and the dependencies will change place in the head.

This is true-WordPress may reorder scripts based on registered dependencies. However, that's a WordPress-level concern that happens after registration. This feature controls what we can control: the order assets are registered via wp_enqueue_*.

For assets without cross-dependencies (or with dependencies already satisfied), registration order directly affects output order.

We also have to consider the footer case imo.

The current implementation handles this correctly. In AssetManager::loopCurrentHookAssets(), assets are filtered by location (header vs footer or any other location) before processing. The priority sorting in AssetCollection::all() applies within each location context—header assets are sorted among themselves, footer assets among themselves.

The order in case of elements of the same priority isn't guarantee in php version lower than 8.0.0.

PHP 7.x reached EOL in November 2022. That said, if the library still supports PHP 7.x, we can make the sort deterministic by adding a tiebreaker:

return $priorityA <=> $priorityB
    ?: $assetA->handle() <=> $assetB->handle();

This ensures assets with equal priority are sorted alphabetically by handle—predictable across all PHP versions.

In particular, related to the ScriptModule they cannot have a priority because they might not rendered like normal scripts as dependencies are moved into the importmap.

Script modules are subject to the same WordPress-level reordering as dependencies. But if this is a concern, we could limit the PrioritizedAsset interface to Script and Style only.

I'll try to come with some real use cases as soon as I can. It's always a better starting point to discuss implementation details.

Let me know what you think, I'll be happy to refactor it according to your preferences.