Add report exports

app/Enums/ExportFormat.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums;
+
+use Maatwebsite\Excel\Excel;
+
+enum ExportFormat: string
+{
+    case CSV = 'csv';
+    case PDF = 'pdf';
+    case XLSX = 'xlsx';
+    case ODS = 'ods';
+
+    public function getFileExtension(): string
+    {
+        return match ($this) {
+            self::CSV => 'csv',
+            self::PDF => 'pdf',
+            self::XLSX => 'xlsx',
+            self::ODS => 'ods',
+        };
+    }
+
+    public function getExportPackageType(): string
+    {
+        return match ($this) {
+            self::CSV => Excel::CSV,
+            self::PDF => Excel::MPDF,
+            self::XLSX => Excel::XLSX,
+            self::ODS => Excel::ODS,
+        };
+    }
+}

app/Http/Controllers/Api/V1/TimeEntryController.php

@@ -4,10 +4,12 @@
 
 namespace App\Http\Controllers\Api\V1;
 
+use App\Enums\ExportFormat;
 use App\Exceptions\Api\TimeEntryCanNotBeRestartedApiException;
 use App\Exceptions\Api\TimeEntryStillRunningApiException;
 use App\Http\Requests\V1\TimeEntry\TimeEntryAggregateRequest;
 use App\Http\Requests\V1\TimeEntry\TimeEntryDestroyMultipleRequest;
+use App\Http\Requests\V1\TimeEntry\TimeEntryIndexExportRequest;
 use App\Http\Requests\V1\TimeEntry\TimeEntryIndexRequest;
 use App\Http\Requests\V1\TimeEntry\TimeEntryStoreRequest;
 use App\Http\Requests\V1\TimeEntry\TimeEntryUpdateMultipleRequest;
@@ -21,15 +23,20 @@
 use App\Models\Project;
 use App\Models\Task;
 use App\Models\TimeEntry;
+use App\Service\ReportExport\TimeEntriesDetailedCsvExport;
+use App\Service\ReportExport\TimeEntriesDetailedExport;
 use App\Service\TimeEntryAggregationService;
 use App\Service\TimeEntryFilter;
 use App\Service\TimezoneService;
 use Illuminate\Auth\Access\AuthorizationException;
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Resources\Json\JsonResource;
 use Illuminate\Support\Collection;
 use Illuminate\Support\Facades\Auth;
 use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Facades\Storage;
+use Maatwebsite\Excel\Facades\Excel;
 
 class TimeEntryController extends Controller
 {
@@ -63,21 +70,7 @@ public function index(Organization $organization, TimeEntryIndexRequest $request
             $this->checkPermission($organization, 'time-entries:view:all');
         }
 
-        $timeEntriesQuery = TimeEntry::query()
-            ->whereBelongsTo($organization, 'organization')
-            ->orderBy('start', 'desc');
-
-        $filter = new TimeEntryFilter($timeEntriesQuery);
-        $filter->addStartFilter($request->input('start'));
-        $filter->addEndFilter($request->input('end'));
-        $filter->addActiveFilter($request->input('active'));
-        $filter->addMemberIdFilter($member);
-        $filter->addMemberIdsFilter($request->input('member_ids'));
-        $filter->addProjectIdsFilter($request->input('project_ids'));
-        $filter->addTagIdsFilter($request->input('tag_ids'));
-        $filter->addTaskIdsFilter($request->input('task_ids'));
-        $filter->addClientIdsFilter($request->input('client_ids'));
-        $filter->addBillableFilter($request->input('billable'));
+        $timeEntriesQuery = $this->getTimeEntriesQuery($organization, $request, $member);
 
         $totalCount = $timeEntriesQuery->count();
 
@@ -128,6 +121,76 @@ public function index(Organization $organization, TimeEntryIndexRequest $request
             ]);
     }
 
