feature: add address api

- users can save, edi and delete addresses
- each user can have multiple address
- used shallow routes for address

backend/app/Actions/DeleteUserAddressAction.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace App\Actions;
+
+use App\Models\Address;
+
+final readonly class DeleteUserAddressAction
+{
+    /**
+     * Execute the action.
+     */
+    public function execute(Address $address)
+    {
+        $address->users()->detach();
+        $address->delete();
+
+        return response()->noContent();
+    }
+}

backend/app/Actions/SaveUserAddressAction.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace App\Actions;
+
+use App\Data\AddUserAddressRequestDTO;
+use App\Data\UserAddressResponseDTO;
+use App\Models\User;
+
+final readonly class SaveUserAddressAction
+{
+    /**
+     * Execute the action.
+     */
+    public function execute(AddUserAddressRequestDTO $data, User $user)
+    {
+        return UserAddressResponseDTO::fromModel(
+            $user
+                ->addresses()
+                ->create($data->toArray())
+        );
+    }
+}

backend/app/Actions/UpdateUserAddressAction.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace App\Actions;
+
+use App\Data\UpdateUserAddressRequestDTO;
+use App\Data\UserAddressResponseDTO;
+use App\Models\Address;
+
+final readonly class UpdateUserAddressAction
+{
+    /**
+     * Execute the action.
+     */
+    public function execute(UpdateUserAddressRequestDTO $data, Address $address)
+    {
+        $address->update($data->toArray());
+        $address->refresh();
+
+        return UserAddressResponseDTO::fromModel($address);
+    }
+}

backend/app/Data/AddUserAddressRequestDTO.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace App\Data;
+
+use App\Contracts\InputDataTransferObject;
+use Illuminate\Foundation\Http\FormRequest;
+
+final readonly class AddUserAddressRequestDTO implements InputDataTransferObject
+{
+    public function __construct(
+        public string $firstName,
+        public string $lastName,
+        public string $street,
+        public string $city,
+        public string $state,
+        public string $pinCode
+    ) {}
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function toArray(): array
+    {
+        return [
+            'first_name' => $this->firstName,
+            'last_name' => $this->lastName,
+            'street' => $this->street,
+            'city' => $this->city,
+            'state' => $this->state,
+            'pin' => $this->pinCode,
+        ];
+    }
+
+    public static function fromRequest(FormRequest $request): InputDataTransferObject
+    {
+        return new self(
+            firstName: $request->firstName,
+            lastName: $request->lastName,
+            street: $request->street,
+            city: $request->city,
+            state: $request->state,
+            pinCode: $request->pinCode
+        );
+    }
+}

backend/app/Data/UpdateUserAddressRequestDTO.php

@@ -0,0 +1,47 @@
+<?php
+
+namespace App\Data;
+
+use App\Contracts\InputDataTransferObject;
+use Illuminate\Foundation\Http\FormRequest;
+
+final readonly class UpdateUserAddressRequestDTO implements InputDataTransferObject
+{
+    public function __construct(
+        public ?string $firstName = null,
+        public ?string $lastName = null,
+        public ?string $street = null,
+        public ?string $city = null,
+        public ?string $state = null,
+        public ?string $pinCode = null,
+    ) {}
+
+    /**
+     * @return array<string = null = null, mixed>
+     */
+    public function toArray(): array
+    {
+        $data = [
+            'first_name' => $this->firstName,
+            'last_name' => $this->lastName,
+            'street' => $this->street,
+            'city' => $this->city,
+            'state' => $this->state,
+            'pin' => $this->pinCode,
+        ];
+
+        return array_filter($data, fn ($value) => $value !== null);
+    }
+
+    public static function fromRequest(FormRequest $request): InputDataTransferObject
+    {
+        return new self(
+            firstName: $request->input('firstName'),
+            lastName: $request->input('lastName'),
+            street: $request->input('street'),
+            city: $request->input('city'),
+            state: $request->input('state'),
+            pinCode: $request->input('pinCode'),
+        );
+    }
+}

