Changed and unified structure (BC breaks)

UPGRADE.md

@@ -0,0 +1,31 @@
+# Upgrade 0.4 to 1.0
+
+- Change all used model classes namespace to 'SmartEmailing\v3\Models'
+(for example `SmartEmailing\v3\Request\Import\Contact` is now `SmartEmailing\v3\Models\Contact`)
+- Change references to namespace `SmartEmailing\v3\Request` to `SmartEmailing\v3\Endpoints`
+- Rename `SmartEmailing\v3\Request\CustomFields\CustomField` to `SmartEmailing\v3\Models\CustomFieldDefinition`
+- Rename `SmartEmailing\v3\Request\Import\CustomField` to `SmartEmailing\v3\Models\CustomFieldValue`
+- Rename `SmartEmailing\v3\Request\Import\Contactlist` to `SmartEmailing\v3\Models\ContactlistStatus`
+- Endpoints `/api/v3/orders` (`$api->eshopOrders()`) and `/api/v3/orders-bulk` (`$api->eshopOrdersBulk()`) are deprecated because SmartEmailing deprecated them in favour of `/api/v3/import-orders`
+
+- `CustomRequest` now returns `CustomResponse` with parsed data using `->data()`
+
+- All `Api` and `Endpoint` methods now follows these conventions:
+  - `something()` sends request immediately and returns `Response` or data (`Model` or `Model[]`)
+  - `somethingRequest()` returns request object that cen be modified and then send by calling `$request->send()`
+  - `get($id): ?Model` - returns Model class by id
+  - `getBySomething($something): ?Model` - returns Model class by id
+  - `list($page = null, $limit = null): array` - returns `Model[]` without filtering
+  - `searchRequest($page = null, $limit = null): Request` - returns search `Request` that can be modified and then send by calling `$request->send()`
+  - `create($data): void` - sends request to create new item
+  - `createRequest($data): Request` - returns create `Request` that can be modified and then send by calling `$request->send()`
+
+- This convetions means for example that now:
+  - `$api->ping()->send()` is just `$api->ping()`
+  - `$api->import()` is `$api->importRequest()`
+  - `$api->customFields()->create()` return `Models\CustomFieldDefinition`
+  - `$api->customFields()->exists()` is `$api->customFields()->getByName()`
+  - for simple list you can use `$api->customFields()->list()`
+  - `$api->contactlists()->lists()` is `$api->contactlists()->list()` and returns `Models\ContactList[]`
+  - `$api->contactlists()->truncate($id)->send()` is `$api->contactlists()->truncate($id)`
+  - `$api->contactlists()->search()` is `$api->contactlists()->searchRequest()`

phpstan.neon

@@ -21,3 +21,8 @@ parameters:
       -
          message: '#^Unreachable statement - code above always terminates\.#'
          path: '*/tests/*'
+      -
+         message: '#.* deprecated .*#'
+         path: '*/tests/*'
+      -
+         message: '#^Class SmartEmailing\\v3\\Endpoints\\Eshops\\.* extends deprecated class SmartEmailing\\v3\\Endpoints\\Eshops\\AbstractEshopOrdersRequest.*#'

readme.md

