Skip to content

Commit 4683b64

Browse files
andrepimpaoandrepimpao
authored
Merge pull request #71 from programmatordev/4.x
v4.0.0
2 parents b6ac5a6 + 9ed07dd commit 4683b64

357 files changed

Lines changed: 28818 additions & 5019 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,17 +10,22 @@ on:
1010
- main
1111
- "*.x"
1212

13+
permissions:
14+
contents: read
15+
1316
jobs:
1417
tests:
1518
name: PHP ${{ matrix.php }} Test
1619
runs-on: ubuntu-latest
20+
timeout-minutes: 10
1721
strategy:
22+
fail-fast: false
1823
matrix:
1924
php: ['8.1', '8.2', '8.3', '8.4', '8.5']
2025

2126
steps:
2227
- name: Checkout code
23-
uses: actions/checkout@v3
28+
uses: actions/checkout@v7
2429

2530
- name: Setup PHP
2631
uses: shivammathur/setup-php@v2
@@ -29,6 +34,10 @@ jobs:
2934
tools: composer:v2
3035
coverage: none
3136

37+
- name: Validate Composer configuration
38+
if: matrix.php == '8.1'
39+
run: composer validate --strict --no-check-lock
40+
3241
- name: Install dependencies
3342
run: composer update --prefer-dist --no-interaction --no-progress
3443

‎.gitignore‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,25 @@
11
/composer.lock
22
/composer.phar
3+
/auth.json
4+
/.env
5+
/.env.*
6+
!/.env.example
37
/phpunit.xml
48
/.phpunit.result.cache
9+
/.phpunit.cache/
510
/vendor/
611
/logs/
7-
/.idea
8-
/index.php
12+
/coverage/
13+
/clover.xml
14+
/coverage.xml
15+
/.idea/
16+
/.vscode/
17+
/.fleet/
18+
/index.php
19+
/plans/
20+
21+
.DS_Store
22+
Thumbs.db
23+
*.swp
24+
*.swo
25+
*~

‎AGENTS.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Project Instructions
2+
3+
## Project Overview
4+
5+
This repository contains a PHP library for accessing OpenWeather APIs. It uses
6+
Composer with PSR-4 autoloading under the
7+
`ProgrammatorDev\OpenWeatherMap` namespace and is built on
8+
`programmatordev/php-api-sdk`.
9+
10+
## Sources Of Truth
11+
12+
- Use the official OpenWeather documentation for endpoint paths, parameters,
13+
response fields, and current access requirements.
14+
- Use the installed PHP API SDK documentation and source for its supported
15+
authoring patterns.
16+
- Read existing resources, entities, tests, and documentation before changing
17+
related behavior.
18+
- Do not infer API access from documentation sidebars; verify it against the
19+
current official API documentation.
20+
21+
## Code Changes
22+
23+
- Prefer focused changes that follow the architecture and naming conventions
24+
documented for the active target version. Do not preserve legacy patterns
25+
when the active public contract intentionally replaces them.
26+
- Organize source files by clear responsibility or domain and mirror that
27+
structure in tests. Keep the root namespace focused on primary entry points;
28+
avoid both unrelated root-level classes and arbitrary one-file folders.
29+
- Reuse shared entities, helpers, resource behavior, test utilities, and
30+
constants when they fit.
31+
- Keep endpoint construction in resource classes and response mapping in typed
32+
entity or response classes.
33+
- Keep request-local fluent options immutable so they do not affect later
34+
resource calls.
35+
- Treat official documentation and representative response fixtures as
36+
complementary schema evidence; neither source is exhaustive on its own.
37+
- Tolerate missing, explicitly `null`, conditional, and unknown response fields.
38+
Reject known non-null fields with invalid types through descriptive hydration
39+
errors rather than silent coercion.
40+
- Represent returned timestamps as nullable UTC `DateTimeImmutable` values and
41+
keep location timezone identifiers or offsets as separate metadata.
42+
- Make destructive operations explicit in method naming and documentation.
43+
- Do not expose API keys through exceptions, logs, fixtures, or committed
44+
example files.
45+
46+
## Dependencies And Tooling
47+
48+
- Run project PHP and Composer commands through DDEV.
49+
- Respect the PHP versions declared by `composer.json` and CI.
50+
- Remove a dependency only when its remaining usages have been eliminated.
51+
- Do not introduce a formatter, static analyzer, or new test framework without
52+
explicit approval.
53+
54+
## Testing
55+
56+
- Use PHPUnit and the existing PSR-18 mock-client approach.
57+
- Do not make live OpenWeather requests in the automated test suite.
58+
- Build automated response tests from sanitized real API captures, supplemented
59+
by synthetic edge-case fixtures. Keep credentials and private or
60+
account-specific data out of committed fixtures.
61+
- Test endpoint method, URL, path parameters, query parameters, headers, body,
62+
response mapping, error mapping, and immutable resource-chain behavior.
63+
- Add focused entity tests for present, missing, explicitly `null`,
64+
conditionally present, unknown, invalidly typed, and nested fields.
65+
- Cover empty-body responses for successful write and delete operations.
66+
- Run the full test suite before handing off an implementation batch when
67+
practical.
68+
69+
## Documentation
70+
71+
- Update public documentation alongside implemented API areas.
72+
- Keep method signatures, examples, supported endpoints, and response entities
73+
aligned with the implementation.
74+
- Avoid hard-coded claims about plans, prices, quotas, or allowances. Link to
75+
the official OpenWeather documentation for current access requirements.
76+
- Document destructive behavior and actions that send additional requests
77+
prominently.

