No migration template in the UPGRADE guide

[korridor]

Passport Version

12.*

Laravel Version

12.19.3

PHP Version

8.3.22

Database Driver & Version

No response

Description

There is not migration template for the upgrade from 12 to 13.
I think there is already a migration template in #1797 (comment) that looks promising. It would really help if this would be in the upgrade guide or copied into the upgrade guide.

If you are interested I can provide a PR.

Steps To Reproduce

1. Upgrade from Passport 12 to 13
2. Database structure is not up-to-date anymore

[hafezdivandari]

I had the upgrade guide entry for DB changes in the early stages (check this: 6aeb388) but we decided to go with backward compatible DB changes, so the upgarde guide entry was removed as it was not necessary anymore.

[korridor]

@hafezdivandari I had problems with the old table structure, but more importantly supporting using two pretty different table structures seams like a short-sighted solution to a long term problem. I personally rather have the table structure that the main developers of the library also use primarily, but if this is not possible I'll just write one for myself or create bug reports for the problems that I had with the old structure.

[korridor]

I now created the following migrations, I hope they help someone else and I'm open to feedback:

remove_oauth_personal_access_clients_table

public function up(): void
{
    Schema::drop('oauth_personal_access_clients');
}

public function down(): void
{
    Schema::create('oauth_personal_access_clients', function (Blueprint $table): void {
        $table->bigIncrements('id');
        $table->uuid('client_id');
        $table->foreign('client_id')
            ->references('id')
            ->on('oauth_clients')
            ->onDelete('restrict')
            ->onUpdate('cascade');
        $table->timestamps();
    });
}

update_oauth_clients_table

public function up(): void
{
    DB::table('oauth_clients')->update(['provider' => 'users']); // Change default provider if necessary

    Schema::table('oauth_clients', function (Blueprint $table): void {
        $table->text('grant_types')->default('[]')->after('provider');
        $table->text('redirect_uris')->default('[]');
        $table->renameColumn('user_id', 'owner_id');
        $table->string('owner_type')->after('owner_id')->nullable();
    });

    DB::table('oauth_clients')
        ->where('redirect', '=', 'http://localhost')
        ->where('personal_access_client', '=', true)
        ->update(['redirect' => '']);

    DB::table('oauth_clients')
        ->whereNotNull('owner_id')
        ->update(['owner_type' => 'user']); // Value might be class name of the owner model, depends on if you use "enforceMorphMap"

    DB::table('oauth_clients')->eachById(function ($client): void {
        $grantTypes = ['urn:ietf:params:oauth:grant-type:device_code', 'refresh_token'];
        $confidential = ! empty($client->secret);
        $noRedirect = empty($client->redirect);
        $redirectUris = $noRedirect ? [] : [$client->redirect];
        $firstParty = empty($client->owner_id);

        if (! $noRedirect) {
            $grantTypes[] = 'authorization_code';
            $grantTypes[] = 'implicit';
        }

        if ($confidential && $firstParty) {
            $grantTypes[] = 'client_credentials';
        }

        if ($client->personal_access_client && $confidential) {
            $grantTypes[] = 'personal_access';
        }

        if ($client->password_client) {
            $grantTypes[] = 'password';
        }

        DB::table('oauth_clients')
            ->where('id', $client->id)
            ->update([
                'redirect_uris' => $redirectUris,
                'grant_types' => $grantTypes,
            ]);
    });

    Schema::table('oauth_clients', function (Blueprint $table): void {
        $table->dropForeign(['user_id']);
        $table->index(['owner_id', 'owner_type']);
        $table->dropColumn('redirect');
        $table->dropColumn('personal_access_client');
        $table->dropColumn('password_client');
    });
}

public function down(): void
{
    Schema::table('oauth_clients', function (Blueprint $table): void {
        $table->dropIndex(['owner_id', 'owner_type']);
        $table->renameColumn('owner_id', 'user_id');
        $table->foreign('user_id')
            ->on('users')
            ->references('id')
            ->onDelete('cascade')
            ->onUpdate('cascade');
        $table->string('redirect')->nullable();
        $table->boolean('personal_access_client')->default(false);
        $table->boolean('password_client')->default(false);
    });

    DB::table('oauth_clients')->eachById(function ($client): void {
        $redirectUris = json_decode($client->redirect_uris);
        $grantTypes = json_decode($client->grant_types);

        DB::table('oauth_clients')
            ->where('id', $client->id)
            ->update([
                'redirect' => $redirectUris[0] ?? '', // redirect not nullable
                'password_client' => in_array('password', $grantTypes, true)
                    && in_array('refresh_token', $grantTypes, true),
                'personal_access_client' => in_array('personal_access', $grantTypes, true),
            ]);
    });

    Schema::table('oauth_clients', function (Blueprint $table): void {
        $table->dropColumn(['grant_types', 'redirect_uris', 'owner_type']);
        $table->string('redirect')->nullable(false)->change();
        $table->boolean('personal_access_client')->default(null)->change();
        $table->boolean('password_client')->default(null)->change();
    });

}

hash_oauth_clients

public function up(): void
{
    // This could be optimized to run all the updates in the eachById
    DB::table('oauth_clients')->whereNotNull('secret')->eachById(function ($client): void {
        $secret = $client->secret;
        if (Hash::isHashed($secret) && ! Hash::needsRehash($secret)) {
            return; // Already hashed and not needing rehash
        }
        DB::table('oauth_clients')
            ->where('id', $client->id)
            ->update([
                'secret' => Hash::make($secret),
            ]);
    });
}

public function down(): void
{
    // This can not be reversed without a backup of the original secrets, for security reasons.
}

If the maintainers are interested I can create a PR to add this to the upgrade guide or wherever you want to have it.