@wordpress/env 6.0.0 → 8.0.0

package/lib/get-host-user.js

@@ -0,0 +1,27 @@
+'use strict';
+/**
+ * External dependencies
+ */
+const os = require( 'os' );
+
+/**
+ * Gets information about the host user.
+ *
+ * @return {Object} The host user's name, uid, and gid.
+ */
+module.exports = function getHostUser() {
+	const hostUser = os.userInfo();
+
+	// On Windows the uid and gid will be -1. Since there isn't a great way to handle this,
+	// we're just going to assign them to 1000. Docker Desktop already takes care of
+	// permission-related issues using magic, so this should be fine.
+	const uid = ( hostUser.uid === -1 ? 1000 : hostUser.uid ).toString();
+	const gid = ( hostUser.gid === -1 ? 1000 : hostUser.gid ).toString();
+
+	return {
+		name: hostUser.username,
+		uid,
+		gid,
+		fullUser: uid + ':' + gid,
+	};
+};

package/lib/init-config.js

@@ -1,3 +1,4 @@
+'use strict';
 /**
  * External dependencies
  */
@@ -5,12 +6,11 @@ const path = require( 'path' );
 const { writeFile, mkdir } = require( 'fs' ).promises;
 const { existsSync } = require( 'fs' );
 const yaml = require( 'js-yaml' );
-const os = require( 'os' );
 
 /**
  * Internal dependencies
  */
-const { readConfig } = require( './config' );
+const { loadConfig, ValidationError } = require( './config' );
 const buildDockerComposeConfig = require( './build-docker-compose-config' );
 
 /**
@@ -39,8 +39,7 @@ module.exports = async function initConfig( {
 	xdebug = 'off',
 	writeChanges = false,
 } ) {
-	const configPath = path.resolve( '.wp-env.json' );
-	const config = await readConfig( configPath );
+	const config = await loadConfig( path.resolve( '.' ) );
 	config.debug = debug;
 
 	// Adding this to the config allows the start command to understand that the
@@ -81,13 +80,23 @@ module.exports = async function initConfig( {
 			yaml.dump( dockerComposeConfig )
 		);
 
-		await writeFile(
-			path.resolve( config.workDirectoryPath, 'Dockerfile' ),
-			dockerFileContents(
-				dockerComposeConfig.services.wordpress.image,
-				config
-			)
-		);
+		// Write four Dockerfiles for each service we provided.
+		// (WordPress and CLI services, then a development and test environment for each.)
+		for ( const imageType of [ 'WordPress', 'CLI' ] ) {
+			for ( const envType of [ 'development', 'tests' ] ) {
+				await writeFile(
+					path.resolve(
+						config.workDirectoryPath,
+						`${
+							envType === 'tests' ? 'Tests-' : ''
+						}${ imageType }.Dockerfile`
+					),
+					imageType === 'WordPress'
+						? wordpressDockerFileContents( envType, config )
+						: cliDockerFileContents( envType, config )
+				);
+			}
+		}
 	} else if ( ! existsSync( config.workDirectoryPath ) ) {
 		spinner.fail(
 			'wp-env has not yet been initialized. Please run `wp-env start` to install the WordPress instance before using any other commands. This is only necessary to set up the environment for the first time; it is typically not necessary for the instance to be running after that in order to use other commands.'
@@ -99,80 +108,194 @@ module.exports = async function initConfig( {
 };
 
 /**
- * Checks the configured PHP version
- * against the minimum version supported by Xdebug
+ * Generates the Dockerfile used by wp-env's `wordpress` and `tests-wordpress` instances.
  *
- * @param {WPConfig} config
- * @return {boolean} Whether the PHP version is supported by Xdebug
+ * @param {string}   env    The environment we're installing -- development or tests.
+ * @param {WPConfig} config The configuration object.
+ * @return {string} The dockerfile contents.
  */
