# CronBase Class Documentation

## Overview

`CronBase` is the abstract base class that provides core functionality for all cronjob handlers. It manages database connections, execution tracking, error handling, and logging.

## Class Structure

### Static Properties

- `$_class_code`: Class identifier code (e.g., '0801')
- `$_class_trans_code`: Transaction code prefix (e.g., 'cron-')
- `$_db`: Database connection instance
- `$_cron_table`: Name of the standard cron table
- `$_rapid_cron_table`: Name of the rapid cron table
- `$_datetime`: Current system datetime
- `$_cron_instance`: Singleton instance of the class
- `$err_code`: Current error code
- `$err_codes`: Array of all error codes
- `$logs`: Accumulated log messages

## Core Methods

### Initialization

#### `__construct()`
Initializes the database connection and sets table names.

**Key Operations:**
- Gets database instance via `SiteDatabase::instance()`
- Sets `$_cron_table` to `{prefix}cron`
- Sets `$_rapid_cron_table` to `{prefix}cron_rapid`

#### `_initialize()`
Ensures the system is initialized before operations.

**Key Operations:**
- Sets current datetime
- Creates singleton instance if not exists

### Error Handling

#### `_set_error_code($code)`
Sets the current error code.

**Parameters:**
- `$code`: Error code (e.g., '001', '002')

**Behavior:**
- Combines class code with method code: `{class_code}{code}`
- Adds to `$err_codes` array
- Sets `$err_code` static property

#### `_set_log($log)`
Appends a log message to the logs.

**Parameters:**
- `$log`: Log message string

**Behavior:**
- Appends to `$logs` with newline separator
- Accumulates multiple log messages

#### `_reset_errors()`
Resets all error-related properties.

**Behavior:**
- Clears `$err_code`
- Clears `$err_codes` array
- Clears `$logs`

### Cron Record Management

#### `_record_cron($code, $date = '')`
Records the start of a cronjob execution.

**Parameters:**
- `$code`: Cron job code (e.g., 'A111', 'A002')
- `$date`: Optional date in YYYY-MM-DD format. If empty, uses current date.

**Returns:**
- `$cron_id`: The database ID of the created record

**Database Fields:**
- `code`: Cron code
- `started`: Current datetime
- `completed`: 'n' (not completed)
- `success`: 'n' (not successful yet)
- `year`: Year from date
- `month`: Month from date
- `day`: Day from date
- `odate`: Date in YYYY-MM-DD format

**Error Handling:**
- Throws `Xception` if database insert fails
- Logs SQL error details

#### `_update_complete_cron($cron_id, $success, $message = '')`
Updates a cron record when execution completes.

**Parameters:**
- `$cron_id`: Database ID of the cron record
- `$success`: Boolean indicating success (true) or failure (false)
- `$message`: Optional message describing the result

**Database Updates:**
- `completed`: 'y'
- `success`: 'y' or 'n' based on `$success` parameter
- `ended`: Current datetime
- `message`: Result message
- `err_code`: Current error code (if any)

**Error Handling:**
- Throws `Xception` if database update fails
- Logs SQL error details

### Rapid Cron Management

#### `_record_rapid_cron($code)`
Records the start of a rapid cronjob execution.

**Parameters:**
- `$code`: Cron job code

**Returns:**
- `$cron_id`: The database ID of the created record

**Note:** Similar to `_record_cron()` but uses `$_rapid_cron_table` instead. Used for cronjobs that may run multiple times per day.

#### `_update_complete_rapid_cron($cron_id, $success, $message = '')`
Updates a rapid cron record when execution completes.

**Parameters:**
- `$cron_id`: Database ID of the cron record
- `$success`: Boolean indicating success
- `$message`: Optional result message

**Note:** Similar to `_update_complete_cron()` but uses `$_rapid_cron_table`.

### Execution Status Checking

#### `is_cron_ran($code, $date)`
Checks if a cronjob has been executed for a given date.

**Parameters:**
- `$code`: Cron job code
- `$date`: Date in YYYY-MM-DD format

**Returns:**
- `bool`: `true` if cron has been executed, `false` otherwise

**SQL Query:**
```sql
SELECT COUNT(*) AS total 
FROM {cron_table} 
WHERE code = '{code}' AND odate = '{date}'
```

**Error Handling:**
- Returns `false` on database errors
- Logs critical errors via `Log::logCriticalErrors()`

#### `is_cron_ran_success($code, $date)`
Checks if a cronjob has been executed successfully for a given date.

**Parameters:**
- `$code`: Cron job code
- `$date`: Date in YYYY-MM-DD format

**Returns:**
- `bool`: `true` if cron has been executed successfully, `false` otherwise

**SQL Query:**
```sql
SELECT COUNT(*) AS total 
FROM {cron_table} 
WHERE code = '{code}' AND success = 'y' AND odate = '{date}'
```

**Use Case:** Used when you want to rerun a cronjob only if it previously failed.

**Error Handling:**
- Returns `false` on database errors
- Logs critical errors

## Usage Pattern

```php
// In derived class
static public function my_cronjob($date) {
    static::_initialize();
    $method_code = 'A999';
    $actionCode = static::$_class_code . $method_code;
    $transCode = static::$_class_trans_code . 'my-cronjob';
    
    static::_reset_errors();
    static::validate_cron_date($date);
    
    $cron_code = $method_code;
    if (!static::is_cron_ran($cron_code, $date)) {
        try {
            $cron_id = static::_record_cron($cron_code, $date);
        } catch (exception $e) {
            // Log error and exit
        }
        
        if (!$error) {
            try {
                // Execute business logic
                $result = $some_model->do_something($date);
            } catch (exception $e) {
                // Handle execution error
            }
            
            // Determine success/failure
            $success = !$result['error'] && !$exec_error;
            $message = $exec_error ? static::$logs : '';
            
            try {
                static::_update_complete_cron($cron_id, $success, $message);
            } catch (exception $e) {
                // Log update error
            }
        }
    }
}
```

## Error Code Format

Error codes follow this pattern:
```
{class_code}{method_code}{error_code}
```

Example: `0801A111001`
- `0801`: Class code
- `A111`: Method code
- `001`: Specific error code

## Dependencies

- `SiteDatabase`: Database connection manager
- `Util`: Utility functions (date validation, string escaping, datetime)
- `DBHelper`: Database helper functions
- `Log`: Logging system
- `Xception`: Custom exception class