backend/app/Data/UserAddressResponseDTO.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace App\Data;
+
+use App\Contracts\OutputDataTransferObject;
+use App\Models\Address;
+
+final readonly class UserAddressResponseDTO implements OutputDataTransferObject
+{
+    public function __construct(
+        public int $id,
+        public string $firstName,
+        public string $lastName,
+        public string $street,
+        public string $city,
+        public string $state,
+        public string $pinCode
+    ) {}
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function toArray(): array
+    {
+        return [
+            'id' => $this->id,
+            'firstName' => $this->firstName,
+            'lastName' => $this->lastName,
+            'street' => $this->street,
+            'city' => $this->city,
+            'state' => $this->state,
+            'pinCode' => $this->pinCode,
+        ];
+    }
+
+    public static function fromModel(Address $address): OutputDataTransferObject
+    {
+        return new self(
+            id: $address->id,
+            firstName: $address->first_name,
+            lastName: $address->last_name,
+            street: $address->street,
+            city: $address->city,
+            state: $address->state,
+            pinCode: $address->pin
+        );
+    }
+}

backend/app/Http/Controllers/UserAddressController.php

@@ -0,0 +1,61 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Actions\DeleteUserAddressAction;
+use App\Actions\SaveUserAddressAction;
+use App\Actions\UpdateUserAddressAction;
+use App\Data\AddUserAddressRequestDTO;
+use App\Data\UpdateUserAddressRequestDTO;
+use App\Data\UserAddressResponseDTO;
+use App\Http\Requests\AddUserAddressRequest;
+use App\Http\Requests\UpdateUserAddressRequest;
+use App\Http\Resources\AddressResource;
+use App\Models\Address;
+use Illuminate\Http\Request;
+
+class UserAddressController extends Controller
+{
+    /**
+     * Display a listing of the resource.
+     */
+    public function index(Request $request)
+    {
+        $addresses = $request->user()->addresses;
+        $data = $addresses->map(fn ($address) => UserAddressResponseDTO::fromModel($address));
+
+        return AddressResource::collection($data);
+    }
+
+    /**
+     * Store a newly created resource in storage.
+     */
+    public function store(AddUserAddressRequest $request, SaveUserAddressAction $action)
+    {
+        return new AddressResource($action->execute(AddUserAddressRequestDTO::fromRequest($request), $request->user()));
+    }
+
+    /**
+     * Display the specified resource.
+     */
+    public function show(Address $address)
+    {
+        return new AddressResource(UserAddressResponseDTO::fromModel($address));
+    }
+
+    /**
+     * Update the specified resource in storage.
+     */
+    public function update(UpdateUserAddressRequest $request, Address $address, UpdateUserAddressAction $action)
+    {
+        return new AddressResource($action->execute(UpdateUserAddressRequestDTO::fromRequest($request), $address));
+    }
+
+    /**
+     * Remove the specified resource from storage.
+     */
+    public function destroy(Address $address, DeleteUserAddressAction $action)
+    {
+        return $action->execute($address);
+    }
+}

backend/app/Http/Requests/AddUserAddressRequest.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace App\Http\Requests;
+
+use Illuminate\Contracts\Validation\ValidationRule;
+use Illuminate\Foundation\Http\FormRequest;
+
+class AddUserAddressRequest extends FormRequest
+{
+    /**
+     * Determine if the user is authorized to make this request.
+     */
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Get the validation rules that apply to the request.
+     *
+     * @return array<string, ValidationRule|array<mixed>|string>
+     */
+    public function rules(): array
+    {
+        return [
+            'firstName' => 'required|string|min:3|max:50',
+            'lastName' => 'required|string|min:3|max:50',
+            'street' => 'required|string|min:3|max:100',
+            'city' => 'required|string|min:3|max:20',
+            'state' => 'required|string|min:3|max:40',
+            'pinCode' => 'required|string|min:3|max:10',
+        ];
+    }
+}

