Assets

Work with images, scripts, CSS files

[Since 0.5.0]

Introduction

Pletfix provides a simple asset pipeline tool to publish your stylesheets, JavaScripts and other assets.

You may define your assets very easy in resources/assets/build.php and publish them with Pletfix command asset. The command will compile, minimize and concatenate the assets, store it into the public folder and suffix a unique token to the filename for Cache Busting.

Under the hood Pletfix uses the following tools:

Asset Build Definition

You may define your assets in resources/assets/build.php. It looks like this:

return [
    'js/app.js' => [
        vendor_path('vendor/npm-asset/jquery/dist/jquery.min.js'),
        vendor_path('npm-asset/bootstrap/dist/js/bootstrap.min.js'),
        resource_path('assets/js/base.js'),
    ],
    'css/app.css' => [
        resource_path('assets/less/base.less'),
    ],
    'fonts' => [
        vendor_path('npm-asset/bootstrap/dist/fonts'),
        resource_path('assets/fonts/fonts.gstatic.com_lato.woff2'),
    ],
];

Pletfix supports JavaScript, stylesheets and other files like fonts or images which should be published into the public folder.

JavaScript

If you would like to minimize one or more JavaScript files or just combine them into a single file, you can define it like this:

'path/to/dest.min.js' => [
    'path/to/source.js',
    'path/to/second-script.js',
    'path/to/folder',
],

The destination file on the left side is relative to the public folder and requires .js as file extension. The source list on the right side should contain JavaScript files or folders, with an absolute path or relative to the base path. Files in the folders which are not JavaScript will be ignored.

Stylesheets

If you would like to minimize and combine some stylesheets to a single file, you may use it as below:

'path/to/dest.min.css' => [
    'path/to/source.css',
    'path/to/scss-file.scss',
    'path/to/less-file.less',
    'path/to/folder',
],

Note that the destination file on the left side must have .css as file extension and the source list on the right side should contain CSS, SCSS, Less files and folders. Only stylesheets are substantial in the folder.

Copying Files & Directories

If you like to just copy some files to the public folder, write entries in resources/assets/build.php like this:

'subpath' => [
    'path/to/a/image.png',
    'path/to/readme.md',
    'path/to/folder'
],

Note the destination is a folder in this example. In this case all files and directories on the right side will be copied into the destination folder instead of being concatenated to a single file.

Of course, it's also possible to concatenate some non-JS files and non-CSS to a single file.

Publishing Assets

You may enter the following Pletfix command in your terminal to build all assets you have defined:

php console asset

If you like to build just one specified asset, set the name of the destination file:

php console asset css/app.css  

The Pletfix's asset command is doing the following steps:

  1. Compiling: If the source file is a SCSS or Less File, the asset command will compile this to a plain CSS file.
  2. Minimizing JavaScript and stylesheets will be minimized so that it can be delivered quicker to the client.
  3. Concatenation: If the destination is not a folder but a file, asset will concatenate the minimized files to a single file.
  4. Copy: Finally asset will copy the concatenate file or the original source files to the public folder under the destination.
  5. Cache Busting: Additional the command suffix the unique token to the filename and store it into public/build.

If you don't like to minimize the file, set the 'no-minify' option:

php console asset css/app.css --no-minify

Removing Assets

If you want to remove an already published asset, enter this in your terminal:

php console asset css/app.css --remove

Plugin Options

You could compile all assets or only a specific asset from a plugin manually. For that, you only have to set the 'plugin' option with the name of the plugin (without vendor):

php console asset css/app.css --plugin=hello

You can use the plugin option and the remove option together to remove all assets of a plugin:

php console asset --remove --plugin=hello

Normally you don't need the plugin option to publish or remove the assets because it's happening automatically when you install or remove a plugin with the Pletfix's plugin command.

Usage in the View

You may use the global helper asset() to load the appropriately hashed asset into the view. Set the asset file relative to the public folder as argument of asset(). The function will automatically determine the current name of the hashed file:

<link rel="stylesheet" href="{{ asset('css/app.css') }}"/>

If no corresponding hashed file exists in public/build, the original file will be loaded.


(edit on GitHub)