Skip to content

Commit

Permalink
Merge branch 'faker-ruby:main' into main
Browse files Browse the repository at this point in the history
  • Loading branch information
@kirkkwang
kirkkwang authored Nov 13, 2023
2 parents 9ea7a9c + 31d99d1 commit 1c8e604
Show file tree
Hide file tree
Showing 35 changed files with 54,372 additions and 6,440 deletions.
147 changes: 95 additions & 52 deletions doc/default/phone_number.md
View file
Original file line number Diff line number Diff line change
@@ -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"
```
55 changes: 37 additions & 18 deletions lib/faker/default/phone_number.rb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

##
Expand All @@ -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
Expand All @@ -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
Expand Down
Loading

0 comments on commit 1c8e604

Please sign in to comment.