README

AssetFlow for Laravel is a comprehensive package for managing UI framework assets with support for multiple adapters, caching, minification, and advanced production optimization features. It provides a clean, extensible architecture that allows Laravel developers to easily switch between different UI frameworks while maintaining consistent asset management practices across their applications.

This package is a Laravel port of the popular AssetFlow library originally created for CodeIgniter 4. It includes all the same features adapted for Laravel's ecosystem, including support for Laravel's caching system, facades, Blade directives, and service providers.

AssetFlow for Laravel was authored by Kazashim Kuzasuwat, a software developer passionate about creating clean, maintainable code solutions for common web development challenges. For questions, suggestions, or contributions, please contact the author at kazashimkuzasuwat@gmail.com.

1. Installation

Prerequisites

Before installing AssetFlow for Laravel, ensure your development environment meets the following requirements. Laravel 10.0 or higher is required, as the package leverages modern features of the framework including the service container, configuration system, and Blade templating engine. PHP 8.1 or higher is recommended for optimal performance, though the package maintains compatibility with PHP 8.0 for projects that have not yet upgraded.

Your project should have Composer installed for dependency management, as AssetFlow follows modern PHP packaging practices. The package requires the illuminate/support, illuminate/cache, illuminate/config, and illuminate/view packages, which are automatically installed as dependencies when you add AssetFlow to your project through Composer.

Installing via Composer

The recommended method for installing AssetFlow for Laravel is through Composer, which handles autoloading and dependency management automatically. Open your terminal or command prompt, navigate to your Laravel project directory, and execute the following command to add AssetFlow to your project's dependencies.

composer require assetflow/asset-flow-laravel

If you want to include the optional dependencies for enhanced functionality, install the package with its suggested dependencies. This provides access to advanced features that may require additional external libraries for optimal performance.

composer require assetflow/asset-flow-laravel --with-dependencies

After installation, AssetFlow will be automatically registered with your Laravel application through the package's service provider. The package will also register the AssetFlow facade, making it available throughout your application without requiring manual configuration.

Publishing the Configuration

After installation, publish the AssetFlow configuration file to your Laravel application's config directory. This allows you to customize the package behavior according to your project's requirements. Run the following Artisan command to publish the configuration.

php artisan vendor:publish --tag=assetflow-config

This command creates a new configuration file at config/assetflow.php in your Laravel application. You can modify this file to change default settings, configure adapters, enable or disable features, and customize theme variables.

2. Configuration

Basic Configuration

The AssetFlow package is configured through the config/assetflow.php file, which provides sensible defaults while allowing customization for specific project requirements. The configuration file uses Laravel's configuration system, which supports environment variable overrides and cached configuration for optimal performance in production environments.

The following example demonstrates a basic configuration setup for a production environment that uses CDN resources with aggressive caching and optimization features enabled. Review each configuration section to understand the available options and their effects on package behavior.

<?php

return [
    // Default UI framework adapter
    'default_adapter' => 'bootstrap5',

    // Environment mode: 'development' or 'production'
    'environment' => env('APP_ENV', 'development'),

    // CDN configuration
    'prefer_cdn' => env('ASSETFLOW_CDN', true),
    'cdn_fallback' => true,

    // Cache configuration
    'cache_enabled' => true,
    'cache_ttl' => 86400,
    'cache_prefix' => 'assetflow_',

    // Minification settings
    'minify_css' => true,
    'minify_js' => true,

    // Default theme configuration
    'theme' => [
        'primary' => '#6366f1',
        'secondary' => '#8b5cf6',
    ],
];

Environment-Based Configuration

Many applications use different configurations for development and production environments. You can implement environment-based configuration by checking Laravel's environment detection features. This approach ensures optimal settings for each deployment context without modifying code between environments.

// In config/assetflow.php
'environment' => env('APP_ENV', 'production'),

'prefer_cdn' => env('ASSETFLOW_CDN', env('APP_ENV') === 'production'),

'cache_enabled' => env('APP_ENV') === 'production',

'minify_css' => env('APP_ENV') === 'production',
'minify_js' => env('APP_ENV') === 'production',

'bundle_assets' => env('ASSETFLOW_BUNDLE', env('APP_ENV') === 'production'),

'cache_busting' => env('ASSETFLOW_CACHE_BUSTING', env('APP_ENV') === 'production'),

Advanced Feature Configuration

The package includes configuration options for advanced features including asset bundling, cache busting, image optimization, critical CSS extraction, and security headers. These features are disabled by default and must be explicitly enabled in the configuration file.

// Asset bundling
'bundle_assets' => true,

