### Custom Storage and Rules with TWZipcode (PHP)

Source: https://context7.com/recca0120/twzipcode/llms.txt

This snippet demonstrates how to create custom storage backends and rules for the TWZipcode library in PHP. It shows loading data from a text source, defining custom rules, and then using these rules to parse addresses and extract zip codes. It also includes examples of loading rules from CSV and JSON files.

```php
<?php
use Recca0120\Twzipcode\Zipcode;
use Recca0120\Twzipcode\Rules;
use Recca0120\Twzipcode\Storages\File;
use Recca0120\Twzipcode\Sources\Text;

// Create custom storage with specific rules
$storage = new File('/path/to/storage');
$storage->flush()->load(new Text('
10043,臺北市,中正區,中華路１段,單  25之   3號以下
10042,臺北市,中正區,中華路１段,單  27號以上
26044,宜蘭縣,宜蘭市,慶和街同興巷,全
26044,宜蘭縣,宜蘭市,慶和街慶和巷,全
41274,臺中市,大里區,塗城路,單 505號以下
41271,臺中市,大里區,塗城路,單 507號以上
41274,臺中市,大里區,塗城路,雙 274號以下
41275,臺中市,大里區,塗城路,雙 276號以上
'));

// Create rules with custom storage
$rules = new Rules($storage);

// Use custom rules for parsing
$zipcode = Zipcode::parse('台北市中正區中華路１段25號', $rules);
echo $zipcode->zip5();  // Output: 10043

// Test odd/even number matching
$oddAddress = Zipcode::parse('台中市大里區塗城路505號', $rules);
echo $oddAddress->zip5();  // Output: 41274 (odd, 505 or below)

$oddAddress2 = Zipcode::parse('台中市大里區塗城路507號', $rules);
echo $oddAddress2->zip5();  // Output: 41271 (odd, 507 or above)

$evenAddress = Zipcode::parse('台中市大里區塗城路274號', $rules);
echo $evenAddress->zip5();  // Output: 41274 (even, 274 or below)

$evenAddress2 = Zipcode::parse('台中市大里區塗城路276號', $rules);
echo $evenAddress2->zip5();  // Output: 41275 (even, 276 or above)

// Load rules from different sources
use Recca0120\Twzipcode\Sources\Csv;
use Recca0120\Twzipcode\Sources\Json;

// From CSV file
$csvStorage = new File('/path/to/storage');
$csvStorage->flush()->load(new Csv('/path/to/rules.csv'));

// From JSON file
$jsonStorage = new File('/path/to/storage');
$jsonStorage->flush()->load(new Json('/path/to/rules.json'));

// Use with Zipcode
$csvRules = new Rules($csvStorage);
$jsonRules = new Rules($jsonStorage);

$result1 = Zipcode::parse('台北市中正區中華路１段25號', $csvRules);
$result2 = Zipcode::parse('台北市中正區中華路１段25號', $jsonRules);
?>
```

--------------------------------

### TWZipcode Rule Matching Logic (PHP)

Source: https://context7.com/recca0120/twzipcode/llms.txt

This PHP snippet showcases the detailed rule matching capabilities of the TWZipcode library. It covers various matching scenarios including continuous ranges, odd/even number assignments, handling of sub-numbers (like '之'), and matching all addresses within a specified area. Each example instantiates a `Rule` object with specific criteria and tests it against an `Address` object.

```php
<?php
use Recca0120\Twzipcode\Rule;
use Recca0120\Twzipcode\Address;

// Create rule with range (連 = continuous range)
$rule = new Rule('10043,臺北市,中正區,中華路１段,連 1號至 99號');
$address = new Address('台北市中正區中華路1段50號');

if ($rule->match($address)) {
    echo $rule->zip5();  // Output: 10043
    echo $rule->zip3();  // Output: 100
}

// Odd number matching (單)
$oddRule = new Rule('41271,臺中市,大里區,塗城路,單 507號以上');
$oddAddress = new Address('台中市大里區塗城路509號');
echo $oddRule->match($oddAddress) ? 'Matched' : 'Not matched';  // Output: Matched

// Even number matching (雙)
$evenRule = new Rule('41275,臺中市,大里區,塗城路,雙 276號以上');
$evenAddress = new Address('台中市大里區塗城路278號');
echo $evenRule->match($evenAddress) ? 'Matched' : 'Not matched';  // Output: Matched

// Range with sub-numbers (之)
$subRule = new Rule('10043,臺北市,中正區,中華路１段,單 25之3號以下');
$subAddress1 = new Address('台北市中正區中華路1段25之1號');
$subAddress2 = new Address('台北市中正區中華路1段25之5號');
echo $subRule->match($subAddress1) ? 'Matched' : 'Not matched';  // Output: Matched
echo $subRule->match($subAddress2) ? 'Matched' : 'Not matched';  // Output: Not matched

// Match all addresses in area (全)
$allRule = new Rule('26044,宜蘭縣,宜蘭市,慶和街同興巷,全');
$anyAddress = new Address('宜蘭縣宜蘭市慶和街同興巷9478號');
echo $allRule->match($anyAddress) ? 'Matched' : 'Not matched';  // Output: Matched

// Complex range matching
$rangeRule = new Rule('26060,宜蘭縣,壯圍鄉,環市東路１段,連 374號以下');
$address1 = new Address('宜蘭縣壯圍鄉環市東路1段100號');
$address2 = new Address('宜蘭縣壯圍鄉環市東路1段500號');
echo $rangeRule->match($address1) ? 'In range' : 'Out of range';  // Output: In range
echo $rangeRule->match($address2) ? 'In range' : 'Out of range';  // Output: Out of range
?>
```

