| name | update-postal-formats |
| description | Updates the $formats array in src/Validator.php from Wikipedia's postal codes list via bin/parse.php. Use when user says 'update formats', 'refresh postal codes', 'sync from Wikipedia', or 'formats are outdated'. Explains the parse.php workflow, MyAdmin dependency requirement, and how to paste output into Validator.php. Do NOT use for adding a single country manually — that is a direct edit to src/Validator.php. |
update-postal-formats
Critical
bin/parse.php cannot run standalone — it requires getcurlpage() and other functions from the parent MyAdmin environment. It must be run from within a MyAdmin install where the MyAdmin bootstrap resolves.- The script also queries the
country_t MySQL table via $GLOBALS['tf']->db to fill in countries not found on Wikipedia. The MyAdmin DB connection must be active.
- Never paste raw Wikipedia wikitext into
src/Validator.php — always run the parser to get properly converted PHP array entries.
- Format symbols:
# = digit [0-9], @ = letter [a-zA-Z]. The parser converts Wikipedia's N → # and A → @ automatically.
Instructions
-
Confirm the MyAdmin environment is available.
Verify the parser script exists:
ls bin/parse.php
If missing, the package is not installed — run composer install first.
-
Run the parser from the MyAdmin root.
The script must be invoked from within the MyAdmin web context or via a bootstrap that initialises $GLOBALS['tf']. Typical invocation:
php bin/parse.php
The script fetches https://en.wikipedia.org/wiki/Special:Export/List_of_postal_codes, parses the wikitext table, merges with country_t DB rows, and prints sorted PHP array lines to stdout.
-
Capture the output.
Redirect to a temp file to review before pasting:
php bin/parse.php > /tmp/new_formats.php
Each output line looks like:
'US' => ['#####', '#####-####'],
'AE' => [],
Verify the output is not empty and contains known countries like 'US', 'CA', 'GB'.
-
Replace the $formats array body in src/Validator.php.
Open src/Validator.php. The array starts at:
protected $formats = [
'AD' => ['AD###'],
and ends with the closing ]; before the next property or method.
Replace everything between protected $formats = [ and its closing ]; with the parser output.
Preserve the existing indentation style (tabs, not spaces — per .scrutinizer.yml).
-
Verify the file is valid PHP.
php -l src/Validator.php
Must output No syntax errors detected.
-
Run the test suite.
vendor/bin/phpunit tests/ -v
All tests must pass. If a previously-passing country now fails, compare the old and new format strings for that country in $formats.
-
Review any countries with empty arrays [].
An empty array means no postal system. Confirm intentional before committing — check Wikipedia directly for that ISO code if uncertain.
Examples
User says: "The postal formats are outdated, can you refresh them from Wikipedia?"
Actions taken:
- Confirmed
bin/parse.php exists.
- Ran
php bin/parse.php > /tmp/new_formats.php — output contained ~250 country entries.
- Opened
src/Validator.php, located protected $formats = [ at line 35.
- Replaced the array body with contents of
/tmp/new_formats.php.
- Ran
php -l src/Validator.php → No syntax errors detected.
- Ran
vendor/bin/phpunit tests/ -v → all tests passed.
Result: $formats in src/Validator.php updated with current Wikipedia data. Example diff:
- 'AF' => ['####'],
+ 'AF' => ['####', '####'],
Common Issues
require /path/to/functions.inc.php: No such file or directory
- You are running
bin/parse.php outside the MyAdmin environment. The MyAdmin bootstrap must be available. Run from within a MyAdmin environment using php bin/parse.php.
Call to undefined function getcurlpage()
function_requirements('getcurlpage') failed to load the function. Verify the MyAdmin bootstrap loaded successfully and that getcurlpage exists in the MyAdmin function files.
Call to a member function query() on null (DB error)
$GLOBALS['tf']->db is not initialised. The script requires an active MyAdmin DB connection. Run it through a MyAdmin bootstrap or CLI entry point that sets up $GLOBALS['tf'].
Empty output from bin/parse.php
- Wikipedia fetch failed or returned unexpected content. Check network access from the server to
en.wikipedia.org. Try curl -s 'https://en.wikipedia.org/wiki/Special:Export/List_of_postal_codes' | head -50 to verify the endpoint is reachable.
PHPUnit test failures after update
- A specific country's format changed. Compare the failing test's expected pattern against the new
$formats entry. If Wikipedia's new data is correct, update the test in tests/Detain/Tests/ZipZapper/ValidatorTest.php. If the new format looks wrong (e.g. a literal ISO code was not replaced), check the get_codes_from() logic in bin/parse.php — it replaces CC with the ISO code, N with #, and A with @.
Tabs vs spaces warning from linter