‎README.md‎

Lines changed: 88 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -4,57 +4,118 @@
44
[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE)
55
[![Tests](https://github.com/programmatordev/openweathermap-php-api/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/programmatordev/openweathermap-php-api/actions/workflows/ci.yml?query=branch%3Amain)
66

7-
OpenWeatherMap PHP library that provides convenient access to the OpenWeatherMap API.
7+
A fluent PHP client for OpenWeather APIs covering current and forecast weather,
8+
air pollution, geocoding, maps, stations, and One Call. Responses use typed
9+
entities that safely handle conditional, missing, and `null` data.
810

9-
Supports [PSR-18 HTTP clients](https://www.php-fig.org/psr/psr-18), [PSR-17 HTTP factories](https://www.php-fig.org/psr/psr-17), [PSR-6 caches](https://www.php-fig.org/psr/psr-6) and [PSR-3 logs](https://www.php-fig.org/psr/psr-3).
11+
The library is built on
12+
[`programmatordev/php-api-sdk`](https://github.com/programmatordev/php-api-sdk),
13+
which provides HTTP client discovery and optional caching, logging, plugins,
14+
and request hooks.
1015

1116
## Requirements
1217

13-
- PHP 8.1 or higher.
14-
15-
## API Key
16-
17-
A key is required to be able to make requests to the API.
18-
You must sign up for an [OpenWeatherMap account](https://openweathermap.org/appid#signup) to get one.
18+
- PHP 8.1 or higher
19+
- An OpenWeather API key
1920

2021
## Installation
2122

22-
Install the library via [Composer](https://getcomposer.org/):
23+
Install the library with Composer:
2324

2425
```bash
2526
composer require programmatordev/openweathermap-php-api
2627
```
2728

28-
## Basic Usage
29+
## Getting Started
30+
31+
Create the API client with an OpenWeather API key, then choose an API and call
32+
one of its methods:
33+
34+
```php
35+
use ProgrammatorDev\OpenWeatherMap\OpenWeatherMap;
36+
37+
$api = new OpenWeatherMap($_ENV['OPENWEATHERMAP_API_KEY']);
38+
39+
$current = $api->weather()->current(
40+
latitude: 38.7223,
41+
longitude: -9.1393,
42+
);
43+
44+
echo $current->temperature();
45+
echo $current->temperatureWithUnit();
46+
```
47+
48+
Response properties may be missing or `null`, so getters return nullable values
49+
where appropriate. Collection getters return empty arrays when the response
50+
does not contain that collection.
2951

30-
Simple usage looks like:
52+
## Configuration
53+
54+
The client defaults to metric units and English. The equivalent explicit
55+
configuration is:
3156

3257
```php
58+
use ProgrammatorDev\OpenWeatherMap\Enum\Language;
59+
use ProgrammatorDev\OpenWeatherMap\Enum\Units;
3360
use ProgrammatorDev\OpenWeatherMap\OpenWeatherMap;
3461

35-
// initialize
36-
$api = new OpenWeatherMap('yourapikey');
62+
$api = new OpenWeatherMap(
63+
apiKey: $_ENV['OPENWEATHERMAP_API_KEY'],
64+
options: [
65+
'units' => Units::METRIC,
66+
'language' => Language::ENGLISH,
67+
],
68+
);
69+
```
70+
71+
Weather and One Call requests can override those values for one fluent request
72+
chain. The client-wide configuration remains unchanged for later requests:
3773

38-
// get current weather by coordinate (latitude, longitude)
39-
$weather = $api->weather()->getCurrent(50, 50);
40-
// show current temperature
41-
echo $weather->getTemperature();
74+
```php
75+
$current = $api
76+
->weather()
77+
->withUnits(Units::IMPERIAL)
78+
->withLanguage(Language::PORTUGUESE)
79+
->current(latitude: 38.7223, longitude: -9.1393);
4280
```
4381

82+
`withLanguage()` also accepts a non-empty language-code string, allowing new
83+
OpenWeather languages to be used without waiting for an enum update.
84+
85+
See OpenWeather's
86+
[units of measurement](https://openweathermap.org/api/current?collection=current_forecast#data) and
87+
[multilingual support](https://openweathermap.org/api/current?collection=current_forecast#multi)
88+
documentation for the currently supported values.
89+
4490
## Documentation
4591

46-
- [Usage](docs/01-usage.md)
47-
- [Configuration](docs/02-configuration.md)
48-
- [Supported APIs](docs/03-supported-apis.md)
49-
- [Error Handling](docs/04-error-handling.md)
50-
- [Entities](docs/05-entities.md)
92+
### APIs
93+
94+
These guides cover each API's endpoints, response entities, and usage examples:
95+
96+
- [One Call 4.0](docs/one-call.md)
97+
- [Air Pollution](docs/air-pollution.md)
98+
- [Weather](docs/weather.md)
99+
- [Maps](docs/maps.md)
100+
- [Stations](docs/stations.md)
101+
- [Geocoding](docs/geocoding.md)
102+
103+
### Client Guides
104+
105+
These guides cover client configuration and failures shared across the APIs:
106+
107+
- [Setup](docs/setup.md) — Configure caching, logging, HTTP clients, plugins,
108+
and request hooks.
109+
- [Error Handling](docs/errors.md) — Handle OpenWeather API errors and client
110+
failures.
51111

52-
## Contributing
112+
## Upgrading
53113

54-
Any form of contribution to improve this library (including requests) will be welcome and appreciated.
55-
Make sure to open a pull request or issue.
114+
Version 4 is a complete rewrite without backward compatibility. Existing
115+
integrations should treat it as a new implementation. See
116+
[Upgrading To 4.0](UPGRADE-4.0.md) for the release expectations and current
117+
baseline.
56118

57119
## License
58120

59-
This project is licensed under the MIT license.
60-
Please see the [LICENSE](LICENSE) file distributed with this source code for further information regarding copyright and licensing.
121+
This project is licensed under the [MIT License](LICENSE).

‎UPGRADE-4.0.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Upgrading To 4.0
2+
3+
Version 4 is a complete rewrite. It is not backward compatible with earlier
4+
releases. Existing integrations should adopt it as a new implementation, even
5+
where the usage looks familiar.
6+
7+
## Upgrade Expectations
8+
9+
- Previous resources, entities, methods, namespaces, and configuration are not
10+
part of the current public contract.
11+
- Compatibility aliases, transitional APIs, and an old-to-new API mapping are
12+
not provided.
13+
- Integrations should be rebuilt against the current [README](README.md) and
14+
[API guides](README.md#apis).
15+
- Application tests should be reviewed and updated before adopting the new
16+
release.
17+
18+
## Current Baseline
19+
20+
- PHP 8.1 or later is required.
21+
- The client is built on
22+
[`programmatordev/php-api-sdk` 3](https://github.com/programmatordev/php-api-sdk).
23+
- Current weather, forecasts, air pollution, geocoding, maps, stations, and One
24+
Call 4.0 are supported.
25+
- Metric units and English are the defaults. They can be configured for the
26+
client or changed for one request chain where supported.
27+
- Response entities accept missing, `null`, conditional, and unknown fields.
28+
Known non-null fields with invalid types produce hydration errors.
29+
- OpenWeather API failures use a documented exception hierarchy; transport,
30+
decoding, and hydration failures remain distinguishable. See
31+
[Error Handling](docs/errors.md).
32+
33+
The current documentation defines the supported behavior for this release.

‎composer.json‎

Lines changed: 4 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
{
22
"name": "programmatordev/openweathermap-php-api",
3-
"description": "OpenWeatherMap PHP library that provides convenient access to the OpenWeatherMap API",
3+
"description": "A fluent PHP client for OpenWeather APIs, including weather, air pollution, geocoding, maps, stations, and One Call",
44
"type": "library",
5-
"keywords": ["openweathermap", "api", "php", "php8", "sdk", "psr-18", "psr-17", "psr-6", "psr-3"],
5+
"keywords": ["openweather", "openweathermap", "weather", "forecast", "air-quality", "geocoding", "api", "php", "php8", "sdk", "psr-18", "psr-17", "psr-6", "psr-3"],
66
"license": "MIT",
77
"authors": [
88
{
@@ -13,23 +13,16 @@
1313
],
1414
"require": {
1515
"php": ">=8.1",
16-
"myclabs/deep-copy": "^1.13",
17-
"programmatordev/php-api-sdk": "^2.1",
18-
"symfony/options-resolver": "^6.4|^7.4|^8.0"
16+
"php-http/discovery": "^1.20",
17+
"programmatordev/php-api-sdk": "^3.3"
1918
},
2019
"require-dev": {
21-
"monolog/monolog": "^3.10",
2220
"nyholm/psr7": "^1.8",
2321
"php-http/mock-client": "^1.6",
2422
"phpunit/phpunit": "^10.5",
25-
"symfony/cache": "^6.4|^7.4|^8.0",
2623
"symfony/http-client": "^6.4|^7.4|^8.0",
2724
"symfony/var-dumper": "^6.4|^7.4|^8.0"
2825
},
29-
"provide": {
30-
"psr/http-client-implementation": "1.0",
31-
"psr/http-factory-implementation": "1.0"
32-
},
3326
"autoload": {
3427
"psr-4": {
3528
"ProgrammatorDev\\OpenWeatherMap\\": "src/"

0 commit comments

Comments
 (0)