From eefb6db4a92dd87baac257e92197671421e48d9b Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Sat, 29 Aug 2015 14:06:54 +0200 Subject: revamps the docs of strong params require [ci skip] References #19565. --- .../action_controller/metal/strong_parameters.rb | 49 ++++++++++++++++++---- 1 file changed, 40 insertions(+), 9 deletions(-) diff --git a/actionpack/lib/action_controller/metal/strong_parameters.rb b/actionpack/lib/action_controller/metal/strong_parameters.rb index da507ca294..32e569e005 100644 --- a/actionpack/lib/action_controller/metal/strong_parameters.rb +++ b/actionpack/lib/action_controller/metal/strong_parameters.rb @@ -240,25 +240,56 @@ module ActionController self end - # Ensures that a parameter is present. If it's present, returns - # the parameter at the given +key+, otherwise raises an - # ActionController::ParameterMissing error. + # This method accepts both a single key and an array of keys. + # + # When passed a single key, if it exists and its associated value is + # either present or the singleton +false+, returns said value: # # ActionController::Parameters.new(person: { name: 'Francesco' }).require(:person) # # => {"name"=>"Francesco"} # + # Otherwise raises ActionController::ParameterMissing: + # + # ActionController::Parameters.new.require(:person) + # # ActionController::ParameterMissing: param is missing or the value is empty: person + # # ActionController::Parameters.new(person: nil).require(:person) - # # => ActionController::ParameterMissing: param is missing or the value is empty: person + # # ActionController::ParameterMissing: param is missing or the value is empty: person + # + # ActionController::Parameters.new(person: "\t").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 + # # ActionController::ParameterMissing: param is missing or the value is empty: person + # + # When given an array of keys, the method tries to require each one of them + # in order. It if succeeds an array with the respective return values is + # returned: + # + # params = ActionController::Parameters.new(user: { ... }, profile: { ... }) + # user_params, profile_params = params.require(:user, :profile) # - # ActionController::Parameters.new(first_name: 'Gaurish', title: nil).require([:first_name, :title]) - # # => ActionController::ParameterMissing: param is missing or the value is empty: title + # Otherwise, the method reraises the first exception found: # - # params = ActionController::Parameters.new(first_name: 'Gaurish', title: 'Mjallo') - # first_name, title = params.require([:first_name, :title]) + # params = ActionController::Parameters.new(user: {}, profile: {}) + # user_params, profile_params = params.require(:user, :profile) + # # ActionController::ParameterMissing: param is missing or the value is empty: user + # + # Technically this method can be used to fetch terminal values: + # + # # CAREFUL + # params = ActionController::Parameters.new(person: { name: 'Finn' }) + # name = params.require(:person).require(:name) # CAREFUL + # + # but take into account that at some point those ones have to be permitted: + # + # def user_params + # params.require(:person).permit(:name).tap do |user_params| + # user_params.require(:name) # SAFER + # end + # end # + # for example. def require(key) return key.map { |k| require(k) } if key.is_a?(Array) value = self[key] -- cgit v1.2.3