Merge pull request #65 from programmatordev/3.x

v3.0.0

Author: andrepimpao

.ddev/config.yaml

@@ -20,27 +20,31 @@ disable_upload_dirs_warning: true
 
 # name: <projectname> # Name of the project, automatically provides
 #   http://projectname.ddev.site and https://projectname.ddev.site
+# If the name is omitted, the project will take the name of the enclosing directory,
+# which is useful if you want to have a copy of the project side by side with this one.
 
-# type: <projecttype>  # backdrop, craftcms, django4, drupal, drupal6, drupal7, laravel, magento, magento2, php, python, shopware6, silverstripe, typo3, wordpress
-# See https://ddev.readthedocs.io/en/stable/users/quickstart/ for more
+# type: <projecttype>  # backdrop, cakephp, craftcms, drupal, drupal6, drupal7, drupal8, drupal9, drupal10, drupal11, generic, laravel, magento, magento2, php, shopware6, silverstripe, symfony, typo3, wordpress
+# See https://docs.ddev.com/en/stable/users/quickstart/ for more
 # information on the different project types
-# "drupal" covers recent Drupal 8+
 
 # docroot: <relative_path> # Relative path to the directory containing index.php.
 
-# php_version: "8.2"  # PHP version to use, "5.6", "7.0", "7.1", "7.2", "7.3", "7.4", "8.0", "8.1", "8.2", "8.3"
+# php_version: "8.3"  # PHP version to use, "5.6" through "8.4"
 
 # You can explicitly specify the webimage but this
 # is not recommended, as the images are often closely tied to DDEV's' behavior,
 # so this can break upgrades.
 
-# webimage: <docker_image>  # nginx/php docker image.
+# webimage: <docker_image>
+# It’s unusual to change this option, and we don’t recommend it without Docker experience and a good reason.
+# Typically, this means additions to the existing web image using a .ddev/web-build/Dockerfile.*
 
 # database:
 #   type: <dbtype> # mysql, mariadb, postgres
 #   version: <version> # database version, like "10.11" or "8.0"
-#   MariaDB versions can be 5.5-10.8 and 10.11, MySQL versions can be 5.5-8.0
-#   PostgreSQL versions can be 9-16.
+#   MariaDB versions can be 5.5-10.8, 10.11, 11.4, 11.8
+#   MySQL versions can be 5.5-8.0, 8.4
+#   PostgreSQL versions can be 9-17
 
 # router_http_port: <port>  # Port to be used for http (defaults to global configuration, usually 80)
 # router_https_port: <port> # Port for https (defaults to global configuration, usually 443)
@@ -50,14 +54,25 @@ disable_upload_dirs_warning: true
 # "ddev xdebug" to enable Xdebug and "ddev xdebug off" to disable it work better,
 # as leaving Xdebug enabled all the time is a big performance hit.
 
-# xhprof_enabled: false  # Set to true to enable Xhprof and "ddev start" or "ddev restart"
-# Note that for most people the commands
-# "ddev xhprof" to enable Xhprof and "ddev xhprof off" to disable it work better,
-# as leaving Xhprof enabled all the time is a big performance hit.
+# xhgui_http_port: "8143"
+# xhgui_https_port: "8142"
+# The XHGui ports can be changed from the default 8143 and 8142
+# Very rarely used
+
+# host_xhgui_port: "8142"
+# Can be used to change the host binding port of the XHGui
+# application. Rarely used; only when port conflict and
+# bind_all_ports is used (normally with router disabled)
+
+# xhprof_mode: [prepend|xhgui|global]
+# Set to "xhgui" to enable XHGui features
+# "xhgui" will become default in a future major release
 
-# webserver_type: nginx-fpm, apache-fpm, or nginx-gunicorn
+# webserver_type: nginx-fpm, apache-fpm, generic
 
 # timezone: Europe/Berlin
