feat: add integration with cache, sessions, queue

Author: lotyp

config/cycle.php

@@ -324,4 +324,25 @@
     'entityBehavior' => [
         'register' => env('CYCLE_REGISTER_ENTITY_BEHAVIOUR', true),
     ],
+
+    'integrations' => [
+        /*
+         * Enables migration generation for Laravel Queues
+         */
+        'queue' => [
+            'enabled' => env('CYCLE_ADAPTER_QUEUE_INTEGRATION', true),
+        ],
+        /*
+         * Enables migration generation for Laravel Sessions
+         */
+        'session' => [
+            'enabled' => env('CYCLE_ADAPTER_SESSION_INTEGRATION', true),
+        ],
+        /*
+         * Enables migration generation for Laravel Cache
+         */
+        'cache' => [
+            'enabled' => env('CYCLE_ADAPTER_CACHE_INTEGRATION', true),
+        ],
+    ],
 ];

docs/pages/services/_meta.json

@@ -4,5 +4,8 @@
     "testing": "Testing",
     "validation": "Validation",
     "pagination": "Pagination",
+    "sessions": "Sessions",
+    "queue": "Queue",
+    "cache": "Cache",
     "laravel-telescope": "Laravel Telescope"
 }

docs/pages/services/cache.mdx

@@ -0,0 +1 @@
+# Cache

docs/pages/services/laravel-telescope.mdx

@@ -21,33 +21,30 @@ Install, telescope as usual, via Composer package manager:
 composer require laravel/telescope
 ```
 
-### Step 2: Publish Telescope Assets
+### Step 2: Add .env Configuration
+
+Add the following configuration to your `.env` file:
+
+```dotenv filename=".env"
+...
+
+DB_USE_TELESCOPE_LOGGER=true
+
+...
+```
+
+### Step 3: Publish Telescope Assets
 
 After installing Telescope, publish its assets and migrations using the `telescope:install` Artisan command.
 
 ```bash
 php artisan telescope:install
 ```
 
-### Step 3: Run Telescope Migrations trough Cycle-ORM-Adapter
+### Step 4: Run Telescope Migrations trough Cycle-ORM-Adapter
 
 After installing Telescope, you should also run the migrate command in order to create the tables needed to store Telescope's data, but as you are using Cycle ORM, you should avoid using default `php artisan migrate` command, and instead, do the following steps:
 
-Edit `config/cycle.php` file and add the following code to the `tokenizer.directories` array:
-
-```php {7} filename="config/cycle.php"
-return [
-    // ...
-    'tokenizer' => [
-    // ...
-        'directories' => [
-            app_path(),
-            __DIR__ . '/../vendor/wayofdev/laravel-cycle-orm-adapter/src/Bridge/Telescope/Entities',
-        ],
-    ],
-],
-```
-
 Run the following command to create the Telescope tables:
 
 ```bash
@@ -56,8 +53,7 @@ php artisan cycle:migrate:init
 php artisan cycle:orm:migrate --split --run
 ```
 
-
-### Step 4: Add the CycleORM Query Watcher
+### Step 5: Add the CycleORM Query Watcher
 
 Next, edit your `config/telescope.php` configuration file and add the following lines to the `watchers` array, right after the default`Watchers\QueryWatcher::class` line:
 
@@ -85,18 +81,6 @@ return [
 ];
 ```
 
-### Step 5: Add .env Configuration
-
-Add the following configuration to your `.env` file:
-
-```dotenv filename=".env"
-...
-
-DB_USE_TELESCOPE_LOGGER=true
-
-...
-```
-
 ### Step 6: Access Laravel Telescope
 
 Finally, you may access the Telescope dashboard via the `/telescope` route. Of course, don't forget to start your Laravel application:

docs/pages/services/pagination.mdx

