Issue with getSubjectModel in Notification

huseyinfiliz

Hi, i'm working on a custom notification blueprint for Flarum, and I've run into an issue with the getSubjectModel method.

In my use case, the subjectId is a simple integer representing a category or type, not an actual model (like User or Post). However, getSubjectModel seems to require a valid class name, and leaving it as an empty string ('') or using a placeholder value (like 'custom_subject') results in errors:

If I leave getSubjectModel as an empty string:

   public static function getSubjectModel(): string
   {
       return '';
   }

This causes the following error in the browser:

   Uncaught TypeError: Cannot read properties of null (reading 'type')

If I try to return a placeholder string (e.g., 'custom_subject'):

   public static function getSubjectModel(): string
   {
       return 'custom_subject';
   }

It results in:

   Error: Class "custom_subject" not found

What I Want to Achieve:

subjectId is just an integer and doesn't correspond to any database model.
I need to implement getSubjectModel in a way that works with Flarum's notification system without linking it to an actual model.

My Current Setup:

Controller: Passes subjectId (integer) to the CustomNotificationBlueprint.

Blueprint: Includes subjectId in the getData method:

   public function getData(): array
   {
       return [
            'type' => $this->notificationType,
            'message' => $this->message,
            'fromUserId' => $this->fromUser?->id,
            'subjectId' => $this->subjectId,
            'unique' => (string) Str::orderedUuid(),
       ];
   }

Question:
How can I implement getSubjectModel properly when my subjectId is not linked to any model? Is there a way to bypass the need for a model entirely in this context, or should I create a "dummy" model class just to satisfy this requirement?

Any advice or guidance would be greatly appreciated!

SychO

huseyinfiliz the model is required. The best solution is what is the closest model in your context/logic, usually at the very minimum you can use the recipient user as subject, I would recommend you do that here as well.

SychO

huseyinfiliz I need to implement getSubjectModel in a way that works with Flarum's notification system without linking it to an actual model.

why?

huseyinfiliz

SychO I initially avoided unnecessary database connections by not linking subjectId to any model. However, based on recommendations, I linked it to User::class.

Currently, the notification system works, and the API allows customization of:

Message: Notification content.
URL: A link associated with the notification.
Icon: A Font Awesome icon.
Avatar ID: The ID of the user avatar.
Target Users: The users who will receive the notification.

The Issue:
The problem lies in the following getSubject method, which I cannot customize via the API. Regardless of what I try (int, string, etc.), subjectId always ends up being null in the database:

public function getSubject(): string
{
    return (string) $this->subjectId;
}

CustomNotificationBlueprint.php
Here's the full class for reference:

<?php

namespace huseyinfiliz\notificationhub\Notification;

use Flarum\Notification\Blueprint\BlueprintInterface;
use Flarum\User\User;
use Illuminate\Support\Str;

class CustomNotificationBlueprint implements BlueprintInterface
{
    protected string $message;
    protected ?User $fromUser;
    protected string $notificationType;
    protected string $subjectId;
    protected string $url;
    protected string $icon;

    public function __construct(
        string $message, 
        ?User $fromUser = null, 
        string $notificationType = 'default', 
        string $subjectId = '1', 
        string $url = '#',
        string $icon = 'fas fa-bell'
    ) {
        $this->message = $message;
        $this->fromUser = $fromUser;
        $this->notificationType = $notificationType;
        $this->subjectId = $subjectId;
        $this->url = $url;
        $this->icon = $icon;
    }

    public function getFromUser(): ?User
    {
        return $this->fromUser ?? User::query()->where('username', 'System')->first();
    }

    public function getSubject(): string
    {
        return (string) $this->subjectId;
    }

    public function getData(): array
    {
        return [
            'type' => $this->notificationType,
            'message' => $this->message,
            'fromUserId' => $this->fromUser?->id,
            'subjectId' => $this->subjectId,
            'url' => $this->url,
            'icon' => $this->icon,
            'unique' => (string) Str::orderedUuid(),
        ];
    }

    public static function getType(): string
    {
        return 'customNotification';
    }

    public static function getSubjectModel(): string
    {
        return User::class;
    }
}

What I Need:
If there are no issues with this CustomNotificationBlueprint, I can share the API-related files for further inspection.

SychO

