Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/piscibus/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.
https://github.com/piscibus/notifly
aggregation laravel notifications
Last synced: 3 months ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/piscibus/notifly
- Owner: piscibus
- License: mit
- Archived: true
- Created: 2020-07-21T19:26:59.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2020-07-28T15:52:23.000Z (over 4 years ago)
- Last Synced: 2024-06-01T11:31:47.558Z (8 months ago)
- Topics: aggregation, laravel, notifications
- Language: PHP
- Homepage:
- Size: 140 KB
- Stars: 11
- Watchers: 2
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-egypt-opensource - piscibus/notifly - Notifly is a Laravel Package, that replaces Laravel's database notifications to allow aggregating notification actors like Facebook. -- (John, Jane Doe, and 8 others reacted to your photo.) (Projects / Web and Publishing)
README
# Notifly
[](https://packagist.org/packages/piscibus/notifly)
[](https://github.com/piscibus/notifly/actions?query=workflow%3ATests+branch%3Amaster)
[](https://packagist.org/packages/piscibus/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:
```bash
composer require piscibus/notifly
```
You can publish and run the migrations with:
```bash
php artisan vendor:publish --provider="Piscibus\Notifly\NotiflyServiceProvider" --tag="migrations"
php artisan migrate
```
You can publish the config file with:
```bash
php artisan vendor:publish --provider="Piscibus\Notifly\NotiflyServiceProvider" --tag="config"
```
This is the contents of the published config file:
```php
return [
'max_actors_count' => 2,
'icons' => [
// 'verb' => VerbIcon::class
],
];
```
## 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.
```php
notify(new CommentNotification($actor, $object, $target));
```
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.
```php
0,
'height' => 0,
'uri' => null,
];
}
}
```
```php
//configs/notifly.php
return [
// ..
'icons' => [
'comment' => CommentNotificationIcon::class,
]
//
];
```
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.
```php
$user = App\User::find(1);
foreach ($user->notifications as $notification){
echo $notification->verb;
}
```
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.
```php
$user = App\User::find(1);
$bellCount = $user->unseenNotifications()->count();
foreach ($user->unseenNotifications as $notification){
echo $notification->verb;
}
```
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.
```php
$user = App\User::find(1);
foreach ($user->unreadNotifications as $notification) {
echo $notification->type;
}
```
## 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:
```php
$user = App\User::find(1);
foreach($user->unseenNotifications as $notificaion) {
$notification->markAsSeen();
}
```
However, instead of looping throug each notification, you may use the `markAsSeen` method directoy on a collection of notifications.
```php
$user->unseenNotifications->markAsSeen();
```
You may also use a mass-update query to mark all the notifications as seen without retrieving them from the database:
```php
$user = App\User::find(1);
$user->unseenNotifications()->update(['seen_at' => now()]);
```
You may `delete` the notifications to remove them from the table entirley:
```php
$user->notifications()->delete();
```
## 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_notification`table:
```php
$user = App\User::find(1);
foreach($user->notifications as $notification) {
$readNotification = $notification->markAsRead();
}
```
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.
```php
$user = App\User::find(1);
foreach($user->readNotifications as $notification) {
$notification->markAsUnRead();
}
```
## 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:
```php
Route::get('/notifications', function(){
$user = App\User::find(1);
$notifications = $user->jsonableNotifications;
return JsonNotifications::collection($notifications);
})
```
A notification JSON appears as follows:
```Javascript
{
"id": "9122a3cb-b4e3-352a-a1ab-087e259403af",
"verb": "comment",
"time": "2020-07-26T16:07:10.000000Z",
"object" : {
"id" : 7,
//...
},
"target": {
"id": 9
},
"actors": {
"data": [
{
"id": 1990,
//...
},
{
"id": 1995,
//...
}
],
"trimmed": 8
},
"icon": {
"width": 500,
"height": 500,
"uri": "https://example.com/path/to/image.jpg"
}
}
```
## Customizing The Notification Entities JSON
To customize a notification JSON, create an [Eloquent API Resource](https://laravel.com/docs/eloquent-resources), 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`
```php
[]`
- **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 `
- **Arguments**:
* `name`*: (required) The name of the notification icon class.