Asset Bundle Laravel Package

Getting Started

hostnet/asset-bundle is a thin Symfony integration layer for hostnet/asset-lib. It does not replace Webpack Encore, AssetMapper, or Symfony's Asset component; it mainly wires the asset library into the Symfony container and exposes configuration. The package has very low adoption and minimal maintenance activity, so start by confirming compatibility rather than assuming it is a drop-in asset system.

As of release 1.0.7, the bundle requires Symfony 5.4 or newer (Minimum symfony version: 5.4). There is no stated upper bound, so verify Symfony 6.x/7.x support against the actual composer.json constraints before adopting it.

Minimal path:

1. Check composer.json constraints for the bundle and hostnet/asset-lib against the app's PHP/Symfony version. Treat Symfony 5.4 as the floor.
2. Install it:

   composer require hostnet/asset-bundle
   

3. Register the bundle manually if Flex does not do it:

   // config/bundles.php
   return [
       // ...
       Hostnet\Bundle\AssetBundle\HostnetAssetBundle::class => ['all' => true],
   ];
   

4. Read these files first, in this order:
   • vendor/hostnet/asset-bundle/README.md
   • vendor/hostnet/asset-bundle/src/DependencyInjection/Configuration.php
   • vendor/hostnet/asset-bundle/src/DependencyInjection/*Extension.php
   • the relevant services/classes in vendor/hostnet/asset-lib
5. Discover the real config alias and keys:

   bin/console config:dump-reference hostnet_asset
   bin/console debug:container | grep -i asset
   

   If the guessed alias fails, use the extension alias from the bundle's DI extension class.

First practical use case: configure one asset collection or asset definition through the bundle, inject the resulting hostnet/asset-lib service into a controller or small Twig extension, and render it in a base layout. Keep the first change narrow: one CSS/JS entry, one environment, one rendered page. Once that works, expand to environment-specific configuration and cache busting.

Implementation Patterns

Treat the bundle as a configuration adapter, not as the place to put application asset logic. The day-to-day pattern is: define assets in Symfony config, consume hostnet/asset-lib services through dependency injection, and wrap the vendor API behind a small application service.

Common patterns:

• Config-first asset registry. Put asset groups, collections, paths, and environment-specific options in config/packages/hostnet_asset.yaml. Use when@dev and when@prod for differences such as minification, cache directories, or versioning.
• Inject, do not static-call. Inject the relevant asset-lib service into controllers, Twig extensions, or application services. Avoid calling vendor classes statically from templates or helpers.
• Create an application-facing wrapper. Define an interface such as App\Asset\AssetRenderer and implement it using hostnet/asset-lib. This isolates the low-maintenance dependency and makes future replacement with Symfony AssetMapper/Encore easier.
• Twig integration. If the bundle provides a Twig extension, register it and use its functions in the base layout. If not, write a small Twig extension that delegates to the injected asset service. Do not let templates know vendor service IDs.
• Environment-specific rendering. In dev, prefer unminified assets and disabled caches. In prod, enable versioning/caching and fail fast if an asset is missing.
• Cache busting. Use asset-lib's versioning support if available. Otherwise append a version query string from APP_VERSION, a git hash, or a build timestamp in the application wrapper.
• Service aliasing. If the bundle exposes services with vendor IDs, alias them to application interfaces:

  services:
      App\Asset\AssetRenderer:
          alias: hostnet_asset.some_service
  

  Verify the actual service ID with debug:container before relying on it.
• Compiler passes only when needed. Use a compiler pass for tags or collection registration only if the bundle exposes tagged services. Otherwise keep configuration explicit.
• Testing. Use bin/console lint:container and debug:container to catch wiring errors. Add one functional test that renders a layout containing the asset output. Unit-test the application wrapper with a mocked asset-lib service.

Integration tip: inspect the container after enabling the bundle. The most reliable documentation for this package is its DI configuration and the hostnet/asset-lib service definitions.

Gotchas and Tips

• Legacy package. Adoption is very low and maintenance is minimal. Release 1.0.7 is essentially a Symfony version-floor bump, not a feature release. Pin exact versions and plan a fork or replacement before upgrading PHP or Symfony. MIT licensing makes forking possible, but budget maintenance effort.
• Symfony compatibility is the first risk. 1.0.7 raises the minimum to Symfony 5.4, so Symfony 5.0–5.3 is no longer supported. Confirm the upper bound for Symfony 6/7 and PHP 8.x in composer.json. If Composer conflicts appear, do not force-resolve them in a production app without testing the bundle's DI extension.
• The config root is not obvious. Confirm the extension alias from Configuration.php/the DI extension. Use config:dump-reference against that alias, not a guessed name.
• Bundle registration differs by Symfony version. Modern apps use config/bundles.php; older apps use AppKernel. After changing registration or config, run bin/console cache:clear.
• Asset path ambiguity. Asset-lib may resolve paths relative to the project root, public directory, or a configured base path. Confirm with a small debug command or temporary dump of resolved paths. Use %kernel.project_dir% explicitly.
• Cache directories and permissions. Production asset caches may live under var/cache or a configured directory. Ensure the web user can write there and warm the cache during deploy.
• Do not hardcode vendor service IDs in templates. Service IDs are an internal detail and may change across versions. Alias them once in application config.
• Missing assets can fail silently. Add a development check that asserts configured files exist, or make the application wrapper throw a clear exception when resolution fails.
• Debugging checklist:

  bin/console debug:config hostnet_asset
  bin/console debug:container | grep -i hostnet
  bin/console lint:container
  bin/console cache:clear
  

  Then inspect the resolved asset path and rendered HTML in dev.
• Extension points. Prefer decorating asset-lib services, adding a Twig extension, or wrapping the library in an application service. Avoid editing vendor files. A compiler pass is appropriate only for tagged service integration.
• Low adoption means few examples. Rely on the bundle's tests and hostnet/asset-lib source/tests rather than blog posts. If the bundle only exposes a small amount of config, most behavior will be defined by asset-lib, not the bundle.
• Replacement planning. If the app only needs simple versioned CSS/JS, Symfony AssetMapper or Webpack Encore may be a lower-risk long-term choice. Use this bundle only where its existing asset-lib behavior is already required.