# Auto-Discovery of Recurring Jobs

The ngauge-queues module can **automatically discover** recurring jobs without requiring explicit configuration in `params-local.php`.

## How It Works

1. On console application bootstrap, the module scans these directories:
   - `console/jobs/`
   - `frontend/jobs/`
   - `api/jobs/`
   - `backend/jobs/`
   - `common/jobs/`
   - `jobs/`

2. For each job file, it checks if the class has a public `$recurringJob` property

3. If found, it automatically registers the job with that configuration

4. Explicit params config takes precedence if specified

## Adding recurringJob to a Job

### Simple Form (Just Interval)

```php
namespace frontend\jobs;

use yii\base\BaseObject;

class CartReminders extends BaseObject implements \common\components\Queue\JobInterface
{
    /**
     * Declare as recurring: every 4 hours (14400 seconds)
     */
    public $recurringJob = 14400;
    
    public function execute($queue)
    {
        // Job logic...
    }
}
```

### Advanced Form (Full Config)

```php
class OrderSync extends BaseObject implements \common\components\Queue\JobInterface
{
    /**
     * Full configuration array
     */
    public $recurringJob = [
        'interval' => 900,              // 15 minutes
        'queue' => 'netsuitequeue',     // Use specific queue
        'name' => 'NetSuite Order Sync', // Display name
        'ttr' => 600,                   // Max runtime
        'enabled' => true,               // Enable/disable
        'checkDuplicates' => true,
        'maxRetries' => 5,
        'params' => [
            'force' => true,
        ],
    ];
    
    public $force = false;
    
    public function execute($queue)
    {
        // Logic...
    }
}
```

## Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `interval` | `int` | `3600` | Seconds between runs |
| `queue` | `string` | `'queue'` | Queue component |
| `name` | `string` | Auto | Human-readable name |
| `ttr` | `int` | `300` | Max execution time |
| `enabled` | `bool` | `true` | Enable/disable job |
| `checkDuplicates` | `bool` | `true` | Prevent duplicates |
| `maxRetries` | `int` | `3` | Retry attempts |
| `params` | `array` | `[]` | Constructor params |

## Examples

### Every 5 Minutes
```php
public $recurringJob = 300;
```

### Every Hour with Custom Queue
```php
public $recurringJob = [
    'interval' => 3600,
    'queue' => 'mailqueue',
];
```

### Disabled by Default (Can Enable in Params)
```php
public $recurringJob = [
    'interval' => 3600,
    'enabled' => false,
];
```

### With Constructor Parameters
```php
public $batchSize = 50;

public $recurringJob = [
    'interval' => 300,
    'params' => [
        'batchSize' => 100,
    ],
];
```

## Disabling Auto-Discovery

To scan jobs manually or only use explicit params config:

```php
'modules' => [
    'queues' => [
        'class' => PortalPeople\queues\Module::class,
        'scanJobsForRecurringConfig' => false,  // Disable scanning
    ],
],
```

## Custom Job Directories

To scan additional directories:

```php
'modules' => [
    'queues' => [
        'class' => PortalPeople\queues\Module::class,
        'jobDirectories' => [
            'console/jobs',
            'frontend/jobs',
            'custom/job/path',  // Add custom paths
        ],
    ],
],
```

## Overriding Scanned Config

Explicit config in `params-local.php` takes precedence:

```php
'settings' => [
    'queues' => [
        'recurring' => [
            [
                'class' => 'frontend\jobs\CartReminders',
                'interval' => 7200,  // Override the 14400 from property
                'enabled' => false,  // Disable
            ],
        ],
    ],
]
```

## Monitoring

Auto-discovered jobs appear in the queue dashboard at `/ngauge-queues` with their configured names. You can monitor status, pending counts, and execution.

## Best Practices

1. **Use simple form for basic jobs**
   ```php
   public $recurringJob = 3600; // 1 hour
   ```

2. **Use array form for complex configuration**
   ```php
   public $recurringJob = ['interval' => 900, 'queue' => 'special'];
   ```

3. **Document the interval in comments**
   ```php
   /**
    * Every 15 minutes (900 seconds)
    */
   public $recurringJob = 900;
   ```

4. **Set `enabled => false` for optional jobs**
   ```php
   public $recurringJob = ['interval' => 3600, 'enabled' => false];
   ```

5. **Override in params for environment-specific changes**
   ```php
   // Development: more frequent, Production: less frequent
   'recurring' => [['class' => '...', 'interval' => 300]];  // params-dev
   'recurring' => [['class' => '...', 'interval' => 3600]]; // params-prod
   ```

## See Also

- `examples/auto_discovered_recurring_job.php` - Simple example
- `examples/auto_discovered_full_config.php` - Full config example
- `RECURRING_JOBS.md` - Recurring jobs overview
- `README.md` - Module documentation
