CRON Translator

https://github.com/lorisleiva/cron-translator
Admin
CRON Translator converts CRON expressions into human-readable descriptions with support for multiple...
Tokens:58,486
Snippets:363
Trust Score:9.5
License:MIT
Update:6 days ago
Show doc for...
Tokens:
Raw
### lang method usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/CronExpression.md

Example of using the lang method with a CronExpression instance and English translations. Demonstrates placeholder substitution and pluralization.

```php
use Lorisleiva\CronTranslator\CronExpression;
use Lorisleiva\CronTranslator\LanguageLoader;

$expression = new CronExpression(
    '*/2 * * * *',
    (new LanguageLoader('en'))->translations
);

echo $expression->lang('minutes.increment', ['increment' => 2]); // every 2 minutes
echo $expression->lang('minutes.times_per_increment', ['times' => 'twice', 'increment' => 4]); // twice every 4 minutes
echo $expression->lang('hours.once_at_time', ['time' => '10:30pm']); // at 10:30pm
```

--------------------------------

### getTimes usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/Field.md

Example of using getTimes with a CronExpression and MinutesField. Outputs 'twice' for the given expression.

```php
use Lorisleiva\CronTranslator\CronExpression;
use Lorisleiva\CronTranslator\LanguageLoader;
use Lorisleiva\CronTranslator\MinutesField;

$expression = new CronExpression('0,30 * * * *', (new LanguageLoader('en'))->translations);
echo (new MinutesField($expression, '0,30'))->getTimes(); // twice
```

--------------------------------

### Example: Creating a MinutesField

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/Field.md

Shows how to instantiate a MinutesField with a CronExpression and a raw field, then access the parsed type. The example uses '0 12 1 1 *' and outputs 'Once'.

```php
use Lorisleiva\CronTranslator\CronExpression;
use Lorisleiva\CronTranslator\MinutesField;

$expression = new CronExpression('0 12 1 1 *');
$minute = new MinutesField($expression, '0');
echo $minute->type->type; // Once
```

--------------------------------

### Combined native usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/Field.md

Example showing how to use CronExpression, HoursField, and LanguageLoader together. It creates an expression for '0 1-5 * * *', then demonstrates getCount, getTimes, translate, and hasType methods.

```php
use Lorisleiva\CronTranslator\CronExpression;
use Lorisleiva\CronTranslator\HoursField;
use Lorisleiva\CronTranslator\LanguageLoader;

$expression = new CronExpression('0 1-5 * * *', (new LanguageLoader('en'))->translations);
$hour = new HoursField($expression, '1-5');

echo $hour->getCount();                    // 5
echo $hour->getTimes();                    // 5 times
echo $hour->translate();                   // 5 times a day
echo $hour->hasType('Multiple');           // true
```

--------------------------------

### mbUcfirst example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/CronTranslator.md

Example usage of mbUcfirst. Echoes the result of uppercasing the first character of 'chaque minute', producing 'Chaque minute'.

```php
echo MyTranslator::mbUcfirst('chaque minute'); // Chaque minute
```

--------------------------------

### Install CRON Translator via Composer

Source: https://github.com/lorisleiva/cron-translator/blob/main/README.md

Use this command to add the package to your project dependencies.

```sh
composer require lorisleiva/cron-translator
```

--------------------------------

### translateOnce usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/DaysOfMonthField.md

Example of using CronTranslator::translate with once expressions. Shows output for '0 0 1 1 *', '0 0 1 * *', and '0 0 2 1 0'.

```php
use Lorisleiva\CronTranslator\CronTranslator;

echo CronTranslator::translate('0 0 1 1 *');    // Every year on January the 1st at 12:00am
echo CronTranslator::translate('0 0 1 * *');    // The 1st of every month at 12:00am
echo CronTranslator::translate('0 0 2 1 0');    // On Sundays on January the 2nd at 12:00am
```

--------------------------------

### translateOnce example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/MonthsField.md

Shows output for cron expressions with a single month.

```php
use Lorisleiva\CronTranslator\CronTranslator;

echo CronTranslator::translate('0 0 1 1 *');  // Every year on January the 1st at 12:00am
echo CronTranslator::translate('* * * 4 1');  // Every minute on Mondays on April
echo CronTranslator::translate('* * * 1 *');  // Every minute on January
```

--------------------------------

### CronTranslator usage examples

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/DaysOfMonthField.md

Examples of translating cron expressions with the CronTranslator class, showing outputs for different weekday configurations.

```php
use Lorisleiva\CronTranslator\CronTranslator;

echo CronTranslator::translate('* * * * 0');    // Every minute on Sundays
echo CronTranslator::translate('0 9 * * 1,4');  // Every Monday and Thursday at 9:00am
echo CronTranslator::translate('0 0 * * *');   // Every day at 12:00am
```

--------------------------------

### getFields() usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/CronExpression.md

Creates a CronExpression for '0 0 1 1 *' and iterates over the fields, printing each field's position, value (or '*'), and type.