huseyinfiliz The problem lies in the following getSubject method, which I cannot customize via the API. Regardless of what I try (int, string, etc.), subjectId always ends up being null in the database:

because getSubject must return either a model instance (real model) or NULL. Anything that isn't a model instance will lead to NULL, in 2.0 the return type is enforced.

huseyinfiliz By the way, the reason I want to change the subjectId is that I plan to use it as a category.

Do you mean visually? like how discussion specific notifications are grouped together?

huseyinfiliz new notifications overwrite the old ones.

even when the data field contains the unique generated value? is your extension code uploaded somewhere? I'd have to try and see.

huseyinfiliz

By the way, the reason I want to change the subjectId is that I plan to use it as a category. If subjectId remains as 1, new notifications overwrite the old ones. I intend to use this field to customize notifications, such as categorizing them as "ads" or "warnings."

huseyinfiliz

SychO

SychO because getSubject must return either a model instance (real model) or NULL. Anything that isn't a model instance will lead to NULL, in 2.0 the return type is enforced.

I solved this by linking it to the user (I think). At least, it seems to be working properly for now.

SychO Do you mean visually? like how discussion specific notifications are grouped together?

Let me explain. Even if the notification content is different, as long as the subject ID remains the same, the new notification overwrites the previous one (the previous notification is hidden).

For example, when a comment receives a new like, the previous notification is hidden. The only way to prevent this is to change the subject ID.

The reason I did this is that there were requests for features like sending warnings to members, sending forum rules to new members, and advertising notifications using this extension.

If the subject ID doesn't change, it causes the previous notification to be hidden, even for notifications of different types.

All custom notifications, even if they belong to different extensions (like the suspend extension), are merged into a single group.

By the way, would you recommend creating multiple notification types? Currently, I'm leaving all notification types as customNotifications and creating different notification types using the subject ID.

SychO even when the data field contains the unique generated value? is your extension code uploaded somewhere? I'd have to try and see.

If everything goes as planned, I aim to release the test version tomorrow. If you have time, I would greatly appreciate it if you could review the extension's code.

Since I couldn't find sufficient documentation on this topic, I've been progressing through trial and error, and I've used a lot of workarounds.

huseyinfiliz

SychO I thought I hadn't explained the notification types well enough, so I prepared a demo.

Notification types:

Database:

huseyinfiliz

luceos Following your suggestion, i started using my own database table. Thanks.

SychO I've been working on this for 2 weeks, but I still haven't been able to connect getSubjectModel to my NotificationHub model.

I get an error like "InvalidArgumentException: Flarum\Api\Serializer\UserSerializer can only serialize instances of Flarum\User\User".

I would be very grateful if you could check it. I'm trying to get the extension ready to be published tomorrow. The codes are still very messy. I hope you can help solve this problem.

Blueprint

<?php

namespace huseyinfiliz\notificationhub\Notification;

use Flarum\Notification\Blueprint\BlueprintInterface;
use Flarum\User\User;
use Illuminate\Support\Str;
use huseyinfiliz\notificationhub\Model\NotificationHub;

class CustomNotificationBlueprint implements BlueprintInterface
{
    protected string $message;
    protected ?User $fromUser;
    protected string $notificationType;
    protected string $subjectId;
    protected string $url;
    protected string $icon;

    public function __construct(
        string $message,
        ?User $fromUser = null,
        string $notificationType = 'default',
        string $subjectId = '1',
        string $url = '#',
        string $icon = 'fas fa-bell'
    ) {
        $this->message = $message;
        $this->fromUser = $fromUser;
        $this->notificationType = $notificationType;
        $this->subjectId = $subjectId;
        $this->url = $url;
        $this->icon = $icon;
    }

    public function getFromUser()
    {
        return $this->fromUser ?: null;
    }

    public function getSubject()
    {
        return NotificationHub::find((int) $this->subjectId);
    }

    public function getData()
    {
        $notificationHub = NotificationHub::find($this->subjectId);
        $excerptText = $notificationHub ? $notificationHub->excerpt_key : null;

        return [
            'message' => $this->message,
            'excerpt' => $excerptText,
            'url' => $this->url,
            'icon' => $this->icon,
            'unique' => (string) Str::orderedUuid(),
        ];
    }

    public static function getType()
    {
        return 'customNotification';
    }

    public static function getSubjectModel()
    {
        return NotificationHub::class;
    }
}

Serializer

<?php

namespace huseyinfiliz\notificationhub\Serializers;

use Flarum\Api\Serializer\AbstractSerializer;
use huseyinfiliz\notificationhub\Model\NotificationHub;

class NotificationTypeSerializer extends AbstractSerializer
{
    protected $type = 'notification_types';

    protected function getDefaultAttributes($model): array
    {
        return [
            'id'                => $model->id,
            'name'              => $model->name,
            //'excerpt_key'       => $model->excerpt_key,
            'default_url'       => $model->default_url,
            'default_icon'      => $model->default_icon,
            'default_message_key' => $model->default_message_key,
            'is_active'         => $model->is_active,
            //'sort_order'        => $model->sort_order,
            //'description'       => $model->description,
            //'permission'        => $model->permission,
            //'color'             => $model->color,
            //'default_recipients' => $model->default_recipients,
            //'createdAt'         => $this->formatDate($model->created_at),
            //'updatedAt'         => $this->formatDate($model->updated_at),
        ];
    }
}

Controller

<?php

namespace huseyinfiliz\notificationhub\Controllers;

use Flarum\Foundation\ValidationException;
use Flarum\Http\RequestUtil;
use Flarum\User\UserRepository;
use Flarum\User\User;
use Flarum\Notification\NotificationSyncer;
use Illuminate\Contracts\Translation\Translator;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Support\Arr;
use Laminas\Diactoros\Response\JsonResponse;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;
use huseyinfiliz\notificationhub\Notification\CustomNotificationBlueprint;
use Flarum\Group\Group;

class SendNotificationController implements RequestHandlerInterface
{
    public function __construct(
        protected UserRepository $users,
        protected NotificationSyncer $notificationSyncer
    ) {
    }

    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        $actor = RequestUtil::getActor($request);

        $data = (array) $request->getParsedBody();
        $groupIds = Arr::get($data, 'groupIds', []);
        $userIds = Arr::get($data, 'userIds', []);

        error_log("SendNotificationController: Received groupIds: " . json_encode($groupIds));
        error_log("SendNotificationController: Received userIds: " . json_encode($userIds));

         // İzin kontrolü
        if (count($groupIds) > 0) {
            $actor->assertCan('huseyinfiliz-notificationhub.send-all');
        } else {
            $actor->assertCan('huseyinfiliz-notificationhub.send-user');
        }


        $messageText = (string)Arr::get($data, 'message');
        $fromUserId = Arr::get($data, 'fromUserId');
        $subjectId = Arr::get($data, 'subjectId', '1');
        $url = (string)Arr::get($data, 'url', '#');
        $icon = (string)Arr::get($data, 'icon', 'fas fa-bell');

         if (!$messageText) {
            /** @var Translator $translator */
            $translator = resolve(Translator::class);
            throw new ValidationException(['message' => [$translator->get('huseyinfiliz-notificationhub.api.message_required')]]);
        }

        if (empty($userIds) && empty($groupIds)) {
             /** @var Translator $translator */
            $translator = resolve(Translator::class);
           throw new ValidationException(['userIds' => [$translator->get('huseyinfiliz-notificationhub.api.user_ids_required')]]);
        }


        // Gönderen kullanıcıyı belirleme
        $fromUser = $fromUserId ? User::find($fromUserId) : $actor;

        $recipientCount = 0;
        $allUserIds = []; // Initializing `$allUserIds` as an empty array.

        $hasMemberGroup = in_array(Group::MEMBER_ID, $groupIds); // Defined the hasMemberGroup before.

         if($userIds && count($userIds)){
             $allUserIds = [...$userIds];  // Add the direct users first.

        }

        if(isset($groupIds) && count($groupIds)){
            $userQuery = $this->users->query();

            if(!$hasMemberGroup){ // If we don't have the member group then fetch by groups as before.
                $userQuery->whereHas('groups', function (Builder $query) use ($groupIds) {
                    $query->whereIn('id', $groupIds);
               });
                 error_log("SendNotificationController: Query after group IDs applied:" . $userQuery->toSql());

                 $userQuery->chunk(50, function ($users) use (&$allUserIds) {
                      foreach ($users as $user) {
                        $allUserIds[] = $user->id;
                      }
                 });
           }
            else {
            // If member group is present then skip the `whereHas` and fetch all users

                error_log("SendNotificationController: Fetching all users since the Member group is present");
                  $this->users->query()->chunk(50, function ($users) use(&$allUserIds){
                      foreach ($users as $user){
                         $allUserIds[] = $user->id;
                      }
                 });

            }

        }
          $allUserIds = array_unique($allUserIds); // Remove duplicates

