Что такое PUT запрос?

Что такое PUT запрос?

PUT (от англ. «to put» — размещать, класть) — это один из основных HTTP-методов (наряду с GET, POST, DELETE, PATCH), используемый в архитектуре RESTful API. Его основное назначение — полное обновление существующего ресурса или создание нового ресурса по известному URI (идентификатору). Согласно спецификации HTTP (RFC 7231), PUT является идемпотентным методом: это означает, что несколько идентичных PUT-запросов подряд должны приводить к одному и тому же состоянию сервера, в отличие от POST.

Ключевые характеристики PUT-запроса

1. Идемпотентность и безопасность

• Идемпотентность: Повторение одного и того же PUT-запроса (с одинаковыми данными и URI) не изменяет результат после первого успешного выполнения. Если ресурс был создан или обновлен, последующие идентичные запросы просто подтвердят это состояние.
• Небезопасность: В отличие от GET, PUT изменяет состояние ресурса на сервере.

2. Семантика: «Полная замена»

PUT-запрос должен содержать полное представление ресурса, которым клиент хочет его заменить. Это ключевое отличие от метода PATCH, который предназначен для частичного обновления (отправляются только изменяемые поля).

Пример: Представим ресурс пользователя с URI /api/users/123 и следующими данными:

{
    "id": 123,
    "name": "Иван",
    "age": 30,
    "email": "ivan@example.com"
}

Клиент хочет изменить email. При использовании PUT он обязан отправить все поля, даже неизменяемые:

{
    "id": 123,
    "name": "Иван",
    "age": 30,
    "email": "ivan.new@example.com"
}

При использовании PATCH можно отправить только изменяемую часть:

{
    "email": "ivan.new@example.com"
}

3. Создание или обновление

• Если ресурс с указанным URI существует, сервер полностью заменяет его состояние на предоставленные данные.
• Если ресурс с указанным URI не существует, и сервер позволяет создание через PUT, то новый ресурс должен быть создан с этим URI и предоставленными данными. Однако на практике эта логика часто делегируется методу POST для создания, а PUT используется строго для обновлений.

Примеры использования в PHP Backend

Обработка PUT-запроса в чистом PHP

Глобальный массив $_PUT по умолчанию не существует, поэтому данные нужно извлекать из входного потока.

<?php
if ($_SERVER['REQUEST_METHOD'] === 'PUT') {
    // Получаем "сырые" данные из тела запроса
    $rawInput = file_get_contents('php://input');
    parse_str($rawInput, $putData); // Работает для form-data
    // Для JSON данных используем:
    $putData = json_decode($rawInput, true);

    // Извлекаем ID ресурса из URI (например, /users/123)
    $requestUri = $_SERVER['REQUEST_URI'];
    preg_match('/\/users\/(\d+)/', $requestUri, $matches);
    $userId = $matches[1] ?? null;

    if ($userId && isset($putData['name'], $putData['email'])) {
        // Здесь обычно происходит валидация и обновление в БД
        // Эмуляция обновления
        $response = [
            'status' => 'success',
            'message' => "Пользователь с ID $UserId обновлен.",
            'data' => ['id' => $userId] + $putData
        ];
        echo json_encode($response);
    } else {
        http_response_code(400); // Bad Request
        echo json_encode(['error' => 'Неверные данные или ID.']);
    }
}
?>

Обработка PUT в современном фреймворке (Laravel)

В Laravel роут и контроллер для PUT-запроса выглядят значительно проще благодаря встроенной функциональности.

// routes/api.php
Route::put('/users/{id}', [UserController::class, 'update']);

// app/Http/Controllers/UserController.php
public function update(Request $request, $id)
{
    // Валидация входящих данных (все поля обязательны для полного обновления)
    $validatedData = $request->validate([
        'name' => 'required|string|max:255',
        'email' => 'required|email|unique:users,email,' . $id,
        'age' => 'required|integer|min:0'
    ]);

    // Находим пользователя и обновляем
    $user = User::findOrFail($id);
    $user->update($validatedData); // Полная замена данных

    return response()->json([
        'message' => 'Пользователь успешно обновлен.',
        'user' => new UserResource($user)
    ], 200); // Статус 200 OK
}

Сравнение с другими методами (таблица)

*Примечание: PATCH не обязательно идемпотентен, но должен быть сделан таким, где это возможно.

Заключение

Понимание PUT-запроса критически важно для разработчика Backend, работающего с REST API. Его правильное применение обеспечивает предсказуемость и надежность API, строго следуя принципам идемпотентности и семантики полного обновления. В современных PHP-фреймворках работа с PUT инкапсулирована, но разработчик должен осознанно проектировать обработку данных, всегда требуя от клиента полное представление ресурса и корректно обрабатывая коды состояния HTTP (200, 204, 404, 400).