README.md in phony_rails-0.14.11 vs README.md in phony_rails-0.14.12
- old
+ new
@@ -154,9 +154,25 @@
validates_plausible_phone :phone_number_normalized, presence: true, if: :phone_number?
```
Validation supports phone numbers with extension, such as `+18181231234 x1234` or `'+1 (818)151-5483 #4312'` out-of-the-box.
+Return original value after validation:
+
+The flag normalize_when_valid (disabled by default), allows to return the original phone_number when is the object is not valid. When phone validation fails, normalization is not triggered at all. It could prevent a situation where user fills in the phone number and after validation, he gets back different, already normalized phone number value, even if phone number was wrong.
+
+Example usage:
+
+```ruby
+validates_plausible_phone :phone_number
+phony_normalize :phone_number, country_code: :country_code, normalize_when_valid: true
+```
+
+Filling in the number will result with following:
+
+When the number is incorrect (e.g. phone_number: `+44 888 888 888` for country_code 'PL'), the original validation behavior is preserved, but if the number is still invalid, the original value is returned.
+When number is valid, it will save the normalized number (e.g. `+48 888 888 888` will be saved as `+48888888888`).
+
#### Allowing records country codes to not match phone number country codes
You may have a record specifying one country (via a `country_code` attribute) but using a phone number from another country. For example, your record may be from Japan but have a phone number from the Philippines. By default, `phony_rails` will consider your record's `country_code` as part of the validation. If that country doesn't match the country code in the phone number, validation will fail.
Additionally, `phony_normalize` will always add the records country code as the country number (eg. the user enters '+81xxx' for Japan and the records `country_code` is 'DE' then `phony_normalize` will change the number to '+4981'). You can turn this off by adding `enforce_record_country: false` to the validation options. The country_code will then only be added if no country code is specified.