Skip to content

coders-tm/laravel-core / .agents/skills/notification-template

notification-template-system

Verified

Manages template-based email and push notifications with Blade rendering. Activates when creating notification classes, editing notification templates or Blade files, using shortcodes/variables, working with NotificationMail or NotificationTemplateRenderer, or seeding notification templates.

Notification System Instructions

Purpose

The notification system provides template-based email and push notifications with support for:

  • Dynamic Templates: Database-driven notification templates stored as Blade files
  • Multiple Channels: Email, SMS, push notifications, and database notifications
  • Blade Variables: Clean object syntax ({{ $user->name }}, {{ $order->number }})
  • Blade Templates: Full Blade directive support in notification templates
  • Security: Template validation and dangerous code prevention
  • Custom Mailable: HTML email rendering via custom NotificationMail class

Architecture

Notification Flow

Notification Event
    → Notification Class (construct with data)
    → Load Template from Database
    → Render Blade Variables ({{ $user->name }}, {{ $order->number }})
    → Render Blade Directives ({{ $variable }}, @if, @foreach)
    → Build HTML Email via NotificationMail
    → Send via Channel (mail, sms, push, database)

Email Rendering System

The system uses a custom Coderstm\Mail\NotificationMail Mailable class that:

  1. Renders the Blade view (emails/notification.blade.php)
  2. Wraps content in responsive HTML email template
  3. Uses htmlString to avoid escaping HTML
  4. Works with both package and Orchestra Testbench environments

Key Files:

  • src/Mail/NotificationMail.php - Custom Mailable class
  • src/Notifications/BaseNotification.php - Base notification (returns NotificationMail)
  • resources/views/emails/notification.blade.php - Email wrapper template
  • workbench/resources/views/emails/notification.blade.php - Testbench copy
  • stubs/database/templates/**/*.blade.php - Individual notification templates

Notification Template Structure

Database Model (Coderstm\Models\Notification)

protected $fillable = [
    'label',      // Human-readable name: "Signup", "Invoice sent"
    'subject',    // Email subject with shortcodes/Blade
    'type',       // Unique identifier: "user:signup", "admin:new-enquiry"
    'content',    // Email body with shortcodes/Blade (HTML)
    'is_default', // Is this the default template for this type?
];

Template Types

User Notifications:

  • user:signup - Welcome email after registration
  • user:subscription-cancel - Cancellation confirmation
  • user:subscription-canceled - Subscription ended
  • user:subscription-downgrade - Plan downgrade notice
  • user:subscription-upgraded - Plan upgrade confirmation
  • user:subscription-renewed - Subscription renewal confirmation
  • user:subscription-expired - Subscription expiration notice
  • user:invoice-sent - Invoice delivery
  • user:order-confirmation - Order placed confirmation
  • user:order-shipped - Shipping notification with tracking
  • user:order-delivered - Delivery confirmation
  • user:order-canceled - Order cancellation notice
  • user:payment-success - Payment confirmation
  • user:payment-failed - Payment failure alert
  • user:partial-refund - Partial refund processed
  • user:order-refunded - Full refund processed
  • user:abandoned-cart - Cart recovery reminder

Admin Notifications:

  • admin:new-admin - New admin user created
  • admin:new-enquiry - New enquiry submitted
  • admin:hold - User account held
  • admin:hold-release - User account released
  • admin:subscription-canceled - User subscription canceled
  • admin:subscription-expired - User subscription expired
  • admin:new-order - New order received
  • admin:order-canceled - Order canceled by customer
  • admin:payment-failed - Payment failure alert
  • admin:refund-processed - Refund processed notification
  • admin:low-stock - Low inventory alert
  • admin:out-of-stock - Out of stock alert

Enquiry Notifications:

  • enquiry:message - New enquiry message
  • enquiry:reply - Enquiry reply from admin
  • enquiry:reply-user - Enquiry reply from user

Push Notifications:

  • push:message - Generic push notification

Task Notifications:

  • task:added - Task assigned to user

Import Notifications:

  • import:completed - Data import finished

Shortcode Reference

Blade Variable Format

All templates use Blade variables for clean, readable syntax:

VariableValueExample
{{ $user->first_name }}User's first nameJohn
{{ $user->email }}User's emailjohn@example.com
{{ $order->number }}Order number#ORD-12345
{{ $order->total }}Formatted order total$99.00
{{ $variant->product_name }}Product namePremium Widget
{{ $cart->recovery_url }}Cart recovery linkhttps://example.com/cart/...
{{ $app->name }}Application nameMyApp

