Merge pull request #1715 from dbarzin/coderabbitai/docstrings/7da4b61

📝 Add docstrings to `dev`

Author: dbarzin

app/Http/Controllers/Admin/SubnetworkController.php

@@ -32,6 +32,18 @@ public function store(StoreSubnetworkRequest $request)
         return redirect()->route('admin.subnetworks.index');
     }
 
+    /**
+     * Display the form to create a new Subnetwork and prepare selection lists for the view.
+     *
+     * Prepares ordered lists for gateways, vlans, networks, subnetworks and distinct non-null
+     * values for ip_allocation_type, responsible_exp, dmz, wifi, and zone. Aborts with HTTP 403
+     * if the current user is not authorized to create subnetworks.
+     *
+     * @return \Illuminate\View\View The create view populated with the prepared lists:
+     *                                `gateways`, `vlans`, `networks`, `subnetworks`,
+     *                                `ip_allocation_type_list`, `responsible_exp_list`,
+     *                                `dmz_list`, `wifi_list`, and `zone_list`.
+     */
     public function create()
     {
         abort_if(Gate::denies('subnetwork_create'), Response::HTTP_FORBIDDEN, '403 Forbidden');
@@ -65,6 +77,15 @@ public function create()
         );
     }
 
+    /**
+     * Display the edit form for a given subnetwork.
+     *
+     * Loads the `connected_subnets` and `gateway` relationships on the provided model
+     * and prepares lists used to populate select inputs in the edit view.
+     *
+     * @param \App\Models\Subnetwork $subnetwork The Subnetwork model to edit.
+     * @return \Illuminate\View\View The edit view populated with the subnetwork and selection lists.
+     */
     public function edit(Subnetwork $subnetwork)
     {
         abort_if(Gate::denies('subnetwork_edit'), Response::HTTP_FORBIDDEN, '403 Forbidden');
@@ -132,4 +153,4 @@ public function massDestroy(MassDestroySubnetworkRequest $request)
 
         return response(null, Response::HTTP_NO_CONTENT);
     }
-}
+}

app/Models/NetworkSwitch.php

@@ -52,7 +52,7 @@ public function physicalSwitches(): BelongsToMany
     /**
      * Get VLANs associated with this network switch, ordered by name.
      *
-     * @return BelongsToMany<Vlan, $this> A many-to-many relation for the related `Vlan` models, ordered by the `name` attribute.
+     * @return BelongsToMany<Vlan, $this> The many-to-many relation instance for the related `Vlan` models.
      */
     public function vlans(): BelongsToMany
     {

app/Models/Subnetwork.php

@@ -80,18 +80,36 @@ public function gateway(): BelongsTo
         return $this->belongsTo(Gateway::class, 'gateway_id');
     }
 
-    /** @return BelongsTo<Vlan, $this> */
+    /**
+     * Get the Vlan that this subnetwork is associated with.
+     *
+     * @return BelongsTo<Vlan, $this> Relationship to the Vlan model.
+     */
     public function vlan(): BelongsTo
     {
         return $this->belongsTo(Vlan::class, 'vlan_id');
     }
 
-    /** @return BelongsTo<Subnetwork, $this> */
+    /**
+     * Get the parent subnetwork that this subnetwork belongs to.
+     *
+     * @return BelongsTo<Subnetwork, $this> Relation to the parent Subnetwork model.
+     */
     public function subnetwork(): BelongsTo
     {
         return $this->belongsTo(Subnetwork::class, 'subnetwork_id');
     }
 
+    /**
+     * Produce a human-readable IP range for this subnetwork's CIDR address.
+     *
+     * Returns the inclusive range represented by the model's `address` property:
+     * - For IPv4 CIDRs returns "start - end".
+     * - For IPv6 CIDRs returns "first -> last".
+     * - Returns `null` when `address` is null and "N/A" when `address` is missing a prefix or not a valid IP/CIDR.
+     *
+     * @return string|null The IP range string, `null` if no address is set, or `"N/A"` for invalid/unparsable addresses.
+     */
     public function ipRange(): ?string
     {
         // no address
@@ -228,4 +246,4 @@ public function contains(string $ip): bool
 
         return false;
     }
-}
+}

app/Models/Vlan.php

@@ -50,17 +50,17 @@ public function physicalRouters(): BelongsToMany
     }
 
     /**
-     * Get the network switches associated with this VLAN, ordered by name.
+     * Network switches associated with this VLAN, ordered by name.
      *
-     * @return BelongsToMany<NetworkSwitch, $this> Relation for NetworkSwitch models related to this Vlan, ordered by `name`.
+     * @return BelongsToMany<NetworkSwitch, $this> Many-to-many relation yielding NetworkSwitch models ordered by `name`.
      */
     public function networkSwitches(): BelongsToMany
     {
         return $this->belongsToMany(NetworkSwitch::class)->orderBy('name');
     }
 
     /**
-     * Get subnetworks belonging to this VLAN ordered by name.
+     * Retrieve subnetworks that belong to this VLAN, ordered by `name`.
      *
      * @return HasMany<Subnetwork, $this> Subnetwork models associated with this VLAN, ordered by name.
      */

