Fix Phone number long number and other updates (#2842)

* Fix Phone number long number and other updates - moves phones country code to `phone_number.country_code` to avoid mixing it with address country code; - removes extensions from the phone number generation. Extensions added more numbers to the cell phone; - update `en.phone_number.country_code` locale to include only a sample of random country codes, and removes extra digits such as area code from them; - fixes Phone number area and exchange code with no locales: if there is no locale set, falls back to the `en.phone_number` area and exchange code generators; - updates YARD docs about the generators, and add more tests; - updates documentation; * Add note about North American Numbering Plan in documentation Co-authored-by: Raymond Sapida <[email protected]> * Update formatting for locale files using reformat_yaml rake task Co-authored-by: Raymond Sapida <[email protected]> * Update phone_number.md --------- Co-authored-by: Raymond Sapida <[email protected]>
faker-ruby · Nov 13, 2023 · 31d99d1 · 31d99d1
1 parent 3173009
commit 31d99d1
Show file tree

Hide file tree

Showing 35 changed files with 54,372 additions and 6,440 deletions.
diff --git a/doc/default/phone_number.md b/doc/default/phone_number.md
@@ -1,85 +1,128 @@
-# `Faker::PhoneNumber`
+# Faker::PhoneNumber
 
-### `.phone_number`
+Phone numbers generate North American Numbering Plan formats (with +1 as the country code). For different countries formats, see [Phone Numbers and Locales](#phone-number-and-locales).
 
-This formatter will return one of the following formats:
+## Faker::PhoneNumber.phone_number
 
-  * 333-333-3333
-  * (333) 333-3333
-  * 1-333-333-3333
-  * 333.333.3333
-  * 333-333-3333 x3333
-  * (333) 333-3333 x3333
-  * 1-333-333-3333 x3333
-  * 333.333.3333 x3333
+Generates a phone number in a random format without the country code and it can have different dividers.
 
-Note: For formats with extensions, the extension can be inclusively between 3 and 5 digits long.
+```ruby
+Faker::PhoneNumber.phone_number #=> "(504) 113-1705"
+Faker::PhoneNumber.phone_number #=> "662.291.7201"
+Faker::PhoneNumber.phone_number #=> "9415283713"
+```
 
-### `.cell_phone`
+## Faker::PhoneNumber.cell_phone
 
-This formatter will return one of the following formats:
+Generates a random cell phone number in a random format without the country code and it can have different dividers.
 
-  * 333-333-3333
-  * (333) 333-3333
-  * 1-333-333-3333
-  * 333.333.3333
+```ruby
+Faker::PhoneNumber.cell_phone #=> "(836) 115-8995"
+Faker::PhoneNumber.cell_phone #=> "382-597-5739"
+Faker::PhoneNumber.cell_phone #=> "316.828.1822"
+```
 
-### `.cell_phone_in_e164`
+## Faker::PhoneNumber.country_code
 
-This formatter will return one of the following formats:
+Generates a random country code number.
 
-  * +33333333333333
-  * +3333333333333
+```ruby
+Faker::PhoneNumber.country_code #=> "+20"
+Faker::PhoneNumber.country_code #=> "+39"
+Faker::PhoneNumber.country_code #=> "+852"
+```
 
-## Locale
-By setting the locale, you can generate a phone number with a valid area code in that locale (and valid exchange code, where relevant).
+## Faker::PhoneNumber.phone_number_with_country_code
 
-### Locales with area codes
-```Faker::Config.locale = 'en-US'
-Faker::Config.locale = 'en-CA'
-Faker::Config.locale = 'fr-CA'
-Faker::Config.locale = 'en-AU'
-Faker::Config.locale = 'pt-BR'
-```
+Generates a random phone number with country code.
 
-### Locales with exchange codes
-```Faker::Config.locale = 'en-US'
-Faker::Config.locale = 'en-CA'
-Faker::Config.locale = 'fr-CA'
+```ruby
+Faker::PhoneNumber.phone_number_with_country_code #=> "+55 466-746-6882"
+Faker::PhoneNumber.phone_number_with_country_code #=> "+81 3718219558"
+Faker::PhoneNumber.phone_number_with_country_code #=> "+49 140 957 9846"
 ```
 
-## Usage
+## Faker::PhoneNumber.cell_phone_with_country_code
 
-Don't let the example output below fool you -- any format can be returned at random.
+Generates a random cell phone number with country code.
 
 ```ruby
-Faker::PhoneNumber.phone_number #=> "397.693.1309 x4321"
+Faker::PhoneNumber.cell_phone_with_country_code #=> "+852 (190) 987-9034"
+Faker::PhoneNumber.cell_phone_with_country_code #=> "+64 (820) 583-6474"
+Faker::PhoneNumber.cell_phone_with_country_code #=> "+1 591.871.7985"
+```
 
-Faker::PhoneNumber.cell_phone #=> "(186)285-7925"
+## Faker::PhoneNumber.cell_phone_in_e164
 
-Faker::PhoneNumber.cell_phone_in_e164 #=> "+944937040625"
+Generates a random phone number in e164 format, i.e., without any dividers.
 
-# NOTE NOTE NOTE NOTE
-# For these two 'Locale-specific' methods, first you must set a relevant locale as mentioned above, such as:
-Faker::Config.locale = 'en-US'
-# or for Canada
-Faker::Config.locale = 'en-CA'
+```ruby
+Faker::PhoneNumber.cell_phone_in_e164 #=> "+542024834991"
+Faker::PhoneNumber.cell_phone_in_e164 #=> "+8522846847703"
+Faker::PhoneNumber.cell_phone_in_e164 #=> "+649477546575"
+```
 
-# Locale-specific
+## Faker::PhoneNumber.area_code
+
+Generates a random area code.
+
+```ruby
 Faker::PhoneNumber.area_code #=> "201"
+Faker::PhoneNumber.area_code #=> "613"
+Faker::PhoneNumber.area_code #=> "321"
+```
+
+## Faker::PhoneNumber.exchange_code
 
-# Locale-specific
+Generates a random exchange code.
+
+```ruby
 Faker::PhoneNumber.exchange_code #=> "208"
+Faker::PhoneNumber.exchange_code #=> "415"
+Faker::PhoneNumber.exchange_code #=> "652"
+```
 
-# Keyword arguments: length
+## Faker::PhoneNumber.subscriber_number (alias Faker::PhoneNumber.extension)
+
+Generates a random extension / subscriber number. Can be used for both extensions and last four digits of phone number.
+
+```ruby
+# keyword arguments: length. Defaults to 4.
 Faker::PhoneNumber.subscriber_number #=> "3873"
 Faker::PhoneNumber.subscriber_number(length: 2) #=> "39"
-
 Faker::PhoneNumber.extension #=> "3764"
+Faker::PhoneNumber.extension(length: 2) => "37"
+```
 
-Faker::PhoneNumber.country_code #=> "+20"
+## Phone Number and Locales
 
-Faker::PhoneNumber.phone_number_with_country_code #=> "+95 1-672-173-8153"
+If no locale is set, Faker generates North American Numbering Plan formats (with +1 area code). For more accurate values when generating US or CA formats, it's
+recommended to set their locales accordingly:
 
-Faker::PhoneNumber.cell_phone_with_country_code #=> "+974 (190) 987-9034"
+```ruby
+# set locale first
+Faker::Config.locale = 'en-US'
+Faker::PhoneNumber.country_code #=> "+1"
+Faker::PhoneNumber.area_code #=> "504"
+Faker::PhoneNumber.exchange_code #=> "715"
+
+
+# set locale first
+Faker::Config.locale = 'en-CA'
+Faker::PhoneNumber.country_code #=> "+1"
+Faker::PhoneNumber.area_code #=> "226"
+Faker::PhoneNumber.exchange_code #=> "956"
+```
+
+Besides US and CA formats, Faker also generates phone numbers according to various locales. Here are some examples:
+
+```ruby
+Faker::Config.locale = 'da-DK'
+Faker::PhoneNumber.cell_phone_with_country_code # => "+45 20 76 45 76"
+
+Faker::Config.locale = 'de'
+Faker::PhoneNumber.cell_phone_with_country_code # => "+49 1559-7973422"
+
+Faker::Config.locale = 'pt-BR'
+Faker::PhoneNumber.cell_phone_with_country_code # => "+55 (77) 96227-7968"
 ```
diff --git a/lib/faker/default/phone_number.rb b/lib/faker/default/phone_number.rb
@@ -4,25 +4,29 @@ module Faker
   class PhoneNumber < Base
     class << self
       ##
-      # Produces a random phone number in a random format (may or may not have a country code, extension and can have different dividers).
+      # Produces a phone number in a random format without the country code and it can have different dividers.
       #
       # @return [String]
       #
       # @example
-      #   Faker::PhoneNumber.phone_number #=> "397.693.1309 x4321"
+      #   Faker::PhoneNumber.phone_number #=> "(504) 113-1705"
+      #   Faker::PhoneNumber.phone_number #=> "662.291.7201"
+      #   Faker::PhoneNumber.phone_number #=> "9415283713"
       #
       # @faker.version 0.3.0
       def phone_number
         parse('phone_number.formats')
       end
 
       ##
-      # Produces a random cell phone number in a random format (may or may not have a country code and can have different dividers).
+      # Produces a random cell phone number in a random format without the country code and it can have different dividers.
       #
       # @return [String]
       #
       # @example
-      #   Faker::PhoneNumber.cell_phone #=> "(186)285-7925"
+      #   Faker::PhoneNumber.cell_phone #=> "(836) 115-8995"
+      #   Faker::PhoneNumber.cell_phone #=> "382-597-5739"
+      #   Faker::PhoneNumber.cell_phone #=> "316.828.1822"
       #
       # @faker.version 1.0.0
       def cell_phone
@@ -36,10 +40,12 @@ def cell_phone
       #
       # @example
       #   Faker::PhoneNumber.country_code #=> "+20"
+      #   Faker::PhoneNumber.country_code #=> "+39"
+      #   Faker::PhoneNumber.country_code #=> "+852"
       #
       # @faker.version 1.9.2
       def country_code
-        "+#{fetch('country_code')}"
+        "+#{fetch('phone_number.country_code')}"
       end
 
       ##
@@ -48,7 +54,9 @@ def country_code
       # @return [String]
       #
       # @example
-      #   Faker::PhoneNumber.phone_number_with_country_code #=> "+95 1-672-173-8153"
+      #   Faker::PhoneNumber.phone_number_with_country_code #=> "+55 466-746-6882"
+      #   Faker::PhoneNumber.phone_number_with_country_code #=> "+81 3718219558"
+      #   Faker::PhoneNumber.phone_number_with_country_code #=> "+49 140 957 9846"
       #
       # @faker.version 1.9.2
       def phone_number_with_country_code
@@ -61,70 +69,81 @@ def phone_number_with_country_code
       # @return [String]
       #
       # @example
-      #   Faker::PhoneNumber.cell_phone_with_country_code #=> "+974 (190) 987-9034"
+      #   Faker::PhoneNumber.cell_phone_with_country_code #=> "+852 (190) 987-9034"
+      #   Faker::PhoneNumber.cell_phone_with_country_code #=> "+64 (820) 583-6474"
+      #   Faker::PhoneNumber.cell_phone_with_country_code #=> "+1 591.871.7985"
       #
       # @faker.version 1.9.2
       def cell_phone_with_country_code
         "#{country_code} #{cell_phone}"
       end
 
       ##
-      # Produces a random phone number in e164 format.
+      # Produces a random phone number in e164 format, i.e., without any dividers.
       #
       # @return [String]
       #
       # @example
-      #   Faker::PhoneNumber.cell_phone_in_e164 #=> "+944937040625"
+      #   Faker::PhoneNumber.cell_phone_in_e164 #=> "+542024834991"
+      #   Faker::PhoneNumber.cell_phone_in_e164 #=> "+8522846847703"
+      #   Faker::PhoneNumber.cell_phone_in_e164 #=> "+649477546575"
       #
       # @faker.version 1.9.2
       def cell_phone_in_e164
         cell_phone_with_country_code.delete('^+0-9')
       end
 
       ##
-      # Produces a random US or Canada-based area code.
+      # Produces a random area code.
       #
       # @return [String]
       #
       # @example
       #   Faker::PhoneNumber.area_code #=> "201"
+      #   Faker::PhoneNumber.area_code #=> "613"
+      #   Faker::PhoneNumber.area_code #=> "321"
       #
       # @faker.version 1.3.0
       def area_code
         fetch('phone_number.area_code')
-      rescue I18n::MissingTranslationData
-        nil
       end
 
       ##
-      # Produces a random US or Canada-based exchange code.
+      # Produces a random exchange code.
       #
       # @return [String]
       #
       # @example
       #   Faker::PhoneNumber.exchange_code #=> "208"
+      #   Faker::PhoneNumber.exchange_code #=> "415"
+      #   Faker::PhoneNumber.exchange_code #=> "652"
       #
       # @faker.version 1.3.0
       def exchange_code
         fetch('phone_number.exchange_code')
-      rescue I18n::MissingTranslationData
-        nil
       end
 
       ##
-      # Produces a random US or Canada-based extension / subscriber number. Can be used for both extensions and last four digits of phone number.
+      # Produces a random extension / subscriber number. Can be used for both extensions and last four digits of phone number.
       #
-      # @param length [Integer] Specifies the length of the return value.
+      # @param length [Integer] Specifies the length of the return value. Defaults to 4.
       # @return [String]
       #
       # @example
       #   Faker::PhoneNumber.subscriber_number #=> "3873"
       #   Faker::PhoneNumber.subscriber_number(length: 2) #=> "39"
       #   Faker::PhoneNumber.extension #=> "3764"
+      #   Faker::PhoneNumber.extension(length: 2) => "37"
       #
       # @faker.version 1.3.0
       def subscriber_number(length: 4)
-        rand.to_s[2..(1 + length)]
+        if !length.is_a?(Integer) || length > 10
+          raise ArgumentError, 'length must be an Integer and be lesser than 10'
+        end
+
+        generate(:string) do |g|
+          g.int(length: length)
+        end
       end
 
       alias extension subscriber_number