@@ -10,8 +10,8 @@ API wrapper for [Smart emailing](http://smartemailing.cz) API. Currenlty in deve
 * [Usage](#usage)
 * [Supports](#supports)
 * [Advanced docs](#advanced-docs)
-* [Changelog](#changelog)
 * [Contribution or overriding](#contribution-or-overriding)
+* [Upgrading](#upgrading)
 * [Copyright and License](#copyright-and-license)
 * [Smart emailing API](https://app.smartemailing.cz/docs/api/v3/index.html)
 
@@ -43,14 +43,14 @@ then use the `$api` with desired method/component.
 
 ```php
 // Creates a new instance
-$api->import()->addContact(new Contact('[email protected]'))->send();
+$api->importRequest()->addContact(new Contact('[email protected]'))->send();
 ```
 
 or
 
 ```php
 // Creates a new instance
-$import = $api->import();
+$import = $api->importRequest();
 $contact = new Contact('[email protected]');
 $contact->setName('Martin')->setNameDay('2017-12-11 11:11:11');
 $import->addContact($contact);
@@ -65,13 +65,13 @@ $import->send();
 ```
 ### Error handling
 
-When using the `send()` method in any request class you can catch the error exception `RequestException`.
+When sending any request you can catch the error exception `RequestException`.
 
 ```php
 use SmartEmailing\v3\Exceptions\RequestException;
 
 try {
-    $api->ping()->send();
+    $api->ping();
 } catch (RequestException $exception) {
     $exception->response(); // to get the real response, will hold status and message (also data if provided)
     $exception->request(); // Can be null if the request was 200/201 but API returned error status text
@@ -107,7 +107,7 @@ The import holds 2 main data points:
 
 Example of usage is above.
 
-### [Contact](./src/Request/Import/Contact.php)
+### [Contact](./src/Models/Contact.php)
 
 The import holds 3 main data points:
 1. All data accessible via public properties. Fluent set method has basic validation and date convert logic
@@ -116,7 +116,7 @@ The import holds 3 main data points:
 
 See source code for all methods/properties that you can use
 
-#### [CustomFields](./src/Request/Import/Holder/CustomFields.php) and [ContactLists](./src/Request/Import/Holder/ContactLists.php)
+#### [CustomFields](./src/Models/Holder/CustomFields.php) and [ContactLists](./src/Models/Holder/ContactLists.php)
 
 Uses a data holder with `create`/`add`/`get`/`isEmpty`/`toArray`/`jsonSerialize` methods.
 
@@ -133,16 +133,17 @@ On this object you can create any request that is currently implemented. See bel
 ### Create
 
 Quick way that will create request with required customField
+
 ```php
-use SmartEmailing\v3\Request\CustomFields\CustomField;
-use SmartEmailing\v3\Request\CustomFields\Create\Response;
+use SmartEmailing\v3\Models\CustomFieldDefinition;
 
 ...
 // Create the new customField and send the request now.
-$response = $api->customFields()->create(new CustomField('test', CustomField::TEXT));
+$customField = new CustomFieldDefinition('test', CustomFieldDefinition::TEXT);
+$data = $api->customFields()->create($customField);
 
  // Get the customField in data
-$customFieldId = $response->data()->id;
+$customFieldId = $data->id;
 ```
 
 or
@@ -159,33 +160,36 @@ $customField->setType(CustomField::RADIO)->setName('test');
 
 // Send the request
 $response = $request->send();
+$data = $response->data();
+$customFieldId = $data->id;
 ```
 
 ### Search / List
 [API DOCS](https://app.smartemailing.cz/docs/api/v3/index.html#api-Customfields-Get_Customfields)
 
 Enables searching threw the custom fields with a filter/sort support. Results are limited by 100 per page. The response
-returns meta data (MetaDataInterface) and an array of `CustomField\CustomField` by calling `$response->data()`.
+returns meta data (MetaDataInterface) and an array of `Models\CustomFieldDefinition` by calling `$response->data()`.
 
 #### Response
 
-* data() returns an array `CustomField\CustomField`
+* data() returns an array `Models\CustomFieldDefinition`
 * meta() returns a `stdClass` with properties (defined in `MetaDataInterface`)
 
-#### Get a list without advanced setup
+#### Get a list without advanced search
 Creates a search request and setups only `$page` or `$limit`. The full response from api with `customfield_options_url` or
+
 ```php
-$response = $api->customFields()->search($page = 1);
+$data = $api->customFields()->list();
 
-/** @var \SmartEmailing\v3\Request\CustomFields\CustomField $customField */
-foreach ($response->data() as $customField) {
+/** @var \SmartEmailing\v3\Models\CustomFieldDefinition $customField */
+foreach ($data as $customField) {
     echo $customField->id;
     echo $customField->name;
     echo $customField->type;
 }
 ```
 
-#### Advanced setup - filter/sort/etc
+#### Advanced search - filter/sort/etc
 
 ```php
 $request = $api->customFields()->searchRequest(1);
@@ -196,6 +200,7 @@ $request->sortBy('name');
 
 // Send the request
 $response = $request->send();
+$data = $response->data();
 ```
 ##### Request methods
 
@@ -243,23 +248,23 @@ Allows filtering custom fields with multiple filter conditions.
     * byType($value)
     * byId($value)
 
-### Exists
+### Get by name
 Runs a search query with name filter and checks if the given name is found in customFields. Returns `false` or the `CustomFields\CustomField`.
 Uses send logic (throws RequestException).
 
 ```php
 // Can throw RequestException - uses send.
-if ($customField = $api->customFields()->exists('name')) {
+if ($customField = $api->customFields()->getByName('name')) {
     return $customField->id;
 } else {
     throw new Exception('Not found!', 404);
 }
 ```
-### Send / Transactional emails
+## Send / Transactional emails
 The implementation of API call ``send/transactional-emails-bulk``: https://app.smartemailing.cz/docs/api/v3/index.html#api-Custom_campaigns-Send_transactional_emails
-## Full transactional email example
+### Full transactional email example
 ```php
-$transactionEmail = new TransactionalEmails($api);
+$transactionEmail = $api->transactionalEmailsRequest();
 
 $credentials = new SenderCredentials();
 $credentials->setFrom('[email protected]');
@@ -318,11 +323,11 @@ $transactionEmail->setMessageContents($messageContents);
 $transactionEmail->send();
 ```
 
-### Send / Bulk custom emails
+## Send / Bulk custom emails
 The implementation of API call ``send/custom-emails-bulk``: https://app.smartemailing.cz/docs/api/v3/index.html#api-Custom_campaigns-Send_bulk_custom_emails
-## Full custom email example
+### Full custom email example
 ```php
-$transactionEmail = new BulkCustomEmails($api);
+$transactionEmail = $api->customEmailsBulkRequest();
 
 $credentials = new SenderCredentials();
 $credentials->setFrom('[email protected]');
@@ -362,42 +367,13 @@ $transactionEmail->addTask($task);
 
 $transactionEmail->send();
 ```
-
-
-## E_shops - Add Placed order
-
-The E_shops section have two endpoints to set single Order or import orders in bulk.
-
-Example add single order
-```php
-use \SmartEmailing\v3\Request\Eshops\Model\Order;
-use \SmartEmailing\v3\Request\Eshops\Model\OrderItem;
-use \SmartEmailing\v3\Request\Eshops\Model\Price;
-
-$order = new Order('my-eshop', 'ORDER0001', '[email protected]');
-$order->orderItems()->add(
-    new OrderItem(
-        'ABC123',   // item Id
-        'My Product', // item name
-        10,          // quantity
-        new Price(
-            100, // without vat
-            121, // with vat
-            'CZK' // currency code
-        ),
-        'https://myeshop.cz/product/ABC123'  // product url
-    )
-);
-$api->eshopOrders()->addOrder($order)->send();
-```
-
-### Send / Bulk custom sms
+## Send / Bulk custom sms
 The implementation of API call ``send/custom-sms-bulk``: https://app.smartemailing.cz/docs/api/v3/index.html#api-Custom_campaigns-Send_bulk_custom_SMS
 
-## Full send sms example
+### Full send sms example
 
 ```php
-$bulkCustomSms = new BulkCustomSms($api);
+$bulkCustomSms = $api->customSmsBulkRequest();
 
 $recipient = new Recipient();
 $recipient->setEmailAddress('[email protected]');
@@ -423,6 +399,10 @@ $bulkCustomSms->addTask($task);
 $bulkCustomSms->send();
 ```
 
+## Upgrading
+See [UPGRADE.md](UPGRADE.md) for how to upgrade to newer versions.
+
+
 ## Contribution or overriding
 See [CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute changes. All contributions are welcome.