PHPackages                             rynpsc/craft-phone-number - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. rynpsc/craft-phone-number

ActiveCraft-plugin[Utility & Helpers](/categories/utility)

rynpsc/craft-phone-number
=========================

International phone number field.

3.0.0(1y ago)2265.9k↓23.3%3[1 issues](https://github.com/rynpsc/craft-phone-number/issues)MITPHPPHP ^8.2

Since Sep 5Pushed 1y ago1 watchersCompare

[ Source](https://github.com/rynpsc/craft-phone-number)[ Packagist](https://packagist.org/packages/rynpsc/craft-phone-number)[ RSS](/packages/rynpsc-craft-phone-number/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (4)Versions (29)Used By (0)

[![Phone Number icon](src/icon.svg)](src/icon.svg)

Phone Number
============

[](#phone-number)

This plugin adds a new fieldtype to Craft for entering and validating international phone numbers, and getting information about those numbers. A Twig extension is also provided for extracting numbers from text.

It's built upon on the excellent [libphonenumber-for-php](https://github.com/giggsey/libphonenumber-for-php) port of Google's [libphonenumber](https://github.com/google/libphonenumber) library.

[![Screenshot](resources/phone-number-field.jpg)](resources/phone-number-field.jpg)

Features
--------

[](#features)

- Field type for entering and validating international phone numbers.
- GraphQL support for both query and mutating phone number fields.
- Support for field and element condition rules.
- Twig filter for extracting number from text.

Requirements
------------

[](#requirements)

This plugin requires Craft CMS 5.0.0 or later.

Installation
------------

[](#installation)

You can install this plugin from the Plugin Store or with Composer.

### From the Plugin Store

[](#from-the-plugin-store)

Go to the Plugin Store in your project’s Control Panel and search for "Phone Number". Then click on the "Install" button in its modal window.

### With Composer

[](#with-composer)

Open your terminal and run the following commands:

```
# Go to the project directory
cd /path/to/project

# Tell Composer to load the plugin
composer require rynpsc/craft-phone-number

# Tell Craft to install the plugin
./craft install/plugin phone-number
```

Field Type
----------

[](#field-type)

The Phone Number field provides an easy way of parsing, formatting, storing and validating international phone numbers.

### Working with Phone Number Field Data

[](#working-with-phone-number-field-data)

The Phone Number field returns a PhoneNumberModel.

When calling any of the below make sure to first check that the field value isn't null. This check is omitted for brevity in the examples.

```
{% if entry.fieldHandle %}
  {{ entry.fieldHandle.region }}
{% endif %}
```

#### region

[](#region)

The raw region code as entered within the field.

```
{{ entry.fieldHandle.region }}
```

#### number

[](#number)

The raw number as entered within the field.

```
{{ entry.fieldHandle.number }}
```

#### getCountryCode()

[](#getcountrycode)

The numerical country code.

```
{{ entry.fieldHandle.getCountryCode() }}
```

#### getRegionCode()

[](#getregioncode)

The alphabetical region code.

```
{{ entry.fieldHandle.getRegionCode() }}
```

#### getLink()

[](#getlink)

Returns a phone number link, see [links](#links).

```
{{ entry.fieldHandle.getLink() }}
```

#### getType()

[](#gettype)

Returns the number type.

```
{{ entry.fieldHandle.getType() }}
```

Number types are returned as integers.

ValueType0Fixed line1Mobile2Fixed line or mobile3Toll free4Premium rate5Shared cost6VOIP7Personal number8Pager9UAN10Unknown27Emergency28Voicemail29Short code30Standard rate#### getDescription(locale, region)

[](#getdescriptionlocale-region)

Returns a description for the number in the supplied locale.

The description returned might consist of the name of the country, or the name of the geographical area the phone number is from.

If `region` is supplied, it will also be taken into consideration. If the phone number is from the same region, only a lower-level description will be returned.

```
{# Manchester #}
{{ entry.fieldHandle.getDescription('en-GB') }}

{# Manchester #}
{{ entry.fieldHandle.getDescription('en-GB', 'GB') }}

{# United Kingdom #}
{{ entry.fieldHandle.getDescription('en-GB', 'US') }}
```

##### getTimeZones()

[](#gettimezones)

Returns an array of time zones to which a phone number belongs.

```
{{ entry.fieldHandle.getTimeZones() }}
```

##### format(format)

[](#formatformat)

Formats a phone number.

```
{{ entry.fieldHandle.format('international') }}
```

Numbers can be formatted in the following formats:

FormatExample Outpute164+441174960123rfc3966tel:+44-117-496-0123national0117 496 0123international+44 117 496 0123The rfc3966 format is also available via the `tel` alias.

##### formatForCountry(region)

[](#formatforcountryregion)

Formats the phone number based on the `region`.

```
{{ entry.fieldHandle.formatForCountry('GB') }}
```

##### formatForMobileDialing(region, withFormatting)

[](#formatformobiledialingregion-withformatting)

Formats the phone number in a way that it can be dialled from the provided `region`. The `withFormatting` parameter determines whether there is any formatting applied to the number.

```
{{ entry.fieldHandle.formatForMobileDialing() }}
```

### Querying Elements with Phone Number Fields

[](#querying-elements-with-phone-number-fields)

When querying for elements that have a Phone Number field, you can filter the results based on the Phone Number field data using a query param named after your field’s handle.

Possible values include:

ValueDescription`':empty:'`Field doesn't have a number`':notempty:'`Field does have a number`{ region: ['GB'] }`Number has the region "GB"`{ region: ['not', 'GB'] }`Number doesn't have the region "GB"`{ number: ['01234567890'] }`Number is equal to "01234567890"`{ number: ['not', '01234567890'] }`Number is not equal to "01234567890"`{ number: '*0' }`Number ends with "0"`{ number: ['not', '*0'] }`Number doesn't end with "0"`{ region: "GB", number: '*0' }`Number has the region "GB" and ends with "0"```
{% set entries = craft.entries()
  .phone({ region: ['GB'] })
  .all() %}
```

### Saving Phone Number Fields

[](#saving-phone-number-fields)

If you have an element form, such as an [entry form](https://craftcms.com/knowledge-base/entry-form), that needs to contain a Phone Number field, you will need to submit your field with inputs for both the region and number.

```

  {% for region in craft.phoneNumber.getAllSupportedRegions() %}
      {{ region.countryName }}
  {% endfor %}

```

Twig Filter
-----------

[](#twig-filter)

The `tel` filter extracts phone numbers from a string and turns them into links, using the number as the link text.

```
{{ entry.text|tel }}
```

By default, only numbers with a region code such as +44 will be converted. To convert numbers without a region code you can pass in a default country code to use when parsing.

```
{{ entry.text|tel('GB') }}
```

Links
-----

[](#links)

Both the `getLink()` method and `tel` filter support setting the generated links content and HTML attributes.

Attributes are set as per [`yii\helpers\BaseHtml::renderTagAttributes()`](https://www.yiiframework.com/doc/api/2.0/yii-helpers-basehtml#renderTagAttributes()-detail).

```
{{ entry.phoneFieldHandle.getLink({
  class: 'my-class'
}) }}

{{ entry.textFieldHandle|tel(null, {
  class: 'my-class'
}) }}
```

If `text` is included in the attributes argument, its value will be HTML-encoded and set as the text contents of the link.

```
{{ entry.phoneFieldHandle.getLink({
  text: 'Content'
}) }}

{{ entry.textField|tel(null, {
  text: 'Content'
}) }}
```

If `html` is included in the attributes argument, its value will be set as the inner HTML of the link (without getting HTML-encoded).

```
{{ entry.phoneFieldHandle.getLink({
  html: 'Content'
}) }}

{{ entry.textField|tel(null, {
  html: 'Content'
}) }}
```

###  Health Score

48

—

FairBetter than 95% of packages

Maintenance34

Infrequent updates — may be unmaintained

Popularity39

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity85

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 98.8% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~85 days

Recently: every ~204 days

Total

27

Last Release

598d ago

Major Versions

1.5.0 → 2.0.0-beta.12022-03-22

1.0.x-dev → 2.0.0-beta.22022-03-26

2.2.0 → 3.0.0-beta.12024-02-21

PHP version history (2 changes)2.0.0-beta.1PHP ^8.0.2

3.0.0-beta.1PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/98d511fb324e63976ff83534ab11bdd70351a5ef1e0b160b0a81f52d7e538cf5?d=identicon)[rynpsc](/maintainers/rynpsc)

---

Top Contributors

[![rynpsc](https://avatars.githubusercontent.com/u/5955881?v=4)](https://github.com/rynpsc "rynpsc (163 commits)")[![brandonkelly](https://avatars.githubusercontent.com/u/47792?v=4)](https://github.com/brandonkelly "brandonkelly (1 commits)")[![jaydensmith](https://avatars.githubusercontent.com/u/16344913?v=4)](https://github.com/jaydensmith "jaydensmith (1 commits)")

---

Tags

craft3craftcmscraftcms-pluginlibphonenumberphone-numbertwig-filterphonelibphonenumbercmsyii2craftcmsnumber

### Embed Badge

![Health badge](/badges/rynpsc-craft-phone-number/health.svg)

```
[![Health](https://phpackages.com/badges/rynpsc-craft-phone-number/health.svg)](https://phpackages.com/packages/rynpsc-craft-phone-number)
```

###  Alternatives

[verbb/formie

The most user-friendly forms plugin for Craft.

101372.9k40](/packages/verbb-formie)[craftcms/ckeditor

Edit rich text content in Craft CMS using CKEditor.

48359.1k52](/packages/craftcms-ckeditor)[craftcms/generator

Craft CMS component generator

88377.0k38](/packages/craftcms-generator)[craftcms/guest-entries

This plugin allows you to save guest entries from the front-end of your website.

10693.0k3](/packages/craftcms-guest-entries)[verbb/tablemaker

Create customizable and user-defined table fields.

40168.8k1](/packages/verbb-tablemaker)[supercool/tablemaker

Create customizable and user-defined table fields.

40141.7k](/packages/supercool-tablemaker)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)