How to setup File Storage

File storage 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 file 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.

Simple setup

The simple setup allows you to start using file 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.

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 script.

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.

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.

In this example, only column settings for the WooCommerce product and order overview will be saved in a custom folder  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 list table based on the List Screen Key. Or for a specific column set based on the List Screen ID.

AC\ListScreenRepository\Rule\EqualId( $list_screen_id )
AC\ListScreenRepository\Rule\EqualType( $list_screen_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 column settings will only be stored in a single repository, the priority of which you use to register the repositories matters.

Migrate settings to file storage

When you decide to work with file storage and still have some column settings in the database that you want to move to file 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.

Usage example

In this example, we store our column settings in three different folders. One folder for each post type. And a folder for the users.

The column settings are stored in their respective folder:
The post post type columns will be stored in a theme folder called column-settings-post.
The page post type columns will be stored in a plugin folder called column-settings-page.
The user columns will be stored in a theme folder called column-settings-users.