Version 11 to 12

This migration guide contains migration instructions for:

• eightshift/boilerplate - 11+ --> 12.0.0
• eightshift/boilerplate-plugin - 4+ --> 5.0.0
• eightshift/frontend-libs - 11+ --> 12.0.0
• eightshift/libs - 7+ --> 8.0.0

This release contains a couple of breaking changes! Check the list below for details about changes that will have to be made.

Also, a couple of changes are optional, but recommended.

The major update on this release is the "cache" loading functionality and refactoring of helpers.

Important changes

This version was focused on improving speed and performance of the project and we set the minimum PHP version to 8.2 so if you project is using older PHP version you should update it before updating the setup.

Setup scripts

We changed the setup script repository and flow so if you are creating a new project you should use the new setup script.

Theme:

// Old setup script
npx create-wp-project

// New setup script
npx eightshift-create theme

Plugin:

// Old setup script
npx create-wp-project plugin

// New setup script
npx eightshift-create plugin

Required changes

The following changes are required to update your project to the latest version.

Remove Manifest class

Migration time: ~1min.

The Manifest class has been removed. If you are using this class in your project, please remove it.

Update Enqueue classes

Migration time: ~5min.

1. If you're using EnqueueTheme, EnqueueBlocks or EnqueueAdmin classes, remove the $this->manifest dependency from the constructor.

2. If you're using the $this->manifest->getAssetsManifestItem method in your project, replace it with the new Helpers::getAsset method.

3. If you're using the getBlockFrontentScriptHandle method, rename it to getBlockFrontendScriptHandle.

4. If you're using a custom wp_register_script, update the function to use the new Helpers::getAsset method and update the script handle if using WordPress 6.3+.

Add the Cache class

Migration time: ~5min.

1. Run the wp boilerplate create manifest-cache CLI command to add the cache functionality to your project.

2. Open the functions.php (or <plugin-name>.php) file and add the following code before the Main class initialization:

   • for themes
   • for plugins

if (\class_exists(ManifestCache::class)) {
	(new ManifestCache())->setAllCache();
}

Replace the ManifestItem filter with the Asset helper

Migration time: ~2min.

If you're using the apply_filters(Manifest::MANIFEST_ITEM, '<key>') filter in your project, replace it with the Helpers::getAsset('<key>') helper.

Update helpers

Migration time: ~5min.

1. Find all instances of the outputCssVariablesGlobal(array $globalManifest = []) function and remove the global settings variable, eg. outputCssVariablesGlobal().

2. Find all instances of the outputCssVariables(array $attributes, array $manifest, string $unique, array $globalManifest = [], string $customSelector = '') function and remove the global settings variable, eg. outputCssVariables(array $attributes, array $manifest, string $unique, string $customSelector = '').

Replace all renderPartial methods

Migration time: ~15min.

Find all instances of the renderPartial method and replace it with the render method.

Before:

echo Components::renderPartial(
	'component',
	'utils',
	'debug-field-details',
	[
		'name' => Components::checkAttr('fieldName', $attributes, $manifest),
	]
);

After:

echo Components::render(
	'debug-field-details',
	[
		'name' => Components::checkAttr('fieldName', $attributes, $manifest),
	],
	'components',
	false,
	'utils/partials'
);

Update the render method

Migration time: ~10min.

Find all instances of the render method to which more than 2 arguments are passed and update the method call to match the new signature.

Before:

return Components::render(
	'form',
	Components::props('form', [], $formProps),
	'',
	true
);

After:

return Components::render(
	'form',
	Components::props('form', [], $formProps),
	'components',
	true
);

Update the wrapper and all blocks with innerBlockContent

Migration time: ~15min.

1. Find all instances of the $this->renderWrapperView method in your project and replace it with echo $renderContent method.
2. Find all instances of the $innerBlockContent variable and replace it with echo $renderContent. (applies to the wrapper, and blocks using inner blocks, like Group, Columns, ...)
3. Remove the wrapperManualContent parameter from all wrapper instances. For more details, check the example

Before:

$this->renderWrapperView(
	$templatePath,
	$attributes,
	$innerBlockContent
);

After:

echo $renderContent;

Replace the Components helper

Migration time: ~5min.

Helper functions from the Components class are renamed, and will be deprecated in the next version. They are now located in the Helpers class. Functions were not changed beyond the rename (except the ones mentioned above).

The fastest way to change them is to search and replace Components:: with Helpers::, and EightshiftLibs\Helpers\Components with EightshiftLibs\Helpers\Helpers in the project.

Fix Custom Post Type or Taxonomy registration

Migration time: ~5min.

We removed getGeneratedLabels helper so you should update your custom post type or taxonomy registration.

You can check the custom post type example or custom taxonomy example from the boilerplate.

Update webpack config

Migration time: ~2min.

We have removed BrowserSync from the project so you should update your webpack config.

Before:

const projectConfig = {
	config: {
		projectDir: __dirname, // Current project directory absolute path.
		projectUrl: 'eightshift.com', // Used for providing browsersync functionality.
		projectPath: 'wp-content/plugins/eightshift-forms', // Project path relative to project root.
		useSsl: true, // Whether to use https or http.
	},
};

After:

const projectConfig = {
	config: {
		projectDir: __dirname, // Current project directory absolute path.
		projectPath: 'wp-content/plugins/eightshift-forms', // Project path relative to project root.
	},
};

Replace Imposter with Strauss

Migration time: ~10min.

We have removed Imposter and replaced it with Strauss for prefixing namespaces.

1. Add /vendor-prefixed to your .gitignore file
2. Add strauss.phar to your theme root. You can get it here
3. Make the following changes in your composer.json file:

• remove typisttech/imposter-plugin
• add the following in the scripts section:

"prefix-namespaces": [
	"@php strauss.phar",
	"composer dump-autoload"
],
"post-install-cmd": [
	"@php strauss.phar",
	"composer dump-autoload"
],
"post-update-cmd": [
	"@php strauss.phar",
	"composer dump-autoload"
]

• remove imposter from the extra section and add the following:

"strauss": {
	"namespace_prefix": "ProjectNameVendor",
	"exclude_from_prefix": {
		"file_patterns": ["/Example.php$/"]
	}
}

4. Update functions.php file

/**
 * Bailout, if the theme is not loaded via Composer.
 */
if (!\file_exists(__DIR__ . '/vendor/autoload.php')) {
	return;
}

/**
 * Require the Composer autoloader.
 */
$loader = require __DIR__ . '/vendor/autoload.php';

/**
 * Require the Composer autoloader for the prefixed libraries.
 */
if (\file_exists(__DIR__ . '/vendor-prefixed/autoload.php')) {
	require __DIR__ . '/vendor-prefixed/autoload.php';
}

5. Add the following line in your phpcs.xml.dist:

<exclude-pattern>*/vendor-prefixed/*</exclude-pattern>

6. Add the following line in your phpstan.neon.dist in boostrapFiles section:

- vendor-prefixed/autoload.php

Once you have made these changes, remove the vendor folder and run composer install.

Update ESLint config

Migration time: ~10min.

Depending on the state the project is in, you might need to allocate some time for fixing errors and warnings after updating the coding standards.

ESLint configuration has been updated in Frontend Libs 12 and a new build config was added.

To implement the changes, follow these steps:

1. Delete the .eslintrc.js and .eslintignore files from the theme root (if they exist)

2. Add eslint.config.mjs file to the theme root with the following content:

import config from '@eightshift/frontend-libs/linters/eslint.config.mjs';

3. Add a .swcrc file to theme root, the file and its contents can be found here.

4. Make sure the project is using NodeJS version 20 (or newer) both in development and production environments.