```php
use Lorisleiva\CronTranslator\CronExpression;

$fields = (new CronExpression('0 0 1 1 *'))->getFields();

foreach ($fields as $field) {
    // $field: MinutesField, HoursField, DaysOfMonthField, MonthsField, DaysOfWeekField
    printf('%d: %s (%s)%s', $field->position, $field->getValue() ?? '*', $field->type->type, PHP_EOL);
}
```

--------------------------------

### translateOnce example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/DaysOfWeekField.md

Example usage of CronTranslator::translate with a single day of the week.

```php
use Lorisleiva\CronTranslator\CronTranslator;

echo CronTranslator::translate('0 16 * * 1');  // Every Monday at 4:00pm
echo CronTranslator::translate('0 0 * * 0');   // Every Sunday at 12:00am
echo CronTranslator::translate('0 0 1 1 0');  // On Sundays on January the 1st at 12:00am
```

--------------------------------

### translateOnce example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/HoursField.md

Example usage of CronTranslator::translate with specific times. Outputs English translations for different cron expressions.

```php
use Lorisleiva\CronTranslator\CronTranslator;

echo CronTranslator::translate('30 22 * * *');  // Every day at 10:30pm
echo CronTranslator::translate('0 12 * * *');    // Every day at 12:00pm
echo CronTranslator::translate('15 9 * * 1');    // Every Monday at 9:15am
```

--------------------------------

### langCountable() usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/CronExpression.md

Demonstrates langCountable with English translations, showing outputs for 'times', 'ordinals', and 'days' with a case argument (ignored for English).

```php
use Lorisleiva\CronTranslator\CronExpression;

$expression = new CronExpression('* * * * *', (new LanguageLoader('en'))->translations);

echo $expression->langCountable('times', 1);      // once
echo $expression->langCountable('times', 2);      // twice
echo $expression->langCountable('times', 5);      // 5 times
echo $expression->langCountable('ordinals', 2);   // 2nd
echo $expression->langCountable('days', 3, 'dative'); // Wednesday (en ignores case)
```

--------------------------------

### getIncrement() usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/Field.md

Creates a MinutesField with value '*/2' and prints its getIncrement() result, which is 2.

```php
echo (new MinutesField($expression, '*/2'))->getIncrement(); // 2
```

--------------------------------

### Example — loading a partial schema

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/LanguageLoader.md

Shows how to call loadTranslationFile('days') from a subclass. The returned array is used to access the nominative form for day 1.

```php
use Lorisleiva\CronTranslator\LanguageLoader;

class PartialLoader extends LanguageLoader
{
    public function loadOnlyDays(): array
    {
        return $this->loadTranslationFile('days');
    }
}

$days = (new PartialLoader('ru'))->loadOnlyDays();
echo $days['nominative'][1]; // в понедельник
```

--------------------------------

### translateMultiple example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/DaysOfWeekField.md

Example usage of CronTranslator::translate with multiple days of the week.

```php
use Lorisleiva\CronTranslator\CronTranslator;

echo CronTranslator::translate('0 9 * * 1,3,5'); // Every Monday, Wednesday and Friday at 9:00am
echo CronTranslator::translate('0 1 5 * 1-4');    // The 5th of every month 4 days a week at 1:00am
```

--------------------------------

### translateMultiple example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/HoursField.md

Example usage of CronTranslator::translate with hour ranges. Outputs English translations for different cron expressions.

```php
use Lorisleiva\CronTranslator\CronTranslator;

echo CronTranslator::translate('0 1-5 * * *');  // 5 times a day
echo CronTranslator::translate('* 1-20 * * *'); // Every minute 20 hours a day
echo CronTranslator::translate('0,30 1-5 * * *'); // Twice an hour 5 hours a day
```

--------------------------------

### getCount() usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/Field.md

Creates a DaysOfMonthField with value '1-5' and prints its getCount() result, which is 5.

```php
echo (new DaysOfMonthField($expression, '1-5'))->getCount(); // 5
```

--------------------------------

### translateMultiple example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/MonthsField.md

Shows output for cron expressions with multiple months.

```php
use Lorisleiva\CronTranslator\CronTranslator;

echo CronTranslator::translate('0 1 5 5,6 *');    // 2 months a year on the 5th at 1:00am
echo CronTranslator::translate('0 1 1-5 5,6 *');   // 5 days a month 2 months a year at 1:00am
```

--------------------------------

### CronType::parse() classification example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/CronType.md

Shows the resulting type for various cron tokens. Demonstrates rule precedence: '*' becomes Every, fixed numbers become Once, lists become Multiple, ranges become Multiple or Once, and increments become Increment.

```php
use Lorisleiva\CronTranslator\CronType;

CronType::parse('*')->type;       // Every
CronType::parse('0')->type;       // Once
CronType::parse('1,2,5')->type;   // Multiple (count 3)
CronType::parse('1-5')->type;     // Multiple (count 5)
CronType::parse('8-8')->type;     // Once (value 8)
CronType::parse('*/2')->type;     // Increment (increment 2)
CronType::parse('1-3/5')->type;   // Increment (increment 5, count 3)
```

--------------------------------

### format example with valid month and range error

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/MonthsField.md

Shows successful formatting and the exception message for an invalid month.

