README

ProKerja is a lightweight PHP job & queue framework focused on declaration-first task orchestration.

It provides a clean, minimal, and transparent job queue system built on top of PHP + SQLite + Symfony Console, without relying on heavy frameworks, magic containers, or hidden execution layers.

ProKerja is designed to be:

technically correct
predictable
framework-agnostic
usable in real projects

Any interpretation beyond what the system explicitly guarantees is outside its responsibility.

Core Concept

ProKerja separates declaration from realization.

Declaring a job means it is registered into the system
Realizing a job depends entirely on worker availability
The system does not promise execution, only orchestration

This is not a limitation.
This is the contract.

Features

Job declaration & dispatch
Persistent queue (SQLite)
Long-running worker process
Explicit job lifecycle:
- pending
- processing
- completed
- failed
Symfony Console–based CLI
Zero framework lock-in
No background magic

Requirements

PHP 8.0+
PDO with SQLite enabled
Composer

Installation

git clone https://github.com/Pedhot-Dev/ProKerja.git
cd prokerja
composer install
chmod +x bin/prokerja or php bin/prokerja

Basic Usage

1. Declare Jobs via CLI

php bin/prokerja declare:job

This command will:

create job entries
store them in the queue
return immediately

A successful declaration means:

the job exists
the job is persisted
the system acknowledges it

It does not mean the job has been executed.

2. Start Worker (Realization Process)

php bin/prokerja realization:start

This starts a blocking worker process that:

continuously checks the queue
processes pending jobs
updates job status

If the queue is empty, the worker will remain idle and wait.

3. View Queue Report

php bin/prokerja report

Example output:

ProKerja Report
pending: 10
processing: 0
completed: 2
failed: 0

This report reflects system state, not execution guarantees.

Creating Your Own Job

1. Create a Job Class

All jobs must implement JobInterface.

<?php

namespace App\Jobs;

use ProKerja\Contracts\JobInterface;

final class SendEmailJob implements JobInterface
{
    public function __construct(
        private int $userId
    ) {}

    public function handle(): void
    {
        // Do the actual work here
        file_put_contents(
            'worker.log',
            "Email sent to user {$this->userId}\n",
            FILE_APPEND
        );
    }

    public function payload(): array
    {
        return [
            'userId' => $this->userId,
        ];
    }
}

Rules for Jobs:

Must be instantiable from payload data
Must not perform work inside the constructor
All heavy work must be inside handle()

Dispatching Jobs (Vanilla PHP)

You can dispatch jobs without using the CLI.

<?php

require 'vendor/autoload.php';

use ProKerja\Queue\DeclarationQueue;
use ProKerja\Queue\Dispatcher;
use App\Jobs\SendEmailJob;

$queue = new DeclarationQueue(__DIR__ . '/prokerja.sqlite');
$dispatcher = new Dispatcher($queue);

$dispatcher->dispatch(
    new SendEmailJob(42)
);

echo "Job declared\n";

Dispatching:

does not execute the job
does not require a running worker
always returns immediately

Running Worker Without CLI (Vanilla)

<?php

require 'vendor/autoload.php';

use ProKerja\Queue\DeclarationQueue;
use ProKerja\Worker\Worker;

$queue = new DeclarationQueue(__DIR__ . '/prokerja.sqlite');
$worker = new Worker($queue);

$worker->run(function () {
    echo "Waiting for ecosystem readiness...\n";
});

This behaves exactly like realization:start.

Important Notes

SQLite Path Consistency

All entry points must use the same SQLite database path.

Recommended:

define('PROKERJA_DB', realpath(__DIR__ . '/prokerja.sqlite'));

Using different paths will result in:

jobs not being picked up
empty reports
inconsistent behavior

Design Principles

Explicit over implicit
No hidden execution
No automatic scaling assumptions
No promise of completion
Transparent failure states

If a job does not run, the system is still functioning correctly.

What ProKerja Is NOT

Not a Laravel Queue replacement
Not a distributed task system
Not a scheduler
Not a background daemon manager
Not a guarantee engine

If you need those features, use a different tool.

Philosophy

ProKerja guarantees registration, not realization.

It records intent, tracks state, and reports status. Execution depends entirely on environment readiness.

The framework does exactly what it claims — nothing more.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

pedhot-dev / prokerja

Maintainers

Details