Laravel Pint

번역일: 2026년 6월 20일

Laravel Pint

소개
설치
Pint 실행
Pint 설정
지속적 통합(CI)
- GitHub Actions

소개

Laravel Pint는 미니멀리스트를 위한 PHP 코드 스타일 자동 교정 도구입니다. PHP CS Fixer를 기반으로 만들어졌으며, 별도의 복잡한 설정 없이도 코드 스타일을 일관되게 유지할 수 있도록 도와줍니다.

Pint는 새로 생성된 Laravel 애플리케이션에 기본으로 포함되어 있어 바로 사용할 수 있습니다. 기본 설정 파일 없이도 즉시 동작하며, Laravel이 권장하는 코딩 스타일을 기준으로 코드를 자동 교정합니다.

설치

Pint는 최신 Laravel 프레임워크에 이미 포함되어 있으므로 별도 설치가 필요하지 않습니다. 다만, 오래된 프로젝트에서는 Composer를 통해 직접 설치할 수 있습니다:

composer require laravel/pint --dev

Pint 실행

프로젝트의 vendor/bin 디렉터리에 있는 pint 실행 파일을 호출하면 코드 스타일 문제를 자동으로 교정할 수 있습니다:

./vendor/bin/pint

성능 향상을 위해 실험적인 병렬 모드로 실행하려면 --parallel 옵션을 사용하세요:

./vendor/bin/pint --parallel

병렬 모드에서는 --max-processes 옵션으로 최대 프로세스 수를 지정할 수도 있습니다. 이 옵션을 생략하면 Pint가 현재 머신의 모든 CPU 코어를 사용합니다:

./vendor/bin/pint --parallel --max-processes=4

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

./vendor/bin/pint app/Models./vendor/bin/pint app/Models/User.php

Pint는 교정한 파일 목록을 출력합니다. -v 옵션을 추가하면 변경 내용을 더 자세히 확인할 수 있습니다:

./vendor/bin/pint -v

실제 파일을 수정하지 않고 스타일 오류만 확인하고 싶다면 --test 옵션을 사용하세요. 스타일 오류가 발견되면 0이 아닌 종료 코드를 반환합니다:

./vendor/bin/pint --test

Git에서 특정 브랜치와 비교해 변경된 파일만 교정하려면 --diff=[branch] 옵션을 사용하세요. CI 환경에서 새로 추가되거나 수정된 파일만 검사할 때 유용합니다:

./vendor/bin/pint --diff=main

커밋되지 않은 변경 사항이 있는 파일만 교정하려면 --dirty 옵션을 사용하세요:

./vendor/bin/pint --dirty

스타일 오류를 교정하되, 교정이 발생한 경우 0이 아닌 종료 코드를 반환하게 하려면 --repair 옵션을 사용하세요:

./vendor/bin/pint --repair

Pint 설정

앞서 언급했듯이 Pint는 별도 설정 없이도 바로 사용할 수 있습니다. 하지만 프리셋, 규칙, 검사 대상 폴더를 직접 지정하고 싶다면 프로젝트 루트 디렉터리에 pint.json 파일을 생성하면 됩니다:

{
    "preset": "laravel"
}

특정 디렉터리에 있는 pint.json을 사용하고 싶다면 --config 옵션으로 경로를 지정할 수 있습니다:

./vendor/bin/pint --config vendor/my-company/coding-style/pint.json

프리셋

프리셋은 코드 스타일 교정에 사용할 규칙 묶음을 정의합니다. 기본값은 laravel 프리셋으로, Laravel 권장 코딩 스타일을 따릅니다. 다른 프리셋을 사용하려면 --preset 옵션으로 지정하세요:

./vendor/bin/pint --preset psr12

pint.json 파일에서도 프리셋을 설정할 수 있습니다:

{
    "preset": "psr12"
}

현재 Pint가 지원하는 프리셋은 laravel, per, psr12, symfony, empty입니다.

규칙

규칙은 코드 스타일을 어떻게 교정할지 정의하는 개별 기준입니다. 프리셋은 이러한 규칙들의 모음으로, 대부분의 PHP 프로젝트에 무리 없이 적용할 수 있도록 미리 구성되어 있습니다. 따라서 일반적으로는 규칙을 개별적으로 설정할 필요가 없습니다.

필요하다면 pint.json 파일에서 특정 규칙을 켜거나 끌 수 있으며, empty 프리셋을 사용해 규칙을 처음부터 직접 구성할 수도 있습니다:

{
    "preset": "laravel",
    "rules": {
        "simplified_null_return": true,
        "array_indentation": false,
        "new_with_parentheses": {
            "anonymous_class": true,
            "named_class": true
        }
    }
}

Pint는 PHP CS Fixer를 기반으로 하므로, PHP CS Fixer의 모든 규칙을 활용할 수 있습니다. 사용 가능한 규칙 목록은 PHP CS Fixer Configurator에서 확인하세요.

커스텀 규칙

PHP CS Fixer 규칙 외에도, Pint는 Pint/ 접두사가 붙은 자체 커스텀 규칙을 제공합니다. 이 규칙들은 기본적으로 비활성화되어 있으며, pint.json 파일에서 명시적으로 활성화해야 합니다.

`Pint/phpdoc_type_annotations_only`

이 규칙은 코드 내 모든 주석과 docblock 설명을 제거하고, @param, @return, @var, @phpstan-type 등 @ 어노테이션이 포함된 줄만 남깁니다:

/**

 * 사용자의 게시물을 가져옵니다.

*

 * @return HasMany<Post, $this>

*/

public function posts(): HasMany

@ 어노테이션이 없는 한 줄 주석 및 블록 주석은 완전히 제거됩니다. 특정 주석을 남기고 싶다면 @note, @warning, @todo 접두사를 붙이세요:

// @note 이 주석은 삭제되지 않고 유지됩니다.

이 규칙을 활성화하려면 pint.json 파일에 추가하세요:

{
    "preset": "laravel",
    "rules": {
        "Pint/phpdoc_type_annotations_only": true
    }
}

NOTE

이 규칙은 config 디렉터리에 있는 파일을 자동으로 건너뜁니다. 설정 파일은 일반적으로 주석을 문서화 용도로 사용하기 때문입니다.

파일 / 폴더 제외

기본적으로 Pint는 vendor 디렉터리를 제외한 프로젝트 내 모든 .php 파일을 검사합니다. 추가로 제외할 폴더가 있다면 exclude 옵션을 사용하세요:

{
    "exclude": [
        "my-specific/folder"
    ]
}

특정 이름 패턴과 일치하는 파일을 모두 제외하려면 notName 옵션을 사용하세요:

{
    "notName": [
        "*-my-file.php"
    ]
}

정확한 파일 경로를 지정해 제외하려면 notPath 옵션을 사용하세요:

{
    "notPath": [
        "path/to/excluded-file.php"
    ]
}

지속적 통합(CI)

GitHub Actions

Laravel Pint를 CI 파이프라인에 통합하면 코드가 푸시될 때마다 스타일을 자동으로 교정할 수 있습니다. GitHub Actions를 사용하는 경우, 먼저 GitHub 저장소의 Settings > Actions > General > Workflow permissions에서 워크플로우에 "Read and write permissions"를 부여해야 합니다. 그런 다음 아래 내용으로 .github/workflows/lint.yml 파일을 생성하세요:

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

이 워크플로우는 코드 푸시 시 Pint를 실행하고, 교정된 파일이 있으면 자동으로 커밋까지 처리합니다.