--------------------------------

### PHP Point Comparison and Address Extraction

Source: https://context7.com/recca0120/twzipcode/llms.txt

Demonstrates creating Point objects for house numbers, comparing them using operators, checking for empty points, and extracting points from Address objects. This is crucial for validating address ranges and ensuring accurate data entry.

```php
<?php
use Recca0120\Twzipcode\Point;
use Recca0120\Twzipcode\Address;

// Create points representing house numbers
$point1 = new Point(25, 0);  // 25號
$point2 = new Point(25, 3);  // 25之3號
$point3 = new Point(27, 0);  // 27號

// Check if point is empty (0, 0)
$emptyPoint = new Point(0, 0);
echo $emptyPoint->isEmpty() ? 'Empty' : 'Not empty';  // Output: Empty

// Compare points using operators
echo $point1->compare($point2, '<') ? 'Less' : 'Not less';  // Output: Less
echo $point2->compare($point1, '>') ? 'Greater' : 'Not greater';  // Output: Greater
echo $point1->compare($point1, '=') ? 'Equal' : 'Not equal';  // Output: Equal

// Comparison logic: (x * 10 + y)
// 25號 = 250, 25之3號 = 253, 27號 = 270
echo $point1->compare($point2, '<=') ? 'true' : 'false';  // Output: true (250 <= 253)
echo $point3->compare($point2, '>=') ? 'true' : 'false';  // Output: true (270 >= 253)

// Extract points from address
$address = new Address('台北市中正區中華路1段25之3號');
$tokens = $address->tokens();

// Get point from specific token index
$roadPoint = $address->point(2);  // Road token (no number)
echo $roadPoint->isEmpty() ? 'No number' : 'Has number';  // Output: No number

$housePoint = $address->point(3);  // House number token
echo "House number: {$housePoint->x}之{$housePoint->y}";  // Output: House number: 25之3

// Practical usage in range checking
$minPoint = new Point(1, 0);    // 1號
$maxPoint = new Point(99, 0);   // 99號
$testPoint = new Point(50, 0);  // 50號

$inRange = $minPoint->compare($testPoint, '<=') && $testPoint->compare($maxPoint, '<=');
echo $inRange ? 'In range (1-99)' : 'Out of range';  // Output: In range (1-99)

// Handle sub-number ranges
$minSub = new Point(25, 1);   // 25之1號
$maxSub = new Point(25, 5);   // 25之5號
$testSub = new Point(25, 3);  // 25之3號

$inSubRange = $minSub->compare($testSub, '<=') && $testSub->compare($maxSub, '<=');
echo $inSubRange ? 'In sub-range' : 'Out of sub-range';  // Output: In sub-range
?>
```

--------------------------------

### Parse Taiwanese Address to Zip Codes and Address Components (PHP)

Source: https://github.com/recca0120/twzipcode/blob/main/README.md

This snippet demonstrates how to use the Twzipcode library to parse a Taiwanese address string. It requires the Composer autoloader and the Twzipcode class. The output includes the 3-digit zip code, 5-digit zip code, county, district, full address, and a short address. No specific input validation is shown, and the library assumes a valid address format.

```php
require __DIR__.'/vendor/autoload.php';

use Recca0120\Twzipcode\Zipcode;

$zipcode = Zipcode::parse('台北市中正區中華路１段25號');
echo $zipcode->zip3(); // 100
echo $zipcode->zip5(); // 10043;
echo $zipcode->county(); // 臺北市
echo $zipcode->district(); // 中正區
echo $zipcode->address(); // 臺北市中正區中華路1段25號
echo $zipcode->shortAddress(); //中華路1段25號
```

--------------------------------

### Normalize Taiwan Addresses

Source: https://context7.com/recca0120/twzipcode/llms.txt

Normalizes Taiwan addresses using the Normalizer class by converting character variants, handling administrative division changes, and standardizing number formats. It supports chaining multiple normalization methods for complex standardization.

