SDSM:Pending Changes

This document consists of multiple parts; for a directory to all of the parts, see SDSM:Index.

Description

This part of the SDS Modernization (SDSM) document enumerates a not necessarily exhaustive list of pending changes or improvements that were made to SDS, made by Darren Duncan if by whom is not otherwise specified.

It is similar to the Historical Changes part but that it describes work which was prepared and published in a Git branch but it was deemed premature to merge it to the trunk, such as due to a desire for more testing first, or because it was possibly unfinished; in contrast, Historical is for work that was merged to trunk.

RETURN

SDS Laravel: Changes to Third-Party Dependencies

2024 Jun 17: Upgrade To Laravel 10 and Vue 3

Summary of PHP Dependency Upgrades or Removals

This task updated composer.json to require the latest PHP-8.1-compatible versions of all PHP library dependencies, in particular taking Laravel from 8.x to 10.x.

To be specific, it made these dependency changes:

• barryvdh/laravel-debugbar (^3.7 to ^3.13.5)
• directorytree/ldaprecord-laravel (^2.7.3 to ^3.3.3)
• etern8ty/beanstream (dev-master unchanged and is custom fork)
• fakerphp/faker (^1.23.1 unchanged)
• fideloper/proxy (^4.4.2 removed as laravel/framework has its upgrade built-in)
• goldspecdigital/laravel-eloquent-uuid (^8.0.1 removed as laravel/framework has its upgrade built-in)
• guzzlehttp/guzzle (^7.8.1 unchanged)
• intervention/image (^2.7.2 removed as intervention/image-laravel is its upgrade)
• intervention/image-laravel (^1.3 added)
• juliomotol/laravel-auth-timeout (^3.1.1 to ^4.1)
• lab404/laravel-impersonate (^1.7.5 unchanged)
• laravel/framework (^8.83.27 to ^10.48.13)
• laravel/helpers (^1.7 removed as laravel/framework has its upgrade built-in)
• laravel/tinker (^2.9 unchanged)
• laravel/ui (^3.4.6 to 4.5.2; but it recommends using Laravel Breeze or Laravel Jetstream instead)
• mockery/mockery (^1.6.12 unchanged)
• nunomaduro/collision (^5.11 to ^7.10)
• phpunit/phpunit (^10.5.20 to ^10.5.22)
• spatie/laravel-ignition (^1.6.4 to ^2.8)
• staudenmeir/eloquent-has-many-deep (^1.14.4 to ^1.19.4)

RETURN

Summary of JavaScript Dependency Upgrades or Removals

This task updated package.json to require the latest versions of all JavaScript library dependencies, in particular taking Vue from 2.x to 3.x.

To be specific, it made these dependency changes:

• @fortawesome/fontawesome-free (^5.15.4 unchanged)
• axios (^0.27.2 unchanged)
• bootstrap (^4.6.2 unchanged)
• bootstrap-select (^1.13.18 unchanged)
• cross-env (^7.0.3 unchanged)
• font-awesome (^4.7.0 unchanged)
• jquery (^3.7.1 unchanged)
• jquery-ui (^1.13.3 unchanged)
• laravel-mix (^5.0.9 unchanged)
• lodash (^4.17.21 unchanged)
• moment (^2.30.1 unchanged)
• popper.js (^1.16.1 unchanged)
• resolve-url-loader (^3.1.5 unchanged)
• sass (^1.77.4 unchanged)
• sass-loader (^8.0.2 unchanged)
• tempusdominus-bootstrap-4 (^5.39.2 unchanged)
• tempusdominus-core (^5.19.3 unchanged)
• vue (^2.7.16 unchanged)
• vue-bootstrap-datetimepicker (^5.0.1 unchanged)
• vue-template-compiler (^2.7.16 unchanged)

RETURN

Specify Minimum PHP Dependency Versions Used Are Stable

This task updated composer.json to specify an app default minimum-stability of stable rather than dev.

This is per the Laravel 10 upgrading recommendation:

• https://laravel.com/docs/10.x/upgrade#updating-minimum-stability

While the setting could instead have been removed as stable is its default, being explicit seemed better here.

Note that this didn't cause any changes to what PHP library versions are actually installed by Composer versus the old setting, but is a good constraint going forward.

RETURN

Changes For laravel/framework Upgrade's Removal of "dates" Model Attribute

This task also updated 51 PHP source files to be compatible with a breaking change made by Laravel itself with version 10.

Laravel supported a "dates" model attribute through version 9, and then Laravel 10 removed it. The function of this was to enumerate database/model fields that were supposed to be automatically converted to Carbon DateTime objects; so under Laravel 8, any "dates" declarations would be respected, while under Laravel 10 they would be ignored.

See also:

• https://laravel.com/docs/10.x/upgrade#model-dates-property

Compare:

• https://laravel.com/api/9.x/Illuminate/Database/Eloquent/Concerns/HasAttributes.html
• https://laravel.com/api/10.x/Illuminate/Database/Eloquent/Concerns/HasAttributes.html

As a result, simply upgrading SDS Laravel from Laravel 8 to 10 resulted in many parts of the app breaking in various ways including when simply visiting the post-login home screen, as PHP died with errors like Call to a member function format() on int.

To fix this, any instances of protected $dates = ['x',...] in model classes were replaced with protected $casts = ['x'=>'datetime',...] which was the more modern way to get the same functionality, which exists in both Laravel 8 and 10. For the few model classes that already had other $casts declarations, the replacements were merged with those.

While the "dates" change could have been its own task that was merged to trunk prior to and separately from the current Laravel 10 upgrade task, it was combined with the latter to streamline testing, as both had potential impacts over a large fraction of the app.

RETURN

Changes For laravel/framework Upgrade's Miscellaneous Changes

This task also updated app/Providers/AuthServiceProvider.php to remove the call $this->registerPolicies(); from boot()because Laravel 10 now calls it automatically, as recommended here:

• https://laravel.com/docs/10.x/upgrade#register-policies

RETURN

Changes For league/flysystem Indirect Upgrade

This task also updated app/Http/Controllers/Admin/Migration/ImportPhotosController.php to be compatible with the league/flysystem upgrade from version 1 to version 3 that was indirect by way of the Laravel 9 upgrade.

See also for context:

• https://flysystem.thephpleague.com/docs/upgrade-from-1.x/
• https://laravel.com/docs/9.x/upgrade#flysystem-3

There were 3 substitutions for compatibility in the store function.

There was 1 like this:

   Storage::disk('photos')->getMimeType($file)

   Storage::disk('photos')->mimeType($file)

And there were 2 like this:

   Storage::disk('photos')->getDriver()->getAdapter()->applyPathPrefix($file);

   Storage::disk('photos')->path($file);

This task also updated config/filesystems.php to add the element 'throw' => true to each disks element. This is to help preserve Laravel 8 behavior that we might have been relying on when a write operation fails. For example, write operations such as write by default no longer throw an exception when a write operation fails and instead returns false; until we can audit our code for how we currently check for such failures, this config change should make it less likely our code was broken by the dependency update.

Note that there are still other kinds of default behavior changes that we should audit our code for handling of. For example, write operations will overwrite existing files by default, so if we don't want that then we should explicitly be checking for their existence first. Also, reading a nonexisting file now returns null rather than an exception.

RETURN

Bug/Security Fixes In Photos Import

This task also updated the 2 files app/Http/Controllers/Admin/Migration/ImportPhotosController.php plus resources/views/admin/migration/import_photos/index.blade.php to fix bugs tangential to the image file path handling.

One fix was in the index function so that the directory path reported to the user was the same one that store actually used, from Storage::disk('photos'), rather than being either of a couple of hard-coded alternatives toggled on an environment variable that isn't actually used.

A second fix was to stop passing a path hidden form field value from index to store, whose value was set from the incorrect path in index, and which store validated as present and subsequently didn't use. Besides being dead code from the disuse, if this had been used it would have been a major security vulnerability, as it would have let web clients directly control actions against server local file system paths.

RETURN

Changes For laravel/helpers Removal

This task also updated these 4 PHP source files to be compatible with the replacement of laravel/helpers with a Laravel built-in:

• app/Http/Controllers/Auth/RegisterController.php
• resources/views/admin/subjects/edit_rotating_courses/show.blade.php
• resources/views/student/student_mark_collections/edit.blade.php
• resources/views/student/student_mark_collections/show.blade.php

For each of the above 4 files, there were either of these 3 subsitutions:

   str_contains(...)
   str_random(...)
   str_replace_array(...)

   Str::contains(...)
   Str::random(...)
   Str::replaceArray(...)

Note that laravel/helpers was just a single PHP source file providing trivially thin wrapper functions over laravel/framework 6+ built-ins that emulated ones from Laravel 5.8, and we were already mostly using the newer versions, so this task just replaced the last 7 instances where we weren't.

RETURN

Changes For goldspecdigital/laravel-eloquent-uuid Removal

This task also updated these 5 PHP source files to be compatible with the replacement of goldspecdigital/laravel-eloquent-uuid with a Laravel built-in:

• app/Models/Application/Application.php
• app/Models/User.php
• app/Models/User/Student.php
• app/Models/User/Teacher.php
• app/Models/User/UserContract.php

These further 3 files also referenced the trait but commented out, so not current users but possible past or future users:

• app/Models/Application/AppUser.php
• app/Models/User/Address.php
• app/Models/User/Guardian.php

For each of the above 8 files, there were these 2 line subsitutions:

   use GoldSpecDigital\LaravelEloquentUUID\Database\Eloquent\Uuid;
   use Uuid;

   use Illuminate\Database\Eloquent\Concerns\HasUuids;
   use HasUuids;

Here is a description of the above built-in feature in Laravel 9.3+:

https://laravel.com/docs/11.x/eloquent#uuid-and-ulid-keys

The purpose of that reimplemented functionality was to empower use of generated UUIDs for primary key fields of some database tables instead of the serially generated integers that SDS Laravel more typically uses; Laravel Eloquent only gained built-in support for UUIDs with version 9.3.

This task also deleted the single PHP file app/Models/Traits/Uuids.php as it appeared to be unused.

RETURN

Changes For fideloper/proxy Removal

This task also updated app/Http/Middleware/TrustProxies.php to be compatible with the replacement of fideloper/proxy with a Laravel built-in. The changes were in 2 spots.

First was this substitution:

   use Fideloper\Proxy\TrustProxies as Middleware;

   use Illuminate\Http\Middleware\TrustProxies as Middleware;

Second was this substitution:

   protected $headers = Request::HEADER_X_FORWARDED_ALL;

   protected $headers =
       Request::HEADER_X_FORWARDED_FOR |
       Request::HEADER_X_FORWARDED_HOST |
       Request::HEADER_X_FORWARDED_PORT |
       Request::HEADER_X_FORWARDED_PROTO |
       Request::HEADER_X_FORWARDED_AWS_ELB;

See also https://laravel.com/docs/9.x/upgrade under "Trusted Proxies".

RETURN

Changes For juliomotol/laravel-auth-timeout Upgrade

This task also updated app/Http/Middleware/AuthTimeoutMiddleware.php to be compatible with the juliomotol/laravel-auth-timeout upgrade.

There was this 1 substitution:

   use JulioMotol\AuthTimeout\Middleware\AuthTimeoutMiddleware as BaseMiddleware;

   use JulioMotol\AuthTimeout\Middlewares\CheckAuthTimeout as BaseMiddleware;

Note that juliomotol/laravel-auth-timeout must be upgraded simultaneously with Laravel since the former's versions 3.1.1 and 4.1 respectively require Laravel 8 and 10 respectively.

See https://github.com/juliomotol/laravel-auth-timeout/blob/master/CHANGELOG.md for more change details and upgrade notes on that.

RETURN

Changes For directorytree/ldaprecord-laravel Upgrade

This task also made 3 distinct sets of changes to be compatible with the directorytree/ldaprecord-laravel upgrade.

