Here's a comprehensive, professional README.md file for your Laravel Smart Scheduler package with detailed documentation, examples, and visual sections:

# Laravel Smart Scheduler 🚀

[![Latest Version](https://img.shields.io/packagist/v/sakshsky/laravel-smart-scheduler.svg?style=flat-square)](https://packagist.org/packages/sakshsky/laravel-smart-scheduler)
[![Total Downloads](https://img.shields.io/packagist/dt/sakshsky/laravel-smart-scheduler.svg?style=flat-square)](https://packagist.org/packages/sakshsky/laravel-smart-scheduler)
[![License](https://img.shields.io/packagist/l/sakshsky/laravel-smart-scheduler.svg?style=flat-square)](https://github.com/sakshsky/laravel-smart-scheduler/blob/main/LICENSE.md)

A beautiful, intuitive interface for managing Laravel task scheduling with real-time previews, visual cron builder, and one-click task execution.

![Scheduler Dashboard](https://via.placeholder.com/800x400.png?text=Scheduler+Dashboard+Preview)
*(Screenshot placeholder - replace with actual screenshot)*

## Features ✨

🎛️ **Visual Cron Expression Builder** - Create schedules without remembering cron syntax
⚡ **Real-time Preview** - See next 5 run times before saving
📝 **Code Generator** - Get ready-to-use Laravel scheduler code
📊 **Task Monitoring** - View execution history and outputs
🔔 **Notifications** - Get alerts for failed tasks (Email/Slack)
🕒 **Timezone Support** - Set per-task timezones
🛡️ **Overlap Protection** - Built-in `withoutOverlapping()` for all tasks

## Installation 📦

1. Require the package via Composer:

```bash
composer require sakshsky/laravel-smart-scheduler

2. Publish assets and configuration:

php artisan vendor:publish --provider="Sakshsky\SmartScheduler\Providers\SmartSchedulerServiceProvider"

3. Run migrations:

php artisan migrate

Basic Usage 🏁

Accessing the Dashboard

Navigate to /scheduler (configurable in config file) after installation.

Creating Your First Task

1. Click "Add New Task"
2. Fill in task details:
   • Name: "Send Daily Reports"
   • Command: emails:send --type=daily
   • Frequency: Daily at 9:00 AM
3. Click "Save"

(Screenshot placeholder)

Advanced Examples 🧠

1. Complex Cron Example

Create a task that runs at 15 minutes past every 4 hours on weekdays:

// Generated code from the visual builder
$schedule->command('reports:generate')
    ->name('Weekday Reports')
    ->cron('15 */4 * * 1-5')
    ->timezone('America/New_York')
    ->withoutOverlapping()
    ->appendOutputTo(storage_path('logs/reports.log'));

2. Task with Notifications

Configure in config/smart-scheduler.php:

'notifications' => [
    'mail' => [
        'enabled' => true,
        'to' => '[email protected]',
    ],
    'slack' => [
        'enabled' => true,
        'webhook_url' => env('SLACK_WEBHOOK_URL'),
    ],
],

3. API Usage

The package provides an API to manage tasks programmatically:

use Sakshsky\SmartScheduler\Models\ScheduledTask;

// Create a new task
ScheduledTask::create([
    'name' => 'Database Backup',
    'command' => 'backup:run',
    'cron_expression' => '0 2 * * *',
    'timezone' => 'UTC',
    'description' => 'Nightly database backup'
]);

// Disable a task
$task = ScheduledTask::find(1);
$task->update(['enabled' => false]);

Configuration ⚙️

After publishing the config file (config/smart-scheduler.php), you can customize:

return [
    'route_prefix' => 'scheduler', // Change dashboard URL
    'middleware' => ['web', 'auth'], // Authentication middleware
    'timezone' => env('APP_TIMEZONE', 'UTC'), // Default timezone
    
    // Enable/disable features
    'features' => [
        'builder' => true,
        'task_management' => true,
        'notifications' => true,
    ],
    
    // Notification channels
    'notifications' => [
        'mail' => [
            'enabled' => true,
            'to' => env('ADMIN_EMAIL'),
        ],
        'slack' => [
            'enabled' => false,
            'webhook_url' => env('SLACK_WEBHOOK_URL'),
        ],
    ],
];

Security Considerations 🔒

By default, the scheduler dashboard is protected by:

• auth middleware (requires login)
• Route prefix (change from default 'scheduler' if needed)

For production:

1. Consider adding additional middleware (e.g., can:admin)
2. Restrict access to specific IPs if needed
3. Regularly update the package

Troubleshooting 🛠️

Issue: Tasks not running
✅ Check php artisan schedule:list to verify tasks are registered
✅ Ensure your cron job is set up correctly on the server:

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

Issue: Timezone not respected
✅ Verify APP_TIMEZONE in your .env
✅ Check individual task timezone settings

Contributing 🤝

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License 📄

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

Support ❤️

If you find this package useful, please consider:

• ⭐ Starring the GitHub repo
• 🐛 Reporting issues
• 💡 Suggesting new features

*Created with ❤️ by sakshsky