+# If timezone is unset, DDEV will attempt to derive it from the host system timezone
+# using the $TZ environment variable or the /etc/localtime symlink.
 # This is the timezone used in the containers and by PHP;
 # it can be set to any valid timezone,
 # see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
@@ -77,16 +92,14 @@ disable_upload_dirs_warning: true
 #   - preview
 #   - snapshot
 # Alternatively, an explicit Composer version may be specified, for example "2.2.18".
-# To reinstall Composer after the image was built, run "ddev debug refresh".
+# To reinstall Composer after the image was built, run "ddev debug rebuild".
 
-# nodejs_version: "20"
+# nodejs_version: "22"
 # change from the default system Node.js version to any other version.
-# Numeric version numbers can be complete (i.e. 18.15.0) or
-# incomplete (18, 17.2, 16). 'lts' and 'latest' can be used as well along with
-# other named releases.
-# see https://www.npmjs.com/package/n#specifying-nodejs-versions
-# Note that you can continue using 'ddev nvm' or nvm inside the web container
-# to change the project's installed node version if you need to.
+# See https://docs.ddev.com/en/stable/users/configuration/config/#nodejs_version for more information
+# and https://www.npmjs.com/package/n#specifying-nodejs-versions for the full documentation,
+# Note that using of 'ddev nvm' is discouraged because "nodejs_version" is much easier to use,
+# can specify any version, and is more robust than using 'nvm'.
 
 # corepack_enable: false
 # Change to 'true' to 'corepack enable' and gain access to latest versions of yarn/pnpm
@@ -119,7 +132,7 @@ disable_upload_dirs_warning: true
 
 # ddev_version_constraint: ""
 # Example:
-# ddev_version_constraint: ">= 1.22.4"
+# ddev_version_constraint: ">= 1.24.8"
 # This will enforce that the running ddev version is within this constraint.
 # See https://github.com/Masterminds/semver#checking-version-constraints for
 # supported constraint formats
@@ -148,8 +161,8 @@ disable_upload_dirs_warning: true
 #   - "mutagen": enables Mutagen for this project.
 #   - "nfs":     enables NFS for this project.
 #
-# See https://ddev.readthedocs.io/en/stable/users/install/performance/#nfs
-# See https://ddev.readthedocs.io/en/stable/users/install/performance/#mutagen
+# See https://docs.ddev.com/en/stable/users/install/performance/#nfs
+# See https://docs.ddev.com/en/stable/users/install/performance/#mutagen
 
 # fail_on_hook_fail: False
 # Decide whether 'ddev start' should be interrupted by a failing hook
@@ -198,17 +211,17 @@ disable_upload_dirs_warning: true
 
 # ngrok_args: --basic-auth username:pass1234
 # Provide extra flags to the "ngrok http" command, see
-# https://ngrok.com/docs/ngrok-agent/config or run "ngrok http -h"
+# https://ngrok.com/docs/agent/config/v3/#agent-configuration or run "ngrok http -h"
 
 # disable_settings_management: false
 # If true, DDEV will not create CMS-specific settings files like
-# Drupal's settings.php/settings.ddev.php or TYPO3's AdditionalConfiguration.php
+# Drupal's settings.php/settings.ddev.php or TYPO3's additional.php
 # In this case the user must provide all such settings.
 
 # You can inject environment variables into the web container with:
 # web_environment:
-# - SOMEENV=somevalue
-# - SOMEOTHERENV=someothervalue
+#     - SOMEENV=somevalue
+#     - SOMEOTHERENV=someothervalue
 
 # no_project_mount: false
 # (Experimental) If true, DDEV will not mount the project into the web container;
@@ -276,7 +289,7 @@ disable_upload_dirs_warning: true
 # Many DDEV commands can be extended to run tasks before or after the
 # DDEV command is executed, for example "post-start", "post-import-db",
 # "pre-composer", "post-composer"