// Cache busting
'cache_busting' => true,
'cache_busting_strategy' => 'content_hash',

// Image optimization
'image_optimization' => true,
'image_optimization_config' => [
    'convert_to_webp' => true,
    'webp_quality' => 85,
    'lazy_loading' => true,
    'responsive_breakpoints' => [480, 768, 1024, 1280, 1920],
],

// Critical CSS
'critical_css_enabled' => true,
'critical_css_config' => [
    'inline_limit' => 10240,
    'strategy' => 'size',
],

// Security headers
'security_headers_enabled' => true,
'security_headers_config' => [
    'csp_enabled' => true,
    'csp_directives' => [
        'default-src' => ["'self'"],
        'script-src' => ["'self'", "'unsafe-inline'"],
        'style-src' => ["'self'", "'unsafe-inline'"],
        'img-src' => ["'self'", 'data:', 'blob:'],
    ],
    'hsts_enabled' => true,
    'hsts_max_age' => 31536000,
],

3. Usage

Basic Usage

Using AssetFlow in your Laravel application is straightforward. The package provides a facade for convenient access from anywhere in your application, including controllers, views, and service classes. Simply use the AssetFlow facade and call the methods you need to configure and render assets.

<?php

namespace App\Http\Controllers;

use AssetFlow\Laravel\AssetFlow;

class HomeController extends Controller
{
    public function index()
    {
        // Configure the adapter and theme
        AssetFlow::setAdapter('bootstrap5')
                 ->setTheme([
                     'primary' => '#6366f1',
                     'secondary' => '#8b5cf6',
                 ]);

        // Add custom assets
        AssetFlow::addCss('/css/custom-styles.css');
        AssetFlow::addJs('/js/custom-scripts.js', ['defer' => true]);

        return view('home');
    }
}

In your Blade template, use the Blade directives provided by the package to render the asset tags in the appropriate locations. The directives provide a clean, expressive syntax for including assets in your views.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    @assetflowHeaders
    @assetflowHead
</head>
<body @assetflowBodyAttrs>
    <div class="container">
        <h1>Welcome to AssetFlow</h1>
        <p>This page uses AssetFlow for asset management.</p>
    </div>

    @assetflowScripts
</body>
</html>

Using the AssetManager Directly

For more advanced use cases, you can resolve the AssetManager from the Laravel container. This approach provides more control over the asset management instance and is useful when you need multiple independent instances or want to inject dependencies.

use AssetFlow\Laravel\Libraries\AssetManager;

class CustomController extends Controller
{
    protected AssetManager $assets;

    public function __construct(AssetManager $assets)
    {
        $this->assets = $assets;
    }

    public function show()
    {
        $this->assets->setAdapter('tailwind')
                     ->setTheme([
                         'primary' => '#3b82f6',
                         'secondary' => '#8b5cf6',
                     ]);

        return view('page', ['assets' => $this->assets]);
    }
}

Switching Adapters

One of AssetFlow's key features is the ability to switch between UI frameworks without modifying your view files. This is particularly valuable for applications that need to support multiple themes, offer user-customizable interfaces, or gradually migrate between frameworks.

// Use Bootstrap 5
AssetFlow::setAdapter('bootstrap5');

// Switch to Tailwind CSS
AssetFlow::setAdapter('tailwind');

// Switch to Materialize
AssetFlow::setAdapter('materialize');

// Use a creative adapter
AssetFlow::setAdapter('cyberpunk');

Theming

AssetFlow's theming system converts configuration values into framework-specific CSS custom properties. Each adapter interprets theme variables according to its framework's CSS architecture, ensuring that theme values are applied correctly regardless of which framework you use.

// Set theme using the facade
AssetFlow::setTheme([
    'primary' => '#6366f1',
    'secondary' => '#8b5cf6',
    'success' => '#22c55e',
    'danger' => '#ef4444',
]);

// Use preset themes (where supported)
AssetFlow::setPreset('dark');
AssetFlow::setPreset('corporate');
AssetFlow::setPreset('startup');

4. Available Adapters

AssetFlow for Laravel includes eight adapters for popular and creative UI frameworks, plus the ComponentBridge adapter for JavaScript framework integration. Each adapter provides a consistent interface while implementing framework-specific asset registration and theming.

Framework Adapters

The Bootstrap 5 adapter provides comprehensive support for the most popular CSS framework. It includes the complete Bootstrap CSS and JavaScript bundle with Popper for positioning floating components. The adapter supports all Bootstrap 5.x versions and generates CSS variables for theming.

The Tailwind CSS adapter uses the Tailwind Play CDN for rapid development and prototyping. This adapter differs from others because Tailwind's CDN handles CSS through JavaScript rather than serving pre-built CSS files. The adapter supports custom configuration through the Tailwind config object.