```php
<?php
use Recca0120\Twzipcode\Normalizer;

// Create normalizer and normalize address
$normalizer = new Normalizer('台北市中正區中華路１段25號');
$normalized = $normalizer->normalize()->normalizeAddress();

echo $normalized->value();  // Output: 臺北市中正區中華路1段25號

// Handles various transformations:
// 1. Convert full-width numbers to half-width
$fullWidth = new Normalizer('台北市中正區中華路１段25號');
echo $fullWidth->normalize()->value();  // 台北市中正區中華路1段25號

// 2. Convert traditional county/district names to current names
$oldFormat = new Normalizer('桃園縣中壢市普義10號');
echo $oldFormat->normalizeAddress()->value();  // 桃園市中壢區普義10號

// 3. Convert Chinese numbers to digits
$chineseNum = new Normalizer('中華路一段25號');
echo $chineseNum->digitize()->value();  // 中華路1段25號

// 4. Handle character variants (台 -> 臺)
$variant = new Normalizer('台灣台北台中');
echo $variant->regularize()->value();  // 臺灣臺北臺中

// 5. Remove prefixes and clean up
$withZip = new Normalizer('10043台北市中正區中華路１段25號');
echo $withZip->normalize()->value();  // 台北市中正區中華路1段25號

// Chain multiple normalization methods
$complex = new Normalizer('  台北縣中和市中和路１段25號  ');
echo $complex->trim()->regularize()->digitize()->normalizeAddress()->value();
// Output: 新北市中和區中和路1段25號
?>
```

--------------------------------

### Tokenize Taiwan Addresses

Source: https://context7.com/recca0120/twzipcode/llms.txt

Parses and tokenizes Taiwan addresses into structured components including number, sub-number, name, and unit fields using the Address class. It handles sub-numbers (之) and allows for retrieving flattened address strings with custom length and offset.

```php
<?php
use Recca0120\Twzipcode\Address;

// Create address object and get tokens
$address = new Address('臺北市大安區市府路1號');
$tokens = $address->tokens();

// Tokens structure: [no, subno, name, unit]
print_r((array)$tokens);
/* Output:
Array
(
    [0] => Array ( [0] => , [1] => , [2] => 臺北, [3] => 市 )
    [1] => Array ( [0] => , [1] => , [2] => 大安, [3] => 區 )
    [2] => Array ( [0] => , [1] => , [2] => 市府, [3] => 路 )
    [3] => Array ( [0] => 1, [1] => , [2] => , [3] => 號 )
)
*/

// Handle sub-numbers (之)
$addressWithSubNo = new Address('臺北市大安區市府路1之1號');
$subTokens = $addressWithSubNo->tokens();
print_r((array)$subTokens);
/* Output:
Array
(
    [0] => Array ( [0] => , [1] => , [2] => 臺北, [3] => 市 )
    [1] => Array ( [0] => , [1] => , [2] => 大安, [3] => 區 )
    [2] => Array ( [0] => , [1] => , [2] => 市府, [3] => 路 )
    [3] => Array ( [0] => 1, [1] => 之1, [2] => , [3] => 號 )
)
*/

// Get flattened address string with custom length and offset
echo $address->flat();  // Full address
echo $address->flat(null, 2);  // Skip first 2 tokens (county and district)
echo $address->flat(1, 0);  // Get only first token (county)
?>
```

--------------------------------

### Parse Taiwan Address and Extract Postal Code

Source: https://context7.com/recca0120/twzipcode/llms.txt

Parses a Taiwan address string to extract 3-digit and 5-digit postal codes, county, district, and normalized address formats using the Zipcode::parse method. It supports basic usage and handling of complex addresses with sub-numbers.

```php
<?php
require __DIR__.'/vendor/autoload.php';

use Recca0120\Twzipcode\Zipcode;

// Basic usage - parse address with all variations
$zipcode = Zipcode::parse('台北市中正區中華路１段25號');

// Extract 3-digit postal code
echo $zipcode->zip3();  // Output: 100

// Extract 5-digit postal code
echo $zipcode->zip5();  // Output: 10043

// Get normalized county name
echo $zipcode->county();  // Output: 臺北市

// Get district name
echo $zipcode->district();  // Output: 中正區

// Get full normalized address
echo $zipcode->address();  // Output: 臺北市中正區中華路1段25號

// Get short address (without county and district)
echo $zipcode->shortAddress();  // Output: 中華路1段25號

// Handle complex addresses with sub-numbers
$complexAddress = Zipcode::parse('台中市大里區金城里14鄰塗城路9478巷9478弄9478號');
echo $complexAddress->zip5();  // Output: 41275
echo $complexAddress->address();  // Output: 臺中市大里區金城里14鄰塗城路9478巷9478弄9478號
echo $complexAddress->shortAddress();  // Output: 金城里14鄰塗城路9478巷9478弄9478號
?>
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.