Added placeholder users; Better exception handling; Enhanced local setup

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

@@ -4,7 +4,7 @@ declare(strict_types=1);
 
 namespace App\Http\Controllers\Api\V1;
 
-use App\Exceptions\TimeEntryStillRunning;
+use App\Exceptions\Api\TimeEntryStillRunningApiException;
 use App\Http\Requests\V1\TimeEntry\TimeEntryIndexRequest;
 use App\Http\Requests\V1\TimeEntry\TimeEntryStoreRequest;
 use App\Http\Requests\V1\TimeEntry\TimeEntryUpdateRequest;
@@ -102,7 +102,7 @@ class TimeEntryController extends Controller
     /**
      * Create time entry
      *
-     * @throws AuthorizationException|TimeEntryStillRunning
+     * @throws AuthorizationException|TimeEntryStillRunningApiException
      */
     public function store(Organization $organization, TimeEntryStoreRequest $request): JsonResource
     {
@@ -114,8 +114,7 @@ class TimeEntryController extends Controller
 
         if ($request->get('end') === null && TimeEntry::query()->where('user_id', $request->get('user_id'))->where('end', null)->exists()) {
             // TODO: API documentation
-            // TODO: Create concept for api exceptions
-            throw new TimeEntryStillRunning('User already has an active time entry');
+            throw new TimeEntryStillRunningApiException();
         }
 
         $timeEntry = new TimeEntry();

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

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Exceptions\Api\UserNotPlaceholderApiException;
+use App\Http\Requests\V1\User\UserIndexRequest;
+use App\Http\Resources\V1\User\UserCollection;
+use App\Models\Organization;
+use App\Models\User;
+use Illuminate\Auth\Access\AuthorizationException;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Laravel\Jetstream\Contracts\InvitesTeamMembers;
+
+class UserController extends Controller
+{
+    /**
+     * List all users in an organization
+     *
+     * @throws AuthorizationException
+     */
+    public function index(Organization $organization, UserIndexRequest $request): UserCollection
+    {
+        $this->checkPermission($organization, 'users:view');
+
+        $users = $organization->users()
+            ->paginate();
+
+        return UserCollection::make($users);
+    }
+
+    /**
+     * Invite a placeholder user to become a real user in the organization
+     *
+     * @throws AuthorizationException|UserNotPlaceholderApiException
+     */
+    public function invitePlaceholder(Organization $organization, User $user, Request $request): JsonResponse
+    {
+        $this->checkPermission($organization, 'users:invite-placeholder');
+
+        if (! $user->is_placeholder) {
+            throw new UserNotPlaceholderApiException();
+        }
+
+        app(InvitesTeamMembers::class)->invite(
+            $request->user(),
+            $organization,
+            $user->email,
+            'employee'
+        );
+
+        return response()->json($user);
+    }
+}

app/Http/Requests/V1/User/UserIndexRequest.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Requests\V1\User;
+
+use App\Models\Organization;
+use Illuminate\Contracts\Validation\ValidationRule;
+use Illuminate\Foundation\Http\FormRequest;
+
+/**
+ * @property Organization $organization
+ */
+class UserIndexRequest extends FormRequest
+{
+    /**
+     * Get the validation rules that apply to the request.
+     *
+     * @return array<string, array<string|ValidationRule>>
+     */
+    public function rules(): array
+    {
+        return [
+        ];
+    }
+}

app/Http/Resources/V1/User/UserCollection.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Resources\V1\User;
+
+use Illuminate\Http\Resources\Json\ResourceCollection;
+
+class UserCollection extends ResourceCollection
+{
+    /**
+     * The resource that this resource collects.
+     *
+     * @var string
+     */
+    public $collects = UserResource::class;
+}

app/Http/Resources/V1/User/UserResource.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Resources\V1\User;
+
+use App\Http\Resources\V1\BaseResource;
+use App\Models\Membership;
+use App\Models\User;
+use Illuminate\Http\Request;
+
+/**
+ * @property User $resource
+ */
+class UserResource extends BaseResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @return array<string, string|bool|int|null|array<string>>
+     */
+    public function toArray(Request $request): array
+    {
+        /** @var Membership $membership */
+        $membership = $this->resource->getRelationValue('membership');
+
+        return [
+            /** @var string $id ID */
+            'id' => $this->resource->id,
+            /** @var string $name Name */
+            'name' => $this->resource->name,
+            /** @var string $email Email */
+            'email' => $this->resource->email,
+            /** @var string $role Role */
+            'role' => $membership->role,
+            /** @var bool $is_placeholder Placeholder user for imports, user might not really exist and does not know about this placeholder membership */
+            'is_placeholder' => $this->resource->is_placeholder,
+        ];
+    }
+}