Laravel (PHP) da Professional darajada yozilgan Logistika tizimining yuragi bo'lgan "Yangi Yuk Yaratish" (POST /shipments) funksiyasini

Bu shunchaki oddiy kod emas, balki "Enterprise" standartlariga (DB Transactions, Validation, Service Pattern) asoslangan yechimdir.

1. Laravel Arxitekturasi

Biz quyidagi ketma-ketlikda ishlaymiz:

1. Request (Validation): Kiruvchi ma'lumotlarni tekshirish.

2. Controller: Mantiqni boshqarish.

3. Service/Logic: Tranzaksiyalar va ma'lumotlarni saqlash.

4. Resource: Javobni chiroyli formatda qaytarish.

A. So'rovni Validatsiya Qilish (StoreShipmentRequest)

Avval terminalda: php artisan make:request StoreShipmentRequest

PHP

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StoreShipmentRequest extends FormRequest
{
    public function authorize()
    {
        return true; // Hozircha hamma uchun ochiq, keyinchalik permission qo'shiladi
    }

    public function rules()
    {
        return [
            // Yuboruvchi
            'sender' => 'required|array',
            'sender.full_name' => 'required|string|max:255',
            'sender.phone' => 'required|string|max:20',
            'sender.address' => 'required|string|max:500',
            
            // Qabul qiluvchi
            'receiver' => 'required|array',
            'receiver.full_name' => 'required|string|max:255',
            'receiver.phone' => 'required|string|max:20',
            'receiver.address' => 'required|string|max:500',

            // Xizmat turi
            'service_type' => 'required|in:STANDARD,EXPRESS,OVERNIGHT',

            // Qadoqlar (Array validation)
            'packages' => 'required|array|min:1',
            'packages.*.weight_kg' => 'required|numeric|min:0.1',
            'packages.*.length_cm' => 'required|integer|min:1',
            'packages.*.width_cm' => 'required|integer|min:1',
            'packages.*.height_cm' => 'required|integer|min:1',
            'packages.*.description' => 'nullable|string',
        ];
    }
}

B. Controller Logikasi (ShipmentController)

Bu yerda biz Database Transaction ishlatamiz. Sababi: agar "Yuk" yaratilib, lekin uning ichidagi "Qadoqlar" (packages) bazaga yozilmay qolsa, tizim buziladi. Tranzaksiya hammasi muvaffaqiyatli bo'lsagina saqlaydi (commit), aks holda bekor qiladi (rollback).

PHP

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Http\Requests\StoreShipmentRequest;
use App\Models\Shipment;
use App\Models\Package;
use App\Models\TrackingEvent;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Str;

class ShipmentController extends Controller
{
    public function store(StoreShipmentRequest $request)
    {
        // 1. Validatsiyadan o'tgan ma'lumotlarni olish
        $data = $request->validated();

        try {
            // 2. Tranzaksiyani boshlash (Atomar operatsiya)
            $shipment = DB::transaction(function () use ($data) {
                
                // A. Tracking raqam generatsiya qilish (Unikal)
                $trackingNumber = 'MSB-' . strtoupper(Str::random(8));

                // B. Yukni (Shipment) yaratish
                $shipment = Shipment::create([
                    'tracking_number' => $trackingNumber,
                    'sender_info' => json_encode($data['sender']), // JSONB ustun uchun
                    'receiver_info' => json_encode($data['receiver']),
                    'service_type' => $data['service_type'],
                    'status' => 'CREATED',
                    // Narxni hisoblash logikasi alohida servisda bo'lishi kerak, bu yerda misol:
                    'total_price' => collect($data['packages'])->sum('weight_kg') * 15000, 
                ]);

                // C. Qadoqlarni (Packages) yaratish
                foreach ($data['packages'] as $pkg) {
                    Package::create([
                        'shipment_id' => $shipment->id,
                        'barcode' => $shipment->tracking_number . '-' . Str::random(4),
                        'weight_kg' => $pkg['weight_kg'],
                        'dimensions' => json_encode([
                            'l' => $pkg['length_cm'],
                            'w' => $pkg['width_cm'],
                            'h' => $pkg['height_cm']
                        ]),
                        'description' => $pkg['description'] ?? null,
                    ]);
                }

                // D. Birinchi Tracking voqeasini yozish
                TrackingEvent::create([
                    'shipment_id' => $shipment->id,
                    'status_code' => 'CREATED',
                    'description' => 'Buyurtma tizimga kiritildi',
                    'location' => 'Online', // Yoki foydalanuvchi turgan shahar
                ]);

                return $shipment;
            });

            // 3. Muvaffaqiyatli javob qaytarish
            return response()->json([
                'success' => true,
                'message' => 'Buyurtma muvaffaqiyatli yaratildi.',
                'data' => [
                    'tracking_number' => $shipment->tracking_number,
                    'status' => $shipment->status,
                    'created_at' => $shipment->created_at,
                    'label_url' => route('api.shipments.label', ['tracking_number' => $shipment->tracking_number])
                ]
            ], 201);

        } catch (\Exception $e) {
            // Xatolik yuz bersa
            return response()->json([
                'success' => false,
                'message' => 'Tizim xatoligi yuz berdi: ' . $e->getMessage()
            ], 500);
        }
    }
}

C. API Route (routes/api.php)

PHP

use App\Http\Controllers\Api\ShipmentController;

Route::post('/v1/shipments', [ShipmentController::class, 'store']);

2. Postman Collection Uchun Qo'llanma

Endi ushbu kodni sinash uchun Postman dasturini sozlaymiz.

1-qadam: Yangi Request yaratish

• Method: POST

• URL: http://localhost:8000/api/v1/shipments (yoki sizning domeningiz)

2-qadam: Headers sozlamalari

• Content-Type: application/json

• Accept: application/json

3-qadam: Body (Raw JSON) Quyidagi JSON ma'lumotni nusxalab, Postman body qismiga qo'ying:

JSON

{
    "service_type": "EXPRESS",
    "sender": {
        "full_name": "Azizbek Karimov",
        "phone": "+998901234567",
        "address": "Toshkent sh, Chilonzor 1-kvartal, 5-uy"
    },
    "receiver": {
        "full_name": "Sardor Aliyev",
        "phone": "+998939876543",
        "address": "Samarqand sh, Gagarin ko'chasi, 22-uy"
    },
    "packages": [
        {
            "weight_kg": 2.5,
            "length_cm": 30,
            "width_cm": 20,
            "height_cm": 10,
            "description": "Noutbuk va zaryadlovchi"
        },
        {
            "weight_kg": 5.0,
            "length_cm": 40,
            "width_cm": 30,
            "height_cm": 20,
            "description": "Kitoblar to'plami"
        }
    ]
}

4-qadam: Javobni tekshirish "Send" tugmasini bosing. Agar hammasi to'g'ri bo'lsa, sizga quyidagi javob qaytishi kerak (Status 201 Created):

JSON

{
    "success": true,
    "message": "Buyurtma muvaffaqiyatli yaratildi.",
    "data": {
        "tracking_number": "MSB-X7Y9Z2A1",
        "status": "CREATED",
        "created_at": "2026-02-15T11:45:00.000000Z",
        "label_url": "http://localhost:8000/api/shipments/MSB-X7Y9Z2A1/label"
    }
}

Professional Maslahat: Logistika loyihasi katta bo'lgani uchun, kelajakda ShipmentController ichidagi logikani Service Class ga ko'chirishni tavsiya qilaman (masalan, ShipmentService). Controller faqat "Traffic Police" vazifasini bajarishi kerak (keldi -> tekshirdi -> servisga berdi -> javob qaytardi).