backend/app/Http/Requests/UpdateUserAddressRequest.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace App\Http\Requests;
+
+use Illuminate\Contracts\Validation\ValidationRule;
+use Illuminate\Foundation\Http\FormRequest;
+
+class UpdateUserAddressRequest extends FormRequest
+{
+    /**
+     * Determine if the user is authorized to make this request.
+     */
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Get the validation rules that apply to the request.
+     *
+     * @return array<string, ValidationRule|array<mixed>|string>
+     */
+    public function rules(): array
+    {
+        return [
+            'firstName' => 'sometimes|string|min:3|max:50',
+            'lastName' => 'sometimes|string|min:3|max:50',
+            'street' => 'sometimes|string|min:3|max:100',
+            'city' => 'sometimes|string|min:3|max:20',
+            'state' => 'sometimes|string|min:3|max:40',
+            'pinCode' => 'sometimes|string|min:3|max:10',
+
+        ];
+    }
+}

backend/app/Http/Resources/AddressCollection.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace App\Http\Resources;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\ResourceCollection;
+
+class AddressCollection extends ResourceCollection
+{
+    /**
+     * Transform the resource collection into an array.
+     *
+     * @return array<int|string, mixed>
+     */
+    public function toArray(Request $request): array
+    {
+        return parent::toArray($request);
+    }
+}

backend/app/Http/Resources/AddressResource.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace App\Http\Resources;
+
+use App\Data\UserAddressResponseDTO;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+/**
+ * @property UserAddressResponseDTO $resource
+ */
+class AddressResource extends JsonResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->resource->id,
+            'firstName' => $this->resource->firstName,
+            'lastName' => $this->resource->lastName,
+            'street' => $this->resource->street,
+            'city' => $this->resource->city,
+            'state' => $this->resource->state,
+            'pinCode' => $this->resource->pinCode,
+        ];
+    }
+}

backend/app/Models/Address.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Collection;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
+use Illuminate\Support\Carbon;
+
+/**
+ * @property-read User|null $user
+ *
+ * @method static \Illuminate\Database\Eloquent\Builder<static>|Address newModelQuery()
+ * @method static \Illuminate\Database\Eloquent\Builder<static>|Address newQuery()
+ * @method static \Illuminate\Database\Eloquent\Builder<static>|Address query()
+ *
+ * @property-read Collection<int, User> $users
+ * @property-read int|null $users_count
+ * @property int $id
+ * @property string $first_name
+ * @property string $last_name
+ * @property string $street
+ * @property string $city
+ * @property string $state
+ * @property string $pin
+ * @property Carbon|null $created_at
+ * @property Carbon|null $updated_at
+ *
+ * @method static \Illuminate\Database\Eloquent\Builder<static>|Address whereCity($value)
+ * @method static \Illuminate\Database\Eloquent\Builder<static>|Address whereCreatedAt($value)
+ * @method static \Illuminate\Database\Eloquent\Builder<static>|Address whereFirstName($value)
+ * @method static \Illuminate\Database\Eloquent\Builder<static>|Address whereId($value)
+ * @method static \Illuminate\Database\Eloquent\Builder<static>|Address whereLastName($value)
+ * @method static \Illuminate\Database\Eloquent\Builder<static>|Address wherePin($value)
+ * @method static \Illuminate\Database\Eloquent\Builder<static>|Address whereState($value)
+ * @method static \Illuminate\Database\Eloquent\Builder<static>|Address whereStreet($value)
+ * @method static \Illuminate\Database\Eloquent\Builder<static>|Address whereUpdatedAt($value)
+ *
+ * @mixin \Eloquent
+ */
+class Address extends Model
+{
+    protected $fillable = ['first_name', 'last_name', 'street', 'city', 'state', 'pin'];
+
+    public function users(): BelongsToMany
+    {
+        return $this->belongsToMany(User::class);
+    }
+}

backend/app/Models/User.php

@@ -4,28 +4,35 @@
 
 // use Illuminate\Contracts\Auth\MustVerifyEmail;
 use App\Enums\UserRoles;
+use Database\Factories\UserFactory;
+use Illuminate\Database\Eloquent\Collection;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
 use Illuminate\Foundation\Auth\User as Authenticatable;
+use Illuminate\Notifications\DatabaseNotification;
+use Illuminate\Notifications\DatabaseNotificationCollection;
 use Illuminate\Notifications\Notifiable;