The Bulma adapter provides lightweight Flexbox-based styling without JavaScript requirements. It includes CSS custom property mappings for theming and initialization scripts for common interactive patterns like dropdowns and mobile menu toggles.

The Materialize adapter implements Google's Material Design specifications with a comprehensive component library. It includes JavaScript for all components including modals, sliders, datepickers, and form elements. The adapter provides automatic initialization of all components with data attributes.

Creative Adapters

The RetroNES adapter implements 8-bit NES-style UI components using NES.css. It includes the Press Start 2P pixel font, scanline overlay effects, and dialog interactions. This adapter is particularly useful for retro gaming websites, pixel art projects, or playful interface designs.

The GlassUI adapter implements modern glassmorphism design with translucent backgrounds, blur effects, and gradient overlays. It includes JavaScript-powered gradient orb animations and hover parallax effects. The adapter supports multiple presets for different glass styling variations.

The CyberPunk adapter implements a futuristic cyberpunk aesthetic with neon glows, glitch effects, and sci-fi visual elements. It includes scanline overlays, holographic hover interactions, and typing effects. The adapter supports multiple color presets for different cyberpunk aesthetics.

ComponentBridge Adapter

The ComponentBridge adapter enables integration of Vue.js and React components within Laravel views. This adapter bridges server-side PHP rendering with client-side JavaScript frameworks, enabling hybrid rendering strategies that combine SEO benefits with rich interactivity.

// Configure Vue.js integration
AssetFlow::setAdapter('componentbridge');
AssetFlow::configureComponents([
    'framework' => 'vue',
    'root_id' => 'app',
    'components' => [
        'Header' => '/js/components/Header.vue',
        'Footer' => '/js/components/Footer.vue',
    ],
    'hydration' => true,
]);

// Register a component with props
AssetFlow::registerComponent('UserCard', [
    'name' => 'John Doe',
    'email' => 'john@example.com',
]);

// Render in Blade
<div id="app">
    @component('header')
    @endcomponent
    
    {{ AssetFlow::renderComponent('UserCard', ['name' => 'Jane Smith']) }}
</div>

5. Blade Directives

AssetFlow provides several Blade directives for convenient usage in your templates. These directives provide a clean, expressive syntax for including assets and configuring the package from within your Blade views.

The @assetflowHead directive renders all CSS links, meta tags, preconnect hints, and theme CSS variables. This directive should be placed in the document head section of your layout template.

The @assetflowScripts directive renders all JavaScript tags, CDN fallback scripts, and framework initialization scripts. This directive should be placed at the end of the document body for optimal page loading performance.

The @assetflowHeaders directive renders HTTP security headers if security headers are enabled in the configuration. This directive should be called before any HTML output, typically at the very beginning of the layout head section.

The @assetflowBodyAttrs directive renders body attributes required by the current adapter. Some adapters like GlassUI and CyberPunk require specific body classes for their visual effects.

The @assetflowAdapter directive switches the current UI adapter from within a Blade template. This is useful for conditionally rendering different frameworks in different sections of your application.

The @assetflowCss and @assetflowJs directives add custom CSS and JavaScript assets from within your templates. These directives are useful for adding page-specific assets without modifying controllers.

The @assetflowTheme directive sets theme variables from within your templates. This enables dynamic theming based on user preferences or route conditions.

The @assetflowImage directive renders an optimized image with lazy loading and responsive srcset attributes. This directive requires image optimization to be enabled in the configuration.

<!DOCTYPE html>
<html lang="en">
<head>
    @assetflowHeaders
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    @assetflowHead
    
    @assetflowCss('/css/page-specific.css')
</head>
<body @assetflowBodyAttrs>
    <div class="container">
        @yield('content')
    </div>

    @assetflowJs('/js/analytics.js')
    @assetflowScripts
</body>
</html>

6. Advanced Features

Asset Bundling

Asset bundling combines multiple CSS and JavaScript files into single optimized bundles, reducing HTTP requests and improving page load times. The bundling system groups related assets together and generates bundled files that can be served efficiently. Enable bundling in the configuration and define bundle groups to organize your assets effectively.

// Define bundles
AssetFlow::defineBundle('css', 'main', [
    '/css/reset.css',
    '/css/base.css',
    '/css/components.css',
]);

AssetFlow::defineBundle('js', 'app', [
    '/js/app/main.js',
    '/js/app/components.js',
]);

// Register bundles
AssetFlow::registerBundle('css', 'main');
AssetFlow::registerBundle('js', 'app');

Cache Busting