-# See https://ddev.readthedocs.io/en/stable/users/extend/custom-commands/ for more
+# See https://docs.ddev.com/en/stable/users/extend/custom-commands/ for more
 # information on the commands that can be extended and the tasks you can define
 # for them. Example:
 #hooks:

.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        php: ['8.1', '8.2', '8.3']
+        php: ['8.1', '8.2', '8.3', '8.4']
 
     steps:
       - name: Checkout code

composer.json

@@ -6,25 +6,25 @@
     "license": "MIT",
     "authors": [
         {
-            "name": "André Pimpão",
-            "email": "a.pimpao@programmator.dev",
+            "name": "Programmator",
+            "email": "hotline@programmator.dev",
             "homepage": "https://programmator.dev"
         }
     ],
     "require": {
         "php": ">=8.1",
-        "myclabs/deep-copy": "^1.11",
-        "programmatordev/php-api-sdk": "^1.0",
-        "programmatordev/yet-another-php-validator": "^1.1"
+        "myclabs/deep-copy": "^1.13",
+        "programmatordev/php-api-sdk": "^2.1",
+        "symfony/options-resolver": "^6.4|^7.3"
     },
     "require-dev": {
-        "monolog/monolog": "^3.6",
+        "monolog/monolog": "^3.9",
         "nyholm/psr7": "^1.8",
         "php-http/mock-client": "^1.6",
         "phpunit/phpunit": "^10.5",
-        "symfony/cache": "^6.4",
-        "symfony/http-client": "^6.4",
-        "symfony/var-dumper": "^6.4"
+        "symfony/cache": "^6.4|^7.3",
+        "symfony/http-client": "^6.4|^7.3",
+        "symfony/var-dumper": "^6.4|^7.3"
     },
     "provide": {
         "psr/http-client-implementation": "1.0",

docs/02-configuration.md

@@ -72,7 +72,7 @@ $api = new OpenWeatherMap('yourapikey', [
 > To get to know about all the available methods, make sure to check the documentation [here](https://github.com/programmatordev/php-api-sdk?tab=readme-ov-file#documentation).
 
 The following sections have examples of some of the most important methods, 
-particularly related with the configuration of the client, cache and logger.
+particularly related to the configuration of the client, cache and logger.
 
 ### `setClientBuilder`
 

docs/03-supported-apis.md

@@ -5,6 +5,10 @@
     - [getWeather](#getweather)
     - [getWeatherByDate](#getweatherbydate)
     - [getWeatherSummaryByDate](#getweathersummarybydate)
+    - [getWeatherOverviewByDate](#getweatheroverviewbydate)
+  - [AI Assistant](#ai-assistant)
+    - [startSession](#startsession)
+    - [resumeSession](#resumesession)
   - [Weather](#weather)
     - [getCurrent](#getcurrent)
     - [getForecast](#getforecast)
@@ -68,6 +72,51 @@ Returns a [`WeatherSummary`](05-entities.md#weathersummary) object:
 $weatherSummary = $api->oneCall()->getWeatherSummaryByDate(50, 50, new \DateTime('1985-07-19'));
 ```
 
+#### `getWeatherOverviewByDate`
+
+```php
+getWeatherOverviewByDate(float $latitude, float $longitude, \DateTimeInterface $date): WeatherOverview
+```
+
+Get the weather overview with a human-readable summary for today and tomorrow's forecast, 
+using OpenWeather AI.
+
+Returns a [`WeatherOverview`](05-entities.md#weatheroverview) object:
+
+```php
+$weatherOverview = $api->oneCall()->getWeatherOverviewByDate(50, 50, new \DateTime('today'));
+```
+
+### AI Assistant
+
+#### `startSession`
+
+```php
+startSession(string $prompt): Answer
+```
+
+Start a new session (create a new conversation) with the Weather AI Assistant.
+
+Returns a [`Answer`](05-entities.md#answer) object:
+
+```php
+$answer = $api->assistant()->startSession('How is the weather today in Lisbon?');
+```
+
+#### `resumeSession`
+
+```php
+resumeSession(string $sessionId, string $prompt): Answer
+```
+
+Resume a session (continue a conversation) with the Weather AI Assistant.
+
+Returns a [`Answer`](05-entities.md#answer) object:
+
+```php
+$answer = $api->assistant()->resumeSession('session-id', 'Do I need an umbrella?');
+```
+
 ### Weather
 
 #### `getCurrent`
@@ -176,7 +225,7 @@ $locations = $api->geocoding()->getByLocationName('lisbon');
 getByCoordinate(float $latitude, float $longitude, int $numResults = 5): array
 ```
 
-Get name of the location (city name or area name) by using geographical coordinates (latitude, longitude). 
+Get the name of the location (city name or area name) by using geographical coordinates (latitude, longitude). 
 
 Returns an array of [`Location`](05-entities.md#location) objects.
 
@@ -245,7 +294,7 @@ withCacheTtl(?int $ttl): self
 Makes a request and saves into cache for the provided duration in seconds. 
 
 Semantics of values:
-- `0`, the response will not be cached (if the servers specifies no `max-age`).
+- `0`, the response will not be cached (if the server specifies no `max-age`).
 - `null`, the response will be cached for as long as it can (forever).
 
 > [!NOTE]

docs/04-error-handling.md

@@ -1,8 +1,5 @@
 # Error Handling
 
-- [API Errors](#api-errors)
-- [Validation Errors](#validation-errors)
-
 ## API Errors
 
 To handle API response errors, multiple exceptions are provided. You can see all available in the following example:
@@ -15,13 +12,9 @@ use ProgrammatorDev\OpenWeatherMap\Exception\UnauthorizedException;
 use ProgrammatorDev\OpenWeatherMap\Exception\UnexpectedErrorException;
 
 try {
-    $location = $api->geocoding()->getByZipCode('1000-001', 'pt');
-    $coordinate = $location->getCoordinate();
+    // ...
 
-    $weather = $api->oneCall()->getWeather(
-        $coordinate->getLatitude(), 
-        $coordinate->getLongitude()
-    );
+    $weather = $api->oneCall()->getWeather($latitude, $longitude);
 }
 // bad request to the API
 catch (BadRequestException $exception) {
@@ -33,7 +26,7 @@ catch (UnauthorizedException $exception) {
     echo $exception->getCode(); // 401
     echo $exception->getMessage();
 }
-// resource not found
+// resource not found,
 // for example, when trying to get a location with a zip code that does not exist
 catch (NotFoundException $exception) {
     echo $exception->getCode(); // 404
@@ -57,35 +50,13 @@ To catch all API errors with a single exception, `ApiErrorException` is availabl
 use ProgrammatorDev\OpenWeatherMap\Exception\ApiErrorException;
 
 try {
-    $location = $api->geocoding()->getByZipCode('1000-001', 'pt');
-    $coordinate = $location->getCoordinate();
-    
-    $weather = $api->oneCall()->getWeather(
-        $coordinate->getLatitude(), 
-        $coordinate->getLongitude()
-    );
+    // ...
+
+    $weather = $api->oneCall()->getWeather($latitude, $longitude);
 }
 // catches all API response errors
 catch (ApiErrorException $exception) {
     echo $exception->getCode();
     echo $exception->getMessage();
 }
-```
-
-## Validation Errors
-
-To catch invalid input data (like an out of range coordinate, blank location name, etc.), the `ValidationException` is available:
-
-```php
-use ProgrammatorDev\Validator\Exception\ValidationException;
-
-try {
-    // an invalid latitude value is given
-    $weather = $api->weather()->getCurrent(999, 50);
-}
-catch (ValidationException $exception) {
-    // should print:
-    // The latitude value should be between -90 and 90, 999 given.
-    echo $exception->getMessage();
-}
 ```