rails-settings-cached 0.7.2 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eba484df56932a47956229096367746c7ffdeb979c61e2f9bcadbad09c0fd0a6
-  data.tar.gz: 73ce168eead5d2627323f5944d2c7ee8629c85df602e3b432afdcb05ee29247a
+  metadata.gz: d45081eacc51de459cd0bc48469430474cd561386e924b40996bd5f66c1299e5
+  data.tar.gz: 485e2df525a6d3b66dfed0c0b5935aa8134b13ae0b0528d1fae536e5b19e4ae2
 SHA512:
-  metadata.gz: 26f409db40e28e6febeba959cc27a127d6caa531d66974792efc7f1e4cf7ee8d0ca1e21130d6c874937ed645b24929e44094fd351add876f5471c0f37bf4a28d
-  data.tar.gz: 02d122fcc7346aac33f12cf470462bb283602d277cd2fc09c1cba40c4d597ccd4e65527572e7ebd523535c7fe92bcf948a99ead45f1f3f6dd7420ba95703d2b0
+  metadata.gz: 6651da35fec5737f76192ec01f0980ea45a85c69efb768c22edbce29b490f29dfa2498798b5af6d45a126955a3fe72bf2fa1ae76bd249237b83f408f7bba72c4
+  data.tar.gz: b96670e501b9c5aff237b02fd2da2560b654dd2835322b2e64e28679e3edf646ee940f2f2ffe69bfa7d851732ac4844bb47b01e292f4ef4b5f04e587977f8c21

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2019 Jason Lee
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOa AND
+NONINFRINGEMENT. IN NO EVENT SaALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,284 +1,454 @@
 # Rails Settings Cached
 
