README

A modern, feature-rich Laravel package for managing scheduled jobs with a beautiful React dashboard. Zero build required - everything is pre-built and ready to use!

✨ Features

🎯 Core Features

Modern React Dashboard - Beautiful UI built with shadcn/ui and Inertia.js
Dynamic Job Management - Create, edit, enable/disable scheduled jobs
Real-time Execution - Run jobs manually with live output
Comprehensive Logging - Track job execution history and errors
Job Details Modal - Click any job or log to view complete details
Cron Expression Builder - Visual cron builder with quick examples
Timezone Support - Set different timezones per job
Route Prefix Configuration - Customize dashboard URLs via config

🛠️ Technical Features

Zero Build Required - Pre-built assets, no npm/webpack needed
Laravel Integration - Seamless integration with Laravel's scheduler
Database Migrations - Automatic table creation
Service Provider - Easy Laravel integration
Error Handling - Robust error logging and display
Example Seeder - Demo jobs included
Test Suite - Comprehensive test coverage with GitHub Actions CI/CD

🚀 Installation

1. Install the Package

composer require sdkwala/laravel-dynamic-scheduler-ui

2. Publish Assets and Configuration

php artisan vendor:publish --provider="Sdkwala\Scheduler\SchedulerServiceProvider"

This will publish:

Configuration file: config/scheduler.php
Database migrations
Public assets (CSS/JS)

3. Run Migrations

php artisan migrate

This creates the required database tables:

scheduled_jobs - Stores job definitions
scheduled_job_logs - Stores execution logs

4. Access the Dashboard

Visit /scheduler in your browser. The dashboard is ready to use!

📖 Usage

Creating a Scheduled Job

Via Dashboard:
- Go to /scheduler
- Click "Create New Job"
- Fill in job details (name, command, schedule, timezone)
- Use the cron builder for easy schedule creation

Via Code:

use Sdkwala\Scheduler\Models\ScheduledJob;

ScheduledJob::create([
    'name' => 'Daily Backup',
    'command' => 'backup:run',
    'schedule' => '0 2 * * *', // Daily at 2 AM
    'timezone' => 'UTC',
    'is_active' => true,
]);

Managing Jobs

Enable/Disable: Toggle job status from the dashboard
Manual Execution: Click "Run" to execute jobs manually
Edit Jobs: Modify job settings anytime
View Logs: See execution history and errors
Job Details: Click any job row to view complete information

Viewing Logs

Dashboard Logs: See latest 5 logs per job on the main page
Full Log History: Visit /scheduler/logs for complete log history
Log Details: Click any log entry to view full output and errors

⚙️ Configuration

Route Prefix

Customize the dashboard URL by editing config/scheduler.php:

return [
    'route_prefix' => 'admin/scheduler', // Default: 'scheduler'
    // ... other config options
];

After changing the prefix:

php artisan route:clear

Available Timezones

The package includes a comprehensive list of timezones organized by region. You can customize this list by editing config/scheduler.php:

'available_timezones' => [
    'UTC' => 'UTC',
    'North America' => [
        'America/New_York' => 'Eastern Time',
        'America/Chicago' => 'Central Time',
        'America/Denver' => 'Mountain Time',
        'America/Los_Angeles' => 'Pacific Time',
        'America/Toronto' => 'Toronto',
        'America/Vancouver' => 'Vancouver',
    ],
    'Europe' => [
        'Europe/London' => 'London',
        'Europe/Paris' => 'Paris',
        'Europe/Berlin' => 'Berlin',
        'Europe/Moscow' => 'Moscow',
        'Europe/Dublin' => 'Dublin',
    ],
    'Asia' => [
        'Asia/Tokyo' => 'Tokyo',
        'Asia/Kolkata' => 'Kolkata (India)',
        'Asia/Dubai' => 'Dubai',
        'Asia/Shanghai' => 'Shanghai',
        'Asia/Singapore' => 'Singapore',
        'Asia/Bangkok' => 'Bangkok',
        'Asia/Seoul' => 'Seoul',
    ],
    'Australia & Pacific' => [
        'Australia/Sydney' => 'Sydney',
        'Australia/Melbourne' => 'Melbourne',
        'Pacific/Auckland' => 'Auckland',
    ],
    'Other' => [
        'Africa/Cairo' => 'Cairo',
        'Africa/Johannesburg' => 'Johannesburg',
        'America/Sao_Paulo' => 'São Paulo',
    ],
],

