Skip to content

A free open source IT asset/license management system

Refactored licenses controller to use a pessimistic lock inside a transaction

snipec25d56ea852a
diff --git a/app/Http/Controllers/Api/LicenseSeatsController.php b/app/Http/Controllers/Api/LicenseSeatsController.php
index eeecc105aa..dbe1565f10 100644
--- a/app/Http/Controllers/Api/LicenseSeatsController.php
+++ b/app/Http/Controllers/Api/LicenseSeatsController.php
@@ -132,91 +132,110 @@ class LicenseSeatsController extends Controller
$this->authorize('checkout', License::class);
- $licenseSeat = LicenseSeat::with(['license', 'asset', 'user'])->find($seatId);
+ $errorResponse = null;
+ $updatedSeat = null;
- if (! $licenseSeat) {
- return response()->json(Helper::formatStandardApiResponse('error', null, 'Seat not found'));
- }
-
- $license = $licenseSeat->license;
- if (! $license || $license->id != intval($licenseId)) {
- return response()->json(Helper::formatStandardApiResponse('error', null, 'Seat does not belong to the specified license'));
- }
+ // Fetch the seat with a pessimistic lock inside a transaction so concurrent requests
+ // on the same seat serialise rather than racing to overwrite each other's assignment.
+ DB::transaction(function () use ($request, $licenseId, $seatId, $validated, &$errorResponse, &$updatedSeat): void {
+ $licenseSeat = LicenseSeat::with(['license', 'asset', 'user'])
+ ->lockForUpdate()
+ ->find($seatId);
- $targetUser = null;
- if (! is_null($request->input('assigned_to'))) {
- // Resolve unscoped target so we can return a clean cross-company error instead of a hidden-not-found.
- $targetUser = User::withoutGlobalScopes()->find($request->input('assigned_to'));
+ if (! $licenseSeat) {
+ $errorResponse = response()->json(Helper::formatStandardApiResponse('error', null, 'Seat not found'));
- if (! $targetUser) {
- return response()->json(Helper::formatStandardApiResponse('error', null, 'Target not found'));
+ return;
}
- if ((Setting::getSettings()->full_multiple_companies_support == '1') && (! $targetUser->companies()->where('companies.id', $license->company_id)->exists())) {
- return response()->json(Helper::formatStandardApiResponse('error', null, trans('general.error_user_company')));
+ $license = $licenseSeat->license;
+ if (! $license || $license->id != intval($licenseId)) {
+ $errorResponse = response()->json(Helper::formatStandardApiResponse('error', null, 'Seat does not belong to the specified license'));
+
+ return;
}
- }
- $targetAsset = null;
- if (! is_null($request->input('asset_id'))) {
- // Resolve unscoped target so FMCS company mismatch can be enforced explicitly.
- $targetAsset = Asset::withoutGlobalScopes()->find($request->input('asset_id'));
+ $targetUser = null;
+ if (! is_null($request->input('assigned_to'))) {
+ // Resolve unscoped target so we can return a clean cross-company error instead of a hidden-not-found.
+ $targetUser = User::withoutGlobalScopes()->find($request->input('assigned_to'));
+
+ if (! $targetUser) {
+ $errorResponse = response()->json(Helper::formatStandardApiResponse('error', null, 'Target not found'));
+
+ return;
+ }
+
+ if ((Setting::getSettings()->full_multiple_companies_support == '1') && (! $targetUser->companies()->where('companies.id', $license->company_id)->exists())) {
+ $errorResponse = response()->json(Helper::formatStandardApiResponse('error', null, trans('general.error_user_company')));
- if (! $targetAsset) {
- return response()->json(Helper::formatStandardApiResponse('error', null, 'Target not found'));
+ return;
+ }
}
- if ((Setting::getSettings()->full_multiple_companies_support == '1') && ($license->company_id !== $targetAsset->company_id)) {
- return response()->json(Helper::formatStandardApiResponse('error', null, trans('general.error_user_company')));
+ $targetAsset = null;
+ if (! is_null($request->input('asset_id'))) {
+ // Resolve unscoped target so FMCS company mismatch can be enforced explicitly.
+ $targetAsset = Asset::withoutGlobalScopes()->find($request->input('asset_id'));
+
+ if (! $targetAsset) {
+ $errorResponse = response()->json(Helper::formatStandardApiResponse('error', null, 'Target not found'));
+
+ return;
+ }
+
+ if ((Setting::getSettings()->full_multiple_companies_support == '1') && ($license->company_id !== $targetAsset->company_id)) {
+ $errorResponse = response()->json(Helper::formatStandardApiResponse('error', null, trans('general.error_user_company')));
+
+ return;
+ }
}
- }
- $oldUser = $licenseSeat->user;
- $oldAsset = $licenseSeat->asset;
+ $oldUser = $licenseSeat->user;
+ $oldAsset = $licenseSeat->asset;
- // attempt to update the license seat
- $licenseSeat->fill($validated);
+ $licenseSeat->fill($validated);
- // check if this update is a checkin operation
- // 1. are relevant fields touched at all?
- $assignmentTouched = $licenseSeat->isDirty('assigned_to') || $licenseSeat->isDirty('asset_id');
- $anythingTouched = $licenseSeat->isDirty();
+ $assignmentTouched = $licenseSeat->isDirty('assigned_to') || $licenseSeat->isDirty('asset_id');
+ $anythingTouched = $licenseSeat->isDirty();
- if (! $anythingTouched) {
- return response()->json(
- Helper::formatStandardApiResponse('success', $licenseSeat, trans('admin/licenses/message.update.success'))
- );
- }
- if ($assignmentTouched && $licenseSeat->unreassignable_seat) {
- return response()->json(Helper::formatStandardApiResponse('error', null, trans('admin/licenses/message.checkout.unavailable')));
- }
+ if (! $anythingTouched) {
+ $updatedSeat = $licenseSeat;
- // 2. are they cleared? if yes then this is a checkin operation
- $is_checkin = ($assignmentTouched && $licenseSeat->assigned_to === null && $licenseSeat->asset_id === null);
- $target = null;
+ return;
+ }
- // the logging functions expect only one "target". if both asset and user are present in the request,
- // we simply let assets take precedence over users...
- if ($licenseSeat->isDirty('assigned_to')) {
- $target = $is_checkin ? $oldUser : $targetUser;
- }
+ if ($assignmentTouched && $licenseSeat->unreassignable_seat) {
+ $errorResponse = response()->json(Helper::formatStandardApiResponse('error', null, trans('admin/licenses/message.checkout.unavailable')));
- if ($licenseSeat->isDirty('asset_id')) {
- $target = $is_checkin ? $oldAsset : $targetAsset;
- }
+ return;
+ }
+
+ // Are the assignment fields cleared? If yes, this is a checkin operation.
+ $is_checkin = ($assignmentTouched && $licenseSeat->assigned_to === null && $licenseSeat->asset_id === null);
- if ($assignmentTouched && is_null($target)) {
- // if both asset_id and assigned_to are null then we are "checking-in"
- // a related model that does not exist (possible purged or bad data).
- if (! is_null($request->input('asset_id')) || ! is_null($request->input('assigned_to'))) {
- return response()->json(Helper::formatStandardApiResponse('error', null, 'Target not found'));
+ // The logging functions expect only one "target"; assets take precedence over users.
+ $target = null;
+ if ($licenseSeat->isDirty('assigned_to')) {
+ $target = $is_checkin ? $oldUser : $targetUser;
+ }
+ if ($licenseSeat->isDirty('asset_id')) {
+ $target = $is_checkin ? $oldAsset : $targetAsset;
+ }
+
+ if ($assignmentTouched && is_null($target)) {
+ // Both fields are null but one was provided — the related model is purged or bad data.
+ if (! is_null($request->input('asset_id')) || ! is_null($request->input('assigned_to'))) {
+ $errorResponse = response()->json(Helper::formatStandardApiResponse('error', null, 'Target not found'));
+
+ return;
+ }
}
- }
- // Keep seat updates and checkout/checkin logging atomic to prevent partial state changes.
- $updated = DB::transaction(function () use ($licenseSeat, $assignmentTouched, $is_checkin, $target, $request): bool {
if (! $licenseSeat->save()) {
- return false;
+ $errorResponse = response()->json(Helper::formatStandardApiResponse('error', null, $licenseSeat->getErrors()));
+
+ return;
}
if ($assignmentTouched) {
@@ -225,25 +244,29 @@ class LicenseSeatsController extends Controller
$licenseSeat->unreassignable_seat = true;
if (! $licenseSeat->save()) {
- return false;
+ $errorResponse = response()->json(Helper::formatStandardApiResponse('error', null, $licenseSeat->getErrors()));
+
+ return;
}
}
- // todo: skip if target is null?
$licenseSeat->logCheckin($target, $licenseSeat->notes);
} else {
- // in this case, relevant fields are touched but it's not a checkin operation. so it must be a checkout operation.
$licenseSeat->logCheckout($request->input('notes'), $target);
}
}
- return true;
+ $updatedSeat = $licenseSeat;
});
- if ($updated) {
- return response()->json(Helper::formatStandardApiResponse('success', $licenseSeat, trans('admin/licenses/message.update.success')));
+ if ($errorResponse) {
+ return $errorResponse;
+ }
+
+ if ($updatedSeat) {
+ return response()->json(Helper::formatStandardApiResponse('success', $updatedSeat, trans('admin/licenses/message.update.success')));
}
- return Helper::formatStandardApiResponse('error', null, $licenseSeat->getErrors());
+ return response()->json(Helper::formatStandardApiResponse('error', null, 'An unexpected error occurred'), 500);
}
}
diff --git a/app/Http/Controllers/Api/LicensesController.php b/app/Http/Controllers/Api/LicensesController.php
index 5a4d6c669d..458f900dd1 100644
--- a/app/Http/Controllers/Api/LicensesController.php
+++ b/app/Http/Controllers/Api/LicensesController.php
@@ -2,15 +2,21 @@
namespace App\Http\Controllers\Api;
+use App\Events\CheckoutableCheckedIn;
+use App\Events\CheckoutableCheckedOut;
use App\Helpers\Helper;
use App\Http\Controllers\Controller;
use App\Http\Requests\FilterRequest;
use App\Http\Transformers\ActionlogsTransformer;
+use App\Http\Transformers\LicenseSeatsTransformer;
use App\Http\Transformers\LicensesTransformer;
use App\Http\Transformers\SelectlistTransformer;
+use App\Models\Asset;
use App\Models\Company;
use App\Models\License;
+use App\Models\LicenseSeat;
use App\Models\Setting;
+use App\Models\User;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;
@@ -261,6 +267,167 @@ class LicensesController extends Controller
return response()->json(Helper::formatStandardApiResponse('error', null, trans('admin/licenses/message.assoc_users')));
}
+ /**
+ * Checkout a license seat to a user or asset.
+ *
+ * Accepts an optional `seat_id`; if omitted the next available free seat is used.
+ * `target_type` must be "user" or "asset". Supply `assigned_to` for users or
+ * `asset_id` for assets.
+ *
+ * This will eventually use the same form request the UI uses, but we need to update the field names first.
+ *
+ * @param int $licenseId
+ */
+ public function checkout(Request $request, $licenseId): JsonResponse
+ {
+ $license = License::findOrFail($licenseId);
+ $this->authorize('checkout', $license);
+
+ $validated = $this->validate($request, [
+ 'seat_id' => 'sometimes|integer|nullable',
+ 'target_type' => 'required|in:user,asset',
+ 'assigned_to' => 'required_if:target_type,user|integer|nullable',
+ 'asset_id' => 'required_if:target_type,asset|integer|nullable',
+ 'notes' => 'sometimes|string|nullable',
+ ]);
+
+ if ($license->isInactive()) {
+ return response()->json(Helper::formatStandardApiResponse('error', null, trans('admin/licenses/message.checkout.license_is_inactive')));
+ }
+
+ $errorResponse = null;
+ $updatedSeat = null;
+ $target = null;
+
+ DB::transaction(function () use ($license, $validated, &$errorResponse, &$updatedSeat, &$target): void {
+ $seatId = $validated['seat_id'] ?? null;
+
+ $licenseSeat = $seatId
+ ? LicenseSeat::where('id', $seatId)->where('license_id', $license->id)->lockForUpdate()->first()
+ : $license->freeSeat(lock: true);
+
+ if (! $licenseSeat) {
+ $errorResponse = response()->json(Helper::formatStandardApiResponse('error', null, trans('admin/licenses/message.checkout.not_enough_seats')));
+
+ return;
+ }
+
+ if ($licenseSeat->unreassignable_seat) {
+ $errorResponse = response()->json(Helper::formatStandardApiResponse('error', null, trans('admin/licenses/message.checkout.unavailable')));
+
+ return;
+ }
+
+ if ($validated['target_type'] === 'user') {
+ $target = User::withoutGlobalScopes()->whereNull('deleted_at')->find($validated['assigned_to'] ?? null);
+ if (! $target) {
+ $errorResponse = response()->json(Helper::formatStandardApiResponse('error', null, trans('admin/licenses/message.user_does_not_exist')));
+
+ return;
+ }
+
+ if (Company::isFullMultipleCompanySupportEnabled() && ! $target->companies()->where('companies.id', $license->company_id)->exists()) {
+ $errorResponse = response()->json(Helper::formatStandardApiResponse('error', null, trans('general.error_user_company')));
+
+ return;
+ }
+
+ $licenseSeat->assigned_to = $target->id;
+ $licenseSeat->asset_id = null;
+ } else {
+ $target = Asset::withoutGlobalScopes()->whereNull('deleted_at')->find($validated['asset_id'] ?? null);
+ if (! $target) {
+ $errorResponse = response()->json(Helper::formatStandardApiResponse('error', null, trans('admin/licenses/message.asset_does_not_exist')));
+
+ return;
+ }
+
+ if (Company::isFullMultipleCompanySupportEnabled() && $license->company_id && $license->company_id !== $target->company_id) {
+ $errorResponse = response()->json(Helper::formatStandardApiResponse('error', null, trans('general.error_user_company')));
+
+ return;
+ }
+
+ $licenseSeat->asset_id = $target->id;
+ $licenseSeat->assigned_to = null;
+
+ if ($target->checkedOutToUser()) {
+ $licenseSeat->assigned_to = $target->assigned_to;
+ }
+ }
+
+ $licenseSeat->notes = $validated['notes'] ?? null;
+ $licenseSeat->created_by = auth()->id();
+
+ if (! $licenseSeat->save()) {
+ $errorResponse = response()->json(Helper::formatStandardApiResponse('error', null, $licenseSeat->getErrors()));
+
+ return;
+ }
+
+ event(new CheckoutableCheckedOut($licenseSeat, $target, auth()->user(), $validated['notes'] ?? null));
+ $updatedSeat = $licenseSeat->load('license', 'user', 'asset');
+ });
+
+ if ($errorResponse) {
+ return $errorResponse;
+ }
+
+ if ($updatedSeat) {
+ return response()->json(Helper::formatStandardApiResponse('success', (new LicenseSeatsTransformer)->transformLicenseSeat($updatedSeat), trans('admin/licenses/message.checkout.success')));
+ }
+
+ return response()->json(Helper::formatStandardApiResponse('error', null, 'An unexpected error occurred'), 500);
+ }
+
+ /**
+ * Checkin a license seat.
+ *
+ * `seat_id` is required to identify which seat to check back in.
+ *
+ * @param int $licenseId
+ */
+ public function checkin(Request $request, $licenseId): JsonResponse
+ {
+ $license = License::findOrFail($licenseId);
+ $this->authorize('checkin', $license);
+
+ $validated = $this->validate($request, [
+ 'seat_id' => 'required|integer',
+ 'notes' => 'sometimes|string|nullable',
+ ]);
+
+ $licenseSeat = LicenseSeat::where('id', $validated['seat_id'])
+ ->where('license_id', $license->id)
+ ->first();
+
+ if (! $licenseSeat) {
+ return response()->json(Helper::formatStandardApiResponse('error', null, trans('admin/licenses/message.not_found')));
+ }
+
+ if (is_null($licenseSeat->assigned_to) && is_null($licenseSeat->asset_id)) {
+ return response()->json(Helper::formatStandardApiResponse('error', null, trans('admin/licenses/message.checkin.error')));
+ }
+
+ $target = $licenseSeat->user ?? $licenseSeat->asset;
+
+ $licenseSeat->assigned_to = null;
+ $licenseSeat->asset_id = null;
+ $licenseSeat->notes = $validated['notes'] ?? null;
+
+ if (! $license->reassignable) {
+ $licenseSeat->unreassignable_seat = true;
+ }
+
+ if (! $licenseSeat->save()) {
+ return response()->json(Helper::formatStandardApiResponse('error', null, $licenseSeat->getErrors()));
+ }
+
+ event(new CheckoutableCheckedIn($licenseSeat, $target, auth()->user(), $licenseSeat->notes));
+
+ return response()->json(Helper::formatStandardApiResponse('success', (new LicenseSeatsTransformer)->transformLicenseSeat($licenseSeat->load('license', 'user', 'asset')), trans('admin/licenses/message.checkin.success')));
+ }
+
/**
* Gets a paginated collection for the select2 menus
*
diff --git a/app/Http/Controllers/Licenses/LicenseCheckoutController.php b/app/Http/Controllers/Licenses/LicenseCheckoutController.php
index 8f7ca26a14..de5e0b18ea 100644
--- a/app/Http/Controllers/Licenses/LicenseCheckoutController.php
+++ b/app/Http/Controllers/Licenses/LicenseCheckoutController.php
@@ -15,6 +15,7 @@ use Illuminate\Auth\Access\AuthorizationException;
use Illuminate\Contracts\View\View;
use Illuminate\Http\Exceptions\HttpResponseException;
use Illuminate\Http\RedirectResponse;
+use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;
class LicenseCheckoutController extends Controller
@@ -94,23 +95,31 @@ class LicenseCheckoutController extends Controller
return redirect()->route('licenses.index')->with('error', trans('admin/licenses/message.checkout.license_is_inactive'));
}
- $licenseSeat = $this->findLicenseSeatToCheckout($license, $seatId);
- $licenseSeat->created_by = auth()->id();
- $licenseSeat->notes = $request->input('notes');
+ $licenseSeat = null;
+ $checkoutTarget = null;
+
+ DB::transaction(function () use ($request, $license, $seatId, &$licenseSeat, &$checkoutTarget): void {
+ $licenseSeat = $this->findLicenseSeatToCheckout($license, $seatId, lock: true);
+ $licenseSeat->created_by = auth()->id();
+ $licenseSeat->notes = $request->input('notes');
+
+ if ($request->filled('asset_id')) {
+ $checkoutTarget = $this->checkoutToAsset($licenseSeat);
+ } elseif ($request->filled('assigned_to')) {
+ $checkoutTarget = $this->checkoutToUser($licenseSeat);
+ }
+ });
if ($request->filled('asset_id')) {
session()->put(['checkout_to_type' => 'asset']);
- $checkoutTarget = $this->checkoutToAsset($licenseSeat);
$request->request->add(['assigned_asset' => $checkoutTarget->id]);
session()->put([
'redirect_option' => $request->input('redirect_option'),
'checkout_to_type' => 'asset',
'sign_in_place' => $request->boolean('sign_in_place'),
]);
-
} elseif ($request->filled('assigned_to')) {
session()->put(['checkout_to_type' => 'user']);
- $checkoutTarget = $this->checkoutToUser($licenseSeat);
$request->request->add(['assigned_user' => $checkoutTarget->id]);
session()->put([
'redirect_option' => $request->input('redirect_option'),
@@ -156,9 +165,11 @@ class LicenseCheckoutController extends Controller
return redirect()->route('licenses.index')->with('error', trans('Something went wrong handling this checkout.'));
}
- protected function findLicenseSeatToCheckout($license, $seatId)
+ protected function findLicenseSeatToCheckout($license, $seatId, bool $lock = false)
{
- $licenseSeat = LicenseSeat::find($seatId) ?? $license->freeSeat();
+ $licenseSeat = $seatId
+ ? LicenseSeat::where('id', $seatId)->when($lock, fn ($q) => $q->lockForUpdate())->first()
+ : $license->freeSeat(lock: $lock);
if (! $licenseSeat) {
if ($seatId) {
diff --git a/app/Models/License.php b/app/Models/License.php
index 73ea25bf36..e2c41089d6 100755
--- a/app/Models/License.php
+++ b/app/Models/License.php
@@ -803,7 +803,7 @@ class License extends Depreciable
*
* @return mixed
*/
- public function freeSeat()
+ public function freeSeat(bool $lock = false)
{
return $this->licenseseats()
->whereNull('deleted_at')
@@ -813,6 +813,7 @@ class License extends Depreciable
->whereNull('asset_id');
})
->orderBy('id', 'asc')
+ ->when($lock, fn ($q) => $q->lockForUpdate())
->first();
}
diff --git a/routes/api.php b/routes/api.php
index 3a128527c2..0dee614cea 100644
--- a/routes/api.php
+++ b/routes/api.php
@@ -726,6 +726,20 @@ Route::group(['prefix' => 'v1', 'middleware' => ['api', 'api-throttle:api']], fu
]
)->name('api.licenses.history')->withTrashed();
+ Route::post('{license_id}/checkout',
+ [
+ Api\LicensesController::class,
+ 'checkout',
+ ]
+ )->name('api.licenses.checkout');
+
+ Route::post('{license_id}/checkin',
+ [
+ Api\LicensesController::class,
+ 'checkin',
+ ]
+ )->name('api.licenses.checkin');
+
});
Route::resource('licenses',
diff --git a/routes/web/licenses.php b/routes/web/licenses.php
index 820cb77f40..64d707651c 100644
--- a/routes/web/licenses.php
+++ b/routes/web/licenses.php
@@ -19,7 +19,7 @@ Route::group(['prefix' => 'licenses', 'middleware' => ['auth']], function () {
Route::post(
'{licenseId}/checkout/{seatId?}',
[Licenses\LicenseCheckoutController::class, 'store']
- ); // name() would duplicate here, so we skip it.
+ )->name('licenses.checkout.save');
Route::get('{licenseSeat}/checkin/{backto?}', [Licenses\LicenseCheckinController::class, 'create'])
->name('licenses.checkin')
diff --git a/tests/Feature/Licenses/Api/LicenseCheckoutCheckinTest.php b/tests/Feature/Licenses/Api/LicenseCheckoutCheckinTest.php
new file mode 100644
index 0000000000..3c9a85537f
--- /dev/null
+++ b/tests/Feature/Licenses/Api/LicenseCheckoutCheckinTest.php
@@ -0,0 +1,318 @@
+<?php
+
+namespace Tests\Feature\Licenses\Api;
+
+use App\Events\CheckoutableCheckedIn;
+use App\Events\CheckoutableCheckedOut;
+use App\Models\Asset;
+use App\Models\License;
+use App\Models\LicenseSeat;
+use App\Models\User;
+use Illuminate\Support\Facades\Event;
+use PHPUnit\Framework\Attributes\Test;
+use Tests\TestCase;
+
+class LicenseCheckoutCheckinTest extends TestCase
+{
+ // ---------------------------------------------------------------------------
+ // Checkout
+ // ---------------------------------------------------------------------------
+
+ #[Test]
+ public function checkout_requires_checkout_permission(): void
+ {
+ $license = License::factory()->create(['seats' => 1]);
+
+ $this->actingAsForApi(User::factory()->create())
+ ->postJson(route('api.licenses.checkout', $license->id), [
+ 'target_type' => 'user',
+ 'assigned_to' => User::factory()->create()->id,
+ ])
+ ->assertForbidden();
+ }
+
+ #[Test]
+ public function checkout_to_user_assigns_free_seat(): void
+ {
+ Event::fake([CheckoutableCheckedOut::class]);
+
+ $license = License::factory()->create(['seats' => 1]);
+ $target = User::factory()->create();
+
+ $this->actingAsForApi(User::factory()->checkoutLicenses()->create())
+ ->postJson(route('api.licenses.checkout', $license->id), [
+ 'target_type' => 'user',
+ 'assigned_to' => $target->id,
+ ])
+ ->assertOk()
+ ->assertJson(['status' => 'success']);
+
+ $seat = $license->licenseseats()->first();
+ $this->assertEquals($target->id, $seat->assigned_to);
+
+ Event::assertDispatched(CheckoutableCheckedOut::class);
+ }
+
+ #[Test]
+ public function checkout_to_asset_assigns_free_seat(): void
+ {
+ Event::fake([CheckoutableCheckedOut::class]);
+
+ $license = License::factory()->create(['seats' => 1]);
+ $asset = Asset::factory()->create();
+
+ $this->actingAsForApi(User::factory()->checkoutLicenses()->create())
+ ->postJson(route('api.licenses.checkout', $license->id), [
+ 'target_type' => 'asset',
+ 'asset_id' => $asset->id,
+ ])
+ ->assertOk()
+ ->assertJson(['status' => 'success']);
+
+ $seat = $license->licenseseats()->first();
+ $this->assertEquals($asset->id, $seat->asset_id);
+
+ Event::assertDispatched(CheckoutableCheckedOut::class);
+ }
+
+ #[Test]
+ public function checkout_to_specific_seat_by_id(): void
+ {
+ Event::fake([CheckoutableCheckedOut::class]);
+
+ $license = License::factory()->create(['seats' => 3]);
+ $seats = $license->licenseseats()->orderBy('id')->get();
+ $target = User::factory()->create();
+
+ $this->actingAsForApi(User::factory()->checkoutLicenses()->create())
+ ->postJson(route('api.licenses.checkout', $license->id), [
+ 'seat_id' => $seats[1]->id,
+ 'target_type' => 'user',
+ 'assigned_to' => $target->id,
+ ])
+ ->assertOk()
+ ->assertJson(['status' => 'success']);
+
+ $this->assertEquals($target->id, $seats[1]->fresh()->assigned_to);
+ $this->assertNull($seats[0]->fresh()->assigned_to);
+ $this->assertNull($seats[2]->fresh()->assigned_to);
+
+ Event::assertDispatched(CheckoutableCheckedOut::class);
+ }
+
+ #[Test]
+ public function checkout_fails_when_no_seats_available(): void
+ {
+ $license = License::factory()->create(['seats' => 1]);
+ LicenseSeat::where('license_id', $license->id)->update(['assigned_to' => User::factory()->create()->id]);
+
+ $this->actingAsForApi(User::factory()->checkoutLicenses()->create())
+ ->postJson(route('api.licenses.checkout', $license->id), [
+ 'target_type' => 'user',
+ 'assigned_to' => User::factory()->create()->id,
+ ])
+ ->assertJson(['status' => 'error']);
+ }
+
+ #[Test]
+ public function checkout_returns_error_for_nonexistent_user(): void
+ {
+ $license = License::factory()->create(['seats' => 1]);
+
+ $this->actingAsForApi(User::factory()->checkoutLicenses()->create())
+ ->postJson(route('api.licenses.checkout', $license->id), [
+ 'target_type' => 'user',
+ 'assigned_to' => 99999,
+ ])
+ ->assertJson(['status' => 'error']);
+ }
+
+ #[Test]
+ public function checkout_returns_error_for_nonexistent_asset(): void
+ {
+ $license = License::factory()->create(['seats' => 1]);
+
+ $this->actingAsForApi(User::factory()->checkoutLicenses()->create())
+ ->postJson(route('api.licenses.checkout', $license->id), [
+ 'target_type' => 'asset',
+ 'asset_id' => 99999,
+ ])
+ ->assertJson(['status' => 'error']);
+ }
+
+ #[Test]
+ public function sequential_checkouts_each_receive_a_distinct_seat(): void
+ {
+ Event::fake([CheckoutableCheckedOut::class]);
+
+ $license = License::factory()->create(['seats' => 2]);
+ $actor = User::factory()->checkoutLicenses()->create();
+ $user1 = User::factory()->create();
+ $user2 = User::factory()->create();
+
+ $this->actingAsForApi($actor)
+ ->postJson(route('api.licenses.checkout', $license->id), [
+ 'target_type' => 'user',
+ 'assigned_to' => $user1->id,
+ ])
+ ->assertJson(['status' => 'success']);
+
+ $this->actingAsForApi($actor)
+ ->postJson(route('api.licenses.checkout', $license->id), [
+ 'target_type' => 'user',
+ 'assigned_to' => $user2->id,
+ ])
+ ->assertJson(['status' => 'success']);
+
+ $assignedTo = $license->licenseseats()->pluck('assigned_to');
+ $this->assertCount(2, $assignedTo->filter());
+ $this->assertEquals(2, $assignedTo->unique()->count());
+
+ Event::assertDispatched(CheckoutableCheckedOut::class, 2);
+ }
+
+ // ---------------------------------------------------------------------------
+ // Checkin
+ // ---------------------------------------------------------------------------
+
+ #[Test]
+ public function checkin_requires_checkin_permission(): void
+ {
+ $license = License::factory()->create(['seats' => 1]);
+ $seat = $license->licenseseats()->first();
+ $seat->update(['assigned_to' => User::factory()->create()->id]);
+
+ $this->actingAsForApi(User::factory()->create())
+ ->postJson(route('api.licenses.checkin', $license->id), [
+ 'seat_id' => $seat->id,
+ ])
+ ->assertForbidden();
+ }
+
+ #[Test]
+ public function checkin_clears_assigned_user(): void
+ {
+ Event::fake([CheckoutableCheckedIn::class]);
+
+ $license = License::factory()->create(['seats' => 1, 'reassignable' => true]);
+ $user = User::factory()->create();
+ $seat = $license->licenseseats()->first();
+ $seat->update(['assigned_to' => $user->id]);
+
+ $this->actingAsForApi(User::factory()->checkinLicenses()->create())
+ ->postJson(route('api.licenses.checkin', $license->id), [
+ 'seat_id' => $seat->id,
+ ])
+ ->assertOk()
+ ->assertJson(['status' => 'success']);
+
+ $this->assertNull($seat->fresh()->assigned_to);
+ $this->assertFalse((bool) $seat->fresh()->unreassignable_seat);
+
+ Event::assertDispatched(CheckoutableCheckedIn::class);
+ }
+
+ #[Test]
+ public function checkin_clears_assigned_asset(): void
+ {
+ Event::fake([CheckoutableCheckedIn::class]);
+
+ $license = License::factory()->create(['seats' => 1, 'reassignable' => true]);
+ $asset = Asset::factory()->create();
+ $seat = $license->licenseseats()->first();
+ $seat->update(['asset_id' => $asset->id]);
+
+ $this->actingAsForApi(User::factory()->checkinLicenses()->create())
+ ->postJson(route('api.licenses.checkin', $license->id), [
+ 'seat_id' => $seat->id,
+ ])
+ ->assertOk()
+ ->assertJson(['status' => 'success']);
+
+ $this->assertNull($seat->fresh()->asset_id);
+
+ Event::assertDispatched(CheckoutableCheckedIn::class);
+ }
+
+ #[Test]
+ public function checkin_marks_seat_unreassignable_when_license_is_not_reassignable(): void
+ {
+ Event::fake([CheckoutableCheckedIn::class]);
+
+ $license = License::factory()->create(['seats' => 1, 'reassignable' => false]);
+ $user = User::factory()->create();
+ $seat = $license->licenseseats()->first();
+ $seat->update(['assigned_to' => $user->id]);
+
+ $this->actingAsForApi(User::factory()->checkinLicenses()->create())
+ ->postJson(route('api.licenses.checkin', $license->id), [
+ 'seat_id' => $seat->id,
+ ])
+ ->assertOk()
+ ->assertJson(['status' => 'success']);
+
+ $this->assertNull($seat->fresh()->assigned_to);
+ $this->assertTrue((bool) $seat->fresh()->unreassignable_seat);
+
+ Event::assertDispatched(CheckoutableCheckedIn::class);
+ }
+
+ #[Test]
+ public function checkin_returns_error_for_unassigned_seat(): void
+ {
+ $license = License::factory()->create(['seats' => 1]);
+ $seat = $license->licenseseats()->first();
+
+ $this->actingAsForApi(User::factory()->checkinLicenses()->create())
+ ->postJson(route('api.licenses.checkin', $license->id), [
+ 'seat_id' => $seat->id,
+ ])
+ ->assertJson(['status' => 'error']);
+ }
+
+ #[Test]
+ public function checkin_returns_error_for_seat_not_belonging_to_license(): void
+ {
+ $license1 = License::factory()->create(['seats' => 1]);
+ $license2 = License::factory()->create(['seats' => 1]);
+ $seat2 = $license2->licenseseats()->first();
+ $seat2->update(['assigned_to' => User::factory()->create()->id]);
+
+ $this->actingAsForApi(User::factory()->checkinLicenses()->create())
+ ->postJson(route('api.licenses.checkin', $license1->id), [
+ 'seat_id' => $seat2->id,
+ ])
+ ->assertJson(['status' => 'error']);
+ }
+
+ #[Test]
+ public function checkout_then_checkin_frees_the_seat(): void
+ {
+ Event::fake([CheckoutableCheckedOut::class, CheckoutableCheckedIn::class]);
+
+ $license = License::factory()->create(['seats' => 1, 'reassignable' => true]);
+ $user = User::factory()->create();
+ $actor = User::factory()->checkoutLicenses()->checkinLicenses()->create();
+
+ $this->actingAsForApi($actor)
+ ->postJson(route('api.licenses.checkout', $license->id), [
+ 'target_type' => 'user',
+ 'assigned_to' => $user->id,
+ ])
+ ->assertJson(['status' => 'success']);
+
+ $seat = $license->licenseseats()->first();
+ $this->assertEquals($user->id, $seat->fresh()->assigned_to);
+
+ $this->actingAsForApi($actor)
+ ->postJson(route('api.licenses.checkin', $license->id), [
+ 'seat_id' => $seat->id,
+ ])
+ ->assertJson(['status' => 'success']);
+
+ $this->assertNull($seat->fresh()->assigned_to);
+
+ Event::assertDispatched(CheckoutableCheckedOut::class);
+ Event::assertDispatched(CheckoutableCheckedIn::class);
+ }
+}
diff --git a/tests/Feature/Licenses/Ui/LicenseCheckoutTest.php b/tests/Feature/Licenses/Ui/LicenseCheckoutTest.php
new file mode 100644
index 0000000000..47956b7fc5
--- /dev/null
+++ b/tests/Feature/Licenses/Ui/LicenseCheckoutTest.php
@@ -0,0 +1,155 @@
+<?php
+
+namespace Tests\Feature\Licenses\Ui;
+
+use App\Events\CheckoutableCheckedOut;
+use App\Models\Asset;
+use App\Models\License;
+use App\Models\LicenseSeat;
+use App\Models\User;
+use Illuminate\Support\Facades\Event;
+use PHPUnit\Framework\Attributes\Test;
+use Tests\TestCase;
+
+class LicenseCheckoutTest extends TestCase
+{
+ #[Test]
+ public function requires_checkout_permission(): void
+ {
+ $license = License::factory()->create(['seats' => 1]);
+
+ $this->actingAs(User::factory()->create())
+ ->post(route('licenses.checkout.save', $license->id), [
+ 'assigned_to' => User::factory()->create()->id,
+ ])
+ ->assertForbidden();
+ }
+
+ #[Test]
+ public function checkout_to_user_assigns_free_seat(): void
+ {
+ Event::fake([CheckoutableCheckedOut::class]);
+
+ $license = License::factory()->create(['seats' => 1]);
+ $target = User::factory()->create();
+ $seat = $license->licenseseats()->first();
+
+ $this->actingAs(User::factory()->checkoutLicenses()->create())
+ ->post(route('licenses.checkout.save', $license->id), [
+ 'assigned_to' => $target->id,
+ ])
+ ->assertRedirect()
+ ->assertSessionHas('success');
+
+ $this->assertEquals($target->id, $seat->fresh()->assigned_to);
+ Event::assertDispatched(CheckoutableCheckedOut::class);
+ }
+
+ #[Test]
+ public function checkout_to_asset_assigns_free_seat(): void
+ {
+ Event::fake([CheckoutableCheckedOut::class]);
+
+ $license = License::factory()->create(['seats' => 1]);
+ $asset = Asset::factory()->create();
+ $seat = $license->licenseseats()->first();
+
+ $this->actingAs(User::factory()->checkoutLicenses()->create())
+ ->post(route('licenses.checkout.save', $license->id), [
+ 'asset_id' => $asset->id,
+ ])
+ ->assertRedirect()
+ ->assertSessionHas('success');
+
+ $this->assertEquals($asset->id, $seat->fresh()->asset_id);
+ Event::assertDispatched(CheckoutableCheckedOut::class);
+ }
+
+ #[Test]
+ public function checkout_of_specific_seat_by_id(): void
+ {
+ Event::fake([CheckoutableCheckedOut::class]);
+
+ $license = License::factory()->create(['seats' => 3]);
+ $seats = $license->licenseseats()->orderBy('id')->get();
+ $target = User::factory()->create();
+
+ $this->actingAs(User::factory()->checkoutLicenses()->create())
+ ->post(route('licenses.checkout.save', ['licenseId' => $license->id, 'seatId' => $seats[1]->id]), [
+ 'assigned_to' => $target->id,
+ ])
+ ->assertRedirect()
+ ->assertSessionHas('success');
+
+ $this->assertEquals($target->id, $seats[1]->fresh()->assigned_to);
+ $this->assertNull($seats[0]->fresh()->assigned_to);
+ $this->assertNull($seats[2]->fresh()->assigned_to);
+ }
+
+ #[Test]
+ public function cannot_checkout_when_no_seats_available(): void
+ {
+ $license = License::factory()->create(['seats' => 1]);
+ LicenseSeat::where('license_id', $license->id)->update(['assigned_to' => User::factory()->create()->id]);
+
+ $this->actingAs(User::factory()->checkoutLicenses()->create())
+ ->post(route('licenses.checkout.save', $license->id), [
+ 'assigned_to' => User::factory()->create()->id,
+ ])
+ ->assertRedirect()
+ ->assertSessionHas('error');
+ }
+
+ #[Test]
+ public function sequential_checkouts_each_receive_a_distinct_seat(): void
+ {
+ Event::fake([CheckoutableCheckedOut::class]);
+
+ $license = License::factory()->create(['seats' => 2]);
+ $actor = User::factory()->checkoutLicenses()->create();
+ $user1 = User::factory()->create();
+ $user2 = User::factory()->create();
+
+ $this->actingAs($actor)
+ ->post(route('licenses.checkout.save', $license->id), ['assigned_to' => $user1->id])
+ ->assertSessionHas('success');
+
+ $this->actingAs($actor)
+ ->post(route('licenses.checkout.save', $license->id), ['assigned_to' => $user2->id])
+ ->assertSessionHas('success');
+
+ $assignedTo = $license->licenseseats()->pluck('assigned_to');
+
+ $this->assertCount(2, $assignedTo->filter());
+ $this->assertContains($user1->id, $assignedTo);
+ $this->assertContains($user2->id, $assignedTo);
+ $this->assertEquals(2, $assignedTo->unique()->count(), 'Both users should hold different seats');
+
+ Event::assertDispatched(CheckoutableCheckedOut::class, 2);
+ }
+
+ #[Test]
+ public function third_checkout_fails_when_only_two_seats_exist(): void
+ {
+ Event::fake([CheckoutableCheckedOut::class]);
+
+ $license = License::factory()->create(['seats' => 2]);
+ $actor = User::factory()->checkoutLicenses()->create();
+
+ foreach ([User::factory()->create(), User::factory()->create()] as $user) {
+ $this->actingAs($actor)
+ ->post(route('licenses.checkout.save', $license->id), ['assigned_to' => $user->id])
+ ->assertSessionHas('success');
+ }
+
+ $this->actingAs($actor)
+ ->post(route('licenses.checkout.save', $license->id), [
+ 'assigned_to' => User::factory()->create()->id,
+ ])
+ ->assertRedirect()
+ ->assertSessionHas('error');
+
+ $this->assertEquals(0, $license->fresh()->freeSeats()->count());
+ Event::assertDispatched(CheckoutableCheckedOut::class, 2);
+ }
+}