```php
use Lorisleiva\CronTranslator\CronExpression;
use Lorisleiva\CronTranslator\MonthsField;
use Lorisleiva\CronTranslator\LanguageLoader;
use Lorisleiva\CronTranslator\CronParsingException;

$translations = (new LanguageLoader('en'))->translations;

$ok = new CronExpression('0 0 1 1 *', $translations);
echo (new MonthsField($ok, '1'))->format(); // January

try {
    (new MonthsField(new CronExpression('* * * 13 *', $translations), '13'))->format();
} catch (CronParsingException $e) {
    echo $e->getMessage(); // Failed to parse the following CRON expression: * * * 13 *
}

// Same failure via the facade:
use Lorisleiva\CronTranslator\CronTranslator;
try {
    CronTranslator::translate('* * * 13 *');
} catch (CronParsingException $e) {
    // caught here too (wrapped with the same message)
}
```

--------------------------------

### hasType() usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/Field.md

Checks if the minute field has type 'Once' or 'Every' and prints a message accordingly.

```php
if ($expression->minute->hasType('Once', 'Every')) {
    echo 'minute is fixed or wildcard';
}
```

--------------------------------

### format() usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/MinutesField.md

Shows zero-padding for minute values and how HoursField::format() uses it to build wall-clock times like `10:30pm`.

```php
use Lorisleiva\CronTranslator\CronExpression;
use Lorisleiva\CronTranslator\HoursField;
use Lorisleiva\CronTranslator\MinutesField;

$expression = new CronExpression('30 22 * * *', (new LanguageLoader('en'))->translations);

echo (new MinutesField($expression, '30'))->format(); // 30
echo (new MinutesField($expression, '0'))->format();  // 00
echo (new HoursField($expression, '22'))->format($expression->minute); // 10:30pm
```

--------------------------------

### Example usage of DaysOfMonthField::format()

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/DaysOfMonthField.md

Shows how to instantiate CronExpression with a LanguageLoader and DaysOfMonthField, then call format() with and without the 'dative' case. Also demonstrates CronTranslator::translate() for a full translation.

```php
use Lorisleiva\CronTranslator\CronExpression;
use Lorisleiva\CronTranslator\DaysOfMonthField;
use Lorisleiva\CronTranslator\LanguageLoader;

$expression = new CronExpression('0 0 22 4 1', (new LanguageLoader('en'))->translations);
echo (new DaysOfMonthField($expression, '22'))->format();        // 22nd
echo (new DaysOfMonthField($expression, '22'))->format('dative'); // 22nd (en ignores case)

use Lorisleiva\CronTranslator\CronTranslator;
echo CronTranslator::translate('10 15 22 4 1'); // On Mondays on April the 22nd at 3:10pm
```

--------------------------------

### Example — getTranslationDirectory

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/LanguageLoader.md

Shows how to call getTranslationDirectory() from a subclass. For locale 'zh-TW' it returns the library's src/lang/zh-TW directory.

```php
use Lorisleiva\CronTranslator\LanguageLoader;

class DirLoader extends LanguageLoader
{
    public function path(): string
    {
        return $this->getTranslationDirectory();
    }
}

echo (new DirLoader('zh-TW'))->path(); // .../src/lang/zh-TW
```

--------------------------------

### CronType::once() usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/CronType.md

Creates a CronType for the fixed value 22 and accesses its properties. Outputs 'Once' and '22'.

```php
use Lorisleiva\CronTranslator\CronType;

$type = CronType::once(22);
echo $type->type;  // Once
echo $type->value; // 22
```

--------------------------------

### translateIncrement example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/DaysOfWeekField.md

Example usage of CronTranslator::translate with a cron expression that uses an increment for days of the week.

```php
use Lorisleiva\CronTranslator\CronTranslator;

echo CronTranslator::translate('0 9 * * */2'); // Every day every 2 days of the week at 9:00am
```

--------------------------------

### Example: Translating fields with different types

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/Field.md

Shows how to translate a minute field with an increment type and an hour field with an 'every' type. The minute field outputs 'every 2 minutes', while the hour field renders only when kept in the expression.

```php
use Lorisleiva\CronTranslator\CronExpression;
use Lorisleiva\CronTranslator\HoursField;
use Lorisleiva\CronTranslator\LanguageLoader;
use Lorisleiva\CronTranslator\MinutesField;

$expression = new CronExpression('*/2 * * * *', (new LanguageLoader('en'))->translations);

$minute = new MinutesField($expression, '*/2');  // type = Increment
echo $minute->translate();                       // every 2 minutes

$hour = new HoursField($expression, '*');        // translateEvery exists
$hour->translate();                              // (rendered when kept, e.g. '0 * */2 * *' -> 'Once an hour')
```

--------------------------------

### hasType() usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/CronType.md

Parses a cron expression and checks type membership. The first call returns `true` for 'Increment', the second returns `false` for 'Every', 'Multiple', and 'Once'.

```php
use Lorisleiva\CronTranslator\CronType;

$type = CronType::parse('*/2');
$type->hasType('Increment');                    // true
$type->hasType('Every', 'Multiple', 'Once');    // false
```