+    /**
+     * @return Builder<TimeEntry>
+     */
+    private function getTimeEntriesQuery(Organization $organization, TimeEntryIndexRequest|TimeEntryIndexExportRequest $request, ?Member $member): Builder
+    {
+        $timeEntriesQuery = TimeEntry::query()
+            ->whereBelongsTo($organization, 'organization')
+            ->orderBy('start', 'desc');
+
+        $filter = new TimeEntryFilter($timeEntriesQuery);
+        $filter->addStartFilter($request->input('start'));
+        $filter->addEndFilter($request->input('end'));
+        $filter->addActiveFilter($request->input('active'));
+        $filter->addMemberIdFilter($member);
+        $filter->addMemberIdsFilter($request->input('member_ids'));
+        $filter->addProjectIdsFilter($request->input('project_ids'));
+        $filter->addTagIdsFilter($request->input('tag_ids'));
+        $filter->addTaskIdsFilter($request->input('task_ids'));
+        $filter->addClientIdsFilter($request->input('client_ids'));
+        $filter->addBillableFilter($request->input('billable'));
+
+        return $filter->get();
+    }
+
+    /**
+     * @throws AuthorizationException
+     */
+    public function indexExport(Organization $organization, TimeEntryIndexExportRequest $request): JsonResponse
+    {
+        /** @var Member|null $member */
+        $member = $request->has('member_id') ? Member::query()->findOrFail($request->input('member_id')) : null;
+        if ($member !== null && $member->user_id === Auth::id()) {
+            $this->checkPermission($organization, 'time-entries:view:own');
+        } else {
+            $this->checkPermission($organization, 'time-entries:view:all');
+        }
+
+        $timeEntriesQuery = $this->getTimeEntriesQuery($organization, $request, $member);
+        $timeEntriesQuery->with([
+            'task',
+            'project' => [
+                'client',
+            ],
+            'user',
+            'tagsRelation',
+        ]);
+        $format = $request->getFormatValue();
+        $filename = 'time-entries-export-'.now()->format('Y-m-d_H-i-s').'.'.$format->getFileExtension();
+        $path = 'exports/'.$filename;
+        if ($format === ExportFormat::CSV) {
+            $export = new TimeEntriesDetailedCsvExport(config('filesystems.private'), $filename, $timeEntriesQuery, 1000);
+            $export->export();
+        } else {
+            Excel::store(
+                new TimeEntriesDetailedExport($timeEntriesQuery),
+                $path,
+                config('filesystems.private'),
+                $format->getExportPackageType(),
+                [
+                    'visibility' => 'private',
+                ]
+            );
+        }
+
+        return response()->json([
+            'download_url' => Storage::disk(config('filesystems.private'))
+                ->temporaryUrl($path, now()->addMinutes(5)),
+        ]);
+    }
+
     /**
      * Get aggregated time entries in organization
      *

app/Http/Requests/V1/TimeEntry/TimeEntryIndexExportRequest.php

@@ -0,0 +1,143 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Requests\V1\TimeEntry;
+
+use App\Enums\ExportFormat;
+use App\Models\Member;
+use App\Models\Organization;
+use App\Models\Project;
+use App\Models\Tag;
+use App\Models\Task;
+use Illuminate\Contracts\Validation\ValidationRule;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Validation\Rule;
+use Korridor\LaravelModelValidationRules\Rules\ExistsEloquent;
+
+/**
+ * @property Organization $organization
+ */
+class TimeEntryIndexExportRequest extends TimeEntryIndexRequest
+{
+    /**
+     * Get the validation rules that apply to the request.
+     *
+     * @return array<string, array<string|ValidationRule|\Illuminate\Contracts\Validation\Rule>>
+     */
+    public function rules(): array
+    {
+        return [
+            'format' => [
+                'required',
+                'string',
+                Rule::enum(ExportFormat::class),
+            ],
+            // Filter by member ID
+            'member_id' => [
+                'string',
+                'uuid',
+                new ExistsEloquent(Member::class, null, function (Builder $builder): Builder {
+                    /** @var Builder<Member> $builder */
+                    return $builder->whereBelongsTo($this->organization, 'organization');
+                }),
+            ],
+            // Filter by multiple member IDs, member IDs are OR combined, but AND combined with the member_id parameter
+            'member_ids' => [
+                'array',
+                'min:1',
+            ],
+            'member_ids.*' => [
+                'string',
+                'uuid',
+                new ExistsEloquent(Member::class, null, function (Builder $builder): Builder {
+                    /** @var Builder<Member> $builder */
+                    return $builder->whereBelongsTo($this->organization, 'organization');
+                }),
+            ],
+            // Filter by project IDs, project IDs are OR combined
+            'project_ids' => [
+                'array',
+                'min:1',
+            ],
+            'project_ids.*' => [
+                'string',
+                'uuid',
+                new ExistsEloquent(Project::class, null, function (Builder $builder): Builder {
+                    /** @var Builder<Project> $builder */
+                    return $builder->whereBelongsTo($this->organization, 'organization');
+                }),
+            ],
+            // Filter by tag IDs, tag IDs are AND combined
+            'tag_ids' => [
+                'array',
+                'min:1',
+            ],
+            'tag_ids.*' => [
+                'string',
+                'uuid',
+                new ExistsEloquent(Tag::class, null, function (Builder $builder): Builder {
+                    /** @var Builder<Tag> $builder */
+                    return $builder->whereBelongsTo($this->organization, 'organization');
+                }),
+            ],
+            // Filter by task IDs, task IDs are OR combined
+            'task_ids' => [
+                'array',
+                'min:1',
+            ],
+            'task_ids.*' => [
+                'string',
+                'uuid',
+                new ExistsEloquent(Task::class, null, function (Builder $builder): Builder {
+                    /** @var Builder<Task> $builder */
+                    return $builder->whereBelongsTo($this->organization, 'organization');
+                }),
+            ],
+            // Filter only time entries that have a start date after the given timestamp in UTC (example: 2021-01-01T00:00:00Z)
+            'start' => [
+                'nullable',
+                'string',
+                'date_format:Y-m-d\TH:i:s\Z',
+                'before:end',
+            ],
+            // Filter only time entries that have a start date before the given timestamp in UTC (example: 2021-01-01T00:00:00Z)
+            'end' => [
+                'nullable',
+                'string',
+                'date_format:Y-m-d\TH:i:s\Z',
+            ],
+            // Filter by active status (active means has no end date, is still running)
+            'active' => [
+                'string',
+                'in:true,false',
+            ],
+            // Filter by billable status
+            'billable' => [
+                'string',
+                'in:true,false',
+            ],
+            // Limit the number of returned time entries (default: 150)
+            'limit' => [
+                'integer',
+                'min:1',
+                'max:500',
+            ],
+            // Filter makes sure that only time entries of a whole date are returned
+            'only_full_dates' => [
+                'string',
+                'in:true,false',
+            ],
+        ];
+    }
+
+    public function getOnlyFullDates(): bool
+    {
+        return $this->input('only_full_dates', 'false') === 'true';
+    }
+
+    public function getFormatValue(): ExportFormat
+    {
+        return ExportFormat::from($this->validated('format'));
+    }
+}

