phonelib 0.10.25 → 0.10.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84e2a8f47cd1fb8108efa26ab0ba6120bd6e28a420794acf7ee099135618ab1e
-  data.tar.gz: a15e47d9b2a941639e4dc83226143c01b314506482d7fdee63ed95afa0ba78f4
+  metadata.gz: e167c9f5d91a48e5bd9b336f41f95da24b5d147b2a2c5fc22ce9c860e7c105e7
+  data.tar.gz: db640f3955e5c5d4fd907bb25d3c4fa1c0bbb783a5245a5515366e4721e01994
 SHA512:
-  metadata.gz: 81a599c8844452b9d0124a8b75315905f85e79a31eedc3e14af66a830885fa0ebbe27aa9ebd65da57c7e710744d9147a1bf6304699049e0cd6452a8d698083bd
-  data.tar.gz: baf0e046b6eea13ae466c97b6a065f2fe9bf6fc496992424ebe78fd51d177acf72cefe8b53bdcae07d0fc2b6a6e42323966558fe593a4f57f22780d7aecf3fd5
+  metadata.gz: 81acdf0374d5fb09daa882cb27ec95f79f39bab2ea8539c67f55aca156eb2516ddaa29d6757cc38ce8860feef5aa74654be96cbdc1c83cc000002495195250e8
+  data.tar.gz: 7080901f2d6d0a235f76fc9f1094775190f32e7036b336e1c719f5b2fc1b8412c66d9edea4fa357863a04f916d5c86b20489b2ab36cd3c9b1d2ea35677784fcb

data/README.md

@@ -154,6 +154,59 @@ if mixed with <tt>possible</tt> will check if number is possible for specified c
 
 <tt>extensions: false</tt> - set to perform check for phone extension to be blank
 
+<<<<<<< HEAD
+<tt>require_international_prefix: true</tt> - requires the original value to use <tt>+</tt> or <tt>00</tt> as its explicit international marker. The marker may follow leading formatting characters recognized by the parser. This option does not change the parser or the formatted output.
+
+<tt>format: :e164</tt> - requires the original value to match Phonelib's canonical <tt>+</tt>-prefixed E.164 representation: 2 to 15 total ASCII digits, beginning with 1-9, with no spaces, punctuation, or extension. Unsupported formats raise an <tt>ArgumentError</tt> when the validator is configured.
+
+||||||| ec5e850
+=======
+<tt>require_international_prefix: true</tt> - requires the original value to use <tt>+</tt> or <tt>00</tt> as its explicit international marker. The marker may follow leading formatting characters recognized by the parser. This option does not change the parser or the formatted output.
+
+<tt>format: :e164</tt> - requires the original value to match Phonelib's canonical <tt>+</tt>-prefixed E.164 representation: 2 to 15 total ASCII digits, beginning with 1-9, with no spaces, punctuation, or extension. Unsupported formats raise an <tt>ArgumentError</tt> when the validator is configured.
+
+<tt>detailed_errors: true</tt> - adds a specific, namespaced ActiveModel error
+for each failed phone rule. It is opt-in; without it the validator keeps adding
+the single <tt>:invalid</tt> error used by previous Phonelib versions. Enabling
+it changes error reporting only, not which values the existing validator
+accepts.
+
+``` ruby
+validates :phone, phone: {
+  types: :mobile,
+  countries: :us,
+  extensions: false,
+  detailed_errors: true
+}
+
+record.errors.details[:phone] # ActiveModel 5+
+# [{ error: :phone_type_not_allowed, allowed_types: [:mobile], ... }]
+
+record.errors.messages[:phone]
+# ["has a phone type that is not allowed"]
+
+record.errors.full_messages
+# ["Phone has a phone type that is not allowed"]
+```
+
+On older ActiveModel versions, the detailed types still drive translated
+<tt>errors.messages</tt>, but <tt>Errors#details</tt> is not provided by the
+framework.
+
+Detailed ActiveModel error types are prefixed with <tt>phone_</tt> so they do
+not collide with generic Rails errors such as <tt>:too_short</tt>. Phonelib
+ships English defaults for every detailed error. Applications can override
+them through the normal I18n hierarchy, for example:
+
+``` yaml
+es:
+  errors:
+    messages:
+      phone_too_short: "es demasiado corto"
+      phone_invalid: "no es un número telefónico válido"
+```
+
+>>>>>>> salasebas-salasebas/structured-validation-errors
 ### Basic usage
 
 To check if phone number is valid simply run:
