feat: timestamp binning

Author: tpetry

README.md

@@ -262,6 +262,33 @@ Schema::table('users', function (Blueprint $table): void {
 > The `Uuid4` expression is not available for all database versions.
 > With PostgreSQL you need at least v13 and with MariaDB at least v10.10.
 
+#### Time
+```php
+use Tpetry\QueryExpressions\Function\Time\Now;
+use Tpetry\QueryExpressions\Function\Time\TimestampBin;
+
+new Now();
+new TimestampBin(string|Expression $expression, DateInterval $step, ?DateTimeInterface $origin = null);
+
+BlogVisit::select([
+    'url',
+    new TimestampBin('created_at', DateInterval::createFromDateString('5 minutes')),
+    new Count('*'),
+])->groupBy(
+    'url',
+    new TimestampBin('created_at', DateInterval::createFromDateString('5 minutes'))
+)->get();
+// | url       | timestamp           | count |
+// |-----------|---------------------|-------|
+// | /example1 | 2023-05-16 09:50:00 | 2     |
+// | /example1 | 2023-05-16 09:55:00 | 1     |
+// | /example1 | 2023-05-16 09:50:00 | 1     |
+
+Schema::table('users', function (Blueprint $table): void {
+    $table->uuid()->default(new Uuid4())->unique();
+});
+```
+
 ## Changelog
 
 Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

src/Function/Time/Now.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tpetry\QueryExpressions\Function\Time;
+
+use Illuminate\Contracts\Database\Query\Expression;
+use Illuminate\Database\Grammar;
+use Tpetry\QueryExpressions\Concerns\IdentifiesDriver;
+
+class Now implements Expression
+{
+    use IdentifiesDriver;
+
+    public function getValue(Grammar $grammar)
+    {
+        // MySQL: The expression needs to be enclosed by parentheses to be used as a default value in create table statements.
+        // PostgreSQL: The CURRENT_TIMESTAMP constant is frozen within transactions.
+        // SQLite: The expression needs to be enclosed by parentheses to be used as a default value in create table statements.
+        return match ($this->identify($grammar)) {
+            'mysql', 'sqlite' => '(current_timestamp)',
+            'pgsql' => 'statement_timestamp()',
+            'sqlsrv' => 'current_timestamp',
+        };
+    }
+}

src/Function/Time/TimestampBin.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tpetry\QueryExpressions\Function\Time;
+
+use Carbon\CarbonInterval;
+use DateInterval;
+use DateTimeInterface;
+use Illuminate\Contracts\Database\Query\Expression;
+use Illuminate\Database\Grammar;
+use RuntimeException;
+use Tpetry\QueryExpressions\Concerns\IdentifiesDriver;
+use Tpetry\QueryExpressions\Concerns\StringizeExpression;
+
+class TimestampBin implements Expression
+{
+    use IdentifiesDriver;
+    use StringizeExpression;
+
+    public function __construct(
+        private readonly string|Expression $expression,
+        private readonly DateInterval $step,
+        private readonly ?DateTimeInterface $origin = null,
+    ) {
+        if ($this->step->f > 0) {
+            throw new RuntimeException('timestamp binning with millisecond resolution is not supported');
+        }
+        if ($this->origin?->getTimestamp() < 0) {
+            throw new RuntimeException('timestamp binning with an origin before 1970-01-01 is not supported');
+        }
+    }
+
+    public function getValue(Grammar $grammar)
+    {
+        $expression = $this->stringize($grammar, $this->expression);
+        $step = (int) CarbonInterval::instance($this->step)->totalSeconds;
+        $origin = $this->origin?->getTimestamp() ?? 0;
+
+        // MySQL: The expression needs to be enclosed by parentheses to be used as a default value in create table statements.
+        // SQLite: The expression needs to be enclosed by parentheses to be used as a default value in create table statements.
+        return match ($this->identify($grammar)) {
+            'mysql' => "(from_unixtime(floor((unix_timestamp({$expression})-{$origin})/{$step})*{$step}+{$origin}))",
+            'pgsql' => "to_timestamp(floor((extract(epoch from {$expression})-{$origin})/{$step})*{$step}+{$origin})",
+            'sqlite' => "(datetime((strftime('%s',{$expression})-{$origin})/{$step}*{$step}+{$origin},'unixepoch'))",
+            'sqlsrv' => "dateadd(s,(datediff(s,'1970-01-01',{$expression})-{$origin})/{$step}*{$step}+{$origin},'1970-01-01')",
+        };
+    }
+}

tests/Function/Time/NowTest.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+use Tpetry\QueryExpressions\Function\Time\Now;
+
+it('can generate the current time')
+    ->expect(new Now())
+    ->toBeExecutable()
+    ->toBeMysql('(current_timestamp)')
+    ->toBePgsql('statement_timestamp()')
+    ->toBeSqlite('(current_timestamp)')
+    ->toBeSqlsrv('current_timestamp');

tests/Function/Time/TimestampBinTest.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+use Illuminate\Database\Query\Expression;
+use Illuminate\Support\Facades\DB;
+use Tpetry\QueryExpressions\Function\Time\TimestampBin;
+
+it('can bin the time of a column')
+    ->expect(new TimestampBin('val', DateInterval::createFromDateString('5 minutes')))
+    ->toBeExecutable(['val timestamp'])
+    ->toBeMysql('(from_unixtime(floor((unix_timestamp(`val`)-0)/300)*300+0))')
+    ->toBePgsql('to_timestamp(floor((extract(epoch from "val")-0)/300)*300+0)')
+    ->toBeSqlite('(datetime((strftime(\'%s\',"val")-0)/300*300+0,\'unixepoch\'))')
+    ->toBeSqlsrv('dateadd(s,(datediff(s,\'1970-01-01\',[val])-0)/300*300+0,\'1970-01-01\')');
+
+it('can bin the time of an expression')
+    ->expect(new TimestampBin(new Expression('current_timestamp'), DateInterval::createFromDateString('1 minute')))
+    ->toBeExecutable(['val timestamp'])
+    ->toBeMysql('(from_unixtime(floor((unix_timestamp(current_timestamp)-0)/60)*60+0))')
+    ->toBePgsql('to_timestamp(floor((extract(epoch from current_timestamp)-0)/60)*60+0)')
+    ->toBeSqlite('(datetime((strftime(\'%s\',current_timestamp)-0)/60*60+0,\'unixepoch\'))')
+    ->toBeSqlsrv('dateadd(s,(datediff(s,\'1970-01-01\',current_timestamp)-0)/60*60+0,\'1970-01-01\')');
+
+it('can bin the time of a column with an origin')
+    ->expect(new TimestampBin('val', DateInterval::createFromDateString('90 seconds'), DateTime::createFromFormat('Y-m-d H:i:s', '2022-02-02 22:22:22')))
+    ->toBeExecutable(['val timestamp'])
+    ->toBeMysql('(from_unixtime(floor((unix_timestamp(`val`)-1643840542)/90)*90+1643840542))')
+    ->toBePgsql('to_timestamp(floor((extract(epoch from "val")-1643840542)/90)*90+1643840542)')
+    ->toBeSqlite('(datetime((strftime(\'%s\',"val")-1643840542)/90*90+1643840542,\'unixepoch\'))')
+    ->toBeSqlsrv('dateadd(s,(datediff(s,\'1970-01-01\',[val])-1643840542)/90*90+1643840542,\'1970-01-01\')');
+
+it('can bin the time of an expression with an origin')
+    ->expect(new TimestampBin(new Expression('current_timestamp'), DateInterval::createFromDateString('1 hour'), DateTime::createFromFormat('Y-m-d H:i:s', '2000-01-01 00:00:00')))
+    ->toBeExecutable(['val timestamp'])
+    ->toBeMysql('(from_unixtime(floor((unix_timestamp(current_timestamp)-946684800)/3600)*3600+946684800))')
+    ->toBePgsql('to_timestamp(floor((extract(epoch from current_timestamp)-946684800)/3600)*3600+946684800)')
+    ->toBeSqlite('(datetime((strftime(\'%s\',current_timestamp)-946684800)/3600*3600+946684800,\'unixepoch\'))')
+    ->toBeSqlsrv('dateadd(s,(datediff(s,\'1970-01-01\',current_timestamp)-946684800)/3600*3600+946684800,\'1970-01-01\')');
+
+it('does not support millisecond steps', function () {
+    $expression = new TimestampBin(
+        expression: new Expression('current_timestamp'),
+        step: DateInterval::createFromDateString('500 milliseconds'),
+    );
+
+    $expression->getValue(DB::connection()->getQueryGrammar());
+})->throws(RuntimeException::class, 'timestamp binning with millisecond resolution is not supported');
+
+it('does not support origins before 1970-01-01', function () {
+    $expression = new TimestampBin(
+        expression: new Expression('current_timestamp'),
+        step: DateInterval::createFromDateString('1 second'),
+        origin: DateTime::createFromFormat('Y-m-d', '1900-01-01'),
+    );
+
+    $expression->getValue(DB::connection()->getQueryGrammar());
+})->throws(RuntimeException::class, 'timestamp binning with an origin before 1970-01-01 is not supported');