pico_phone-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a77136e5c4b12dd9a039e2fc5fb3a417bd6eae8e353c937f9c05b8c7b768fea4
+  data.tar.gz: 6979e2642a4793889171a5de42a7f5bf209b486a4845488fd296b8af54821425
+SHA512:
+  metadata.gz: 8ee3cebc17f0fa5fa98ad427b763b024ad97114738d40e774739a50c04abe2c5c9082177fdefb31bd6e9a1a89ef9d026da6c1a0a7aafbca5c1c30473dd456366
+  data.tar.gz: dffc493a5abe2b513629b9fa29cc7ac741d5181f7e128add7d592baeab92e4b3c757f3e9d5ecc2faf82067b76810498f681b15a5d0400dde53e5cd5e0d53d809

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Gabi Jack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,72 @@
+# pico_phone-rails
+
+Rails integration for [`pico_phone`](https://github.com/gjack/pico_phone): an
+ActiveRecord attribute type, an ActiveModel validator, and a before-validation
+normalizer for phone numbers.
+
+## Installation
+
+```ruby
+gem "pico_phone-rails"
+```
+
+## Usage
+
+### Validator
+
+```ruby
+class Contact < ApplicationRecord
+  validates :phone, phone: { region: "US", allow_blank: true }
+end
+```
+
+Options:
+
+- `region:` — ISO 3166-1 alpha-2 default region used to interpret national-format input
+- `allow_blank:` — skip validation when the value is `nil` or empty
+- `possible:` — use a looser "possible" check instead of full validity
+
+### Attribute type
+
+```ruby
+class Contact < ApplicationRecord
+  attribute :phone, :phone_number, region: "US"
+end
+
+contact.phone        # => #<PicoPhone::PhoneNumber ...>
+contact.phone.e164   # => "+15102745656"
+```
+
+Reads deserialize to a `PicoPhone::PhoneNumber`; writes serialize back to E.164
+when valid. `nil` and unparseable input survive the round-trip without raising.
+
+### Normalizer
+
+```ruby
+class Contact < ApplicationRecord
+  normalize_phone :phone, region: "US"
+end
+```
+
+A `before_validation` callback that rewrites the column to E.164 when it parses
+as valid, so formatting noise ("(510) 274-5656") is stripped before the
+validator runs. Pairs naturally with the validator above.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+The Rails/Ruby support matrix is exercised via [Appraisal](https://github.com/thoughtbot/appraisal):
+
+```bash
+bundle exec appraisal install
+bundle exec appraisal rake
+```
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/phone_validator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Defined at the top level (not under PicoPhone::Rails) so ActiveModel's
+# validator lookup resolves `validates :phone, phone: { ... }` to this class —
+# EachValidator constantizes "#{key.to_s.camelize}Validator" against the
+# including model's namespace up through Object, same convention the
+# email_validator gem uses.
+#
+#   validates :phone, phone: { region: "US", allow_blank: true }
+class PhoneValidator < ActiveModel::EachValidator
+  def validate_each(record, attribute, value)
+    return if options[:allow_blank] && value.blank?
+
+    return if phone_valid?(value.to_s)
+
+    record.errors.add(attribute, :invalid_phone, **options.slice(:message))
+  end
+
+  private
+
+  def phone_valid?(string)
+    region = options[:region]
+
+    if options[:possible]
+      region ? PicoPhone.possible_for_country?(string, region) : PicoPhone.possible?(string)
+    else
+      region ? PicoPhone.valid_for_country?(string, region) : PicoPhone.valid?(string)
+    end
+  end
+end

data/lib/pico_phone/rails/locale/en.yml

@@ -0,0 +1,4 @@
+en:
+  errors:
+    messages:
+      invalid_phone: "is not a valid phone number"

data/lib/pico_phone/rails/normalizer.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module PicoPhone
+  module Rails
+    # Included into ActiveRecord::Base by the railtie. Adds a `normalize_phone`
+    # class macro that rewrites the given attributes to E.164 before validation
+    # runs, so validators and persisted data see a consistent format.
+    #
+    #   class Contact < ApplicationRecord
+    #     normalize_phone :phone, region: "US"
+    #   end
+    module Normalizer
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def normalize_phone(*attributes, region: nil)
+          before_validation do
+            attributes.each do |attribute|
+              value = public_send(attribute)
+              next if value.blank?
+
+              phone_number = PicoPhone.parse(value.to_s, region)
+              public_send("#{attribute}=", phone_number.e164) if phone_number.valid?
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pico_phone/rails/railtie.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module PicoPhone
+  module Rails
+    class Railtie < ::Rails::Railtie
+      initializer "pico_phone_rails.type" do
+        ActiveSupport.on_load(:active_record) do
+          ActiveRecord::Type.register(:phone_number, PicoPhone::Rails::Type)
+        end
+      end
+
+      initializer "pico_phone_rails.normalizer" do
+        ActiveSupport.on_load(:active_record) do
+          include PicoPhone::Rails::Normalizer
+        end
+      end
+
+      initializer "pico_phone_rails.i18n" do |app|
+        app.config.i18n.load_path += Dir[File.expand_path("locale/*.yml", __dir__)]
+      end
+    end
+  end
+end

data/lib/pico_phone/rails/type.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+module PicoPhone
+  module Rails
+    # Registered as `:phone_number` in the railtie. Casts a stored string to a
+    # PicoPhone::PhoneNumber on read and serializes back to E.164 on write.
+    #
+    #   attribute :phone, :phone_number, region: "US"
+    class Type < ActiveModel::Type::Value
+      def initialize(region: nil)
+        @region = region
+        super()
+      end
+
+      def type
+        :string
+      end
+
+      def cast(value)
+        return value if value.is_a?(PicoPhone::PhoneNumber)
+        return nil if value.nil?
+
+        PicoPhone.parse(value.to_s, @region)
+      end
+
+      def serialize(value)
+        return nil if value.nil?
+
+        phone_number = value.is_a?(PicoPhone::PhoneNumber) ? value : PicoPhone.parse(value.to_s, @region)
+        phone_number.valid? ? phone_number.e164 : phone_number.to_s
+      end
+
+      def deserialize(value)
+        cast(value)
+      end
+    end
+  end
+end

data/lib/pico_phone/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module PicoPhone
+  module Rails
+    VERSION = "0.1.0"
+  end
+end

data/lib/pico_phone/rails.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "pico_phone"
+require "pico_phone/rails/version"
+require "phone_validator"
+require "pico_phone/rails/type"
+require "pico_phone/rails/normalizer"
+require "pico_phone/rails/railtie" if defined?(Rails::Railtie)
+
+module PicoPhone
+  module Rails
+    class Error < StandardError; end
+  end
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: pico_phone-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Gabi Jack
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: pico_phone
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: 'pico_phone-rails wires the pico_phone gem into Rails: a :phone_number
+  ActiveRecord attribute type, a PhoneValidator for ActiveModel validations, and a
+  normalize_phone class macro that rewrites phone attributes to E.164 before validation.'
+email:
+- gabi@gabijack.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/phone_validator.rb
+- lib/pico_phone/rails.rb
+- lib/pico_phone/rails/locale/en.yml
+- lib/pico_phone/rails/normalizer.rb
+- lib/pico_phone/rails/railtie.rb
+- lib/pico_phone/rails/type.rb
+- lib/pico_phone/rails/version.rb
+homepage: https://github.com/gjack/pico_phone-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/gjack/pico_phone-rails
+  source_code_uri: https://github.com/gjack/pico_phone-rails
+  changelog_uri: https://github.com/gjack/pico_phone-rails/releases
+  bug_tracker_uri: https://github.com/gjack/pico_phone-rails/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: 'Rails integration for pico_phone: attribute type, validator, and normalizer
+  for phone numbers'
+test_files: []