構成

本章ではcomposer.jsonのスキーマのconfig節について記述していきます。

process-timeout

プロセス実行の制限時間で、秒単位です。既定では300（5分）です。 git cloneのような時間の掛かるプロセスは、Composerによりプロセスの異常終了が推定されるまで、実行できます。接続が遅い場合やベンダーが大きい場合は、これを増やす必要があるかもしれません。

例：

{
    "config": {
        "process-timeout": 900
    }
}

個々のスクリプトのコマンドで制限時間を無効にする

scripts以下の独自コマンドでプロセスの制限時間を無効にするには、静的ヘルパーが使えます。

{
    "scripts": {
        "test": [
            "Composer\\Config::disableProcessTimeout",
            "phpunit"
        ]
    }
}

allow-plugins

既定は{}で、1つもプラグインを読み込むことはできません。

Composer 2.2.0では、allow-pluginsオプションによってセキュリティの層が追加され、Composerの実行中にどのComposerプラグインがコードを実行できるかを制限できるようになりました。

新しいプラグインが最初に活性化され、それが構成オプションにまだ挙げられていなければ、Composerは警告を印字します。 Composerを対話的に実行すると、プラグインを実行するかどうかを決めるようプロンプトを出します。

この設定を使うと、信頼できるパッケージのみがコードを実行できるようになります。パッケージ名パターンをキーに持つオブジェクトに設定します。値は、許可する場合はtrueで、許可しない場合はfalseです。何れもこれ以外の警告とプロンプトは抑制されます。

{
    "config": {
        "allow-plugins": {
            "third-party/required-plugin": true,
            "my-organization/*": true,
            "unnecessary/plugin": false
        }
    }
}

構成オプション自体をfalseにして全てのプラグインを拒否したり、trueにして全てのプロラグインが走るのを許可したり（全くお勧めしません）するようにも設定できます。例えば以下の通りです。

{
    "config": {
        "allow-plugins": false
    }
}

use-include-path

既定ではfalseです。 trueにすると、Composerの自動読み込み器はPHPのインクルードパスにあるクラスも探します。

preferred-install

既定ではdistで、source、dist、autoの何れかです。このオプションではComposerが優先して使うインストール方法を設定できます。お好みで、より柔軟なインストール設定のためにキーにパッケージ名のパターンがあるオブジェクトにすることもできます。

{
    "config": {
        "preferred-install": {
            "my-organization/stable-package": "dist",
            "my-organization/*": "source",
            "partner-organization/*": "auto",
            "*": "dist"
        }
    }
}

sourceは、Composerが（存在する場合）sourceからパッケージをインストールすることを意味します。通常、git cloneまたは同等のパッケージが使用するバージョン管理システムのチェックアウトです。プロジェクトにバグ修正を行い、依存関係のローカルgitクローンを直接取得する場合に便利です。
autoは遺物的な動作です。開発バージョンの場合にComposerはsourceを自動的に使用し、それ以外の場合はdistを使用します。
dist（Composer 2.1以降で既定）は、可能であればComposerがdistからインストールすることを意味します。通常、zipファイルのダウンロードであり、リポジトリ全体のクローンよりも高速です。

補足： 順番は重要です。より限定されたパターンは、より緩いパターンの前に来るべきです。大域構成やパッケージ構成で文字列表記とハッシュ構成を混在させると、文字列表記は*パッケージパターンに解釈されます。

セキュリティの監査とバージョンの遮断の構成オプションです。監査の報告はcomposer auditで生成でき、短い形式のものは自動でupdateないしrequireコマンドの末尾で報告されます。バージョンの遮断では、安全でなかったり放棄されたりしているものと確認されたパッケージのバージョンを、構成に応じて、依存関係を解決する前に無視します。これにより、そうしたパッケージがインストールされないようにします。

ignore

勧告の識別子、リモートの識別子、CVEの識別子、パッケージ名（非推奨）のリストです。これらは監査の報告やバージョンの遮断からは無視されます。

