Provide initial code

Author: Vectorial1024

composer.json

@@ -21,7 +21,7 @@
     },
     "autoload-dev": {
         "psr-4": {
-            "Vectorial1024\\LaravelBackgroundAsync\\Tests\\": "tests/"
+            "Vectorial1024\\LaravelProcessAsync\\Tests\\": "tests/"
         }
     },
     "authors": [
@@ -41,5 +41,12 @@
     },
     "scripts": {
         "test": "vendor/bin/phpunit tests"
+    },
+    "extra": {
+        "laravel": {
+            "providers": [
+                "Vectorial1024\\LaravelProcessAsync\\BackgroundAsyncServiceProvider"
+            ]
+        }
     }
 }

src/AsyncTask.php

@@ -0,0 +1,110 @@
+<?php
+
+namespace Vectorial1024\LaravelProcessAsync;
+
+use Closure;
+use Illuminate\Support\Facades\Process;
+use Laravel\SerializableClosure\SerializableClosure;
+
+/**
+ * The common handler of an AsyncTask; this can be a closure (will be wrapped inside AsyncTask) or an interface instance.
+ */
+class AsyncTask
+{
+    /**
+     * The back to be executed in the background.
+     * @var SerializableClosure|AsyncTaskInterface
+     */
+    private SerializableClosure|AsyncTaskInterface $theTask;
+
+    /**
+     * Creates an AsyncTask instance.
+     * @param Closure|AsyncTaskInterface $theTask The task to be executed in the background.
+     */
+    public function __construct(Closure|AsyncTaskInterface $theTask)
+    {
+        if ($theTask instanceof Closure) {
+            // convert to serializable closure first
+            $theTask = new SerializableClosure($theTask);
+        }
+        $this->theTask = $theTask;
+    }
+
+    /**
+     * Inside an available PHP process, runs this AsyncTask instance.
+     * 
+     * This should only be called from the runner so that we are really inside an available PHP process.
+     * @return void
+     * @see AsyncTaskRunnerCommand
+     */
+    public function run(): void
+    {
+        // todo startup configs
+
+        // then, execute the task itself
+        if ($this->theTask instanceof SerializableClosure) {
+            $innerClosure = $this->theTask->getClosure();
+            $innerClosure();
+            unset($innerClosure);
+        } else {
+            // must be AsyncTaskInterface
+            $this->theTask->execute();
+        }
+
+        // todo what if want some "task complete" event handling?
+        return;
+    }
+
+    /**
+     * Starts this AsyncTask immediately in the background.
+     * @return void
+     */
+    public function start(): void
+    {
+        // assume unix for now
+        $serializedTask = $this->toBase64Serial();
+        Process::start("php artisan async:run $serializedTask 2>&1");
+    }
+
+    /**
+     * Returns the base64-encoded serialization for this object.
+     * 
+     * This has the benefit of entirely ignoring potential encoding problems, such as '\0' from private instance variables.
+     * 
+     * This mechanism might have problems if the task closure is too long, but let's be honest: long closures are best converted to dedicated interface objects.
+     * @return string The special serialization.
+     * @see self::fromBase64Serial()
+     */
+    public function toBase64Serial(): string
+    {
+        return base64_encode(serialize($this));
+    }
+
+    /**
+     * Returns the AsyncTask instance represented by the given base64-encoded serial.
+     * @param string $serial The special serialization.
+     * @return static|null If the serial is valid, then the reconstructed instance will be returned, else returns null.
+     * @see self::toBase64Serial()
+     */
+    public static function fromBase64Serial(string $serial): ?static
+    {
+        $temp = base64_decode($serial, true);
+        if ($temp === false) {
+            // bad data
+            return null;
+        }
+        try {
+            $temp = unserialize($temp);
+            // also check that we are unserializing into ourselves
+            if ($temp instanceof static) {
+                // correct value type
+                return $temp;
+            }
+            // incorrect value type
+            return null;
+        } catch (ErrorException) {
+            // bad data
+            return null;
+        }
+    }
+}

src/AsyncTaskInterface.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace Vectorial1024\LaravelProcessAsync;
+
+/**
+ * An interface to describe the details of a background async task.
+ * 
+ * This is the recommended way in case your task is not suitable for a serialized closure (e.g. it involves anonymous classes).
+ */
+interface AsyncTaskInterface
+{
+    /**
+     * Executes the task when the background async runner is ready to handle this task.
+     * 
+     * Note: result-checking with the task issuer and exception handling (if needed) must be defined within this method.
+     * @return void
+     */
+    public function execute(): void;
+}

src/AsyncTaskRunnerCommand.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace Vectorial1024\LaravelProcessAsync;
+
+use Illuminate\Console\Command;
+
+/**
+ * The Artisan command to run AsyncTask. DO NOT USE DIRECTLY!
+ */
+class AsyncTaskRunnerCommand extends Command
+{
+    /**
+     * The name and signature of the console command.
+     *
+     * @var string
+     */
+    protected $signature = 'async:run {task}';
+
+    /**
+     * The console command description.
+     *
+     * @var string
+     */
+    protected $description = 'Runs a background async task (DO NOT USE DIRECTLY)';
+
+    /**
+     * Execute the console command.
+     *
+     * @return int
+     */
+    public function handle(): int
+    {
+        // first, unpack the task
+        // (Symfony already safeguards the "task" argument to make it required)
+        $theTask = $this->argument('task');
+        $theTask = AsyncTask::fromBase64Serial($theTask);
+        if ($theTask === null) {
+            // bad underializing; probably bad data
+            $this->error("Invalid task details!");
+            return self::INVALID;
+        }
+
+        // the task type is correct; we can execute it!
+        /** @var AsyncTask $theTask */
+        $theTask->run();
+        return self::SUCCESS;
+    }
+}

src/BackgroundAsyncServiceProvider.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Vectorial1024\LaravelProcessAsync;
+
+use Illuminate\Support\ServiceProvider;
+
+class BackgroundAsyncServiceProvider extends ServiceProvider
+{
+    /**
+     * Register services.
+     */
+    public function register(): void
+    {
+        // pass
+    }
+
+    /**
+     * Bootstrap services.
+     */
+    public function boot(): void
+    {
+        $this->commands([
+            AsyncTaskRunnerCommand::class,
+        ]);
+    }
+}

tests/AsyncTaskTest.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Vectorial1024\LaravelProcessAsync\Tests;
+
+class AsyncTaskTest extends BaseTestCase
+{
+    // nothing for now
+}

tests/BaseTestCase.php

@@ -0,0 +1,46 @@
+<?php
+
+namespace Vectorial1024\LaravelProcessAsync\Tests;
+
+use Illuminate\Contracts\Auth\Authenticatable;
+use Orchestra\Testbench\TestCase;
+
+/**
+ * Base class for project test cases for some common test config.
+ */
+class BaseTestCase extends TestCase 
+{
+    protected function getPackageProviders($app)
+    {
+        // load required package providers for our library to work during testing
+        return [
+            \Vectorial1024\LaravelProcessAsync\BackgroundAsyncServiceProvider::class
+        ];
+    }
+
+    // ---
+
+    public function call($method, $uri, $parameters = [], $files = [], $server = [], $content = null, $changeHistory = true)
+    {
+        // pass
+        return;
+    }
+
+    public function be(Authenticatable $user, $driver = null)
+    {
+        // pass
+        return;
+    }
+
+    public function seed($class = 'DatabaseSeeder')
+    {
+        // pass
+        return;
+    }
+
+    public function artisan($command, $parameters = [])
+    {
+        // pass
+        return;
+    }
+}