+use Illuminate\Support\Carbon;
 
 /**
  * @property int $id
  * @property string $name
  * @property string $email
- * @property \Illuminate\Support\Carbon|null $email_verified_at
+ * @property Carbon|null $email_verified_at
  * @property string $password
  * @property string|null $remember_token
- * @property \Illuminate\Support\Carbon|null $created_at
- * @property \Illuminate\Support\Carbon|null $updated_at
+ * @property Carbon|null $created_at
+ * @property Carbon|null $updated_at
  * @property string $mobile_number
  * @property string $city
  * @property UserRoles $role
- * @property-read \Illuminate\Database\Eloquent\Collection<int, \App\Models\Cart> $carts
+ * @property-read Collection<int, Cart> $carts
  * @property-read int|null $carts_count
- * @property-read \Illuminate\Database\Eloquent\Collection<int, \App\Models\Product> $favoriteProducts
+ * @property-read Collection<int, Product> $favoriteProducts
  * @property-read int|null $favorite_products_count
- * @property-read \Illuminate\Notifications\DatabaseNotificationCollection<int, \Illuminate\Notifications\DatabaseNotification> $notifications
+ * @property-read DatabaseNotificationCollection<int, DatabaseNotification> $notifications
  * @property-read int|null $notifications_count
+ *
  * @method static \Database\Factories\UserFactory factory($count = null, $state = [])
  * @method static \Illuminate\Database\Eloquent\Builder<static>|User newModelQuery()
  * @method static \Illuminate\Database\Eloquent\Builder<static>|User newQuery()
@@ -41,11 +48,12 @@
  * @method static \Illuminate\Database\Eloquent\Builder<static>|User whereRememberToken($value)
  * @method static \Illuminate\Database\Eloquent\Builder<static>|User whereRole($value)
  * @method static \Illuminate\Database\Eloquent\Builder<static>|User whereUpdatedAt($value)
+ *
  * @mixin \Eloquent
  */
 class User extends Authenticatable
 {
-    /** @use HasFactory<\Database\Factories\UserFactory> */
+    /** @use HasFactory<UserFactory> */
     use HasFactory;
 
     use Notifiable;
@@ -88,7 +96,7 @@ protected function casts(): array
         ];
     }
 
-    public function favoriteProducts()
+    public function favoriteProducts(): BelongsToMany
     {
         return $this->belongsToMany(Product::class, 'favorite_products', 'user_id', 'product_id');
     }
@@ -102,4 +110,9 @@ public function carts()
     {
         return $this->hasMany(Cart::class);
     }
+
+    public function addresses(): BelongsToMany
+    {
+        return $this->belongsToMany(Address::class);
+    }
 }

backend/database/migrations/2026_03_12_141247_create_addresses_table.php

@@ -0,0 +1,33 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('addresses', function (Blueprint $table) {
+            $table->id();
+            $table->string('first_name');
+            $table->string('last_name');
+            $table->string('street');
+            $table->string('city');
+            $table->string('state');
+            $table->string('pin');
+            $table->timestamps();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('addresses');
+    }
+};

backend/database/migrations/2026_03_12_141909_address_user.php

@@ -0,0 +1,29 @@
+<?php
+
+use App\Models\Address;
+use App\Models\User;
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('address_user', function (Blueprint $table) {
+            $table->foreignIdFor(User::class)->constrained()->cascadeOnDelete();
+            $table->foreignIdFor(Address::class)->constrained()->cascadeOnDelete();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('address_user');
+    }
+};

backend/routes/api.php

@@ -7,6 +7,7 @@
 use App\Http\Controllers\ProductController;
 use App\Http\Controllers\ProductImagesController;
 use App\Http\Controllers\RegisteredUserController;
+use App\Http\Controllers\UserAddressController;
 use Illuminate\Support\Facades\Route;
 
 Route::middleware('guest')->group(function () {
@@ -24,6 +25,8 @@
     Route::apiSingleton('/cart', CartController::class)
         ->creatable()
         ->destroyable();
+
+    Route::apiResource('user.addresses', UserAddressController::class)->shallow();
 });
 Route::get('/categories', [ProductCategoryController::class, 'index']);
 Route::apiResource('products', ProductController::class);