{"id":19764352,"url":"https://github.com/brick/phonenumber","last_synced_at":"2025-05-15T17:01:17.748Z","repository":{"id":34381626,"uuid":"38308109","full_name":"brick/phonenumber","owner":"brick","description":"A phone number library for PHP","archived":false,"fork":false,"pushed_at":"2024-05-02T23:28:42.000Z","size":84,"stargazers_count":365,"open_issues_count":2,"forks_count":38,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-10-25T04:47:58.973Z","etag":null,"topics":["libphonenumber","phone-number","php"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brick.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"BenMorel"}},"created_at":"2015-06-30T12:33:42.000Z","updated_at":"2024-10-19T12:29:55.000Z","dependencies_parsed_at":"2023-10-14T15:31:33.720Z","dependency_job_id":"4032aa1d-e53b-496d-b3b6-d3a401a5f9e1","html_url":"https://github.com/brick/phonenumber","commit_stats":{"total_commits":91,"total_committers":5,"mean_commits":18.2,"dds":0.05494505494505497,"last_synced_commit":"84007e698e0e37fbc434f9017f75fdb74e9772ec"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brick%2Fphonenumber","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brick%2Fphonenumber/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brick%2Fphonenumber/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brick%2Fphonenumber/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brick","download_url":"https://codeload.github.com/brick/phonenumber/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254384929,"owners_count":22062421,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["libphonenumber","phone-number","php"],"created_at":"2024-11-12T04:13:35.492Z","updated_at":"2025-05-15T17:01:17.227Z","avatar_url":"https://github.com/brick.png","language":"PHP","funding_links":["https://github.com/sponsors/BenMorel"],"categories":[],"sub_categories":[],"readme":"# Brick\\PhoneNumber\n\n\u003cimg src=\"https://raw.githubusercontent.com/brick/brick/master/logo.png\" alt=\"\" align=\"left\" height=\"64\"\u003e\n\nA phone number library for PHP.\n\n[![Build Status](https://github.com/brick/phonenumber/workflows/CI/badge.svg)](https://github.com/brick/phonenumber/actions)\n[![Coverage Status](https://coveralls.io/repos/github/brick/phonenumber/badge.svg?branch=master)](https://coveralls.io/github/brick/phonenumber?branch=master)\n[![Latest Stable Version](https://poser.pugx.org/brick/phonenumber/v/stable)](https://packagist.org/packages/brick/phonenumber)\n[![Total Downloads](https://poser.pugx.org/brick/phonenumber/downloads)](https://packagist.org/packages/brick/phonenumber)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](http://opensource.org/licenses/MIT)\n\nThis library is a thin wrapper around [giggsey/libphonenumber-for-php](https://github.com/giggsey/libphonenumber-for-php),\nitself a port of [Google's libphonenumber](https://github.com/googlei18n/libphonenumber).\n\nIt provides an equivalent functionality, with the following implementation differences:\n\n- `PhoneNumber` is an immutable class; it can be safely passed around without having to worry about the risk for it to be changed;\n- `PhoneNumber` is not just a mere data container, but provides all the methods to parse, format and validate phone numbers; it transparently encapsulates services such as `PhoneNumberUtil`;\n\n## Installation\n\nThis library is installable via [Composer](https://getcomposer.org/):\n\n```bash\ncomposer require brick/phonenumber\n```\n\n## Requirements\n\nThis library requires PHP 8.1 or later.\n\nFor PHP 7.4 and PHP 8.0 support, use version `0.5`.\nFor PHP 7.1 support, use version `0.4`.\nFor PHP 5.6 and PHP 7.0 support, use version `0.1`.\nNote that [these PHP versions are EOL](http://php.net/supported-versions.php) and not supported anymore. If you're still using one of these PHP versions, you should consider upgrading as soon as possible.\n\n## Project status \u0026 release process\n\nWhile this library is still under development, it is well tested and is considered stable enough to use in production environments.\n\nThe current releases are numbered `0.x.y`. When a non-breaking change is introduced (adding new methods, optimizing existing code, etc.), `y` is incremented.\n\n**When a breaking change is introduced, a new `0.x` version cycle is always started.**\n\nIt is therefore safe to lock your project to a given release cycle, such as `0.7.*`.\n\nIf you need to upgrade to a newer release cycle, check the [release history](https://github.com/brick/phonenumber/releases) for a list of changes introduced by each further `0.x.0` version.\n\n\n## Quick start\n\nAll the classes lie in the `Brick\\PhoneNumber` namespace.\n\nTo obtain an instance of `PhoneNumber`, use the `parse()` method:\n\n- Using an international number: `PhoneNumber::parse('+33123456789')`;\n- Using a national number and a country code: `PhoneNumber::parse('01 23 45 67 89', 'FR')`;\n\n### Validating a number\n\nThe `parse()` method is quite permissive with numbers; it basically attempts to match a country code,\nand validates the length of the phone number for this country.\n\nIf a number is really malformed, it throws a `PhoneNumberParseException`:\n\n```php\nuse Brick\\PhoneNumber\\PhoneNumber;\nuse Brick\\PhoneNumber\\PhoneNumberParseException;\n\ntry {\n    $number = PhoneNumber::parse('+333');\n}\ncatch (PhoneNumberParseException $e) {\n    // 'The string supplied is too short to be a phone number.'\n}\n```\n\nIn most cases, it is recommended to perform an extra step of validation with `isValidNumber()` or `isPossibleNumber()`:\n\n```php\nif ($number-\u003eisValidNumber()) {\n    // strict check relying on up-to-date metadata library\n}\n\n// or\n\nif ($number-\u003eisPossibleNumber()) {\n    // a more lenient and faster check than `isValidNumber()`\n}\n```\n\nAs a rule of thumb, do the following:\n\n- When the number comes from user input, do a full validation: `parse()` and catch `PhoneNumberParseException`, then call `isValidNumber()` (or `isPossibleNumber()` for a more lenient check) if no exception occurred;\n- When the number is later retrieved from your database, and has been validated before, you can just perform a blind `parse()`.\n\n### Formatting a number\n\n#### Basic formatting\n\nYou can use `format()` with a [PhoneNumberFormat](https://github.com/brick/phonenumber/blob/master/src/PhoneNumberFormat.php) enum value:\n\n```php\n$number = PhoneNumber::parse('+41446681800');\n$number-\u003eformat(PhoneNumberFormat::E164); // +41446681800\n$number-\u003eformat(PhoneNumberFormat::INTERNATIONAL); // +41 44 668 18 00\n$number-\u003eformat(PhoneNumberFormat::NATIONAL); // 044 668 18 00\n$number-\u003eformat(PhoneNumberFormat::RFC3966); // tel:+41-44-668-18-00\n```\n\n#### Formatting to call from a given country\n\nYou may want to present a phone number to an audience in a specific country, with the correct international \nprefix when required. This is what `formatForCallingFrom()` does:\n\n```php\n$number = PhoneNumber::parse('+447123456789');\n$number-\u003eformatForCallingFrom('GB'); // 07123 456789\n$number-\u003eformatForCallingFrom('FR'); // 00 44 7123 456789\n$number-\u003eformatForCallingFrom('US'); // 011 44 7123 456789\n```\n\n#### Formatting to call from a mobile phone in a given country\n\nIf you want to present a number to dial from a mobile phone, you can use `formatForMobileDialing()`:\n\n```php\n$number = PhoneNumber::parse('+447123456789');\n\n$number-\u003eformatForMobileDialing('GB', withFormatting: false); // 07123456789\n$number-\u003eformatForMobileDialing('GB', withFormatting: true); // 07123 456789\n\n$number-\u003eformatForMobileDialing('FR', withFormatting: false); // +447123456789\n$number-\u003eformatForMobileDialing('FR', withFormatting: true); // +44 7123 456789\n```\n\n### Getting number information\n\nYou can extract basic information from a phone number:\n\n```php\n$number = PhoneNumber::parse('+447123456789');\n\n$number-\u003egetRegionCode(); // GB\n$number-\u003egetCountryCode(); // 44\n$number-\u003egetNationalNumber(); // 7123456789\n```\n\n#### Number type\n\nIn certain cases, it is possible to know the type of a phone number (fixed line, mobile phone, etc.), using\nthe `getNumberType()` method, which returns a [PhoneNumberType](https://github.com/brick/phonenumber/blob/master/src/PhoneNumberType.php) enum value:\n\n```php\nPhoneNumber::parse('+336123456789')-\u003egetNumberType(); // PhoneNumberType::MOBILE\nPhoneNumber::parse('+33123456789')-\u003egetNumberType(); // PhoneNumberType::FIXED_LINE\n```\n\nIf the type is unknown, the `PhoneNumberType::UNKNOWN` value is returned.\nCheck the `PhoneNumberType` enum for all possible values.\n\n#### Description\n\nYou can get a human-readable description of a phone number:\n\n```php\nPhoneNumber::parse('+33123456789')-\u003egetDescription(locale: 'en'); // France\nPhoneNumber::parse('+16509030000')-\u003egetDescription(locale: 'en'); // Mountain View, CA\n```\n\n#### Carrier name\n\nFor some phone numbers, it is possible to get the carrier name:\n\n```php\n$number = PhoneNumber::parse('+336789012345');\n$number-\u003egetCarrierName(languageCode: 'en'); // Orange France\n```\n\nNote that in countries that support mobile number portability, the carrier name for a phone number may no longer be\ncorrect. You can control whether the carrier name should be returned in this case, by passing a\n[CarrierNameMode](https://github.com/brick/phonenumber/blob/master/src/CarrierNameMode.php) enum:\n\n```php\n// null, because France supports mobile number portability\n$number-\u003egetCarrierName(languageCode: 'en', mode: CarrierNameMode::MOBILE_NO_PORTABILITY_ONLY);\n```\n\n#### Time zones\n\nYou can get the time zones that typically match a phone number:\n\n```php\n$number = PhoneNumber::parse('+14155552671');\n$number-\u003egetTimeZones(); // ['America/Los_Angeles']\n```\n\n### Example numbers\n\nYou can get an example number for a country code and an optional number type (defaults to fixed line).\nThis can be useful to use as a placeholder in an input field, for example:\n\n```php\necho PhoneNumber::getExampleNumber('FR'); // +33123456789\necho PhoneNumber::getExampleNumber('FR', PhoneNumberType::MOBILE); // +33612345678\n```\n\nThe return type of `getExampleNumber()` is a `PhoneNumber` instance, so you can format it as you like:\n\n```php\necho PhoneNumber::getExampleNumber('FR')-\u003eformatForCallingFrom('FR'); // 01 23 45 67 89\n```\n\nIf no example phone number is available for the country code / number type combination, a `PhoneNumberException` is thrown.\n\n### Casting to string\n\nCasting a `PhoneNumber` to string returns its E164 representation (`+` followed by digits), so the following are equivalent:\n\n```php\n(string) $phoneNumber\n```\n\n```php\n$phoneNumber-\u003eformat(PhoneNumberFormat::E164)\n```\n\nYou can serialize a `PhoneNumber` to string, then recover it using `parse()` without a country code:\n\n```php\n$phoneNumber = PhoneNumber::parse('02079834000', 'GB');\n$phoneNumberAsString = (string) $phoneNumber; // +442079834000\n$phoneNumber2 = PhoneNumber::parse($phoneNumberAsString);\n\n$phoneNumber2-\u003eisEqualTo($phoneNumber); // true\n```\n\n### Doctrine mappings\n\nYou can use `PhoneNumber` objects in your Doctrine entities using the [brick/phonenumber-doctrine](https://github.com/brick/phonenumber-doctrine) package.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrick%2Fphonenumber","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrick%2Fphonenumber","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrick%2Fphonenumber/lists"}