Maintenance: Upgrade to Laravel 10

[ardelato]

Description

Most of the changes were automatically created by Laravel Shift. There were some additional tweaks that needed to be made in order to get things working.

Note

The referenced commits/links may not be correct as I had to rebase and use the commits from -- iFixit#2

Shift Output

This pull request includes the changes for upgrading to Laravel 10.x.

Before merging, you need to:

• Checkout the this branch branch
• Review all pull request comments for additional changes
• Run composer update (if the scripts fail, try with --no-scripts)
• Clear any config, route, or view cache
• Thoroughly test your application (no tests?, no CI?)

If you need help with your upgrade, check out the Human Shifts.

1. ℹ️ Starting with Laravel 10, the lang folder is no longer included in a default Laravel application. Laravel now recursively merges any customizations with framework defaults.

Shift streamlined your language files by removing options that matched the Laravel defaults and preserving your customizations. If you wish to keep the full set of language, Shift recommends running artisan lang:publish --force to get the latest configuration files from Laravel, then reapplying the customizations Shift streamlined.

2. ℹ️ Laravel 10 deprecated the ImplicitRule, InvokableRule, and Rule contracts in favor of using the new, streamlined ValidationRule contract. These contracts will be removed in a future version of Laravel.

Given the change in the method names and return type, Shift can not reliably automate this change. At your convenience, you should review these custom validation rules and update them to implement the ValidationRule contract.

• app/Rules/Timezone.php

3. ⚠️ Early versions of Laravel 9 included a lang/en.json file containing password validation messages. However, this file was quickly removed in favor of keeping this with the other validation rules in validation.php.

Shift detected your version differed from the default Laravel version. If you have customized the password validation messages, you should merge them with the password messages in validation.php and remove lang/en.json.

4. ⚠️ Shift upgraded your configuration files by defaulting them and merging your true customizations. These include values which are not changeable through core ENV variables.

You should review this commit for additional customizations or opportunities to use new ENV variables. If you have a lot of customizations, you may undo this commit with git revert 422343d4 and make the config file changes manually.

5. ℹ️ Laravel 10 now verifies hashed values were created by the same hashing algorithm. If your application has hashed values created by different hashing algorithms, you may set the verify option to false in your hashing configuration. For more details, you may review the original PR.

6. ℹ️ Shift updated your dependencies for Laravel 10. While many of the popular packages are reviewed, you may have to update additional packages in order for your application to be compatible with Laravel 10. Watch dealing with dependencies for tips on handling any Composer issues.

The following dependencies were updated by a major version and may have their own changes. You may check their changelog for any additional upgrade steps.

• addwiki/mediawiki-api
• doctrine/dbal
• laravel/dusk
• laravel/ui
• owen-it/laravel-auditing
• sentry/sentry-laravel

The following dependencies were not updated by Shift and may be incompatible. If Composer lists one of these packages as a problem, you should check for a newer version.

• addwiki/mediawiki-api-base
• hieu-le/wordpress-xmlrpc-client
• mcamara/laravel-localization
• wouternl/laravel-drip

7. ℹ️ Shift detected your application has a test suite. To allow you to verify the upgrade in isolation, Shift did not bump your testing dependencies for PHPUnit 10. Once you have completed your upgrade, you may run the PHPUnit 10 Shift for free to upgrade your test suite to PHPUnit 10 separately.

8. ℹ️ Laravel 9 adopted anonymous migrations. Shift automated this change to align with modern Laravel conventions and avoid naming migrations.

9. ℹ️ Laravel renamed the password_resets table to password_reset_tokens. While an optional change, Shift detected you have a migration for the original table and created a migration to rename the table. You should check for any additional references to the password_resets table and run php artisan migrate to complete your upgrade.

10. ⚠️ Laravel 10 has added a return type of array to the Event broadcastOn and Notification via methods. However, you may still return a single channel from these methods.

Shift added the array return type to these methods in the following classes. You should review them to ensure you are returning an array, or remove the return type.

• app/Events/EventDeleted.php
• app/Events/UserEmailUpdated.php
• app/Events/UserLanguageUpdated.php
• app/Events/UserRegistered.php
• app/Notifications/BaseNotification.php
• app/Notifications/EventConfirmed.php
• app/Notifications/EventDevices.php
• app/Notifications/GroupConfirmed.php
• app/Notifications/JoinEvent.php
• app/Notifications/JoinGroup.php
• app/Notifications/ResetPassword.php

