lms/Modules/Certificate/SETUP.md

Certificate Module - Quick Setup Guide

🚀 Quick Start

Follow these steps to get the Certificate Builder up and running:

Step 1: Run Migration

cd /home/jamir-hossain/Works/laravel/mentor-lms
php artisan migrate

This will create the certificate_templates table with the following structure:

• id (primary key)
• name (template name)
• logo_path (nullable, stores logo file path)
• template_data (JSON, stores all customization)
• is_active (boolean, only one can be true)
• created_at, updated_at

Step 2: Ensure Storage Link Exists

php artisan storage:link

This creates a symbolic link from public/storage to storage/app/public so logos are accessible.

Step 3: Set Permissions (if needed)

chmod -R 775 storage/app/public

Step 4: Clear Cache (optional but recommended)

php artisan route:clear
php artisan config:clear
php artisan cache:clear

Step 5: Access the Certificate Builder

Admin Side:

• Navigate to: /admin/certificate-templates
• This will render the certificate builder UI

Student Side:

• Navigate to: /certificates/{courseId}
• Students will see their certificate with the active template

📝 Testing the System

Create Your First Template

1. Go to /admin/certificate-templates
2. Click "Create Template"
3. Fill in basic info:
   • Name: "Modern Blue Certificate"
   • Toggle "Set as Active"
4. Choose colors:
   • Primary: #3730a3 (Indigo)
   • Secondary: #4b5563 (Gray)
   • Background: #dbeafe (Light Blue)
   • Border: #f59e0b (Amber)
5. Upload a logo (optional)
6. Customize text or use defaults
7. Click "Create Template"

Test Student Certificate

1. Go to /certificates/1 (or any course ID)
2. You should see the certificate with your active template
3. Try downloading as PNG and PDF

🔧 Integration with Your LMS

To integrate this with your existing course completion flow:

Option 1: Add Certificate Link to Course Completion Page

In your course completion component/page, add a link:

import { Link } from '@inertiajs/react';

// In your completion page
<Link href={route('certificate.show', course.id)}>
   <Button>
      <Award className="mr-2 h-4 w-4" />
      Download Certificate
   </Button>
</Link>;

Option 2: Use the Dynamic Certificate Component Directly

import DynamicCertificate from '@/components/dynamic-certificate';

// In your page
<DynamicCertificate template={activeTemplate} studentName={auth.user.name} courseName={course.title} completionDate={completionDate} />;

Option 3: Pass Active Template from Backend

In your controller where students complete courses:

use Modules\Certificate\Models\CertificateTemplate;

$activeTemplate = CertificateTemplate::where('is_active', true)->first();

return Inertia::render('YourPage', [
    'activeTemplate' => $activeTemplate,
    // ... other props
]);

🎨 Customization Tips

Default Template

If no templates exist or none are active, the system uses default blue/gold colors automatically.

Logo Recommendations

• Format: PNG or SVG preferred
• Size: 200x200px to 400x400px
• Background: Transparent PNG works best
• Max File Size: 2MB

Color Schemes

Professional Blue (default)

Primary: #3730a3 (Indigo)
Secondary: #4b5563 (Gray)
Background: #dbeafe (Light Blue)
Border: #f59e0b (Amber)

Elegant Green

Primary: #047857 (Emerald)
Secondary: #1f2937 (Dark Gray)
Background: #d1fae5 (Light Green)
Border: #fbbf24 (Yellow)

Corporate Red

Primary: #991b1b (Dark Red)
Secondary: #374151 (Gray)
Background: #fee2e2 (Light Red)
Border: #92400e (Brown)

🔍 Troubleshooting

Issue: "Class CertificateTemplate not found"

Solution: Make sure the module is properly registered and run:

composer dump-autoload
php artisan config:clear

Issue: Logo not showing

Solution:

1. Check storage link: php artisan storage:link
2. Verify permissions: chmod -R 775 storage/app/public
3. Check file was uploaded to storage/app/public/certificates/logos/

Issue: Routes not found

Solution:

1. Ensure module routes are loaded in config/modules.php or bootstrap/app.php
2. Run: php artisan route:clear
3. Check routes: php artisan route:list | grep certificate

Issue: Template not activating

Solution: Check database - only one template should have is_active = 1. The model automatically handles this, but if you manually edited the database, fix it:

UPDATE certificate_templates SET is_active = 0;
UPDATE certificate_templates SET is_active = 1 WHERE id = [your_template_id];

📊 Database Seeder (Optional)

Create a default template for testing:

// database/seeders/CertificateTemplateSeeder.php
<?php

namespace Database\Seeders;

use Illuminate\Database\Seeder;
use Modules\Certificate\Models\CertificateTemplate;

class CertificateTemplateSeeder extends Seeder
{
    public function run()
    {
        CertificateTemplate::create([
            'name' => 'Default Blue Certificate',
            'logo_path' => null,
            'template_data' => [
                'primaryColor' => '#3730a3',
                'secondaryColor' => '#4b5563',
                'backgroundColor' => '#dbeafe',
                'borderColor' => '#f59e0b',
                'titleText' => 'Certificate of Completion',
                'descriptionText' => 'This certificate is proudly presented to',
                'completionText' => 'for successfully completing the course',
                'footerText' => 'Authorized Certificate',
                'fontFamily' => 'serif',
            ],
            'is_active' => true,
        ]);
    }
}

Run with:

php artisan db:seed --class=CertificateTemplateSeeder

✅ Checklist

• Run migration
• Create storage link
• Set proper permissions
• Clear caches
• Access /admin/certificate-templates
• Create your first template
• Set template as active
• Test student certificate download
• Integrate with course completion flow

🎉 You're Ready!

Your certificate builder is now fully functional. Start creating beautiful certificates for your students!

For detailed documentation, see README.md.