<?php

namespace App\Http\Controllers;

use App\Http\Requests\StoreItemRequest;
use App\Http\Requests\UpdateItemRequest;
use App\Http\Resources\ItemResource;
use App\Models\Item;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\AnonymousResourceCollection;

/**
 * Controller for managing inventory items.
 *
 * Provides CRUD operations for items with proper validation,
 * authorization, and resource transformation.
 */
class ItemController extends Controller
{
    /**
     * Display a listing of items.
     */
    public function index(Request $request): AnonymousResourceCollection
    {
        $items = Item::with(['partner', 'project', 'country'])
            ->when($request->has('search'), function ($query) use ($request) {
                $query->where('internal_name', 'like', "%{$request->search}%");
            })
            ->paginate(15);

        return ItemResource::collection($items);
    }

    /**
     * Store a newly created item.
     */
    public function store(StoreItemRequest $request): ItemResource
    {
        $item = Item::create($request->validated());

        return new ItemResource($item->load(['partner', 'project', 'country']));
    }
}

<?php

// ✅ Good - Organized imports
// 1. Laravel/Framework imports
use Illuminate\Http\Request;
use Illuminate\Http\JsonResponse;
use Illuminate\Support\Facades\DB;

// 2. Third-party imports
use Carbon\Carbon;

// 3. Internal imports - Models
use App\Models\Item;
use App\Models\Partner;

// 4. Internal imports - Resources
use App\Http\Resources\ItemResource;

// 5. Internal imports - Requests
use App\Http\Requests\StoreItemRequest;

// 6. Internal imports - Services
use App\Services\ImageProcessingService;

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Concerns\HasUuids;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Database\Eloquent\Relations\HasMany;

/**
 * Item model representing inventory objects.
 *
 * @property string $id
 * @property string $internal_name
 * @property string $partner_id
 * @property string $project_id
 * @property string $country_id
 * @property string|null $backward_compatibility
 * @property \Carbon\Carbon $created_at
 * @property \Carbon\Carbon $updated_at
 */
class Item extends Model
{
    use HasFactory, HasUuids;

    /**
     * The attributes that are mass assignable.
     */
    protected $fillable = [
        'internal_name',
        'partner_id',
        'project_id',
        'country_id',
        'backward_compatibility',
    ];

    /**
     * Get the columns that should receive a unique identifier.
     */
    public function uniqueIds(): array
    {
        return ['id'];
    }

    /**
     * Get the partner that owns the item.
     */
    public function partner(): BelongsTo
    {
        return $this->belongsTo(Partner::class);
    }

    /**
     * Get the project associated with the item.
     */
    public function project(): BelongsTo
    {
        return $this->belongsTo(Project::class);
    }

    /**
     * Get the country associated with the item.
     */
    public function country(): BelongsTo
    {
        return $this->belongsTo(Country::class);
    }

    /**
     * Get the pictures associated with the item.
     */
    public function pictures(): HasMany
    {
        return $this->hasMany(Picture::class);
    }
}

<?php

namespace App\Http\Controllers;

use App\Http\Requests\StoreItemRequest;
use App\Http\Requests\UpdateItemRequest;
use App\Http\Resources\ItemResource;
use App\Models\Item;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Resources\Json\AnonymousResourceCollection;

/**
 * ✅ Good - Resource controller with proper typing
 */
class ItemController extends Controller
{
    public function index(): AnonymousResourceCollection
    {
        $items = Item::with(['partner', 'project', 'country'])->paginate(15);

        return ItemResource::collection($items);
    }

    public function show(Item $item): ItemResource
    {
        return new ItemResource($item->load(['partner', 'project', 'country']));
    }

    public function store(StoreItemRequest $request): ItemResource
    {
        $item = Item::create($request->validated());

        return new ItemResource($item->load(['partner', 'project', 'country']));
    }

    public function update(UpdateItemRequest $request, Item $item): ItemResource
    {
        $item->update($request->validated());

        return new ItemResource($item->load(['partner', 'project', 'country']));
    }

    public function destroy(Item $item): JsonResponse
    {
        $item->delete();

        return response()->json(null, 204);
    }
}