PHPackages                             polyplugins/settings-class-for-wordpress - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. polyplugins/settings-class-for-wordpress

ActiveLibrary[Utility & Helpers](/categories/utility)

polyplugins/settings-class-for-wordpress
========================================

A reusable settings class for WordPress.

4.0.5(3w ago)7793GPL-3.0-or-laterPHPPHP >=7.4

Since Aug 17Pushed 3w ago1 watchersCompare

[ Source](https://github.com/PolyPlugins/Settings-Class-for-Wordpress)[ Packagist](https://packagist.org/packages/polyplugins/settings-class-for-wordpress)[ Docs](https://github.com/PolyPlugins/Settings-Class-for-Wordpress)[ RSS](/packages/polyplugins-settings-class-for-wordpress/feed)WikiDiscussions main Synced today

READMEChangelog (10)DependenciesVersions (18)Used By (0)

Settings Class for WordPress
============================

[](#settings-class-for-wordpress)

[![Demo](https://private-user-images.githubusercontent.com/85666508/481354746-f2c2ea9f-da11-43b7-9bd6-cfa8fe3457c0.gif?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3ODIxMDQ3MzcsIm5iZiI6MTc4MjEwNDQzNywicGF0aCI6Ii84NTY2NjUwOC80ODEzNTQ3NDYtZjJjMmVhOWYtZGExMS00M2I3LTliZDYtY2ZhOGZlMzQ1N2MwLmdpZj9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjA2MjIlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwNjIyVDA1MDAzN1omWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTAzYTk2Y2U2NmNmYTA1NmYyYjE4N2E5MzIyNzVhZWJiZWFmZGZmMDU5ZDVjNGUzZGM2MzBlMGM5ZjBhZmVkMzMmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JnJlc3BvbnNlLWNvbnRlbnQtdHlwZT1pbWFnZSUyRmdpZiJ9.q1llPfWzlAji5RPilzvipong6IPKbtcCaNlXYTsMFbw)](https://private-user-images.githubusercontent.com/85666508/481354746-f2c2ea9f-da11-43b7-9bd6-cfa8fe3457c0.gif?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3ODIxMDQ3MzcsIm5iZiI6MTc4MjEwNDQzNywicGF0aCI6Ii84NTY2NjUwOC80ODEzNTQ3NDYtZjJjMmVhOWYtZGExMS00M2I3LTliZDYtY2ZhOGZlMzQ1N2MwLmdpZj9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjA2MjIlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwNjIyVDA1MDAzN1omWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTAzYTk2Y2U2NmNmYTA1NmYyYjE4N2E5MzIyNzVhZWJiZWFmZGZmMDU5ZDVjNGUzZGM2MzBlMGM5ZjBhZmVkMzMmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JnJlc3BvbnNlLWNvbnRlbnQtdHlwZT1pbWFnZSUyRmdpZiJ9.q1llPfWzlAji5RPilzvipong6IPKbtcCaNlXYTsMFbw)

Our goal was to create a class that could easily be imported into projects to give easy methods to handle adding a clean and dynamic settings panel to the backend of WordPress.

Update
------

[](#update)

This project will be actively maintained again as a Composer package.

As a composer package it will make it simpler for plugin developers to include the settings class directly, without extra plugins. Any breaking changes are reserved for major releases, so updates won’t catch you off guard.

You can still use [Reusable Admin Panel](https://wordpress.org/plugins/reusable-admin-panel/) if you like, but feature development has stopped and only critical fixes will be provided. If Reusable Admin Panel introduced breaking changes, it would impact any site using it unless we maintained full backwards compatibility, which adds unnecessary complexity. We also wanted to avoid forcing users to install extra plugins just to run ours, which is why this Composer based approach was a better fit for us.

Features
--------

[](#features)

- **Developer Friendly**

    - All settings saved in a single multi-dimensional array for easier access
    - Built-in sanitization and escaping for safer data handling
    - Validation powered by [validator.js](https://github.com/validatorjs/validator.js)
    - Clear placeholders, descriptions, and help text support on fields
    - Separators for cleaner layouts
    - Extendable and namespaced for easy integration into your own plugins
- **Built-in Field Types**

    - Text, textarea (single and multi-row), password, email, URL
    - Number (with min/max/step), time, date, color picker
    - Switch toggles
    - Dropdowns (including disabled options)
    - Dropdown toggle fields (switches between grouped sets of fields)
    - Buttons with multiple actions (JS or external links)
- **Section & Navigation Controls**

    - Dynamic tab navigation with jQuery
    - Subsections within sections (with icons and labels)
    - Section "notes" with contextual alerts (success, warning, error)
- **Modern UI with Bootstrap**

    - Clean Bootstrap container layout
    - Built-in Bootstrap Icons for field helpers and navigation
    - Sidebar info helper
- **Flexible Configuration**

    - Add plugin action links and meta links directly from config
    - Permanent sidebar with configurable heading, text, and button
    - Custom CSS/JS overrides
- **Templating**

    - Choose from Default and Recharge templates

Installation
------------

[](#installation)

The easiest way to install Settings Class for WordPress is via our [Boilerplate Generator](https://www.polyplugins.com/settings-class-for-wordpress-boilerplate-generator/). Once generated you can follow the below steps:

1. Make sure you have [composer](http://getcomposer.org) installed
2. Backup WordPress
3. Copy the folder within the generated zip to your `/wp-content/plugins/` directory.
4. Inside your generated plugin folder `/wp-content/plugins/your-plugin/` run `composer install`
5. Activate the plugin
6. Visit Settings -> Your Plugin in the backend of WordPress.

You can learn more about the fields and configuration parameters via our [Documentation](https://www.polyplugins.com/docs/settings-class-for-wordpress/).

Updates
-------

[](#updates)

To update minor or patch versions, run the following after taking a backup of WordPress:

`composer update`

Within your plugin folder (`/wp-content/plugins/your-plugin/`)

Starting with v4, the class is namespaced by version (e.g. `Poly_Plugins\V4_0_5\Settings`). Multiple plugins on the same site can each bundle their own version without conflicts so the old issue where whichever class loaded first would take priority is resolved. When you update, make sure your `use` statement matches the version in your `composer.json`.

Composer will only update versions that fit the constraints defined in your composer.json, so major releases generally won't be installed automatically.

Major versions may include breaking changes, so review the release notes before updating and follow any migration instructions.

### Upgrading to v4

[](#upgrading-to-v4)

Field and section keys are now stored with underscores instead of hyphens. Previously, keys were sanitized with `sanitize_title()`, which produces URL-style slugs with hyphens. That works for slugs, but hyphens are awkward as PHP array keys and they don't match the underscore convention WordPress uses elsewhere for options and meta. Underscores also keep `get_option()` predictable as whatever you pass in (a label, a slug, or a name with spaces) is normalized to the same key every time.

If you are upgrading from v3, add something similar to your updater logic that only runs once to migrate existing settings in the database. Replace `your_settings_name` with the value from your `settings_name` config. Be sure to test it on your staging environment first before pushing live.

This migration is not built into the class. Running it automatically would require storing a version flag per plugin in the database so we know the migration has already run. We may add that in the future, but for now we want to keep the database footprint as small as possible.

```
function migrate_settings_keys_to_underscores($settings_name) {
  $settings = get_option($settings_name);

  if (!is_array($settings) || empty($settings)) {
    return;
  }

  $migrated = array();

  foreach ($settings as $section => $fields) {
    $new_section = str_replace('-', '_', $section);

    if (!is_array($fields)) {
      $migrated[$new_section] = $fields;
      continue;
    }

    $migrated[$new_section] = array();

    foreach ($fields as $name => $option) {
      $new_name = str_replace('-', '_', $name);
      $migrated[$new_section][$new_name] = $option;
    }
  }

  update_option($settings_name, $migrated);
}

// Run once on upgrade
migrate_settings_keys_to_underscores('your_settings_name');
```

We also moved the css, js, and img folders to assets folder so you will need to update any references for that as well.

Example Plugin
--------------

[](#example-plugin)

If you want barebones you can create a test-plugin.php file within a new /wp-content/plugins/test-plugin/ folder and add the below code:

```