> For the complete documentation index, see [llms.txt](https://quantumphp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumphp.gitbook.io/docs/packages/cron/overview.md).

# Overview

Cron gives you a file-based task runner for scheduled jobs inside a Quantum application.

Use it when you want to define application tasks as PHP files, check whether they are due, and prevent the same task from running twice at the same time.

## What the package provides

* `Quantum\Cron\CronManager` to discover and run tasks
* `Quantum\Cron\CronTask` for explicit task objects
* `Quantum\Cron\Schedule` for fluent schedule creation
* `Quantum\Cron\CronLock` for file-based concurrency protection
* helpers: `cron_manager()`, `cron_task()`, `schedule()`, and `cron_config()`

## Quick example

Create a task file in your app cron directory:

```php
<?php

return schedule('reports:daily')
    ->dailyAt('06:30')
    ->call(function (): void {
        // send reports
    })
    ->build();
```

Run due tasks:

```php
$stats = cron_manager()->runDueTasks();
```

## How task loading works

By default, `CronManager` looks for `*.php` files in `base_dir()/cron`.

Each file must return one of these:

* a `CronTaskInterface` implementation
* an array with `name`, `expression`, and `callback`

If the default `cron` directory does not exist, the manager quietly treats that as "no tasks". If you pass a custom directory and it does not exist, the manager throws `CronException`.

## Important behavior

* task names are the lookup key; if multiple files return the same name, the later loaded task replaces the earlier one
* `runDueTasks()` catches task callback failures, logs them, increments `failed`, and continues with other due tasks
* `runTaskByName()` also uses the same internal runner, so task callback failures are logged instead of re-thrown
* locks are skipped only when you run in force mode
* `cron_manager()` returns a new manager each time; stats are not shared across helper calls

## Configuration defaults

`cron_config()` lazily loads `config/cron` once per process if it is available.

The package has working defaults even when that config file is missing:

* task directory: `base_dir()/cron`
* lock directory: `base_dir()/runtime/cron/locks`
* maximum lock age: `86400` seconds


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://quantumphp.gitbook.io/docs/packages/cron/overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.