feat: add contract reminders system with custom scheduling options

Author: Itamar Junior

app/Livewire/Company/BudgetCalendar.php

@@ -35,10 +35,10 @@ public function mount()
     }
 
     public function showDueItems($date)
-{
-    $this->selectedDate = $date;
-    $this->selectedDueItems = $this->dueDatesByDay[$date] ?? [];
-}
+    {
+        $this->selectedDate = $date;
+        $this->selectedDueItems = $this->dueDatesByDay[$date] ?? [];
+    }
 
     public function updatedViewMode($value)
     {
@@ -78,13 +78,52 @@ public function loadMonthlyContracts()
 
         if (!$this->selectedCompanyId) return;
 
-        $contracts = CompanyServiceContract::with(['provider', 'category'])
+        $contracts = CompanyServiceContract::with(['provider', 'category', 'reminders.contract'])
             ->where('company_id', $this->selectedCompanyId)
             ->get();
 
         foreach ($contracts as $contract) {
-            $date = Carbon::parse($contract->next_due_date)->toDateString();
-            $this->dueDatesByDay[$date][] = $contract;
+            // Add contract end_date (if any)
+            if ($contract->end_date) {
+                $date = Carbon::parse($contract->end_date)->toDateString();
+                $this->dueDatesByDay[$date][] = [
+                    'type' => 'contract',
+                    'title' => "{$contract->category->name} - {$contract->provider->name}",
+                    'model' => $contract,
+                    'due_date' => $date,
+                ];
+            }
+
+
+            foreach ($contract->reminders as $reminder) {
+                $allDates = [];
+
+                // Always include the primary due_date first
+                if ($reminder->due_date) {
+                    $allDates[] = Carbon::parse($reminder->due_date)->toDateString();
+                }
+
+                // Add custom dates if manual
+                if ($reminder->frequency === 'manual') {
+                    $customDates = is_string($reminder->custom_dates) ? json_decode($reminder->custom_dates) : $reminder->custom_dates;
+
+                    if (is_array($customDates)) {
+                        foreach ($customDates as $customDate) {
+                            $allDates[] = Carbon::parse($customDate)->toDateString();
+                        }
+                    }
+                }
+
+                // Add all to dueDatesByDay
+                foreach (array_unique($allDates) as $date) {
+                    $this->dueDatesByDay[$date][] = [
+                        'type' => 'reminder',
+                        'title' => $reminder->title,
+                        'model' => $reminder,
+                        'due_date' => $date,
+                    ];
+                }
+            }
         }
     }
 

app/Livewire/Company/Service/ContractManager.php

@@ -6,6 +6,7 @@
 use Livewire\Component;
 use App\Models\ServiceCategory;
 use App\Models\ServiceProvider;
+use App\Models\ContractReminder;
 use Illuminate\Support\Facades\Auth;
 use App\Models\CompanyServiceContract;
 use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
@@ -24,7 +25,7 @@ class ContractManager extends Component
     public $service_provider_id;
     public $budget;
     public $start_date;
-    public $next_due_date;
+    public $end_date;
     public $status = 'active';
     public $notes;
 
@@ -36,6 +37,17 @@ class ContractManager extends Component
     public ?CompanyServiceContract $editingContract = null;
     public ?CompanyServiceContract $deletingContract = null;
 
+    // Reminder properties
+    public bool $showReminderModal = false;
+    public ?int $contractReminderContractId = null;
+    public $reminder_title, $reminder_due_date, $reminder_frequency = 'manual';
+    public $reminder_day_of_month, $reminder_custom_dates = [], $reminder_months_active = [];
+    public $reminder_days_before = 7, $reminder_days_after = 0, $reminder_notes;
+    public string $reminder_months_active_string = '';
+    public string $reminder_custom_dates_string = '';
+    public ?int $reminder_id = null;
+
+
     public function mount()
     {
         $this->companies = Company::where('business_id', Auth::user()->current_business_id)->orderBy('name')->get();
@@ -53,14 +65,14 @@ public function updatedServiceCategoryId($categoryId)
 
     public function loadContracts()
     {
-        $this->contracts = CompanyServiceContract::with(['company', 'provider', 'category'])
+        $this->contracts = CompanyServiceContract::with(['company', 'provider', 'category', 'reminders'])
             ->whereHas('company', fn($q) => $q->where('business_id', Auth::user()->current_business_id))
             ->latest()->get();
     }
 
     public function openCreateModal()
     {
-        $this->reset(['company_id', 'service_category_id', 'service_provider_id', 'budget', 'start_date', 'next_due_date', 'status', 'notes']);
+        $this->reset(['company_id', 'service_category_id', 'service_provider_id', 'budget', 'start_date', 'end_date', 'status', 'notes']);
         $this->resetValidation();
         $this->showCreateModal = true;
     }
@@ -73,7 +85,7 @@ public function create()
             'service_provider_id' => 'required|exists:service_providers,id',
             'budget' => 'nullable|numeric',
             'start_date' => 'nullable|date',
-            'next_due_date' => 'nullable|date',
+            'end_date' => 'nullable|date',
             'status' => 'required|in:active,inactive,terminated',
         ]);
 