        error_log("SendNotificationController: Final user ids before sending:". json_encode($allUserIds)); // log before sending notifications

        foreach ($allUserIds as $userId) {
            $user = User::find($userId);
            if ($user) {
                $blueprint = new CustomNotificationBlueprint(
                    $messageText,
                    $fromUser,
                    'custom_admin_notification',
                    $subjectId,
                    $url,
                    $icon
                );
				$this->notificationSyncer->sync($blueprint, [$user]);
                $recipientCount++;
            }
        }

         if ($recipientCount === 0) {
            /** @var Translator $translator */
            $translator = resolve(Translator::class);
            throw new ValidationException(['userIds' => [$translator->get('huseyinfiliz-notificationhub.api.no_valid_recipients')]]);
        }

        return new JsonResponse([
            'message' => $messageText,
            'recipientCount' => $recipientCount,
            'status' => 'OK'
        ]);
    }
}

SychO

huseyinfiliz I've checked the code, it does indeed group by (type, subject_id) and unless that's changed in core by introducing a third column (grouping_key set to null by default for example that can be customized per blueprint) you won't be able to do anything about it. (In case you're interested, feel free to contribute a change for this on the 2.x branch.)

flarum/frameworkblob/1.x/framework/core/src/Notification/NotificationRepository.php#L34

If by multiple types you mean doing something like customNotification + random unique id for each notification, i don't recommend that either. You will face multiple issues when you try to implement emails for example. (edited)

My recommendation would be to not use the notification system at all (except for emails).

Until this is improved in core, I would suggest creating your own notification dropdown/area, it's fairly easy to do, you can check the flags extension to see how it copied the dropdown area. You can create your own model/table to save these dynamic notifications and display them in the UI (would avoid naming it notification to prevent conflicts).

By doing so you guarantee that your code is not dealing with case scenarios that will lead to issues in the future.

huseyinfiliz

SychO SychO First of all, I am not using the email system—this will only be for notifications. Additionally, I want to work with the existing notification route rather than creating a separate one like drafts or flags.

Since I started developing this feature, I’ve realized that many people have been requesting something similar for years, and yet nothing like this has been implemented. This became a challenge for me. I enjoy thinking differently and solving problems, so I saw this as an opportunity to do so.

Regarding different notification types, I’m considering either creating distinct "types" for each kind of notification or just leaving it as it is for now.

Admittedly, my approach might not be the most ideal or logical one, but it seems like I’ve achieved what I wanted to accomplish.

In the past, I’ve faced issues with extensions that had their own custom database tables. For this reason, none of my extensions include custom tables in the database. I believe Flarum could make some improvements on the core side to address this more effectively.

For now, everything seems to be working fine (the “if it works, don’t touch it” principle). I really appreciate all your support—without it, I’d probably feel like I was drowning in an ocean, unable to solve even a simple problem for days 😄

SychO

theoretically though if you really really don't wish to separate from the notifications system, you could replace the notification listing controller

flarum/frameworkblob/1.x/framework/core/src/Api/Controller/ListNotificationsController.php

by copy pasting the same code and changing the query used to group by (type, subject_id, grouping_key) where you would add a new grouping_key column (for example) that would be null by default but filled with a random value for your customNotification type.

SychO

huseyinfiliz First of all, I am not using the email system—this will only be for notifications.

not yet 😉, it's the same system so sending the notifications by email only require implementing an interface and adding the email content of the type. You'll likely want to add that eventually. At least for some types.

huseyinfiliz I believe Flarum could make some improvements on the core side to address this more effectively.

Adding new tables is very safe and straightforward as long as you follow good practices. Some extensions write not so ideal code that can create issues down the line, but otherwise, look at bundled extensions for example, many of them have custom tables. Feel free to share more details though if you run into that again 👍️

luceos

huseyinfiliz In the past, I’ve faced issues with extensions that had their own custom database tables. For this reason, none of my extensions include custom tables in the database. I believe Flarum could make some improvements on the core side to address this more effectively.

