Basset for Laravel

To customize Basset's behavior, you can publish its configuration file to your application's config directory using the config tag. This allows you to modify settings like the asset disk or execution logging.

php artisan vendor:publish --tag=config

Install Basset via Composer and run the installation command to set up the package. After installation, it is highly recommended to run the check command to ensure everything is configured correctly.

composer require backpack/basset
php artisan basset:install

# Recommended: check if everything is working correctly
php artisan basset:check

To use Basset on Laravel Vapor, you must use an S3 bucket for storage and disable the cache map because Vapor's filesystem is ephemeral.

1. In vapor.yml, include your storage bucket:

   storage: yourbucketname

2. In your Vapor .env file, configure the disk and cache map:

   BASSET_DISK=s3
   BASSET_CACHE_MAP=false

Follow these steps to upgrade your project to Basset v2:

1. Refresh installation: Run php artisan basset:install --git-ignore to refresh composer hooks and optionally ignore the public cache folder.
2. Configure Disk: Decide on your BASSET_DISK strategy (basset with storage symlink, or public_basset with Git tracking) before deploying.
3. Update Directives: Replace any custom @loadOnce usage with @basset or @bassetBlock. The old directive now acts as a proxy for the new ones.
4. Warm Cache: Ensure your deployment scripts run php artisan basset:cache or php artisan basset:fresh so assets are ready when the application boots.

Basset can be fine-tuned using the following environment variables:

• BASSET_DEV_MODE: (boolean) If true, Basset hashes local files/blocks so edits are picked up immediately. Defaults to false in production.
• BASSET_DISK: The disk used for internalized assets (e.g., basset, public_basset, or s3).
• BASSET_CACHE_MAP: (boolean) Set to false on serverless platforms like Laravel Vapor.
• BASSET_FETCH_TIMEOUT: Timeout for fetching remote assets (default 30s).
• BASSET_FETCH_RETRIES: Number of retries for failed fetches (default 3).
• BASSET_FETCH_RETRY_DELAY: Delay between retries in milliseconds (default 10000).
• BASSET_CACHE_MAP_COMPARISON: (boolean) If true, basset:cache skips re-downloading assets if their URL hasn't changed.

You can enable execution time logging for Basset in your configuration. When enabled, Basset will log the total number of calls and the total execution time to the Laravel logs upon application termination.

Set log_execution_time to true in config/backpack/basset.php.

The @basset() directive automatically generates the correct HTML tag based on the file extension. It ensures the asset is internalized and only loaded once per page load.

@basset('https://cdn.com/path/to/file.js') {{-- Outputs <script src="..."> --}}
@basset('https://cdn.com/path/to/file.css') {{-- Outputs <link href="..."> --}}
@basset(resource_path('/path/to/file.jpg')) {{-- Outputs <img src="..."> --}}

Replace Laravel's asset() helper with basset() to internalize assets from non-public paths or external URLs. Basset will download/copy the file to your configured disk and return the local path.

{{-- From a CDN --}}
<link href="{{ basset('https://cdn.com/path/to/file.css') }}">

{{-- From a non-public local path (e.g. vendor or storage) --}}
<script src="{{ basset(base_path('vendor/org/package/assets/file.js')) }}">
<script src="{{ basset(storage_path('file.js')) }}">

Basset provides several Blade directives to manage assets and code blocks within your templates.

Note on Deprecated Directives: @loadOnce, @endLoadOnce, @loadStyleOnce, and @loadScriptOnce are deprecated and will be removed in Backpack v7. You should migrate to @basset or @bassetBlock.

{{-- Recommended usage --}}
@basset('path/to/asset.css')
@basset('path/to/script.js')

{{-- Code blocks --}}
@bassetBlock($myBlock)
    <script>
        console.log('Hello Basset!');
    </script>
@endBassetBlock

{{-- Directory and Archive --}}
@bassetDirectory('path/to/directory')
@bassetArchive('path/to/archive.zip')

Internalize an entire non-public directory at once by providing the path and a name for the directory.

{{-- Internalize the directory --}}
@bassetDirectory(resource_path('package-1.0.0/'), 'package-1.0.0')

{{-- Use a file from that directory --}}
@basset('package-1.0.0/plugin.min.js')