How to setup Local Storage
Local 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 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.
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.
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.
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
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.
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 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.
- 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.
- 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.