php-nederland-postcode/src/NederlandPostcodeClient.php at 48b0eda21f5fc4589513fb7079738976d7f152c9 · Label84/php-nederland-postcode · GitHub

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
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
<?php

namespace Label84\NederlandPostcode;

use GuzzleHttp\Client;
use Label84\NederlandPostcode\DTO\Address;
use Label84\NederlandPostcode\DTO\AddressCollection;
use Label84\NederlandPostcode\DTO\Quota;
use Label84\NederlandPostcode\Enums\AddressAttributesEnum;
use Label84\NederlandPostcode\Exceptions\AddressNotFoundException;
use Label84\NederlandPostcode\Exceptions\MultipleAddressesFoundException;
use Label84\NederlandPostcode\Exceptions\NederlandPostcodeException;
use Label84\NederlandPostcode\Resources\AddressesResource;
use Label84\NederlandPostcode\Resources\EnergyLabelResource;
use Label84\NederlandPostcode\Resources\QuotaResource;

/**
 * @method AddressesResource addresses()
 * @method QuotaResource quota()
 * @method EnergyLabelResource energyLabels()
 * @method AddressCollection<Address> list(string $postcode, int $number, ?string $addition = null, array<int|string, string|AddressAttributesEnum> $attributes = [])
 * @method Address find(string $postcode, int $number, ?string $addition = null, array<int|string, string|AddressAttributesEnum> $attributes = [])
 * @method Quota usage()
 */
class NederlandPostcodeClient
{
    public const DEFAULT_BASE_URL = 'https://api.nederlandpostcode.nl/';

    protected Client $client;

    /**
     * @param  array<string, string>  $headers
     */
    public function __construct(
        public string $key,
        public string $baseUrl = self::DEFAULT_BASE_URL,
        public int $timeout = 5,
        array $headers = []
    ) {
        $this->client = new Client([
            'base_uri' => $this->baseUrl,
            'timeout' => $this->timeout,
            'headers' => array_merge([
                'Authorization' => "Bearer {$this->key}",
                'Accept' => 'application/json',
            ], $headers),
        ]);
    }

    /**
     * @param  array<string, mixed>  $options
     * @return array<mixed, mixed>
     */
    public function request(string $method, string $uri, array $options = []): array
    {
        $response = $this->client->request($method, $uri, $options);

        $body = $response->getBody()->getContents();

        $decoded = json_decode($body, true);

        if (! is_array($decoded)) {
            throw new NederlandPostcodeException('Invalid JSON response from API');
        }
        return $decoded;
    }

    public function addresses(): AddressesResource
    {
        return new AddressesResource($this);
    }

    public function energyLabels(): EnergyLabelResource
    {
        return new EnergyLabelResource($this);
    }

    public function quota(): QuotaResource
    {
        return new QuotaResource($this);
    }

    /**
     * Fetch a list of addresses by postcode, number, and addition.
     *
     * @param  array<int|string, string|AddressAttributesEnum>  $attributes
     * @return AddressCollection<Address>
     */
    public function list(string $postcode, int $number, ?string $addition = null, array $attributes = []): AddressCollection
    {
        return $this->addresses()->get(
            postcode: $postcode,
            number: $number,
            addition: $addition,
            attributes: $attributes,
        );
    }

    /**
     * Fetch a single address by postcode, number, and addition.
     *
     * @param  array<int|string, string|AddressAttributesEnum>  $attributes
     *
     * @throws AddressNotFoundException
     * @throws MultipleAddressesFoundException
     */
    public function find(string $postcode, int $number, ?string $addition = null, array $attributes = []): Address
    {
        $addresses = $this->addresses()->get(
            postcode: $postcode,
            number: $number,
            addition: $addition,
            attributes: $attributes,
        );

        if ($addresses->isEmpty()) {
            throw new AddressNotFoundException();
        } elseif ($addresses->count() > 1) {
            throw new MultipleAddressesFoundException();
        }

        return $addresses->all()[0];
    }

    /**
     * Fetch the current quota usage.
     */
    public function usage(): Quota
    {
        return $this->quota()->get();
    }
}