README

Welcome to sTask!

sTask is a high-performance asynchronous task management system designed specifically for Evolution CMS. It provides an enterprise-grade framework for creating, executing, and monitoring background tasks with automatic worker discovery, comprehensive performance monitoring, and advanced caching capabilities.

Whether you need to process large data imports, generate reports, send emails in bulk, or perform any other time-consuming operations, sTask gives you the tools to handle these tasks efficiently without blocking your main application. Built with performance and scalability in mind, it's designed to become the fundamental task management solution for the entire Evolution CMS ecosystem.

Features

🚀 Core Task Management

Asynchronous Processing: Execute long-running tasks in the background
Priority System: Task prioritization (low, normal, high) with intelligent queuing
Progress Tracking: Real-time progress monitoring (0-100%) via filesystem-based tracking
Status Management: Complete task lifecycle (queued, preparing, running, finished, failed)
Retry Mechanism: Configurable automatic retry with exponential backoff
File Downloads: Download task results and exported files

⚡ High-Performance Architecture

Multi-Level Caching: In-memory + Laravel cache for optimal worker resolution
Database Optimization: Batch operations and optimized queries
Memory Management: Automatic memory cleanup and resource management
Performance Metrics: Real-time monitoring and analytics
System Health: Automated health checks and performance alerts
Cache Statistics: Detailed cache performance monitoring

🔧 Worker System

Automatic Discovery: Auto-discovery of worker implementations from packages
Worker Registration: Dynamic worker registration and activation/deactivation
Interface Validation: Comprehensive worker validation and error handling
Custom Implementation: Clean interface for custom worker development
Worker Settings: Individual worker configuration and settings management

🎛️ Admin Interface

Modern Dashboard: Clean, responsive interface with task statistics
Worker Management: Visual worker management with card-based layout
Real-time Monitoring: Live task progress and status updates
Performance Analytics: Built-in performance monitoring and alerts
Cache Management: Visual cache statistics and management tools

🔌 Developer Experience

RESTful API: Comprehensive API for task management and monitoring
Clean Architecture: Well-structured, extensible codebase
Comprehensive Documentation: Detailed docs with examples
Error Context: Detailed error information for debugging
Performance Tools: Built-in performance analysis and optimization tools

🔗 Integration

Evolution CMS: Seamless integration with Evolution CMS manager
Menu Integration: Custom logo and menu integration
Artisan Commands: CLI tools for task management
Composer Package: Auto-assets publishing and dependency management

Requirements

Evolution CMS 3.7+
PHP 8.3+
Composer 2.2+
One of: MySQL 8.0+ / MariaDB 10.5+ / PostgreSQL 10+ / SQLite 3.25+

Installation

Go to Your /core/ folder:

cd core

composer update

Run php artisan commands:

php artisan package:installrequire seiger/stask "*"

php artisan vendor:publish --tag=stask

php artisan migrate

Setup Cron Job

Add the following cron job to run scheduled tasks every minute:

# Edit your crontab
crontab -e

# Add this line to run every minute
* * * * * cd /path/to/your/project && php artisan schedule:run >> /dev/null 2>&1

Important: Replace /path/to/your/project with the actual path to your Evolution CMS installation.

For shared hosting, you may need to use the full path to PHP:

* * * * * cd /path/to/your/project && /usr/bin/php artisan schedule:run >> /dev/null 2>&1

Quick Start

Creating a Task

use Seiger\sTask\Facades\sTask;

// Create a new task
$task = sTask::create(
    identifier: 'product_sync',
    action: 'import',
    data: ['file' => '/path/to/products.csv'],
    priority: 'high',
    userId: evo()->getLoginUserID()
);

Processing Tasks

// Process pending tasks
$processedCount = sTask::processPendingTasks();

// Get task statistics
$stats = sTask::getStats();

// Get all incomplete tasks (pending, preparing, running)
$incomplete = \Seiger\sTask\Models\sTaskModel::incomplete()->get();

Creating Custom Workers

<?php namespace YourNamespace\Workers;

use Seiger\sTask\Workers\BaseWorker;
use Seiger\sTask\Models\sTaskModel;

class EmailWorker extends BaseWorker
{
    public function identifier(): string
    {
        return 'email_campaign';
    }
    
    public function scope(): string
    {
        return 'notifications';
    }
    
    public function icon(): string
    {
        return '<i class="fa fa-envelope"></i>';
    }
    
    public function title(): string
    {
        return 'Email Campaign';
    }
    
    public function description(): string
    {
        return 'Send bulk email campaigns to users';
    }
    
    public function taskSend(sTaskModel $task, array $options = []): void
    {
        $this->pushProgress(10, 'Preparing email data');
        
        $recipients = $options['recipients'] ?? [];
        $subject = $options['subject'] ?? 'Campaign';
        
        foreach ($recipients as $email) {
            // Send email logic
            $this->pushProgress(50 + (40 / count($recipients)), "Sent to {$email}");
        }
        
        $this->markFinished('All emails sent successfully');
    }
    
