feat: Add Yii3, Laravel, and Spiral integrations

Author: roxblnfk

composer.json

@@ -15,12 +15,23 @@
         "cycle/orm": "^2.18"
     },
     "require-dev": {
+        "buggregator/trap": "^1.16",
         "cycle/skills": "1.x-dev",
+        "illuminate/container": "^11 || ^12 || ^13",
+        "illuminate/support": "^11 || ^12 || ^13",
         "infection/infection": ">=0.32.6",
         "llm/skills": "^1.7",
+        "spiral/boot": "^3.12",
+        "spiral/cycle-bridge": "^2.13",
         "testo/bridge-infection": "^0.1.6",
         "testo/testo": "^0.10.26",
-        "vimeo/psalm": "^7"
+        "vimeo/psalm": "^7",
+        "yiisoft/di": "^1.3"
+    },
+    "suggest": {
+        "spiral/cycle-bridge": "Provides integration with the Spiral Framework via TransactionBootloader",
+        "wayofdev/laravel-cycle-orm-adapter": "Provides Cycle ORM integration for Laravel (TransactionServiceProvider)",
+        "yiisoft/yii-cycle": "Provides Cycle ORM integration for the Yii Framework"
     },
     "autoload": {
         "psr-4": {
@@ -54,6 +65,21 @@
             "infection --ansi --configuration=infection.json --logger-github --threads=max --show-mutations=0 --min-msi=50"
         ]
     },
