Laravel Pint

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

​

Laravel Pint란

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

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

​

설치

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

composer require laravel/pint --dev

​

실행 방법

​

기본 사용법

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

./vendor/bin/pint

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

./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	사용할 프리셋을 지정한다

# 파일을 변경하지 않고 체크만
./vendor/bin/pint --test

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

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

​

설정

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

{
    "preset": "laravel"
}

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

./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	규칙 없음. 개별적으로 규칙을 정의해서 사용

# 커맨드라인에서 프리셋 지정
./vendor/bin/pint --preset psr12

​

규칙 커스터마이징

pint.json에서 규칙을 개별적으로 활성화/비활성화할 수 있습니다. 사용 가능한 규칙은 PHP CS Fixer Configurator를 참조해 주세요.

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

​

파일·폴더 제외

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

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

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

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

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

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

​

권장 설정

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

{
    "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);를 자동 추가하여 타입 안전성을 높인다

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

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

​

composer.json에 scripts 설정

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

{
    "scripts": {
        "pint": "./vendor/bin/pint",
        "pint:test": "./vendor/bin/pint --test"
    }
}

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

# 코드를 자동 수정
composer pint

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

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

​

GitHub Actions에서 자동 실행

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

1. Workflow의 권한을 설정한다

   GitHub 리포지토리의 Settings > Actions > General > Workflow permissions에서 “Read and write permissions”를 활성화합니다.

2. Workflow 파일을 생성한다

   .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를 실행하고, 스타일 위반을 수정한 파일을 자동으로 커밋합니다.

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