Package Data | |
---|---|
Maintainer Username: | michaeljennings |
Maintainer Contact: | michael.jennings91@gmail.com (Michael Jennings) |
Package Create Date: | 2015-12-23 |
Package Last Update: | 2018-07-23 |
Home Page: | |
Language: | PHP |
License: | MIT |
Last Refreshed: | 2024-12-22 03:16:29 |
Package Statistics | |
---|---|
Total Downloads: | 1,429 |
Monthly Downloads: | 0 |
Daily Downloads: | 0 |
Total Stars: | 11 |
Total Watchers: | 1 |
Total Forks: | 2 |
Total Open Issues: | 0 |
Note: This package is no longer maintaned for Laravel 5.3+ since Laravel now offers built in notifications.
A basic notification feed for laravel 5+.
Below is some example code of all of the basic methods for the package.
$user = User::find(1);
$team = Team::find(1);
// Push notification to a user
$feed->push('This is a new notification', $user);
// Push notification to a user, and a team of users
$feed->push('This is a new notification', [$user, $team]);
// Push notification to a user with multiple parameters
$feed->push([
'icon' => 'icon-alert',
'title' => 'Something Broke!',
'body' => 'Something super important broke'
], $user);
// Get all of the notifications for a user
$notifications = $feed->pull($user);
// Get 10 notifications for the user
$notifications = $feed->limit(10)->pull($user);
// Mark a notification as read
$feed->markAsRead($notification);
This package requires at least laravel 5.
To install through composer include the package in your composer.json
.
"michaeljennings/feed": "0.2.*"
Run composer install
or composer update
to download the dependencies, or you can run composer require michaeljennings/feed
.
Once installed add the service provider to the providers array in config/app.php
.
'providers' => [
Michaeljennings\Feed\FeedServiceProvider::class
];
To publish the migrations and config files run php artisan vendor:publish
.
The package comes with a default migration to create the database structure for the package. By default this table allows for the notifications to have a body, and an icon. If need more data for your notification such as a title, we recommend adding the columns to the default migration.
The package comes with feed.php
config file. This allows you to customise the database driver you are using with the package. At present only eloquent is supported, but we are working on a laravel db driver currently.
From time to time you may need to add additional methods or properties to the notification model, for example you might want to add an additional relationship to the notification model.
This can be done very simply by changing the notification model in the config file as shown below.
'drivers' => [
'eloquent' => [
'model' => 'Path\To\Notification', // Update this to your notification model.
],
]
The default notification model implements a couple of interfaces that are required by this package. If you need to make changes to the model I recommend extending the default model, otherwise make sure you implement the interfaces.
// Example of extending the model
class Notification extends \Michaeljennings\Feed\Store\Eloquent\Notification
{
public function foo()
{
//
}
}
// Example of just implementing the interfaces
class Notification implements \Michaeljennings\Feed\Contracts\Notification, \Michaeljennings\Feed\Contracts\Store
{
public function bar()
{
//
}
}
You may require another driver, i.e. you're using a data store not supported by laravel. If this is the case you can add a driver to the system verify simply as shown below.
// Here we grab the driver manager and then extend it to a new 'foo' driver.
// Ideally this would be done within a service provider.
app('feed.manager')->extend('foo', function($app) {
return new Foo();
});
// The Foo driver needs to implement the Store interface so it has all of
// the necessary methods.
class Foo implements Michaeljennings\Feed\Contracts\Store
{
//
}
// The in the config file set the driver to our new foo driver.
return [
'driver' => 'foo'
]
For more information on adding drivers look at the laravel documentation on extending the framework.
Once installed you can access the feed in multiple ways.
Firstly you can dependency inject it from the IOC container by either the push or pull feed interfaces. Both interfaces will return the same instance, it's just to make your code more readable.
public function __construct(
Michaeljennings\Feed\Contracts\PullFeed $pullFeed,
Michaeljennings\Feed\Contracts\PushFeed $pushFeed
) {
$this->pullFeed = $pullFeed;
$this->pushFeed = $pushFeed;
}
Or you there is a feed
helper method.
$feed = feed();
Or if you want to use the facade you can register it in the aliases array in config/app.php
.
'aliases' => [
'Feed' => Michaeljennings\Feed\Facades\Feed::class
]
To set up a notifiable model you just need to implement the notifiable interface, and then use the notifiable trait in your model.
This will set up the required relationships.
use Michaeljennings\Feed\Contracts\Notifiable as NotifiableContract;
use Michaeljennings\Feed\Notifications\Notifiable;
class User extends Model implements NotifiableContract
{
use Notifiable;
}
It is also possible to set up groups of notifiable models, an example of when this would be useful is having a team of users. This will allow us to push a notification to all the members of that group.
To set up a notifiable group you need implement the notifiable group interface on the group model. This will add a method called getGroup
which requires you to return the members you would like to be notified.
In the example below we have a team model which implements the group interface. It has a users
relationship which returns all of the users belonging to the team. Then in the getGroup
method we simply return the users.
use Michaeljennings\Feed\Contracts\NotifiableGroup;
class Team extends Model implements NotifiableGroup
{
public function users()
{
return $this->hasMany('App\User');
}
public function getGroup()
{
return $this->users;
}
}
Below is a list of all of the currently available notification methods. If you think of anything you want to add please feel free to create an issue, or a pull request.
The push method allows you to push a notification to a notifiable model, multiple notifiable models, or a notifiable group.
When pushing to a notifiable group each member of the group will get their own notification, it will not share one notification for all of the members.
$feed->push('My awesome notification', $user);
$feed->push('My awesome notification', [$user, $team]);
$feed->push([
'title' => 'New Notification',
'body' => 'My awesome notification'
], $user);
When the notification is pushed a NotificationAdded
event will be fired.
You can then listen for this and then broadcast the notification, send an email etc.
You just need to register the listeners in the event service provider.
protected $listen = [
'Michaeljennings\Feed\Events\NotificationAdded' => [
'App\Listeners\BroadcastNotification',
'App\Listeners\EmailNotification',
],
];
The pull method gets all of the unread notifications for the notifiable models you pass it.
$feed->pull($user);
To get all of the read notifications for a member, use the pullRead
method.
$feed->pullRead($user);
To limit the amount of notifications returned when pulling, chain the limit
method.
$feed->limit(10)->pull($user);
$feed->limit(10)->pullRead($user);
To offset the results when pulling, chain the offset
method. This can be useful for infinte scrollers.
$feed->offset(10)->pull($user);
$feed->offset(10)->pullRead($user);
If you want to paginate the results and let laravel handle the limiting and offsetting for you, chain the paginate
method.
$feed->paginate(10)->pull($user);
$feed->paginate(10)->pullRead($user);
From time to time you may wish to run additional queries on the notification results, to do this chain the filter method.
The filter method requires a closure which is passed an instance of the query builder. In the example below we're only getting results that have an alert icon.
$feed->filter(function($query) {
$query->where('icon', 'icon-alert');
})->pull($user);
$feed->filter(function($query) {
$query->where('icon', 'icon-alert');
})->pullRead($user);
To order the results by the latest notification added, chain the latest
method. By default the notifications are ordered by the latest notification added.
$feed->latest()->pull($user);
$feed->latest()->pullRead($user);
To order the results by the oldest notification added, chain the oldest
method. By default the notifications are ordered by the latest notification added.
$feed->oldest()->pull($user);
$feed->oldest()->pullRead($user);
All of these methods can be chained together, this should allow you to get the notifications in any way you require.
// Limit and offset the results
$feed->limit(10)->offset(10)->pull($user);
// Get all of the oldest read notifications, that have an alert icon.
$feed->filter(function($query) {
$query->where('icon', 'icon-alert');
})->oldest()->pullRead($user);
To mark a notification as read you can either use the markAsRead
method, or it is aliased to read
if you prefer.
$feed->markAsRead($notification);
$feed->read($notification);
When the notification is read marked as read a NotificationRead
event will be fired.
You can then listen for this and then broadcast it etc.
protected $listen = [
'Michaeljennings\Feed\Events\NotificationRead' => [
'App\Listeners\BroadcastReadNotification',
],
];
To mark a notification as unread you can either use the markAsUnread
method, or it is aliased to unread
if you prefer.
$feed->markAsUnread($notification);
$feed->unread($notification);
When the notification is read marked as unread a NotificationUnread
event will be fired.
You can then listen for this and then broadcast it etc.
protected $listen = [
'Michaeljennings\Feed\Events\NotificationUnread' => [
'App\Listeners\BroadcastUnreadNotification',
],
];