Merge pull request #28 from MarcinOrlowski/client-update-6953

Release 1.3.0

.markdownlint.yaml.dist

@@ -78,7 +78,8 @@ MD013:
   # Include code blocks
   code_blocks: true
   # Include tables
-  tables: true
+  # tables: true
+  tables: false  # MOR
   # Include headings
   headings: true
   # Include headings

CHANGES.md

@@ -6,6 +6,20 @@ Olza Logistic's Pickup Point API Client PHP library.
 
 # Changelog
 
+* v1.3.0-dev (YYYY-MM-DD)
+  * Added `withHttpClient()` and `withRequestFactory()` methods to `Client` builder.
+  * Removed `withGuzzleHttpClient()` as Guzzle no longer needs special treatment.
+  * Removed `withSymfonyHttpClient()`. See docs on how to use Symfony HTTP client.
+  * Removed `withPsrClient()`. Use `withHttpClient()` and `withRequestClient()` instead.
+  * Attempt to modify sealed client now throws `ClientAlreadyInitializedException`.
+  * Attempt to access not sealed client now throws `ClientNotSealedException`.
+  * Improved construction of `Config` response object.
+  * The `Spedition::getLabel()` now returns spedition code if no label is returned by API.
+  * Implemented `Arrayable` contact (`toArray()`) for response data classes.
+  * Updated tests.
+  * Updated library documentation.
+
+
 * v1.2.2 (2023-10-06)
   * Fixed API response code not being included in the thrown exception.
   * Added dedicated exceptions to reflect API error codes (when `throwOnError` is enabled).

README.md

@@ -2,29 +2,29 @@
 
 # PP API Client for PHP
 
-The PP API Client is a robust library for PHP 7.4 or newer, designed to interact with the Pickup
-Points (PP) API service offered by Olza Logistic, facilitating seamless access to a comprehensive
-database of parcel delivery pickup points. This library empowers developers to execute precise
-queries to fetch information about pickup points across various parameters. With the PP API Client,
-one can effortlessly:
-
-* search for pickup points in a specified country,
-* filter pickup points based on the courier service,
-* distinguish between different types of pickup points such as lockers or offices,
-* locate pickup points in proximity to a defined location,
-* retrieve detailed information about individual pickup points.
-
-Whether integrating a parcel delivery system or enhancing the user experience by providing
-convenient pickup options, the PP API Client library is an indispensable tool that offers a
-streamlined interface to the PP API service, thereby simplifying the development process and
-augmenting the functionality of parcel delivery-related applications.
+The PP API Client is a robust library tailored for PHP 7.4 or newer, designed to interact with the
+Pickup Points (PP) API service offered by Olza Logistic. This library facilitates seamless access to
+a comprehensive database of parcel delivery pickup points, empowering developers to execute precise
+queries to retrieve information about pickup points based on various parameters. With the PP API
+Client, one can effortlessly:
+
+* Search for pickup points in a specified country,
+* Filter pickup points based on the courier service,
+* Distinguish between different types of pickup points, such as lockers or offices,
+* Locate pickup points in proximity to a defined location,
+* Retrieve detailed information about individual pickup points.
+
+Whether you're integrating a parcel delivery system or enhancing the user experience by providing
+convenient pickup options, the PP API Client library is an indispensable tool. It offers
+a streamlined interface to the PP API service, simplifying the development process and augmenting
+the functionality of parcel delivery-related applications.
 
 ---
 
 ## Documentation
 
 * [Requirements](docs/installation.md)
-* [Usage examples](examples.md)
+* [Usage examples](docs/examples/README.md)
 * [Library API reference](docs/README.md)
 
 ---

docs/README.md

@@ -4,18 +4,10 @@
 
 # PP API Client for PHP
 
-* **[« Go back](README.md)**
+**[« Go back to main README](../README.md)**
+
 * [Library requirements](requirements.md)
 * [Installation](installation.md)
