feature #137 Add Encore.configureFilenames() method to the public API (Lyrkan)

This PR was merged into the master branch.

Discussion
----------

Add Encore.configureFilenames() method to the public API

This PR adds the `Encore.configureFilenames()` method to the public API (fixes #125).

**Example:**

```js
Encore.configureFilenames({
    js: '[name].[chunkhash].js',
    css: '[name].[contenthash].css',
    images: 'images/[name].[hash:8].[ext]',
    fonts: 'fonts/[name].[hash:8].[ext]'
});
```

If one key is defined in the first parameter it will be used for the filenames of the related category.
If it isn't the behavior will stay the same as before.

For now I kept the old naming strategies as the default values. We could eventually change that following the discussion in #136.

Commits
-------

0c9a8fe Add Encore.configureFilenames() method to the public API

Author: weaverryan

index.js

@@ -471,6 +471,34 @@ const publicApi = {
         return this;
     },
 
+    /**
+     * Call this to change how the name of each output
+     * file is generated.
+     *
+     *     Encore.configureFilenames({
+     *         js: '[name].[chunkhash].js',
+     *         css: '[name].[contenthash].css',
+     *         images: 'images/[name].[hash:8].[ext]',
+     *         fonts: 'fonts/[name].[hash:8].[ext]'
+     *     });
+     *
+     * Only the filenames defined in the first parameter
+     * of this method will be modified.
+     *
+     * If you are using Encore.enableVersioning()
+     * make sure that your "js" filenames contain
+     * "[chunkhash]" and your "css" filenames contain
+     * "[contenthash]".
+     *
+     * @param {object} filenames
+     * @returns {exports}
+     */
+    configureFilenames(filenames) {
+        webpackConfig.configureFilenames(filenames);
+
+        return this;
+    },
+
     /**
      * If enabled, the output directory is emptied between
      * each build (to remove old files).

lib/WebpackConfig.js

@@ -62,6 +62,7 @@ class WebpackConfig {
         this.forkedTypeScriptTypesCheckOptionsCallback = () => {};
         this.useImagesLoader = true;
         this.useFontsLoader = true;
+        this.configuredFilenames = {};
     }
 
     getContext() {
@@ -285,6 +286,22 @@ class WebpackConfig {
         this.useFontsLoader = false;
     }
 
+    configureFilenames(configuredFilenames = {}) {
+        if (typeof configuredFilenames !== 'object') {
+            throw new Error('Argument 1 to configureFilenames() must be an object.');
+        }
+
+        // Check allowed keys
+        const validKeys = ['js', 'css', 'images', 'fonts'];
+        for (const key of Object.keys(configuredFilenames)) {
+            if (validKeys.indexOf(key) === -1) {
+                throw new Error(`"${key}" is not a valid key for configureFilenames(). Valid keys: ${validKeys.join(', ')}.`);
+            }
+        }
+
+        this.configuredFilenames = configuredFilenames;
+    }
+
     cleanupOutputBeforeBuild() {
         this.cleanupOutput = true;
     }

lib/config-generator.js

@@ -101,9 +101,15 @@ class ConfigGenerator {
     }
 
     buildOutputConfig() {
+        // Default filename can be overriden using Encore.configureFilenames({ js: '...' })
+        let filename = this.webpackConfig.useVersioning ? '[name].[chunkhash].js' : '[name].js';
+        if (this.webpackConfig.configuredFilenames.js) {
+            filename = this.webpackConfig.configuredFilenames.js;
+        }
+
         return {
             path: this.webpackConfig.outputPath,
-            filename: this.webpackConfig.useVersioning ? '[name].[chunkhash].js' : '[name].js',
+            filename: filename,
             // will use the CDN path (if one is available) so that split
             // chunks load internally through the CDN.
             publicPath: this.webpackConfig.getRealPublicPath(),
@@ -126,22 +132,34 @@ class ConfigGenerator {
         ];
 
         if (this.webpackConfig.useImagesLoader) {
+            // Default filename can be overriden using Encore.configureFilenames({ images: '...' })
+            let filename = 'images/[name].[hash:8].[ext]';
+            if (this.webpackConfig.configuredFilenames.images) {
+                filename = this.webpackConfig.configuredFilenames.images;
+            }
+
             rules.push({
                 test: /\.(png|jpg|jpeg|gif|ico|svg)$/,
                 loader: 'file-loader',
                 options: {
-                    name: 'images/[name].[hash:8].[ext]',
+                    name: filename,
                     publicPath: this.webpackConfig.getRealPublicPath()
                 }
             });
         }
 
         if (this.webpackConfig.useFontsLoader) {
+            // Default filename can be overriden using Encore.configureFilenames({ fonts: '...' })
+            let filename = 'fonts/[name].[hash:8].[ext]';
+            if (this.webpackConfig.configuredFilenames.fonts) {
+                filename = this.webpackConfig.configuredFilenames.fonts;
+            }
+
             rules.push({
                 test: /\.(woff|woff2|ttf|eot|otf)$/,
                 loader: 'file-loader',
                 options: {
-                    name: 'fonts/[name].[hash:8].[ext]',
+                    name: filename,
                     publicPath: this.webpackConfig.getRealPublicPath()
                 }
             });

lib/plugins/extract-text.js

@@ -30,8 +30,15 @@ module.exports = function(plugins, webpackConfig, extractTextOptions = {}) {
      * link tag for an entry point's CSS (unless no CSS file
      * was imported - in which case no CSS file will be dumped).
      */
+
+    // Default filename can be overriden using Encore.configureFilenames({ css: '...' })
+    let filename = webpackConfig.useVersioning ? '[name].[contenthash].css' : '[name].css';
+    if (webpackConfig.configuredFilenames.css) {
+        filename = webpackConfig.configuredFilenames.css;
+    }
+
     let config = Object.assign({}, extractTextOptions, {
-        filename: webpackConfig.useVersioning ? '[name].[contenthash].css' : '[name].css',
+        filename: filename,
         // if true, async CSS (e.g. loaded via require.ensure())
         // is extracted to the entry point CSS. If false, it's
         // inlined in the AJAX-loaded .js file.

test/WebpackConfig.js

@@ -460,4 +460,41 @@ describe('WebpackConfig object', () => {
             expect(config.useFontsLoader).to.be.false;
         });
     });
+
+    describe('configureFilenames', () => {
+        it('Calling method sets it', () => {
+            const config = createConfig();
+            config.configureFilenames({
+                js: '[name].[chunkhash].js',
+                css: '[name].[contenthash].css',
+                images: 'images/[name].[hash:8].[ext]',
+                fonts: 'fonts/[name].[hash:8].[ext]'
+            });
+
+            expect(config.configuredFilenames).to.deep.equals({
+                js: '[name].[chunkhash].js',
+                css: '[name].[contenthash].css',
+                images: 'images/[name].[hash:8].[ext]',
+                fonts: 'fonts/[name].[hash:8].[ext]'
+            });
+        });
+
+        it('Calling with non-object throws an error', () => {
+            const config = createConfig();
+
+            expect(() => {
+                config.configureFilenames('FOO');
+            }).to.throw('must be an object');
+        });
+
+        it('Calling with an unknown key throws an error', () => {
+            const config = createConfig();
+
+            expect(() => {
+                config.configureFilenames({
+                    foo: 'bar'
+                });
+            }).to.throw('"foo" is not a valid key');
+        });
+    });
 });

