> ## Documentation Index
> Fetch the complete documentation index at: https://validity-kt.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone numbers

> phone, mobilePhone, countryCode and areaCode, by the metadata of Google's libphonenumber, in the validity-phone module.

Phone numbers are hard: every country has its own lengths, prefixes and mobile ranges, and they change. The phone
constraints rely on Google's [libphonenumber](https://github.com/google/libphonenumber), so they live in their own
module, and the core stays free of it.

```kotlin build.gradle.kts theme={null}
implementation("io.github.soleworks:validity-phone:0.1.0")
```

```groovy build.gradle theme={null}
implementation 'io.github.soleworks:validity-phone:0.1.0'
```

```xml pom.xml theme={null}
<dependency>
    <groupId>io.github.soleworks</groupId>
    <artifactId>validity-phone</artifactId>
    <version>0.1.0</version>
</dependency>
```

The constraints are in the package `io.github.soleworks.validity.phone`:

```kotlin Courier.kt theme={null}
data class Courier(
    val mobile: String?,
    val office: String? = null
) : Validatable {
    override fun validation() = validation {
        ::mobile required { mobilePhone(countryCode = "55", format = PhoneFormat.COMPLETE) }
        ::office ifPresent { phone(countryCode = "55") }
    }
}
```

| Constraint | Checks |
| - | - |
| [`phone`](#phone) | A valid phone number, of any kind |
| [`mobilePhone`](#mobilephone) | A valid mobile phone number |
| [`countryCode`](#countrycode) | A country calling code, such as `55` or `+1` |
| [`areaCode`](#areacode) | An area code used in a country, such as `11` in Brazil |

### `phone`

`phone(countryCode, areaCode, format)` on `String`

Checks that the string is a valid phone number, by the metadata of libphonenumber. Every argument is optional and
narrows what passes: a number from another country, with another area code or written in another format fails.

* `countryCode`: the country calling code the number must have, such as `55` or `+55`. With `null`, any country.
* `areaCode`: the area code the number must have, such as `11`. With `null`, any area code.
* `format`: how the number must be written, a `PhoneFormat`. With `null`, any of them.

**Code** `phone`· **Message** `must be a valid phone number` · **Change it** `phone { phone = "…" }`

### `mobilePhone`

`mobilePhone(countryCode, areaCode, format)` on `String`

Checks that the string is a valid mobile phone number, with the same arguments as `phone`. Numbers that can be mobile
or fixed line, as in the United States, pass.

**Code** `mobilePhone`· **Message** `must be a valid mobile phone number` · **Change it** `phone { mobilePhone = "…" }`

### `countryCode`

`countryCode()` on `String`

Checks that the string is a country calling code, such as `55` or `+1`, with or without the `+`.

**Code** `countryCode`· **Message** `must be a valid country calling code` · **Change it** `phone { countryCode = "…" }`

### `areaCode`

`areaCode(countryCode)` on `String`

Checks that the string is an area code used in `countryCode`, such as `11` in Brazil. Where the area codes of a country
have different lengths, any 1 to 5 digits pass.

**Code** `areaCode`· **Message** `must be a valid area code` · **Change it** `phone { areaCode = "…" }`

## Formats

`PhoneFormat` says how a number is written:

| Entry | Example |
| - | - |
| `PhoneFormat.COMPLETE` | `+55 11 91234-5678`, with the country calling code. The `+` is optional. |
| `PhoneFormat.AREA_CODE_AND_NUMBER` | `11 91234-5678`, with the area code but not the country calling code. |
| `PhoneFormat.NUMBER_ONLY` | `91234-5678`, only the local number. |

## Messages

The messages of the module are in a block of their own:

```kotlin theme={null}
Validity.configure {
    messages {
        phone {
            phone = "telefone inválido"
            mobilePhone = "celular inválido"
        }
    }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.