User Variables

Available via $user->getShortCodes():

VariableValueExample
{{ $user->name }}Full name (first + last)John Doe
{{ $user->first_name }}User's first nameJohn
{{ $user->last_name }}User's last nameDoe
{{ $user->id }}User ID123
{{ $user->email }}User's emailjohn@example.com
{{ $user->phone_number }}User's phone+1234567890

Subscription Variables

Available via $subscription->getShortCodes():

VariableValueExample
{{ $subscription->plan_label }}Plan namePremium Plan
{{ $subscription->plan_price }}Formatted price$99.00
{{ $subscription->billing_cycle }}Billing intervalMonthly
{{ $subscription->expires_at }}Expiration dateDec 31, 2025
{{ $subscription->billing_url }}Billing page URL/billing

Order Variables

Available via $order->getShortCodes():

VariableValueExample
{{ $order->number }}Order number#ORD-12345
{{ $order->total }}Formatted total$99.00
{{ $order->status }}Order statusCompleted
{{ $order->date }}Order dateDec 15, 2025
{{ $order->tracking_number }}Tracking numberTRACK123
{{ $order->tracking_company }}Tracking companyFedEx
{{ $order->customer_name }}Customer nameJohn Doe

Cart/Checkout Variables

Available via $checkout->getShortCodes():

VariableValueExample
{{ $cart->total }}Cart total$99.00
{{ $cart->item_count }}Number of items3
{{ $cart->recovery_url }}Recovery link/cart/abc123

Product/Variant Variables

Available via $variant->getShortCodes():

VariableValueExample
{{ $variant->product_name }}Product namePremium Widget
{{ $variant->sku }}SKUWIDGET-001
{{ $variant->price }}Price$49.99
{{ $variant->stock }}Available quantity10

App Variables

Available via $app:

VariableValueExample
{{ $app->name }}Application nameMyApp
{{ $app->email }}Support emailsupport@

Creating New Notifications

Step 1: Create Notification Class

Modern Approach (Recommended):

<?php

namespace Coderstm\Notifications\Shop;

use Coderstm\Models\Shop\Order;
use Coderstm\Models\Notification as Template;
use Coderstm\Notifications\BaseNotification;

class OrderConfirmationNotification extends BaseNotification
{
    public $order;
    public $subject;
    public $message;

    public function __construct(Order $order)
    {
        $this->order = $order;

        // Load template from database
        $template = Template::default('user:order-confirmation');

        // Render using NotificationTemplateRenderer with order data
        $rendered = $template->render([
            'order' => $order->getShortCodes(),
        ]);

        parent::__construct($rendered['subject'], $rendered['content']);
    }

    public function via($notifiable): array
    {
        return ['mail', 'database'];
    }

    public function toArray($notifiable): array
    {
        return [
            'order_id' => $this->order->id,
            'order_number' => $this->order->formated_id,
            'total' => $this->order->total(),
            'status' => $this->order->status,
        ];
    }
}

Step 2: Create Template Metadata (JSON)

Using Blade Variables:

{
    "label": "Order Confirmation",
    "subject": "Order Confirmation - Order #{{ $order->number }}",
    "is_default": true,
    "type": "user:order-confirmation"
}

Note: The content is stored in a separate .blade.php file (e.g., user/order-confirmation.blade.php), not in the JSON file.

Step 3: Create Blade Template

Create the corresponding Blade template file in stubs/database/templates/:

Example: stubs/database/templates/user/order-confirmation.blade.php