@@ -8,12 +8,68 @@ Pagination is provided by external package [wayofdev/laravel-paginator](https://
 composer require wayofdev/laravel-paginator
 ```
 
-## Usage
+## Usage with Repositories
 
 <div className="steps-container">
 
 ### Step 1: Define `paginate()` method in your Repository
 
-@todo
+Create a `paginate()` method in your abstract repository class that will return a `CyclePaginator` instance.
+
+```php filename="app/Infrastructure/Persistence/Cycle/Repository.php"
+<?php
+
+declare(strict_types=1);
+
+namespace Infrastructure\Persistence\Cycle;
+
+use Cycle\ORM\EntityManagerInterface;
+use Cycle\ORM\Select;
+use Cycle\ORM\Select\Repository as CycleRepository;
+use Illuminate\Support\Collection;
+use Spiral\Pagination\Paginator as SpiralPaginator;
+use WayOfDev\Paginator\CyclePaginator;
+
+class Repository extends CycleRepository
+{
+    /**
+     * Create repository linked to one specific selector.
+     *
+     * @param Select<TEntity> $select
+     */
+    public function __construct(
+        protected Select $select,
+        protected EntityManagerInterface $entityManager
+    ) {
+        parent::__construct($select);
+    }
+
+    // ...
+
+    public function paginate(int $perPage = 20, int $page = 1, string $pageName = 'page'): CyclePaginator
+    {
+        return $this->paginateQuery(
+            $this->select(),
+            $perPage,
+            $page,
+            $pageName,
+        );
+    }
+
+    protected function paginateQuery(Select $query, int $perPage = 20, int $page = 1, string $pageName = 'page'): CyclePaginator
+    {
+        return new CyclePaginator(
+            (new SpiralPaginator($perPage))->withPage($page)->paginate($query),
+            $this->createCollection($query->fetchAll()),
+            $pageName,
+        );
+    }
+
+    protected function createCollection(iterable $items): Collection
+    {
+        return new Collection($items);
+    }
+}
+```
 
 </div>

docs/pages/services/queue.mdx

@@ -0,0 +1 @@
+# Queue

docs/pages/services/sessions.mdx

@@ -0,0 +1 @@
+# Sessions

phpunit.xml.dist

@@ -13,6 +13,15 @@
         <server name="APP_KEY" value="AckfSECXIvnK5r28GVIWUAxmbBSjTsmF"/>
         <server name="APP_ENV" value="testing"/>
         <server name="CACHE_DRIVER" value="array"/>
+        <server name="CYCLE_ADAPTER_QUEUE_INTEGRATION" value="false"/>
+        <server name="CYCLE_ADAPTER_SESSION_INTEGRATION" value="false"/>
+        <server name="CYCLE_ADAPTER_CACHE_INTEGRATION" value="false"/>
+
+        <server name="CYCLE_ATTRIBUTES_CACHE" value="true"/>
+        <server name="CYCLE_ATTRIBUTES_CACHE_DRIVER" value="array"/>
+
+        <server name="CYCLE_SCHEMA_CACHE" value="true"/>
+        <server name="CYCLE_SCHEMA_CACHE_DRIVER" value="array"/>
     </php>
     <testsuites>
         <testsuite name="Tests">

src/Bridge/Cache/Entities/Cache.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WayOfDev\Cycle\Bridge\Cache\Entities;
+
+use Cycle\Annotated\Annotation\Column;
+use Cycle\Annotated\Annotation\Entity;
+
+#[Entity(table: 'cache')]
+class Cache
+{
+    #[Column(type: 'string', primary: true)]
+    public string $key;
+
+    #[Column(type: 'longText')]
+    public string $text;
+
+    #[Column(type: 'integer')]
+    public int $expiration;
+}

src/Bridge/Cache/Entities/CacheLock.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WayOfDev\Cycle\Bridge\Cache\Entities;
+
+use Cycle\Annotated\Annotation\Column;
+use Cycle\Annotated\Annotation\Entity;
+
+#[Entity(table: 'cache_locks')]
+class CacheLock
+{
+    #[Column(type: 'string', primary: true)]
+    public string $key;
+
+    #[Column(type: 'string')]
+    public string $owner;
+
+    #[Column(type: 'integer')]
+    public int $expiration;
+}

src/Bridge/Cache/Providers/CacheServiceProvider.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WayOfDev\Cycle\Bridge\Cache\Providers;
+
+use Illuminate\Config\Repository;
+use Illuminate\Support\ServiceProvider;
+use Psr\Container\ContainerExceptionInterface;
+use Psr\Container\NotFoundExceptionInterface;
+
+use function array_merge;
+
+class CacheServiceProvider extends ServiceProvider
+{
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public function register(): void
+    {
+        /** @var Repository $config */
+        $config = $this->app->get(Repository::class);
+
+        $config->set('cycle.tokenizer.directories', array_merge(
+            $config->get('cycle.tokenizer.directories', []),
+            [__DIR__ . '/../Entities']
+        ));
+    }
+}

src/Bridge/Laravel/Providers/CycleServiceProvider.php

@@ -10,9 +10,13 @@
 use Illuminate\Support\ServiceProvider;
 use Psr\Container\ContainerExceptionInterface;
 use Psr\Container\NotFoundExceptionInterface;
+use WayOfDev\Cycle\Bridge\Cache\Providers\CacheServiceProvider;
 use WayOfDev\Cycle\Bridge\Laravel\Console\Commands\Database;
 use WayOfDev\Cycle\Bridge\Laravel\Console\Commands\Migrations;
 use WayOfDev\Cycle\Bridge\Laravel\Console\Commands\ORM;
+use WayOfDev\Cycle\Bridge\Queue\Providers\QueueServiceProvider;
+use WayOfDev\Cycle\Bridge\Session\Providers\SessionServiceProvider;
+use WayOfDev\Cycle\Bridge\Telescope\Providers\TelescopeServiceProvider;
 
 final class CycleServiceProvider extends ServiceProvider
 {
@@ -65,6 +69,24 @@ public function register(): void
         foreach ($registrators as $registrator) {
             (new $registrator())($this->app);
         }
+
+        $this->registerIntegrations();
+    }
+
+    private function registerIntegrations(): void
+    {
+        $services = [
+            'cycle.integrations.session.enabled' => SessionServiceProvider::class,
+            'cycle.integrations.cache.enabled' => CacheServiceProvider::class,
+            'cycle.integrations.queue.enabled' => QueueServiceProvider::class,
+            'cycle.database.logger.use_telescope' => TelescopeServiceProvider::class,
+        ];
+
+        foreach ($services as $configKey => $providerClass) {
+            if (config($configKey) === true) {
+                $this->app->register($providerClass);
+            }
+        }
     }
 
     private function registerConsoleCommands(): void

src/Bridge/Queue/Entities/FailedJob.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WayOfDev\Cycle\Bridge\Queue\Entities;
+
+use Cycle\Annotated\Annotation\Column;
+use Cycle\Annotated\Annotation\Entity;
+use Cycle\Annotated\Annotation\Table\Index;
+use DateTimeImmutable;
+
+#[Index(columns: ['uuid'], unique: true)]
+#[Entity(table: 'failed_jobs')]
+class FailedJob
+{
+    #[Column(type: 'primary')]
+    public int $id;
+
+    #[Column(type: 'string')]
+    public string $uuid;
+
+    #[Column(type: 'text')]
+    public string $connection;
+
+    #[Column(type: 'text')]
+    public string $queue;
+
+    #[Column(type: 'longText')]
+    public string $payload;
+
+    #[Column(type: 'longText')]
+    public string $exception;
+
+    #[Column(type: 'datetime', default: 'CURRENT_TIMESTAMP')]
+    public DateTimeImmutable $failedAt;
+}

src/Bridge/Queue/Entities/Job.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WayOfDev\Cycle\Bridge\Queue\Entities;
+
+use Cycle\Annotated\Annotation\Column;
+use Cycle\Annotated\Annotation\Entity;
+use Cycle\Annotated\Annotation\Table\Index;
+
+#[Index(columns: ['queue'])]
+#[Entity(table: 'jobs')]
+class Job
+{
+    #[Column(type: 'primary')]
+    public int $id;
+
+    #[Column(type: 'string')]
+    public string $queue;
+
+    #[Column(type: 'longText')]
+    public string $payload;
+
+    #[Column(type: 'tinyInteger', unsigned: true)]
+    public int $attempts;
+
+    #[Column(type: 'timestamp', nullable: true)]
+    public ?int $reservedAt;
+
+    #[Column(type: 'timestamp')]
+    public int $availableAt;
+
+    #[Column(type: 'timestamp')]
+    public int $createdAt;
+}