See also for context:

• https://ldaprecord.com/docs/laravel/v3/upgrading/
• https://ldaprecord.com/docs/laravel/v3/release-notes/
• https://github.com/DirectoryTree/LdapRecord-Laravel/releases

The first set of changes...

This task updated the 1 PHP config source file config/ldap.php to account for logging now being an array. There was this 1 substitution:

   'logging' => env('LDAP_LOGGING', true),

   'logging' => [
       'enabled' => env('LDAP_LOGGING', true),
   ],

The second set of changes...

For context, directorytree/ldaprecord-laravel had a PHP trait named LdapRecord\Laravel\Auth\MultiDomainAuthentication which was deprecated before version 2.7.3 and removed in version 3.0.0. The 1 SDS PHP source file app/Http/Controllers/Auth/LoginController.php used that trait.

This task updated LoginController to clone into itself the used portions of MultiDomainAuthentication, thus removing the external dependency of the former on the latter.

As the removed trait was itself a sub-trait of LdapRecord\Laravel\Auth\CreatesUserProvider, LoginController now composed that directly and not indirectly.

Also LoginController gained the new protected function getLdapGuard cloned from the removed trait.

Note that the function getLdapGuardFromRequest was not cloned from the removed trait since LoginController already had its own version that overrode it.

The third set of changes...

For context, each of these 5 SDS classes composed one of the 2 classes LdapRecord\Models\Model or LdapRecord\Models\Scope:

• app/Ldap/ExternalUser.php
• app/Ldap/Scopes/OnlyStaffUsers.php
• app/Ldap/Scopes/OnlyStudents.php
• app/Ldap/SmusStudents.php
• app/Ldap/SmusUser.php

For each of those 5, it was updated such that for any property or method it contained which overrode or implemented a same-named one from Model or Scope, that property or method had explicit type annotations added to match the originals. This was required for the SDS code to satisfy a PHP or Laravel stricture so the code runs.

RETURN

Changes For intervention/image Upgrade

This task also made 2 distinct sets of changes to be compatible with the intervention/image upgrade.

For context, as part of the major update of intervention/image from version 2.x to 3.x, it was also split up into multiple libraries, with the core remaining under the old name and the optional Laravel-specific add-ons being in the new intervention/image-laravel library. We only need to directly require the latter, which brings in the former.

See also for context:

• https://image.intervention.io/v3/introduction/upgrade
• https://github.com/Intervention/image-laravel/blob/main/README.md
• https://image.intervention.io/v3/modifying/resizing

The first set of changes...

This task added the 1 PHP config source file config/image.php that is standard per the above-linked README.

The second set of changes...

This task replaced the use of the no longer existing PHP class Intervention\Image\ImageServiceProvider with the existing Intervention\Image\Laravel\Facades\Image.

In addition, the class is now used directly by its full name in the 2 PHP source files where the image handling functionality is actually used, which are app/Models/File.php and app/Http/Controllers/Admin/Migration/ImportPhotosController.php. This task has purged any explicit registration in config/app.php of any class of this library in providers or aliases; the Image alias is now purged.

The PHP source code that directly used the Intervention Image libraries was updated for compatibility with several method renames or substitutions.

Changes were made to reflect the rename of the library static method make to read.

Changes were made to reflect the changes with the set of image manipulation methods for image resizing. The resize method of version 2 had taken a third argument by which one specified the resize should keep the original aspect ratio. The resize method of version 3 doesn't take that argument, and instead the version 3 method scale is explicitly for resizing that maintains the aspect ratio.

RETURN

SDS Laravel Documentation Changes

This task updated composer.json to update primary documentation attributes so they describe the actual SDS application this is rather than the Laravel template used to build it.

There were these substitutions:

   "name": "laravel/laravel",
   "description": "The Laravel Framework.",
   "keywords": ["framework","laravel"],

   "name": "smus/sds",
   "description": "School Data System (SDS)",
   "keywords": [],

This task also completely rewrote README.md so it describes this SDS application rather than the Laravel framework.

RETURN