--------------------------------

### translateIncrement usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/DaysOfMonthField.md

Example of using CronTranslator::translate with increment expressions. Shows output for '0 0 */2 * *' and '0 * */2 * *'.

```php
use Lorisleiva\CronTranslator\CronTranslator;

echo CronTranslator::translate('0 0 */2 * *'); // Every 2 days at 12:00am
// Full: "Once an hour every 2 days" for '0 * */2 * *'
echo CronTranslator::translate('0 * */2 * *'); // Once an hour every 2 days
```

--------------------------------

### pluralize usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/CronExpression.md

Shows how to use pluralize with Russian and English templates. Outputs declined forms for counts 1, 2, and 5, and returns the input unchanged when no blocks are present.

```php
use Lorisleiva\CronTranslator\CronExpression;

$expression = new CronExpression('*/5 * * * *');

echo $expression->pluralize('1 {день|дня|дней} 2 {час|часа|часов} 5 {минута|минуты|минут}');
// 1 день 2 часа 5 минут

echo $expression->pluralize('1 {day|days} 2 {hour|hours} 5 {minute|minutes}');
// 1 day 2 hours 5 minutes

echo $expression->pluralize('no blocks here'); // no blocks here
```

--------------------------------

### getValue() usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/Field.md

Creates an HoursField with value '22' and prints its getValue() result, which is 22.

```php
echo (new HoursField($expression, '22'))->getValue(); // 22
```

--------------------------------

### CronExpression usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/CronExpression.md

Creates a CronExpression with English translations and formats individual fields. Outputs '00', '12:00pm', and 'January' for the given cron expression.

```php
use Lorisleiva\CronTranslator\CronExpression;
use Lorisleiva\CronTranslator\LanguageLoader;

$expression = new CronExpression(
    '0 12 1 1 *',
    (new LanguageLoader('en'))->translations
);

echo $expression->minute->format();   // 00
echo $expression->hour->format($expression->minute); // 12:00pm
echo $expression->month->format();   // January
```

--------------------------------

### translateMultiple usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/DaysOfMonthField.md

Example of using CronTranslator::translate with multiple day expressions. Shows output for '0 1 1-5 * *' and '0 1 1,2,3 * *'.

```php
use Lorisleiva\CronTranslator\CronTranslator;

echo CronTranslator::translate('0 1 1-5 * *');  // 5 days a month at 1:00am
echo CronTranslator::translate('0 1 1,2,3 * *'); // 3 days a month at 1:00am
```

--------------------------------

### translateEvery() usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/MinutesField.md

Constructs a MinutesField for the `* * * * *` expression and prints the translation. The full pipeline via CronTranslator::translate outputs `Every minute`.

```php
use Lorisleiva\CronTranslator\CronExpression;
use Lorisleiva\CronTranslator\CronTranslator;
use Lorisleiva\CronTranslator\MinutesField;

$expression = new CronExpression('* * * * *', (new LanguageLoader('en'))->translations);
echo (new MinutesField($expression, '*'))->translate(); // every minute
// Full pipeline:
echo CronTranslator::translate('* * * * *'); // Every minute
```

--------------------------------

### CronType::every() usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/CronType.md

Creates a `CronType` via `CronType::every()` and outputs its properties. The `type` is 'Every', while `value`, `count`, and `increment` are all `NULL`.

```php
use Lorisleiva\CronTranslator\CronType;

$type = CronType::every();
echo $type->type; // Every
var_dump($type->value, $type->count, $type->increment); // NULL, NULL, NULL
```

--------------------------------

### CronType::increment() usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/CronType.md

Creates `CronType` instances with `CronType::increment()` and prints their `type` and `count` properties. For `increment(2)`, `count` is `1`; for `increment(5, 3)`, `count` is `3`.

```php
use Lorisleiva\CronTranslator\CronType;

echo CronType::increment(2)->type;            // Increment
echo CronType::increment(2)->count;           // 1
echo CronType::increment(5, 3)->count;        // 3
```

--------------------------------

### Example: valid value and range error

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/DaysOfWeekField.md

Example usage of format() with a valid value (0) and an invalid value (8). The valid call returns 'Sunday' (case ignored in English). The invalid call throws CronParsingException with the raw expression in the message.

```php
use Lorisleiva\CronTranslator\CronExpression;
use Lorisleiva\CronTranslator\DaysOfWeekField;
use Lorisleiva\CronTranslator\LanguageLoader;
use Lorisleiva\CronTranslator\CronParsingException;

$translations = (new LanguageLoader('en'))->translations;

$ok = new CronExpression('0 0 * * 0', $translations);
echo (new DaysOfWeekField($ok, '0'))->format();        // Sunday
echo (new DaysOfWeekField($ok, '0'))->format('dative'); // Sunday (en ignores case)

try {
    (new DaysOfWeekField(new CronExpression('* * * * 8', $translations), '8'))->format();
} catch (CronParsingException $e) {
    echo $e->getMessage(); // Failed to parse the following CRON expression: * * * * 8
}
```

--------------------------------

