feat: add ExtractDatePart expression (tpetry#33)

Co-authored-by: tpetry <github@tpetry.me>

Author: authanram

CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+### Added
+* `ExtractYear` time function to extract the year from date/datetime columns
+
 ## [1.5.0] - 2025-02-14
 ### Added
 * Laravel 12 support

README.md

@@ -360,9 +360,11 @@ Schema::table('users', function (Blueprint $table): void {
 
 #### Time
 ```php
+use Tpetry\QueryExpressions\Function\Time\ExtractDatePart;
 use Tpetry\QueryExpressions\Function\Time\Now;
 use Tpetry\QueryExpressions\Function\Time\TimestampBin;
 
+new ExtractDatePart(string|Expression $column, string $part);
 new Now();
 new TimestampBin(string|Expression $expression, DateInterval $step, ?DateTimeInterface $origin = null);
 

src/Function/Time/ExtractDatePart.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tpetry\QueryExpressions\Function\Time;
+
+use Illuminate\Contracts\Database\Query\Expression;
+use Illuminate\Database\Grammar;
+use InvalidArgumentException;
+use Tpetry\QueryExpressions\Concerns\IdentifiesDriver;
+use Tpetry\QueryExpressions\Concerns\StringizeExpression;
+
+class ExtractDatePart implements Expression
+{
+    use IdentifiesDriver;
+    use StringizeExpression;
+
+    /**
+     * @param  'year'  $part
+     */
+    public function __construct(
+        private readonly string|Expression $column,
+        private readonly string $part,
+    ) {}
+
+    public function getValue(Grammar $grammar): string
+    {
+        $column = $this->stringize($grammar, $this->column);
+
+        return match ($this->part) {
+            'year' => $this->extractYear($grammar, $column), // @phpstan-ignore-line match.alwaysTrue
+            default => throw new InvalidArgumentException("Invalid date part: '{$this->part}'."),
+        };
+    }
+
+    private function extractYear(Grammar $grammar, string $column): string
+    {
+        return match ($this->identify($grammar)) {
+            'mariadb', 'mysql', 'sqlsrv' => "(year({$column}))",
+            'pgsql' => "extract(year from {$column})::int",
+            'sqlite' => "cast(strftime('%Y', {$column}) as integer)",
+        };
+    }
+}

tests/Function/Time/ExtractDatePartTest.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+use Illuminate\Database\Query\Expression;
+use Illuminate\Database\Schema\Blueprint;
+use Tpetry\QueryExpressions\Function\Time\ExtractDatePart;
+
+test('fails for unimplemented date parts', function () {
+    expect(function () {
+        (new ExtractDatePart('val', 'day'))->getValue(DB::getQueryGrammar());
+    })->toThrow("Invalid date part: 'day'.");
+});
+
+it('can extract the year from a column')
+    ->expect(new ExtractDatePart('val', 'year'))
+    ->toBeExecutable(function (Blueprint $table) {
+        $table->date('val');
+    })
+    ->toBeMysql('(year(`val`))')
+    ->toBePgsql('extract(year from "val")::int')
+    ->toBeSqlite('cast(strftime(\'%Y\', "val") as integer)')
+    ->toBeSqlsrv('year([val])');
+
+it('can extract the year from an expression')
+    ->expect(new ExtractDatePart(new Expression('current_date'), 'year'))
+    ->toBeExecutable(function (Blueprint $table) {
+        $table->date('val');
+    })
+    ->toBeMysql('(year(current_date))')
+    ->toBePgsql('extract(year from current_date)::int')
+    ->toBeSqlite('cast(strftime(\'%Y\', current_date) as integer)')
+    ->toBeSqlsrv('year(current_date)');