+    "extra": {
+        "laravel": {
+            "providers": [
+                "Cycle\\Transaction\\Bridge\\Laravel\\Providers\\TransactionServiceProvider"
+            ]
+        },
+        "config-plugin": {
+            "di": "src/Bridge/Yii3/config/di.php"
+        },
+        "spiral": {
+            "bootloaders": [
+                "Cycle\\Transaction\\Bridge\\Spiral\\Bootloader\\TransactionBootloader"
+            ]
+        }
+    },
     "minimum-stability": "dev",
     "prefer-stable": true,
     "config": {

src/Bridge/Laravel/Providers/TransactionServiceProvider.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cycle\Transaction\Bridge\Laravel\Providers;
+
+use Cycle\Transaction\Internal\TransactionImpl;
+use Cycle\Transaction\Transaction;
+use Illuminate\Support\ServiceProvider;
+
+final class TransactionServiceProvider extends ServiceProvider
+{
+    #[\Override]
+    public function register(): void
+    {
+        // TransactionImpl is autowired from the container's ORMInterface and DatabaseProviderInterface,
+        // which the Cycle ORM Laravel adapter is expected to bind.
+        $this->app->singleton(Transaction::class, TransactionImpl::class);
+    }
+}

src/Bridge/Spiral/Bootloader/TransactionBootloader.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cycle\Transaction\Bridge\Spiral\Bootloader;
+
+use Cycle\Transaction\Internal\TransactionImpl;
+use Cycle\Transaction\Transaction;
+use Spiral\Boot\Bootloader\Bootloader;
+
+final class TransactionBootloader extends Bootloader
+{
+    protected const SINGLETONS = [
+        Transaction::class => TransactionImpl::class,
+    ];
+}

src/Bridge/Yii3/config/di.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+use Cycle\Transaction\Internal\TransactionImpl;
+use Cycle\Transaction\Transaction;
+
+/**
+ * Yii3 DI definitions. {@see TransactionImpl} is autowired from the container's ORMInterface and
+ * DatabaseProviderInterface, which the Yii Cycle integration is expected to register.
+ */
+return [
+    Transaction::class => TransactionImpl::class,
+];

tests/Unit/TransactionBootloaderTest.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cycle\Transaction\Tests\Unit;
+
+use Cycle\Database\DatabaseProviderInterface;
+use Cycle\ORM\ORMInterface;
+use Cycle\Transaction\Bridge\Spiral\Bootloader\TransactionBootloader;
+use Cycle\Transaction\Internal\TransactionImpl;
+use Cycle\Transaction\Tests\Fixtures\SqliteEnvironment;
+use Cycle\Transaction\Tests\Fixtures\TestEnvironment;
+use Cycle\Transaction\Transaction;
+use Spiral\Core\Container;
+use Testo\Assert;
+use Testo\Codecov\Covers;
+use Testo\Lifecycle\BeforeTest;
+use Testo\Test;
+
+/**
+ * Unit tests for the Spiral {@see TransactionBootloader}.
+ *
+ * Rather than booting a full Spiral application, this checks the bootloader's contract directly: it
+ * binds {@see Transaction} as a singleton resolving to {@see TransactionImpl}, given an
+ * {@see ORMInterface} and a {@see DatabaseProviderInterface} are available in the container.
+ */
+#[Test]
+#[Covers(TransactionBootloader::class)]
+final class TransactionBootloaderTest
+{
+    private TestEnvironment $env;
+
+    #[BeforeTest]
+    public function setUp(): void
+    {
+        $this->env = SqliteEnvironment::create();
+    }
+
+    public function itResolvesTransactionAsASingleton(): void
+    {
+        $container = new Container();
+        $container->bindSingleton(ORMInterface::class, $this->env->orm);
+        $container->bindSingleton(DatabaseProviderInterface::class, $this->env->dbal);
+
+        // Apply the bootloader's bindings exactly as Spiral would.
+        foreach ((new TransactionBootloader())->defineSingletons() as $alias => $resolver) {
+            $container->bindSingleton($alias, $resolver);
+        }
+
+        $transaction = $container->get(Transaction::class);
+
+        Assert::instanceOf($transaction, TransactionImpl::class);
+        // A singleton must hand back the very same instance on every resolution.
+        Assert::same($container->get(Transaction::class), $transaction);
+    }
+}

tests/Unit/TransactionServiceProviderTest.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cycle\Transaction\Tests\Unit;
+
+use Cycle\Database\DatabaseProviderInterface;
+use Cycle\ORM\ORMInterface;
+use Cycle\Transaction\Bridge\Laravel\Providers\TransactionServiceProvider;
+use Cycle\Transaction\Internal\TransactionImpl;
+use Cycle\Transaction\Tests\Fixtures\SqliteEnvironment;
+use Cycle\Transaction\Tests\Fixtures\TestEnvironment;
+use Cycle\Transaction\Transaction;
+use Illuminate\Container\Container;
+use Testo\Assert;
+use Testo\Codecov\Covers;
+use Testo\Lifecycle\BeforeTest;
+use Testo\Test;
+
+/**
+ * Unit tests for the Laravel {@see TransactionServiceProvider}.
+ *
+ * Rather than booting a full Laravel application, this checks the provider's contract directly: it
+ * binds {@see Transaction} as a singleton resolving to {@see TransactionImpl}, given an
+ * {@see ORMInterface} and a {@see DatabaseProviderInterface} are available in the container.
+ */
+#[Test]
+#[Covers(TransactionServiceProvider::class)]
+final class TransactionServiceProviderTest
+{
+    private TestEnvironment $env;
+
+    #[BeforeTest]
+    public function setUp(): void
+    {
+        $this->env = SqliteEnvironment::create();
+    }
+
+    public function itResolvesTransactionAsASingleton(): void
+    {
+        $container = new Container();
+        $container->instance(ORMInterface::class, $this->env->orm);
+        $container->instance(DatabaseProviderInterface::class, $this->env->dbal);
+
+        // ServiceProvider's docblock types $app as the Application contract, but it only uses the
+        // container's bind/singleton methods, which Illuminate\Container\Container provides.
+        /** @psalm-suppress InvalidArgument */
+        (new TransactionServiceProvider($container))->register();
+
+        $transaction = $container->make(Transaction::class);
+
+        Assert::instanceOf($transaction, TransactionImpl::class);
+        // A singleton must hand back the very same instance on every resolution.
+        Assert::same($container->make(Transaction::class), $transaction);
+    }
+}

tests/Unit/TransactionYiiConfigTest.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cycle\Transaction\Tests\Unit;
+
+use Cycle\Database\DatabaseProviderInterface;
+use Cycle\ORM\ORMInterface;
+use Cycle\Transaction\Internal\TransactionImpl;
+use Cycle\Transaction\Tests\Fixtures\SqliteEnvironment;
+use Cycle\Transaction\Tests\Fixtures\TestEnvironment;
+use Cycle\Transaction\Transaction;
+use Testo\Assert;
+use Testo\Lifecycle\BeforeTest;
+use Testo\Test;
+use Yiisoft\Di\Container;
+use Yiisoft\Di\ContainerConfig;
+
+/**
+ * Unit tests for the Yii3 DI configuration (`src/Bridge/Yii3/config/di.php`).
+ *
+ * The config is loaded into a real Yii container together with stub ORMInterface and
+ * DatabaseProviderInterface services, and we assert that {@see Transaction} resolves to a shared
+ * {@see TransactionImpl} instance.
+ */
+#[Test]
+final class TransactionYiiConfigTest
+{
+    private TestEnvironment $env;
+
+    #[BeforeTest]
+    public function setUp(): void
+    {
+        $this->env = SqliteEnvironment::create();
+    }
+
+    public function itResolvesTransactionAsASharedService(): void
+    {
+        /** @var array<string, mixed> $definitions */
+        $definitions = require \dirname(__DIR__, 2) . '/src/Bridge/Yii3/config/di.php';
+
+        $container = new Container(
+            ContainerConfig::create()->withDefinitions([
+                ORMInterface::class => $this->env->orm,
+                DatabaseProviderInterface::class => $this->env->dbal,
+                ...$definitions,
+            ]),
+        );
+
+        $transaction = $container->get(Transaction::class);
+
+        Assert::instanceOf($transaction, TransactionImpl::class);
+        // The container must return the same shared instance on every resolution.
+        Assert::same($container->get(Transaction::class), $transaction);
+    }
+}