This repository has been archived by the owner. It is now read-only.
Permalink
Browse files

Add code coloring to readme

  • Loading branch information...
1 parent 998c8d5 commit b2036aa9d1a3b621c9fcb69aa8182c2271f44919 @soffes soffes committed Feb 27, 2013
Showing with 167 additions and 158 deletions.
  1. +1 −1 Gemfile
  2. +35 −47 Gemfile.lock
  3. +128 −0 README.md
  4. +0 −108 README.rdoc
  5. +2 −1 Rakefile
  6. +1 −1 strong_parameters.gemspec
View
@@ -1,4 +1,4 @@
source "http://rubygems.org"
gemspec
-gem 'rdoc'
+gem 'rdoc', '>= 4.0.0'
View
@@ -1,69 +1,57 @@
PATH
remote: .
specs:
- strong_parameters (0.1.6.dev)
+ strong_parameters (0.2.0)
actionpack (~> 3.0)
activemodel (~> 3.0)
railties (~> 3.0)
GEM
remote: http://rubygems.org/
specs:
- actionpack (3.2.8)
- activemodel (= 3.2.8)
- activesupport (= 3.2.8)
- builder (~> 3.0.0)
- erubis (~> 2.7.0)
- journey (~> 1.0.4)
- rack (~> 1.4.0)
- rack-cache (~> 1.2)
- rack-test (~> 0.6.1)
- sprockets (~> 2.1.3)
- activemodel (3.2.8)
- activesupport (= 3.2.8)
- builder (~> 3.0.0)
- activesupport (3.2.8)
- i18n (~> 0.6)
- multi_json (~> 1.0)
- builder (3.0.4)
- erubis (2.7.0)
- hike (1.2.1)
- i18n (0.6.1)
- journey (1.0.4)
- json (1.7.5)
+ abstract (1.0.0)
+ actionpack (3.0.8)
+ activemodel (= 3.0.8)
+ activesupport (= 3.0.8)
+ builder (~> 2.1.2)
+ erubis (~> 2.6.6)
+ i18n (~> 0.5.0)
+ rack (~> 1.2.1)
+ rack-mount (~> 0.6.14)
+ rack-test (~> 0.5.7)
+ tzinfo (~> 0.3.23)
+ activemodel (3.0.8)
+ activesupport (= 3.0.8)
+ builder (~> 2.1.2)
+ i18n (~> 0.5.0)
+ activesupport (3.0.8)
+ builder (2.1.2)
+ erubis (2.6.6)
+ abstract (>= 1.0.0)
+ i18n (0.5.0)
metaclass (0.0.1)
- mocha (0.12.0)
+ mocha (0.12.10)
metaclass (~> 0.0.1)
- multi_json (1.3.7)
- rack (1.4.1)
- rack-cache (1.2)
- rack (>= 0.4)
- rack-ssl (1.3.2)
- rack
- rack-test (0.6.2)
+ rack (1.2.8)
+ rack-mount (0.6.14)
+ rack (>= 1.0.0)
+ rack-test (0.5.7)
rack (>= 1.0)
- railties (3.2.8)
- actionpack (= 3.2.8)
- activesupport (= 3.2.8)
- rack-ssl (~> 1.3.2)
+ railties (3.0.8)
+ actionpack (= 3.0.8)
+ activesupport (= 3.0.8)
rake (>= 0.8.7)
- rdoc (~> 3.4)
- thor (>= 0.14.6, < 2.0)
- rake (0.9.2.2)
- rdoc (3.12)
- json (~> 1.4)
- sprockets (2.1.3)
- hike (~> 1.2)
- rack (~> 1.0)
- tilt (~> 1.1, != 1.3.0)
- thor (0.16.0)
- tilt (1.3.3)
+ thor (~> 0.14.4)
+ rake (10.0.3)
+ rdoc (4.0.0)
+ thor (0.14.6)
+ tzinfo (0.3.35)
PLATFORMS
ruby
DEPENDENCIES
mocha (~> 0.12.0)
rake
- rdoc
+ rdoc (>= 4.0.0)
strong_parameters!
View
128 README.md
@@ -0,0 +1,128 @@
+# Strong Parameters
+
+With this plugin Action Controller parameters are forbidden to be used in Active Model mass assignments until they have been whitelisted. This means you'll have to make a conscious choice about which attributes to allow for mass updating and thus prevent accidentally exposing that which shouldn't be exposed.
+
+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.
+
+``` ruby
+class PeopleController < ActionController::Base
+ # This will raise an ActiveModel::ForbiddenAttributes exception because it's using mass assignment
+ # without an explicit permit step.
+ def create
+ Person.create(params[:person])
+ end
+
+ # This will pass with flying colors as long as there's a person key in the parameters, otherwise
+ # it'll raise a ActionController::MissingParameter exception, which will get caught by
+ # ActionController::Base and turned into that 400 Bad Request reply.
+ def update
+ person = current_account.people.find(params[:id])
+ person.update_attributes!(person_params)
+ redirect_to person
+ 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
+```
+
+## Permitted Scalar Values
+
+Given
+
+``` ruby
+params.permit(:id)
+```
+
+the key `:id` will pass the whitelisting if it appears in `params` and it has a permitted scalar value associated. Otherwise the key is going to be filtered out, so arrays, hashes, or any other objects cannot be injected.
+
+The permitted scalar types are `String`, `Symbol`, `NilClass`, `Numeric`, `TrueClass`, `FalseClass`, `Date`, `Time`, `DateTime`, `StringIO`, `IO`, `ActionDispatch::Http::UploadedFile` and `Rack::Test::UploadedFile`.
+
+To declare that the value in `params` must be an array of permitted scalar values map the key to an empty array:
+
+``` ruby
+params.permit(:id => [])
+```
+
+To whitelist an entire hash of parameters, the `permit!` method can be used
+
+``` ruby
+params.require(:log_entry).permit!
+```
+
+This will mark the `:log_entry` parameters hash and any subhash of it permitted. Extreme care should be taken when using `permit!` as it will allow all current and future model attributes to be mass-assigned.
+
+## Nested Parameters
+
+You can also use permit on nested parameters, like:
+
+``` ruby
+params.permit(:name, {:emails => []}, :friends => [ :name, { :family => [ :name ], :hobbies => [] }])
+```
+
+This declaration whitelists the `name`, `emails` and `friends` attributes. It is expected that `emails` will be an array of permitted scalar values and that `friends` will be an array of resources with specific attributes : they should have a `name` attribute (any permitted scalar values allowed), a `hobbies` attribute as an array of permitted scalar values, and a `family` attribute which is restricted to having a `name` (any permitted scalar values allowed, too).
+
+Thanks to Nick Kallen for the permit idea!
+
+## Handling of Unpermitted Keys
+
+By default parameter keys that are not explicitly permitted will be logged in the development and test environment. In other environments these parameters will simply be filtered out and ignored.
+
+Additionally, this behaviour can be changed by changing the `config.action_controller.action_on_unpermitted_parameters` property in your environment files. If set to `:log` the unpermitted attributes will be logged, if set to `:raise` an exception will be raised.
+
+## Use Outside of Controllers
+
+While Strong Parameters will enforce permitted and required values in your application controllers, keep in mind
+that you will need to sanitize untrusted data used for mass assignment when in use outside of controllers.
+
+For example, if you retrieve JSON data from a third party API call and pass the unchecked parsed result on to
+`Model.create`, undesired mass assignments could take place. You can alleviate this risk by slicing the hash data,
+or wrapping the data in a new instance of `ActionController::Parameters` and declaring permissions the same as
+you would in a controller. For example:
+
+``` ruby
+raw_parameters = { :email => "john@example.com", :name => "John", :admin => true }
+parameters = ActionController::Parameters.new(raw_parameters)
+user = User.create(parameters.permit(:name, :email))
+```
+
+## Installation
+
+In Gemfile:
+
+``` ruby
+gem 'strong_parameters'
+```
+
+and then run `bundle`. To activate the strong parameters, you need to include this module in
+every model you want protected.
+
+``` ruby
+class Post < ActiveRecord::Base
+ include ActiveModel::ForbiddenAttributesProtection
+end
+```
+
+Alternatively, you can protect all Active Record resources by default by creating an initializer and pasting the line:
+
+``` ruby
+ActiveRecord::Base.send(:include, ActiveModel::ForbiddenAttributesProtection)
+```
+
+If you want to now disable the default whitelisting that occurs in later versions of Rails, change the `config.active_record.whitelist_attributes` property in your `config/application.rb`:
+
+``` ruby
+config.active_record.whitelist_attributes = false
+```
+
+This will allow you to remove / not have to use `attr_accessible` and do mass assignment inside your code and tests.
+
+## Compatibility
+
+This plugin is only fully compatible with Rails versions 3.0, 3.1 and 3.2 but not 4.0+, as it is part of Rails Core in 4.0.
+An unofficial Rails 2 version is [strong_parameters_rails2](https://github.com/grosser/strong_parameters/tree/rails2).
View
@@ -1,108 +0,0 @@
-= Strong Parameters
-
-With this plugin Action Controller parameters are forbidden to be used in Active Model mass assignments until they have been whitelisted. This means you'll have to make a conscious choice about which attributes to allow for mass updating and thus prevent accidentally exposing that which shouldn't be exposed.
-
-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
- # This will raise an ActiveModel::ForbiddenAttributes exception because it's using mass assignment
- # without an explicit permit step.
- def create
- Person.create(params[:person])
- end
-
- # This will pass with flying colors as long as there's a person key in the parameters, otherwise
- # it'll raise a ActionController::MissingParameter exception, which will get caught by
- # ActionController::Base and turned into that 400 Bad Request reply.
- def update
- person = current_account.people.find(params[:id])
- person.update_attributes!(person_params)
- redirect_to person
- 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
-
-== Permitted Scalar Values
-
-Given
-
- params.permit(:id)
-
-the key +:id+ will pass the whitelisting if it appears in +params+ and it has a permitted scalar value associated. Otherwise the key is going to be filtered out, so arrays, hashes, or any other objects cannot be injected.
-
-The permitted scalar types are +String+, +Symbol+, +NilClass+, +Numeric+, +TrueClass+, +FalseClass+, +Date+, +Time+, +DateTime+, +StringIO+, +IO+, +ActionDispatch::Http::UploadedFile+ and +Rack::Test::UploadedFile+.
-
-To declare that the value in +params+ must be an array of permitted scalar values map the key to an empty array:
-
- params.permit(:id => [])
-
-To whitelist an entire hash of parameters, the +permit!+ method can be used
-
- params.require(:log_entry).permit!
-
-This will mark the +:log_entry+ parameters hash and any subhash of it permitted. Extreme care should be taken when using +permit!+ as it will allow all current and future model attributes to be mass-assigned.
-
-== Nested Parameters
-
-You can also use permit on nested parameters, like:
-
- params.permit(:name, {:emails => []}, :friends => [ :name, { :family => [ :name ], :hobbies => [] }])
-
-This declaration whitelists the +name+, +emails+ and +friends+ attributes. It is expected that +emails+ will be an array of permitted scalar values and that +friends+ will be an array of resources with specific attributes : they should have a +name+ attribute (any permitted scalar values allowed), a +hobbies+ attribute as an array of permitted scalar values, and a +family+ attribute which is restricted to having a +name+ (any permitted scalar values allowed, too).
-
-Thanks to Nick Kallen for the permit idea!
-
-== Handling of Unpermitted Keys
-
-By default parameter keys that are not explicitly permitted will be logged in the development and test environment. In other environments these parameters will simply be filtered out and ignored.
-
-Additionally, this behaviour can be changed by changing the +config.action_controller.action_on_unpermitted_parameters+ property in your environment files. If set to +:log+ the unpermitted attributes will be logged, if set to +:raise+ an exception will be raised.
-
-== Use Outside of Controllers
-
-While Strong Parameters will enforce permitted and required values in your application controllers, keep in mind
-that you will need to sanitize untrusted data used for mass assignment when in use outside of controllers.
-
-For example, if you retrieve JSON data from a third party API call and pass the unchecked parsed result on to
-+Model.create+, undesired mass assignments could take place. You can alleviate this risk by slicing the hash data,
-or wrapping the data in a new instance of +ActionController::Parameters+ and declaring permissions the same as
-you would in a controller. For example:
-
- raw_parameters = { :email => "john@example.com", :name => "John", :admin => true }
- parameters = ActionController::Parameters.new(raw_parameters)
- user = User.create(parameters.permit(:name, :email))
-
-== Installation
-
-In Gemfile:
-
- gem 'strong_parameters'
-
-and then run `bundle`. To activate the strong parameters, you need to include this module in
-every model you want protected.
-
- class Post < ActiveRecord::Base
- include ActiveModel::ForbiddenAttributesProtection
- end
-
-Alternatively, you can protect all Active Record resources by default by creating an initializer and pasting the line:
-
- ActiveRecord::Base.send(:include, ActiveModel::ForbiddenAttributesProtection)
-
-If you want to now disable the default whitelisting that occurs in later versions of Rails, change the +config.active_record.whitelist_attributes+ property in your +config/application.rb+:
-
- config.active_record.whitelist_attributes = false
-
-This will allow you to remove / not have to use +attr_accessible+ and do mass assignment inside your code and tests.
-
-== Compatibility
-
-This plugin is only fully compatible with Rails versions 3.0, 3.1 and 3.2 but not 4.0+, as it is part of Rails Core in 4.0.
-An unofficial Rails 2 version is {strong_parameters_rails2}[https://github.com/grosser/strong_parameters/tree/rails2].
View
@@ -12,7 +12,8 @@ RDoc::Task.new(:rdoc) do |rdoc|
rdoc.rdoc_dir = 'rdoc'
rdoc.title = 'StrongParameters'
rdoc.options << '--line-numbers'
- rdoc.rdoc_files.include('README.rdoc')
+ rdoc_main = 'README.md'
+ rdoc.rdoc_files.include('README.md')
rdoc.rdoc_files.include('lib/**/*.rb')
end
@@ -12,7 +12,7 @@ Gem::Specification.new do |s|
s.summary = "Permitted and required parameters for Action Pack"
s.homepage = "https://github.com/rails/strong_parameters"
- s.files = Dir["{app,config,db,lib}/**/*"] + ["MIT-LICENSE", "Rakefile", "README.rdoc"]
+ s.files = Dir["{app,config,db,lib}/**/*"] + ["MIT-LICENSE", "Rakefile", "README.md"]
s.test_files = Dir["test/**/*"]
s.add_dependency "actionpack", "~> 3.0"

0 comments on commit b2036aa

Please sign in to comment.