Meta: retire old functions in functions.php

[yookoala]

Problem

There are roughly 4 types of functions in functions.php:

1. Old style database reading functions with old school $guid and/or $connection2 (\PDO) as parameter.
2. HTML element rendering.
3. Utility functions for formatting (e.g. email body sanitation) or other helper functions (e.g. resolving client IP address).
4. Shortcut for accessing core service feature (e.g. __(), __n(), __m()).

The first type of function cause usage of all the global $guid and $connection2, which is an anti-pattern when transiting to service container architecture.

Proposed Solution

1. The first type should be rewritten into Gateway service method (or, in some case, rewritten as service provider).
2. The second type should be rewritten into Form component or other Outputable class.
3. The thrid type can be rewritten as static methods of some utility classes.
4. The forth type can be left as-is for now.

In the rewrite, all obsoleted functions should not be removed for now. Instead, they are to be marked deprecated in their phpdocs doc-block. Modern IDE (e.g. VSCode) will identify the deprecated function calls and warn developers.

Alternatives

Leaving things as-is.

Additional Context

Functions to refactor:

• getIPAddress
• emailBodyConvert (Services: replace emailBodyConvert calls with Format::emailBodyToPlain #1683)
• __ (should be left alone)
• __n (should be left alone)
• __m (should be left alone)
• renderGradeScaleSelect
• archiveNotification (System: replace archiveNotification with gateway method #1662)
• daysUntilNextBirthday (System: refactor birthday calculation logics and functions #1684)
• is_leap_year (System: refactor birthday calculation logics and functions #1684)
• doesPasswordMatchPolicy (Refactor password policy #1685)
• getPasswordPolicy (Refactor password policy #1685)
• getFastFinder
• getAlert (System: replace getAlert with AlertLevelGateway method #1663)
• getSalt
• getUnit
• getWeekNumber
• getEditor (Refactor: make getEditor function obsoleted #1648)
• getYearGroups
• getYearGroupsFromIDList
• getTerms (School: replace getTerms with SchoolYearTermGateway methods #1664)
• msort (Refactor: Deprecate msort #1752)
• getMaxUpload
• htmlPrep
• getHighestMedicalRisk (Students: replace getHighestMedicalRisk with MedicalGateway method #1667, Students: fix phpdocs for getHighestMedicalRisk #1690)
• getHighestGroupedAction (Replace getHighestGroupAction with ActionGateway method #1666)
• getRoleCategory (Replace getRoleCategory with gateway method #1682)
• isSchoolOpen
• getAlertBar
• getSystemSettings
• setLanguageSession
• isActionAccessible
• isModuleAccessible (77cb3ed)
• getModuleName
• getActionName
• checkModuleReady
• getModuleCategory
• setCurrentSchoolYear (Refactor: SchoolYearGateway methods to replace functions.php relevant functions #1669, System: move school year session setup to SessionFactory #1688)
• nl2brr (Deprecate nl2brr #1696)
• getPreviousSchoolYearID (Refactor: SchoolYearGateway methods to replace functions.php relevant functions #1669)
• geteNextSchoolYearID (Refactor: SchoolYearGateway methods to replace functions.php relevant functions #1669)
• getNextYearGroupID (School: replace functions with YearGroupGateway methods #1670)
• getNextFormGroupID (FormGroups: replace getNextFormGroupID with method #1671)
• getLastYearGroupID (School: replace functions with YearGroupGateway methods #1670)
• randomPassword (System: deprecate randomPassword #1700)
• getModuleID
• getModuleIDFromName
• isCommandLineInterface
• returnProcess (OOification: Return Process #1243)

[SKuipers]

Amazing, thanks for getting this initiative underway and documenting it so well 😃