    public function settings(): array
    {
        return [
            'smtp_host' => 'localhost',
            'smtp_port' => 587,
            'from_email' => 'noreply@example.com',
        ];
    }
}

Admin Interface

Access sTask through Manager → Tools → Task Manager.

Dashboard

Task statistics (pending, running, completed, failed)
Recent activity with progress tracking
Quick actions for processing and cleanup

Workers

Automatic worker discovery
Worker activation/deactivation
Worker configuration management

Artisan Commands

Task Worker (System Command)

The task worker is automatically executed by the system via cron job every minute. You don't need to run it manually.

What it does:

Processes all pending tasks in the queue
Executes tasks through their respective workers
Updates task progress and status
Cleans up old progress files when idle
Should be configured via cron for continuous processing

Note: Workers are automatically discovered when you access the Workers tab in the admin interface. No manual discovery needed!

API Endpoints

sTask provides a comprehensive RESTful API for task management and monitoring:

Task Management

POST /stask/worker/{identifier}/run/{action} # Start task
GET /stask/task/{id}/progress                # Get progress
GET /stask/task/{id}/download                # Download result

Performance Monitoring

GET /stask/performance/summary?hours=24      # System performance
GET /stask/performance/workers?hours=24      # Worker statistics
GET /stask/performance/alerts                # Performance alerts

Configuration

Check if sTask is installed:

if (evo()->getConfig('check_sTask', false)) {
    // sTask is available
    $task = \Seiger\sTask\Facades\sTask::create(
        identifier: 'my_worker',
        action: 'process',
        data: []
    );
}

Database Tables

sTask creates the following tables:

s_workers - Worker configurations
s_tasks - Task records

Storage Structure

storage/
├── stask/           # Task log files
│   ├── 1.log        # Logs for task ID 1
│   ├── 2.log        # Logs for task ID 2
│   └── ...

Task Status Codes

10 - Queued (waiting to be executed)
30 - Preparing (task is being prepared)
50 - Running (currently executing)
80 - Finished (successfully completed)
100 - Failed (encountered an error)

Querying Tasks

use Seiger\sTask\Models\sTaskModel;

// Get tasks by status
$pending = sTaskModel::pending()->get();
$running = sTaskModel::running()->get();
$completed = sTaskModel::finished()->get();
$failed = sTaskModel::failed()->get();

// Get all incomplete tasks (pending, preparing, running)
$incomplete = sTaskModel::incomplete()->get();

// Get tasks by priority
$highPriority = sTaskModel::highPriority()->get();
$normalPriority = sTaskModel::normalPriority()->get();
$lowPriority = sTaskModel::lowPriority()->get();

Priority Levels

low - Lowest priority, executed last
normal - Default priority
high - Highest priority, executed first

Performance & Monitoring

🎯 Performance Targets Achieved

Task execution overhead < 100ms
Memory usage < 10MB per worker
Database queries < 3 per task
File I/O operations < 5 per task
Cache hit rate > 85%

📊 Built-in Monitoring

Real-time metrics collection and analysis
Performance alerts with configurable thresholds
System health checks and automated monitoring
Worker statistics and performance analytics
Cache performance tracking and optimization
Memory usage monitoring and cleanup

🔧 Enterprise Features

Multi-level caching (in-memory + Laravel cache)
Database optimization with batch operations
Automatic memory management and cleanup
Performance analytics with historical data
System health monitoring with alerts
Cache management with detailed statistics

🚀 Roadmap

Task scheduling with cron integration
Task dependencies and workflow management
Email notifications for task completion
Webhook support for external integrations
Task templates and presets
Multi-server task distribution
Advanced queue prioritization algorithms

Documentation

📖 Full Documentation

Getting Started - Installation and basic usage
Admin Interface - Managing tasks and workers
Developer Guide - Creating custom workers
API Reference - Complete API documentation
Performance Guide - Optimization and monitoring

Evolution CMS Ecosystem

sTask is designed to become the fundamental task management solution for the entire Evolution CMS ecosystem:

🎯 Core Dependency

sCommerce - Uses sTask for product synchronization and data processing
sArticles - Leverages sTask for content management and publishing
sGallery - Utilizes sTask for image processing and optimization
Future packages - Will integrate with sTask for async operations

🔄 Migration Strategy

Phase 1: Parallel operation with existing systems
Phase 2: Gradual migration of async operations
Phase 3: Complete replacement of legacy task systems
Phase 4: Optimization and enhancement

🚀 Benefits for Package Developers

Standardized async processing across all packages
Unified task management interface
Performance optimization out of the box
Monitoring and analytics built-in
Easy integration with clean APIs

Support

If you need help, please don't hesitate to open an issue.

License

This project is licensed under the GPL-3.0 License - see the LICENSE file for details.

Author

Seiger IT Team

Website: https://seigerit.com
GitHub: @Seiger

Made with ❤️ for Evolution CMS

seiger / stask

Maintainers

Details