理由付きの単純な形式：

{
    "config": {
        "audit": {
            "ignore": {
                "CVE-1234": "The affected component is not in use.",
                "GHSA-xx": "The security fix was applied as a patch.",
                "PKSA-yy": "Due to mitigations in place the update can be delayed."
            }
        }
    }
}

理由のない単純な形式：

{
    "config": {
        "audit": {
            "ignore": ["CVE-1234", "GHSA-xx", "PKSA-yy"]
        }
    }
}

適用範囲付きの詳細な形式：

詳細な形式では、無視するための構成が、監査の報告だけか、バージョンの遮断のみか、あるいはその両方かを制御できるようにします。 applyフィールドは

audit - 監査の報告だけ無視します（勧告は監査の報告に現れませんが、パッケージは更新するときに遮断されます）
block - バージョンの遮断のみ無視します（パッケージは更新中のみ使えますが、勧告は監査の報告に現れます）
all - 監査の報告とバージョンの遮断のときに無視されます（既定の動作）

{
    "config": {
        "audit": {
            "ignore": {
                "CVE-1234": {
                    "apply": "audit",
                    "reason": "Not applicable to us, so don't report, but still want to make sure we don't use this version in updates."
                },
                "GHSA-xx": {
                    "apply": "block",
                    "reason": "Workaround applied, can only fix next week, allow during updates but still report in audits"
                },
                "PKSA-yy": {
                    "apply": "all",
                    "reason": "False report, Ignore completely in all contexts"
                }
            }
        }
    }
}

これら全ての形式は同じ構成に混ぜて使えます。

abandoned

Composer 2.7以降、既定でfailです（このオプションが追加されたComposer 2.6では既定でreportでした）。監査コマンドが放棄されたパッケージを報告するかどうかを定義するもので、3つの値を取り得ます。

ignoreでは、監査の報告で放棄されたパッケージを全く考慮しません。
reportでは、放棄されたパッケージが失敗として報告されるものの、composerの監査コマンドは非ゼロコードで終了しません。
failでは、放棄されたパッケージにより監査コマンドが非ゼロコードで失敗します。

なお、これは監査の報告にのみ適用されます。この設定は安全でないパッケージの阻止には効果がありません。放棄されたパッケージの阻止を構成するには、block-abandonedオプションを参照。

{
    "config": {
        "audit": {
            "abandoned": "report"
        }
    }
}

Composer 2.7以降、COMPOSER_AUDIT_ABANDONED環境変数を介して、オプションをオーバーライドできます。

Composer 2.8以降、--abandonedコマンドラインオプションを介して、オプションをオーバーライドできます。このオプションにより、構成値と環境変数が共にオーバーライドされます。

ignore-abandoned

放棄されたパッケージ名のリストで、監査の報告やバージョンの遮断で無視されます。放棄された状態であっても使い続けたいパッケージを選ぶことができます。

理由付きの単純な形式：

{
    "config": {
        "audit": {
            "ignore-abandoned": {
                "acme/*": "Work scheduled for removal next month.",
                "acme/package": "Transitive dependency but unreachable and not in active use within our project context."
            }
        }
    }
}

理由のない単純な形式：

{
    "config": {
        "audit": {
            "ignore-abandoned": ["acme/*", "acme/package"]
        }
    }
}

適用範囲付きの詳細な形式：

詳細な形式では、無視する設定が、監査の報告のみか、バージョンの遮断のみか、あるいはその両方に適用されるかを制御できます。 applyフィールドは以下を受け付けます。

audit - 監査の報告のみ無視します

（パッケージは監査の報告に現れませんが、block-abandonedが有効のときは更新のときに遮断されます）

block - バージョンの遮断のみ無視します（block-abandonedが有効でもパッケージは更新のときに使えます。ただし監査の報告には現れます）
all - 監査の報告とバージョンの遮断を無視します（既定の動作）

