MunicipalityCodeSource.php

<?php
/*
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
 */
/**
 * Italix Rules - MunicipalityCodeSource
 *
 * @package Italix\Rules
 * @license MPL-2.0
 */

declare(strict_types=1);

namespace Italix\Rules;

/**
 * Optional reference data for TaxCodeCheck: does this place-of-birth code
 * exist? (Italy: the four-character "codice Belfiore", e.g. H501 for Rome.)
 *
 * The library ships no such table on purpose. It is large, it changes when
 * municipalities merge, and every application that needs it already has it
 * in its own database — italix/rules would only offer a second, staler copy.
 *
 * So the check states its need as one method and the application satisfies it:
 *
 *     final class DbMunicipalityCodes implements MunicipalityCodeSource
 *     {
 *         public function __construct(private DataManager $dm) {}
 *
 *         public function has_code(string $code_c, string $country_c = 'IT'): bool
 *         {
 *             return $this->dm->query_one(
 *                 'SELECT 1 FROM uni_municipality_it WHERE belfiore_c = ?', [$code_c]
 *             ) !== null;
 *         }
 *     }
 *
 * Without a source, TaxCodeCheck still verifies length, character set and the
 * control character — it just cannot rule out a well-formed code for a place
 * that does not exist.
 */
interface MunicipalityCodeSource
{
    /**
     * @param string $code_c    The place code as it appears inside the tax code
     * @param string $country_c ISO 3166-1 alpha-2 country the code belongs to
     * @return bool
     */
    public function has_code(string $code_c, string $country_c = 'IT'): bool;
}