-* Library API reference
-  * [`Client` class - gateway to the PP API](client.md#gateway-to-the-api)
-    * [Creating client instance](client.md#instantiation)
-    * Public API methods
-      * [`config(Params $params): Result;`](client.md#configparams-params-result)
-      * [`details(Params $params): Result;`](client.md#detailsparams-params-result)
-      * [`find(Params $params): Result;`](client.md#findparams-params-result)
-      * [`search(Params $params): Result;`](client.md#searchparams-params-result)
-  * [`Params` class - passing method arguments](params.md#passing-method-arguments)
-  * [`Result` class - accessing response data](response.md#accessing-response-data)
-    * [`Data` class - accessing response payload](response.md#accessing-response-payload)
-  * [Exceptions](exceptions.md)
+* [Public API methods](api.md)
+* [Library classes reference](classes.md)
+* [Usage examples](examples/README.md)

docs/api.md

@@ -0,0 +1,105 @@
+![Olza Logistic Logo](olza-logo-small.png)
+
+---
+
+# PP API Client for PHP
+
+* [Library requirements](requirements.md)
+* [Installation](installation.md)
+* Public API methods
+  * [`config(Params $params): Result;`](#configparams-params-result)
+  * [`details(Params $params): Result;`](#detailsparams-params-result)
+  * [`find(Params $params): Result;`](#findparams-params-result)
+  * [`nearby(Params $params): Result;`](#nearbyparams-params-result)
+* [Library classes reference](classes.md)
+
+---
+
+## Usage
+
+To simplify the usage of the library, all public methods provided by the library expect arguments to
+be passed using the [Params](params.md) class. All response data is also returned, encapsulated
+within a unified [Result](response.md) class object. For those who prefer handling exceptions rather
+than checking the result, there's a mode that transforms each unsuccessful API response into a
+corresponding exception (for more information, see the details
+on [Client class instantiation](client.md)).
+
+---
+
+## Public API methods
+
+The following public methods serve as you gateway to PP API:
+
+### `config(Params $params): Result;`
+
+Returns current vital information about PP API environment.
+
+![Note](note.png)  It's highly recommended to invoke the `config/` method as the very first method
+during your PP API communication session. This method is expected to return vital runtime parameters
+back to the client, allowing you to act accordingly. For instance, `config/` will return a list of
+all currently available carriers (and their IDs), providing foresight on what to expect from other
+carrier-dependent methods.
+
+Required arguments:
+
+* `country` - **(required)** country code (use `Country::xxx` consts)
+
+[See usage example](examples/config.md)
+
+---
+
+### `details(Params $params): Result;`
+
+Return details about specific Pickup Point.
+
+Required arguments:
+
+* `country` - **(required)** country code (use `Country::xxx` consts)
+* `spedition` - **(required)** one (string) or more (array of strings)
+* `id` - **(required)** Pickup point identifier
+
+[See usage example](examples/details.md)
+
+---
+
+### `find(Params $params): Result;`
+
+Searches for available pickup points that match the provided parameters.
+
+Required arguments:
+
+* `country` - **[required]** country code (use `Country::xxx` consts).
+* `spedition` - **[required]** either a single spedition (string) or multiple speditions (array of
+  strings).
+
+Optional arguments:
+
+* `search` - A search string that will be additionally matched against pickup point names,
+  identifiers, addresses, etc.
+* `services` - A list of services (see `ServiceType::*`) that a pickup point must support to be
+  included in the returned dataset. **NOTE: services are `OR`ed, so supporting just one suffices.**
+* `payments` - A list of payment types (see `PaymentType::*`) that a pickup point must support to be
+  included in the returned dataset. **NOTE: payment types are `OR`ed, so supporting just one
+  suffices.**
+* `limit` - The maximum number of items to be returned. The default is to return all matching items
+  (API cap limit may apply).
+
+[See usage example](examples/find.md)
+
+---
+
+### `nearby(Params $params): Result;`
+
+Searches for pickup points located near a specified geographic location.
+
+Required arguments:
+
+* `country` - **[required]** country code (use `Country::xxx` consts).
+* `spedition` - **[required]** either a single spedition (string) or multiple speditions (array of
+  strings).
+* `coords` - **[required]** geographic coordinates to search near. The value should be a string in
+  the format `latitude,longitude`.
+* `limit` - The maximum number of items to be returned. The default is to return all matching
+  items (API cap limit may apply).
+
+[See usage example](examples/nearby.md)

docs/classes.md

@@ -0,0 +1,40 @@
+![Olza Logistic Logo](olza-logo-small.png)
+
+---
+
+# PP API Client for PHP
+
+* [Library requirements](requirements.md)
+* [Installation](installation.md)
+* [Public API methods](api.md)
+* Library classes reference
+* [Exceptions](exceptions.md)
+
+---
+
+## `Client` - gateway to PP API
+
+The `Client` class serves as your gateway to the PP API. It acts as a wrapper around the HTTP client
+library, handling the intricacies of communicating with the API and processing responses.
+
+[`Client` class API documentation](client.md)
+
+---
+
+## `Params` - method arguments vessel
+
+All public client methods requiring arguments expect instance of `Params` class as argument, with
+all the method required arguments set using all exposed `withXXX()` helper methods.
+
+[`Params` class API documentation](params.md)
+
+---
+
+## `Result` - response data container
+
+Client responses are always provided as instances of the `Result` class. The object is immutable,
+and for ease of use, `Result` is a subclass
+of [ArrayObject](https://www.php.net/manual/en/class.arrayobject.php) and aside from exposing useful
+methods, it also acts as a regular array.
+
+[`Result` class API documentation](response.md)