Merge pull request #27427 from rails/binary-params

Document and update API for `skip_parameter_encoding`

1 files changed, 29 insertions, 10 deletions

diff --git a/actionpack/lib/action_controller/metal/parameter_encoding.rb b/actionpack/lib/action_controller/metal/parameter_encoding.rb
index c457fd0d06..962532ff09 100644
--- a/actionpack/lib/action_controller/metal/parameter_encoding.rb
+++ b/actionpack/lib/action_controller/metal/parameter_encoding.rb
@@ -1,5 +1,5 @@
 module ActionController
-  # Allows encoding to be specified per parameter per action.
+  # Specify binary encoding for parameters for a given action.
   module ParameterEncoding
     extend ActiveSupport::Concern
 
@@ -13,17 +13,36 @@ module ActionController
         @_parameter_encodings = {}
       end
 
-      def encoding_for_param(action, param) # :nodoc:
-        if @_parameter_encodings[action.to_s] && @_parameter_encodings[action.to_s][param.to_s]
-          @_parameter_encodings[action.to_s][param.to_s]
-        else
-          super
-        end
+      def binary_params_for?(action) # :nodoc:
+        @_parameter_encodings[action.to_s]
       end
 
-      def parameter_encoding(action, param_name, encoding)
-        @_parameter_encodings[action.to_s] ||= {}
-        @_parameter_encodings[action.to_s][param_name.to_s] = encoding
+      # Specify that a given action's parameters should all be encoded as
+      # ASCII-8BIT (it "skips" the encoding default of UTF-8).
+      #
+      # For example, a controller would use it like this:
+      #
+      #   class RepositoryController < ActionController::Base
+      #     skip_parameter_encoding :show
+      #
+      #     def show
+      #       @repo = Repository.find_by_filesystem_path params[:file_path]
+      #
+      #       # `repo_name` is guaranteed to be UTF-8, but was ASCII-8BIT, so
+      #       # tag it as such
+      #       @repo_name = params[:repo_name].force_encoding 'UTF-8'
+      #     end
+      #
+      #     def index
+      #       @repositories = Repository.all
+      #     end
+      #   end
+      #
+      # The show action in the above controller would have all parameter values
+      # encoded as ASCII-8BIT.  This is useful in the case where an application
+      # must handle data but encoding of the data is unknown, like file system data.
+      def skip_parameter_encoding(action)
+        @_parameter_encodings[action.to_s] = true
       end
     end
   end