Download the PHP package nabeghe/cronark without Composer

Cronark

A lightweight, cron-based background job scheduler and worker manager for PHP.

Cronark provides a simple yet powerful solution for running background jobs in PHP applications. Unlike traditional queue systems that require external services (Redis, RabbitMQ, Beanstalkd), Cronark works with just cron and minimal storage; making it perfect for shared hosting, small to medium projects, or anywhere you want to avoid infrastructure complexity.

🎯 Why Cronark?

The Problem with Traditional Queue Systems

Most PHP queue solutions come with significant challenges:

• ❌ Infrastructure Overhead: Require Redis, RabbitMQ, or other external services
• ❌ Shared Hosting: Not available on most shared hosting environments
• ❌ Complexity: Learning curve, configuration, and maintenance burden
• ❌ Resource Heavy: Memory consumption and process management complexity
• ❌ Overkill: Too much for simple background job needs

The Cronark Solution

Cronark takes a different approach:

• ✅ Zero Dependencies: Just PHP 8.1+ and cron (available everywhere)
• ✅ Shared Hosting Friendly: Works on any hosting with cron access
• ✅ Simple Setup: Define jobs, register with cron, done
• ✅ Lightweight: Minimal resource footprint
• ✅ Process-Safe: Prevents duplicate worker execution automatically
• ✅ Flexible Storage: File-based by default, easily customizable to database or Redis

📦 Installation

Install via Composer:

Requirements:

• PHP 8.1 or higher
• Cron access (available on virtually all hosting providers)

🚀 Quick Start

1. Create a Job

2. Register the Job

Create a worker file (e.g., worker.php):

3. Setup Cron

Add to your crontab:

That's it! Your jobs will now run continuously in the background.

🎨 Features

Multiple Workers Run different workers for different job types:

Process Management

Cronark automatically prevents duplicate workers:

Job Ordering

Control job execution order:

Custom Storage

Implement your own storage backend (Database, Redis, Memcached, etc.):

Built-in Storage:

• File-based (default): Zero setup, works everywhere
• Custom: Implement StorageInterface for database, Redis, etc.

Lifecycle Hooks

Customize worker behavior:

Performance Tuning

Control CPU usage by adding delay between job executions:

When to use delay:

• ✅ Shared hosting with CPU limits
• ✅ Light/fast jobs (< 10ms execution time)
• ✅ Rate limiting external API calls
• ✅ Reducing database connection pressure

When NOT to use delay:

• ❌ Heavy/slow jobs (they already have natural delay)
• ❌ Real-time processing requirements
• ❌ Time-sensitive operations

Recommended values:

• 0 – No delay (default, maximum speed)
• 10000 – 10ms (~100 jobs/sec, near real-time)
• 50000 – 50ms (~20 jobs/sec, balanced)
• 100000 – 100ms (~10 jobs/sec, CPU friendly)

📖 How It Works

Architecture

• Cron Trigger: Cron executes worker script every minute (or your interval)
• Duplicate Prevention: Worker checks if it's already running (via PID + script path)
• Infinite Loop: If not running, worker enters infinite loop
• Job Execution: Executes jobs sequentially in a circular fashion
• Graceful Shutdown: Monitors PID to allow graceful termination

Process Flow

Job Wrapping

Jobs execute in a circular fashion:

This ensures all jobs get executed repeatedly without any sitting idle.

🔧 Advanced Usage

Jobs can throw exceptions; they won't stop the worker:

Error Handling

Worker Isolation

Each worker maintains its own state:

Cron Schedule Examples

Deployment on Shared Hosting

Most shared hosting providers (cPanel, Plesk) offer cron job access:

cPanel:

1. Go to "Cron Jobs"
2. Add: * php /home/username/public_html/worker.php

Plesk:

1. Go to "Scheduled Tasks"
2. Add command: php /var/www/vhosts/domain.com/worker.php
3. Set schedule: Every minute

🧪 Testing

Test Coverage: 67 tests with full coverage of all core functionality.

🛡️ Reliability

Duplicate Prevention

Cronark uses PID + Script Path verification to prevent duplicate workers:

Crash Recovery

If worker crashes, cron will restart it on next trigger:

Atomic Storage

File operations use LOCK_EX for atomic writes:

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

💡 Use Cases

Perfect for:

• Shared Hosting Projects: No Redis/RabbitMQ required
• Small to Medium Apps: When full queue infrastructure is overkill
• Email Processing: Send newsletters, notifications
• Data Import/Export: Process CSV files, API sync
• Report Generation: Periodic reports, analytics
• Cleanup Tasks: Temp file cleanup, log rotation
• Social Media Posting: Schedule posts, fetch feeds
• Database Maintenance: Backups, optimization
• Any Recurring Task: If it needs to run regularly, Cronark can handle it

📚 Documentation

Core Classes

• Cronark: Main scheduler class
• Job: Interface for all jobs
• Process: Cross-platform process utilities
• Storage: File-based storage implementation
• StorageInterface: Storage contract for custom backends

Key Methods

⚠️ Important Notes

1. Execution Time: Workers run indefinitely; ensure your hosting allows long-running processes
2. Memory: Monitor memory usage if jobs process large datasets
3. Error Handling: Always implement proper error handling in jobs
4. Logging: Use the print() method or implement custom logging
5. Database Connections: Reconnect to database in onJobCreating() hook to avoid timeout issues

🌟 Show Your Support

If you find Cronark useful, please:

• ⭐ Star the repository
• 🐛 Report bugs
• 💡 Suggest features
• 📖 Improve documentation
• 🔀 Submit pull requests

📖 License

Licensed under the MIT license, see LICENSE.md for details.

Made with ❤️ by (Nabeghe)[https://github.com/nabeghe]

Cronark - Simple, Reliable, Zero-Dependency Background Jobs for PHP