Integration of Laravel Telescope with Cycle ORM Using Laravel-Cycle-ORM-Adapter

[lotyp]

Hello, Community!

I'm currently working on the laravel-cycle-orm-adapter project, aiming to integrate laravel/telescope with native Cycle ORM migrations.

I've encountered a challenge while attempting to adapt Laravel Telescope's migration files for use with Cycle ORM, specifically regarding the #[ForeignKey] annotation.

Original Laravel Telescope Migration File

I started with the Laravel Telescope migration file located here: https://github.com/laravel/telescope/blob/5.x/database/migrations/2018_08_08_100000_create_telescope_entries_table.php

2018_08_08_100000_create_telescope_entries_table.php

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
     * Get the migration connection name.
     */
    public function getConnection(): string|null
    {
        return config('telescope.storage.database.connection');
    }

    /**
     * Run the migrations.
     */
    public function up(): void
    {
        $schema = Schema::connection($this->getConnection());

        $schema->create('telescope_entries', function (Blueprint $table) {
            $table->bigIncrements('sequence');
            $table->uuid('uuid');
            $table->uuid('batch_id');
            $table->string('family_hash')->nullable();
            $table->boolean('should_display_on_index')->default(true);
            $table->string('type', 20);
            $table->longText('content');
            $table->dateTime('created_at')->nullable();

            $table->unique('uuid');
            $table->index('batch_id');
            $table->index('family_hash');
            $table->index('created_at');
            $table->index(['type', 'should_display_on_index']);
        });

        $schema->create('telescope_entries_tags', function (Blueprint $table) {
            $table->uuid('entry_uuid');
            $table->string('tag');

            $table->primary(['entry_uuid', 'tag']);
            $table->index('tag');

            $table->foreign('entry_uuid')
                  ->references('uuid')
                  ->on('telescope_entries')
                  ->onDelete('cascade');
        });

        $schema->create('telescope_monitoring', function (Blueprint $table) {
            $table->string('tag')->primary();
        });
    }

    /**
     * Reverse the migrations.
     */
    public function down(): void
    {
        $schema = Schema::connection($this->getConnection());

        $schema->dropIfExists('telescope_entries_tags');
        $schema->dropIfExists('telescope_entries');
        $schema->dropIfExists('telescope_monitoring');
    }
};

Which generates such SQL:

CREATE TABLE "telescope_entries" (
    "sequence" integer primary key autoincrement not null,
    "uuid" varchar not null,
    "batch_id" varchar not null,
    "family_hash" varchar,
    "should_display_on_index" tinyint(1) not null default '1',
    "type" varchar not null,
    "content" text not null,
    "created_at" datetime);

CREATE TABLE "telescope_entries_tags" (
    "entry_uuid" varchar not null,
    "tag" varchar not null,
foreign key("entry_uuid") references "telescope_entries"("uuid") on delete cascade,
primary key ("entry_uuid", "tag"));

CREATE TABLE "telescope_monitoring" (
    "tag" varchar not null,
    primary key ("tag"));

INSERT INTO "telescope_entries" ("sequence", "uuid", "batch_id", "family_hash", "should_display_on_index", "type", "content", "created_at") VALUES
('1', '9b9e8cb0-40d7-4146-b2fe-aed5b6e9a5a9', '9b9e8cb0-4b76-4bff-8130-cc526872d3fd', NULL, '1', 'query', '{"connection":"sqlite","bindings":[],"sql":"select exists (select 1 from pragma_compile_options where compile_options = ''ENABLE_DBSTAT_VTAB'') as enabled","time":"0.20","slow":false,"file":"\/github\/wayofdev\/_playground\/example-laravel-app\/artisan","line":13,"hash":"bbe479d6d8ae419144ed7d668fb48ce2","hostname":"ghosts-MacBook-Pro.local"}', '2024-03-21 20:24:34');

This file contains the schema for creating telescope_entries, telescope_entries_tags, and telescope_monitoring tables.

Converted ORM Entities

From the Laravel migration file, I've created the following annotated ORM entities:

For telescope_entries table:

<?php

declare(strict_types=1);

namespace WayOfDev\Cycle\Bridge\Telescope\Entities;

use Cycle\Annotated\Annotation\Column;
use Cycle\Annotated\Annotation\Entity;
use Cycle\Annotated\Annotation\Table\Index;
use DateTimeImmutable;

#[Index(columns: ['batch_id'])]
#[Index(columns: ['family_hash'])]
#[Index(columns: ['created_at'])]
#[Index(columns: ['type', 'should_display_on_index'])]
#[Entity(table: 'telescope_entries')]
class TelescopeEntry
{
    #[Column(type: 'bigInteger', primary: true)]
    public int $sequence;

    #[Column(type: 'uuid', unique: true)]
    public string $uuid;

    #[Column(type: 'uuid')]
    public string $batchId;

    #[Column(type: 'string', nullable: true)]
    public string $familyHash;

    #[Column(type: 'boolean', default: true)]
    public bool $shouldDisplayOnIndex;

    #[Column(type: 'string', size: 20)]
    public string $type;

    #[Column(type: 'longText')]
    public string $content;

    #[Column(type: 'datetime', nullable: true)]
    public ?DateTimeImmutable $createdAt;
}