To add custom timezones:

Edit config/scheduler.php
Add your timezone to the appropriate region or create a new region
Use the format: 'Timezone/Identifier' => 'Display Name'

Cron Expression Validation

The package includes robust validation for cron expressions:

Format Validation: Ensures proper cron syntax (5 fields: minute hour day month weekday)
Runtime Validation: Uses the CronExpression library to validate expressions
Error Messages: Clear error messages for invalid expressions

Valid Examples:

* * * * * - Every minute
0 2 * * * - Daily at 2 AM
0 0 1 * * - Monthly on 1st
0 9 * * 1-5 - Weekdays at 9 AM
*/15 * * * * - Every 15 minutes

Invalid Examples:

* * * * - Missing field
60 * * * * - Invalid minute (0-59)
* 25 * * * - Invalid hour (0-23)
* * 32 * * - Invalid day (1-31)

Available Routes

GET /{prefix} - Main dashboard
GET /{prefix}/create - Create new job
POST /{prefix} - Store new job
GET /{prefix}/{id}/edit - Edit job
PUT /{prefix}/{id} - Update job
DELETE /{prefix}/{id} - Delete job
POST /{prefix}/{id}/run - Run job manually
GET /{prefix}/logs - View all logs

🔧 Integration with Laravel Scheduler

The package automatically integrates with Laravel's scheduler. Jobs created via the dashboard will be automatically registered with Laravel's Schedule facade.

Example: Custom Job Registration

// In your App\Console\Kernel.php
protected function schedule(Schedule $schedule)
{
    // Your existing scheduled jobs...
    
    // The package automatically adds dynamic jobs here
}

🎨 UI Features

Dashboard

Job Table: View all scheduled jobs with status, last run, next run
Quick Actions: Run, edit, enable/disable, delete jobs
Tab Navigation: Switch between dynamic jobs and Artisan schedule
Job Details Modal: Click any job row to view complete information

Logs Page

Complete History: View all job execution logs
Filter Options: Filter by job, status, date range
Log Details Modal: Click any log to view full output and errors

Create/Edit Forms

Cron Builder: Visual cron expression builder
Timezone Selection: Choose timezone per job
Validation: Real-time form validation
Quick Examples: Pre-built cron examples

🐛 Troubleshooting

Common Issues

1. Logs not appearing for scheduled runs:

Check Laravel logs for errors
Ensure your cron job is running: * * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1
Verify database migrations are run

2. Dashboard not loading:

Ensure assets are published: php artisan vendor:publish --provider="Sdkwala\Scheduler\SchedulerServiceProvider"
Clear route cache: php artisan route:clear

3. Jobs not executing:

Check if jobs are enabled in the dashboard
Verify cron expressions are valid
Check Laravel logs for errors

4. Modal not working:

Ensure you're using the latest version
Clear browser cache
Check browser console for JavaScript errors

Debug Commands

# Check if jobs are registered
php artisan schedule:list

# Test a specific job
php artisan schedule:test

# Clear all caches
php artisan config:clear && php artisan route:clear && php artisan view:clear

🧪 Testing

Local Testing

Run the comprehensive test suite:

# Install dependencies
composer install

# Run all tests
vendor/bin/phpunit

# Run specific test files
vendor/bin/phpunit tests/ScheduledJobTest.php
vendor/bin/phpunit tests/SchedulerControllerTest.php

# Run JavaScript tests
npm install
npm run build

Continuous Integration

This package includes GitHub Actions workflows that automatically run tests on:

Push to main branch
Pull requests to main branch

The CI pipeline tests:

PHP compatibility (8.1, 8.2, 8.3)
Laravel compatibility (10., 11., 12.*)
JavaScript build process
Security vulnerabilities
Code quality checks

For detailed testing information, see TESTING.md.

📚 Development

For development, customization, and contribution instructions, see DEVELOPMENT.md.

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📄 License

This package is open-sourced software licensed under the MIT license.

🔗 Links

GitHub: https://github.com/sdkwala/laravel-dynamic-scheduler-ui
Packagist: https://packagist.org/packages/sdkwala/laravel-dynamic-scheduler-ui
Issues: https://github.com/sdkwala/laravel-dynamic-scheduler-ui/issues

Built with ❤️ using Laravel, React, Inertia.js, and shadcn/ui

sdkwala / laravel-dynamic-scheduler-ui

Maintainers

Details