Class: ActionController::Parameters
- Inherits:
-
ActiveSupport::HashWithIndifferentAccess
- Object
- ActiveSupport::HashWithIndifferentAccess
- ActionController::Parameters
- Defined in:
- lib/action_controller/metal/strong_parameters.rb
Overview
Action Controller Parameters
Allows to choose which attributes should be whitelisted for mass updating and thus prevent accidentally exposing that which shouldn’t be exposed. Provides two methods for this purpose: #require and #permit. The former is used to mark parameters as required. The latter is used to set the parameter as permitted and limit which attributes should be allowed for mass updating.
params = ActionController::Parameters.new({
person: {
name: 'Francesco',
age: 22,
role: 'admin'
}
})
permitted = params.require(:person).permit(:name, :age)
permitted # => {"name"=>"Francesco", "age"=>22}
permitted.class # => ActionController::Parameters
permitted.permitted? # => true
Person.first.update!(permitted)
# => #<Person id: 1, name: "Francesco", age: 22, role: "user">
It provides two options that controls the top-level behavior of new instances:
-
permit_all_parameters
- If it’strue
, all the parameters will be permitted by default. The default isfalse
. -
action_on_unpermitted_parameters
- Allow to control the behavior when parameters that are not explicitly permitted are found. The values can be:log
to write a message on the logger or:raise
to raise ActionController::UnpermittedParameters exception. The default value is:log
in test and development environments,false
otherwise.
Examples:
params = ActionController::Parameters.new
params.permitted? # => false
ActionController::Parameters.permit_all_parameters = true
params = ActionController::Parameters.new
params.permitted? # => true
params = ActionController::Parameters.new(a: "123", b: "456")
params.permit(:c)
# => {}
ActionController::Parameters.action_on_unpermitted_parameters = :raise
params = ActionController::Parameters.new(a: "123", b: "456")
params.permit(:c)
# => ActionController::UnpermittedParameters: found unpermitted keys: a, b
Please note that these options *are not thread-safe*. In a multi-threaded environment they should only be set once at boot-time and never mutated at runtime.
ActionController::Parameters
inherits from ActiveSupport::HashWithIndifferentAccess
, this means that you can fetch values using either :key
or "key"
.
params = ActionController::Parameters.new(key: 'value')
params[:key] # => "value"
params["key"] # => "value"
Class Method Summary collapse
Instance Method Summary collapse
-
#[](key) ⇒ Object
Returns a parameter for the given
key
. -
#converted_arrays ⇒ Object
Attribute that keeps track of converted arrays, if any, to avoid double looping in the common use case permit + mass-assignment.
-
#delete(key, &block) ⇒ Object
Deletes and returns a key-value pair from
Parameters
whose key is equal to key. -
#dup ⇒ Object
Returns an exact copy of the
ActionController::Parameters
instance. -
#each_pair(&block) ⇒ Object
(also: #each)
Convert all hashes in values into parameters, then yield each pair like the same way as
Hash#each_pair
. -
#extract!(*keys) ⇒ Object
Removes and returns the key/value pairs matching the given keys.
-
#fetch(key, *args) ⇒ Object
Returns a parameter for the given
key
. -
#initialize(attributes = nil) ⇒ Parameters
constructor
Returns a new instance of
ActionController::Parameters
. -
#permit(*filters) ⇒ Object
Returns a new
ActionController::Parameters
instance that includes only the givenfilters
and sets thepermitted
attribute for the object totrue
. -
#permit! ⇒ Object
Sets the
permitted
attribute totrue
. -
#permitted? ⇒ Boolean
Returns
true
if the parameter is permitted,false
otherwise. -
#require(key) ⇒ Object
(also: #required)
Ensures that a parameter is present.
-
#select!(&block) ⇒ Object
Equivalent to Hash#keep_if, but returns nil if no changes were made.
-
#slice(*keys) ⇒ Object
Returns a new
ActionController::Parameters
instance that includes only the givenkeys
. -
#to_h ⇒ Object
Returns a safe
Hash
representation of this parameter with all unpermitted keys removed. -
#to_unsafe_h ⇒ Object
(also: #to_unsafe_hash)
Returns an unsafe, unfiltered
Hash
representation of this parameter. -
#transform_keys ⇒ Object
This method is here only to make sure that the returned object has the correct
permitted
status. -
#transform_values ⇒ Object
Returns a new
ActionController::Parameters
with the results of runningblock
once for every value.
Constructor Details
#initialize(attributes = nil) ⇒ Parameters
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">
146 147 148 149 |
# File 'lib/action_controller/metal/strong_parameters.rb', line 146 def initialize(attributes = nil) super(attributes) @permitted = self.class.permit_all_parameters end |
Class Method Details
.const_missing(const_name) ⇒ Object
120 121 122 123 124 125 126 127 128 |
# File 'lib/action_controller/metal/strong_parameters.rb', line 120 def self.const_missing(const_name) 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 |
Instance Method Details
#[](key) ⇒ Object
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
348 349 350 |
# File 'lib/action_controller/metal/strong_parameters.rb', line 348 def [](key) convert_hashes_to_parameters(key, super) end |
#converted_arrays ⇒ Object
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.
195 196 197 |
# File 'lib/action_controller/metal/strong_parameters.rb', line 195 def converted_arrays @converted_arrays ||= Set.new end |
#delete(key, &block) ⇒ Object
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.
418 419 420 |
# File 'lib/action_controller/metal/strong_parameters.rb', line 418 def delete(key, &block) convert_hashes_to_parameters(key, super, false) end |
#dup ⇒ Object
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
435 436 437 438 439 |
# File 'lib/action_controller/metal/strong_parameters.rb', line 435 def dup super.tap do |duplicate| duplicate.permitted = @permitted end end |
#each_pair(&block) ⇒ Object Also known as: each
Convert all hashes in values into parameters, then yield each pair like the same way as Hash#each_pair
178 179 180 181 182 183 184 |
# File 'lib/action_controller/metal/strong_parameters.rb', line 178 def each_pair(&block) super do |key, value| convert_hashes_to_parameters(key, value) end super end |
#extract!(*keys) ⇒ Object
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}
385 386 387 |
# File 'lib/action_controller/metal/strong_parameters.rb', line 385 def extract!(*keys) new_instance_with_inherited_permitted_status(super) end |
#fetch(key, *args) ⇒ Object
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 not found: none
params.fetch(:none, 'Francesco') # => "Francesco"
params.fetch(:none) { 'Francesco' } # => "Francesco"
363 364 365 366 367 |
# File 'lib/action_controller/metal/strong_parameters.rb', line 363 def fetch(key, *args) convert_hashes_to_parameters(key, super, false) rescue KeyError raise ActionController::ParameterMissing.new(key) end |
#permit(*filters) ⇒ Object
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 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: '[email protected]',
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"=>"[email protected]", "phone"=>"555-1234"}}
325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 |
# File 'lib/action_controller/metal/strong_parameters.rb', line 325 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 |
#permit! ⇒ Object
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">
221 222 223 224 225 226 227 228 229 230 |
# File 'lib/action_controller/metal/strong_parameters.rb', line 221 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 |
#permitted? ⇒ Boolean
Returns true
if the parameter is permitted, false
otherwise.
params = ActionController::Parameters.new
params.permitted? # => false
params.permit!
params.permitted? # => true
205 206 207 |
# File 'lib/action_controller/metal/strong_parameters.rb', line 205 def permitted? @permitted end |
#require(key) ⇒ Object Also known as: required
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 not found: person
ActionController::Parameters.new(person: {}).require(:person)
# => ActionController::ParameterMissing: param not found: person
244 245 246 247 248 249 250 251 |
# File 'lib/action_controller/metal/strong_parameters.rb', line 244 def require(key) value = self[key] if value.present? || value == false value else raise ParameterMissing.new(key) end end |
#select!(&block) ⇒ Object
Equivalent to Hash#keep_if, but returns nil if no changes were made.
423 424 425 |
# File 'lib/action_controller/metal/strong_parameters.rb', line 423 def select!(&block) convert_value_to_parameters(super) end |
#slice(*keys) ⇒ Object
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) # => {}
376 377 378 |
# File 'lib/action_controller/metal/strong_parameters.rb', line 376 def slice(*keys) new_instance_with_inherited_permitted_status(super) end |
#to_h ⇒ Object
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"}
162 163 164 165 166 167 168 |
# File 'lib/action_controller/metal/strong_parameters.rb', line 162 def to_h if permitted? to_hash else slice(*self.class.always_permitted_parameters).permit!.to_h end end |
#to_unsafe_h ⇒ Object Also known as: to_unsafe_hash
Returns an unsafe, unfiltered Hash
representation of this parameter.
171 172 173 |
# File 'lib/action_controller/metal/strong_parameters.rb', line 171 def to_unsafe_h to_hash end |
#transform_keys ⇒ Object
This method is here only to make sure that the returned object has the correct permitted
status. It should not matter since the parent of this object is HashWithIndifferentAccess
406 407 408 409 410 411 412 |
# File 'lib/action_controller/metal/strong_parameters.rb', line 406 def transform_keys # :nodoc: if block_given? new_instance_with_inherited_permitted_status(super) else super end end |
#transform_values ⇒ Object
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}
395 396 397 398 399 400 401 |
# File 'lib/action_controller/metal/strong_parameters.rb', line 395 def transform_values if block_given? new_instance_with_inherited_permitted_status(super) else super end end |