Feature TIMEDIFF and TIMESTAMPDIFF function expressions

[kevinfrom]

feat: added sql function expressions for "TIMEDIFF" and "TIMESTAMPDIFF"

Currently the dateDiff method already exists in \Cake\Database\FunctionsBuilder, but not for either "TIMEDIFF" or "TIMESTAMPDIFF" SQL functions.

Note: The new functions only work in MySQL, which I've added a comment in the method docblocks.

[dereuromark]

Should probably target 5.next

[othercorey]

I am concerned about adding too many built-in functions that are supported by a single db engine only.

[ADmad]

I am concerned about adding too many built-in functions that are supported by a single db engine only.

I share the same concern.

[markstory]

I also share the concern about adding functions that are only supported on a single SQL dialect. Are any of these functions we can simulate or approximate in other platforms? It looks like sqlite has timediff. and postgres allows operations like time '05:00' - time '03:00' will return 02:00:00.

[kevinfrom]

I like the idea of approximating in the three other SQL dialects, and I've done some testing. The formats are vastly different, and a CakePHP dev may expect the result to be returned as an object which is easy to interact with. A DateTimeInterval object of some sort.

Let me know what you think and how I may proceed with this PR.

Test results:

TIMEDIFF test in different SQL dialects.

MySQL / MariaDB:
Query: "SELECT TIMEDIFF('2024-04-09 16:00:00', '2024-04-08 08:00:00');"
RESULT: "32:00:00"

Postgres:
Query: "SELECT (timestamp '2024-04-09 16:00:00' - timestamp '2024-04-08 08:00:00');"
RESULT: "1 day 08:00:00"

SQLServer Express:
Query: "SELECT DATEDIFF(s, '2024-04-09 16:00:00', '2024-04-08 08:00:00');"
Result (seconds): -115200
Note: The DATEDIFF function for SQL Express functions roughly the same as TIMESTAMPDIFF in MySQL.
Note 2: The returned value is negative when the first argument is higher/later than the second argument.

sqlite3:
Query: "SELECT TIMEDIFF('2024-04-09 16:00:00', '2024-04-08 08:00:00');"
Result: "+0000-00-01 08:00:00.000"
Note: The returned value is negative when the first argument is higher/later than the second argument.

TIMESTAMPDIFF test in different SQL dialects.

MySQL / MariaDB:
Query: "SELECT TIMESTAMPDIFF(SECOND, '2024-04-09 16:00:00', '2024-04-08 08:00:00');"
Result: -115200
Note: The TIMESTAMPDIFF MySQL function is equivalent to the DATEDIFF function in SQL Express.
Note 2:Note 2: The returned value is negative when the first argument is higher/later than the second argument.

Postgres:
Query: "SELECT EXTRACT(EPOCH FROM (timestamp '2024-04-09 16:00:00' - timestamp '2024-04-08 08:00:00'));"
Result: 115200.000000
Note: This returns the amount of seconds in difference.

sqlite3:
Query: "SELECT unixepoch('2024-04-09 16:00:00') - unixepoch('2024-04-08 08:00:00');"
Result: 115200
Note: Note: This returns the amount of seconds in difference.

SQLServer Express:
Query: "SELECT DATEDIFF(s, '2024-04-09 16:00:00', '2024-04-08 08:00:00');"
Result (seconds): -115200
Note 1: This is the exact same function as above.
Note 2: The DATEDIFF function for SQL Express functions roughly the same as TIMESTAMPDIFF in MySQL.
Note 3: The returned value is negative when the first argument is higher/later than the second argument.

[markstory]

The results for timestampdiff look promising. The results sometimes being negative could be something we smooth over with additional casting, or leave alone and document that the results vary based on the database provider.