From 67276c6444a70b61030ab3ee52b84dc5014af0e8 Mon Sep 17 00:00:00 2001 From: Murilo Ijanc Date: Mon, 27 Jul 2026 20:31:30 -0300 Subject: Carry the municipality of a not-found CEP on the exception The API now sends an optional faixa block on the 404 of GET /{cep}, naming the municipality the CEP would have belonged to. That failing CEP is rarely random: it is usually someone who knows the city and guessed the number, most often the -000 that 957 municipalities never received. Knowing the lookup failed "in Areal/RJ" is the difference between a message a user can act on and a bare "CEP not found". It stays an error. Faixa hangs off CepNotFoundException, never off Address, and parsing is deliberately forgiving: a missing, empty or malformed block yields null rather than turning a clean not-found into a parse failure. Its cep_ini/cep_fim are the CEPs that exist, not the bounds the Correios publish, and the interval between them is sparse -- hence ceps, and hence the docblocks insisting the pair is not a list of valid CEPs. --- src/CepNotFoundException.php | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'src/CepNotFoundException.php') diff --git a/src/CepNotFoundException.php b/src/CepNotFoundException.php index c64de8b..e9511e7 100644 --- a/src/CepNotFoundException.php +++ b/src/CepNotFoundException.php @@ -9,7 +9,26 @@ namespace Cepis; * * Extends `\OutOfBoundsException`, the SPL type for a value that is not a * valid key: looking a CEP up is conceptually a key lookup. + * + * {@see CepNotFoundException::$faixa} may name the municipality the CEP would + * have belonged to. It does not soften the answer — the CEP still does not + * exist — it only makes the failure sayable: *"we could not find that CEP in + * Areal/RJ"* rather than *"CEP not found"*. */ final class CepNotFoundException extends \OutOfBoundsException implements CepisException { + /** + * @param Faixa|null $faixa The municipality whose range covers the CEP, or + * `null` when the API sent none — which is the case for a CEP in a band + * no municipality owns, and also whenever the block cannot be read. + * Never assume it is there. See {@see Faixa} for why the range it + * carries is not a list of valid CEPs. + */ + public function __construct( + string $message, + public readonly ?Faixa $faixa = null, + ?\Throwable $previous = null, + ) { + parent::__construct($message, 0, $previous); + } } -- cgit v1.3