Getting Started

Requirements check first. This is a Laravel 4-only package (the illuminate/support constraint will be 4.x). Before anything else, confirm you are actually on L4 — on Laravel 5+ the service provider will fail to autoload or the facade will blow up on App::make. If you are on L5+, stop here and use a maintained option (Mix/Vite, or spatie/laravel-html style helpers).

Install. The package has no meaningful footprint on Packagist, so expect to either add a VCS repository entry or pin a commit rather than trusting a tagged release:

"repositories": [{ "type": "vcs", "url": "https://github.com/lightgear/asset" }],
"require": { "lightgear/asset": "dev-master" }

Then composer update lightgear/asset.

Register the provider in app/config/app.php:

'providers' => array(
    // ...
    'Lightgear\Asset\AssetServiceProvider',
),

'aliases' => array(
    'Asset' => 'Lightgear\Asset\Facades\Asset',
),

Publish the config (L4 syntax, not vendor:publish):

php artisan config:publish lightgear/asset

This drops config into app/config/packages/lightgear/asset/. Read that file first — it is the real documentation: it tells you the container names, default paths, minify/cache toggles, and where compiled output is written.

Where to look next. The repo README is thin, so read src/ in this order: the service provider (what gets bound), the facade (the public surface), then the main manager class. The API is small — usually add(), styles(), scripts(), and a container/collection accessor.

First use case. Register your base assets once in app/start/global.php (or a view composer), then render in your master layout:

// app/start/global.php
Asset::add('jquery', 'js/vendor/jquery.js');
Asset::add('app', 'js/app.js');
Asset::add('app-css', 'css/app.css');

{{-- app/views/layouts/master.blade.php --}}
<head>
    {{ Asset::styles() }}
</head>
<body>
    @yield('content')
    {{ Asset::scripts() }}
</body>

Note that in Laravel 4, {{ }} is unescaped output — that is why this renders markup rather than an HTML-escaped string. If you ever port this to L5+, every one of these calls becomes {!! !!}.

Implementation Patterns

Use named containers to control placement. Most asset managers of this generation expose container/collection grouping, so keep <head> CSS and footer JS in separate buckets rather than one global bag:

Asset::container('footer')->add('app', 'js/app.js');

Register page-specific assets from the child view, not from a section. In Blade, the child view body executes (and captures sections) before the layout is rendered, so a bare Asset::add() at the top of a page view is registered in time for the layout's Asset::scripts() call. Putting it inside @section('scripts') is too late — that section is only echoed where the layout yields it.

{{-- app/views/pages/dashboard.blade.php --}}
@extends('layouts.master')
<?php Asset::add('charts', 'js/vendor/chart.js'); ?>

Order matters — treat it as a dependency list. Register jQuery before plugins, bootstrap before your overrides. If the manager supports a "requires" argument, use it; otherwise rely on insertion order and never register from two places for the same key, because the last add() for a name usually wins (or silently duplicates — verify against the source before assuming).

Compose globally via a view composer rather than app/start/global.php if you want testability:

View::composer('layouts.master', function ($view) {
    Asset::add('app-css', 'css/app.css');
});

Environment-aware output. Skip concatenation/minification locally so stack traces and line numbers survive:

if (App::environment('local')) {
    // config override: disable minify/cache for this request
}

Cache-busting. The package's compiled file will be served with a stable name, so append a version query string derived from config or filemtime and bump it on deploy — otherwise browsers will hold stale JS for hours.

Package/theme integration. If you ship your own L4 package with views, register its assets in its service provider using the same facade so host apps get them for free, and namespace the keys (mytheme-app) to avoid collisions.

Inline snippets and conditional comments. IE conditional shivs (<!--[if lt IE 9]>) generally require a dedicated inline/raw container or plain markup in the layout. Don't try to force them through the normal CSS/JS pipeline — you'll get escaped or concatenated output that browsers ignore.

Gotchas and Tips

Abandoned stack. Laravel 4 is EOL and this package has essentially no community. There will be no Stack Overflow answers; the source is the documentation. Budget time to read it rather than searching.
Console requests. Registering assets in app/start/global.php runs for artisan invocations too. Guard with if (!App::runningInConsole()) if the manager touches the filesystem or triggers compilation.
Escaping surprises. L4 {{ }} is raw; {{{ }}} escapes. If output looks like literal <link ...> text on the page, you've used the wrong brace count — and the reverse bug appears if you copy L5 snippets from the web.
Relative url() in CSS breaks on concatenation. When multiple stylesheets are combined into one file in a different directory, url(../img/foo.png) resolves against the new location. Either keep compiled output at the same depth, rewrite paths, or switch to absolute URLs.
Already-minified vendor files. Re-minifying jQuery or a pre-built bundle is a classic source of "works locally, breaks in production" bugs. Exclude vendor files from the minifier via config or by container.
Writable output directory. If compilation/caching is enabled, the target directory under public/ must be writable by the web user. Silent failures here manifest as an empty <link> or a 404 on a file that "should" exist.
Stale compiled cache after deploy. Clear the compiled asset directory (or bump the version string) as part of your deploy script. This is the single most common "why is old code still running" issue with this class of package.
Path semantics — public/ root, not app/. Paths are relative to the public directory. Leading slashes, CDN hosts, and // protocol-relative URLs are not always normalised; if you pass an absolute URL, check whether the manager prepends asset() or a base path to it.
Facade alias collisions. Asset is a popular alias; if another package also registers it, the last one in app/config/app.php wins. Alias it as LightgearAsset if you hit weird behaviour.
Debug by dumping state, not by inspecting the DOM. The browser inspector shows injected/compiled results; dump the registry instead (dd(Asset::scripts()) or the equivalent getter) to see what was actually registered and in what order.
Extension points. The manager is almost certainly bound as a singleton in the provider — you can rebind it in app/start/global.php or a custom provider to swap in your own subclass if you need different minification or path resolution. That's the cleanest escape hatch when the package does 90% of what you want and fights you on the last 10%.
Don't make it the critical path. Keep above-the-fold CSS inline in the layout rather than relying on this package's pipeline; it gives you one dependency fewer between the user and first paint, and it survives the eventual migration off the package.

Asset Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips