diff --git a/UPGRADE.md b/UPGRADE.md index ba4c2d70..36ce769f 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -1,378 +1,3 @@ # Upgrade Guide -## Upgrading to Socialstream 5.x - -> [!NOTE] -> This upgrade guide assumes you're coming from Socialstream 4.x - -### Changes - -#### Project dependencies - -Socialstream 5.x drops `laravel/jetstream`, and by extension, `laravel/fortify` as dependencies. -As a result, before you upgrade, you will need to add these dependencies to your projects' `composer.json` -file. - -Add `laravel/jetstream` to your project with composer: - -```shell -composer require laravel/jetstream -``` - -Upgrade Socialstream via composer: - -```shell -composer require joelbutcher/socialstream:^5.x -``` - -## Upgrading to Socialstream 4.x - -### Changes - -#### Native Type declarations - -Version 4.x updates the interfaces and published `php` files to use native type declarations. -Please ensure the following files have been updated to match their interface counterparts: - -``` -CreateConnectedAccount.php -CreateUserFromProvider.php -HandleInvalidState.php -ResolveSocialiteUser.php -SetUserPassword.php -UpdateConnectedAccount.php -``` - - -#### User Profile Photo - -If you have included the `HasProfilePhoto` trait in your user model, please update your model to the following: - -```diff - use HasProfilePhoto { -- getProfilePhotoUrlAttribute as getPhotoUrl; -+ profilePhotoUrl as getPhotoUrl; - } -``` - -And replace the `getProfilePhotoUrlAttribute` method in the model with: - -```php -/** - * Get the URL to the user's profile photo. - */ -public function profilePhotoUrl(): Attribute -{ - return filter_var($this->profile_photo_path, FILTER_VALIDATE_URL) - ? Attribute::get(fn () => $this->profile_photo_path) - : $this->getPhotoUrl(); -} -``` - -#### Changes to jetstream props in inertia - -If you're using Inertia, please update your `Profile/Show.vue` file to the following: - -```diff --29: -+29: -``` - -## Upgrading From Socialstream 2.x To Socialstream 3.x - -### Changes - -#### Disabling Socialstream - -To disable Socialstream in v3, you will need to update your existing `SocialstreamServiceProvider.php` to include the following code snippet in your providers `boot` method: - -```php - Socialstream::enabled(fn () => false); -``` - -The function accepts a callback so if you wanted to implement more complex logic, you may do so. - -> Note, the callback MUST return a boolean - -#### Providers - -V3 introduces a new `Providers` class, for defining what Socialite providers you have enabled in your config. This class is also used in the socialstream.blade.php stub and the connected-account.blade.php component stub. Please update any Socialite providers you have in your `socialstream.php` config file to use this class, e.g: - -```php -use \JoelButcher\Socialstream\Providers; - -return [ - // ... - - 'providers' => [ - Providers::google(), - Providers::facebook(), - ], - -]; -``` - -#### Remember Sessions - -V3 of Socialstream move the remember session config variable into the 'features' config array. During your upgrade, if you have previously set this config variable to `true`, you will need to add it to your features list. - -```php -return [ - // ... - - 'features' => [ - Features::rememberSession(), - ], - -]; -``` - -#### Token Column Lengths - -In version 3.x, we've fixed an issue with the length of tokens and refresh tokens being too long for the columns in the database. - -To fix this yourself, you should create a new `connected_accounts` migration: - -```sh -php artisan make:migration update_connected_accounts_token_lengths --table=connected_accounts -``` - -Once done, you should then add the following code to the `up` method: - -```php - $table->string('token', 1000)->change(); - $table->string('refresh_token', 1000)->change(); -``` - -#### Provider Avatars - -In v3, we've updated the provider avatars feature to download the avatar from the url provided by the Socialite user. If you have opted to use the `providerAvatars` feature in your config's features definition, you should add the `SetsProfilePhotoFromUrl` trait to your user model: - -```php -stateless()->user(); -``` - -To ensure v3 compatibility, copy the `ResolveSocialiteUser` action stub found [here](https://github.com/joelbutcher/socialstream/blob/3.x/stubs/app/Actions/Socialstream/ResolveSocialiteUser.php) to your `app/Actions/Socialstream` directory and add the following to your `app\Providers\SocialstreamServiceProvider.php`: - -```php -use App\Actions\Socialstream\ResolveSocialiteUser; -use JoelButcher\Socialstream\Socialstream; - -// Add this to the 'boot' method. -Socialstream::resolvesSocialiteUsersUsing(ResolveSocialiteUser::class); -``` - -## Upgrading From Socialstream 1.x To Socialstream 2.x - -### Changes - -#### Connected Account Details - -Version 2.x of Socialstream now captures more user data from a provider and saves them to your `connected_accounts` table. In order to correctly save this data, you will need to create a new migration to make the appropriate changes. - -To do this, you should create a new `connected_accounts` migration: - -```sh -php artisan make:migration update_connected_accounts_table --table=connected_accounts -``` - -The geneated migration should contain the following code: - -```php -string('name')->after('provider_name')->nullable(); - $table->string('nickname')->after('name')->nullable(); - $table->string('email')->after('nickname')->nullable(); - $table->string('telephone')->after('email')->nullable(); - $table->string('avatar_path')->after('telephone')->nullable(); - - $table->renameColumn('provider_name', 'provider'); - }); - } - - /** - * Reverse the migrations. - * - * @return void - */ - public function down() - { - Schema::table('connected_accounts', function (Blueprint $table) { - // Revert... - }); - } -} - -``` - -#### Create Connected Account Action - -Socialstream 2.x adds a new action for creating connected accounts on registration with a provider. You should copy the new [CreateConnectedAccount](https://github.com/joelbutcher/socialstream/blob/2.x/stubs/app/Actions/Socialstream/CreateConnectedAccount.php) action to the `App/Actions/Socialstream` directory in your project. - -You should then add the register the action with Socialstream by placing the following code into the `boot` method of your application's `SocialstreamServiceProvider`: - -```php -use App\Actions\Socialstream\CreateConnectedAccount; - -Socialstream::createConnectedAccountsUsing(CreateConnectedAccount::class); -``` - -#### Generate Provider Redirect Action - -Socialstream 2.x includes a new action to generate the redirects URI's used to authenticate with providers. - -You should then register this action with Socialstream by placing the following code into the `boot` method of your application's `SocialstreamServiceProvider`: - -```php -use App\Actions\Socialstream\GenerateRedirectForProvider; - -Socialstream::generatesProvidersRedirectsUsing(GenerateRedirectForProvider::class); -``` - -If you wish, you may override this action by writing your own. This may allow you to define `scopes` or additional parameters, such as a `response_type` for explicit grants. See below for an example. - -> Note: the action **MUST** implement the `JoelButcher\Socialstream\Contracts\GeneratesProviderRedirect` contract. - -```php -scopes(['*']) - ->with(['response_type' => 'token']) - ->redirect(); - } -} -``` - -### Connected Account Credentials - -For convenience, Socialstream now also provides a `Credentials` helper class which can be used for authenticating with additional provider API's (e.g. Facebook's Graph API). - -You may retrieve an instance of this class from a connected account: - -```php -$connectedAccount = \App\Models\ConnectedAccount::first(); - -$credentials = $connectedAccount->getCredentials(); -``` - -### Inertia Stack - - -#### Authentication Views - -To upgrade your application's authentication views to use the new Vue files from Jetstream 2.x, you should copy the [Jetstream auth files](https://github.com/laravel/jetstream/tree/2.x/stubs/inertia/resources/js/Pages/Auth), then the [Socialstream auth files](https://github.com/joelbutcher/socialstream/tree/2.x/stubs/inertia/resources/js/Pages/Auth) to the `resources/js/Pages/Auth` folder location. - -You will also need to copy the [Providers.vue](https://github.com/joelbutcher/socialstream/blob/2.x/stubs/inertia/resources/js/Socialstream/Providers.vue) file to the `resources/js/Socialstream` directory. - -However, if you wish to continue to render the Blade based authentication views, you should add the following code to the `boot` method of your application's `JetstreamServiceProvider` class: - -```php -use Illuminate\Support\Facades\Route; -use Laravel\Fortify\Fortify; - -Fortify::loginView(function () { - return view('auth/login', [ - 'canResetPassword' => Route::has('password.request'), - 'status' => session('status'), - ]); -}); - -Fortify::requestPasswordResetLinkView(function () { - return view('auth/forgot-password', [ - 'status' => session('status'), - ]); -}); - -Fortify::resetPasswordView(function (Request $request) { - return view('auth/reset-password', [ - 'email' => $request->input('email'), - 'token' => $request->route('token'), - ]); -}); - -Fortify::registerView(function () { - return view('auth/register'); -}); - -Fortify::verifyEmailView(function () { - return view('auth/verify-email', [ - 'status' => session('status'), - ]); -}); - -Fortify::twoFactorChallengeView(function () { - return view('auth/two-factor-challenge'); -}); - -Fortify::confirmPasswordView(function () { - return view('auth/confirm-password'); -}); -``` +The Upgrade Guide has moved to the [official documentation](https://docs.socialstream.dev/prologue/upgrade-guide).