Potential Laravel Package: Notifications README.md

Notifications

ATTN!

This is a rough draft of a potential README for a Laravel package called (something along the lines of) Notifications. Nothing is set in stone and these are rough concepts and ideas to be expanded upon and discussed in Reddit threads.

Notifications is a system that allows you to collect and display a set of notifications for a user.

The core concept is to handle, organize and store notifications for a user and show them the ones they have configured to see.

Notifications steps out of the way of the developer and allows a high amount of configuration so that it fits in with any site, any dashboard.

Creating A Notification

class User extends Model {
  use Notifications;
}

// Now you can do:

$user = User::find(1);

$user->createNotification(
    'Some title',
    'Short Description',
    'link'                  // Type: configurable, link is an example. You can put whatever here. See below with migrations.
    [
      'url' => 'http://google.ca',          // Optional
      // See below for more information ...
      'expiration_unread' => Carbon::now(), // Optional
      'expiration_read' => Carbon::now(),   // Optional
      'soft_expiration_delete' => true      // Optional
    ]
);

The above will create a notification of type link that when clicked on will take them a URL. the user will see a notification symbol (assuming that’s how you design it) and when clicking to see the notification will see a short description and a title.

This system is similar to that of Laravels notification system where you can broad cast notifications over the site, the difference is in simplicity.

We have fewer methods that allow you to do more with less:

$user->getAllNotifications([
  'max' => 50 // Optional Param, gets back maximum of 50 notifications.
]);

// You can use none or all and we will build the query for you.
$user->getNotifications([
  'type' => 'link',     // Returns all of type link.
  'status' => 'unread'  // Accepts: unread, read, dismissed
]);

// Single notification. You can use one or all the query options shown below.
$user->getNotification([
  'id' => 1,            // Returns the matching notification for this user under this id.
  'title' => 'title',   // Returns any notification matching this title (titles are unique)
]);

Migrations

We do have a couple migrations, one changes the user table to add a notification_max column so that your users can have pre-defined maximum notifications. For example, if you only want to allow a user to have 50 notifications then you would have to write an update migration to add 50 as the value. By default, we set this as optional and thus allow you to have as many notifications as you want.

The second migration adds a notification table; this contains the following fields:

• type (string & unique)
• id (int auto incrementing)
• short_description (string)
• dismissed (boolean & default false)
• unread (boolean & default false)
• user_id (integer)
• expiration_unread (Date & optional)
• expiration_read (Date & optional)
• softDeletes (See me on soft deletes)
• soft_expiration_delete (boolean & default false)

This is a Many to one relationship. A user may have many notifications but a notification has one user (belongs to).

ATTN!!

We make the assumption that you use the default user database table, if you do not you will need to write your own migration and take into account that the user table will need a column called notification_max.

Expiration

When a notification is unread, you might give it 3 months, this applies to unread dismissed notifications. However, if a notification is marked as read you might delete it in 24 hours. Hence the two different types. Both of which are optional.

If you use either one, you have an additional field called soft_expiration_delete which means do we use the soft delete method or do we do the hard delete method on this notification when its expiration date is matched?

// Works on dismissed and read.
$user->getNotifications(['status' => 'unread'])->get_expiration_date();

// Over rides whatever the current expiration is to whatever you set it as.
// Note: Dismissed notifications are considered unread notifications that were just dismissed.
$user->getNotifications(['status' => 'dismissed'])->set_expiration(Carbon::now());

// Accepts soft or hard.
$user->getNotifications(['status' => 'read'])->set_delete('soft');

ATTN!!

The above methods also work on getNotification

Difference Between Dismissed and Deleted

There is a bit of terminology here, one is the concept of a dismissed notification and the other is concept of a deleted notification. The core difference here is that dismissed notifications are unread notifications that do not show up in the list of notifications when you just do: $user->getNotifications(). You would need to pass in dismissed with a value of true.

Deleted notifications are simply that. It doesn't matter if they were dismissed, read or unread - they were deleted.

When you manage a user’s notifications you can use soft delete or force delete, we then use Laravels soft deletion concept

For example:

$user->getNotification(['id' => 6])->delete();      // Soft delete.
$user->getNotification(['id' => 6])->reinstate();   // Re-instates a notifications that was soft deleted.
$user->getNotification(['id' => 6])->forceDelete(); // Actual delete.

// Dismissing a notification

$user->getNotification(['id' => 6])->dismiss(); // dismisses a notification.
$user->getNotification(['id' => 6])->recall();  // recalls a dismissed notification.

ATTN!!

It doesn't make sense to dismiss a read notification, to me you would delete it. So you can only Dismiss unread notifications.

Difference Between Read and Unread Notifications

Unread is exactly that. Unread. It shows up. It has some kind of notification symbol or color and when clicked on it becomes read.

Read is the same concept. its Read, there’s nothing more to do then delete it. The difference here is in functionality.

Read notifications can have an expiration date on them as can unread (or dismissed) notifications.

You can also set a notification that’s read to unread:

$user->getNotification(['status' => 'read'])->unread();

// The same works on getNotifications()

Real Time Notifications

The idea here would be to then hook into Laravels notification system. How ever this has to be figured out.

This idea would then play into the core concept that if the app had a notification then we could use Laravels notification system to send SMS and email. Thus I don't have to implement those features.

This would be done via a concept called bridges. Where we bridge a notifications from our system to that of Laravels.

More thought needed on this.