typisttech/wp-option-store

Extending WordPress Options API, read options from places other than database, the OOP way

Maintainers

Details

github.com/typisttech/wp-option-store

Homepage

Source

Issues

Fund package maintenance!
tangrufus
typist.tech/donation
www.paypal.me/iAmTangRufus/30usd

Installs: 16 480

Dependents: 2

Suggesters: 0

Security: 0

Stars: 15

Watchers: 3

Forks: 2

0.2.0 2018-03-16 22:06 UTC

Requires

  • php: >7.1

Requires (Dev)

Suggests

GPL-2.0-or-later 115ff7cb4b5f566c89c1294fe2b68c82d62cccc2

wordpresswp

This package is auto-updated.

Last update: 2024-11-29 05:34:42 UTC

README

Packagist Packagist PHP from Packagist CircleCI codecov GitHub GitHub Sponsor Sponsor via PayPal Hire Typist Tech Twitter Follow @TangRufus

Extending WordPress Options API, read options from places other than database, the OOP way.

The Goals, or What This Package Does?

WordPress Option API only allows you get_option from database. This package is for those who not accepting the status quo.

Install

Installation should be done via composer, details of how to install composer can be found at https://getcomposer.org/.

$ composer require typisttech/wp-option-store

You should put all WP Option Store classes under your own namespace to avoid class name conflicts.

Usage

Example

use TypistTech\WPOptionStore\Factory;

// By default, the `Factory` adds 2 strategies (order matters):
//  1. ConstantStrategy
//  2. DatabaseStrategy
$filteredOptionStore = Factory::build();

// To get an option from strategies:
//  1. Read `MY_OPTION` constant
//  2. If (1) is not `null`, jump to (6)
//  3. Read from `get_option('my_option')`, the normal WordPress Options API
//  4. If (3) is not `null`, jump to (6)
//  5. We have tried all strategies, pass `null` to (6)
//  6. Pass whatever we have read (could be null) through `apply_filters('my_option', $whateverWeHaveRead);`
$filteredOptionStore->get('my_option');

// To get an option and perform type cast.
$filteredOptionStore->getBoolean('my_boolean_option');
$filteredOptionStore->getInt('my_integer_option');
$filteredOptionStore->getString('my_string_option');
$filteredOptionStore->getArray('my_array_option');

ConstantStrategy

This strategy gets options from PHP constants.

define('MY_OPTION', 'abc123');

$strategy = new ConstantStrategy();

$value1 = $strategy->get('my_option');
// $value1 === 'abc123';

$value2 = $strategy->get('my_non_exist_option');
// $value2 === null;

DatabaseStrategy

This strategy gets options from WordPress Options API.

update_option('my_option', 'abc123');

$strategy = new DatabaseStrategy();

$value1 = $strategy->get('my_option');
// $value1 === 'abc123';

$value2 = $strategy->get('my_non_exist_option');
// $value2 === null;

Important: An unset value should be null instead of WordPress' default false.

OptionStore

This class gets option values from strategies.

__construct(StrategyInterface ...$strategies)

OptionStore constructor.

  • @param StrategyInterface[] ...$strategies Strategies that get option values.
$databaseStrategy = new DatabaseStrategy();
$constantStrategy = new ConstantStrategy();
$optionStore = new OptionStore($constantStrategy, $databaseStrategy);

Note: Strategies order matters!

get(string $optionName)

Get an option value.

  • @param string $optionName Name of option to retrieve.
// It returns the first non-null value from strategies.
define('MY_OPTION', 'abc');
update_option('my_option', 'xyz');

$value1 = $optionStore->get('my_option');
// $value1 === 'abc';

// It returns `null` when option not found.
$value2 = $optionStore->get('my_non_exist_option');
// $value2 === null;

Type casting

OptionStore provides several helper methods for type casting.

$optionStore->getBoolean('my_boolean_option');
$optionStore->getInt('my_integer_option');
$optionStore->getString('my_string_option');
$optionStore->getArray('my_array_option');

FilteredOptionStore

This is a subclass of OptionStore.

get(string $optionName)

Get an option value.

  • @param string $optionName Name of option to retrieve.
// It returns the first non-null value from strategies,
// and applies filters.
define('MY_OPTION', 'abc');
update_option('my_option', 'xyz');

add_filter('my_option', function($value) {
    return 'filtered ' . $value;
});

$value = $filteredOptionStore->get('my_option');
// $value === 'filtered abc';

Note: Filters are applied before type casting.

Factory

Factory is a helper class to reduce boilerplate code for those who use default strategies. If you use a custom strategy or reorder the strategies, don't use this class.

build(): FilteredOptionStore

$filteredOptionStore = Factory::build();

Frequently Asked Questions

Can I implement my own strategy classes?

Of course! Just implements the StrategyInterface.

Take a look at classes ConstantStrategy and DatabaseStrategy as well as their tests for example implementations of StrategyInterface.

If you'd like to create a open-source package to do this to help others, open a new issue to let us know, we'd love to help you with it.

Can I change the order of the strategies?

Why not? Don't use Factory.

// Order matters!
$optionStore = new FilteredOptionStore(
    new MyStrategy1(),
    new MyStrategy2(),
    new MyStrategy3(),
);

Is this a plugin?

No, this is a package that should be part of your plugin.

What to do when wp.org plugin team tell me to clean up the vendor folder?

Re-install packages via the following command. This package exports only necessary files to dist.

$ composer install --no-dev --prefer-dist --optimize-autoloader

Can two different plugins use this package at the same time?

Yes, if put all WP Option Store classes under your own namespace to avoid class name conflicts.

Do you have real life examples that use this package?

Here you go:

Add your own plugin here

Will you add support for older PHP versions?

Never! This plugin will only work on actively supported PHP versions.

Don't use it on end of life or security fixes only PHP versions.

It looks awesome. Where can I find some more goodies like this?

Where can I give ⭐⭐⭐⭐⭐ reviews?

Thanks! Glad you like it. It's important to let my know somebody is using this project. Since this is not hosted on wordpress.org, please consider:

Sponsoring ❤️

Love WP Option Store? Help me maintain it, a sponsorship here can help with it.

GitHub Sponsors Matching Fund

Do you know GitHub is going to match your sponsorship?

Sponsor now via GitHub to double your greatness.

Why don't you hire me?

Ready to take freelance WordPress jobs. Contact me via the contact form here or, via email info@typist.tech

Want to help in other way? Want to be a sponsor?

Contact: Tang Rufus

Running the Tests

Run the tests:

$ composer test
$ composer style:check

Feedback

Please provide feedback! We want to make this project useful in as many projects as possible. Please submit an issue and point out what you do and don't like, or fork the project and make suggestions. No issue is too small.

Change log

Please see CHANGELOG for more information on what has changed recently.

Security

If you discover any security related issues, please email wp-option-store@typist.tech instead of using the issue tracker.

Credits

WP Option Store is a Typist Tech project and maintained by Tang Rufus, freelance developer for hire.

Full list of contributors can be found here.

License

The MIT License (MIT). Please see License File for more information.