### Example usage of LanguageLoader

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/LanguageLoader.md

Loads French translations and accesses locale and translation arrays. Demonstrates accessing ordinal and field translations.

```php
use Lorisleiva\CronTranslator\LanguageLoader;

$loader = new LanguageLoader('fr');
echo $loader->locale;                                              // fr
echo $loader->translations['times'][1];                            // une fois
echo $loader->translations['fields']['minutes']['every'];          // chaque minute
```

--------------------------------

### CronType::multiple() usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/CronType.md

Creates a `CronType` via `CronType::multiple(2)` and prints its `count` property, which is `2`.

```php
use Lorisleiva\CronTranslator\CronType;

echo CronType::multiple(2)->count; // 2
```

--------------------------------

### translateEvery example with CronTranslator

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/HoursField.md

Shows usage of CronTranslator::translate with wildcard and fixed minute expressions. The first outputs 'Every minute' because the minutes field wins, the second outputs 'Once an hour' because the minute is Once.

```php
use Lorisleiva\CronTranslator\CronTranslator;

echo CronTranslator::translate('* * * * *'); // Every minute     (minutes field wins)
echo CronTranslator::translate('0 * * * *'); // Once an hour     (minute is Once)
```

--------------------------------

### Example usage of HoursField::format with 12-hour and 24-hour modes

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/HoursField.md

Demonstrates formatting hours in both 12-hour and 24-hour modes, including minute handling and facade translation.

```php
use Lorisleiva\CronTranslator\CronExpression;
use Lorisleiva\CronTranslator\HoursField;
use Lorisleiva\CronTranslator\LanguageLoader;

$translations = (new LanguageLoader('en'))->translations;

$expr12 = new CronExpression('30 18 * * *', $translations, false);
$expr24 = new CronExpression('30 18 * * *', $translations, true);

echo (new HoursField($expr12, '18'))->format($expr12->minute); // 6:30pm
echo (new HoursField($expr24, '18'))->format($expr24->minute); // 18:30
echo (new HoursField($expr12, '12'))->format();                  // 12pm

// Compare directly via the facade:
use Lorisleiva\CronTranslator\CronTranslator;
echo CronTranslator::translate('30 18 * * *', 'en', false); // Every day at 6:30pm
echo CronTranslator::translate('30 18 * * *', 'en', true);  // Every day at 18:30
```

--------------------------------

### translateIncrement() usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/MinutesField.md

Uses the `1-3/5 * * * *` expression to show the `times_per_increment` template, producing `3 times every 5 minutes`.

```php
use Lorisleiva\CronTranslator\CronExpression;
use Lorisleiva\CronTranslator\MinutesField;

$expression = new CronExpression('1-3/5 * * * *', (new LanguageLoader('en'))->translations);
echo (new MinutesField($expression, '1-3/5'))->translate(); // 3 times every 5 minutes
// CronTranslator::translate('1-3/5 * * * *') => 3 times every 5 minutes
```

--------------------------------

### Subclass usage of ensureLocaleExists

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/LanguageLoader.md

Example of a subclass that explicitly enforces the fallback in its constructor. Instantiating with 'zz' falls back to 'en' and the locale property becomes 'en'.

```php
use Lorisleiva\CronTranslator\LanguageLoader;

class StrictLoader extends LanguageLoader
{
    public function __construct(string $locale)
    {
        parent::__construct($locale);
        // Default constructor does not fall back; enforce it explicitly:
        $this->ensureLocaleExists('en');
    }
}

$loader = new StrictLoader('zz'); // falls back to 'en'
echo $loader->locale;             // en
```

--------------------------------

### translateIncrement example with CronTranslator

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/HoursField.md

Shows usage of CronTranslator::translate with various increment expressions. Each line demonstrates a different branch: 'Once every 2 hours', 'Twice every 5 hours', 'Every minute 2 hours out of 5', 'Every minute of every 2 hours', and 'Once every 3 hours'.

```php
use Lorisleiva\CronTranslator\CronTranslator;

echo CronTranslator::translate('0 */2 * * *');     // Once every 2 hours
echo CronTranslator::translate('0 1,2/5 * * *');   // Twice every 5 hours
echo CronTranslator::translate('* 1,2/5 * * *');   // Every minute 2 hours out of 5
echo CronTranslator::translate('* */2 * * *');      // Every minute of every 2 hours
echo CronTranslator::translate('0 1/3 * * *');      // Once every 3 hours
```

--------------------------------

### translateEvery usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/MonthsField.md

Shows how to translate cron expressions that trigger the translateEvery method. The first expression includes a day-of-month value, producing 'Every minute on the 1st of every month'. The second expression has a month value, producing 'Every minute on January'.

```php
use Lorisleiva\CronTranslator\CronTranslator;

echo CronTranslator::translate('* * 1 * *'); // Every minute on the 1st of every month
echo CronTranslator::translate('* * * 1 *'); // Every minute on January
```

--------------------------------

### translateMultiple() usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/MinutesField.md

Uses the `0,30 * * * *` expression to show the `minutes.multiple` template, producing `twice an hour` (and `Twice an hour` via the full pipeline).