Truth be told, often it's much better to isolate your tables from core and other extensions than re-using existing tables. This is especially true for the posts, discussion and users table. On highly volatile communities with millions of records it's almost impossible to execute a migration that adds a column or updates one to any of these tables. That's also why many extensions, rightfully, use their own table, even for minor features.

huseyinfiliz

SychO hello again, actually, I wanted to ask your opinion on a different topic, but I hope I'm not bothering you. I’ve tried countless things to send bulk notifications to Group IDs. I used a permission dropdown to let users select group IDs, etc., but none of them worked successfully.

As you can see below, I added a field where users can manually write group IDs separated by commas. This allows adding as many group IDs as needed.

Then, when the "Check" button is clicked, using https://example.com/api/users, it checks 20 users at a time and sequentially checks all users to find those who match the given group IDs, adding them collectively to the field above.

I’ve tried many approaches, but I’ve failed each time. I don’t think this is an efficient method for large forums, but at least it “works.”

I couldn’t find any extension with such functionality to fetch group members from group IDs. If you know of an extension, I could review its code. If not, I’ll unfortunately have to continue with this method.

Thank you in advance for your help!

SychO

huseyinfiliz hmm I don't fully understand. So the admin can either select specific users OR groups to send to. Or is the group selection field there to filter out the provided user selection?

I would drop the "check" button. Keep the group selection (IDs) then on the backend side, query the users of those groups in an optimal way:

User::query()
    ->whereIn('id', $userIds)
    ->orWhereHas('groups', function($query) use ($groupIds) {
        $query->whereIn('groups.id', $groupIds);
    })
    ->chunk(200, function (Collection $users) {
        // Notify the 200 users.
    });

This will query 200 users at a time from the database. It's the most optimal way you can do this.

I would then improve the user and group selections by creating multi select fields that use the API to search the models and save the selected ones (it's easier than it sounds, and a nice challenge)

huseyinfiliz

omg, is this a joke?? I feel so dumb right now

->type(CustomNotificationBlueprint::class, NotificationTypeSerializer::class, ['alert']),

I think i was still using UserSerializer here, and that was probably the root cause of the error. Ugh, rookie mistake 😒

huseyinfiliz

@SychO I’m facing an issue where a new notification is being received and displayed in the forum interface (the notification count increases), but it’s not being processed or displayed in the notification panel. Here’s the API response for the notification:

{
    "data": [
        {
            "type": "notifications",
            "id": "793",
            "attributes": {
                "contentType": "customNotification",
                "content": {
                    "message": "1",
                    "excerpt": "Default Excerpt",
                    "url": "",
                    "icon": "",
                    "unique": "9e33b595-16b8-4567-95b8-f01c7e19492b"
                },
                "createdAt": "2025-02-13T12:21:09+00:00",
                "isRead": false
            },
            "relationships": {
                "fromUser": {
                    "data": {
                        "type": "users",
                        "id": "1"
                    }
                },
                "subject": {
                    "data": {
                        "type": "notification_types",
                        "id": "2"
                    }
                }
            }
        }
    ]
}

I suspect the issue might be related to the "type": "notification_types" in the subject field. Here’s what I’ve tried so far:

Verified that the notification_types with ID "2" exists in the backend.
Checked the frontend logic for handling "customNotification" content type.

Could this be due to missing logic for handling the notification_types type? Any suggestions on how to debug or fix this?

Thanks in advance!

SychO

huseyinfiliz displayed in the forum interface

huseyinfiliz not being processed or displayed in the notification panel

i can't really tell which is which of these interfaces.

By default there is the notification dropdown, and there is the notification preference settings. Which are you referring to?

SychO

huseyinfiliz nvm, i see it here (sorry, multi tasking).

What's the code for the notification type component on the js side? i'm especially looking for the part that registers the notification type component (you might have either used a JS extender or just code in index.js)

huseyinfiliz

I think I can do this with Notification Grid, but I just couldn't manage it.

huseyinfiliz

SychO I will try to be more clear.

BEFORE OPENING the notification dropdown, a number appears/increases on the notification icon, indicating that a notification has arrived.

However, when I click on the notification icon and OPEN the notification dropdown, the notifications do not appear.

I'm sorry for using capital letters; I just have poor English.