<table cellpadding="0" cellspacing="0" role="presentation" width="100%"><tr><td style="font-size:14px;line-height:1.5;">
    <p style="margin:0 0 16px;font-size:14px;line-height:1.5;">Dear {{ $order->customer->first_name }},</p>
    <p style="margin:0 0 16px;font-size:14px;line-height:1.5;">Thank you for your order! We're processing it now.</p>

    <table cellpadding="0" cellspacing="0" role="presentation" width="100%" style="background:#f5f5f5;font-size:14px;margin:20px 0;">
        <tr>
            <td style="padding:12px;">
                <strong>Order #{{ $order->number }}</strong><br>
                Order Date: {{ $order->date }}<br>
                Total: {{ $order->total }}
            </td>
        </tr>
    </table>

    <p style="margin:0 0 12px;font-size:14px;font-weight:600;">Order Items:</p>
    <table cellpadding="0" cellspacing="0" role="presentation" width="100%" style="background:#ffffff;border:1px solid #e5e7eb;font-size:14px;">
        <thead>
            <tr>
                <th align="left" style="padding:12px;font-size:12px;font-weight:600;text-transform:uppercase;letter-spacing:0.5px;color:#6b7280;border-bottom:1px solid #e5e7eb;">Item</th>
                <th align="center" width="60" style="padding:12px;font-size:12px;font-weight:600;text-transform:uppercase;letter-spacing:0.5px;color:#6b7280;border-bottom:1px solid #e5e7eb;">Qty</th>
                <th align="right" width="80" style="padding:12px;font-size:12px;font-weight:600;text-transform:uppercase;letter-spacing:0.5px;color:#6b7280;border-bottom:1px solid #e5e7eb;">Price</th>
                <th align="right" width="100" style="padding:12px;font-size:12px;font-weight:600;text-transform:uppercase;letter-spacing:0.5px;color:#6b7280;border-bottom:1px solid #e5e7eb;">Total</th>
            </tr>
        </thead>
        <tbody>
            @foreach($order->items as $item)
            <tr style="border-bottom:1px solid #f3f4f6;">
                <td style="padding:12px;font-size:14px;">{{ $item['name'] }}</td>
                <td align="center" style="padding:12px;font-size:14px;">{{ $item['quantity'] }}</td>
                <td align="right" style="padding:12px;font-size:14px;">{{ $item['price'] }}</td>
                <td align="right" style="padding:12px;font-size:14px;font-weight:600;">{{ $item['total'] }}</td>
            </tr>
            @endforeach
        </tbody>
    </table>

    <table cellpadding="0" cellspacing="0" role="presentation" width="100%" style="margin:20px auto;text-align:center;" align="center">
        <tr>
            <td align="center">
                <a href="{{ $order->url }}" style="border-radius:4px;color:#ffffff;display:inline-block;text-decoration:none;padding:0 12px;font-size:14px;line-height:28px;font-weight:500;background:#3869d4;">View Order Details</a>
            </td>
        </tr>
    </table>

    <p style="margin:0 0 16px;font-size:14px;line-height:1.5;">Best regards,<br>{{ $app->name }} Team</p>
</td></tr></table>

Step 4: Seed Template

Templates are automatically seeded by NotificationSeeder which reads JSON metadata and Blade files:

// In NotificationSeeder or test setUp()
$notifications = json_decode(
    file_get_contents(__DIR__ . '/../data/notifications.json'),
    true
);

foreach ($notifications as $notification) {
    Notification::updateOrCreate(
        ['type' => $notification['type']],
        $notification
    );
}

Step 4: Send Notification

// In controller or service
$user->notify(new UserWelcomeNotification($user));

// Or via facade
Notification::send($users, new UserWelcomeNotification($user));

Using Blade Directives in Templates

Basic Example

<table cellpadding="0" cellspacing="0" role="presentation" width="100%"><tr><td>
    Hello {{ $user->first_name }}, @if($isPremium)
    <p>Thank you for being a premium member!</p>
    <p>Your plan: {{ $plan->label }} at {{ $plan->price }}</p>
    @else
    <p><a href="{{ $upgradeUrl }}">Upgrade to Premium</a></p>
    @endif
</td></tr></table>

Conditionals

<!-- In template content -->
<table cellpadding="0" cellspacing="0" role="presentation" width="100%"><tr><td>
    Hello {{ $user->first_name }}, @if($isPremium)
    <p>Thank you for being a premium member!</p>
    @else
    <p><a href="{{ $upgradeUrl }}">Upgrade to Premium</a></p>
    @endif
</td></tr></table>
// In notification class
$rendered = $notification->render([
    'user' => $user->getShortCodes(),
    'isPremium' => $user->subscription?->plan->isPremium(),
    'upgradeUrl' => url('/upgrade'),
]);

Loops

<p>Your subscription includes:</p>
<ul>
    @foreach($features as $feature)
    <li>{{ $feature->name }}</li>
    @endforeach
</ul>
$rendered = $notification->render([
    'features' => $plan->features,
]);

Model Property Access

<table cellpadding="0" cellspacing="0" role="presentation" width="100%"><tr><td>
    Email: {{ $user->email }}<br />
    Phone: {{ $user->phone_number }}<br />
    Plan: {{ $subscription->plan->label }}
</td></tr></table>
$rendered = $notification->render([
    'user' => $user,
    'subscription' => $subscription,
]);

Security Considerations

Dangerous Directives Blocked