```php
use Lorisleiva\CronTranslator\CronExpression;
use Lorisleiva\CronTranslator\CronTranslator;
use Lorisleiva\CronTranslator\MinutesField;

$expression = new CronExpression('0,30 * * * *', (new LanguageLoader('en'))->translations);
echo (new MinutesField($expression, '0,30'))->translate(); // twice an hour
echo CronTranslator::translate('0,30 * * * *');             // Twice an hour
```

--------------------------------

### translateIncrement usage example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/MonthsField.md

Shows how to translate cron expressions that trigger the translateIncrement method. The first expression uses a simple increment, producing 'Every day every 4 months at 12:00am'. The second expression uses a range with increment, producing 'Every day 3 months out of 3 at 12:00am' due to the verbatim source behavior.

```php
use Lorisleiva\CronTranslator\CronTranslator;

echo CronTranslator::translate('0 0 * */4 *');   // Every day every 4 months at 12:00am
echo CronTranslator::translate('0 0 * 1-3/4 *'); // Every day 3 months out of 3 at 12:00am (verbatim source behavior)
```

--------------------------------

### CronType::parse() error handling example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/CronType.md

Catches CronParsingException thrown for invalid tokens like '1,2-3'. The exception message embeds the single token, not the full cron string.

```php
use Lorisleiva\CronTranslator\CronType;
use Lorisleiva\CronTranslator\CronParsingException;

try {
    CronType::parse('1,2-3');
} catch (CronParsingException $e) {
    // "Failed to parse the following CRON expression: 1,2-3"
    echo $e->getMessage();
}
```

--------------------------------

### Catching TranslationFileMissingException

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/errors.md

Example of catching the exception when constructing LanguageLoader. The try block throws if a required file like times.php is missing; the catch prints the message.

```php
use Lorisleiva\CronTranslator\LanguageLoader;
use Lorisleiva\CronTranslator\TranslationFileMissingException;

try {
    $loader = new LanguageLoader('en'); // would throw if e.g. src/lang/en/times.php is missing
} catch (TranslationFileMissingException $e) {
    echo $e->getMessage();
    // "Failed to load the translation file [times] from the locale [en]."
}
```

--------------------------------

### isDiscreteList example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/DaysOfWeekField.md

Example usage of isDiscreteList with a CronExpression. Shows true for '1,4' and false for '1-4'.

```php
use Lorisleiva\CronTranslator\CronExpression;
use Lorisleiva\CronTranslator\DaysOfWeekField;
use Lorisleiva\CronTranslator\LanguageLoader;

$expression = new CronExpression('0 9 * * 1,4', (new LanguageLoader('en'))->translations);

echo (new DaysOfWeekField($expression, '1,4'))->isDiscreteList(); // true
echo (new DaysOfWeekField($expression, '1-4'))->isDiscreteList(); // false
```

--------------------------------

### Basic usage of CronTranslator::translate()

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/index.md

Use the static facade to convert a cron expression into a human-readable sentence. The first argument is the cron string, the second is an optional locale (defaults to 'en'), and the third enables 24-hour time format. The examples show English and French outputs.

```php
use Lorisleiva\CronTranslator\CronTranslator;

CronTranslator::translate('30 22 * * *');       // => Every day at 10:30pm
CronTranslator::translate('30 18 * * *', 'fr'); // => Chaque jour à 6:30pm
CronTranslator::translate('30 18 * * *', 'fr', true); // => Chaque jour à 18:30
```

--------------------------------

### getFormattedDiscreteList example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/DaysOfWeekField.md

Example usage of getFormattedDiscreteList with a CronExpression and CronTranslator. Shows localized output for '6,0' as 'Saturday and Sunday'.

```php
use Lorisleiva\CronTranslator\CronExpression;
use Lorisleiva\CronTranslator\CronTranslator;
use Lorisleiva\CronTranslator\DaysOfWeekField;
use Lorisleiva\CronTranslator\LanguageLoader;

$expression = new CronExpression('0 9 * * 6,0', (new LanguageLoader('en'))->translations);
echo (new DaysOfWeekField($expression, '6,0'))->getFormattedDiscreteList(); // Saturday and Sunday

echo CronTranslator::translate('0 10 * * 6,0'); // Every Saturday and Sunday at 10:00am
```

--------------------------------

### lang(string $key, array $replacements = []): string

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/CronExpression.md

Resolves a translation string from the loaded locale's fields using a dot notation key, applies placeholder replacements and pluralization, and returns the final string. Throws an error if the key does not exist.

```APIDOC
## lang(string $key, array $replacements = []): string

### Description
Resolves a translation string from the loaded locale's fields using a dot notation key, applies placeholder replacements and pluralization, and returns the final string. Throws an error if the key does not exist.

### Method
lang

### Signature
```php
public function lang(string $key, array $replacements = []): string
```

### Parameters
- **$key** (string) - Required - Dot notation path into `$this->translations['fields']`, e.g. `minutes.times_per_increment`.
- **$replacements** (array) - Optional - Assoc array of placeholder → value; each `:key` occurrence in the resolved string is replaced via `str_replace(':'.$key, $value, $translation)`.

### Returns
- **string** - The resolved template after placeholder substitution and pluralization (`$this->pluralize($translation)`). Throws a PHP `Error`/"undefined array key" unit-level failure if the path does not exist (implementation calls `getArrayDot` unconditionally); through `CronTranslator::translate()` this is wrapped into `CronParsingException`.

### Example
```php
use Lorisleiva\CronTranslator\CronExpression;
use Lorisleiva\CronTranslator\LanguageLoader;

