v4.0.0

.github/workflows/ci.yml

@@ -10,17 +10,22 @@ on:
       - main
       - "*.x"
 
+permissions:
+  contents: read
+
 jobs:
   tests:
     name: PHP ${{ matrix.php }} Test
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     strategy:
+      fail-fast: false
       matrix:
         php: ['8.1', '8.2', '8.3', '8.4', '8.5']
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
 
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
@@ -29,6 +34,10 @@ jobs:
           tools: composer:v2
           coverage: none
 
+      - name: Validate Composer configuration
+        if: matrix.php == '8.1'
+        run: composer validate --strict --no-check-lock
+
       - name: Install dependencies
         run: composer update --prefer-dist --no-interaction --no-progress
 

.gitignore

@@ -1,8 +1,25 @@
 /composer.lock
 /composer.phar
+/auth.json
+/.env
+/.env.*
+!/.env.example
 /phpunit.xml
 /.phpunit.result.cache
+/.phpunit.cache/
 /vendor/
 /logs/
-/.idea
-/index.php
+/coverage/
+/clover.xml
+/coverage.xml
+/.idea/
+/.vscode/
+/.fleet/
+/index.php
+/plans/
+
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+*~

AGENTS.md

@@ -0,0 +1,77 @@
+# Project Instructions
+
+## Project Overview
+
+This repository contains a PHP library for accessing OpenWeather APIs. It uses
+Composer with PSR-4 autoloading under the
+`ProgrammatorDev\OpenWeatherMap` namespace and is built on
+`programmatordev/php-api-sdk`.
+
+## Sources Of Truth
+
+- Use the official OpenWeather documentation for endpoint paths, parameters,
+  response fields, and current access requirements.
+- Use the installed PHP API SDK documentation and source for its supported
+  authoring patterns.
+- Read existing resources, entities, tests, and documentation before changing
+  related behavior.
+- Do not infer API access from documentation sidebars; verify it against the
+  current official API documentation.
+
+## Code Changes
+
+- Prefer focused changes that follow the architecture and naming conventions
+  documented for the active target version. Do not preserve legacy patterns
+  when the active public contract intentionally replaces them.
+- Organize source files by clear responsibility or domain and mirror that
+  structure in tests. Keep the root namespace focused on primary entry points;
+  avoid both unrelated root-level classes and arbitrary one-file folders.
+- Reuse shared entities, helpers, resource behavior, test utilities, and
+  constants when they fit.
+- Keep endpoint construction in resource classes and response mapping in typed
+  entity or response classes.
+- Keep request-local fluent options immutable so they do not affect later
+  resource calls.
+- Treat official documentation and representative response fixtures as
+  complementary schema evidence; neither source is exhaustive on its own.
+- Tolerate missing, explicitly `null`, conditional, and unknown response fields.
+  Reject known non-null fields with invalid types through descriptive hydration
+  errors rather than silent coercion.
+- Represent returned timestamps as nullable UTC `DateTimeImmutable` values and
+  keep location timezone identifiers or offsets as separate metadata.
+- Make destructive operations explicit in method naming and documentation.
+- Do not expose API keys through exceptions, logs, fixtures, or committed
+  example files.
+
+## Dependencies And Tooling
+
+- Run project PHP and Composer commands through DDEV.
+- Respect the PHP versions declared by `composer.json` and CI.
+- Remove a dependency only when its remaining usages have been eliminated.
+- Do not introduce a formatter, static analyzer, or new test framework without
+  explicit approval.
+
+## Testing
+
+- Use PHPUnit and the existing PSR-18 mock-client approach.
+- Do not make live OpenWeather requests in the automated test suite.
+- Build automated response tests from sanitized real API captures, supplemented
+  by synthetic edge-case fixtures. Keep credentials and private or
+  account-specific data out of committed fixtures.
+- Test endpoint method, URL, path parameters, query parameters, headers, body,
+  response mapping, error mapping, and immutable resource-chain behavior.
+- Add focused entity tests for present, missing, explicitly `null`,
+  conditionally present, unknown, invalidly typed, and nested fields.
+- Cover empty-body responses for successful write and delete operations.
+- Run the full test suite before handing off an implementation batch when
+  practical.
+
+## Documentation
+
+- Update public documentation alongside implemented API areas.
+- Keep method signatures, examples, supported endpoints, and response entities
+  aligned with the implementation.
+- Avoid hard-coded claims about plans, prices, quotas, or allowances. Link to
+  the official OpenWeather documentation for current access requirements.
+- Document destructive behavior and actions that send additional requests
+  prominently.

README.md

