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

# Laravel Pint

> PHP CS Fixer 위에 구축된 코드 스타일 자동 수정 도구. 팀에서 일관된 코딩 스타일을 유지하는 방법을 설명합니다.

## Laravel Pint란

[Laravel Pint](https://github.com/laravel/pint)는 PHP CS Fixer 위에 구축된 코드 스타일 자동 수정 도구입니다. 설정 없이 바로 사용할 수 있도록 설계되었으며, Laravel의 코딩 스타일에 따라 코드를 자동으로 정형화합니다.

팀 개발에서 자주 있는 "코드 스타일에 대한 리뷰 코멘트"를 자동화함으로써 본질적인 코드 리뷰에 집중할 수 있게 됩니다.

```mermaid theme={null}
flowchart LR
    A["PHP 파일"] --> B["pint 실행"]
    B --> C{스타일<br>에러 있음?}
    C -- 있음 --> D["자동 수정"]
    C -- 없음 --> E["변경 없음"]
    D --> F["정형화된 파일"]
    E --> F
```

## 설치

새로 생성된 Laravel 애플리케이션에는 Pint가 자동으로 설치되어 있습니다. 구버전 프로젝트에는 Composer로 설치해 주세요.

```shell theme={null}
composer require laravel/pint --dev
```

## 실행 방법

### 기본 사용법

프로젝트 내의 모든 `.php` 파일을 자동 수정합니다.

```shell theme={null}
./vendor/bin/pint
```

특정 파일이나 디렉터리만 대상으로 할 수도 있습니다.

```shell theme={null}
./vendor/bin/pint app/Models
./vendor/bin/pint app/Models/User.php
```

### 옵션 목록

| 옵션                  | 설명                                                  |
| ------------------- | --------------------------------------------------- |
| `--test`            | 파일을 변경하지 않고 스타일 에러만 검출한다. 에러가 있으면 0이 아닌 종료 코드를 반환한다 |
| `--dirty`           | Git으로 커밋되지 않은 변경이 있는 파일만 대상으로 한다                    |
| `--diff=[branch]`   | 지정 브랜치와의 차이가 있는 파일만 대상으로 한다                         |
| `--repair`          | 스타일 에러를 수정하면서 수정이 있으면 0이 아닌 종료 코드를 반환한다             |
| `--parallel`        | 병렬 실행 모드(실험적)로 성능을 향상시킨다                            |
| `--max-processes=4` | `--parallel`과 조합해 최대 프로세스 수를 지정한다                   |
| `-v`                | 변경 내용의 상세 정보를 표시한다                                  |
| `--config`          | 사용할 `pint.json`의 경로를 지정한다                           |
| `--preset`          | 사용할 프리셋을 지정한다                                       |

```shell theme={null}
# 파일을 변경하지 않고 체크만
./vendor/bin/pint --test

# 커밋되지 않은 파일만 대상
./vendor/bin/pint --dirty

# 병렬 실행
./vendor/bin/pint --parallel
```

## 설정

프로젝트 루트에 `pint.json`을 생성하여 동작을 커스터마이징할 수 있습니다.

```json theme={null}
{
    "preset": "laravel"
}
```

설정 파일 경로를 명시적으로 지정할 수도 있습니다.

```shell theme={null}
./vendor/bin/pint --config vendor/my-company/coding-style/pint.json
```

### 프리셋

프리셋은 규칙 세트입니다. 기본값은 `laravel` 프리셋이며, Laravel 프로젝트에 최적화된 규칙이 적용됩니다.

| 프리셋       | 설명                       |
| --------- | ------------------------ |
| `laravel` | Laravel의 권장 코딩 스타일(기본값)  |
| `psr12`   | PSR-12 코딩 표준             |
| `per`     | PER Coding Style         |
| `symfony` | Symfony의 코딩 스타일          |
| `empty`   | 규칙 없음. 개별적으로 규칙을 정의해서 사용 |

```shell theme={null}
# 커맨드라인에서 프리셋 지정
./vendor/bin/pint --preset psr12
```

### 규칙 커스터마이징

`pint.json`에서 규칙을 개별적으로 활성화/비활성화할 수 있습니다. 사용 가능한 규칙은 [PHP CS Fixer Configurator](https://mlocati.github.io/php-cs-fixer-configurator)를 참조해 주세요.

```json theme={null}
{
    "preset": "laravel",
    "rules": {
        "simplified_null_return": true,
        "array_indentation": false,
        "new_with_parentheses": {
            "anonymous_class": true,
            "named_class": true
        }
    }
}
```

### 파일·폴더 제외

특정 폴더를 검사 대상에서 제외할 수 있습니다.

```json theme={null}
{
    "exclude": [
        "my-specific/folder"
    ]
}
```

파일명 패턴으로 제외하는 경우에는 `notName`을 사용합니다.

```json theme={null}
{
    "notName": [
        "*-my-file.php"
    ]
}
```

특정 파일 경로로 제외하는 경우에는 `notPath`를 사용합니다.

```json theme={null}
{
    "notPath": [
        "path/to/excluded-file.php"
    ]
}
```

## 권장 설정

실제 개발 현장에서 효과적인 `pint.json` 설정 예시를 소개합니다.

```json theme={null}
{
    "preset": "laravel",
    "rules": {
        "no_unused_imports": false,
        "strict_comparison": true,
        "declare_strict_types": true
    }
}
```

각 규칙을 추가하는 이유는 다음과 같습니다.

| 규칙                     | 효과                                                                                                |
| ---------------------- | ------------------------------------------------------------------------------------------------- |
| `no_unused_imports`    | `false`로 하면 사용되지 않는 `use` 문을 삭제하지 않고 남긴다. Pint의 기본값은 `true`(삭제)이므로 일반적인 Laravel 프로젝트에서는 이 항목은 불필요 |
| `strict_comparison`    | `==`를 `===`로, `!=`를 `!==`로 변환하여 예기치 않은 형 변환 버그를 방지                                                |
| `declare_strict_types` | 파일 시작 부분에 `declare(strict_types=1);`를 자동 추가하여 타입 안전성을 높인다                                         |

<Tip>
  `strict_comparison`과 `declare_strict_types`는 타입에 엄격한 코드를 강제하므로 기존 프로젝트에 추가할 때 초회 수정량이 많아질 수 있습니다. 신규 프로젝트에서는 처음부터 도입하는 것을 권장합니다.
</Tip>

<Info>
  **`no_unused_imports`는 패키지 개발용 설정입니다.** Pint의 기본값은 `true`(사용되지 않는 `use` 문 삭제)이므로 일반적인 Laravel 프로젝트에서는 이 항목 자체가 불필요합니다. 패키지 개발에서는 트레이트나 인터페이스의 임포트로 기능을 온/오프하는 패턴이 있기 때문에, `false`를 추가해 두고 각 패키지 상황에 맞춰 `true`로 변경하는 운용이 편리합니다.
</Info>

## composer.json에 scripts 설정

`composer.json`에 `pint`용 스크립트를 등록하면 `composer pint`만으로 실행할 수 있게 됩니다.

```json theme={null}
{
    "scripts": {
        "pint": "./vendor/bin/pint",
        "pint:test": "./vendor/bin/pint --test"
    }
}
```

등록 후에는 다음과 같이 실행할 수 있습니다.

```shell theme={null}
# 코드를 자동 수정
composer pint

# 체크만(수정하지 않음)
composer pint:test
```

<Info>
  CI 환경에서는 `composer pint:test`를 사용하면 파일을 변경하지 않고 스타일 위반을 검출할 수 있습니다. `--test` 옵션은 에러가 있으면 0이 아닌 종료 코드를 반환하므로 CI의 패스 체크에 사용할 수 있습니다.
</Info>

## GitHub Actions에서 자동 실행

GitHub Actions를 사용해 푸시할 때마다 코드 스타일을 자동 수정·커밋할 수 있습니다.

<Steps>
  <Step title="Workflow의 권한을 설정한다">
    GitHub 리포지토리의 **Settings > Actions > General > Workflow permissions**에서 "Read and write permissions"를 활성화합니다.
  </Step>

  <Step title="Workflow 파일을 생성한다">
    `.github/workflows/lint.yml`을 생성합니다.

    ```yaml theme={null}
    name: Fix Code Style

    on: [push]

    jobs:
      lint:
        runs-on: ubuntu-latest
        strategy:
          fail-fast: true
          matrix:
            php: [8.4]

        steps:
          - name: Checkout code
            uses: actions/checkout@v5

          - name: Setup PHP
            uses: shivammathur/setup-php@v2
            with:
              php-version: ${{ matrix.php }}
              tools: pint

          - name: Run Pint
            run: pint

          - name: Commit linted files
            uses: stefanzweifel/git-auto-commit-action@v6
    ```
  </Step>
</Steps>

이 워크플로우는 푸시할 때마다 Pint를 실행하고, 스타일 위반을 수정한 파일을 자동으로 커밋합니다.

<Tip>
  Pull Request 리뷰 전에 자동 수정이 들어가므로 코드 스타일에 관한 리뷰 코멘트가 줄어듭니다. 팀에 도입할 때는 처음에 모든 파일을 로컬에서 수정한 후 워크플로우를 추가하면 여분의 커밋을 방지할 수 있습니다.
</Tip>


## Related topics

- [Laravel과 AI 개발](/ko/ai.md)
- [Laravel Package Skeleton — 공식 패키지용 스타터 템플릿](/ko/blog/package-skeleton-introduction.md)
- [Laravel Boost](/ko/boost.md)
- [Laravel Telescope](/ko/telescope.md)
- [Laravel Bluesky](/ko/packages/laravel-bluesky/index.md)