app/Models/Tag.php

@@ -12,6 +12,8 @@
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Support\Carbon;
 use OwenIt\Auditing\Contracts\Auditable as AuditableContract;
+use Staudenmeir\EloquentJsonRelations\HasJsonRelationships;
+use Staudenmeir\EloquentJsonRelations\Relations\HasManyJson;
 
 /**
  * @property string $id
@@ -30,6 +32,7 @@ class Tag extends Model implements AuditableContract
     /** @use HasFactory<TagFactory> */
     use HasFactory;
 
+    use HasJsonRelationships;
     use HasUuids;
 
     /**
@@ -48,4 +51,14 @@ public function organization(): BelongsTo
     {
         return $this->belongsTo(Organization::class, 'organization_id');
     }
+
+    /**
+     * Warning: This relation based on a JSON column. Please make sure that there are no performance issues, before using it.
+     *
+     * @return HasManyJson<TimeEntry, $this>
+     */
+    public function timeEntries(): HasManyJson
+    {
+        return $this->hasManyJson(TimeEntry::class, 'tags');
+    }
 }

app/Models/TimeEntry.php

@@ -10,13 +10,16 @@
 use Carbon\CarbonInterval;
 use Database\Factories\TimeEntryFactory;
 use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Collection;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Database\Eloquent\Relations\Relation;
 use Illuminate\Support\Carbon;
 use Korridor\LaravelComputedAttributes\ComputedAttributes;
 use OwenIt\Auditing\Contracts\Auditable as AuditableContract;
+use Staudenmeir\EloquentJsonRelations\HasJsonRelationships;
+use Staudenmeir\EloquentJsonRelations\Relations\BelongsToJson;
 
 /**
  * @property string $id
@@ -42,6 +45,7 @@
  * @property-read Client|null $client
  * @property string|null $task_id
  * @property-read Task|null $task
+ * @property-read Collection<Tag> $tagsRelation
  *
  * @method Builder<TimeEntry> hasTag(Tag $tag)
  * @method static TimeEntryFactory factory()
@@ -50,10 +54,11 @@ class TimeEntry extends Model implements AuditableContract
 {
     use ComputedAttributes;
     use CustomAuditable;
-
     /** @use HasFactory<TimeEntryFactory> */
     use HasFactory;
 
+    use HasJsonRelationships;
+
     use HasUuids;
 
     /**
@@ -197,4 +202,14 @@ public function client(): BelongsTo
     {
         return $this->belongsTo(Client::class, 'client_id');
     }
+
+    /**
+     * Warning: This relation based on a JSON column. Please make sure that there are no performance issues, before using it.
+     *
+     * @return BelongsToJson<Tag, $this>
+     */
+    public function tagsRelation(): BelongsToJson
+    {
+        return $this->belongsToJson(Tag::class, 'tags');
+    }
 }