How to setup Local Storage

Overview

Local storage is a feature that is introduced since Admin Columns Pro 5.1 that allows you to store column settings on the file system in PHP files. This allows you to ship and migrate column settings easily between environments and even store them in a version control system (VCS) to share with your fellow developers. This feature can be enabled by the usage of custom hooks.

We aimed to build a solution that is both easy to use but also flexible enough for developers to set up a more fine-grained solution. If you’re just looking for an easy way to switch between local storage and the database based on a development- or live environment, we suggest having a look at the simple setup section. If you need a more fine-grained approach when you want to store column settings in different directories, then have a look at the advanced setup section.

Tip Local Storage is available since Admin Columns Pro 5.1

Simple setup

The simple setup allows you to start using local storage with two simple hooks. By using the acp/storage/file/directory hook, you can set the storage directory to a folder on your file system. Only a single folder can be active at the time by using this hook.

add_filter( 'acp/storage/file/directory', function() {
	// Use a writable path, directory will be created for you
	return get_stylesheet_directory() . '/acp-settings';
} );

Every time you save your column settings, a new PHP file will be created in the provided folder. Once this hook is loaded, all column settings will be loaded from your directory. Any settings in your database will be loaded as read-only but can be made editable by creating a new copy, or by using our migration tool.

When moving to a live-environment, you probably want your local file settings to be loaded as read-only and make the database the default storage engine again. The following hook allows you to easily switch between read-only storage or writable storage.

add_filter( 'acp/storage/file/directory/writable', '__return_false' );

Advanced Setup

If you need more control over where to store specific column settings, you can use the advanced setup. Using this method, allows you to make use of rules to determine the location where the column settings should be stored, including the database.

use AC\ListScreenRepository\Storage\ListScreenRepositoryFactory;
use AC\ListScreenRepository\Rules;
use AC\ListScreenRepository\Rule;

add_filter( 'acp/storage/repositories', function( array $repositories, ListScreenRepositoryFactory $factory ) {
	// 1. Use something like $_ENV or a defined variable that you can configure
	$writable = defined( 'MY_CONFIG_PARAMETER' ) && MY_CONFIG_PARAMETER;

	// 2. Add rules to target individual list tables.

	// Defaults to Rules::MATCH_ANY added here for clarity, other option is Rules::MATCH_ALL
	$rules = new Rules( Rules::MATCH_ANY );
	$rules->add_rule( new Rule\EqualType( 'my_custom_post_type' ) );

	// 3. Register your repository to the stack
	$repositories['my_plugin_slug'] = $factory->create(
			get_stylesheet_directory() . '/acp-woocommerce-column-settings',
			$writable,
			$rules
	);

	return $repositories;
}, 10, 2 );

In this example, only column settings for the WooCommerce product and order overview will be saved in a custom folder acp-woocommerce-column-settings inside the loaded theme. This folder is writable at this moment, but should probably be set to readable on a live environment.

This hook can be used multiple times to register multiple file storage repositories and the priority on which you add repositories to the stack matters. The last repository that was added will be used as the main storage repository. Please notice that only one repository will store the column settings. With the use of Rules, you can choose which of the repositories it should be, keeping the priority in mind.

Using Rules

Rules are used to determine whether the columns settings should be saved in a specific location or not. This is only useful when you have multiple locations where settings can be stored, for example when you use different folders to store settings. Rules can only be used in an advanced setup.

The first step to use rules is to create new Rules container and set if you want to match all or any of the rules that it contains: new AC\ListScreenRepository\Rules( 'all' )

The next step is to create new rules for the container. We included two rule classes that can be used to include settings for a specific overview page or for a specific column set based on its ID.

AC\ListScreenRepository\Rule\EqualId( $layout_id )
AC\ListScreenRepository\Rule\EqualType( $overview_key )

The final step is to add the rules container to the newly created repository. See the example in the advanced setup on how this can be done.

Since the columns settings will only be stored in a single repository, the priority of which you use to register the repositories matters.

Migrate settings to local storage

When you decide to work with local storage and still have some column settings in the database that you want to move to local storage, you have the following options to migrate your data from data to file.

  1. The first option is to open the column settings that are in the database and create a copy by clicking the + Add Column Set button. Once you have a copy, you can remove the old one from the database.
  2. Use our migration script that migrates all database settings to your file system once.

The following hook migrates all the column settings that are in the database to your file system, removing all migrated settings from the database afterward. Once the migration is successful, you can remove the snippet from your installation to prevent it from keep trying to migrate the settings.

add_filter( 'acp/storage/file/directory/migrate', '__return_true' );