For telescope_entry_tags table:

<?php

declare(strict_types=1);

namespace WayOfDev\Cycle\Bridge\Telescope\Entities;

use Cycle\Annotated\Annotation\Column;
use Cycle\Annotated\Annotation\Entity;
use Cycle\Annotated\Annotation\ForeignKey;
use Cycle\Annotated\Annotation\Table\Index;

#[Index(columns: ['entry_uuid', 'tag'])]
#[Index(columns: ['tag'])]
#[ForeignKey(target: 'telescope_entries', innerKey: 'entry_uuid', outerKey: 'uuid', action: 'CASCADE')]
#[Entity(table: 'telescope_entries_tags')]
class TelescopeEntryTags
{
    #[Column(type: 'uuid')]
    public string $entryUuid;

    #[Column(type: 'string')]
    public string $tag;
}

For telescope_monitoring table:

<?php

declare(strict_types=1);

namespace WayOfDev\Cycle\Bridge\Telescope\Entities;

use Cycle\Annotated\Annotation\Column;
use Cycle\Annotated\Annotation\Entity;

#[Entity(table: 'telescope_monitoring')]
class TelescopeMonitoring
{
    #[Column(type: 'string', primary: true)]
    public string $tag;
}

Issue with #[ForeignKey] Annotation

The problem arises when I use the #[ForeignKey] annotation in the TelescopeEntryTags class:

#[ForeignKey(target: 'telescope_entries', innerKey: 'entry_uuid', outerKey: 'uuid', action: 'CASCADE')]

Upon setting this line, I encounter an error with the following stack trace:

 FAILED  WayOfDev\Tests\Bridge\Telescope\Watchers\QueryWatcherTest > query watcher registers database queries                                                                  RegistryException   
  Undefined entity `telescope_entries`

  at vendor/cycle/schema-builder/src/Registry.php:85
     81▕                 return $entity;
     82▕             }
     83▕         }
     84▕ 
  ➜  85▕         throw new RegistryException("Undefined entity `{$role}`");
     86▕     }
     87▕ 
     88▕     public function getIterator(): Traversable
     89▕     {

  1   vendor/cycle/schema-builder/src/Registry.php:85
  2   vendor/cycle/annotated/src/Entities.php:195
  3   vendor/cycle/annotated/src/Entities.php:151
  4   vendor/cycle/annotated/src/Entities.php:98
  5   vendor/cycle/schema-builder/src/Compiler.php:45
  6   src/Schema/Compiler.php:22
  7   src/Bridge/Laravel/Console/Commands/ORM/MigrateCommand.php:66
  8   vendor/laravel/framework/src/Illuminate/Container/BoundMethod.php:36
  9   vendor/laravel/framework/src/Illuminate/Container/Util.php:41
  10  vendor/laravel/framework/src/Illuminate/Container/BoundMethod.php:93
  11  vendor/laravel/framework/src/Illuminate/Container/BoundMethod.php:35
  12  vendor/laravel/framework/src/Illuminate/Container/Container.php:662
  13  vendor/laravel/framework/src/Illuminate/Console/Command.php:212
  14  vendor/symfony/console/Command/Command.php:279
  15  vendor/laravel/framework/src/Illuminate/Console/Command.php:181
  16  vendor/symfony/console/Application.php:1031
  17  vendor/symfony/console/Application.php:318
  18  vendor/symfony/console/Application.php:169
  19  vendor/laravel/framework/src/Illuminate/Console/Application.php:162
  20  vendor/laravel/framework/src/Illuminate/Foundation/Console/Kernel.php:423
  21  tests/src/TestCase.php:73
  22  tests/src/TelescopeTestCase.php:35

Question

Am I implementing the foreign key relation correctly, or should it be approached differently? When I comment out the ForeignKey annotation, the migrations work without issues.

I appreciate any guidance or suggestions from the community. Thank you!

[lotyp]

Update: Found my issue, had to define target as FQDN class-name:

#[ForeignKey(target: TelescopeEntry::class, innerKey: 'entry_uuid', outerKey: 'uuid', action: 'CASCADE')]

Current workaround:

Is to define property and add HasMany annotation to it:

<?php

declare(strict_types=1);

namespace WayOfDev\Cycle\Bridge\Telescope\Entities;

use Cycle\Annotated\Annotation\Column;
use Cycle\Annotated\Annotation\Entity;
use Cycle\Annotated\Annotation\ForeignKey;
use Cycle\Annotated\Annotation\Relation\HasMany;
use Cycle\Annotated\Annotation\Table\Index;
use Illuminate\Support\Collection;

#[Index(columns: ['entry_uuid', 'tag'])]
#[Index(columns: ['tag'])]
// #[ForeignKey(target: 'telescope_entries', innerKey: 'entry_uuid', outerKey: 'uuid', action: 'CASCADE')]
#[Entity(table: 'telescope_entry_tags')]
class TelescopeEntryTags
{
    #[Column(type: 'uuid', primary: true)]
    public string $entryUuid;

    #[Column(type: 'string')]
    public string $tag;

    #[HasMany(target: TelescopeEntry::class, innerKey: 'entry_uuid', outerKey: 'uuid', fkAction: 'CASCADE')]
    public Collection $entries;
}