11. ℹ️ Laravel 10 added PHP type hints to all user-land code included in a new Laravel application. In an effort to modernize your code, Shift added type hints to any method which is used by Laravel.

12. ℹ️ Now with type hints in your code, defining types within PHP DocBlocks is redundant. Laravel has removed all of the @param and @return tags from its DocBlocks where types are defined with PHP. Similarly, Shift removed these tags from any DocBlock where the code now has equivalent type hints.

13. ℹ️ Shift understands developers have different preferences when it comes to type hints. All of Shift's automation is done in nice, atomic commits. This makes it easier to undo any of the changes Shift makes.

If you wish to undo the changes relating to type hints, you may run:

• git revert eb6605d9cd to revert the DocBlock changes.
• git revert cc190c3a99 to revert the type hints added from DocBlocks.
• git revert bf39c4a7eb to revert the type hints added for Laravel 10.

14. ⚠️ In Laravel 10 you may no longer implicitly cast a DB::raw() expression to a string. Instead, you must retrieve the string value from the expression using the getValue() method. Query builder methods will continue to automatically handle DB::raw() expressions as before. This change only affects instances where you are using DB::raw() expressions in your own code.

Shift detected calls to DB::raw(). You should review these instances to see if you are attempting to use them as a string.

• app/Category.php
• app/Console/Commands/FixViews.php
• app/Device.php
• app/Group.php
• app/Helpers/Fixometer.php
• app/Helpers/FixometerFile.php
• app/Helpers/LcaStats.php
• app/Party.php
• app/Role.php
• app/Session.php
• app/User.php
• app/UserGroups.php
• app/Xref.php
• database/migrations/2020_10_21_121813_alter_table_charsets.php
• database/migrations/2021_08_13_000439_update_lca_unpowered_categories.php
• database/migrations/2022_01_24_101405_timezones.php
• database/migrations/2022_11_07_152558_record_approval.php
• database/migrations/2023_06_07_130653_new_zealand.php
• database/migrations/2023_06_12_153317_country_codes.php
• database/migrations/2023_08_02_183803_item_type_collation.php
• tests/Feature/Events/ModerationEventPhotosNotificationTest.php
• tests/Feature/Groups/GroupEditTest.php
• tests/Feature/Networks/APIv2NetworkTest.php

15. ℹ️ All of the underlying Symfony components used by Laravel have been upgraded to Symfony 6.2. Shift detected references to Symfony classes within your application. These are most likely type hints and can safely be ignored. If you are using Symfony classes directly or experience issues relating to Symfony, you should review the Symfony change log for any additional changes.

16. ℹ️ The app/Models folder was reintroduced in Laravel 8. This was an optional change. Laravel and the artisan commands will automatically detect if you are using the app/Models folder or not.

If you wish to modernize your application to use the app/Models folder, you may run the Namespace Models Shift for free.

17. ℹ️ Laravel began using Vite to build frontend assets in Laravel 9.19. While you may continue to use Laravel Mix, it is no longer the default. If you wish to modernize your application to use Vite, you may run the Vite Converter for free.

18. ⚠️ Laravel 10 requires Composer 2.2 or higher. You should verify the Composer version in your environments by running composer --version to ensure it meets this new requirement. If necessary, run composer self-update to update Composer.

19. ⚠️ Laravel 10 requires PHP 8.1 or higher. You should verify the PHP version in your environments to ensure it meets this new requirement.

20. ⚠️ Laravel 10. has reached end of life. It no longer receives bug fixes or security updates. Shift recommends continuing to upgrade to the latest version (Laravel 12.x).

CR Notes

Outside of the Laravel Shift changes, I tried to explain the reasoning for each change in the commit messages.

All the changes are related to the action items described in the Shift output. I condensed the action items into a list and added notes to provide additional context on some of the changes.

Laravel Shift Action Items

Laravel 10 Upgrade Action Items

Validation Rules

• Update app/Rules/Timezone.php to implement the new ValidationRule contract instead of the deprecated contracts
  • Note: The class is imported in GroupController.php but not actually used directly. Both GroupController.php and EventController.php use manual timezone validation.

Password Validation

• Merge password validation messages from lang/en.json into validation.php
• Remove lang/en.json after merging
  • Note: We don't actually have a validation.php file for lang/en.json but we do have an auth.php file that only has a single message for mismatched and less than 6 character password failure message.
  • This isn't a current problem since we have very lax password requirements, but we should probably address this in the future.

Hashing Configuration

• Review hashing configuration and check if your app uses multiple hashing algorithms
  • Set verify option to false in hashing config if needed
  • Note: There is both Laravel's Hash facade (bcrypt) and a custom MD5 crypt mechanism being used

Event & Notification Return Types

Fix array return type in the following files:

• app/Events/EventDeleted.php
• app/Events/UserEmailUpdated.php
• app/Events/UserLanguageUpdated.php
• app/Events/UserRegistered.php
• app/Notifications/BaseNotification.php
• app/Notifications/EventConfirmed.php
• app/Notifications/EventDevices.php
• app/Notifications/GroupConfirmed.php
• app/Notifications/JoinEvent.php
• app/Notifications/JoinGroup.php
• app/Notifications/ResetPassword.php
  • Note: The Event classes were returning a single channel in their broadcastOn() method instead of an array. We updated them to return arrays.
  • The Notification classes were already using the correct array return type in their via() methods.

DB::raw() Usage Fixes

Replace DB::statement(DB::raw('query')) with DB::statement('query') and DB::select(DB::raw('query')) with DB::select('query').
For direct string uses of DB::raw, add ->getValue() method.

• database/migrations/2020_10_21_121813_alter_table_charsets.php
• database/migrations/2021_08_13_000439_update_lca_unpowered_categories.php
• database/migrations/2022_01_24_101405_timezones.php
• database/migrations/2022_11_07_152558_record_approval.php
• database/migrations/2023_06_07_130653_new_zealand.php
• database/migrations/2023_06_12_153317_country_codes.php
• database/migrations/2023_08_02_183803_item_type_collation.php
• tests/Feature/Networks/APIv2NetworkTest.php
• tests/Feature/Events/ModerationEventPhotosNotificationTest.php
• app/Category.php
• app/Console/Commands/FixViews.php
• app/Device.php
• app/Group.php
• app/Helpers/Fixometer.php
• app/Helpers/FixometerFile.php
• app/Helpers/LcaStats.php
• app/Party.php
• app/Role.php
• app/Session.php
• app/User.php
• app/UserGroups.php
• app/Xref.php
• tests/Feature/Groups/GroupEditTest.php

Dependencies

• Remove, patch, or switch the wouternl/laravel-drip package
• Remove, patch, or switch the php-coveralls package

Database Migrations

• Run php artisan migrate to complete table renaming

Environment Requirements

• Verify Composer 2.2+ is installed in all environments
• Verify PHP 8.1+ is installed in all environments

Notes

• For DB::raw issue, use one of these approaches:
  • For DB::statement(DB::raw('query')) → DB::statement('query')
  • For DB::select(DB::raw('query')) → DB::select('query')
  • For string interpolation in SQL, replace 'SELECT * FROM '.$table.'' with "SELECT * FROM {$table}"
  • For direct string uses of DB::raw, add ->getValue(): $someVar = DB::raw('EXPRESSION')->getValue()

Some additional things to note, I did not address item 16 and 17 in this pull, but I will do so in a follow up pull.

16. The `app/Models` folder was reintroduced in Laravel 8. This was an _optional_ change. Laravel and the `artisan` commands will automatically detect if you are using the `app/Models` folder or not.

17. Laravel began using Vite to build frontend assets in Laravel 9.19. While you may continue to use Laravel Mix, it is no longer the default. If you wish to modernize your application to use Vite, you may run the [Vite Converter](https://laravelshift.com/convert-laravel-mix-to-vite) for free.

[sonarqubecloud]

Quality Gate failed

Failed conditions
32.5% Duplication on New Code (required ≤ 3%)
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

[github-advanced-security]

SonarCloud found more than 20 potential problems in the proposed changes. Check the Files changed tab for more details.

[ardelato]

Somethings to note:

1. I did not apply the changes from the composer update as we removed Drip and PHP Coveralls -- iFixit/restarters@c633844 (#2)
2. I did not apply the changes to consolidating the password hashing methodologies as I am not sure if this is something you guys intended on addressing
   iFixit/restarters@f5f6c85 (#2)

[edwh]

@ardelato Just to let you know I'm going to sort out the move to vite.