-function checkXdebugPhpCompatibility( config ) {
-	// By default, an undefined phpVersion uses the version on the docker image,
-	// which is supported by Xdebug 3.
-	const phpCompatibility = true;
-
-	// If PHP version is defined
-	// ensure it meets the Xdebug minimum compatibility requirment.
-	if ( config.env.development.phpVersion ) {
-		const versionTokens = config.env.development.phpVersion.split( '.' );
-		const majorVer = parseInt( versionTokens[ 0 ] );
-		const minorVer = parseInt( versionTokens[ 1 ] );
+function wordpressDockerFileContents( env, config ) {
+	const phpVersion = config.env[ env ].phpVersion
+		? ':php' + config.env[ env ].phpVersion
+		: '';
 
-		if ( isNaN( majorVer ) || isNaN( minorVer ) ) {
-			throw new Error(
-				'Something went wrong when parsing the PHP version.'
-			);
-		}
+	return `FROM wordpress${ phpVersion }
 
-		// Xdebug 3 supports 7.2 and higher
-		// Ensure user has specified a compatible PHP version.
-		if ( majorVer < 7 || ( majorVer === 7 && minorVer < 2 ) ) {
-			throw new Error( 'Cannot use XDebug 3 on PHP < 7.2.' );
-		}
-	}
+# Update apt sources for archived versions of Debian.
+
+# stretch (https://lists.debian.org/debian-devel-announce/2023/03/msg00006.html)
+RUN sed -i 's|deb.debian.org/debian stretch|archive.debian.org/debian stretch|g' /etc/apt/sources.list
+RUN sed -i 's|security.debian.org/debian-security stretch|archive.debian.org/debian-security stretch|g' /etc/apt/sources.list
+RUN sed -i '/stretch-updates/d' /etc/apt/sources.list
 
-	return phpCompatibility;
+# Create the host's user so that we can match ownership in the container.
+ARG HOST_USERNAME
+ARG HOST_UID
+ARG HOST_GID
+# When the IDs are already in use we can still safely move on.
+RUN groupadd -g $HOST_GID $HOST_USERNAME || true
+RUN useradd -m -u $HOST_UID -g $HOST_GID $HOST_USERNAME || true
+
+# Install any dependencies we need in the container.
+${ installDependencies( 'wordpress', env, config ) }`;
 }
 
 /**
- * Generates the Dockerfile used by wp-env's development instance.
+ * Generates the Dockerfile used by wp-env's `cli` and `tests-cli` instances.
  *
- * @param {string}   image  The base docker image to use.
+ * @param {string}   env    The environment we're installing -- development or tests.
  * @param {WPConfig} config The configuration object.
- *
  * @return {string} The dockerfile contents.
  */
-function dockerFileContents( image, config ) {
-	// Don't install XDebug unless it is explicitly required.
-	let shouldInstallXdebug = false;
+function cliDockerFileContents( env, config ) {
+	const phpVersion = config.env[ env ].phpVersion
+		? '-php' + config.env[ env ].phpVersion
+		: '';
+
+	return `FROM wordpress:cli${ phpVersion }
+
+# Switch to root so we can create users.
+USER root
+
+# Create the host's user so that we can match ownership in the container.
+ARG HOST_USERNAME
+ARG HOST_UID
+ARG HOST_GID
+# When the IDs are already in use we can still safely move on.
+RUN addgroup -g $HOST_GID $HOST_USERNAME || true
+RUN adduser -h /home/$HOST_USERNAME -G $( getent group $HOST_GID | cut -d: -f1 ) -u $HOST_UID $HOST_USERNAME || true
+
+# Install any dependencies we need in the container.
+${ installDependencies( 'cli', env, config ) }
+	
+# Switch back to the original user now that we're done.
+USER www-data
+
+# Have the container sleep infinitely to keep it alive for us to run commands on it.
+CMD [ "/bin/sh", "-c", "while true; do sleep 2073600; done" ]
+`;
+}
+
+/**
+ * Generates content for the Dockerfile to install dependencies.
+ *
+ * @param {string}   service The kind of service that we're installing dependencies on ('wordpress' or 'cli').
+ * @param {string}   env     The environment we're installing dependencies for ('development' or 'tests').
+ * @param {WPConfig} config  The configuration object.
+ * @return {string} The Dockerfile content for installing dependencies.
+ */
+function installDependencies( service, env, config ) {
+	let dockerFileContent = '';
+
+	// At times we may need to evaluate the environment. This is because the
+	// WordPress image uses Ubuntu while the CLI image uses Alpine.
+
+	// Start with some environment-specific dependency installations.
+	switch ( service ) {
+		case 'wordpress': {
+			dockerFileContent += `
+# Make sure we're working with the latest packages.
+RUN apt-get -qy update
 
-	if ( config.xdebug !== 'off' ) {
-		const usingCompatiblePhp = checkXdebugPhpCompatibility( config );
+# Install some basic PHP dependencies.
+RUN apt-get -qy install $PHPIZE_DEPS && touch /usr/local/etc/php/php.ini
+
+# Set up sudo so they can have root access.
+RUN apt-get -qy install sudo
+RUN echo "#$HOST_UID ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers`;
+			break;
+		}
+		case 'cli': {
+			dockerFileContent += `
+# Make sure we're working with the latest packages.
+RUN apk update
+
+# Install some basic PHP dependencies.
+RUN apk --no-cache add $PHPIZE_DEPS && touch /usr/local/etc/php/php.ini
 
-		if ( usingCompatiblePhp ) {
-			shouldInstallXdebug = true;
+# Set up sudo so they can have root access.
+RUN apk --no-cache add sudo linux-headers
+RUN echo "#$HOST_UID ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers`;
+			break;
+		}
+		default: {
+			throw new Error( `Invalid service "${ service }" given` );
 		}
 	}
 
-	return `FROM ${ image }
+	dockerFileContent += getXdebugConfig(
+		config.xdebug,
+		config.env[ env ].phpVersion
+	);
 
-RUN apt-get -qy install $PHPIZE_DEPS && touch /usr/local/etc/php/php.ini
-${ shouldInstallXdebug ? installXdebug( config.xdebug ) : '' }
-`;
+	// Add better PHP settings.
+	dockerFileContent += `
+RUN echo 'upload_max_filesize = 1G' >> /usr/local/etc/php/php.ini
+RUN echo 'post_max_size = 1G' >> /usr/local/etc/php/php.ini`;
+
+	// Make sure Composer is available for use in all services.
+	dockerFileContent += `
+RUN curl -sS https://getcomposer.org/installer -o /tmp/composer-setup.php
+RUN export COMPOSER_HASH=\`curl -sS https://composer.github.io/installer.sig\` && php -r "if (hash_file('SHA384', '/tmp/composer-setup.php') === '$COMPOSER_HASH') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('/tmp/composer-setup.php'); } echo PHP_EOL;"
+RUN php /tmp/composer-setup.php --install-dir=/usr/local/bin --filename=composer
+RUN rm /tmp/composer-setup.php`;
+
+	// Install any Composer packages we might need globally.
+	// Make sure to do this as the user and ensure the binaries are available in the $PATH.
+	dockerFileContent += `
+USER $HOST_UID:$HOST_GID
+ENV PATH="\${PATH}:~/.composer/vendor/bin"
+RUN composer global require --dev yoast/phpunit-polyfills:"^1.0"
+USER root`;
+
+	return dockerFileContent;
 }
 
-function installXdebug( enableXdebug ) {
-	const isLinux = os.type() === 'Linux';
-	// Discover client host does not appear to work on macOS with Docker.
-	const clientDetectSettings = isLinux
-		? 'xdebug.discover_client_host=true'
-		: 'xdebug.client_host="host.docker.internal"';
+/**
+ * Gets the Xdebug config based on the options in the config object.
+ *
+ * @param {string} xdebugMode The Xdebug mode set in the config.
+ * @param {string} phpVersion The php version set in the environment.
+ * @return {string} The Xdebug config -- can be an empty string when it's not used.
+ */
+function getXdebugConfig( xdebugMode = 'off', phpVersion ) {
+	if ( xdebugMode === 'off' ) {
+		return '';
+	}
+
+	let xdebugVersion = 'xdebug';
+
+	if ( phpVersion ) {
+		const versionTokens = phpVersion.split( '.' );
+		const majorVer = parseInt( versionTokens[ 0 ] );
+		const minorVer = parseInt( versionTokens[ 1 ] );
+
+		if ( isNaN( majorVer ) || isNaN( minorVer ) ) {
+			throw new ValidationError(
+				'Something went wrong when parsing the PHP version.'
+			);
+		}
+
+		// Throw an error if someone tries to use Xdebug with an unsupported PHP version.
+		// Xdebug 3 only supports 7.2 and higher.
+		if ( majorVer < 7 || ( majorVer === 7 && minorVer < 2 ) ) {
+			throw new ValidationError(
+				`Cannot use XDebug 3 with PHP < 7.2. Your PHP version is ${ phpVersion }.`
+			);
+		}
+
+		// For now, we support PHP 7 by installing the final version of Xdebug to
+		// support PHP 7 when the environment uses that version. By default, use the
+		// latest version.
+		if ( majorVer === 7 ) {
+			xdebugVersion = 'xdebug-3.1.6';
+		}
+	}
 
 	return `
-# Install Xdebug:
-RUN if [ -z "$(pecl list | grep xdebug)" ] ; then pecl install xdebug ; fi
+RUN if [ -z "$(pecl list | grep ${ xdebugVersion })" ] ; then pecl install ${ xdebugVersion } ; fi
 RUN docker-php-ext-enable xdebug
 RUN echo 'xdebug.start_with_request=yes' >> /usr/local/etc/php/php.ini
-RUN echo 'xdebug.mode=${ enableXdebug }' >> /usr/local/etc/php/php.ini
-RUN echo '${ clientDetectSettings }' >> /usr/local/etc/php/php.ini
-	`;
+RUN echo 'xdebug.mode=${ xdebugMode }' >> /usr/local/etc/php/php.ini
+RUN echo 'xdebug.client_host="host.docker.internal"' >> /usr/local/etc/php/php.ini`;
 }

package/lib/md5.js

@@ -1,3 +1,4 @@
+'use strict';
 /**
  * External dependencies
  */

package/lib/parse-xdebug-mode.js

@@ -1,3 +1,4 @@
+'use strict';
 // See https://xdebug.org/docs/all_settings#mode
 const XDEBUG_MODES = [
 	'develop',

package/lib/retry.js

@@ -1,3 +1,4 @@
+'use strict';
 /**
  * External dependencies
  */

package/lib/test/__snapshots__/md5.js.snap

@@ -0,0 +1,9 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`md5 creates a hash of a number 1`] = `"55587a910882016321201e6ebbc9f595"`;
+
+exports[`md5 creates a hash of a object 1`] = `"a0294b0e88367a0ff800d78413356538"`;
+
+exports[`md5 creates a hash of a string 1`] = `"5d41402abc4b2a76b9719d911017c592"`;
+
+exports[`md5 creates a hash of null 1`] = `"37a6259cc0c1dae299a7866489dff0bd"`;

package/lib/test/build-docker-compose-config.js

@@ -0,0 +1,134 @@
+'use strict';
+/**
+ * Internal dependencies
+ */
+const buildDockerComposeConfig = require( '../build-docker-compose-config' );
+const getHostUser = require( '../get-host-user' );
+
+// The basic config keys which build docker compose config requires.
+const CONFIG = {
+	mappings: {},
+	pluginSources: [],
+	themeSources: [],
+	port: 8888,
+	configDirectoryPath: '/path/to/config',
+};
+
+jest.mock( '../get-host-user', () => jest.fn() );
+getHostUser.mockImplementation( () => {
+	return {
+		name: 'test',
+		uid: 1,
+		gid: 2,
+		fullUser: '1:2',
+	};
+} );
+
+describe( 'buildDockerComposeConfig', () => {
+	it( 'should map directories before individual sources', () => {
+		const envConfig = {
+			...CONFIG,
+			mappings: {
+				'wp-content/plugins': {
+					path: '/path/to/wp-plugins',
+				},
+			},
+			pluginSources: [
+				{ path: '/path/to/local/plugin', basename: 'test-name' },
+			],
+		};
+		const dockerConfig = buildDockerComposeConfig( {
+			workDirectoryPath: '/path',
+			env: { development: envConfig, tests: envConfig },
+		} );
+		const { volumes } = dockerConfig.services.wordpress;
+		expect( volumes ).toEqual( [
+			'wordpress:/var/www/html', // WordPress root.
+			'/path/WordPress-PHPUnit/tests/phpunit:/wordpress-phpunit', // WordPress test library,
+			'user-home:/home/test',
+			'/path/to/wp-plugins:/var/www/html/wp-content/plugins', // Mapped plugins root.
+			'/path/to/local/plugin:/var/www/html/wp-content/plugins/test-name', // Mapped plugin.
+		] );
+	} );
+
+	it( 'should add all specified sources to tests, dev, and cli services', () => {
+		const envConfig = {
+			...CONFIG,
+			mappings: {
+				'wp-content/plugins': {
+					path: '/path/to/wp-plugins',
+				},
+			},
+			pluginSources: [
+				{ path: '/path/to/local/plugin', basename: 'test-name' },
+			],
+			themeSources: [
+				{ path: '/path/to/local/theme', basename: 'test-theme' },
+			],
+		};
+		const dockerConfig = buildDockerComposeConfig( {
+			workDirectoryPath: '/path',
+			env: { development: envConfig, tests: envConfig },
+		} );
+		const devVolumes = dockerConfig.services.wordpress.volumes;
+		const cliVolumes = dockerConfig.services.cli.volumes;
+		expect( devVolumes ).toEqual( cliVolumes );
+
+		const testsVolumes = dockerConfig.services[ 'tests-wordpress' ].volumes;
+		const testsCliVolumes = dockerConfig.services[ 'tests-cli' ].volumes;
+		expect( testsVolumes ).toEqual( testsCliVolumes );
+
+		let localSources = [
+			'/path/to/wp-plugins:/var/www/html/wp-content/plugins',
+			'/path/WordPress-PHPUnit/tests/phpunit:/wordpress-phpunit',
+			'user-home:/home/test',
+			'/path/to/local/plugin:/var/www/html/wp-content/plugins/test-name',
+			'/path/to/local/theme:/var/www/html/wp-content/themes/test-theme',
+		];
+		expect( devVolumes ).toEqual( expect.arrayContaining( localSources ) );
+
+		localSources = [
+			'/path/to/wp-plugins:/var/www/html/wp-content/plugins',
+			'/path/tests-WordPress-PHPUnit/tests/phpunit:/wordpress-phpunit',
+			'tests-user-home:/home/test',
+			'/path/to/local/plugin:/var/www/html/wp-content/plugins/test-name',
+			'/path/to/local/theme:/var/www/html/wp-content/themes/test-theme',
+		];
+		expect( testsVolumes ).toEqual(
+			expect.arrayContaining( localSources )
+		);
+	} );
+
+	it( 'should create "wordpress" and "tests-wordpress" volumes if they are needed by containers', () => {
+		// CONFIG has no coreSource entry, so there are no core sources on the
+		// local filesystem, so a volume should be created to contain core
+		// sources.
+		const dockerConfig = buildDockerComposeConfig( {
+			workDirectoryPath: '/path',
+			env: { development: CONFIG, tests: CONFIG },
+		} );
+
+		expect( dockerConfig.volumes.wordpress ).not.toBe( undefined );
+		expect( dockerConfig.volumes[ 'tests-wordpress' ] ).not.toBe(
+			undefined
+		);
+	} );
+
+	it( 'should NOT create "wordpress" and "tests-wordpress" volumes if they are not needed by containers', () => {
+		const envConfig = {
+			...CONFIG,
+			coreSource: {
+				path: '/some/random/path',
+				local: true,
+			},
+		};
+
+		const dockerConfig = buildDockerComposeConfig( {
+			workDirectoryPath: '/path',
+			env: { development: envConfig, tests: envConfig },
+		} );
+
+		expect( dockerConfig.volumes.wordpress ).toBe( undefined );
+		expect( dockerConfig.volumes[ 'tests-wordpress' ] ).toBe( undefined );
+	} );
+} );

package/lib/test/cache.js

@@ -0,0 +1,154 @@
+'use strict';
+/**
+ * External dependencies
+ */
+const { readFile, writeFile } = require( 'fs' ).promises;
+
+/**
+ * Internal dependencies
+ */
+const {
+	didCacheChange,
+	setCache,
+	getCache,
+	getCacheFile,
+} = require( '../cache' );
+
+jest.mock( 'fs', () => ( {
+	promises: {
+		readFile: jest.fn(),
+		writeFile: jest.fn(),
+	},
+} ) );
+
+const cacheOptions = {
+	workDirectoryPath: '/a/b/c',
+};
+
+function deleteCacheFile() {
+	readFile.mockImplementation( () => Promise.reject( 'No file!' ) );
+}
+
+function setCacheFile( data ) {
+	readFile.mockImplementation( () =>
+		Promise.resolve( JSON.stringify( data ) )
+	);
+}
+
+function setupWriteFile() {
+	writeFile.mockImplementation( ( fileName, data ) => {
+		readFile.mockClear();
+		readFile.mockImplementation( () => Promise.resolve( data ) );
+	} );
+}
+
+describe( 'cache file', () => {
+	beforeEach( () => {
+		jest.clearAllMocks();
+	} );
+
+	describe( 'didCacheChange', () => {
+		it( 'returns true if the existing cache value is different', async () => {
+			setCacheFile( { test: 'test1' } );
+			const result = await didCacheChange( 'test', 'nope', cacheOptions );
+			expect( result ).toBe( true );
+		} );
+		it( 'returns false if the existing cache value is the same', async () => {
+			setCacheFile( { test: 'test1' } );
+			const result = await didCacheChange(
+				'test',
+				'test1',
+				cacheOptions
+			);
+			expect( result ).toBe( false );
+		} );
+		it( 'returns true if the existing cache value does not exist', async () => {
+			expect.assertions( 2 );
+
+			setCacheFile( { howdy: 'test1' } );
+			const result = await didCacheChange( 'test', 'nope', cacheOptions );
+			expect( result ).toBe( true );
+
+			deleteCacheFile();
+			const result2 = await didCacheChange(
+				'test',
+				'nope',
+				cacheOptions
+			);
+			expect( result2 ).toBe( true );
+		} );
+	} );
+
+	describe( 'setCache', () => {
+		it( 'saves a new cache value to the file', async () => {
+			setupWriteFile();
+			await setCache( 'test', 'abc', cacheOptions );
+			const result = await getCacheFile( cacheOptions );
+			expect( result ).toEqual( { test: 'abc' } );
+		} );
+		it( 'overwrites an existing key', async () => {
+			expect.assertions( 2 );
+			setCacheFile( { test: 'abc' } );
+			const result = await getCacheFile( cacheOptions );
+			expect( result ).toEqual( { test: 'abc' } );
+
+			await setCache( 'test', '123', cacheOptions );
+			const result2 = await getCacheFile( cacheOptions );
+			expect( result2 ).toEqual( { test: '123' } );
+		} );
+		it( 'does not overwrite other keys', async () => {
+			setCacheFile( { test: 'abc' } );
+
+			await setCache( 'test2', 1234, cacheOptions );
+			const result = await getCacheFile( cacheOptions );
+			expect( result ).toEqual( { test: 'abc', test2: 1234 } );
+		} );
+	} );
+
+	describe( 'getCache', () => {
+		it( 'returns the cache value associated with the key', async () => {
+			const value = 'test1';
+			setCacheFile( { test: value } );
+			const result = await getCache( 'test', cacheOptions );
+			expect( result ).toBe( value );
+		} );
+		it( 'returns undefined if there is no existing value', async () => {
+			setCacheFile( { anotherValue: 'hello' } );
+			const result = await getCache( 'test', cacheOptions );
+			expect( result ).toBe( undefined );
+		} );
+		it( 'returns undefined if the file does not exist', async () => {
+			deleteCacheFile();
+			const result = await getCache( 'test', cacheOptions );
+			expect( result ).toBe( undefined );
+		} );
+	} );
+
+	describe( 'getCacheFile', () => {
+		it( 'returns the stored JSON data as an Object', async () => {
+			const testData = {
+				a: 'test',
+				b: 1,
+				c: true,
+				d: null,
+				e: {
+					foo: 'test2',
+				},
+			};
+			setCacheFile( testData );
+
+			const result = await getCacheFile( cacheOptions );
+			expect( result ).toEqual( testData );
+		} );
+		it( 'returns an empty object if the file does not exist', async () => {
+			deleteCacheFile();
+			const result = await getCacheFile( cacheOptions );
+			expect( result ).toEqual( {} );
+		} );
+		it( 'returns an empty object if the file is invalid', async () => {
+			readFile.mockImplementation( () => Promise.resolve( '{' ) );
+			const result = await getCacheFile( cacheOptions );
+			expect( result ).toEqual( {} );
+		} );
+	} );
+} );