Download project

modules/psxmarketingwithgoogle/vendor/brick/phonenumber/README.md

@@ -0,0 +1,184 @@
+# Brick\PhoneNumber
+
+<img src="https://raw.githubusercontent.com/brick/brick/master/logo.png" alt="" align="left" height="64">
+
+A phone number library for PHP.
+
+[![Build Status](https://github.com/brick/phonenumber/workflows/CI/badge.svg)](https://github.com/brick/phonenumber/actions)
+[![Coverage Status](https://coveralls.io/repos/github/brick/phonenumber/badge.svg?branch=master)](https://coveralls.io/github/brick/phonenumber?branch=master)
+[![Latest Stable Version](https://poser.pugx.org/brick/phonenumber/v/stable)](https://packagist.org/packages/brick/phonenumber)
+[![Total Downloads](https://poser.pugx.org/brick/phonenumber/downloads)](https://packagist.org/packages/brick/phonenumber)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](http://opensource.org/licenses/MIT)
+
+This library is a thin wrapper around [giggsey/libphonenumber-for-php](https://github.com/giggsey/libphonenumber-for-php),
+itself a port of [Google's libphonenumber](https://github.com/googlei18n/libphonenumber).
+
+It provides an equivalent functionality, with the following implementation differences:
+
+- `PhoneNumber` is an immutable class; it can be safely passed around without having to worry about the risk for it to be changed;
+- `PhoneNumber` is not just a mere data container, but provides all the methods to parse, format and validate phone numbers; it transparently encapsulates `PhoneNumberUtil`.
+
+## Installation
+
+This library is installable via [Composer](https://getcomposer.org/):
+
+```bash
+composer require brick/phonenumber
+```
+
+## Requirements
+
+This library requires PHP 7.1 or later. for PHP 5.6 and PHP 7.0 support, use version `0.1`.
+
+## Project status & release process
+
+While this library is still under development, it is well tested and should be stable enough to use in production environments.
+
+The current releases are numbered `0.x.y`. When a non-breaking change is introduced (adding new methods, optimizing existing code, etc.), `y` is incremented.
+
+**When a breaking change is introduced, a new `0.x` version cycle is always started.**
+
+It is therefore safe to lock your project to a given release cycle, such as `0.4.*`.
+
+If 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.
+
+
+## Quick start
+
+All the classes lie in the `Brick\PhoneNumber` namespace.
+
+To obtain an instance of `PhoneNumber`, use the `parse()` method:
+
+- Using an international number: `PhoneNumber::parse('+33123456789')`;
+- Using a national number and a country code: `PhoneNumber::parse('01 23 45 67 89', 'FR')`;
+
+### Validating a number
+
+The `parse()` method is quite permissive with numbers; it basically attempts to match a country code,
+and validates the length of the phone number for this country.
+
+If a number is really malformed, it throws a `PhoneNumberParseException`:
+
+```php
+use Brick\PhoneNumber\PhoneNumber;
+use Brick\PhoneNumber\PhoneNumberParseException;
+
+try {
+    $number = PhoneNumber::parse('+333');
+}
+catch (PhoneNumberParseException $e) {
+    // 'The string supplied is too short to be a phone number.'
+}
+```
+
+In most cases, it is recommended to perform an extra step of validation with `isValidNumber()` or `isPossibleNumber()`:
+
+```php
+if (! $number->isPossibleNumber()) {
+    // a more lenient and faster check than `isValidNumber()`
+}
+
+if (! $number->isValidNumber()) {
+    // strict check relying on up-to-date metadata library
+}
+
+```
+
+As a rule of thumb, do the following:
+
+- 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;
+- When the number is later retrieved from your database, and has been validated before, you can just perform a blind `parse()`.
+
+### Formatting a number
+
+#### Basic formatting
+
+You can use `format()` with constants from the [PhoneNumberFormat](https://github.com/brick/phonenumber/blob/master/src/PhoneNumberFormat.php) class:
+
+```php
+$number = PhoneNumber::parse('+41446681800');
+$number->format(PhoneNumberFormat::E164); // +41446681800
+$number->format(PhoneNumberFormat::INTERNATIONAL); // +41 44 668 18 00
+$number->format(PhoneNumberFormat::NATIONAL); // 044 668 18 00
+$number->format(PhoneNumberFormat::RFC3966); // tel:+41-44-668-18-00
+```
+
+#### Formatting to call from another country
+
+You may want to present a phone number to an audience in a specific country, with the correct international 
+prefix when required. This is what `formatForCallingFrom()` does:
+
+```php
+$number = PhoneNumber::parse('+447123456789');
+$number->formatForCallingFrom('GB'); // 07123 456789
+$number->formatForCallingFrom('FR'); // 00 44 7123 456789
+$number->formatForCallingFrom('US'); // 011 44 7123 456789
+```
+
+### Number types
+
+In certain cases, it is possible to know the type of a phone number (fixed line, mobile phone, etc.), using
+the `getNumberType()` method, which returns a constant from the [PhoneNumberType](https://github.com/brick/phonenumber/blob/master/src/PhoneNumberType.php) class:
+
+```php
+PhoneNumber::parse('+336123456789')->getNumberType(); // PhoneNumberType::MOBILE
+PhoneNumber::parse('+33123456789')->getNumberType(); // PhoneNumberType::FIXED_LINE
+```
+
+If the type is unknown, the `PhoneNumberType::UNKNOWN` value is returned.
+Check the `PhoneNumberType` class for all possible values.
+
+### Number information
+
+You can extract the following information from a phone number:
+
+```php
+$number = PhoneNumber::parse('+447123456789');
+echo $number->getRegionCode(); // GB
+echo $number->getCountryCode(); // 44
+echo $number->getNationalNumber(); // 7123456789
+```
+
+### Example numbers
+
+You can get an example number for a country code and an optional number type (defaults to fixed line).
+This can be useful to use as a placeholder in an input field, for example:
+
+```php
+echo PhoneNumber::getExampleNumber('FR'); // +33123456789
+echo PhoneNumber::getExampleNumber('FR', PhoneNumberType::MOBILE); // +33612345678
+```
+
+The return type of `getExampleNumber()` is a `PhoneNumber` instance, so you can format it as you like:
+
+```php
+echo PhoneNumber::getExampleNumber('FR')->formatForCallingFrom('FR'); // 01 23 45 67 89
+```
+
+If no example phone number is available for the country code / number type combination, a `PhoneNumberException` is thrown.
+
+### Casting to string
+
+Casting a `PhoneNumber` to string returns its E164 representation (`+` followed by digits), so the following are equivalent:
+
+```php
+(string) $phoneNumber
+```
+
+```php
+$phoneNumber->format(PhoneNumberFormat::E164)
+```
+
+You can serialize a `PhoneNumber` to string, then recover it using `parse()` without a country code:
+
+```php
+$phoneNumber = PhoneNumber::parse('02079834000', 'GB');
+$phoneNumberAsString = (string) $phoneNumber; // +442079834000
+$phoneNumber2 = PhoneNumber::parse($phoneNumberAsString);
+
+$phoneNumber2->isEqualTo($phoneNumber); // true
+```
+
+### Doctrine mappings
+
+You can use `PhoneNumber` objects in your Doctrine entities using the [brick/phonenumber-doctrine](https://github.com/brick/phonenumber-doctrine) package.