composerをもっと知ろう（４）ローカルのパッケージをLaravelで使う

皆さんは、DGFTのベリトランスの支払決済のPHPのSDKキットを使用したことありますか？ それを利用するには彼らのウェブサイトからファイルをダウンロードして、プロジェクトに置いてそれをパッケージとしてインストールします。今回はその仕組みの説明です。ローカルにパッケージを作成してそれをcomposer requireします。

自分のパッケージを作成

まず、デモとしてあるヘルパー関数の定義を含むパッケージを作成します。このパッケージには１つのヘルパー関数しかなく、インストールしたら以下のように、全角の英数字文字列を半角に変換する関数、to_hankaku()を使うことができます。

Psy Shell v0.12.7 (PHP 8.2.15 — cli) by Justin Hileman
> to_hankaku('１２３');
= "123"

便利そうでしょう。

まず、Laravelのプロジェクトを新規作成して、プロジェクトのディレクトリ直下にpackagesのディレクトリを作成して、以下のような構造で必要なファイルを作成します。

├── app
...

packages
└── larajapan
    └── japanese-utils
        ├── composer.json
        └── src
            └── helpers.php
...

上では、composer.jsonとhelpers.phpのみがファイルで他は皆ディレクトリです。larajapanが開発者のアイデンティティでその下のjapanese-utilsが今回のパッケージ名となります。

まずそのパッケージのcomposer.jsonの中身を見てみましょう（混乱していけないのは、このcomposer.jsonはjapanese-utilsのパッケージのcomposer.jsonであり、これからそれをインストールしようというLaravelのプロジェクト、つまりルートパッケージのcomposer.jsonではありません）。

{
    "name": "larajapan/japanese-utils",
    "description": "helpers to manipuliate a japanese string",
    "version": "1.0.0",
    "require": {
        "php": ">=7.4",
        "ext-mbstring": "*"
    },
    "autoload": {
        "files": [
            "src/helpers.php"
        ]
    }
}

ここでは、パッケージ名（name）、説明（description）、バージョン（version）、必須条件（require）、ロードの指示（autoload）が含まれます。to_hanakaku()の関数では、mbstringのPHPのモジュールのmb_convert()を使用し、さらにタイプヒントも使用するので、それを対応しているPHPバージョン7.4以上であることをインストールの前提とします.

今度は、その関数を定義するhelpers.phpを見てみましょう。

if (!function_exists('to_hankaku')) {
    function to_hankaku(string $zenkaku): string
    {
        return mb_convert_kana($zenkaku, 'as'); // 全角英数字と空白を半角に変換
    }
}

とても簡単な定義ですが、他のパッケージですでに定義されていたら困るので、!function_exists('to_hankaku')の条件を入れています。

Laravelのプロジェクトにインストール

同じプロジェクトのディレクトリ内にパッケージを作成したものの、これだけではプロジェクトで先ほどのto_hanakaku()は使えません。プロジェクトにインストールすることが必要です。

今度は作成したパッケージのではなくプロジェクト（ルートパッケージ）のcomposer.jsonの編集が必要です。以下のrepositoriesのブロックが追加した部分です。

{
    "$schema": "https://getcomposer.org/schema.json",
    "name": "laravel/laravel",
    "type": "project",
    "description": "The skeleton application for the Laravel framework.",
    "keywords": ["laravel", "framework"],
    "license": "MIT",
    "repositories": [
        {
            "type": "path",
            "url": "./packages/larajapan/japanese-utils",
            "options": {
                "symlink": true
            }
        }
    ],
    "require": {
        "php": "^8.2",
        "laravel/framework": "^11.31",
        "laravel/tinker": "^2.9"
    },
...
}

“type”: “path”がローカルのパッケージがレポジトリということを指示し、その場所 “url”にパッケージの相対の場所を指定します。そして、“options”として、“symlink”: trueは、プロジェクトにおいて使用されるパッケージを収めるvendorのディレクトリにおいて、作成したパッケージへのsymlinkを張るという指示です。ちなみにfalseならファイルのコピーとなります。

これでインストールの準備は完了です。通常のパッケージのインストールのようにcomposre requireを実行しましょう。

$ composer require larajapan/japanese-utils

インストール後には、composer.jsonは更新され、“larajapan/japanese-utils”: “^1.0”,のエントリーが追加されているのがわかります。

{
...
    "require": {
        "php": "^8.2",
        "larajapan/japanese-utils": "^1.0",
        "laravel/framework": "^11.31",
        "laravel/tinker": "^2.9"
    },
...
}

vendorのディレクトリを見ると、以下のようにパッケージへのsymlinkとなっています。

$ ls -l vendor/larajapan
total 0
lrwxrwxrwx 1 kenji kenji 40 Feb 19 16:42 japanese-utils -> ../../packages/larajapan/japanese-utils/

これで、このLaravelのプロジェクト内で、to_hankaku()のヘルパーをどこでも使えるようになります。

最後に

自分が作成したパッケージは、Packagistに登録したものでもなく、githubのレポジトリに置いたプライベートのパッケージでもありません。そのようなパッケージが必要となるのは不思議と思われるかもしれません。しかし、以下のようにいくつか必要となるケースがあります。

• 将来はPackagistにおいて自分で開発したパッケージを共有したいが、完成度が低いので暫くは自分のプロジェクトだけ使う
• 今まで使用していたgithubにあるパッケージはもうメンテインされていなくダウンロードして自分のプロジェクトだけで使えるようにする
• プロジェクトが肥大化したのでパッケージとしてモジュール化して使う
• あえて自社のサービスのSDKキットをPackagistでパブリックで共有することをせずに、サービスを利用する開発者にローカルにダウンロードしてからcomposerでインストールしてもらう。日本で有名なDGFTのベリトランスの決済のPHPのSDKキットはまさにそれです。