The MaskSensitiveConfig compiler blocks dangerous functions:

  • ❌ exec(), shell_exec(), system()
  • ❌ file_get_contents(), file_put_contents()
  • ❌ eval(), assert()
  • ❌ DB::raw(), DB::statement()
  • ❌ config() writes, settings() writes
  • ❌ Inline PHP tags: <?php ?>

Allowed Directives

  • ✅ @if/@else/@endif
  • ✅ @foreach/@endforeach
  • ✅ {{ $variable }}
  • ✅ {{ $model->property }}
  • ✅ @isset/@empty
  • ✅ Standard Blade helpers

Template Validation

// Validate template before saving
$validation = $notification->validate();

if (!$validation['subject']['valid']) {
    throw new \Exception($validation['subject']['error']);
}

if (!$validation['content']['valid']) {
    throw new \Exception($validation['content']['error']);
}

Best Practices

1. Use getShortCodes() for Data

// ✅ Recommended - use model's getShortCodes()
$rendered = $template->render([
    'user' => $user->getShortCodes(),
    'order' => $order->getShortCodes(),
]);

2. Use Blade Variables for Complex Logic

// ✅ Good - use Blade for conditionals and loops
@if($isPremium)
    {{ $plan->label }}
@endif

@foreach($features as $feature)
    {{ $feature->name }}
@endforeach

3. Use Name Accessor

// ✅ Good - uses accessor from getShortCodes()
'name' => $user->name // Accessor concatenates first + last

// ❌ Bad - manual concatenation
'name' => "{$user->first_name} {$user->last_name}"

4. Format Values in getShortCodes()

// ✅ Good - pre-formatted in getShortCodes()
public function getShortCodes(): array
{
    return [
        'plan_price' => $this->plan->formatPrice(),    // "$99.00"
        'expires_at' => $this->expires_at->format('M d, Y'),
    ];
}

// ❌ Bad - raw values
public function getShortCodes(): array
{
    return [
        'plan_price' => $this->plan->price,  // 99.00
        'expires_at' => $this->expires_at,   // Carbon object
    ];
}

5. Use Optional Chaining

// ✅ Good - handles null subscription
'plan_label' => optional($user->subscription)->plan->label

// ❌ Bad - will error if no subscription
'plan_label' => $user->subscription->plan->label

6. Keep Templates Simple

// ✅ Good - simple Blade variable
{{ $plan->label }}

// ⚠️ Avoid - complex logic in template
{{ $subscription->plan->price > 100 ? 'Premium' : 'Basic' }}

// ✅ Better - calculate in getShortCodes()
'plan_type' => $subscription->plan->price > 100 ? 'Premium' : 'Basic'

7. Use Standardized Font Sizes

All templates use consistent font sizes for a uniform appearance:

ContextSizeUsage
Primary textfont-size:14pxBody <p> tags, table values, buttons, item titles, section titles
Secondary textfont-size:12pxLabels, table headers (th), small notes, variant text
Emphasizedfont-size:15px;font-weight:700Total amount display

8. Use Standard Panel Style for Alerts

Use full-background panels instead of quote-style left borders:

<table cellpadding="0" cellspacing="0" role="presentation" width="100%" style="margin:20px 0;">
    <tr>
        <td style="background:#dbeafe;color:#1e40af;padding:12px;font-size:14px;line-height:1.5;">Info content</td>
    </tr>
</table>

Available background/color pairs:

  • Info: background:#dbeafe; color:#1e40af
  • Success: background:#d1fae5; color:#065f46
  • Warning: background:#fef3c7; color:#92400e
  • Danger: background:#fee2e2; color:#991b1b
  • Neutral: background:#edf2f7; color:#718096

9. Test All Templates

public function test_notification_template_renders_correctly()
{
    $user = User::factory()->create();
    $template = Notification::default('user:signup');

    $rendered = $template->render([
        'user' => $user->getShortCodes(),
    ]);

    $this->assertStringContainsString($user->name, $rendered['subject']);
    $this->assertStringContainsString($user->first_name, $rendered['content']);
    $this->assertStringNotContainsString('{{', $rendered['content']);
}

Related Files

  • Models: src/Models/Notification.php
  • Renderer: src/Services/NotificationTemplateRenderer.php
  • Security: src/Services/MaskSensitiveConfig.php
  • Base Class: src/Notifications/BaseNotification.php
  • Templates: stubs/database/data/notifications.json
  • Seeder: stubs/database/seeders/NotificationSeeder.php
  • Helper: lib/helpers.php (replace_short_code())
  • Tests: tests/Feature/NotificationTemplateRenderingTest.php
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 193kUpdated Claude CodeCodexVerifiedInstall