Download the PHP package piscibus/notifly without Composer

Notifly

Notifly allows aggregating notification actors like Facebook, Twitter, Instagram and etc -- (John Doe, Jane Doe and 8 others reacted to your photo.) A notification consists of an actor, a verb, an object and a target. It tells the story of a person performing an action on or with an object.

Installation

You can install the package via composer:

You can publish and run the migrations with:

You can publish the config file with:

This is the contents of the published config file:

Creating Notifications

In Notifly, the same as In Laravel, each notification is represented by a single class (typically stored in the app/Notifications directory). you can create a notification class by running the notifly:make:notification Artisan command.

php artisan notifly:make:notification CommentNotification

This command will place a fresh notification class in your app/Notifications directory. Each notification class contains a via method which returns an array of supported channels. It returns NotiflyChannel by default, you can append any required channels. The NotiflyChannel replaces Laravel's database channel, but any other message building channels such as toMail are supported the same as expected in a normal notification class.

Sending Notifications

The Notified user model must implement the TransformableInterface, don't worry about the required methods, they are implemented in the Notifiable from Piscibus not Laravel. Let's explore a User model example.

This trait contains a notify method which expects to receive a notification instance.

In the previous example, the $actor is the user who commented on the $user's post. The $object is the comment itself. Finally, the $target is the post the $actor commented on.

All those required entities ($actor, $object and $target) must implement the TransformableInterface, and again don't worry about the required methods, they are implemented in Notifly Trait.

Since the User model, may represent an actor and a notifiable in the same time, the required methods are provided by a Notifibale trait.

tl;dr

• All models used in notifications should implement \Piscibus\Notifly\Contracts\TransformableInterface
• The Notified model -- (User) uses the \Piscibus\Notifly\Traits\Notifiable trait.

• Any other models -- (Comment, Post) uses \Piscibus\Notifly\Traits\Notifly trait.

  Formatting Notifications

  The notification class contains an attribute $verb, replace its value with a descriptive word. Let's Explore a CommentNotification class.

A Notification usually has an icon, the icon is represented by an array in the JSON response. To customize a notification icon, you need to create an icon class, and register this icon class in the configuration file configs/notifly.php. To generate an icon class run the notifly:make:icon Artisan command.

php artisan notifly:make:icon CommentNotificationIcon

This command will place a fresh Icon class in the app/Icons directory.

Within the toArray method you can access all entities of the notification.

• $this->actors a collection of the notification actors.
• $this->object the notification object.
• $this->target the notification target.

Use them to customize the notification icon.

Accessing The Notifications

Once notifications are stored in the database, you need a convenient way to access them from your notifiable entities . The \Piscibus\Notifly\Traits\Notifiable includes a notifications Eloquent relationship that returns the "un-read" notifications for the entity. To fetch notifications, you may access this method like any other Eloquent relationships. By default, notifications will be sorted by the updated_at timestamp.

If you want to retrieve the "un-seen" notifications, you may use the unseenNotifications relationship. Again, these notifications will be sorted by the updated_at timestamp.

If you want to retrieve the "read" notifications, you may use the "readNotifications" relationship. Again, these notifications will be sorted by the updated_at timestamp.

Marking Notifications As Seen

Typically, you will want to mark a notification as "seen" when a user retrieves the notification list. The \Piscibus\Notifly\Traits\Notifiable provides a markAsSeen method, wich updates the seen_at column on the notification's database record:

However, instead of looping throug each notification, you may use the markAsSeen method directoy on a collection of notifications.

You may also use a mass-update query to mark all the notifications as seen without retrieving them from the database:

You may delete the notifications to remove them from the table entirley:

Marking Notifications As Read

Typically, you will want to mark a notification as "read" when a user views it. You may use the markAsRead method, which deletes this notification entry and creates a new entry in the read_notificationtable:

If you want to mark a read-notification as "unread", you may use markAsUnRead method, which reverses the previouls process of marking the notification as read.

Notifications JSON Response

Typically, you will want to provied a JSON response of a notifiable notifications. You may use the \Piscibus\Notifly\Resources\JsonNotifications JSON resource. To avoid "N+1" queriers, the \Piscibus\Notifly\Traits\Notifiable has a jsonableNotifications and jsonableReadNotifications relationships which eagrly load the required relations:

A notification JSON appears as follows:

Customizing The Notification Entities JSON

To customize a notification JSON, create an Eloquent API Resource, then override the getTransformer in the entity model class. In a John commented on your post case, the object is a Comment model, to customize its JSON:

php artisan make:resource Comment

For more information about Eloquent API Resource, check Laravel documentation.

Artisan Commands

Creating Notifications

notifly:make:notification

• Description: Create a new notification class.
• Usage: notifly:make:notification [options] [--] <name> [<verb>]
• Arguments:
  • name^*: (required) The name of the notification class.
  • verb: (Optional) The name of the notification verb.

• Options:

  • -i, --icon: Creates an icon class for the created notification class.

  Creating Icons

  notifly:make:icon

  • Description: Create a new notification icon class.
  • Usage: notifly:make:icon <name>
  • Arguments:
  • name^*: (required) The name of the notification icon class.