Merge pull request #36 from SpearDevs/dev/update-readme

[OS-23] - Readme update

README.md

@@ -1,7 +1,15 @@
+![img.png](docs/images/img_header.png)
 # Sylius Push Notification Plugin
 
 Plugin for Sylius, based on the [bpolaszek/webpush-bundle](https://github.com/bpolaszek/webpush-bundle) package, enabling the sending of push notifications within an online store. This plugin provides the functionality to send push notifications in two key scenarios: after order placement and after order shipment. Additionally, it allows for the sending of push notifications to individual users or user groups.
 
+### Documentation:
+After installation, read more about using the plugin and its functions for the user and administrator.
+
+1. [More about plugin usage.](docs/usage.md)
+2. [Customer section.](docs/customer_experience.md)
+3. [Administrator section.](docs/admin_experience.md)
+
 ### Instalation
 
 1. Run `composer require speardevs/sylius-push-notifications-plugin`.

docs/admin_experience.md

@@ -0,0 +1,26 @@
+![img.png](images/img_header.png)
+
+## Administrator Experience: 
+1. New menu in the administration panel
+
+    ![img_3.png](images/img_3.png)
+
+2.Panel for sending push notifications to a user or group:
+    ![img_4.png](images/img_4.png)
+
+    1. Push notification title - required
+    2. Push notification content - required
+    3. Channel, push notifications are sent depending on the selected channel.
+    4. You can send push notifications to a group or user.
+    5. Here you select a defined group of users or a specific user to whom the push notification will be sent.
+
+
+3. Here you define an object of the `SpearDevs\SyliusPushNotificationsPlugin\Entity\PushNotificationTemplate` class
+   You can use these objects to send push notifications later
+    ![img_5.png](images/img_5.png)
+
+4. An example panel with push notification history:
+    ![img_6.png](images/img_6.png)
+
+5. Example panel with push notification configuration:
+    ![img_7.png](images/img_7.png)

docs/customer_experience.md

@@ -0,0 +1,13 @@
+![img.png](images/img_header.png)
+
+## Customer Experience: 
+1. Push notifications will only be sent to users who have consented to them. The user can consent after logging in in the Push Notifications tab. At the address: `/account/push-notifications`.
+![img_1.png](images/img_1.png)
+
+
+2. All push notifications sent to the client are available in the Push notification history tab. At the address `/account/push-notifications-history`
+    ![img_1.png](images/img.png)
+
+
+3. An example of a push notification sent from the dekstop level.
+    ![img_2.png](images/img_2.png)

docs/usage.md

@@ -0,0 +1,156 @@
+![img.png](images/img_header.png)
+
+## Usage
+
+The class is responsible for sending push notifications
+
+`SpearDevs\SyliusPushNotificationsPlugin\WebPushSender`
+
+Here you can use 3 class methods:
+
+```php
+    public function sendToGroup(WebPushInterface $webPush, ChannelInterface $channel, ?string $receiver = null): void;
+
+    public function sendToUser(WebPushInterface $webPush, ChannelInterface $channel, ?string $receiver = null): void;
+
+    public function sendOrderWebPush(OrderInterface $order, string $pushNotificationCode, ChannelInterface $channel): void;
+```
+
+
+Below you will find an example of a function that is used to send push notifications when a product is available. This function can be used in an event or in a command that will be configured from cron.
+As you can see, the `$webPush` object is created by `WebPushFactoryInterface`.
+
+#### `$webPushFactory` needs:
+- A class that extends `SpearDevs\SyliusPushNotificationsPlugin\ParameterMapper\AbstractParameterMapper`
+- A class that implement `Sylius\Component\Resource\Model\ResourceInterface`
+- and object of class `SpearDevs\SyliusPushNotificationsPlugin\Entity\PushNotificationTemplate\PushNotificationTemplate`
+
+You can pass the object `$webPush` created this way to the function `sendToUser` along with actual Channel as `$channel` and the user's email as `$receiver` to send push notification.
+
+```php
+# Example of WebPushManager you can implement
+<?php
+
+declare(strict_types=1);
+
+namespace App\WebPush;
+
+use App\Entity\Product\Product;
+use App\WebPush\ParameterMapper\ProductParameterMapper;
+use SpearDevs\SyliusPushNotificationsPlugin\Context\ChannelContextInterface;
+use SpearDevs\SyliusPushNotificationsPlugin\Factory\Interfaces\WebPushFactoryInterface;
+use SpearDevs\SyliusPushNotificationsPlugin\Repository\PushNotificationTemplate\PushNotificationTemplateRepositoryInterface;
+use SpearDevs\SyliusPushNotificationsPlugin\WebPushSender\WebPushSenderInterface;
+use Sylius\Component\Core\Model\ChannelInterface;
+
+final class WebPushManager
+{
+    public function __construct(
+        private readonly WebPushSenderInterface $webPushSender,
+        private readonly WebPushFactoryInterface $webPushFactory,
+        private readonly ProductParameterMapper $productParameterMapper,
+        private readonly PushNotificationTemplateRepositoryInterface $pushNotificationTemplateRepository,
+        private readonly ChannelContextInterface $channelContext,
+    ) {
+    }
+
+    public function sendProductAvailableWebPush(
+        string $receiver,
+        ChannelInterface $channel,
+        Product $product,
+        string $pushNotificationTemplateCode
+    ): void {
+        $pushNotificationTemplate = $this->pushNotificationTemplateRepository->findOneBy([
+            'code' => $pushNotificationTemplateCode,
+        ]);
+
+        $this->channelContext->setChannelCode($channel->getCode());
+
+        $webPush = $this->webPushFactory->create($this->productParameterMapper, $product, $pushNotificationTemplate);
+
+        $this->webPushSender->sendToUser($webPush, $channel, $receiver);
+    }
+}
+```
+
+```php
+# Example of parameter mapper extends AbstractParameterMapper you can implement
+<?php
+
+declare(strict_types=1);
+
+namespace App\WebPush\ParameterMapper;
+
+use App\Entity\Product\Product;
+use SpearDevs\SyliusPushNotificationsPlugin\ParameterMapper\AbstractParameterMapper;
+use Sylius\Component\Resource\Model\ResourceInterface;
+use Webmozart\Assert\Assert;
+
+final class ProductParameterMapper extends AbstractParameterMapper
+{
+    public function mapParameters(ResourceInterface $product, string $text): string
+    {
+        Assert::isInstanceOf(
+            $product,
+            Product::class,
+            'Mapper can be used with an entity: App\Entity\Product\Product',
+        );
+
+        /** @var Product $product */
+        $productData = $this->getProductData($product);
+
+        //{product_name} can be used in push notification template in title or in content
+        //You can add more variables example product brand or model name
+        $change = [
+            '{product_name}' => $productData['product_name'],
+        ];
+
+        return strtr($text, $change);
+    }
+
+    private function getProductData(Product $product): array
+    {
+        return [
+            'product_name' => $product->getName(),
+        ];
+    }
+}
+```
+
+### State Machine callbacks:
+
+By default, the push notification engine has two actions configured when changing the order and the shipment state. If you want to send notifications during another activity or permanently opt out of such sending, below you will find an example of how to do it.
+
+```yaml
+winzou_state_machine:
+    sylius_order:
+        callbacks:
+            after:
+                sylius_send_web_push:
+                    on: [ 'create' ]
+                    do: [ '@SpearDevs\SyliusPushNotificationsPlugin\WebPushSender\WebPushSender', 'sendOrderWebPush' ]
+                    args: [ 'object', !php/const SpearDevs\SyliusPushNotificationsPlugin\WebPushSender\WebPushSender::PUSH_NEW_ORDER_CODE, 'object.getChannel()' ]
+                    priority: 100
+```
+
+```yaml
+winzou_state_machine:
+    sylius_shipment:
+        callbacks:
+            after:
+                sylius_send_web_push:
+                    on: [ 'ship' ]
+                    do: [ '@SpearDevs\SyliusPushNotificationsPlugin\WebPushSender\WebPushSender', 'sendOrderWebPush' ]
+                    args: ['object.getOrder()', !php/const SpearDevs\SyliusPushNotificationsPlugin\WebPushSender\WebPushSender::PUSH_ORDER_SHIPPED_CODE, 'object.getOrder().getChannel()' ]
+                    priority: 100
+```
+
+Example of turning callback off:
+```yaml
+winzou_state_machine:
+    sylius_order:
+        callbacks:
+            after:
+                sylius_send_web_push:
+                    disabled: true
+```