-This is improved from [rails-settings](https://github.com/ledermann/rails-settings),
-added caching for all settings. Settings is a plugin that makes managing a table of
-global key, value pairs easy. Think of it like a global Hash stored in your database,
-that uses simple ActiveRecord like methods for manipulation. Keep track of any global
-setting that you dont want to hard code into your rails app. You can store any kind
-of object. Strings, numbers, arrays, or any object.
+The best solution for store global settings in Rails applications.
 
-## Status
+This gem will make managing a table of а global key, value pairs easy. Think of it like a global Hash stored in your database, that uses simple ActiveRecord like methods for manipulation. Keep track of any global setting that you don't want to hard code into your rails app.
 
-[![Gem Version](https://badge.fury.io/rb/rails-settings-cached.svg)](https://rubygems.org/gems/rails-settings-cached) [![CI Status](https://travis-ci.org/huacnlee/rails-settings-cached.svg)](http://travis-ci.org/huacnlee/rails-settings-cached) [![Code Climate](https://codeclimate.com/github/huacnlee/rails-settings-cached/badges/gpa.svg)](https://codeclimate.com/github/huacnlee/rails-settings-cached) [![codecov.io](https://codecov.io/github/huacnlee/rails-settings-cached/coverage.svg?branch=master)](https://codecov.io/github/huacnlee/rails-settings-cached?branch=master)
+You can store any kind of object. Strings, numbers, arrays, booleans, or any object.
 
-## Setup
+[![Gem Version](https://badge.fury.io/rb/rails-settings-cached.svg)](https://rubygems.org/gems/rails-settings-cached) [![build](https://github.com/huacnlee/rails-settings-cached/workflows/build/badge.svg)](https://github.com/huacnlee/rails-settings-cached/actions?query=workflow%3Abuild) [![codecov.io](https://codecov.io/github/huacnlee/rails-settings-cached/coverage.svg?branch=master)](https://codecov.io/github/huacnlee/rails-settings-cached?branch=master)
 
-Edit your Gemfile:
-
-```ruby
-gem "rails-settings-cached"
-```
+## Installation
 
-Generate your settings:
+Edit your Gemfile:
 
 ```bash
-$ rails g settings:install
+$ bundle add rails-settings-cached
 ```
 
-If you want custom model name:
+Generate your settings:
 
 ```bash
 $ rails g settings:install
-```
 
-Or use a custom name:
-
-```bash
-$ rails g settings:install SiteConfig
+# Or use a custom name:
+$ rails g settings:install AppConfig
 ```
 
 You will get `app/models/setting.rb`
 
 ```rb
 class Setting < RailsSettings::Base
-  source Rails.root.join("config/app.yml")
   # cache_prefix { "v1" }
+
+  scope :application do
+    field :app_name, default: "Rails Settings", validates: { presence: true, length: { in: 2..20 } }
+    field :host, default: "http://example.com", readonly: true
+    field :default_locale, default: "zh-CN", validates: { presence: true, inclusion: { in: %w[zh-CN en jp] } }, option_values: %w[en zh-CN]
+    field :admin_emails, type: :array, default: %w[admin@rubyonrails.org]
+
+    # lambda default value
+    field :welcome_message, type: :string, default: -> { "welcome to #{self.app_name}" }, validates: { length: { maximum: 255 } }
+    # Override array separator, default: /[\n,]/ split with \n or comma.
+    field :tips, type: :array, separator: /[\n]+/
+  end
+
+  scope :limits do
+    field :user_limits, type: :integer, default: 20
+    field :exchange_rate, type: :float, default: 0.123
+    field :captcha_enable, type: :boolean, default: true, group: :limits
+  end
+
+  field :notification_options, type: :hash, default: {
+    send_all: true,
+    logging: true,
+    sender_email: "foo@bar.com"
+  }, group: :advanced
+
+  field :readonly_item, type: :integer, default: 100, readonly: true
 end
 ```
 
+You must use the `field` method to statement the setting keys, otherwise you can't use it.
+
 Now just put that migration in the database with:
 
 ```bash
-rake db:migrate
+$ rails db:migrate
 ```
 
 ## Usage
 
-The syntax is easy.  First, lets create some settings to keep track of:
+The syntax is easy. First, let's create some settings to keep track of:
 
 ```ruby
-Setting.admin_password = 'supersecret'
-Setting.date_format    = '%m %d, %Y'
-Setting.cocktails      = ['Martini', 'Screwdriver', 'White Russian']
-Setting.foo            = 123
-Setting.credentials    = { :username => 'tom', :password => 'secret' }
+irb > Setting.host
+"http://example.com"
+irb > Setting.app_name
+"Rails Settings"
+irb > Setting.app_name = "Rails Settings Cached"
+irb > Setting.app_name
+"Rails Settings Cached"
+
+irb > Setting.user_limits
+20
+irb > Setting.user_limits = "30"
+irb > Setting.user_limits
+30
+irb > Setting.user_limits = 45
+irb > Setting.user_limits
+45
+
+irb > Setting.captcha_enable
+1
+irb > Setting.captcha_enable?
+true
+irb > Setting.captcha_enable = "0"
+irb > Setting.captcha_enable
+false
+irb > Setting.captcha_enable = "1"
+irb > Setting.captcha_enable
+true
+irb > Setting.captcha_enable = "false"
+irb > Setting.captcha_enable
+false
+irb > Setting.captcha_enable = "true"
+irb > Setting.captcha_enable
+true
+irb > Setting.captcha_enable?
+true
+
+irb > Setting.admin_emails
+["admin@rubyonrails.org"]
+irb > Setting.admin_emails = %w[foo@bar.com bar@dar.com]
+irb > Setting.admin_emails
+["foo@bar.com", "bar@dar.com"]
+irb > Setting.admin_emails = "huacnlee@gmail.com,admin@admin.com\nadmin@rubyonrails.org"
+irb > Setting.admin_emails
+["huacnlee@gmail.com", "admin@admin.com", "admin@rubyonrails.org"]
+
+irb > Setting.notification_options
+{
+  send_all: true,
+  logging: true,
+  sender_email: "foo@bar.com"
+}
+irb > Setting.notification_options = {
+  sender_email: "notice@rubyonrails.org"
+}
+irb > Setting.notification_options
+{
+  sender_email: "notice@rubyonrails.org"
+}
 ```
 
-Now lets read them back:
+### Get defined fields
 
-```ruby
-Setting.foo            # returns 123
-```
+> version 2.3+
 
-Changing an existing setting is the same as creating a new setting:
-
-```ruby
-Setting.foo = 'super duper bar'
+```rb
+# Get all keys
+Setting.keys
+=> ["app_name", "host", "default_locale", "readonly_item"]
+
+# Get editable keys
+Settng.editable_keys
+=> ["app_name", "default_locale"]
+
+# Get readonly keys
+Setting.readonly_keys
+=> ["host", "readonly_item"]
+
+# Get options of field
+Setting.get_field("host")
+=> { scope: :application, key: "host", type: :string, default: "http://example.com", readonly: true }
+Setting.get_field("app_name")
+=> { scope: :application, key: "app_name", type: :string, default: "Rails Settings", readonly: false }
+Setting.get_field(:user_limits)
+=> { scope: :limits, key: "user_limits", type: :integer, default: 20, readonly: false }
 ```
 
-Decide you dont want to track a particular setting anymore?
-
-```ruby
-Setting.destroy :foo
-Setting.foo            # returns nil
-```
+#### Get All defined fields
 
-Want a list of all the settings?
-```ruby
-Setting.get_all
-```
+> version 2.7.0+
 
-You need name spaces and want a list of settings for a give name space? Just choose your prefered named space delimiter and use `Setting.get_all` (`Settings.all` for # Rails 3.x and 4.0.x) like this:
+You can use `defined_fields` method to get all defined fields in Setting.
 
-```ruby
-Setting['preferences.color'] = :blue
-Setting['preferences.size'] = :large
-Setting['license.key'] = 'ABC-DEF'
-# Rails 4.1.x
-Setting.get_all('preferences.')
-# Rails 3.x and 4.0.x
-Setting.all('preferences.')
-# returns { 'preferences.color' => :blue, 'preferences.size' => :large }
+```rb
+# Get editable fields and group by scope
+editable_fields = Setting.defined_fields
+  .select { |field| !field[:readonly] }
+  .group_by { |field| field[:scope] }
 ```
 
-## Extend a model
+## Validations
 
-Settings may be bound to any existing ActiveRecord object. Define this association like this:
-Notice! is not do caching in this version.
+You can use `validates` options to special the [Rails Validation](https://api.rubyonrails.org/classes/ActiveModel/Validations/ClassMethods.html#method-i-validates) for fields.
 
-```ruby
-class User < ActiveRecord::Base
-  include RailsSettings::Extend
+```rb
+class Setting < RailsSettings::Base
+  # cache_prefix { "v1" }
+  field :app_name, default: "Rails Settings", validates: { presence: true, length: { in: 2..20 } }
+  field :default_locale, default: "zh-CN", validates: { presence: true, inclusion: { in: %w[zh-CN en jp], message: "is not included in [zh-CN, en, jp]" } }
 end
 ```
 
-Then you can set/get a setting for a given user instance just by doing this:
+Now validate will work on record save:
 
-```ruby
-user = User.find(123)
-user.settings.color = :red
-user.settings.color # returns :red
-user.settings.get_all
-# { "color" => :red }
+```rb
+irb> Setting.app_name = ""
+ActiveRecord::RecordInvalid: (Validation failed: App name can't be blank)
+irb> Setting.app_name = "Rails Settings"
+"Rails Settings"
+irb> Setting.default_locale = "zh-TW"
+ActiveRecord::RecordInvalid: (Validation failed: Default locale is not included in [zh-CN, en, jp])
+irb> Setting.default_locale = "en"
+"en"
 ```
 
-If you want to find users having or not having some settings, there are named scopes for this:
+Validate by `save` / `valid?` method:
 
-```ruby
-User.with_settings
-# => returns a scope of users having any setting
+```rb
 
-User.with_settings_for('color')
-# => returns a scope of users having a 'color' setting
+setting = Setting.find_or_initialize_by(var: :app_name)
+setting.value = ""
+setting.valid?
+# => false
+setting.errors.full_messages
+# => ["App name can't be blank", "App name too short (minimum is 2 characters)"]
+
+setting = Setting.find_or_initialize_by(var: :default_locale)
+setting.value = "zh-TW"
+setting.save
+# => false
+setting.errors.full_messages
+# => ["Default locale is not included in [zh-CN, en, jp]"]
+setting.value = "en"
+setting.valid?
+# => true
+```
 
-User.without_settings
-# returns a scope of users having no setting at all (means user.settings.get_all == {})
+## Use Setting in Rails initializing:
 
-User.without_settings('color')
-# returns a scope of users having no 'color' setting (means user.settings.color == nil)
+In `version 2.3+` you can use Setting before Rails is initialized.
+
+For example `config/initializers/devise.rb`
+
+```rb
+Devise.setup do |config|
+  if Setting.omniauth_google_client_id.present?
+    config.omniauth :google_oauth2, Setting.omniauth_google_client_id, Setting.omniauth_google_client_secret
+  end
+end
 ```
 
-## Default settings
+```rb
+class Setting < RailsSettings::Base
+  field :omniauth_google_client_id, default: ENV["OMNIAUTH_GOOGLE_CLIENT_ID"]
+  field :omniauth_google_client_secret, default: ENV["OMNIAUTH_GOOGLE_CLIENT_SECRET"]
+end
+```
 
-Sometimes you may want define default settings.
+## Readonly field
 
-RailsSettings has generate a config YAML file in:
+You may also want use Setting before Rails initialize:
 
-```yml
-# config/app.yml
-defaults: &defaults
-  github_token: "123456"
-  twitter_token: "<%= ENV["TWITTER_TOKEN"] %>"
-  foo:
-    bar: "Foo bar"
+```
+config/environments/*.rb
+```
 
-development:
-  <<: *defaults
+If you want do that do that, the setting field must has `readonly: true`.
 
-test:
-  <<: *defaults
+For example:
 
-production:
-  <<: *defaults
+```rb
+class Setting < RailsSettings::Base
+  field :mailer_provider, default: (ENV["mailer_provider"] || "smtp"), readonly: true
+  field :mailer_options, type: :hash, readonly: true, default: {
+    address: ENV["mailer_options.address"],
+    port: ENV["mailer_options.port"],
+    domain: ENV["mailer_options.domain"],
+    user_name: ENV["mailer_options.user_name"],
+    password: ENV["mailer_options.password"],
+    authentication: ENV["mailer_options.authentication"] || "login",
+    enable_starttls_auto: ENV["mailer_options.enable_starttls_auto"]
+  }
+end
 ```
 
-And you can use by `Setting` model:
+config/environments/production.rb
 
-```
-Setting.github_token
-=> "123456"
-Setting.github_token = "654321"
-# Save into database.
-Setting.github_token
-# Read from databae / caching.
-=> "654321"
-Setting['foo.bar']
-=> 'Foo bar'
-```
+```rb
+# You must require_relative directly in Rails 6.1+ in config/environments/production.rb
+require_relative "../../app/models/setting"
 
-NOTE: YAML setting it also under the cache scope, when you restart Rails application, cache will expire,
-      so when you want change default config, you need restart Rails application server.
+Rails.application.configure do
+  config.action_mailer.delivery_method = :smtp
+  config.action_mailer.smtp_settings = Setting.mailer_options.deep_symbolize_keys
+end
+```
 
-### Caching flow:
+## Caching flow:
 
 ```
-Setting.foo -> Check Cache -> Exist - Write Cache -> Return
-                   |
-                Check DB -> Exist -> Write Cache -> Return
+Setting.host -> Check Cache -> Exist - Get value of key for cache -> Return
                    |
-               Check Default -> Exist -> Write Cache -> Return
+                Fetch all key and values from DB -> Write Cache -> Get value of key for cache -> return
                    |
-               Return nil
+                Return default value or nil
 ```
 
+In each Setting keys call, we will load the cache/db and save in [ActiveSupport::CurrentAttributes](https://api.rubyonrails.org/classes/ActiveSupport/CurrentAttributes.html) to avoid hit cache/db.
+
+Each key update will expire the cache, so do not add some frequent update key.
+
 ## Change cache key
 
-When `config/app.yml` has changed, you may need change the cache prefix to expires caches.
+Some times you may need to force update cache, now you can use `cache_prefix`
 
 ```ruby
 class Setting < RailsSettings::Base
-  cache_prefix { 'you-prefix' }
+  cache_prefix { "you-prefix" }
   ...
 end
 ```
 
------
+In testing, you need add `Setting.clear_cache` for each Test case:
+
+```rb
+class ActiveSupport::TestCase
+  teardown do
+    Setting.clear_cache
+  end
+end
+```
+
+---
 
-## How to create a list, form to manage Settings?
+## How to manage Settings in the admin interface?
 
-If you want create an admin interface to editing the Settings, you can try methods in follow:
+If you want to create an admin interface to editing the Settings, you can try methods in following:
 
 config/routes.rb
 
 ```rb
 namespace :admin do
-  resources :settings
+  resource :settings
 end
 ```
 
-
 app/controllers/admin/settings_controller.rb
 
 ```rb
 module Admin
   class SettingsController < ApplicationController
-    before_action :get_setting, only: [:edit, :update]
-
-    def index
-      @settings = Setting.get_all
-    end
+    def create
+      @errors = ActiveModel::Errors.new
+      setting_params.keys.each do |key|
+        next if setting_params[key].nil?
+
+        setting = Setting.new(var: key)
+        setting.value = setting_params[key].strip
+        unless setting.valid?
+          @errors.merge!(setting.errors)
+        end
+      end
 
-    def edit
-    end
+      if @errors.any?
+        render :new
+      end
 
-    def update
-      if @setting.value != params[:setting][:value]
-        @setting.value = params[:setting][:value]
-        @setting.save
-        redirect_to admin_settings_path, notice: 'Setting has updated.'
-      else
-        redirect_to admin_settings_path
+      setting_params.keys.each do |key|
+        Setting.send("#{key}=", setting_params[key].strip) unless setting_params[key].nil?
       end
-    end
 
-    def get_setting
-      @setting = Setting.find_by(var: params[:id]) || Setting.new(var: params[:id])
+      redirect_to admin_settings_path, notice: "Setting was successfully updated."
     end
+
+    private
+      def setting_params
+        params.require(:setting).permit(:host, :user_limits, :admin_emails,
+          :captcha_enable, :notification_options)
+      end
   end
 end
 ```
 
-app/views/admin/settings/index.html.erb
+app/views/admin/settings/show.html.erb
 
 ```erb
-<table>
-  <tr>
-    <th>Key</th>
-    <th></th>
-  </tr>
-  <% @settings.each_key do |key| %>
-  <tr>
-    <td><%= key %></td>
-    <td><%= link_to 'edit', edit_admin_setting_path(key) %></td>
-  </tr>
+<%= form_for(Setting.new, url: admin_settings_path) do |f| %>
+  <% if @errors.any? %>
+    <div class="alert alert-block alert-danger">
+      <ul>
+        <% @errors.full_messages.each do |msg| %>
+        <li><%= msg %></li>
+        <% end %>
+      </ul>
+    </div>
   <% end %>
-</table>
-```
-
-app/views/admin/settings/edit.html.erb
 
-```erb
-<%= form_for(@setting, url: admin_setting_path(@setting.var), method: 'patch') do |f| %>
-  <label><%= @setting.var %></label>
-  <%= f.text_area :value, rows: 10 %>
-  <%= f.submit %>
+  <div class="form-group">
+    <label class="control-label">Host</label>
+    <%= f.text_field :host, value: Setting.host, class: "form-control", placeholder: "http://localhost"  %>
+  </div>
+
+  <div class="form-group form-checkbox">
+    <label>
+      <%= f.check_box :captcha_enable, checked: Setting.captcha_enable? %>
+      Enable/Disable Captcha
+    </label>
+  </div>
+
+  <div class="form-group">
+    <label class="control-label">Admin Emails</label>
+    <%= f.text_area :admin_emails, value: Setting.admin_emails.join("\n"), class: "form-control" %>
+  </div>
+
+  <div class="form-group">
+    <label class="control-label">Notification options</label>
+    <%= f.text_area :notification_options, value: YAML.dump(Setting.notification_options), class: "form-control", style: "height: 180px;"  %>
+    <div class="form-text">
+      Use YAML format to config the SMTP_html
+    </div>
+  </div>
+
+  <div>
+    <%= f.submit 'Update Settings' %>
+  </div>
 <% end %>
 ```
 
-Also you may use [rails-settings-ui](https://github.com/accessd/rails-settings-ui) gem
-for building ready to using interface with validations,
-or [activeadmin_settings_cached](https://github.com/artofhuman/activeadmin_settings_cached) gem if you use [activeadmin](https://github.com/activeadmin/activeadmin).
+## Scoped Settings
 
-## Use case:
+> 🚨 BREAK CHANGES WARNING:
+> rails-settings-cached 2.x has redesigned the API, the new version will compatible with the stored setting values by an older version.
+> When you want to upgrade 2.x, you must read the README again, and follow guides to change your Setting model.
+> 0.x stable branch: https://github.com/huacnlee/rails-settings-cached/tree/0.x
+
+- [Backward compatible to support 0.x scoped settings](docs/backward-compatible-to-scoped-settings.md)
+
+For new project / new user of rails-settings-cached. The [ActiveRecord::AttributeMethods::Serialization](https://api.rubyonrails.org/classes/ActiveRecord/AttributeMethods/Serialization/ClassMethods.html#method-i-serialize) is best choice.
+
+> This is reason of why rails-settings-cached 2.x removed **Scoped Settings** feature.
+
+For example:
+
+We wants a preferences setting for user.
+
+```rb
+class User < ActiveRecord::Base
+  serialize :preferences
+end
+
+@user = User.new
+@user.preferences[:receive_emails] = true
+@user.preferences[:public_email] = true
+@user.save
+```
 
-- [ruby-china/ruby-china](https://github.com/ruby-china/ruby-china)
+## Use cases:
+
+- [ruby-china/homeland](https://github.com/ruby-china/homeland) - master
+- [forem/forem](https://github.com/forem/forem) - 2.x
+- [siwapp/siwapp](https://github.com/siwapp/siwapp) - 2.x
+- [aidewoode/black_candy](https://github.com/aidewoode/black_candy) - 2.x
+- [huacnlee/bluedoc](https://github.com/huacnlee/bluedoc) - 2.x
+- [getzealot/zealot](https://github.com/getzealot/zealot) - 2.x
+- [kaishuu0123/rebacklogs](https://github.com/kaishuu0123/rebacklogs) - 2.x
+- [texterify/texterify](https://github.com/texterify/texterify) - 2.x
+- [tootsuite/mastodon](https://github.com/tootsuite/mastodon) - 0.6.x
+- [helpyio/helpy](https://github.com/helpyio/helpy) - 0.5.x
+- [daqing/rabel](https://github.com/daqing/rabel) - 0.4.x
+
+And more than [1K repositories](https://github.com/huacnlee/rails-settings-cached/network/dependents) used.