{
    "config": {
        "audit": {
            "ignore-abandoned": {
                "acme/package": {
                    "apply": "block",
                    "reason": "Allow during updates but still report as abandoned"
                },
                "vendor/*": {
                    "apply": "all",
                    "reason": "We maintain these packages internally"
                }
            }
        }
    }
}

これら全ての形式は同じ構成に混ぜて使えます。

ignore-severity

既定は[]です。監査の報告やバージョンの遮断で無視されるセキュリティ水準のリストです。

単純な形式：

{
    "config": {
        "audit": {
            "ignore-severity": ["low", "medium"]
        }
    }
}

適用範囲付きの詳細な形式：

詳細な形式では、無視する構成が、監査の報告のみか、バージョンの遮断のみか、あるいはその両方に適用されるかを制御できます。 applyフィールドは以下を受け付けます。

audit - 監査の報告のみ無視します（この厳密さの勧告は監査の報告に現れませんが、パッケージは更新のとき遮断されます）
block - バージョンの遮断のみ無視します（パッケージは更新のときは使えますが、この厳密さの勧告は監査の報告で現れます）
all - 監査と遮断の両方で無視されます（既定の動作）

{
    "config": {
        "audit": {
            "ignore-severity": {
                "low": {
                    "apply": "all"
                },
                "medium": {
                    "apply": "block"
                }
            }
        }
    }
}

これら全ての形式は同じ構成に混ぜて使えます。

ignore-unreachable

既定でfalseです。到達できないリポジトリはcomposer auditのときに無視されます。全てのリポジトリはアクセスできない環境でコマンドを実行するときに役立つことがあります。この設定はcomposer auditコマンド以外のところで生成されたバージョンの遮断や監査の報告には適用されません。

{
    "config": {
        "audit": {
            "ignore-unreachable": true
        }
    }
}

block-insecure

既定でtrueです。 trueのとき、セキュリティ勧告が無視されていなければ、セキュリティ勧告の影響を受けるパッケージのバージョンは遮断され、composer update/require/deleteコマンドで使えません。 block-abandonedが有効であれば、バージョンの遮断では、放棄されたパッケージの使用も防ぎます。

{
    "config": {
        "audit": {
            "block-insecure": false
        }
    }
}

block-abandoned

既定でfalseです。 trueのとき、放棄されたパッケージはcomposerのupdate/required/deleteコマンドで使えません。 block-insecureが偽に設定されてバージョンの遮断が無効になっていないときにのみ適用されます。

{
    "config": {
        "audit": {
            "block-abandoned": true
        }
    }
}

use-parent-dir

composer.jsonがないディレクトリでComposerを実行しており、その上のディレクトリにcomposer.jsonがある場合、Composerは既定で、そのディレクトリのcomposer.jsonを代わりに使用するかどうかを尋ねます。

このプロンプトに対して常に「はい」と答えたい場合は、この構成値をtrueに設定できます。プロンプトが表示されないようにするには、falseに設定します。既定は"prompt"です。

補足： この構成を機能させるには、大域的な利用者全体の構成で設定しなければなりません。例えばphp composer.phar config --global use-parent-dir trueを使用して設定します。

store-auths

認証のプロンプトの後にする動作です。 true（常に保存する）、false（保存しない）、"prompt"（毎回確認する）の何れか1つで、既定では"prompt"です。

github-protocols

既定では["https", "ssh", "git"]です。 github.comからクローンを作成するときに使用するプロトコルのリストで、優先度順に並べます。既定ではgitが存在しますが、gitプロトコルは暗号化されていないため、secure-httpが無効になっている場合のみ使われます。 originのリモートプッシュURLでssh (git@github.com:...) ではなくhttpsを使用する場合、プロトコルリストを["https"]のみに設定すると、ComposerはプッシュURLをSSHのURLに上書きすることを取り止めます。

github-oauth

