Asset Contracts

This page summarizes the behavior you can rely on when integrating Asset.

Supported asset types

The package supports two built-in asset types:

  • Asset::CSS
  • Asset::JS

The rendering helpers map those to string keys:

  • css
  • js

Path resolution contract

Asset::url() and AssetManager::url() behave the same way:

  • if the path has a host, it is returned unchanged
  • otherwise the path is prefixed with base_url() . '/assets/'

This package does not normalize slashes for you. Pass paths that already match your public assets directory structure.

Registration contract

You can register assets individually or in batches.

asset()->registerAsset($asset);
asset()->register([$asset1, $asset2]);

When an asset has a name, that name must be unique across the manager store.

Registering another named asset with the same name throws an AssetException.

Unnamed assets are allowed and can be repeated.

Ordering contract

Each asset carries a position integer.

  • -1 means no explicit position
  • any other integer reserves an exact slot inside its own type group

CSS and JavaScript are ordered independently.

When rendering:

  • explicitly positioned assets are placed first into their requested slots
  • if two assets of the same type claim the same position, registration succeeds but rendering throws an AssetException
  • unpositioned assets are assigned to the next free slot starting from 0
  • final output is sorted by slot number in ascending order

Rendering contract

assets('css') and assets('js') echo output directly.

They do not return strings.

Rendered tags include a trailing newline after each asset.

Template behavior differs slightly by type:

  • CSS renders <link rel="stylesheet" type="text/css" href="...">
  • JavaScript renders <script src="..." ...></script>

JavaScript attributes are joined with spaces and inserted into the tag.

CSS attributes passed to Asset are not rendered.

Shared-instance contract

asset() returns a DI-backed shared AssetManager instance.

That means registrations, lookups, and flushes all operate on the same manager instance inside the current process.

Failure contract

Expect AssetException for:

  • duplicate asset names
  • duplicate render positions within the same asset type

Expect a PHP error if assets() is called with an unsupported string key, because the helper indexes the built-in type map directly.