class StrongParameters::Parameters
Strong Parameters¶ ↑
It provides an interface for protecting attributes from end-user assignment. This makes Action Controller parameters forbidden to be used in Active Model mass assignment until they have been whitelisted.
In addition, parameters can be marked as required and flow through a predefined raise/rescue flow to end up as a 400 Bad Request with no effort.
class PeopleController < ActionController::Base # Using "Person.create(params[:person])" would raise an # ActiveModel::ForbiddenAttributes exception because it'd # be using mass assignment without an explicit permit step. # This is the recommended form: def create Person.create(person_params) end # This will pass with flying colors as long as there's a person key in the # parameters, otherwise it'll raise an ActionController::MissingParameter # exception, which will get caught by ActionController::Base and turned # into a 400 Bad Request reply. def update redirect_to current_account.people.find(params[:id]).tap { |person| person.update!(person_params) } end private # Using a private method to encapsulate the permissible parameters is # just a good pattern since you'll be able to reuse the same permit # list between create and update. Also, you can specialize this method # with per-user checking of permissible attributes. def person_params params.require(:person).permit(:name, :age) end end
In order to use accepts_nested_attributes_for
with Strong Parameters, you will need to specify which nested attributes should be whitelisted.
class Person has_many :pets accepts_nested_attributes_for :pets end class PeopleController < ActionController::Base def create Person.create(person_params) end ... private def person_params # It's mandatory to specify the nested attributes that should be whitelisted. # If you use `permit` with just the key that points to the nested attributes hash, # it will return an empty hash. params.require(:person).permit(:name, :age, pets_attributes: [ :name, :category ]) end end
See ActionController::Parameters.require and ActionController::Parameters.permit for more information.V
Constants
- EMPTY_ARRAY
- PERMITTED_SCALAR_TYPES
This is a white list of permitted scalar types that includes the ones supported in XML and JSON requests.
This list is in particular used to filter ordinary requests, String goes as first element to quickly short-circuit the common case.
If you modify this collection please update the API of
permit
above.
Attributes
Public Class Methods
# File lib/strong_parameters.rb, line 96 def self.const_missing(const_name) return super unless const_name == :NEVER_UNPERMITTED_PARAMS ActiveSupport::Deprecation.warn(<<-MSG.squish) `ActionController::Parameters::NEVER_UNPERMITTED_PARAMS` has been deprecated. Use `ActionController::Parameters.always_permitted_parameters` instead. MSG always_permitted_parameters end
Returns a new instance of ActionController::Parameters
. Also, sets the permitted
attribute to the default value of ActionController::Parameters.permit_all_parameters
.
class Person < ActiveRecord::Base end params = ActionController::Parameters.new(name: 'Francesco') params.permitted? # => false Person.new(params) # => ActiveModel::ForbiddenAttributesError ActionController::Parameters.permit_all_parameters = true params = ActionController::Parameters.new(name: 'Francesco') params.permitted? # => true Person.new(params) # => #<Person id: nil, name: "Francesco">
# File lib/strong_parameters.rb, line 122 def initialize(attributes = nil) super(attributes) @permitted = self.class.permit_all_parameters end
Public Instance Methods
Returns a parameter for the given key
. If not found, returns nil
.
params = ActionController::Parameters.new(person: { name: 'Francesco' }) params[:person] # => {"name"=>"Francesco"} params[:none] # => nil
# File lib/strong_parameters.rb, line 324 def [](key) convert_hashes_to_parameters(key, super) end
Attribute that keeps track of converted arrays, if any, to avoid double looping in the common use case permit + mass-assignment. Defined in a method to instantiate it only if needed.
Testing membership still loops, but it’s going to be faster than our own loop that converts values. Also, we are not going to build a new array object per fetch.
# File lib/strong_parameters.rb, line 171 def converted_arrays @converted_arrays ||= Set.new end
Deletes and returns a key-value pair from Parameters
whose key is equal to key. If the key is not found, returns the default value. If the optional code block is given and the key is not found, pass in the key and return the result of block.
# File lib/strong_parameters.rb, line 394 def delete(key, &block) convert_hashes_to_parameters(key, super, false) end
Returns an exact copy of the ActionController::Parameters
instance. permitted
state is kept on the duped object.
params = ActionController::Parameters.new(a: 1) params.permit! params.permitted? # => true copy_params = params.dup # => {"a"=>1} copy_params.permitted? # => true
# File lib/strong_parameters.rb, line 411 def dup super.tap do |duplicate| duplicate.permitted = @permitted end end
Convert all hashes in values into parameters, then yield each pair like the same way as Hash#each_pair
# File lib/strong_parameters.rb, line 154 def each_pair(&block) super do |key, value| convert_hashes_to_parameters(key, value) end super end
Removes and returns the key/value pairs matching the given keys.
params = ActionController::Parameters.new(a: 1, b: 2, c: 3) params.extract!(:a, :b) # => {"a"=>1, "b"=>2} params # => {"c"=>3}
# File lib/strong_parameters.rb, line 361 def extract!(*keys) new_instance_with_inherited_permitted_status(super) end
Returns a parameter for the given key
. If the key
can’t be found, there are several options: With no other arguments, it will raise an ActionController::ParameterMissing
error; if more arguments are given, then that will be returned; if a block is given, then that will be run and its result returned.
params = ActionController::Parameters.new(person: { name: 'Francesco' }) params.fetch(:person) # => {"name"=>"Francesco"} params.fetch(:none) # => ActionController::ParameterMissing: param is missing or the value is empty: none params.fetch(:none, 'Francesco') # => "Francesco" params.fetch(:none) { 'Francesco' } # => "Francesco"
# File lib/strong_parameters.rb, line 339 def fetch(key, *args) convert_hashes_to_parameters(key, super, false) rescue KeyError raise StrongParameters::Error::ParameterMissing.new(key) end
Returns a new ActionController::Parameters
instance that includes only the given filters
and sets the permitted
attribute for the object to true
. This is useful for limiting which attributes should be allowed for mass updating.
params = ActionController::Parameters.new(user: { name: 'Francesco', age: 22, role: 'admin' }) permitted = params.require(:user).permit(:name, :age) permitted.permitted? # => true permitted.has_key?(:name) # => true permitted.has_key?(:age) # => true permitted.has_key?(:role) # => false
Only permitted scalars pass the filter. For example, given
params.permit(:name)
:name
passes if it is a key of params
whose associated value is of type String
, Symbol
, NilClass
, Numeric
, TrueClass
, FalseClass
, Date
, Time
, DateTime
, StringIO
, IO
, ActionDispatch::Http::UploadedFile
or Rack::Test::UploadedFile
. Otherwise, the key :name
is filtered out.
You may declare that the parameter should be an array of permitted scalars by mapping it to an empty array:
params = ActionController::Parameters.new(tags: ['rails', 'parameters']) params.permit(tags: [])
You can also use permit
on nested parameters, like:
params = ActionController::Parameters.new({ person: { name: 'Francesco', age: 22, pets: [{ name: 'Purplish', category: 'dogs' }] } }) permitted = params.permit(person: [ :name, { pets: :name } ]) permitted.permitted? # => true permitted[:person][:name] # => "Francesco" permitted[:person][:age] # => nil permitted[:person][:pets][0][:name] # => "Purplish" permitted[:person][:pets][0][:category] # => nil
Note that if you use permit
in a key that points to a hash, it won’t allow all the hash. You also need to specify which attributes inside the hash should be whitelisted.
params = ActionController::Parameters.new({ person: { contact: { email: 'none@test.com', phone: '555-1234' } } }) params.require(:person).permit(:contact) # => {} params.require(:person).permit(contact: :phone) # => {"contact"=>{"phone"=>"555-1234"}} params.require(:person).permit(contact: [ :email, :phone ]) # => {"contact"=>{"email"=>"none@test.com", "phone"=>"555-1234"}}
# File lib/strong_parameters.rb, line 301 def permit(*filters) params = self.class.new filters.flatten.each do |filter| case filter when Symbol, String permitted_scalar_filter(params, filter) when Hash then hash_filter(params, filter) end end unpermitted_parameters!(params) if self.class.action_on_unpermitted_parameters params.permit! end
Sets the permitted
attribute to true
. This can be used to pass mass assignment. Returns self
.
class Person < ActiveRecord::Base end params = ActionController::Parameters.new(name: 'Francesco') params.permitted? # => false Person.new(params) # => ActiveModel::ForbiddenAttributesError params.permit! params.permitted? # => true Person.new(params) # => #<Person id: nil, name: "Francesco">
# File lib/strong_parameters.rb, line 197 def permit! each_pair do |_key, value| Array.wrap(value).each do |v| v.permit! if v.respond_to? :permit! end end @permitted = true self end
Returns true
if the parameter is permitted, false
otherwise.
params = ActionController::Parameters.new params.permitted? # => false params.permit! params.permitted? # => true
# File lib/strong_parameters.rb, line 181 def permitted? @permitted end
Ensures that a parameter is present. If it’s present, returns the parameter at the given key
, otherwise raises an ActionController::ParameterMissing
error.
ActionController::Parameters.new(person: { name: 'Francesco' }).require(:person) # => {"name"=>"Francesco"} ActionController::Parameters.new(person: nil).require(:person) # => ActionController::ParameterMissing: param is missing or the value is empty: person ActionController::Parameters.new(person: {}).require(:person) # => ActionController::ParameterMissing: param is missing or the value is empty: person
# File lib/strong_parameters.rb, line 220 def require(key) value = self[key] if value.present? || value == false value else fail StrongParameters::Error::ParameterMissing.new(key) end end
Equivalent to Hash#keep_if, but returns nil if no changes were made.
# File lib/strong_parameters.rb, line 399 def select!(&block) convert_value_to_parameters(super) end
Returns a new ActionController::Parameters
instance that includes only the given keys
. If the given keys
don’t exist, returns an empty hash.
params = ActionController::Parameters.new(a: 1, b: 2, c: 3) params.slice(:a, :b) # => {"a"=>1, "b"=>2} params.slice(:d) # => {}
# File lib/strong_parameters.rb, line 352 def slice(*keys) new_instance_with_inherited_permitted_status(super) end
Returns a safe Hash
representation of this parameter with all unpermitted keys removed.
params = ActionController::Parameters.new({ name: 'Senjougahara Hitagi', oddity: 'Heavy stone crab' }) params.to_h # => {} safe_params = params.permit(:name) safe_params.to_h # => {"name"=>"Senjougahara Hitagi"}
# File lib/strong_parameters.rb, line 138 def to_h if permitted? to_hash else slice(*self.class.always_permitted_parameters).permit!.to_h end end
Returns an unsafe, unfiltered Hash
representation of this parameter.
# File lib/strong_parameters.rb, line 147 def to_unsafe_h to_hash end
Returns a new ActionController::Parameters
with the results of running block
once for every value. The keys are unchanged.
params = ActionController::Parameters.new(a: 1, b: 2, c: 3) params.transform_values { |x| x * 2 } # => {"a"=>2, "b"=>4, "c"=>6}
# File lib/strong_parameters.rb, line 371 def transform_values if block_given? new_instance_with_inherited_permitted_status(super) else super end end
Private Instance Methods
# File lib/strong_parameters.rb, line 523 def array_of_permitted_scalars?(value) if value.is_a?(Array) value.all? { |element| permitted_scalar?(element) } end end
# File lib/strong_parameters.rb, line 529 def array_of_permitted_scalars_filter(params, key) if key?(key) && array_of_permitted_scalars?(self[key]) params[key] = self[key] end end
# File lib/strong_parameters.rb, line 429 def convert_hashes_to_parameters(key, value, assign_if_converted = true) converted = convert_value_to_parameters(value) self[key] = converted if assign_if_converted && !converted.equal?(value) converted end
# File lib/strong_parameters.rb, line 435 def convert_value_to_parameters(value) if value.is_a?(Array) && !converted_arrays.member?(value) converted = value.map { |_| convert_value_to_parameters(_) } converted_arrays << converted converted elsif value.is_a?(Parameters) || !value.is_a?(Hash) value else self.class.new(value) end end
# File lib/strong_parameters.rb, line 447 def each_element(object) if object.is_a?(Array) object.map { |el| yield el }.compact elsif fields_for_style?(object) hash = object.class.new object.each { |k, v| hash[k] = yield v } hash else yield object end end
# File lib/strong_parameters.rb, line 459 def fields_for_style?(object) object.is_a?(Hash) && object.all? { |k, v| k =~ /\A-?\d+\z/ && v.is_a?(Hash) } end
# File lib/strong_parameters.rb, line 536 def hash_filter(params, filter) filter = filter.with_indifferent_access # Slicing filters out non-declared keys. slice(*filter.keys).each do |key, value| next unless value if filter[key] == EMPTY_ARRAY # Declaration { comment_ids: [] }. array_of_permitted_scalars_filter(params, key) else # Declaration { user: :name } or { user: [:name, :age, { address: ... }] }. params[key] = each_element(value) do |element| if element.is_a?(Hash) element = self.class.new(element) unless element.respond_to?(:permit) element.permit(*Array.wrap(filter[key])) end end end end end
# File lib/strong_parameters.rb, line 423 def new_instance_with_inherited_permitted_status(hash) self.class.new(hash).tap do |new_instance| new_instance.permitted = @permitted end end
# File lib/strong_parameters.rb, line 507 def permitted_scalar?(value) PERMITTED_SCALAR_TYPES.any? { |type| value.is_a?(type) } end
# File lib/strong_parameters.rb, line 511 def permitted_scalar_filter(params, key) if key?(key) && permitted_scalar?(self[key]) params[key] = self[key] end keys.grep(/\A#{Regexp.escape(key)}\(\d+[if]?\)\z/) do |k| if permitted_scalar?(self[k]) params[k] = self[k] end end end
# File lib/strong_parameters.rb, line 476 def unpermitted_keys(params) self.keys - params.keys - self.always_permitted_parameters end
# File lib/strong_parameters.rb, line 463 def unpermitted_parameters!(params) unpermitted_keys = unpermitted_keys(params) if unpermitted_keys.any? case self.class.action_on_unpermitted_parameters when :log name = 'unpermitted_parameters.action_controller' ActiveSupport::Notifications.instrument(name, keys: unpermitted_keys) when :raise fail StrongParameters::Error::UnpermittedParameters.new(unpermitted_keys) end end end