Merge pull request rails#49105 from Earlopain/ar-normalizes-where

Document `where` support for AR `normalizes`

Author: byroot

activerecord/CHANGELOG.md

@@ -862,6 +862,7 @@
       ```ruby
       class User < ActiveRecord::Base
         normalizes :email, with: -> email { email.strip.downcase }
+        normalizes :phone, with: -> phone { phone.delete("^0-9").delete_prefix("1") }
       end
 
       user = User.create(email: " [email protected]\n")
@@ -871,8 +872,12 @@
       user.email                  # => "[email protected]"
       user.email_before_type_cast # => "[email protected]"
 
+      User.where(email: "\t[email protected] ").count # => 1
+
       User.exists?(email: "\t[email protected] ")         # => true
       User.exists?(["email = ?", "\t[email protected] "]) # => false
+
+      User.normalize_value_for(:phone, "+1 (555) 867-5309") # => "5558675309"
       ```
 
     *Jonathan Hefner*

activerecord/lib/active_record/normalization.rb

@@ -69,6 +69,8 @@ module ClassMethods
       #   user.email                  # => "[email protected]"
       #   user.email_before_type_cast # => "[email protected]"
       #
+      #   User.where(email: "\[email protected] ").count # => 1
+      #
       #   User.exists?(email: "\[email protected] ")         # => true
       #   User.exists?(["email = ?", "\[email protected] "]) # => false
       #

activerecord/test/cases/normalized_attribute_test.rb

@@ -83,6 +83,16 @@ class NormalizedAircraft < Aircraft
     assert_equal @aircraft, NormalizedAircraft.find_by(manufactured_at: @time.to_s)
   end
 
+  test "searches a record by normalized value" do
+    from_database = NormalizedAircraft.where(name: "fly HIGH")
+    assert_equal [@aircraft], from_database
+  end
+
+  test "searches a record by normalized values" do
+    from_database = NormalizedAircraft.where(name: ["fly LOW", "fly HIGH"])
+    assert_equal [@aircraft], from_database
+  end
+
   test "can stack normalizations" do
     titlecase_then_reverse = Class.new(NormalizedAircraft) do
       normalizes :name, with: -> name { name.reverse }

guides/source/7_1_release_notes.md

@@ -78,10 +78,12 @@ user = User.find_by(email: "\[email protected] ")
 user.email                  # => "[email protected]"
 user.email_before_type_cast # => "[email protected]"
 
+User.where(email: "\t[email protected] ").count # => 1
+
 User.exists?(email: "\t[email protected] ")         # => true
 User.exists?(["email = ?", "\t[email protected] "]) # => false
 
-User.normalize(:phone, "+1 (555) 867-5309") # => "5558675309"
+User.normalize_value_for(:phone, "+1 (555) 867-5309") # => "5558675309"
 ```
 
 ### Add `ActiveRecord::Base.generates_token_for`