@@ -187,6 +240,73 @@ phone = Phonelib.parse('123456789')
 phone = Phonelib.parse('+1 (972) 123-4567', 'US')
 ```
 
+Parsed phones expose immutable validation diagnostics without requiring Rails:
+
+``` ruby
+phone = Phonelib.parse('+1 253000')
+
+phone.errors.details
+# [{ error: :too_short, actual_length: 6, expected_lengths: [10] }]
+
+phone.errors.messages
+# ["is too short"]
+
+phone.errors.full_messages
+# ["is too short"] # no model attribute exists in the core API
+```
+
+Use <tt>validation</tt> when the result or a validation policy is also needed:
+
+``` ruby
+result = phone.validation(
+  possible: true,
+  types: :mobile,
+  countries: [:us, :ca],
+  extensions: false
+)
+
+result.valid?       # whether all requested rules passed
+result.invalid?
+result.phone        # the same parsed Phone instance
+result.errors       # Phonelib::Errors
+result.error        # first ValidationError, or nil
+result.possibility  # :possible, :possible_local_only, or :impossible
+```
+
+<tt>possible_local_only</tt> means the number has a length that can be dialed
+within its local area but lacks the information required for general dialing.
+It is exposed as diagnostic context; <tt>validation(possible: true)</tt> still
+follows the existing <tt>Phone#possible?</tt> result and therefore reports
+<tt>:not_possible</tt> for a local-only number.
+
+Core diagnostic codes are deliberately short because they already live in
+<tt>Phonelib::ValidationError</tt>:
+
+* <tt>:not_a_number</tt>
+* <tt>:invalid_country_code</tt>
+* <tt>:too_short</tt>
+* <tt>:too_long</tt>
+* <tt>:invalid_length</tt>
+* <tt>:not_possible</tt>
+* <tt>:invalid</tt>
+* <tt>:type_not_allowed</tt>
+* <tt>:country_not_allowed</tt>
+* <tt>:extension_not_allowed</tt>
+
+Successful validity and possibility are represented by the result, not by
+error codes.
+
+Messages can be translated in plain Ruby without adding an I18n dependency to
+Phonelib. Pass any callable that accepts an I18n-style key and keyword values:
+
+``` ruby
+translator = -> key, default:, **values do
+  I18n.t(key, default: default, **values)
+end
+
+phone.errors.messages(translator: translator)
+```
+
 You can pass phone number with extension, it should be separated with <tt>;</tt> or <tt>#</tt> signs from the phone number.
 
 Returned value is object of <tt>Phonelib::Phone</tt> class which have following methods:

data/lib/phonelib/core.rb

@@ -184,6 +184,8 @@ module Phonelib
     # setter for data file to use
     def override_phone_data=(file_path)
       @@override_phone_data = file_path
+      @@phone_data = @@data_by_country_codes = @@all_int_prefixes = nil
+      @@phone_regexp_cache.clear
     end
 
     def override_phone_data
@@ -308,6 +310,10 @@ module Phonelib
     VALID_PATTERN = :national_number_pattern
     # @private Possible regex pattern key
     POSSIBLE_PATTERN = :possible_number_pattern
+    # @private Possible national number lengths imported from libphonenumber
+    POSSIBLE_LENGTHS = :possible_lengths
+    # @private Possible local-only number lengths imported from libphonenumber
+    POSSIBLE_LOCAL_ONLY_LENGTHS = :possible_local_only_lengths
     # @private National prefix key
     NATIONAL_PREFIX = :national_prefix
     # @private National prefix for parsing key

data/lib/phonelib/data_importer.rb

@@ -243,19 +243,29 @@ module Phonelib
         @data[country_id][:types][type][Core::SHORT] ||= {}
         data.each do |k, v|
           if @data[country_id][:types][type][Core::SHORT][k]
-            @data[country_id][:types][type][Core::SHORT][k] += "|#{v}"
+            if possible_lengths_key?(k)
+              @data[country_id][:types][type][Core::SHORT][k] =
+                  (@data[country_id][:types][type][Core::SHORT][k] + v).uniq.sort
+            else
+              @data[country_id][:types][type][Core::SHORT][k] += "|#{v}"
+            end
           else
             @data[country_id][:types][type][Core::SHORT][k] = v
           end
         end
       end
 
+      def possible_lengths_key?(key)
+        [Core::POSSIBLE_LENGTHS, Core::POSSIBLE_LOCAL_ONLY_LENGTHS].include?(key)
+      end
+
       # adds possible pattern in case it doesn't exists
       def fill_possible_to_types_if_nil(result)
         result[:types].each do |type, data|
           if data[Core::VALID_PATTERN] && !data[Core::POSSIBLE_PATTERN]
             result[:types][type][Core::POSSIBLE_PATTERN] = case type
                   when Core::GENERAL
+                    fill_general_possible_lengths(result[:types], data)
                     national_possible result[:types]
                   else
                     data[Core::VALID_PATTERN]
@@ -265,10 +275,33 @@ module Phonelib
         result
       end
 
+      def fill_general_possible_lengths(types, general)
+        national = concrete_possible_lengths(types, Core::POSSIBLE_LENGTHS)
+        local_only = concrete_possible_lengths(
+          types,
+          Core::POSSIBLE_LOCAL_ONLY_LENGTHS
+        ) - national
+        general[Core::POSSIBLE_LENGTHS] = national unless national.empty?
+        unless local_only.empty?
+          general[Core::POSSIBLE_LOCAL_ONLY_LENGTHS] = local_only
+        end
+      end
+
+      def concrete_possible_lengths(types, key)
+        lengths = []
+        types.each do |type, data|
+          next if type == Core::GENERAL || !data[key]
+
+          lengths.concat(data[key].select { |length| length > 0 })
+        end
+        lengths.uniq.sort
+      end
+
       # take all possible patters from all types
       def national_possible(types)
         types.map { |k, v| v[:possible_number_pattern] }.
-            compact.map { |e| e.split('|') }.flatten.uniq.join('|')
+            compact.reject { |pattern| pattern == '(?!)' }.
+            map { |e| e.split('|') }.flatten.uniq.join('|')
       end
 
       # method parses xml for formats data

data/lib/phonelib/data_importer_helper.rb

@@ -7,6 +7,8 @@ module Phonelib
     XML_COMMENT_ATTRIBUTES = %w(text comment)
     # xml format attributes names
     XML_FORMAT_NAMES = %w(intlFormat format)
+    # libphonenumber's maximum supported national significant number length
+    MAX_POSSIBLE_LENGTH = 17
 
     def file_path(file)
       "#{File.dirname(__FILE__)}/../../#{file}"
@@ -83,8 +85,16 @@ module Phonelib
       when :element
         data.elements.each do |child|
           if child.name == 'possibleLengths'
-            hash[Core::POSSIBLE_PATTERN] =
-                possible_length_regex(hash_from_xml(child, :attributes))
+            attributes = hash_from_xml(child, :attributes)
+            hash[Core::POSSIBLE_PATTERN] = possible_length_regex(attributes)
+
+            national_lengths = possible_lengths(attributes[:national])
+            hash[Core::POSSIBLE_LENGTHS] = national_lengths unless national_lengths.empty?
+
+            local_only_lengths = possible_lengths(attributes[:local_only])
+            unless local_only_lengths.empty?
+              hash[Core::POSSIBLE_LOCAL_ONLY_LENGTHS] = local_only_lengths
+            end
           else
             hash[name2sym(child.name)] = str_clean(child.children.first)
           end
@@ -95,15 +105,58 @@ module Phonelib
 
     def possible_length_regex(attributes)
       return '' unless attributes[:national]
-      attributes[:national].split(',').map do |m|
-        if m.include? '-'
-          "\\d{#{m.gsub(/[\[\]]/, '').gsub('-', ',')}}"
+
+      possible_length_ranges(attributes[:national]).map do |first, last|
+        if first == -1
+          '(?!)'
+        elsif first == last
+          "\\d{#{first}}"
         else
-          "\\d{#{m}}"
+          "\\d{#{first},#{last}}"
         end
       end.join('|')
     end
 
+    def possible_lengths(lengths)
+      return [] unless lengths
+
+      possible_length_ranges(lengths).flat_map do |first, last|
+        first == -1 ? [-1] : (first..last).to_a
+      end.uniq.sort
+    end
+
+    def possible_length_ranges(lengths)
+      lengths.split(',').map do |length|
+        raw_token = length
+        token = if raw_token.include?('[') || raw_token.include?(']')
+                  unless raw_token =~ /\A\[\d+(?:-\d+)?\]\z/
+                    raise ArgumentError, "invalid possible length: #{raw_token}"
+                  end
+                  raw_token[1..-2]
+                else
+                  raw_token
+                end
+        unless token =~ /\A(?:-1|\d+(?:-\d+)?)\z/
+          raise ArgumentError, "invalid possible length: #{raw_token}"
+        end
+
+        next [-1, -1] if token == '-1'
+
+        first, last = token.split('-').map(&:to_i)
+        last ||= first
+        [first, last].each do |value|
+          unless (1..MAX_POSSIBLE_LENGTH).include?(value)
+            raise ArgumentError, "possible length out of range: #{value}"
+          end
+        end
+        if first > last
+          raise ArgumentError, "invalid possible length range: #{token}"
+        end
+
+        [first, last]
+      end
+    end
+
     # method parses raw data file
     def parse_raw_file(file)
       data = {}

data/lib/phonelib/errors.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Phonelib
+  # Read-only collection of phone validation errors.
+  class Errors
+    include Enumerable
+
+    def initialize(errors = [])
+      @errors = errors.dup.freeze
+      freeze
+    end
+
+    def each(&block)
+      @errors.each(&block)
+    end
+
+    def empty?
+      @errors.empty?
+    end
+
+    def size
+      @errors.size
+    end
+
+    def first
+      @errors.first
+    end
+
+    def details
+      @errors.map { |error| { error: error.code }.merge(error.details).freeze }.freeze
+    end
+
+    def messages(options = {})
+      translator = options.is_a?(Hash) ? options[:translator] : options
+      @errors.map { |error| error.message(translator) }.freeze
+    end
+
+    def full_messages(options = {})
+      messages(options)
+    end
+  end
+end

data/lib/phonelib/locale/en.yml

@@ -0,0 +1,13 @@
+en:
+  errors:
+    messages:
+      phone_not_a_number: "is not a phone number"
+      phone_invalid_country_code: "has an invalid country calling code"
+      phone_too_short: "is too short"
+      phone_too_long: "is too long"
+      phone_invalid_length: "has an invalid length"
+      phone_not_possible: "is not a possible phone number"
+      phone_invalid: "is not a valid phone number"
+      phone_type_not_allowed: "has a phone type that is not allowed"
+      phone_country_not_allowed: "is from a country that is not allowed"
+      phone_extension_not_allowed: "must not include an extension"

data/lib/phonelib/phone.rb

@@ -17,6 +17,7 @@ module Phonelib
     include Phonelib::PhoneAnalyzer
     include Phonelib::PhoneExtendedData
     include Phonelib::PhoneFormatter
+    include Phonelib::PhoneValidation
 
     # class initialization method
     # @param phone [String] Phone number for parsing
@@ -30,12 +31,15 @@ module Phonelib
 
       if sanitized.empty?
         @data = {}
+        @diagnostic_possibility = :impossible
       else
-        @data = analyze(sanitized, passed_country(country))
+        @passed_country = passed_country(country)
+        @data = analyze(sanitized, @passed_country)
         # the national number must come from the country #country reports:
         # another entry can be a possible-only match, and mixing entries makes
         # e164 splice one country's code onto another's number (issue #355)
         @national_number = country_data ? country_data[:national] : sanitized
+        @diagnostic_possibility = diagnostic_possibility
       end
     end
 
@@ -62,6 +66,13 @@ module Phonelib
               '')
     end
 
+    # Returns whether the original input begins with an explicit + or 00
+    # international prefix after parser-recognized leading formatting.
+    # @return [Boolean] original input has an explicit international prefix
+    def explicit_international_prefix?
+      !!original_starts_with_plus_or_double_zero?
+    end
+
     # Returns all phone types that matched valid patterns
     # @return [Array] all valid phone types
     def types

data/lib/phonelib/phone_validation.rb

@@ -0,0 +1,338 @@
+# frozen_string_literal: true
+
+module Phonelib
+  # Framework-independent diagnostics and policy validation for a parsed phone.
+  module PhoneValidation
+    VALIDATION_OPTIONS = [:possible, :types, :countries, :extensions].freeze
+    VALID_TYPE_NAMES = Core::TYPES_DESC_KEYS.map(&:to_s).freeze
+    MAX_VALIDATION_VALUES = 300
+    private_constant :VALIDATION_OPTIONS, :VALID_TYPE_NAMES,
+                     :MAX_VALIDATION_VALUES
+
+    # Returns an immutable result explaining whether this phone satisfies the
+    # requested rules and, when it does not, why.
+    # @param options [Hash] phone validation rules
+    # @return [Phonelib::ValidationResult]
+    def validation(options = {})
+      validate_options!(options)
+      possible = options.fetch(:possible, false)
+      possibility = diagnostic_possibility
+      validation_errors = intrinsic_validation_errors(possible, possibility)
+      if validation_errors.empty?
+        validation_errors.concat(policy_validation_errors(options, possible))
+      end
+
+      ValidationResult.new(self, validation_errors, possibility)
+    end
+
+    # Convenience accessor for validation diagnostics.
+    # @param options [Hash] phone validation rules
+    # @return [Phonelib::Errors]
+    def errors(options = {})
+      validation(options).errors
+    end
+
+    private
+
+    def validate_options!(options)
+      unknown_options = options.keys - VALIDATION_OPTIONS
+      if unknown_options.any?
+        raise ArgumentError, "unknown validation option: #{unknown_options.first}"
+      end
+
+      validate_boolean_option!(:possible, options.fetch(:possible, false))
+      validate_boolean_option!(:extensions, options.fetch(:extensions, true))
+      validate_collection_option!(:types, options[:types])
+      validate_collection_option!(:countries, options[:countries])
+    end
+
+    def validate_boolean_option!(name, value)
+      return if value == true || value == false
+
+      raise ArgumentError, "#{name} must be true or false"
+    end
+
+    def validate_collection_option!(name, value)
+      return if value.nil?
+
+      values = value.is_a?(Array) ? value : [value]
+      if values.size > MAX_VALIDATION_VALUES
+        raise ArgumentError,
+              "#{name} must contain at most #{MAX_VALIDATION_VALUES} values"
+      end
+      unless values.all? { |item| item.is_a?(String) || item.is_a?(Symbol) }
+        raise ArgumentError, "#{name} must be a symbol, string, or array of them"
+      end
+      validate_type_names!(values) if name == :types
+    end
+
+    def validate_type_names!(values)
+      unknown = values.find { |item| !VALID_TYPE_NAMES.include?(item.to_s) }
+      raise ArgumentError, "unknown phone type: #{unknown}" if unknown
+    end
+
+    def intrinsic_validation_errors(possible, possibility)
+      if possible
+        return [] if possible?
+        if possibility != :impossible
+          return [ValidationError.new(:not_possible, possibility: possibility)]
+        end
+      end
+      return [] if !possible && valid?
+      return [ValidationError.new(:invalid)] if possibility != :impossible
+
+      diagnostic_error = intrinsic_diagnostic_error
+      return [diagnostic_error] if diagnostic_error
+
+      [ValidationError.new(:not_possible)]
+    end
+
+    def intrinsic_diagnostic_error
+      return ValidationError.new(:not_a_number) unless viable_input?
+      parser_length = parser_national_length
+      if parser_length && parser_length > 17
+        return ValidationError.new(
+          :too_long,
+          actual_length: parser_length
+        )
+      end
+      return ValidationError.new(:invalid_country_code) if passed_country_invalid?
+
+      idd_remainder = digits_after_international_dialing_prefix
+      if idd_remainder && idd_remainder.length <= 2
+        return ValidationError.new(
+          :too_short,
+          actual_length: idd_remainder.length
+        )
+      end
+
+      international_digits = international_digits_for_diagnostics
+      if international_digits && country_calling_code_for(international_digits).nil?
+        return ValidationError.new(:invalid_country_code)
+      end
+      national_length_error = short_national_number_error(international_digits)
+      return national_length_error if national_length_error
+
+      possibility_length_error
+    end
+
+    def viable_input?
+      candidate = significant_original_s.sub(cr('[^0-9A-Za-z]+\z'), '')
+      return false if Phonelib.strict_check && !sanitized.match?(cr('\A[0-9]+\z'))
+
+      minimum_digits = candidate.match?(cr('\A[0-9]+\z')) ? 2 : 3
+      sanitized.length >= minimum_digits
+    end
+
+    def parser_national_length
+      international_digits = international_digits_for_diagnostics
+      return sanitized.length unless international_digits
+
+      country_code = country_calling_code_for(international_digits)
+      international_digits.delete_prefix(country_code).length if country_code
+    end
+
+    def passed_country_invalid?
+      return false if significant_original_s.start_with?(Core::PLUS_SIGN)
+
+      passed_countries = Array(@passed_country).compact
+      passed_countries.any? && passed_countries.none? do |country|
+        Phonelib.phone_data.key?(normalize_passed_country(country))
+      end
+    end
+
+    def short_national_number_error(international_digits)
+      return unless international_digits
+
+      country_code = country_calling_code_for(international_digits)
+      national_digits = international_digits.delete_prefix(country_code)
+      return unless national_digits.length < 2
+
+      ValidationError.new(
+        :too_short,
+        actual_length: national_digits.length
+      )
+    end
+
+    def possibility_length_error
+      context = diagnostic_number_context
+      return unless context
+
+      national_digits, data = context
+      lengths = possible_lengths_for(data)
+      local_only_lengths = possible_local_only_lengths_for(data)
+      return if lengths.empty? || lengths.include?(national_digits.length) ||
+                local_only_lengths.include?(national_digits.length)
+
+      code = if national_digits.length < lengths.min
+               :too_short
+             elsif national_digits.length > lengths.max
+               :too_long
+             else
+               :invalid_length
+             end
+      ValidationError.new(
+        code,
+        actual_length: national_digits.length,
+        expected_lengths: lengths
+      )
+    end
+
+    def diagnostic_possibility
+      return @diagnostic_possibility if defined?(@diagnostic_possibility)
+
+      return :impossible if passed_country_invalid?
+      return :impossible unless viable_input?
+      return :possible if possible_special_number?
+
+      context = diagnostic_number_context
+      return possible? ? :possible : :impossible unless context
+
+      national_digits, data = context
+      length = national_digits.length
+      return :possible if possible_lengths_for(data).include?(length)
+      return :possible if additional_regex_possible?(national_digits, data)
+      return :possible_local_only if possible_local_only_lengths_for(data).include?(length)
+
+      :impossible
+    end
+
+    def possible_special_number?
+      Phonelib.parse_special && (possible_types & Core::SHORT_CODES).any?
+    end
+
+    def additional_regex_possible?(national_digits, data)
+      candidate_countries = countries.any? ? countries : [data[:id]]
+      candidate_countries.any? do |country|
+        regexes = Phonelib.additional_regexes[country]
+        regexes && regexes.values.flatten.any? do |regex|
+          national_digits.match?(cr("^(?:#{regex})$"))
+        end
+      end
+    end
+
+    def diagnostic_number_context
+      international_digits = international_digits_for_diagnostics
+      if international_digits
+        country_code = country_calling_code_for(international_digits)
+        return unless country_code
+
+        countries_data = Phonelib.data_by_country_codes[country_code]
+        data = countries_data.find do |candidate|
+          candidate[Core::MAIN_COUNTRY_FOR_CODE] == 'true'
+        end || countries_data.first
+        national_digits = if valid? || possible?
+                            @national_number
+                          else
+                            international_digits.delete_prefix(country_code)
+                          end
+        return [national_digits, data]
+      end
+
+      resolved_country = self.country
+      data = resolved_country && Phonelib.phone_data[resolved_country]
+      unless data
+        supplied_country = Array(
+          @passed_country || Phonelib.default_country
+        ).compact.first
+        data = supplied_country && Phonelib.phone_data[
+          normalize_passed_country(supplied_country)
+        ]
+      end
+      [@national_number || sanitized, data] if data
+    end
+
+    def international_digits_for_diagnostics
+      if !Phonelib.ignore_plus &&
+         significant_original_s.start_with?(Core::PLUS_SIGN)
+        return sanitized
+      end
+
+      digits_after_international_dialing_prefix
+    end
+
+    def possible_lengths_for(data)
+      general = data[Core::TYPES][Core::GENERAL]
+      lengths = general[Core::POSSIBLE_LENGTHS]
+      return lengths if lengths.is_a?(Array)
+
+      regex = general[Core::POSSIBLE_PATTERN]
+      return [] unless regex
+
+      (1..17).select { |length| ('0' * length).match?(cr("^(?:#{regex})$")) }
+    end
+
+    def possible_local_only_lengths_for(data)
+      lengths = data[Core::TYPES][Core::GENERAL][Core::POSSIBLE_LOCAL_ONLY_LENGTHS]
+      lengths.is_a?(Array) ? lengths : []
+    end
+
+    def digits_after_international_dialing_prefix
+      diagnostic_countries.each do |country|
+        data = Phonelib.phone_data[country]
+        next unless data && data[Core::INTERNATIONAL_PREFIX]
+
+        prefix = sanitized.match(cr("^(?:#{data[Core::INTERNATIONAL_PREFIX]})"))
+        return sanitized[prefix[0].length..-1] if prefix
+      end
+      nil
+    end
+
+    def diagnostic_countries
+      Array(@passed_country || Phonelib.default_country).compact.map do |country|
+        normalize_passed_country(country)
+      end
+    end
+
+    def country_calling_code_for(digits)
+      (1..3).map { |length| digits[0, length] }.find do |code|
+        Phonelib.data_by_country_codes.key?(code)
+      end
+    end
+
+    def policy_validation_errors(options, possible)
+      errors = []
+      allowed_types = normalize_validation_values(options[:types]) { |type| type.to_sym }
+      matched_types = possible ? possible_types : types
+      expanded_types = matched_types.dup
+      if expanded_types.include?(Core::FIXED_OR_MOBILE)
+        expanded_types += Core::FIXED_LINE_OR_MOBILE_ARRAY
+      end
+      if !options[:types].nil? && (expanded_types & allowed_types).empty?
+        errors << ValidationError.new(
+          :type_not_allowed,
+          allowed_types: allowed_types,
+          matched_types: matched_types
+        )
+      end
+
+      allowed_countries = normalize_validation_values(options[:countries]) do |country|
+        country.to_s.upcase
+      end
+      matched_countries = possible ? possible_policy_countries : valid_countries
+      if !options[:countries].nil? && (matched_countries & allowed_countries).empty?
+        errors << ValidationError.new(
+          :country_not_allowed,
+          allowed_countries: allowed_countries,
+          matched_countries: matched_countries
+        )
+      end
+
+      if options.fetch(:extensions, true) == false && !extension.to_s.empty?
+        errors << ValidationError.new(:extension_not_allowed, extension_present: true)
+      end
+      errors
+    end
+
+    def possible_policy_countries
+      return countries if countries.any?
+
+      context = diagnostic_number_context
+      context ? [context.last[:id]].compact : []
+    end
+
+    def normalize_validation_values(value)
+      Array(value).map { |item| yield(item) }.uniq.freeze
+    end
+  end
+end

data/lib/phonelib/railtie.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Phonelib
+  class Railtie < Rails::Railtie
+    initializer 'phonelib' do |app|
+      app.config.eager_load_namespaces << Phonelib
+
+      locale_files = Dir[File.expand_path('phonelib/locale/*.yml', __dir__)]
+      app.config.i18n.load_path = locale_files | app.config.i18n.load_path if defined?(I18n)
+    end
+  end
+end

data/lib/phonelib/validation_error.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Phonelib
+  # A framework-independent, immutable phone validation diagnostic.
+  class ValidationError
+    DEFAULT_MESSAGES = {
+      not_a_number: 'is not a phone number',
+      invalid_country_code: 'has an invalid country calling code',
+      too_short: 'is too short',
+      too_long: 'is too long',
+      invalid_length: 'has an invalid length',
+      not_possible: 'is not a possible phone number',
+      invalid: 'is not a valid phone number',
+      type_not_allowed: 'has a phone type that is not allowed',
+      country_not_allowed: 'is from a country that is not allowed',
+      extension_not_allowed: 'must not include an extension'
+    }.freeze
+
+    attr_reader :code, :details
+
+    def initialize(code, details = {})
+      @code = DEFAULT_MESSAGES.keys.find { |key| key.to_s == code.to_s }
+      unless @code
+        raise ArgumentError, "unknown validation error code: #{code}"
+      end
+      @details = immutable_copy(details)
+      freeze
+    end
+
+    def i18n_key
+      "phonelib.errors.#{code}".to_sym
+    end
+
+    def message(translator = nil)
+      default = DEFAULT_MESSAGES.fetch(code, code.to_s.tr('_', ' '))
+      return default unless translator
+
+      translator.call(i18n_key, **{ default: default }.merge(details))
+    end
+
+    private
+
+    def immutable_copy(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, item), copy|
+          copy[key] = immutable_copy(item)
+        end.freeze
+      when Array
+        value.map { |item| immutable_copy(item) }.freeze
+      when String
+        value.dup.freeze
+      else
+        value
+      end
+    end
+  end
+end

data/lib/phonelib/validation_result.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Phonelib
+  # Immutable outcome of validating a parsed phone against a rule set.
+  class ValidationResult
+    attr_reader :phone, :errors, :possibility
+
+    def initialize(phone, errors, possibility)
+      @phone = phone
+      @errors = Errors.new(errors)
+      @possibility = possibility
+      freeze
+    end
+
+    def valid?
+      errors.empty?
+    end
+
+    def invalid?
+      !valid?
+    end
+
+    def error
+      errors.first
+    end
+  end
+end

data/lib/phonelib/version.rb

@@ -2,5 +2,5 @@
 
 module Phonelib
   # @private
-  VERSION = '0.10.25'
+  VERSION = '0.10.26'
 end

data/lib/phonelib.rb

@@ -8,19 +8,18 @@ module Phonelib
   require 'phonelib/phone_analyzer_helper'
   require 'phonelib/phone_analyzer'
   require 'phonelib/phone_extended_data'
+  require 'phonelib/validation_error'
+  require 'phonelib/errors'
+  require 'phonelib/validation_result'
+  require 'phonelib/phone_validation'
   require 'phonelib/phone'
 
   extend Core
 end
 
-if defined?(ActiveModel) || defined?(Rails)
-  autoload :PhoneValidator, 'validators/phone_validator'
+autoload :PhoneValidator, 'validators/phone_validator'
 
-  if defined?(Rails)
-    class Phonelib::Railtie < Rails::Railtie
-      initializer 'phonelib' do |app|
-        app.config.eager_load_namespaces << Phonelib
-      end
-    end
-  end
-end
+locale_files = Dir[File.expand_path('phonelib/locale/*.yml', __dir__)]
+I18n.load_path = locale_files | I18n.load_path if defined?(I18n)
+
+require 'phonelib/railtie' if defined?(Rails::Railtie)

data/lib/validators/phone_validator.rb

@@ -53,18 +53,51 @@
 #     validates :number, phone: { extensions: false }
 #   end
 #
+# Validates that the original value includes an explicit international prefix.
+# Both + and 00 prefixes are accepted.
+#
+#   class Phone < ActiveRecord::Base
+#     validates :number, phone: { require_international_prefix: true }
+#   end
+#
+# Validates that the original value uses canonical E.164 input format.
+#
+#   class Phone < ActiveRecord::Base
+#     validates :number, phone: { format: :e164 }
+#   end
+#
+
+if defined?(I18n)
+  locale_files = Dir[File.expand_path('../phonelib/locale/*.yml', __dir__)]
+  I18n.load_path = locale_files | I18n.load_path
+end
+
 class PhoneValidator < ActiveModel::EachValidator
+  E164_PATTERN = /\A\+[1-9][0-9]{1,14}\z/
+  SUPPORTED_FORMATS = [:e164, 'e164'].freeze
+
   # Include all core methods
   include Phonelib::Core
 
+  def check_validity!
+    return unless options.has_key?(:format)
+    return if SUPPORTED_FORMATS.include?(options[:format])
+
+    raise ArgumentError, "Unsupported phone format: #{options[:format]}"
+  end
+
   # Validation method
   def validate_each(record, attribute, value)
     return if options[:allow_blank] && value.blank?
 
-    @phone = parse(value, specified_country(record))
-    valid = phone_valid? && valid_types? && valid_country? && valid_extensions?
+    phone = parse(value, specified_country(record))
+    if detailed_errors?
+      return validate_with_details(record, attribute, phone)
+    end
 
-    record.errors.add(attribute, message, **options) unless valid
+    valid = phone_valid?(phone) && valid_types?(phone) && valid_country?(phone) &&
+            valid_extensions?(phone) && valid_input_format?(value)
+    record.errors.add(attribute, message, **legacy_error_options) unless valid
   end
 
   private
@@ -73,23 +106,84 @@ class PhoneValidator < ActiveModel::EachValidator
     options[:message] || :invalid
   end
 
-  def phone_valid?
-    @phone.send(options[:possible] ? :possible? : :valid?)
+  def detailed_errors?
+    options[:detailed_errors]
+  end
+
+  def legacy_error_options
+    options.reject { |key, _value| key == :detailed_errors }
+  end
+
+  def validate_with_details(record, attribute, phone)
+    result = phone.validation(
+      possible: !!options[:possible],
+      types: detailed_types,
+      countries: detailed_countries,
+      extensions: extensions_allowed?
+    )
+    return if result.valid?
+
+    result.errors.each do |error|
+      record.errors.add(
+        attribute,
+        "phone_#{error.code}".to_sym,
+        **detailed_error_options(error)
+      )
+    end
+  end
+
+  def detailed_error_options(error)
+    details = error.details.dup
+    details.delete(:error)
+    details.delete('error')
+    details[:message] = options[:message] if options.key?(:message)
+    details[:strict] = options[:strict] if options.key?(:strict)
+    details
+  end
+
+  def detailed_types
+    types.uniq if options[:types]
   end
 
-  def valid_types?
+  def detailed_countries
+    return unless options[:countries]
+
+    countries.uniq.select { |country| Phonelib.phone_data.key?(country) }
+  end
+
+  def phone_valid?(phone)
+    phone.send(options[:possible] ? :possible? : :valid?)
+  end
+
+  def valid_types?(phone)
     return true unless options[:types]
-    (phone_types & types).size > 0
+    (phone_types(phone) & types).size > 0
   end
 
-  def valid_country?
+  def valid_country?(phone)
     return true unless options[:countries]
-    (phone_countries & countries).size > 0
+    (phone_countries(phone) & countries).size > 0
+  end
+
+  def valid_extensions?(phone)
+    return true if extensions_allowed?
+    phone.extension.empty?
+  end
+
+  def extensions_allowed?
+    !options.has_key?(:extensions) || !!options[:extensions]
   end
 
-  def valid_extensions?
-    return true if !options.has_key?(:extensions) || options[:extensions]
-    @phone.extension.empty?
+  def valid_international_prefix?
+    return true unless options[:require_international_prefix]
+
+    @phone.explicit_international_prefix?
+  end
+
+  def valid_input_format?(value)
+    return true unless options[:format]
+
+    SUPPORTED_FORMATS.include?(options[:format]) && value.is_a?(String) && value.match?(E164_PATTERN)
   end
 
   def specified_country(record)
@@ -103,9 +197,9 @@ class PhoneValidator < ActiveModel::EachValidator
   end
 
   # @private
-  def phone_types
+  def phone_types(phone)
     method = options[:possible] ? :possible_types : :types
-    phone_types = @phone.send(method)
+    phone_types = phone.send(method)
     if (phone_types & [Phonelib::Core::FIXED_OR_MOBILE]).size > 0
       phone_types += [Phonelib::Core::FIXED_LINE, Phonelib::Core::MOBILE]
     end
@@ -113,15 +207,17 @@ class PhoneValidator < ActiveModel::EachValidator
   end
 
   # @private
-  def phone_countries
+  def phone_countries(phone)
     method = options[:possible] ? :countries : :valid_countries
-    @phone.send(method)
+    phone.send(method)
   end
 
   # @private
   def types
     types = options[:types].is_a?(Array) ? options[:types] : [options[:types]]
-    types.map(&:to_sym)
+    types.map do |type|
+      Phonelib::Core::TYPES_DESC_KEYS.find { |known| known.to_s == type.to_s }
+    end.compact
   end
 
   # @private

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phonelib
 version: !ruby/object:Gem::Version
-  version: 0.10.25
+  version: 0.10.26
 platform: ruby
 authors:
 - Vadim Senderovich
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-18 00:00:00.000000000 Z
+date: 2026-08-26 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Google libphonenumber library was taken as a basis for
@@ -28,11 +28,17 @@ files:
 - lib/phonelib/core.rb
 - lib/phonelib/data_importer.rb
 - lib/phonelib/data_importer_helper.rb
+- lib/phonelib/errors.rb
+- lib/phonelib/locale/en.yml
 - lib/phonelib/phone.rb
 - lib/phonelib/phone_analyzer.rb
 - lib/phonelib/phone_analyzer_helper.rb
 - lib/phonelib/phone_extended_data.rb
 - lib/phonelib/phone_formatter.rb
+- lib/phonelib/phone_validation.rb
+- lib/phonelib/railtie.rb
+- lib/phonelib/validation_error.rb
+- lib/phonelib/validation_result.rb
 - lib/phonelib/version.rb
 - lib/tasks/phonelib_tasks.rake
 - lib/validators/phone_validator.rb
@@ -40,7 +46,7 @@ homepage: https://github.com/daddyz/phonelib
 licenses:
 - MIT
 metadata:
-  changelog_uri: https://github.com/daddyz/phonelib/releases/tag/v0.10.25
+  changelog_uri: https://github.com/daddyz/phonelib/releases/tag/v0.10.26
 post_install_message: 
 rdoc_options:
 - " --no-private - CHANGELOG.md --readme README.md"