Skip to content

A free open source IT asset/license management system

Added file path enums + tests

snipecb2bd195016e
diff --git a/app/Enums/FileStorage.php b/app/Enums/FileStorage.php
new file mode 100644
index 0000000000..b79270d4ab
--- /dev/null
+++ b/app/Enums/FileStorage.php
@@ -0,0 +1,180 @@
+<?php
+
+namespace App\Enums;
+
+/**
+ * Single source of truth for file-storage directory names across the app.
+ *
+ * Each case backs a directory subdir name. Scope methods declare
+ * whether the directory lives under public, private, or both. Path /
+ * directory accessors derive from the backing value plus the scope.
+ *
+ * Call sites use the enum cases directly rather than passing literal
+ * strings, so IDE autocomplete / static analysis will catch typos:
+ *
+ * FileStorage::Signatures->privatePath();
+ * FileStorage::Avatars->publicPath();
+ * FileStorage::publicDirs(); // for enumeration
+ * FileStorage::privateDirs();
+ *
+ * Models with image/avatar fields use the `HasImageUpload`
+ * trait to declare their resource once and resolve the path via
+ * `$model->imageUploadPath()`.
+ */
+enum FileStorage: string
+{
+ case Accessories = 'accessories';
+ case Assets = 'assets';
+ case Audits = 'audits';
+ case Avatars = 'avatars';
+ case Barcodes = 'barcodes';
+ case Categories = 'categories';
+ case Companies = 'companies';
+ case Components = 'components';
+ case Consumables = 'consumables';
+ case Departments = 'departments';
+ case EulaPdfs = 'eula-pdfs';
+ case Imports = 'imports';
+ case Licenses = 'licenses';
+ case Locations = 'locations';
+ case Maintenances = 'maintenances';
+ case Manufacturers = 'manufacturers';
+ case Models = 'models';
+ case Signatures = 'signatures';
+ case Suppliers = 'suppliers';
+ case Users = 'users';
+
+ /**
+ * Historical private-tree directory renames. Backups from older
+ * installs may carry the old subdir name. The restore maps old to
+ * new so the files end up in the current directory.
+ *
+ * @var array<string, string>
+ */
+ private const PRIVATE_ALIASES = [
+ 'assetmodels' => 'models',
+ 'asset_maintenances' => 'maintenances',
+ ];
+
+ public function hasPublicScope(): bool
+ {
+ return match ($this) {
+ self::Accessories,
+ self::Assets,
+ self::Avatars,
+ self::Barcodes,
+ self::Categories,
+ self::Companies,
+ self::Components,
+ self::Consumables,
+ self::Departments,
+ self::Locations,
+ self::Maintenances,
+ self::Manufacturers,
+ self::Models,
+ self::Suppliers => true,
+ default => false,
+ };
+ }
+
+ public function hasPrivateScope(): bool
+ {
+ return match ($this) {
+ self::Accessories,
+ self::Assets,
+ self::Audits,
+ self::Components,
+ self::Consumables,
+ self::EulaPdfs,
+ self::Imports,
+ self::Licenses,
+ self::Locations,
+ self::Maintenances,
+ self::Models,
+ self::Signatures,
+ self::Users => true,
+ default => false,
+ };
+ }
+
+ /**
+ * Public upload subdir with trailing slash, suitable for appending
+ * a filename. Returns null when the resource has no public scope.
+ */
+ public function publicPath(): ?string
+ {
+ return $this->hasPublicScope() ? $this->value.'/' : null;
+ }
+
+ /**
+ * Private upload subdir with trailing slash. Returns null when the
+ * resource has no private scope.
+ */
+ public function privatePath(): ?string
+ {
+ return $this->hasPrivateScope() ? $this->value.'/' : null;
+ }
+
+ /**
+ * Full public directory, relative to the repo root. For restore
+ * extraction + pruning.
+ */
+ public function publicDir(): ?string
+ {
+ return $this->hasPublicScope() ? 'public/uploads/'.$this->value : null;
+ }
+
+ /**
+ * Full private directory, relative to the repo root. For restore
+ * extraction + pruning.
+ */
+ public function privateDir(): ?string
+ {
+ return $this->hasPrivateScope() ? 'storage/private_uploads/'.$this->value : null;
+ }
+
+ /**
+ * All public directories as a flat list. Format matches what
+ * RestoreFromBackup's extraction + pruning loops consume.
+ *
+ * @return list<string>
+ */
+ public static function publicDirs(): array
+ {
+ $out = [];
+ foreach (self::cases() as $case) {
+ if ($case->hasPublicScope()) {
+ $out[] = $case->publicDir();
+ }
+ }
+
+ return $out;
+ }
+
+ /**
+ * All private directories, including historical aliases mapped to
+ * their current destinations.
+ * Integer keys for straight entries, string keys for alias =>
+ * destination.
+ *
+ * @return array<int|string, string>
+ */
+ public static function privateDirs(): array
+ {
+ $out = [];
+ $privateNames = [];
+ foreach (self::cases() as $case) {
+ if ($case->hasPrivateScope()) {
+ $out[] = $case->privateDir();
+ $privateNames[$case->value] = true;
+ }
+ }
+ foreach (self::PRIVATE_ALIASES as $old => $new) {
+ if (isset($privateNames[$new])) {
+ $out['storage/private_uploads/'.$old] = 'storage/private_uploads/'.$new;
+ }
+ }
+
+ return $out;
+ }
+}
diff --git a/tests/Unit/Enums/FileStorageTest.php b/tests/Unit/Enums/FileStorageTest.php
new file mode 100644
index 0000000000..0fe4f06273
--- /dev/null
+++ b/tests/Unit/Enums/FileStorageTest.php
@@ -0,0 +1,77 @@
+<?php
+
+namespace Tests\Unit\Enums;
+
+use App\Enums\FileStorage;
+use Tests\TestCase;
+
+class FileStorageTest extends TestCase
+{
+ public function test_public_only_cases_expose_public_paths_and_not_private(): void
+ {
+ $this->assertSame('avatars/', FileStorage::Avatars->publicPath());
+ $this->assertSame('public/uploads/avatars', FileStorage::Avatars->publicDir());
+ $this->assertNull(FileStorage::Avatars->privatePath());
+ $this->assertNull(FileStorage::Avatars->privateDir());
+ }
+
+ public function test_private_only_cases_expose_private_paths_and_not_public(): void
+ {
+ $this->assertSame('signatures/', FileStorage::Signatures->privatePath());
+ $this->assertSame('storage/private_uploads/signatures', FileStorage::Signatures->privateDir());
+ $this->assertNull(FileStorage::Signatures->publicPath());
+ $this->assertNull(FileStorage::Signatures->publicDir());
+ }
+
+ public function test_both_scope_cases_expose_both_paths(): void
+ {
+ // Assets split content across both scopes: public holds asset
+ // pictures, private holds asset file attachments.
+ $this->assertSame('assets/', FileStorage::Assets->publicPath());
+ $this->assertSame('assets/', FileStorage::Assets->privatePath());
+ $this->assertSame('public/uploads/assets', FileStorage::Assets->publicDir());
+ $this->assertSame('storage/private_uploads/assets', FileStorage::Assets->privateDir());
+ }
+
+ public function test_public_dirs_enumeration_includes_barcodes_cache(): void
+ {
+ // Barcode cache dir has to be in the public enumeration so the
+ // restore prunes stale QR / 1D barcode images that would
+ // otherwise linger from the previous install.
+ $this->assertContains('public/uploads/barcodes', FileStorage::publicDirs());
+ }
+
+ public function test_private_dirs_enumeration_includes_historical_aliases(): void
+ {
+ // Backups from older installs may carry old subdir names.
+ // The restore maps them to their current destinations so the
+ // files land correctly after the rename.
+ $privateDirs = FileStorage::privateDirs();
+
+ $this->assertArrayHasKey('storage/private_uploads/assetmodels', $privateDirs);
+ $this->assertSame('storage/private_uploads/models', $privateDirs['storage/private_uploads/assetmodels']);
+
+ $this->assertArrayHasKey('storage/private_uploads/asset_maintenances', $privateDirs);
+ $this->assertSame('storage/private_uploads/maintenances', $privateDirs['storage/private_uploads/asset_maintenances']);
+ }
+
+ public function test_public_dirs_includes_every_public_scoped_case(): void
+ {
+ $publicDirs = FileStorage::publicDirs();
+ foreach (FileStorage::cases() as $case) {
+ if ($case->hasPublicScope()) {
+ $this->assertContains($case->publicDir(), $publicDirs, "Public dir enumeration missing {$case->value}.");
+ }
+ }
+ }
+
+ public function test_private_dirs_includes_every_private_scoped_case(): void
+ {
+ $privateDirs = FileStorage::privateDirs();
+ foreach (FileStorage::cases() as $case) {
+ if ($case->hasPrivateScope()) {
+ $this->assertContains($case->privateDir(), $privateDirs, "Private dir enumeration missing {$case->value}.");
+ }
+ }
+ }
+}