Module: Twilio::Rails::Formatter

Extended by:
Formatter
Included in:
Formatter
Defined in:
lib/twilio/rails/formatter.rb

Constant Summary collapse

PHONE_NUMBER_REGEX = 
/\A\+1[0-9]{10}\Z/
PHONE_NUMBER_SEGMENTS_REGEX = 
/\A\+1([0-9]{3})([0-9]{3})([0-9]{4})\Z/

Instance Method Summary collapse

Instance Method Details

#coerce_to_valid_phone_number(string) ⇒ String?

Takes in a string or a PhoneNumber or something that responds to ‘to_s` and turns it into a consistently formatted valid north american 10 digit phone number prefixed with 1 and plus. It uses the format Twilio expects which is “+15555555555” or returns `nil` if it cannot be coerced.

Parameters:

Returns:

  • (String, nil) —

    the phone number string or nil.



16
17
18
19
20
21
22
23
24
25
26
27
28
 
# File 'lib/twilio/rails/formatter.rb', line 16

def coerce_to_valid_phone_number(string)
  string = string.number if string.is_a?(Twilio::Rails::PhoneNumber)
  string = string.to_s.presence

  if string
    string = string.gsub(/[^0-9]/, "")
    string = "1#{ string }" unless string.starts_with?("1")
    string = "+#{ string }"
    string = nil unless valid_north_american_phone_number?(string)
  end

  string
end

#display_phone_number(phone_number) ⇒ String, Object

Takes in a string or a PhoneNumber or something that responds to ‘to_s` and turns it into a phone number string formatted for display. If the number cannot be coerced to a valid phone number it will be passed through.

Parameters:

Returns:

  • (String, Object) —

    the phone number string or the original object if invalid.



60
61
62
63
64
65
66
67
68
69
 
# File 'lib/twilio/rails/formatter.rb', line 60

def display_phone_number(phone_number)
  coerced_phone_number = coerce_to_valid_phone_number(phone_number)
  if coerced_phone_number
    matches = coerced_phone_number.match(PHONE_NUMBER_SEGMENTS_REGEX)
    raise Twilio::Rails::Error, "[display_phone_number] Phone number marked as valid but could not capture. I made a bad regex: #{ phone_number }" unless matches
    "(#{ matches.captures[0] }) #{ matches.captures[1] } #{ matches.captures[2] }"
  else
    phone_number
  end
end

#location(city: nil, country: nil, province: nil) ⇒ String

Formats a city, province, and country into a single string, correctly handling blanks, and formatting countries.

Parameters:

  • city (String, nil) (defaults to: nil) —

    the city name.

  • province (String, nil) (defaults to: nil) —

    the province name.

  • country (String, nil) (defaults to: nil) —

    the country code.

Returns:

  • (String) —

    the formatted location string.



77
78
79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/twilio/rails/formatter.rb', line 77

def location(city: nil, country: nil, province: nil)
  country_name = case country
  when "CA" then "Canada"
  when "US" then "USA"
  else
    country
  end

  [
    city.presence&.titleize,
    province,
    country_name,
  ].reject(&:blank?).join(", ")
end

#to_phone_number_url_param(phone_number) ⇒ String

Takes in a string or a PhoneNumber or something that responds to ‘to_s` and turns it into a phone number formatted for URLs. Appropriate to use for `#to_param` in Rails or other controller concerns where a phone number or phone caller can be passed around as a URL parameter.

Parameters:

Returns:

  • (String) —

    the phone number string or empty string if invalid.

Raises:



46
47
48
49
50
51
52
 
# File 'lib/twilio/rails/formatter.rb', line 46

def to_phone_number_url_param(phone_number)
  phone_number = coerce_to_valid_phone_number(phone_number)
  return "" unless phone_number
  matches = phone_number.match(PHONE_NUMBER_SEGMENTS_REGEX)
  raise Twilio::Rails::Error, "[to_phone_number_url_param] Phone number marked as valid but could not capture. I made a bad regex: #{ phone_number }" unless matches
  matches.captures.join("-")
end

#valid_north_american_phone_number?(phone_number) ⇒ true, false

Takes in a string or a PhoneNumber or something that responds to ‘to_s` and validates it matches the expected format “+15555555555” of a north american phone number.

Parameters:

Returns:

  • (true, false) 


35
36
37
38
 
# File 'lib/twilio/rails/formatter.rb', line 35

def valid_north_american_phone_number?(phone_number)
  phone_number = phone_number.number if phone_number.is_a?(Twilio::Rails::PhoneNumber)
  !!phone_number&.match?(PHONE_NUMBER_REGEX)
end