test/config-generator.js

@@ -476,4 +476,57 @@ describe('The config-generator function', () => {
             }).to.throw();
         });
     });
+
+    describe('Test filenames changes', () => {
+        it('without versioning', () => {
+            const config = createConfig();
+            config.outputPath = '/tmp/public-path';
+            config.publicPath = '/public-path';
+            config.addEntry('main', './main');
+            config.configureFilenames({
+                js: '[name].foo.js',
+                css: '[name].foo.css',
+                images: '[name].foo.[ext]',
+                fonts: '[name].bar.[ext]'
+            });
+
+            const actualConfig = configGenerator(config);
+            expect(actualConfig.output.filename).to.equal('[name].foo.js');
+
+            const extractTextPlugin = findPlugin(ExtractTextPlugin, actualConfig.plugins);
+            expect(extractTextPlugin.filename).to.equal('[name].foo.css');
+
+            const imagesRule = findRule(/\.(png|jpg|jpeg|gif|ico|svg)$/, actualConfig.module.rules);
+            expect(imagesRule.options.name).to.equal('[name].foo.[ext]');
+
+            const fontsRule = findRule(/\.(woff|woff2|ttf|eot|otf)$/, actualConfig.module.rules);
+            expect(fontsRule.options.name).to.equal('[name].bar.[ext]');
+        });
+
+        it('with versioning', () => {
+            const config = createConfig();
+            config.outputPath = '/tmp/public-path';
+            config.publicPath = '/public-path';
+            config.addEntry('main', './main');
+            config.enableVersioning();
+            config.configureFilenames({
+                js: '[name].foo.js',
+                css: '[name].foo.css',
+                images: '[name].foo.[ext]',
+                fonts: '[name].bar.[ext]'
+            });
+
+            const actualConfig = configGenerator(config);
+            expect(actualConfig.output.filename).to.equal('[name].foo.js');
+
+            const extractTextPlugin = findPlugin(ExtractTextPlugin, actualConfig.plugins);
+            expect(extractTextPlugin.filename).to.equal('[name].foo.css');
+
+            const imagesRule = findRule(/\.(png|jpg|jpeg|gif|ico|svg)$/, actualConfig.module.rules);
+            expect(imagesRule.options.name).to.equal('[name].foo.[ext]');
+
+            const fontsRule = findRule(/\.(woff|woff2|ttf|eot|otf)$/, actualConfig.module.rules);
+            expect(fontsRule.options.name).to.equal('[name].bar.[ext]');
+        });
+    });
 });

test/index.js

@@ -224,6 +224,15 @@ describe('Public API', () => {
 
     });
 
+    describe('configureFilenames', () => {
+
+        it('must return the API object', () => {
+            const returnedValue = api.configureFilenames({});
+            expect(returnedValue).to.equal(api);
+        });
+
+    });
+
     describe('cleanupOutputBeforeBuild', () => {
 
         it('must return the API object', () => {