🔔 Notific

Notific is a simple, and minimal, static notification system for Laravel. It stores notification data based on user_id, and fetch notifications for the user_id. It's not that feature rich.

The package has no UI, it just a database based cached data-driven mechanism of organized methods. You have to build you own UI.

License: GPL-2.0+
Requires: Laravel 5.8
Tested up to: Laravel 8.x
Developers: Mayeenul Islam, Nazmul Hasan

Table of Contents

• Features
• Installation
  • Step 1: Download & Setup
    • Providers array
    • Aliases array
  • Step 2: Publish the Necessary files
  • Step 3: Make tables ready
• Configuration
  • Cache status
  • Cache time
• API: How to use
  • Store notification
  • Get notifications
  • Get notification count
  • Mark notification as read
• Examples
  • 01. Create a notification
  • 02. Get notifications
  • 03. Get notification count
  • 04. Mark notification as read
  • 05. Maybe Unserialize
• Contributions
• Uninstallation
• Credits

Features

• Database table creation using migration
• Store notifications into the database
• Fetch notifications from the database
• Store and fetch any types of additional information for notification with metadata
• Cached data to save some valuable resources - configurable

Features that are not present:

• Event listener and real-time notification (but you can easily extend into those)

Installation

Step 1: Download & Setup

Open up the command console on the root of your app and run:

composer require technovistalimited/notific

Providers array

Add the following string to the config/app.php under providers array:

Technovistalimited\Notific\NotificServiceProvider::class,

Aliases array

Add the following line to the config/app.php under aliases array:

'Notific' => Technovistalimited\Notific\Facades\Notific::class,

Step 2: Publish the Necessary files

Make the configuration and migration files ready first; in the command console, type and hit enter:

php artisan vendor:publish --tag=notific

Step 3: Make tables ready

Open up the command console on the root of your app and run the migrations:

php artisan migrate

Configuration

Change configuration in config/notific.php.

Cache status

Set whether to use the cache or not, under 'cache' => ['is_cache']. Accepted value: true (enabled), false (disabled)
Default: true - enabled

Cache time

Change the time under 'cache' => ['cache_time']. Accepted value: any positive integer to denote seconds.
Default: 10 minutes

API: How to use

If you defined the helper class correctly, the package is easy to use:

Store notification

To store notification, simply place the following method where you want to plug it into. The method will also clear the cache for the user to update the notification history.

Notific::notify( $userId, $message, $notificationType, $metaData, $createdBy );

$userID : integer/array
User ID or array of user IDs to notify.

$message : string
The message with which you want to notify with.

$notificationType : string : (optional)
The notification type if you have any, other than notification.
default: 'notification'

$metaData : integer/string/array : (optional)
Whatever additional information you want to pass with. Whether pass them as integer, string or as an array.
default: empty

$createdBy : integer : (optional)
If you want to keep trace who issued the notification.
default: empty

Get notifications

Get the notifications by user ID.

Notific::getNotifications( $userId, $arguments );

$userID : integer
User ID for which to fetch the notifications.

$arguments : array : (optional)
Array of Query parameters. default: array() - fetch notifications based on default settings

$read_status : string
The notification read status. Accepts: 'all', 'read', 'unread'.
default: 'all'

$order : string
Designates ascending or descending order of notifications. Accepts 'ASC', 'DESC'.
default: 'DESC'

$orderby : string
Sort retrieved posts by parameter. Single option can be passed. Accepts any valid column name from db table.
default: 'created_at'

$paginate : boolean
Whether to enable pagination or not.
default: false - pagination DEactivated

$items_per_page : integer
Fetch the number of items. Accepts any positive integer.
default: -1 - fetch everything

Get notification count

Get the total count of notifications by user ID.

Notific::getNotificationCount( $userId, $status );

$userID : integer
User ID for which to fetch the notifications.

$status : string : (optional)
The notification read status. Accepts: 'all', 'read', 'unread'.
default: all - fetch all the notification count

Mark notification as read