@@ -83,7 +95,7 @@ public function create()
             'service_provider_id' => $this->service_provider_id,
             'budget' => $this->budget,
             'start_date' => $this->start_date,
-            'next_due_date' => $this->next_due_date,
+            'end_date' => $this->end_date,
             'status' => $this->status,
             'notes' => $this->notes,
         ]);
@@ -103,7 +115,7 @@ public function edit($id)
         $this->service_provider_id = $this->editingContract->service_provider_id;
         $this->budget = $this->editingContract->budget;
         $this->start_date = $this->editingContract->start_date;
-        $this->next_due_date = $this->editingContract->next_due_date;
+        $this->end_date = $this->editingContract->end_date;
         $this->status = $this->editingContract->status;
         $this->notes = $this->editingContract->notes;
 
@@ -118,7 +130,7 @@ public function update()
             'service_provider_id' => 'required|exists:service_providers,id',
             'budget' => 'nullable|numeric',
             'start_date' => 'nullable|date',
-            'next_due_date' => 'nullable|date',
+            'end_date' => 'nullable|date',
             'status' => 'required|in:active,inactive,terminated',
         ]);
 
@@ -130,7 +142,7 @@ public function update()
             'service_provider_id' => $this->service_provider_id,
             'budget' => $this->budget,
             'start_date' => $this->start_date,
-            'next_due_date' => $this->next_due_date,
+            'end_date' => $this->end_date,
             'status' => $this->status,
             'notes' => $this->notes,
         ]);
@@ -158,6 +170,91 @@ public function delete()
         session()->flash('success', 'Contract deleted.');
     }
 
+    public function openReminderModal($contractIdToAttachToReminder)
+    {
+        $this->reset([
+            'reminder_title',
+            'reminder_due_date',
+            'reminder_frequency',
+            'reminder_day_of_month',
+            'reminder_custom_dates',
+            'reminder_months_active',
+            'reminder_days_before',
+            'reminder_days_after',
+            'reminder_notes',
+            'reminder_id',
+        ]);
+
+        $this->contractReminderContractId = $contractIdToAttachToReminder;
+        $this->showReminderModal = true;
+    }
+
+    public function saveReminder()
+    {
+        $months = collect(explode(',', $this->reminder_months_active_string))
+            ->filter()
+            ->map(fn($m) => (int) trim($m))
+            ->filter(fn($m) => $m >= 1 && $m <= 12)
+            ->values()
+            ->toArray();
+
+        $dates = collect(explode(',', $this->reminder_custom_dates_string))
+            ->map(fn($d) => trim($d))
+            ->filter(function ($d) {
+                try {
+                    return \Carbon\Carbon::createFromFormat('Y-m-d', $d) !== false;
+                } catch (\Exception $e) {
+                    return false;
+                }
+            })
+            ->values()
+            ->toArray();
+
+        $data = [
+            'company_service_contract_id' => $this->contractReminderContractId,
+            'title' => $this->reminder_title,
+            'due_date' => $this->reminder_due_date,
+            'frequency' => $this->reminder_frequency,
+            'day_of_month' => $this->reminder_day_of_month,
+            'custom_dates' => $dates,
+            'months_active' => $months,
+            'reminder_days_before' => $this->reminder_days_before,
+            'reminder_days_after' => $this->reminder_days_after,
+            'notes' => $this->reminder_notes,
+        ];
+
+        if ($this->reminder_id) {
+            ContractReminder::find($this->reminder_id)?->update($data);
+            session()->flash('success', 'Reminder updated.');
+        } else {
+            ContractReminder::create($data);
+            session()->flash('success', 'Reminder created.');
+        }
+
+        $this->reset(['showReminderModal', 'reminder_id']);
+        $this->loadContracts();
+    }
+
+    public function editReminder($reminderId)
+    {
+        $reminder = ContractReminder::findOrFail($reminderId);
+
+        $this->reminder_id = $reminder->id;
+        $this->contractReminderContractId = $reminder->company_service_contract_id;
+
+        $this->reminder_title = $reminder->title;
+        $this->reminder_due_date = $reminder->due_date;
+        $this->reminder_frequency = $reminder->frequency;
+        $this->reminder_day_of_month = $reminder->day_of_month;
+        $this->reminder_custom_dates_string = collect($reminder->custom_dates)->implode(',');
+        $this->reminder_months_active_string = collect($reminder->months_active)->implode(',');
+        $this->reminder_days_before = $reminder->reminder_days_before;
+        $this->reminder_days_after = $reminder->reminder_days_after;
+        $this->reminder_notes = $reminder->notes;
+
+        $this->showReminderModal = true;
+    }
+
     public function render()
     {
         return view('livewire.company.service.contract-manager');

app/Models/CompanyServiceContract.php

@@ -15,7 +15,7 @@ class CompanyServiceContract extends Model
         'service_category_id',
         'budget',
         'start_date',
-        'next_due_date',
+        'end_date',
         'status',
         'notes',
     ];
