GitLab CI/CD × php-cs-fixerを利用してPHPコードを自動フォーマットする

# 概要

やろうと思ったきっかけとしてはこちら↓

https://qiita.com/g-iki/items/b81f70d6b183bf3f8540#comment-45d0f5fc2cb774f84a04

php-cs-fixerを利用してコードの自動成形を行いたいが、個々のIDE上でフォーマットを行ったつもりでもかかっていなかったり、独自の設定を行ってしまい、結局バラバラになってしまうこともありました。
設定が一定であるサーバ上でフォーマットをかけて、フォーマットがかかっていないコードのコミットだった場合CI側で自動でフォーマットをかけてコミットを行うことで確実にフォーマットがかかったような状態を目指します。
(git hookでフォーマットをかける方法もありますが、これも環境依存となってしまうため、GitLab CI/CDで行う方法を選択しました。)

## 前提

- ソースはphpを対象とします
    - php-cs-fixerを使用してphpコードのフォーマットを行います
        - 参考:[ソースコードの“赤ペン先生”PHP-CS-Fixerのインストールと設定](https://qiita.com/suin/items/4242aec018d086312fe7)
    - 他拡張子ファイルもコマンドライン実行可能であれば同じ手順で設定可能だと思います
- 差分が大変なことになってしまうので、ある一定のタイミング(プロジェクトが落ち着いているタイミング)で自動整形を行う前に一斉に成形を行うことをおすすめします。
- git flowで開発を行い、マージリクエスト時に自動フォーマットが動くことを想定しています
    - 私の運用している開発フローは[GitFlow + GitLab(GitHub)を活用した開発運用メモ
](https://qiita.com/g-iki/items/09342df443f011a165a7)を参照ください


## 詳細

### GitLab側の事前準備

当記事内ではGitLab Runnerの設定が完了している前提で記載しますが、設定していない場合は下記の手順を参考にRunnerの設定を行います。

https://qiita.com/g-iki/items/3ea1890fc58110bd6de5

設定 > リポジトリ から Deploy Keysの登録を行います。

![2022-12-22_12h56_54.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/127686/0d004be6-f181-af6d-2e51-d80393e4429d.png)

設定 > CI/CD からジョブで使用する変数を定義します。

![2022-12-22_13h00_01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/127686/cbc4dd28-c88c-78f2-7a37-802c133b2023.png)

### gitlab-ci.yml記述内容

scriptの箇所は下記の記事を参照させていただきました。

https://qiita.com/ynott/items/8cb3b3995cb41ca78437



ジョブの実行条件として**developブランチをターゲットとしてマージリクエストが発行されたとき**とします。

```yml
code_format:
  image: php:7.4-alpine
  tags:
    - docker-runner
  script:
    - apk --update add git openssh-client curl
    - eval $(ssh-agent -s)
    - printenv DEPLOY_SSH_PRIVATE_KEY | ssh-add -
    - git config --global user.name "codeFormatBot"
    - git config --global user.email "test@example.jp"
    - git remote set-url --push origin git@$CI_SERVER_HOST:$CI_PROJECT_PATH.git
    - git fetch
    - git checkout $CI_COMMIT_REF_NAME
    - git pull
    - curl -s https://getcomposer.org/installer | php
    - alias composer='php composer.phar'
    - composer require --dev friendsofphp/php-cs-fixer
    - ./vendor/bin/php-cs-fixer fix ./
    - git add -u
    - if [ -n $ret ];then
    -   git commit -m '[ci skip] CodeFormat, Push by GitLab runner'
    -   git -c core.sshCommand="ssh -oStrictHostKeyChecking=no" push origin
    - fi
  only:
    refs:
        - merge_requests
    variables:
        - $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "develop"
```

<details>
<summary>ちょっと解説</summary>


```yml
    - eval $(ssh-agent -s)
    - printenv DEPLOY_SSH_PRIVATE_KEY | ssh-add -
```

で ssh-agent の開始を行い、事前にGitLab設定画面から設定していたCI用の変数`DEPLOY_SSH_PRIVATE_KEY`からSSHプライベートキーをssh-agentに追加

```yml
    - git config --global user.name "codeFormatBot"
    - git config --global user.email "test@example.jp"
    - git remote set-url --push origin git@$CI_SERVER_HOST:$CI_PROJECT_PATH.git
```

でgitの設定

```yml
    - git fetch
    - git checkout $CI_COMMIT_REF_NAME
    - git pull
```

でコミットが行われたブランチのチェックアウト、プル

```yml
    - curl -s https://getcomposer.org/installer | php
    - alias composer='php composer.phar'
    - composer require --dev friendsofphp/php-cs-fixer
```

でcomposer自体のインストール

```yml
    - ./vendor/bin/php-cs-fixer fix ./src
    - git add -u
    - if [ -n $ret ];then
    -   git commit -m '[ci skip] CodeFormat, Push by GitLab runner'
    -   git -c core.sshCommand="ssh -oStrictHostKeyChecking=no" push origin
    - fi
```

で srcディレクトリを対象にphp-cs-fixerを実行し、変更があったものをgitステージング、
ステージング対象があれば`'[ci skip] CodeFormat, Push by GitLab runner'`というメッセージでコミット、プッシュを行う

:::note
コミットメッセージに`[ci skip]`のようなキーワードを含めることでジョブをスキップすることができます。

↓こちらの記事が参考になりました。
[CIサービスの自動ビルドをスキップする方法まとめ](https://qiita.com/vmmhypervisor/items/f10c77a375c2a663b300)
:::


```yml
  only:
    refs:
        - merge_requests
    variables:
        - $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "develop"
```

でdevelopブランチに対するマージリクエストが行われたとき(また、マージリクエスト後に同じブランチに対してコミットが行われたとき)という条件にしています。

</details>


### .php-cs-fixer.php 例

<details>
<summary>
設定例(長いので折りたたみ)
</summary>

:::note warn
下記の設定例は自分の関わった比較的古いプロジェクトを元に記載していますので、 
https://mlocati.github.io/php-cs-fixer-configurator
等でプロジェクトに合う設定を行ってください
:::

```php
<?php
/*
 * This document has been generated with
 * https://mlocati.github.io/php-cs-fixer-configurator/#version:2.15.5|configurator
 * you can change this configuration by importing this file.
 */
return PhpCsFixer\Config::create()
    ->setRules([
        'align_multiline_comment' => true,
        'array_indentation' => true,
        'array_syntax' => ['syntax'=>'short'],
        'backtick_to_shell_exec' => true,
        'binary_operator_spaces' => true,
        'blank_line_after_namespace' => true,
        'blank_line_after_opening_tag' => true,
        'blank_line_before_statement' => true,
        'braces' => true,
        'cast_spaces' => true,
        'class_attributes_separation' => true,
        'class_definition' => true,
        'combine_consecutive_issets' => true,
        'combine_consecutive_unsets' => true,
        'compact_nullable_typehint' => true,
        'concat_space' => true,
        'declare_equal_normalize' => true,
        'elseif' => true,
        'encoding' => true,
        'escape_implicit_backslashes' => true,
        'explicit_string_variable' => true,
        'full_opening_tag' => true,
        'fully_qualified_strict_types' => true,
        'function_declaration' => true,
        'function_typehint_space' => true,
        'heredoc_to_nowdoc' => true,
        'include' => true,
        'indentation_type' => true,
        'line_ending' => true,
        'linebreak_after_opening_tag' => true,
        'lowercase_cast' => true,
        'lowercase_constants' => true,
        'lowercase_keywords' => true,
        'lowercase_static_reference' => true,
        'magic_constant_casing' => true,
        'magic_method_casing' => true,
        'method_argument_space' => true,
        'method_chaining_indentation' => true,
        'multiline_comment_opening_closing' => true,
        'multiline_whitespace_before_semicolons' => true,
        'native_function_casing' => true,
        'native_function_type_declaration_casing' => true,
        'new_with_braces' => true,
        'no_alternative_syntax' => true,
        'no_binary_string' => true,
        'no_blank_lines_after_class_opening' => true,
        'no_blank_lines_after_phpdoc' => true,
        'no_break_comment' => true,
        'no_closing_tag' => true,
        'no_empty_comment' => true,
        'no_empty_phpdoc' => true,
        'no_empty_statement' => true,
        'no_extra_blank_lines' => true,
        'no_leading_import_slash' => true,
        'no_leading_namespace_whitespace' => true,
        'no_mixed_echo_print' => true,
        'no_multiline_whitespace_around_double_arrow' => true,
        'no_null_property_initialization' => true,
        'no_short_bool_cast' => true,
        'no_singleline_whitespace_before_semicolons' => true,
        'no_spaces_after_function_name' => true,
        'no_spaces_around_offset' => true,
        'no_spaces_inside_parenthesis' => true,
        'no_superfluous_elseif' => true,
        'no_trailing_comma_in_list_call' => true,
        'no_trailing_comma_in_singleline_array' => true,
        'no_trailing_whitespace' => true,
        'no_trailing_whitespace_in_comment' => true,
        'no_unneeded_control_parentheses' => true,
        'no_unneeded_curly_braces' => true,
        'no_unneeded_final_method' => true,
        'no_unset_cast' => true,
        'no_unused_imports' => true,
        'no_useless_else' => true,
        'no_useless_return' => true,
        'no_whitespace_before_comma_in_array' => true,
        'no_whitespace_in_blank_line' => true,
        'normalize_index_brace' => true,
        'object_operator_without_whitespace' => true,
        'ordered_class_elements' => true,
        'ordered_imports' => true,
        'php_unit_fqcn_annotation' => true,
        'phpdoc_add_missing_param_annotation' => true,
        'phpdoc_align' => true,
        'phpdoc_annotation_without_dot' => true,
        'phpdoc_indent' => true,
        'phpdoc_inline_tag' => true,
        'phpdoc_no_access' => true,
        'phpdoc_no_empty_return' => true,
        'phpdoc_no_package' => true,
        'phpdoc_order' => true,
        'phpdoc_return_self_reference' => true,
        'phpdoc_scalar' => true,
        'phpdoc_separation' => true,
        'phpdoc_single_line_var_spacing' => true,
        'phpdoc_summary' => true,
        'phpdoc_to_comment' => true,
        'phpdoc_trim' => true,
        'phpdoc_trim_consecutive_blank_line_separation' => true,
        'phpdoc_types' => true,
        'phpdoc_types_order' => true,
        'phpdoc_var_annotation_correct_order' => true,
        'phpdoc_var_without_name' => true,
        'return_type_declaration' => true,
        'semicolon_after_instruction' => true,
        'short_scalar_cast' => true,
        'simplified_null_return' => true,
        'single_blank_line_at_eof' => true,
        'single_blank_line_before_namespace' => true,
        'single_class_element_per_statement' => true,
        'single_import_per_statement' => true,
        'single_line_after_imports' => true,
        'single_line_comment_style' => true,
        'single_quote' => true,
        'space_after_semicolon' => true,
        'standardize_not_equals' => true,
        'switch_case_semicolon_to_colon' => true,
        'switch_case_space' => true,
        'ternary_operator_spaces' => true,
        'trailing_comma_in_multiline_array' => true,
        'trim_array_spaces' => true,
        'unary_operator_spaces' => true,
        'whitespace_after_comma_in_array' => true,
    ])
    ->setFinder(PhpCsFixer\Finder::create()
        ->exclude('vendor')
        ->in(__DIR__)
    )
;
```

:::note
最後に`->exclude('vendor')`としているのはVSCodeを使用したリモート開発を想定した設定で、(自分の場合はVSCode上でファイルの保存を行うときにフォーマットをかけるようにしていますが、)コマンドラインからphp-CS-fixerをディレクトリに対して実行したときcomposerで落としてきているソースまでフォーマットをかけてしまうためexcludeとしています。
(実際にはgitignoreでvendor配下のソースは管理しないようにしていると思いますが、無駄に時間がかかってしまうので排除しています。)
:::

</details>


### 実行時のGitLab側の画面

マージリクエスト > パイプライン画面からどのようにジョブが動いているか確認できます。
(一時的にCIによるコミットログが発生しますが、squashオプションを付けてマージを完了させることでログからは見えない状態となります。)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/127686/7489fdb7-faef-c8a6-307c-ebdbcad6922d.png)

# 終わりに

まだしっかりとした運用にすることはできていませんが、自動化することでphp-cs-fixerでできる範囲↓

- インデントがずれている
- インデントにスペースとタブが入り乱れている
- シングルクォーテーションとダブルクオーテーションが入り乱れている
- etc...

のようなコードを読むのに集中力の切れてしまう要因を少なくすることができるようになったのではないかと思います。

また、他の拡張子のファイルについても同じく自動フォーマットが行えるツールを探して適用していこうと思います。