add method to make sending notifications easy

Author: damms005

README.md

@@ -81,6 +81,12 @@ Now run this command in your terminal to publish this package resources:
 php artisan vendor:publish --provider="Nahid\Talk\TalkServiceProvider"
 ```
 
+Note that you can publish only the migrations with the command below:
+
+```
+php artisan vendor:publish --provider="Nahid\Talk\TalkServiceProvider" --tag=migrations
+```
+
 After running this command, all necessary file will be included in your project. This package has two default migrations. So you have to run migrate command like this. (But make sure your database configuration is configured correctly.)
 
 ```shell
@@ -157,6 +163,7 @@ Please see the API Doc.
 - [isAuthenticUser](https://github.com/nahid/talk#isauthenticuser)
 - [sendMessage](https://github.com/nahid/talk#sendmessage)
 - [sendMessageByUserId](https://github.com/nahid/talk#sendmessagebyuserid)
+- [sendNotificationToUser](https://github.com/nahid/talk#sendnotificationtouser)
 - [getInbox](https://github.com/nahid/talk#getinbox)
 - [getInboxAll](https://github.com/nahid/talk#getinboxAll)
 - [threads](https://github.com/nahid/talk#threads)
@@ -285,6 +292,17 @@ You can send message via receiver id by using this method. If the message is suc
 object|false sendMessageByUserId($receiverId, $message)
 ```
 
+### sendNotificationToUser
+
+This allows you to quickly send notification to a user. Notifications usually will not have a sender (user), because the idea is that notifications are system messages (actions completed, alerts, etc.). However, Talk still allows you to specifier a sender if you must.
+
+**Syntax**
+
+```php
+object|false sendNotificationToUser($receiverId, $message, $title = null, $customNotificationTag = null, \$optionalSenderId = null)
+
+```
+
 ### getInbox
 
 If you want to get all the inboxes except soft deleted message , this method may help you. This method gets all the inboxes via previously assigned authenticated user id. It returns collections of message threads with latest messages in each of the returned threads. Specifically, it retrieves all message threads (i.e. conversations) for the authenticated user without soft deleted message, including latest messages, sender and receiver user model. This method differs from the `getInboxAll()` method in that each conversation returned contains a lot more data (each conversation contains the conversation model itself, the messages in the conversation, a collection of only unread messages in the conversation, the corresponding user, etc.)

database/migrations/2020_03_29_014907_make_user1_nullable_in_conversations_table.php

@@ -0,0 +1,32 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+class CreateConversationsTable extends Migration
+{
+	/**
+	 * Run the migrations.
+	 *
+	 * @return void
+	 */
+	public function up()
+	{
+		Schema::table('conversations', function (Blueprint $table) {
+			$table->integer('user_one')->nullable();
+		});
+	}
+
+	/**
+	 * Reverse the migrations.
+	 *
+	 * @return void
+	 */
+	public function down()
+	{
+		Schema::table('conversations', function (Blueprint $table) {
+			$table->integer('user_one');
+		});
+	}
+}

src/Talk.php

@@ -32,6 +32,13 @@ class Talk
 	 */
 	const STAR_TAG = "talk_special_tag_star";
 
+	/**
+	 * Just like STAR_TAG, this constant is also courtesy of the tag feature of Talk.
+	 *
+	 * @var string
+	 */
+	const NOTIFICATION_TAG = "talk_special_tag_notification";
+
 	/**
 	 * configurations instance.
 	 *
@@ -88,19 +95,20 @@ public function __construct(Repository $config, Broadcast $broadcast, Conversati
 
 	/**
 	 * make two users as serialize with ascending order.
+	 * It returns an array whose elements are $user1 and $user2
 	 *
 	 * @param int $user1
 	 * @param int $user2
 	 *
 	 * @return array
 	 */
-	protected function getSerializeUser($user1, $user2)
+	protected function getSerializeUser($user1_id, $user2_id)
 	{
-		$user        = [];
-		$user['one'] = ($user1 < $user2) ? $user1 : $user2;
-		$user['two'] = ($user1 < $user2) ? $user2 : $user1;
+		$users       = [];
+		$user['one'] = ($user1_id < $user2_id) ? $user1_id : $user2_id;
+		$user['two'] = ($user1_id < $user2_id) ? $user2_id : $user1_id;
 
-		return $user;
+		return $users;
 	}
 
 	/**
@@ -172,12 +180,12 @@ protected function makeMessageCollection($conversations)
 	protected function newConversation($receiverId, $title, $tagName = null)
 	{
 		// $conversationId = $this->isConversationExists($receiverId);
-		$user = $this->getSerializeUser($this->authUserId, $receiverId);
+		$users = $this->getSerializeUser($this->authUserId, $receiverId);
 
 		// if ($conversationId === false) {
 		$conversation = $this->conversation->create([
-			'user_one' => $user['one'],
-			'user_two' => $user['two'],
+			'user_one' => $users['one'],
+			'user_two' => $users['two'],
 			'title'    => $title,
 			'status'   => 1,
 		]);
@@ -293,7 +301,7 @@ public function sendMessage($conversationId, $message)
 	 *
 	 * @return \Nahid\Talk\Messages\Message
 	 */
-	public function sendMessageByUserId($receiverId, $message, $title = null, $tag = null)
+	public function sendMessageByUserId($receiverId, $message, $title = null, $tagName = null)
 	{
 		if ($conversationId = $this->isConversationExists($receiverId)) {
 			$con = \Nahid\Talk\Conversations\Conversation::find($conversationId);
@@ -303,12 +311,34 @@ public function sendMessageByUserId($receiverId, $message, $title = null, $tag =
 			}
 		}
 
-		$conversationId = $this->newConversation($receiverId, $title, $tag);
+		$conversationId = $this->newConversation($receiverId, $title, $tagName);
 		$message        = $this->makeMessage($conversationId, $message);
 
 		return $message;
 	}
 
+	/**
+	 * Undocumented function
+	 *
+	 * @param int $receiverId
+	 * @param string $message
+	 * @param string $title
+	 * @param string $customNotificationTagName
+	 * @param int $optionalSenderId
+	 *
+	 * @return \Nahid\Talk\Messages\Message
+	 */
+	public function sendNotificationToUser($receiverId, $message, $title = null, $customNotificationTagName = null, $optionalSenderId = null)
+	{
+		//when sending notifications, there is no user_one, because
+		//notifications should ideally be sent by the "system"
+		$this->authUserId = $optionalSenderId;
+
+		$customNotificationTagName = empty($customNotificationTagName) ? self::NOTIFICATION_TAG : $customNotificationTagName;
+
+		return $this->sendMessageByUserId($receiverId, $message, $title, $customNotificationTagName);
+	}
+
 	/**
 	 * fetch all inbox (i.e. conversations) for currently loggedin user with pagination.
 	 *
@@ -515,7 +545,7 @@ public function createTagForUser($tagName)
 	}
 
 	/**
-	 * adds a tag to a conversation. Creates the tag if it does not exist for the user
+	 * adds a tag to an existing conversation. Creates the tag if it does not exist for the user
 	 * This allows for several users to maintain same tag name conveniently without any conflicts/issues
 	 *
 	 * @param int $conversationId
@@ -734,8 +764,8 @@ public function getUnreadMessagesInConversation($conversationId)
 	 * gets all messages not yet read in all conversations altogether
 	 *
 	 *
-	 * @param int $removeSpecialMessages : allows to use Talk also to send system notifications
-	 * to users by allowing some conversations to be tagged as "special".
+	 * @param int $removeSpecialMessages When true will remove conversations that have special tags.
+	 * Special tags is one of those features of Talk that makes it easy to mimic sending of system notifications
 	 * As a rule of thumb, any conversation that is not "normal" message/conversation should simply be tagged as special, so
 	 * that it is easy to get unread messages without confusing message contexts
 	 *