$expression = new CronExpression(
    '*/2 * * * *',
    (new LanguageLoader('en'))->translations
);

echo $expression->lang('minutes.increment', ['increment' => 2]); // every 2 minutes
echo $expression->lang('minutes.times_per_increment', ['times' => 'twice', 'increment' => 4]); // twice every 4 minutes
echo $expression->lang('hours.once_at_time', ['time' => '10:30pm']); // at 10:30pm
```
```

--------------------------------

### filterByType example

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/CronTranslator.md

Example usage of filterByType with a CronExpression. Creates a new expression and filters fields by type 'Once', returning the matching fields.

```php
use Lorisleiva\CronTranslator\CronExpression;

$expression = new CronExpression('0 0 1 1 *');
$onces = MyTranslator::filterByType($expression->getFields(), 'Once');
// -> [MinutesField(0), HoursField(0), DaysOfMonthField(1), MonthsField(1)]
```

--------------------------------

### __construct

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/Field.md

Constructor for the Field class. Initializes the field with the owning CronExpression and the raw cron token, parsing the token to determine its type.

```APIDOC
## __construct

### Description
Constructor for the Field class. Initializes the field with the owning CronExpression and the raw cron token, parsing the token to determine its type.

### Method
Constructor

### Signature
```php
public function __construct(
    protected CronExpression $expression,
    protected string $rawField
)
```

### Parameters
- `$expression` (CronExpression) - Required - The owning expression; stored as a promoted protected property.
- `$rawField` (string) - Required - The cron token; stored as a promoted protected property and parsed with `CronType::parse()`.

### Throws
- `CronParsingException` - when `CronType::parse($rawField)` fails.

### Example
```php
use Lorisleiva\CronTranslator\CronExpression;
use Lorisleiva\CronTranslator\MinutesField;

$expression = new CronExpression('0 12 1 1 *');
$minute = new MinutesField($expression, '0');
echo $minute->type->type; // Once
```
```

--------------------------------

### __construct

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/CronExpression.md

Creates a new CronExpression instance from a 5-field cron expression and optional translations and time format settings. The constructor parses the cron string into field objects and throws exceptions for invalid input.

```APIDOC
## __construct

### Description
Creates a new CronExpression instance from a 5-field cron expression and optional translations and time format settings. The constructor parses the cron string into field objects and throws exceptions for invalid input.

### Method
Constructor

### Signature
```php
public function __construct(string $cron, array $translations = [], bool $timeFormat24hours = false)
```

### Parameters
- **$cron** (string) - Required - A 5-field cron expression. Split with `explode(' ', $cron)`; tokens beyond index 4 are ignored, and fewer than 5 tokens will cause a `TypeError` (`null` passed to a typed parameter) at construction. `@`-prefixed expressions are **not** expanded here — that happens in `CronTranslator::translate()`.
- **$translations** (array) - Optional - Default: `[]` - Translation arrays as produced by `LanguageLoader->translations`. When empty, every `lang()`/`langCountable()` call resolves to `''` (or the raw `:key` string).
- **$timeFormat24hours** (bool) - Optional - Default: `false` - Propagated to `HoursField::format()` via the public property.

### Throws
- `TypeError` if fewer than 5 space-separated tokens are supplied (e.g. `'* * * *'`)
- `CronParsingException` if any token fails `CronType::parse()` (thrown from the `Field` constructors). Both are converted to `CronParsingException` when called through `CronTranslator::translate()`.

### Example
```php
use Lorisleiva\CronTranslator\CronExpression;
use Lorisleiva\CronTranslator\LanguageLoader;

$expression = new CronExpression(
    '0 12 1 1 *',
    (new LanguageLoader('en'))->translations
);

echo $expression->minute->format();   // 00
echo $expression->hour->format($expression->minute); // 12:00pm
echo $expression->month->format();   // January
```
```

--------------------------------

### __construct

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/LanguageLoader.md

Creates a new LanguageLoader instance for the given locale. Loads the five translation files (days, fields, months, ordinals, times) from the locale directory, falling back to 'en' if the locale directory does not exist.

```APIDOC
## __construct

### Description
Creates a new LanguageLoader instance for the given locale. Loads the five translation files (days, fields, months, ordinals, times) from the locale directory, falling back to 'en' if the locale directory does not exist.

### Method
Constructor

### Signature
```php
public function __construct(string $locale = 'en')
```

### Parameters
- `$locale` (string) - Optional - Default: `'en'` - Locale directory name under `src/lang/`. Any string is accepted; unknown locales fall back to `en` via `ensureLocaleExists()`.

### Throws
- `TranslationFileMissingException` - if the locale directory exists but one of the five required files is missing.

### Example
```php
use Lorisleiva\CronTranslator\LanguageLoader;