Cache busting ensures that browsers download updated assets when content changes, preventing users from seeing stale cached versions of your files. AssetFlow supports multiple cache busting strategies including content hash-based naming, query string versioning, and filename-based versioning.

// In config/assetflow.php
'cache_busting' => true,
'cache_busting_strategy' => 'content_hash',

Image Optimization

AssetFlow includes comprehensive image optimization features that automatically convert images to WebP format, generate responsive image sets, and implement lazy loading. These optimizations significantly reduce page weight and improve load times.

// Configure image optimization
AssetFlow::configureImageOptimization([
    'convert_to_webp' => true,
    'webp_quality' => 85,
    'lazy_loading' => true,
    'responsive_breakpoints' => [480, 768, 1024, 1280, 1920],
]);

// Render optimized image
@assetflowImage('/images/hero.jpg', ['alt' => 'Hero image', 'class' => 'img-fluid'])

Critical CSS

Critical CSS extraction identifies and inlines the styles needed to render above-fold content, improving first contentful paint metrics. This technique is particularly effective for improving Core Web Vitals scores.

// Configure critical CSS
AssetFlow::configureCriticalCss([
    'inline_limit' => 10240,
    'strategy' => 'size',
]);

Security Headers

AssetFlow includes a security headers driver that generates and manages content security policy headers, HTTP strict transport security, and other security-related response headers. These headers protect your application against common web vulnerabilities.

// Configure security headers
AssetFlow::configureSecurityHeaders([
    'csp_enabled' => true,
    'csp_directives' => [
        'default-src' => ["'self'"],
        'script-src' => ["'self'", "'unsafe-inline'"],
        'style-src' => ["'self'", "'unsafe-inline'"],
    ],
    'hsts_enabled' => true,
    'hsts_max_age' => 31536000,
]);

7. API Reference

AssetFlow Facade Methods

The AssetFlow facade provides static access to all AssetManager functionality. The following methods are available for configuring and rendering assets in your application.

The setAdapter method switches the current UI framework adapter. The adapter name must match a registered adapter, either built-in or custom-registered.

The setVersion method specifies the framework version to use. The version string must be available in the adapter's version registry.

The setTheme method configures theme variables that are converted to framework-specific CSS custom properties.

The addCss and addJs methods register additional assets that are included alongside framework assets. These methods accept additional HTML attributes as a second parameter.

The renderHead method generates all CSS links, meta tags, preconnect hints, and theme CSS variables for the document head.

The renderScripts method generates all JavaScript tags, CDN fallback scripts, and framework initialization scripts.

The renderBodyAttributes method returns HTML attribute string for the body element if the current adapter requires any.

The renderSecurityHeaders method outputs the configured security headers if enabled.

The clearCache method invalidates all cached asset output, forcing regeneration on the next render call.

8. Publishing to Packagist

AssetFlow for Laravel can be published to Packagist for discoverable installation by other developers. The package's composer.json file includes all necessary metadata for Packagist publication, including proper namespace mapping, package type, and Laravel-specific configuration.

To publish the package, ensure your repository has a complete composer.json file with accurate package metadata, including the package name, description, keywords, license, and author information. Create version tags following semantic versioning principles and push them to your GitHub repository.

Submit your package to Packagist by entering your GitHub repository URL on the Packagist submit page. Configure automatic updates through the GitHub webhook integration to ensure Packagist stays synchronized with your repository.

9. Contributing

Contributions to AssetFlow for Laravel are welcome through pull requests on GitHub. Before submitting a pull request, ensure your changes follow the existing code style and include appropriate tests. The package follows PSR-12 coding standards and Laravel conventions.

Fork the repository, create a feature branch for your changes, and submit the pull request when ready. Include a clear description of the changes and the problem they solve. Pull requests are reviewed by the maintainer and may require adjustments before being merged.

10. License

AssetFlow for Laravel is open source software licensed under the MIT license. This license permits use, modification, distribution, and sublicense of the software for both commercial and non-commercial purposes.

11. Support and Contact

For questions, suggestions, or inquiries about AssetFlow for Laravel, please contact the author Kazashim Kuzasuwat at kazashimkuzasuwat@gmail.com. The author welcomes feedback on the package's design, documentation, and functionality, as well as contributions from the developer community.

Bug reports and feature requests should be submitted through the GitHub issues page to ensure they are tracked and addressed systematically.

AssetFlow for Laravel

Author: Kazashim Kuzasuwat
Email: kazashimkuzasuwat@gmail.com
Repository: https://github.com/kazashim/assetflow

Package version: 1.0.0
Last updated: January 2026

assetflow / asset-flow-laravel

Maintainers

Details