feature #963 feat: add Encore.when() (Kocal)

This PR was squashed before being merged into the main branch.

Discussion
----------

feat: add Encore.when()

Replace #900 by adding a more generic and flexible API than `Encore.isDev()`/`Encore.isProd()`, see #900 (comment).

`Encore.when()` takes two parameters:
- `condition`: can be a callback (where the current instance of Encore is passed as first parameter) or a boolean. If this results to `true`, the parameter `callback` is called
- `callback`: executed when parameter `condition` results to `true`, it takes the current instance of Encore as first parameter

WDYT? Thanks!

Commits
-------

8082c61 feat: add Encore.when()

Author: weaverryan

index.js

@@ -1596,6 +1596,29 @@ class Encore {
         return webpackConfig.isDevServer();
     }
 
+    /**
+     * Use to conditionally configure or enable features only in when the first parameter results to "true".
+     *
+     * ```
+     * Encore
+     *     // passing a callback
+     *     .when((Encore) => Encore.isProduction(), (Encore) => Encore.enableVersioning())
+     *     // passing a boolean
+     *     .when(process.argv.includes('--analyze'), (Encore) => Encore.addPlugin(new BundleAnalyzerPlugin()))
+     * ```
+     *
+     * @param {(function(Encore): boolean) | boolean} condition
+     * @param {function(Encore): void} callback
+     * @return {Encore}
+     */
+    when(condition, callback) {
+        if (typeof condition === 'function' && condition(this) || typeof condition === 'boolean' && condition) {
+            callback(this);
+        }
+
+        return this;
+    }
+
     /**
      * Use this at the bottom of your webpack.config.js file:
      *

test/index.js

@@ -10,6 +10,7 @@
 'use strict';
 
 const expect = require('chai').expect;
+const sinon = require('sinon');
 const api = require('../index');
 const path = require('path');
 
@@ -454,6 +455,21 @@ describe('Public API', () => {
 
     });
 
+    describe('when', () => {
+        it('should call or not callbacks depending of the conditions', () => {
+            api.configureRuntimeEnvironment('dev', {}, false);
+
+            const spy = sinon.spy();
+            api
+                .when((Encore) => Encore.isDev(), (Encore) => spy('is dev'))
+                .when((Encore) => Encore.isProduction(), (Encore) => spy('is production'))
+                .when(true, (Encore) => spy('true'));
+            expect(spy.calledWith('is dev'), 'callback for "is dev" should be called').to.be.true;
+            expect(spy.calledWith('is production'), 'callback for "is production" should NOT be called').to.be.false;
+            expect(spy.calledWith('true'), 'callback for "true" should be called').to.be.true;
+        });
+    });
+
     describe('isRuntimeEnvironmentConfigured', () => {
 
         it('should return true if the runtime environment has been configured', () => {