$loader = new LanguageLoader('fr');
echo $loader->locale;                                              // fr
echo $loader->translations['times'][1];                            // une fois
echo $loader->translations['fields']['minutes']['every'];          // chaque minute
```
```

--------------------------------

### Constructor signature for Field

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/Field.md

The constructor accepts a CronExpression and a raw field string, storing them as promoted properties and parsing the raw field with CronType::parse(). Throws CronParsingException when parsing fails.

```php
public function __construct(
    protected CronExpression $expression,
    protected string $rawField
) {
    $this->type = CronType::parse($rawField);
}
```

--------------------------------

### langCountable() internal resolution logic

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/CronExpression.md

Shows the exact resolution order: case-specific number, flat number, case-specific default, flat default, then empty string. Replaces ':number' placeholder with the number.

```php
$value = $array[$case][$number] ?? $array[$number] ?? $array[$case]['default'] ?? $array['default'] ?? '';
return str_replace(':number', $number, $value);
```

--------------------------------

### hasType() method signature

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/CronType.md

Declares the public method `hasType()` with no parameters. The method reads arguments at runtime via `func_get_args()`.

```php
public function hasType(): bool
```

--------------------------------

### getTimes method signature

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/Field.md

Public method signature for getTimes, returns array|string. Used to get localized 'times' wording for the field's count.

```php
public function getTimes(): array|string
```

--------------------------------

### CronExpression constructor signature

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/CronExpression.md

Constructor for CronExpression. Requires a 5-field cron string; fewer than 5 tokens cause a TypeError, and invalid tokens throw CronParsingException. Translations default to empty, and timeFormat24hours defaults to false.

```php
public function __construct(string $cron, array $translations = [], bool $timeFormat24hours = false)
```

--------------------------------

### getFields

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/CronExpression.md

Returns the five cron fields in cron-token order: minute, hour, day, month, weekday. This array is used for sentence ordering in translations.

```APIDOC
## getFields

### Description
Returns the five cron fields in cron-token order: minute, hour, day, month, weekday. This array is used for sentence ordering in translations.

### Method
PHP method

### Signature
```php
public function getFields(): array
```

### Parameters
None.

### Returns
`array` — the five fields in cron-token order: `[$this->minute, $this->hour, $this->day, $this->month, $this->weekday]`.

### Example
```php
use Lorisleiva\CronTranslator\CronExpression;

$fields = (new CronExpression('0 0 1 1 *'))->getFields();

foreach ($fields as $field) {
    // $field: MinutesField, HoursField, DaysOfMonthField, MonthsField, DaysOfWeekField
    printf('%d: %s (%s)%s', $field->position, $field->getValue() ?? '*', $field->type->type, PHP_EOL);
}
```
```

--------------------------------

### Translate CRON expressions with locale and 24-hour format

Source: https://github.com/lorisleiva/cron-translator/blob/main/README.md

Provide a locale as the second argument and a boolean for 24-hour time formatting as the third argument.

```php
CronTranslator::translate('30 18 * * *', 'fr');       // => Chaque jour à 6:30pm
CronTranslator::translate('30 18 * * *', 'fr', true); // => Chaque jour à 18:30
```

--------------------------------

### Extended cron map static configuration

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/configuration.md

Maps @-prefixed names to expressions or to themselves. Only @reboot stays @-prefixed and requires the fields.extended.@reboot key in each locale.

```php
'@reboot'   => '@reboot',          // rendered via fields.extended.@reboot
'@yearly'   => '0 0 1 1 *',
'@annually' => '0 0 1 1 *',
'@monthly'  => '0 0 1 * *',
'@weekly'   => '0 0 * * 0',
'@daily'    => '0 0 * * *',
'@midnight' => '0 0 * * *',
'@hourly'   => '0 * * * *'
```

--------------------------------

### LanguageLoader constructor signature

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/LanguageLoader.md

Constructor accepts an optional locale string defaulting to 'en'. Unknown locales fall back to 'en' via ensureLocaleExists(). Throws TranslationFileMissingException if the locale directory exists but a required file is missing.

```php
public function __construct(string $locale = 'en')
```

--------------------------------

### declineCount implementation

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/CronExpression.md

Internal logic that picks the form index using the Russian-style plural rule. Returns the form at the computed index from the forms array.

```php
$formsArray = explode('|', $forms);
if (count($formsArray) < 3) { $formsArray[2] = $formsArray[1]; }
$cases = [2, 0, 1, 1, 1, 2];
$count = abs((int) strip_tags($count));
$formIndex = ($count % 100 > 4 && $count % 100 < 20)
    ? 2
    : $cases[min($count % 10, 5)];
return $formsArray[$formIndex];
```

--------------------------------

### loadTranslations signature

Source: https://github.com/lorisleiva/cron-translator/blob/main/_autodocs/api-reference/LanguageLoader.md

Protected method that assembles the translations array by loading five translation files.

```php
protected function loadTranslations(): void
```
Tokens:
Raw