database/migrations/2025_10_17_073218_add_cluster_logical_server.php

@@ -24,6 +24,13 @@
      */
     public $withinTransaction = false;
 
+    /**
+     * Move cluster association from logical_servers into a pivot table.
+     *
+     * Creates the cluster_logical_server pivot table with a composite primary key and foreign keys,
+     * backfills it from existing logical_servers.cluster_id values, then removes the foreign key
+     * (and on non-SQLite drivers the cluster_id column) from logical_servers.
+     */
     public function up(): void
     {
 
@@ -111,4 +118,4 @@ public function down(): void
         // 4) Suppression de la table pivot
         Schema::dropIfExists('cluster_logical_server');
     }
-};
+};

database/migrations/2025_10_18_174616_add_cluster_physical_server.php

@@ -10,6 +10,17 @@
     // SQLite ne gère pas les DDL en transaction -> off
     public $withinTransaction = false;
 
+    / **
+     * Create the cluster_physical_server pivot table, migrate existing cluster associations into it,
+     * and remove the legacy `cluster_id` column and its related constraints/indexes from physical_servers.
+     *
+     * The migration performs three main actions:
+     * 1. Create the pivot table `cluster_physical_server` with a composite primary key (cluster_id, physical_server_id),
+     *    an index on `physical_server_id`, and cascading foreign keys to `clusters.id` and `physical_servers.id`.
+     * 2. Backfill the pivot from existing `physical_servers.cluster_id`, inserting (cluster_id, physical_server_id) pairs.
+     * 3. If `physical_servers.cluster_id` exists, drop its foreign key(s) and related indexes (including defensive attempts
+     *    for common/custom index names and a SQLite-specific purge of indexes containing "cluster_id"), then drop the column.
+     */
     public function up(): void
     {
         // 1) Table pivot
@@ -101,6 +112,11 @@ public function up(): void
         }
     }
 
+    /**
+     * Restores the physical_servers.cluster_id column, repopulates it from the pivot, re-adds the foreign key, and removes the pivot table.
+     *
+     * If missing, adds a nullable `cluster_id` column and index on `physical_servers`; sets `cluster_id` to the minimum associated cluster for each physical server based on `cluster_physical_server`; recreates the foreign key to `clusters(id)` with `ON DELETE CASCADE`; and drops the `cluster_physical_server` pivot table.
+     */
     public function down(): void
     {
         // 1) Recréer la colonne (nullable) + index
@@ -133,4 +149,4 @@ public function down(): void
         // 4) Drop de la table pivot
         Schema::dropIfExists('cluster_physical_server');
     }
-};
+};

database/migrations/2025_10_18_183453_add_cluster_router.php

@@ -10,6 +10,11 @@
     // DDL non transactionnel pour SQLite & co
     public $withinTransaction = false;
 
+    /**
+     * Apply migration: create the cluster_router pivot, migrate existing router->cluster relations into it, and remove the routers.cluster_id column and its constraints/indexes.
+     *
+     * Creates the cluster_router pivot table with foreign keys to clusters and routers, copies non-null routers.cluster_id values into the pivot (in batches), and then safely removes the cluster_id foreign key, related indexes and the column from the routers table (including defensive handling for legacy constraint/index names and SQLite).
+     */
     public function up(): void
     {
         // 1) Table pivot
@@ -98,6 +103,13 @@ public function up(): void
         }
     }
 
+    /**
+     * Reverts the migration by restoring the routers.cluster_id column and removing the cluster_router pivot.
+     *
+     * Restores a nullable unsigned integer `cluster_id` on `routers` (adds an index), populates it from `cluster_router`
+     * using the minimum `cluster_id` per `router_id`, recreates the foreign key to `clusters.id` with ON DELETE CASCADE,
+     * and then drops the `cluster_router` table.
+     */
     public function down(): void
     {
         // 1) Recréer la colonne (nullable) + index (laisser Laravel nommer)
@@ -130,4 +142,4 @@ public function down(): void
         // 4) Drop de la table pivot
         Schema::dropIfExists('cluster_router');
     }
-};
+};

database/migrations/2025_11_10_090632_add_subnetwork_link.php

@@ -7,7 +7,10 @@
 return new class extends Migration
 {
     /**
-     * Run the migrations.
+     * Add a nullable unsigned `subnetwork_id` column to the `subnetworks` table and create its index and foreign key.
+     *
+     * The new `subnetwork_id` column is placed after `network_id`, indexed, and constrained to `subnetworks.id` with
+     * `ON DELETE SET NULL` behavior.
      */
     public function up(): void
     {
@@ -24,7 +27,11 @@ public function up(): void
     }
 
     /**
-     * Reverse the migrations.
+     * Reverts the migration by removing the `subnetwork_id` column and its associated index and foreign key from the `subnetworks` table.
+     *
+     * If the `subnetwork_id` column does not exist, the method returns without making changes. On SQLite, foreign key and index removal are skipped and only the column is dropped.
+     *
+     * @return void
      */
     public function down(): void
     {
@@ -40,4 +47,4 @@ public function down(): void
             $table->dropColumn('subnetwork_id');
         });
     }
-};
+};