@@ -34,4 +34,9 @@ public function category(): \Illuminate\Database\Eloquent\Relations\BelongsTo
     {
         return $this->belongsTo(ServiceCategory::class, 'service_category_id');
     }
+
+    public function reminders(): \Illuminate\Database\Eloquent\Relations\HasMany
+    {
+        return $this->hasMany(ContractReminder::class, 'company_service_contract_id');
+    }
 }

app/Models/ContractReminder.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+
+class ContractReminder extends Model
+{
+    use HasFactory;
+
+    protected $fillable = [
+        'company_service_contract_id',
+        'title',
+        'due_date', // first/next due date
+        'frequency', // manual, monthly, bimonthly, quarterly, yearly, once
+        'day_of_month', // e.g., 15th of the month
+        'months_active', // e.g., ["January", "February", "March"] or ["1", "2", "3"] for Jan, Feb, Mar
+        'custom_dates', // e.g., ["2025-02-12", "2025-05-08", "2025-11-30"]
+        'reminder_days_before', // days before the due date to notify
+        'reminder_days_after', // days after the due date to notify
+        'notified_before', // whether notification before the due date has been sent
+        'notified_after', // whether notification after the due date has been sent
+        'notes', // additional notes for the reminder
+    ];
+
+    protected $casts = [
+        'custom_dates' => 'array',
+        'months_active' => 'array',
+    ];
+
+    public function contract()
+    {
+        return $this->belongsTo(CompanyServiceContract::class, 'company_service_contract_id');
+    }
+}

database/migrations/2025_06_16_100437_create_company_service_contracts_table.php

@@ -21,7 +21,7 @@ public function up(): void
 
             $table->decimal('budget', 12, 2)->nullable();
             $table->date('start_date')->nullable();
-            $table->date('next_due_date')->nullable();
+            $table->date('end_date')->nullable();
             $table->enum('status', ['active', 'inactive', 'terminated'])->default('active');
             $table->text('notes')->nullable();
         });

database/migrations/2025_06_20_133233_create_contract_reminders_table.php

@@ -0,0 +1,42 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('contract_reminders', function (Blueprint $table) {
+            $table->id();
+            $table->timestamps();
+
+            $table->foreignId('company_service_contract_id')->constrained()->cascadeOnDelete();
+            $table->string('title')->nullable();
+            $table->date('due_date'); // first/next due date
+            $table->enum('frequency', ['manual','weekly', 'biweekly', 'semimonthly', 'monthly', 'bimonthly', 'threemonthly', 'quarterly', 'yearly', 'once'])->nullable();
+
+            $table->unsignedTinyInteger('day_of_month')->nullable(); // e.g., 15th of the month
+            $table->json('months_active')->nullable(); // e.g., ["January", "February", "March"] or ["1", "2", "3"] for Jan, Feb, Mar
+            $table->json('custom_dates')->nullable(); // e.g., ["2025-02-12", "2025-05-08", "2025-11-30"]
+
+            $table->integer('reminder_days_before')->default(0);
+            $table->integer('reminder_days_after')->default(0);
+            $table->boolean('notified_before')->default(false);
+            $table->boolean('notified_after')->default(false);
+            $table->text('notes')->nullable();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('contract_reminders');
+    }
+};