Skip to content

Commit

Permalink
added documentation to methods
Browse files Browse the repository at this point in the history
  • Loading branch information
@tonglil
tonglil committed Dec 11, 2014
1 parent 3193a23 commit 898e30e
Showing 1 changed file with 86 additions and 0 deletions.
86 changes: 86 additions & 0 deletions src/Localize.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,22 @@

class Localize
{
/**
* The locale
* @var string
*/
private $locale;

/**
* The mapping of formats and regular expressions to results
* @var array
*/
private $mapping = array();

/**
* The mapping of countries between two-character locales and full names
* @var array
*/
private $countries = array(
array(
'short' => 'CA',
Expand All @@ -21,12 +33,23 @@ class Localize
),
);

/**
* Create a new Localize instance
* @param string $locale Optional two-character locale
*/
public function __construct($locale = 'CA')
{
$locale = $this->country($locale, true);
$this->setLocale($locale);
}

/**
* Set the locale of a Localize instance
* @param string $locale Optional two-character locale
* @throws LocaleParseException When the locale file is malformed
* @throws LocaleSupportException When the locale file is not found
* @return boolean True when the local is set
*/
public function setLocale($locale = 'CA')
{
$file = __DIR__ . '/locales/' . $locale . '.json';
Expand All @@ -47,11 +70,22 @@ public function setLocale($locale = 'CA')
}
}

/**
* Get the locale of a Localize instance
* @return string The two-character locale
*/
public function getLocale()
{
return $this->locale;
}

/**
* Get the matching short or long value of the input from the mapping
* @param string $type The group in the mapping to match
* @param string $input The given input to look for
* @param boolean $short True to return the short version
* @return string|null The formatted value from the mapping if found, otherwise null
*/
private function comparator($type, $input, $short = false)
{
$input = strtolower(trim($input));
Expand All @@ -69,11 +103,24 @@ private function comparator($type, $input, $short = false)
return null;
}

/**
* Run the input through the regular expression engine based on the type mapping
* @param string $type The group in the mapping to match
* @param string $input The given input
* @return string|null The formatted value from the mapping if found, otherwise null
*/
private function formatter($type, $input)
{
return $this->regex($input, $this->mapping[$type]['regex'], $this->mapping[$type]['format']);
}

/**
* Replace the input in the specified format if it matches the regular expression
* @param string $input The given input
* @param string $regex The regular expression to match
* @param string $replace The format to use when replacing
* @return string|null The formatted value based on the replace if a match is found, otherwise null
*/
public function regex($input, $regex, $replace)
{
if (preg_match($regex, $input)) {
Expand All @@ -83,6 +130,13 @@ public function regex($input, $regex, $replace)
}
}

/**
* Replace the input in the specified format if it matches any of multiple regular expressions
* @param string $input The given input
* @param array $regex The regular expressions to match
* @param string $replace The format to use when replacing
* @return string|null The formatted value based on the replace if a match is found, otherwise null
*/
public function regexManyToOne($input, array $regex, $replace)
{
foreach ($regex as $rule) {
Expand All @@ -94,6 +148,14 @@ public function regexManyToOne($input, array $regex, $replace)
return null;
}

/**
* Replace the input in the corresponding format if it matches any of multiple regular expressions
* @param string $input The given input
* @param array $regex The regular expressions to match
* @param array $replace The formats to use when replacing
* @throws UnmatchedRegexException When the number of regular expressions do not match the number of replaces
* @return string|null The formatted value based on the corresponding replace if a match is found, otherwise null
*/
public function regexMany($input, array $regex, array $replace)
{
if (count($regex) != count($replace)) {
Expand All @@ -109,6 +171,12 @@ public function regexMany($input, array $regex, array $replace)
return null;
}

/**
* Find and format the given country
* @param string $country The given input
* @param boolean $short True to return the short version
* @return string|null The formatted country if found, otherwise null
*/
public function country($country, $short = false)
{
$this->mapping = array_merge($this->mapping, array(
Expand All @@ -118,16 +186,34 @@ public function country($country, $short = false)
return $this->comparator('countries', $country, $short);
}

/**
* Find and format the given region
* @param string $region The given input
* @param boolean $short True to return the short version
* @return string|null The formatted region if found, otherwise null
*/
public function region($region, $short = false)
{
return $this->comparator('regions', $region, $short);
}

/**
* Find and format the given postal code
* @param string $postalCode The given input
* @param boolean $short True to return the short version
* @return string|null The formatted postal code if found, otherwise null
*/
public function postalCode($postalCode)
{
return $this->formatter('postalCode', strtoupper($postalCode));
}

/**
* Find and format the given phone number
* @param string $phone The given input
* @param boolean $short True to return the short version
* @return string|null The formatted phone number if found, otherwise null
*/
public function phone($phone)
{
return $this->formatter('phoneNumber', $phone);
Expand Down

0 comments on commit 898e30e

Please sign in to comment.