src/CepNotFoundException.php


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

<?php

declare(strict_types=1);

namespace Cepis;

/**
 * The CEP is well-formed but does not exist in the DNE database.
 *
 * 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);
    }
}