Mark the notification as read when actually they are. You might need AJAX to mark them read on the fly.

Notific::markNotificationRead( $userId, $notificationId );

$userID : integer
User ID to mark the notification as read for.

$notificationId : integer : (optional)
If you want to mark each of the notification as read, pass the notification ID
default: empty - mark all as read

Examples

01. Create a notification

With the following examples, a user with the ID 21 will be notified accordingly:

// Notified with a simple message.
Notific::notify( 21, 'Your application submitted.' ) );

// Notified with a message and date.
Notific::notify( 21, sprintf( 'Your application submitted on %s is approved.', date('d F Y') ) );

// Notified with a different type of notification.
Notific::notify( 21, 'Your application submitted.', 'message' ) );

// Notified with some meta data incorporated.
Notific::notify( 21, 'Your application is approved. Click to see it.', 'notification', array('link' => 'http://link.to/the/application/' ) ) );

// Notified with someone who (with ID 8) assigned the notification
Notific::notify( 21, 'Your application submitted.', 'notification', '', 8 ) );

// Notify multiple users (with ID 21, 4, and 5) at a time
Notific::notify( [21, 4, 5], 'An application is submitted. Please check.' );

02. Get notifications

With the following examples, we're fetching the notifications assigned to a user with ID 21:

// Get all the notifications.
Notific::getNotifications( 21 );

// Get unread notifications only.
Notific::getNotifications( 21, array( 'read_status' => 'unread' ) );

// Get read notifications only.
Notific::getNotifications( 21, array( 'read_status' => 'read' ) );

// Get read notifications and maximum 10 of them only.
Notific::getNotifications( 21, array( 'read_status' => 'all', 'items_per_page' => 10 ) );

// Get all notifications and paginate them to 50 per page only.
Notific::getNotifications( 21, array( 'paginate' => true, 'items_per_page' => 50 ) );

03. Get notification count

With the following examples, we're fetching the count of notifications assigned to a user with ID 21:

// Get all notifications of the user ID 21.
Notific::getNotificationCount( 21 );
Notific::getNotificationCount( 21, 'all' );

// Get only the 'unread' notifications of the user ID 21.
Notific::getNotificationCount( 21, 'unread' );

// Get only the 'read' notifications of the user ID 21.
Notific::getNotificationCount( 21, 'read' );

04. Mark notification as read

// Mark all the notifications as 'read' for the user with ID 21.
Notific::markNotificationRead( 21 );

// Mark notification number 56 as 'read' for the user with ID 21.
Notific::markNotificationRead( 21, 56 );

05. Maybe Unserialize

Adopted from WordPress, this function can detect whether to unserialize a string or not and serialize, if it's a serialized data. If you make custom methods, you might need to convert the serialized meta data back into array - this method will help you then.

// Unserialize if serialized.
Notific::maybeUnserialize( $string );

Contributions

Any bug report is welcome. We might not support the package as you might require. But we will definitely try to fix the bugs as long as they meet our leisure.

If you want to contribute code, feel free to add Pull Request.

Uninstallation

• Search the whole project of any declaration of Notific::, and remove the functions from the source, or comment them out. Otherwise, they will generate a fatal error after uninstallation.
• Open config/app.php and remove the line ...NotificServiceProvider::class under providers and aliases array.
• Remove the configuration file notific.php in config/notific.php
• Remove the notific migration files from database/migrations/
• Delete the two database tables manually (as the package is not released): table:notifications, and table:user_notifications

Now, open up the command console, and type:

composer remove technovistalimited/notific

You are done!

Credits

All the credit goes to the almighty God first. Thanks to Mr. Amiya Kishore Saha who let both of us make our first Laravel package. Thanks to Mr. Kamrul Hasan for reviewing the progress and suggesting his ideas. And thanks to TechnoVista Limited for supporting the initiative. Thanks to Notifynder - a Laravel notification package available at Packagist from Fabrizio - we followed them to learn. Thanks to WordPress - a GPL licensed web framework - we took some of their code thankfully.