> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP 요청

> Laravel의 Illuminate\Http\Request 객체를 사용해 HTTP 요청 데이터를 가져오는 방법을 설명합니다.

## Request 객체란

`Illuminate\Http\Request`는 애플리케이션이 받는 HTTP 요청을 객체 지향적으로 다루기 위한 클래스입니다.
폼 데이터·쿼리 문자열·파일·헤더 등 요청에 포함되는 모든 정보에 접근할 수 있습니다.

## 컨트롤러에 요청 주입

컨트롤러의 메서드에서 `Illuminate\Http\Request`를 타입 힌트하면, Laravel의 서비스 컨테이너가 자동으로 요청 인스턴스를 주입합니다.

```php theme={null}
<?php

namespace App\Http\Controllers;

use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class UserController extends Controller
{
    public function store(Request $request): RedirectResponse
    {
        $name = $request->input('name');

        // 사용자를 저장하는 처리...

        return redirect('/users');
    }
}
```

라우트 클로저에서도 동일하게 타입 힌트할 수 있습니다.

```php theme={null}
use Illuminate\Http\Request;

Route::get('/', function (Request $request) {
    // ...
});
```

### 라우트 파라미터와의 병용

컨트롤러 메서드가 라우트 파라미터도 받는 경우, `Request` 뒤에 라우트 파라미터를 작성합니다.

```php theme={null}
use App\Http\Controllers\UserController;

Route::put('/user/{id}', [UserController::class, 'update']);
```

```php theme={null}
public function update(Request $request, string $id): RedirectResponse
{
    // $request로 요청 데이터에, $id로 라우트 파라미터에 접근할 수 있다

    return redirect('/users');
}
```

## 요청 데이터 가져오기

### 모든 입력 데이터 가져오기

`all` 메서드로 모든 입력 데이터를 배열로 가져옵니다.
HTML 폼에서의 요청에서도 XHR 요청에서도 사용할 수 있습니다.

```php theme={null}
$input = $request->all();
```

### 특정 필드 가져오기

`input` 메서드는 HTTP 메서드와 상관없이, 요청 페이로드 전체(쿼리 문자열 포함)에서 값을 가져옵니다.

```php theme={null}
$name = $request->input('name');
```

값이 존재하지 않을 경우의 기본값을 두 번째 인수로 지정할 수 있습니다.

```php theme={null}
$name = $request->input('name', 'Sally');
```

배열 입력에는 점 표기법으로 접근합니다.

```php theme={null}
$name = $request->input('products.0.name');

$names = $request->input('products.*.name');
```

### 쿼리 문자열 가져오기

`query` 메서드는 쿼리 문자열(URL의 `?` 이후)에서만 값을 가져옵니다.

```php theme={null}
$name = $request->query('name');

$name = $request->query('name', 'Helen');

// 모든 쿼리 문자열을 배열로 가져오기
$query = $request->query();
```

<Info>
  `input`은 요청 본문과 쿼리 문자열 양쪽을 대상으로 하지만, `query`는 쿼리 문자열만을 대상으로 합니다.
  폼의 POST 데이터와 URL 파라미터를 구별하고 싶은 경우에는 `query`를 사용합시다.
</Info>

### 타입 지정 가져오기

`input` 이외에도 타입을 지정해 입력 값을 가져오는 메서드가 있습니다.

```php theme={null}
// 문자열로 가져오기(Stringable 인스턴스)
$name = $request->string('name')->trim();

// 정수로 가져오기
$perPage = $request->integer('per_page');

// 불리언으로 가져오기("1", "true", "on", "yes" → true)
$archived = $request->boolean('archived');

// 배열로 가져오기
$versions = $request->array('versions');

// 날짜를 Carbon 인스턴스로 가져오기
$birthday = $request->date('birthday');
```

### 동적 프로퍼티

필드 이름을 그대로 프로퍼티로 접근할 수도 있습니다.

```php theme={null}
$name = $request->name;
```

<Tip>
  동적 프로퍼티에서는 먼저 요청 페이로드에서 값을 찾고, 없으면 라우트 파라미터를 검색합니다.
</Tip>

### 입력 데이터의 일부 가져오기

`only`와 `except`로 입력 데이터의 서브셋을 가져올 수 있습니다.

