coders-tm/laravel-core / .agents/skills/notification-template
notification-template-system
VerifiedManages 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 19.8 KB |
SKILL.md
View on GitHub---
name: notification-template-system
description: "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."
license: MIT
metadata:
author: coderstm
---
# 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`)
```php
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:**
| Variable | Value | Example |
| ------------------------------ | --------------------- | ---------------------------- |
| `{{ $user->first_name }}` | User's first name | John |
| `{{ $user->email }}` | User's email | john@example.com |
| `{{ $order->number }}` | Order number | #ORD-12345 |
| `{{ $order->total }}` | Formatted order total | $99.00 |
| `{{ $variant->product_name }}` | Product name | Premium Widget |
| `{{ $cart->recovery_url }}` | Cart recovery link | https://example.com/cart/... |
| `{{ $app->name }}` | Application name | MyApp |
### User Variables
Available via `$user->getShortCodes()`:
| Variable | Value | Example |
| --------------------------- | ------------------------ | ---------------- |
| `{{ $user->name }}` | Full name (first + last) | John Doe |
| `{{ $user->first_name }}` | User's first name | John |
| `{{ $user->last_name }}` | User's last name | Doe |
| `{{ $user->id }}` | User ID | 123 |
| `{{ $user->email }}` | User's email | john@example.com |
| `{{ $user->phone_number }}` | User's phone | +1234567890 |
### Subscription Variables
Available via `$subscription->getShortCodes()`:
| Variable | Value | Example |
| ------------------------------------ | ---------------- | ------------ |
| `{{ $subscription->plan_label }}` | Plan name | Premium Plan |
| `{{ $subscription->plan_price }}` | Formatted price | $99.00 |
| `{{ $subscription->billing_cycle }}` | Billing interval | Monthly |
| `{{ $subscription->expires_at }}` | Expiration date | Dec 31, 2025 |
| `{{ $subscription->billing_url }}` | Billing page URL | /billing |
### Order Variables
Available via `$order->getShortCodes()`:
| Variable | Value | Example |
| -------------------------------- | ---------------- | ------------ |
| `{{ $order->number }}` | Order number | #ORD-12345 |
| `{{ $order->total }}` | Formatted total | $99.00 |
| `{{ $order->status }}` | Order status | Completed |
| `{{ $order->date }}` | Order date | Dec 15, 2025 |
| `{{ $order->tracking_number }}` | Tracking number | TRACK123 |
| `{{ $order->tracking_company }}` | Tracking company | FedEx |
| `{{ $order->customer_name }}` | Customer name | John Doe |
### Cart/Checkout Variables
Available via `$checkout->getShortCodes()`:
| Variable | Value | Example |
| --------------------------- | --------------- | ------------ |
| `{{ $cart->total }}` | Cart total | $99.00 |
| `{{ $cart->item_count }}` | Number of items | 3 |
| `{{ $cart->recovery_url }}` | Recovery link | /cart/abc123 |
### Product/Variant Variables
Available via `$variant->getShortCodes()`:
| Variable | Value | Example |
| ------------------------------ | ------------------ | -------------- |
| `{{ $variant->product_name }}` | Product name | Premium Widget |
| `{{ $variant->sku }}` | SKU | WIDGET-001 |
| `{{ $variant->price }}` | Price | $49.99 |
| `{{ $variant->stock }}` | Available quantity | 10 |
### App Variables
Available via `$app`:
| Variable | Value | Example |
| ------------------- | ---------------- | -------- |
| `{{ $app->name }}` | Application name | MyApp |
| `{{ $app->email }}` | Support email | support@ |
## Creating New Notifications
### Step 1: Create Notification Class
**Modern Approach (Recommended):**
```php
<?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:**
```json
{
"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`**
```blade
<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:
```php
// 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
```php
// 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
```html
<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
```html
<!-- 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>
```
```php
// In notification class
$rendered = $notification->render([
'user' => $user->getShortCodes(),
'isPremium' => $user->subscription?->plan->isPremium(),
'upgradeUrl' => url('/upgrade'),
]);
```
### Loops
```html
<p>Your subscription includes:</p>
<ul>
@foreach($features as $feature)
<li>{{ $feature->name }}</li>
@endforeach
</ul>
```
```php
$rendered = $notification->render([
'features' => $plan->features,
]);
```
### Model Property Access
```html
<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>
```
```php
$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
```php
// 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
```php
// ✅ Recommended - use model's getShortCodes()
$rendered = $template->render([
'user' => $user->getShortCodes(),
'order' => $order->getShortCodes(),
]);
```
### 2. Use Blade Variables for Complex Logic
```php
// ✅ Good - use Blade for conditionals and loops
@if($isPremium)
{{ $plan->label }}
@endif
@foreach($features as $feature)
{{ $feature->name }}
@endforeach
```
### 3. Use Name Accessor
```php
// ✅ 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()
```php
// ✅ 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
```php
// ✅ 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
```php
// ✅ 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:
| Context | Size | Usage |
|---------|------|-------|
| Primary text | `font-size:14px` | Body `<p>` tags, table values, buttons, item titles, section titles |
| Secondary text | `font-size:12px` | Labels, table headers `(th)`, small notes, variant text |
| Emphasized | `font-size:15px;font-weight:700` | Total amount display |
### 8. Use Standard Panel Style for Alerts
Use full-background panels instead of quote-style left borders:
```html
<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
```php
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`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |