libphonenumber is Google’s library for parsing, formatting and validating international phone numbers. This extension gives a Quarkus application these parts:

  • An injectable PhoneNumberUtil.

  • A @PhoneNumber bean validation constraint.

  • Native image support. The per-region metadata is bundled into the executable.

It uses libphonenumber 9.0.42 and needs Quarkus 3.x with Java 21 or later.

Installation

<dependency>
    <groupId>org.sitenetsoft</groupId>
    <artifactId>quarkus-libphonenumber</artifactId>
    <version>0.1.0-SNAPSHOT</version>
</dependency>

The artifact brings in quarkus-hibernate-validator, which the constraint needs.

PhoneNumberUtil

@Inject
PhoneNumberUtil util;

Phonenumber.PhoneNumber number = util.parse("+16135550100", null);
String region = util.getRegionCodeForNumber(number); // CA

The bean is a @Singleton that returns PhoneNumberUtil.getInstance().

The @PhoneNumber constraint

public record Signup(
        @NotNull
        @PhoneNumber(regions = { "CA", "US" }, types = { MOBILE, FIXED_LINE_OR_MOBILE })
        String phone) {
}

The value is parsed with the configured default region. It must then be a valid number. When regions is not empty, the number must belong to one of them. When types is not empty, the number must have one of them.

  • regions and types empty mean any region and any type.

  • null is valid. Add @NotNull to require a value.

  • An empty or unparsable string is invalid.

  • Mobile numbers in Canada and the United States report FIXED_LINE_OR_MOBILE, since their numbering plan does not tell the two apart. List it next to MOBILE.

  • The message key is {org.sitenetsoft.quarkus.libphonenumber.PhoneNumber.message}. The extension ships the English text in ValidationMessages.properties. If your application has its own ValidationMessages.properties, add the key there, or set message on the annotation.

Configuration

Set quarkus.libphonenumber.default-region to an ISO 3166-1 region such as CA to accept numbers typed without a +. Without it, only numbers in international format parse. See Configuration reference.