```php theme={null}
$input = $request->only(['username', 'password']);

$input = $request->except(['credit_card']);
```

## 입력의 존재 확인

`has` 메서드로 값이 요청에 포함되어 있는지 확인합니다.

```php theme={null}
if ($request->has('name')) {
    // ...
}

// 여러 키를 모두 포함하는지 확인
if ($request->has(['name', 'email'])) {
    // ...
}
```

빈 문자열을 제외하고 값이 존재하는지는 `filled`를 사용합니다.

```php theme={null}
if ($request->filled('name')) {
    // ...
}
```

값이 존재하지 않거나 빈 문자열인 경우에는 `isNotFilled`를 사용합니다.

```php theme={null}
if ($request->isNotFilled('name')) {
    // ...
}
```

## 요청의 경로와 메서드 확인

### 경로 가져오기와 확인

```php theme={null}
// 경로 가져오기(예: "foo/bar")
$uri = $request->path();

// 패턴과 일치하는지 확인(와일드카드 *를 사용할 수 있다)
if ($request->is('admin/*')) {
    // ...
}

// 이름 지정 라우트와 일치하는지 확인
if ($request->routeIs('admin.*')) {
    // ...
}
```

### URL 가져오기

```php theme={null}
// 쿼리 문자열 없는 URL
$url = $request->url();

// 쿼리 문자열을 포함한 URL
$urlWithQueryString = $request->fullUrl();
```

### HTTP 메서드 확인

`isMethod`로 HTTP 메서드를 확인할 수 있습니다.

```php theme={null}
$method = $request->method();

if ($request->isMethod('post')) {
    // POST 요청만 처리한다
}
```

## 파일 업로드

### 업로드된 파일 가져오기

`file` 메서드로 업로드된 파일을 가져옵니다.
`Illuminate\Http\UploadedFile` 인스턴스가 반환됩니다.

```php theme={null}
$file = $request->file('photo');

// 동적 프로퍼티로도 가져올 수 있다
$file = $request->photo;
```

파일이 존재하는지 확인하려면 `hasFile`을 사용합니다.

```php theme={null}
if ($request->hasFile('photo')) {
    // ...
}
```

### 파일 저장

`store` 메서드로 파일을 스토리지에 저장합니다.
파일명은 자동으로 생성됩니다.

```php theme={null}
// 기본 디스크의 "images" 디렉터리에 저장
$path = $request->photo->store('images');

// S3에 저장
$path = $request->photo->store('images', 's3');
```

파일명을 지정하고 싶은 경우에는 `storeAs`를 사용합니다.

```php theme={null}
$path = $request->photo->storeAs('images', 'filename.jpg');
```

<Warning>
  파일 업로드를 받는 경우에는 반드시 파일의 종류와 크기를 검증해 주세요.
  유효성 검증을 사용해 안전하게 처리할 것을 권장합니다.
</Warning>

## 실전 예시: 폼 데이터 받기

사용자 등록 폼의 데이터를 컨트롤러에서 받는 예시입니다.

```php theme={null}
<?php

namespace App\Http\Controllers;

use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class RegisterController extends Controller
{
    public function store(Request $request): RedirectResponse
    {
        // 폼 데이터 가져오기
        $name = $request->input('name');
        $email = $request->input('email');
        $password = $request->input('password');

        // 필요한 데이터만 가져오기
        $data = $request->only(['name', 'email', 'password']);

        // 사용자를 생성하는 처리...

        return redirect('/dashboard');
    }
}
```

대응하는 라우트를 정의합니다.

```php theme={null}
use App\Http\Controllers\RegisterController;

Route::post('/register', [RegisterController::class, 'store']);
```

## 다음 단계

<Card title="미들웨어" icon="shield" href="/ko/middleware">
  요청을 필터링하는 미들웨어의 사용법을 되짚어 봅니다.
</Card>


## Related topics

- [요청 라이프사이클](/ko/lifecycle.md)
- [미들웨어](/ko/middleware.md)
- [Inertia.js로 SPA 구축하기](/ko/blog/inertia-introduction.md)
- [컨트롤러](/ko/controllers.md)
- [Laravel Nightwatch 입문](/ko/blog/nightwatch-introduction.md)