ドメイン名とoauthキーのリストです。たとえば、このオプションの値として{"github.com": "oauthtoken"}を使用すると、oauthtokenを使用してgithubの私有リポジトリにアクセスし、APIのIPに基づく低いレート制限を回避します。 Composerは、必要に応じて資格情報を要求する場合がありますが、これらは手動で設定することもできます。 GitHubのOAuthトークンを取得する方法及びcliの構文の詳細については、こちらを参照してください。

gitlab-domains

既定では["gitlab.com"]です。 GitLabサーバーのドメインのリストです。 gitlabリポジトリ種別を使う場合に使用されます。

gitlab-oauth

ドメイン名とoauthキーのリストです。たとえば、このオプションの値として{"gitlab.com": "oauthtoken"}を使用すると、oauthtokenを使用してgitlabの私有リポジトリにアクセスします。なお、パッケージがgitlab.comでホストされていない場合、ドメイン名もgitlab-domainsオプションで指定する必要があります。詳細情報はこちらにもあります。

gitlab-token

ドメイン名と私有トークンのリストです。私有トークンは、単純な文字列、または利用者名とトークンを含む配列の何れかです。たとえば、このオプションの値として{"gitlab.com": "privatetoken"}を使用すると、privatetokenを使用してgitlabの私有リポジトリにアクセスします。 {"gitlab.com": {"username": "gitlabuser", "token": "privatetoken"}}を使用すると、利用者名とトークンの両方を使ってgitlabのデプロイトークン機能 (https://docs.gitlab.com/ ee/user/project/deploy_tokens/) を使用します。なお、パッケージがgitlab.comでホストされていない場合、ドメイン名もgitlab-domainsオプションで指定する必要があります。トークンにはapiまたはread_apiスコープが必要です。詳細情報はこちらにもあります。

gitlab-protocol

パッケージメタデータのsource値用にリポジトリのURLを作成するときに、強制的に使用するプロトコルです。 gitまたはhttpの何れかです（httpsはhttpの同義語として扱われます）。 HTTPベーシック認証を使ったGitLabのCI_JOB_TOKENにより、後々GitLab CIのジョブでクローンされる私有リポジトリを参照するプロジェクトを扱う際に役立ちます。既定では、Composerは私有リポジトリについてはgit-over-SSHのURLを生成し、公開リポジトリについてはHTTP(S)のみを生成します。

forgejo-domains

既定では["codeberg.org"]です。 Forgejoサーバーのドメインのリストです。 forgejoリポジトリ種別を使う場合に使用されます。

forgejo-token

ドメイン名とそのドメインで認証するためのユーザー名／アクセストークンのリストです。たとえば、このオプションの値として{"codeberg.org": {"username": "forgejo-user", "token": "access-token"}}を使うと、codeberg.orgに対して認証します。なお、パッケージがcodeberg.orgのドメイン名でホストされていない場合、ドメイン名もforgejo-domainsオプションで指定する必要があります。詳細情報はこちらにもあります。

disable-tls

既定はfalseです。真に設定すると、すべてのHTTPSのURLが代わりにHTTPで試行され、ネットワークレベルの暗号化は実行されません。これを有効にすることはセキュリティ上の危険性であり、全く推奨されません。より良い方法は、php.iniでphp_openssl拡張機能を有効にすることです。これを有効にすると、secure-httpオプションが暗黙に無効になります。

secure-http

既定ではtrueです。真に設定すると、HTTPSのURLのみがComposer経由でダウンロードできるようになります。何かしらへのHTTPアクセスが絶対に必要な場合は無効にできますが、Let’s Encryptを使用して無料のSSL証明書を取得する方が一般的にはより良い代替手段です。

bitbucket-oauth

ドメイン名と消費者のリストです。例えば{"bitbucket.org": {"consumer-key": "myKey", "consumer-secret": "mySecret"}}のように使います。より詳しくはこちらを読んでください。

cafile

ローカルファイルシステム上の認証局ファイルの配置場所です。 PHP 5.6以降ではシステムCAファイルを自動的に検出できますが、PHP 5.6以降でも、php.iniのopenssl.cafileを介してこれを設定すべきです。

capath

cafileが指定されていない場合、またはそこに証明書がない場合は、capathが指すディレクトリで適切な証明書が探索されます。 capathは正しくハッシュされた証明書ディレクトリでなければなりません。

http-basic

認証するためのドメイン名と、利用者名とパスワードのリストです。たとえば、このオプションの値として{"example.org": {"username": "alice", "password": "foo"}}を使用すると、Composerはexample.orgに対して認証します。詳細については、こちらを参照してください。

bearer

認証するドメイン名とトークンのリストです。たとえば、このオプションの値として{"example.org": "foo"}を使用すると、ComposerはAuthorization: Bearer fooヘッダーを使用して、example.orgに対して認証を行うことができます。

platform

プラットフォームパッケージ（PHP及び拡張機能）を偽装して、運用環境をエミュレートしたり、構成で対象のプラットフォームを定義したりできるようにします。例えば{"php": "7.0.3", "ext-something": "4.0.3"}です。

これにより、ローカルで実行する実際のPHPバージョンに関係なく、PHP 7.0.3以上を必要とするパッケージをインストールできなくなります。ただし、依存関係が正しく検査されなくなったことも意味します。 PHP 5.6を実行すると、7.0.3を想定しているため問題なくインストールされますが、実行時に失敗します。これは、{"php":"7.4"}が指定されることも意味します。 7.4.1を最小のバージョンとして定義するパッケージは使用されません。

したがって、これを使用する場合は、デプロイ戦略の一部としてcheck-platform-reqsコマンドも走らせることをお勧めしますし、より安全です。

ローカルにインストールしていない拡張機能が依存関係に必要な場合は、代わりに--ignore-platform-req=ext-fooをupdate、install、またはrequireに渡して無視できます。しかし長い目で見れば、今は無視するにせよ必要な拡張はインストールすべきで、1箇月後に新しいパッケージでも必要になると、知らず知らずのうちに本番環境に問題が発生する可能性があります。

拡張をローカルにインストールしているが本番環境ではそうではない場合、{"ext-foo": false}を使ってComposerから意図的に隠すこともできます。

vendor-dir

既定はvendorです。お好みで違うディレクトリに依存関係をインストールできます。 vendor-dirと以下の全ての*-dirオプション中では、$HOMEと~はホームディレクトリに置換されます。

bin-dir

既定ではvendor/binです。プロジェクトがバイナリを含む場合、それらのバイナリはこのディレクトリにシンボリックリンクが張られます。

data-dir

既定では、WindowsではC:\Users\<user>\AppData\Roaming\Composer、XDG Base Directory Specificationsに従うunixシステムでは$XDG_DATA_HOME/composer、その他のunixシステムでは$COMPOSER_HOMEです。現在、過去のcomposer.pharファイルを保存して古いバージョンにロールバックできるようにするためにのみ使用されています。 COMPOSER_HOMEも参照してください。

cache-dir

既定では、WindowsではC:\Users\<user>\AppData\Local\Composer、macOSでは/Users/<user>/Library/Caches/composer、XDG Base Directory Specificationに従うunixシステムでは$XDG_CACHE_HOME/composer、他のunixシステムでは$COMPOSER_HOME/cacheになります。 Composerで使う全てのキャッシュが保管されます。 COMPOSER_HOMEも参照してください。

cache-files-dir

既定では$cache-dir/filesです。パッケージのzipアーカイブを保管します。

cache-repo-dir

既定では$cache-dir/repoです。 composerの種別用のリポジトリのメタデータと、svn、fossil、github、gitbucketの種別のVCSリポジトリを保管します。

cache-vcs-dir

既定では$cache-dir/vcsです。 git及びhgの種別用のVCSリポジトリメタデータを読み込むためのVCSクローンを保管し、インストールを高速にします。

cache-files-ttl

既定では15552000（6箇月）です。 Composerはダウンロードした全てのdist（zip、tar、……）をキャッシュします。既定では使われていないものについて6箇月経った後に削除します。このオプションはこの期間を（秒数で）調整ないし0に設定することで、完全に無効にできるようにするものです。

cache-files-maxsize

既定では300MiBです。 Composerはダウンロードした全ての配布パッケージ（zip、tar、……）をキャッシュします。ガベージコレクションが定期的に走っている場合、キャッシュで使える最大量です。最後のキャッシュヒットから時間が経った（比較的使われていない）ファイルが削除されます。

cache-read-only

既定ではfalseです。 Composerのキャッシュを読取専用モードで使うかどうかを決めます。

bin-compat

既定ではautoです。インストールするバイナリの互換性を決定します。 autoの場合、Composerは、WindowsまたはWSLの場合に.batプロキシファイルのみをインストールします。 fullに設定すると、Windows用の.batファイルとUnixベースのオペレーティングシステム用のスクリプトの両方がバイナリごとにインストールされます。主にLinux VM内でComposerを実行しているが、WindowsホストOSで使用できる.batプロキシが必要な場合に役立ちます。 proxyに設定すると、ComposerはbashでUnixスタイルのプロキシファイルのみを作成し、WindowsないしWSLでも.batファイルを作成しません。

prepend-autoloader

既定はtrueです。 falseにするとComposerの自動読み込み器は既存の自動読み込み器の前に置かれなくなります。他の自動読み込み器との相互運用性の問題を修正する際に必要になることがあります。

autoloader-suffix

既定ではnullです。空でない文字列に設定した場合、生成されたComposerの自動読み込み器の接尾辞に使われます。 nullに設定された場合、可能であればcomposer.lockファイルのcontent-hash値が使われます。そうでなければ、乱択された接尾辞が生成されます。

optimize-autoloader

既定ではfalseです。 trueの場合、自動読み込み器を吐き出す際に常に最適化されます。

sort-packages

既定ではfalseです。 trueの場合、新しいパッケージを追加したときにcomposer.json中のrequireコマンドでパッケージが名前順に整列された状態に保たれます。

classmap-authoritative

既定ではfalseです。 trueにするとComposerの自動読み込み器はクラスマップからのクラスのみを読み込みます。暗にoptimize-autoloaderを有効にします。

apcu-autoloader

既定ではfalseです。 trueの場合、Composerの自動読み込み器はAPCuを確認し、拡張が有効になった場合にクラスの有無をキャッシュするのに使います。

github-domains

既定では["github.com"]です。 githubモードで使われるドメインのリストです。 GitHub Enterpriseの準備で使われます。

github-expose-hostname

既定ではtrueです。 falseにするとgithub APIにアクセスするために作られるOAuthトークンがマシンのホスト名ではなく日付になります。

use-github-api

既定ではtrueです。特定のリポジトリに於けるno-apiキーに似ており、use-github-apiをfalseに設定すると、他のgitリポジトリのように、全てのGitHubリポジトリについて、GitHub APIを使う代わりにリポジトリをクローンするように大域的な挙動を定義します。しかしgitドライバを直接使うのではなく、ComposerはやはりGitHubのzipファイルを使うことを試みます。

notify-on-install

既定ではtrueです。 Composerではリポジトリが通知のURLを定義できるようにしており、そのリポジトリからパッケージがインストールされたことの通知を受けられます。このオプションはその挙動を無効にできます。

discard-changes

既定ではfalseで、true、false、またはstashの何れかにできます。このオプションでは非対話モードでダーティアップデートを制御する既定の方式を設定できます。 trueはベンダーの変更を常に破棄しますが、"stash"は取っておいて再適用しようとします。よくベンダーを変更する場合は、CIサーバーやデプロイスクリプトにこれを使ってください。

archive-format

既定ではtarです。 archiveコマンドにより使われる既定の形式を上書きします。

archive-dir

既定では.です。 archiveコマンドによる作られる、アーカイブの既定の対象パスです。

例：

{
    "config": {
        "archive-dir": "/home/user/.composer/repo"
    }
}

Keyboard shortcuts

Composer