@@ -4,57 +4,118 @@
 [![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE)
 [![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)
 
-OpenWeatherMap PHP library that provides convenient access to the OpenWeatherMap API.
+A fluent PHP client for OpenWeather APIs covering current and forecast weather,
+air pollution, geocoding, maps, stations, and One Call. Responses use typed
+entities that safely handle conditional, missing, and `null` data.
 
-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).
+The library is built on
+[`programmatordev/php-api-sdk`](https://github.com/programmatordev/php-api-sdk),
+which provides HTTP client discovery and optional caching, logging, plugins,
+and request hooks.
 
 ## Requirements
 
-- PHP 8.1 or higher.
-
-## API Key
-
-A key is required to be able to make requests to the API.
-You must sign up for an [OpenWeatherMap account](https://openweathermap.org/appid#signup) to get one.
+- PHP 8.1 or higher
+- An OpenWeather API key
 
 ## Installation
 
-Install the library via [Composer](https://getcomposer.org/):
+Install the library with Composer:
 
 ```bash
 composer require programmatordev/openweathermap-php-api
 ```
 
-## Basic Usage
+## Getting Started
+
+Create the API client with an OpenWeather API key, then choose an API and call
+one of its methods:
+
+```php
+use ProgrammatorDev\OpenWeatherMap\OpenWeatherMap;
+
+$api = new OpenWeatherMap($_ENV['OPENWEATHERMAP_API_KEY']);
+
+$current = $api->weather()->current(
+    latitude: 38.7223,
+    longitude: -9.1393,
+);
+
+echo $current->temperature();
+echo $current->temperatureWithUnit();
+```
+
+Response properties may be missing or `null`, so getters return nullable values
+where appropriate. Collection getters return empty arrays when the response
+does not contain that collection.
 
-Simple usage looks like:
+## Configuration
+
+The client defaults to metric units and English. The equivalent explicit
+configuration is:
 
 ```php
+use ProgrammatorDev\OpenWeatherMap\Enum\Language;
+use ProgrammatorDev\OpenWeatherMap\Enum\Units;
 use ProgrammatorDev\OpenWeatherMap\OpenWeatherMap;
 
-// initialize
-$api = new OpenWeatherMap('yourapikey');
+$api = new OpenWeatherMap(
+    apiKey: $_ENV['OPENWEATHERMAP_API_KEY'],
+    options: [
+        'units' => Units::METRIC,
+        'language' => Language::ENGLISH,
+    ],
+);
+```
+
+Weather and One Call requests can override those values for one fluent request
+chain. The client-wide configuration remains unchanged for later requests:
 
-// get current weather by coordinate (latitude, longitude)
-$weather = $api->weather()->getCurrent(50, 50);
-// show current temperature
-echo $weather->getTemperature();
+```php
+$current = $api
+    ->weather()
+    ->withUnits(Units::IMPERIAL)
+    ->withLanguage(Language::PORTUGUESE)
+    ->current(latitude: 38.7223, longitude: -9.1393);
 ```
 
+`withLanguage()` also accepts a non-empty language-code string, allowing new
+OpenWeather languages to be used without waiting for an enum update.
+
+See OpenWeather's
+[units of measurement](https://openweathermap.org/api/current?collection=current_forecast#data) and
+[multilingual support](https://openweathermap.org/api/current?collection=current_forecast#multi)
+documentation for the currently supported values.
+
 ## Documentation
 
-- [Usage](docs/01-usage.md)
-- [Configuration](docs/02-configuration.md)
-- [Supported APIs](docs/03-supported-apis.md)
-- [Error Handling](docs/04-error-handling.md)
-- [Entities](docs/05-entities.md)
+### APIs
+
+These guides cover each API's endpoints, response entities, and usage examples:
+
+- [One Call 4.0](docs/one-call.md)
+- [Air Pollution](docs/air-pollution.md)
+- [Weather](docs/weather.md)
+- [Maps](docs/maps.md)
+- [Stations](docs/stations.md)
+- [Geocoding](docs/geocoding.md)
+
+### Client Guides
+
+These guides cover client configuration and failures shared across the APIs:
+
+- [Setup](docs/setup.md) — Configure caching, logging, HTTP clients, plugins,
+  and request hooks.
+- [Error Handling](docs/errors.md) — Handle OpenWeather API errors and client
+  failures.
 
-## Contributing
+## Upgrading
 
-Any form of contribution to improve this library (including requests) will be welcome and appreciated.
-Make sure to open a pull request or issue.
+Version 4 is a complete rewrite without backward compatibility. Existing
+integrations should treat it as a new implementation. See
+[Upgrading To 4.0](UPGRADE-4.0.md) for the release expectations and current
+baseline.
 
 ## License
 
-This project is licensed under the MIT license. 
-Please see the [LICENSE](LICENSE) file distributed with this source code for further information regarding copyright and licensing.
+This project is licensed under the [MIT License](LICENSE).

UPGRADE-4.0.md

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

composer.json

@@ -1,8 +1,8 @@
 {
     "name": "programmatordev/openweathermap-php-api",
-    "description": "OpenWeatherMap PHP library that provides convenient access to the OpenWeatherMap API",
+    "description": "A fluent PHP client for OpenWeather APIs, including weather, air pollution, geocoding, maps, stations, and One Call",
     "type": "library",
-    "keywords": ["openweathermap", "api", "php", "php8", "sdk", "psr-18", "psr-17", "psr-6", "psr-3"],
+    "keywords": ["openweather", "openweathermap", "weather", "forecast", "air-quality", "geocoding", "api", "php", "php8", "sdk", "psr-18", "psr-17", "psr-6", "psr-3"],
     "license": "MIT",
     "authors": [
         {
@@ -13,23 +13,16 @@
     ],
     "require": {
         "php": ">=8.1",
-        "myclabs/deep-copy": "^1.13",
-        "programmatordev/php-api-sdk": "^2.1",
-        "symfony/options-resolver": "^6.4|^7.4|^8.0"
+        "php-http/discovery": "^1.20",
+        "programmatordev/php-api-sdk": "^3.3"
     },
     "require-dev": {
-        "monolog/monolog": "^3.10",
         "nyholm/psr7": "^1.8",
         "php-http/mock-client": "^1.6",
         "phpunit/phpunit": "^10.5",
-        "symfony/cache": "^6.4|^7.4|^8.0",
         "symfony/http-client": "^6.4|^7.4|^8.0",
         "symfony/var-dumper": "^6.4|^7.4|^8.0"
     },
-    "provide": {
-        "psr/http-client-implementation": "1.0",
-        "psr/http-factory-implementation": "1.0"
-    },
     "autoload": {
         "psr-4": {
             "ProgrammatorDev\\OpenWeatherMap\\": "src/"