Drupalのモジュール開発Tips

:::note info
この記事は[『Code Polaris Advent Calendar 2024』](https://qiita.com/advent-calendar/2024/code-polaris) の4日目の記事です。
:::

こんばんは、Kyonです。

数年ぶりに、業務でがっつり開発をしていて、いろいろ調べたことのメモを書き残しておきます。

この記事では、CMSのDrupalのモジュール開発に関するTipsを読むことができます。

# 環境
* Drupal 10.3.6
* PHP 8.3.10
* MySQL 5.7.44

# モジュールとは

Drupalでのモジュールとは、CMSに機能を追加するためのPHP、Javascript、CSS等のファイルのまとまりです。

モジュールには3種類あります。
1\. 素のDrupalで必要な「コアモジュール」
2\. オープンソースで公開されてい無料で使用できる「コントリビュートモジュール」
3\. 自分で追加する「カスタムモジュール」

この記事で取り扱うのは、3つ目の「カスタムモジュール」です。

## 参考Webサイト
[1.2. 概念: モジュール](https://www.drupal.org/ja/docs/user_guide/ja/understanding-modules.html#:~:text=%E3%81%A8%E3%81%97%E3%81%A6%E3%81%AEDrupal%E3%80%8D-,%E3%83%A2%E3%82%B8%E3%83%A5%E3%83%BC%E3%83%AB%E3%81%A8%E3%81%AF%E4%BD%95%E3%81%A7%E3%81%99%E3%81%8B%3F,%E3%81%99%E3%82%8B%E3%81%93%E3%81%A8%E3%81%8C%E3%81%A7%E3%81%8D%E3%81%BE%E3%81%99%E3%80%82)
[モジュールでDrupalサイトの機能拡張をしよう～インストールからモジュールを開発する方法を解説](https://codezine.jp/article/detail/13559)

# カスタムモジュールで必要なもの

カスタムモジュールは自分で作ることができます。サイトの見た感を作り込みたいとか、より詳細なバリデーションを入れたいとか、そういうニーズを、コードを書くことで満たすことができます。

## 今回想定するモジュール

* 名前：test
* 機能：CSVファイルを出力
* 実行タイミング：ビュー「〇〇管理一覧」に配置した「CSVエクスポート」ボタンを押下時

システムとしては、業務アプリを想定しています。その業務アプリの中で、「◯◯管理一覧」というビューがあり、そのビュー上に「CSVエクスポート」ボタンがあって、そのボタンを押下した時に、Drupalで管理されているデータを吸い上げてCSVファイルに出力するイメージです。

この記事では、CSVファイルに出力する処理については、言及しません。

## ディレクトリ構成

web/modules/customディレクトリ直下に、カスタムモジュール用のディレクトリを作り、その中にコードを配置します。

下記では「test」という名前のモジュールを想定して、その際のディレクトリ構成を記載しています。

```
web/modules/custom
    test                ←ディレクトリ
        src             ←ディレクトリ
            Controller  ←ディレクトリ
                TestController.php
        test.info.yml
        test.module
        test.routing.yml
```

最低でもこれだけのディレクトリ構成とファイルは必要です。

## 必要なファイルについて

### 設定ファイル

`test.info.yml`を指します。

中身は下記の通りです。

``` test.info.yml
name: test
type: module
description: 'CSVファイルを出力する'
package: Custom
core_version_requirement: ^10
author: Kyon
```

中身の説明は下記の通りです。

* name：モジュールの名称。Drupalの管理画面に表示有り。
* type：モジュールの場合は「modules」固定。
* description：モジュールの説明。Drupalの管理画面に表示有り。
* package：「Custom」というパッケージ名で管理することを表す。
* core_version_requirement：Drupalのどのコアバージョンで動作するかを指定。
* author：モジュールの作者名。

「package」「author」あたりは、関係者が多い（会社が複数社関わっている等）場合に設定しておくと、担当や責任範囲が分かりやすくて良いかなと思います。

### モジュールフック設定

`test.module`を指します。

今回想定のモジュールでは特に記載することが無かったので、省略します。

### ルーティング設定

PHPなら、おなじみの設定ですね。

`test.routing.yml`を指します。

中身は下記の通りです。

``` test.routing.yml
test.downloadCSV:
  path: '/admin/list/downloadCSV/csv'
  
  defaults: 
    _title: 'CSV Download
    _controller: '\Drupal\test\Controller\TestController::downloadCSV'
  requirements:
    _permission: 'access content'
```

中身の説明は下記の通りです。

* path：ルーティングのURL。今回だと、「CSVエクスポート」ボタンを押下時のURL。
* _title：ページのタイトル。
* _controller：ルーティングで使用するControllerファイル名とそのメソッド名。
* _permission：アクセス可能な権限。「access content」だとどの権限のユーザもアクセス可。

「_permission」は、管理者権限のみアクセス可にしたい場合は「administrator」です。

### Controller

一応PHPファイルのControllerも提示しておきます。

``` TestController.php
<?php
namespace Drupal\test\Controller;

use Drupal\Core\Controller\ControllerBase;

class HelloWorldController extends ControllerBase {

    public function downloadCSV() {
    // ここに処理を書く
    }
}
```

## モジュールのインストール

モジュールは上記のファイルを作成しただけでは、使用できません。

管理画面にログインして、モジュールをインストールする必要があります。

`管理画面＞管理＞機能拡張` にアクセスして、リストの中から「test」モジュールを探します。

「test」モジュールにチェックを入れて、画面下部の「インストール」ボタンを押下します。

下記メッセージが表示されたら、インストール完了です。

```
ステータスメッセージ
モジュール test が有効化されました。
```

## モジュールをアンインストールする場合

`管理画面＞管理＞機能拡張＞モジュールをアンインストール` にアクセスして、リストの中から「test」モジュールを探します。

「test」モジュールにチェックを入れて、画面下部の「アンインストール」ボタンを押下することで、アンインストールが完了します。

ディレクトリを先に削除してしまうと、Drupalの管理と実態が合わず、管理画面にログインできなくなる可能性があるので、要注意です。

# 参考Webサイト

[Drupalでカスタムモジュールを作ってみよう](https://qiita.com/nekihcom/items/4b9cfce4e1656c29d3f4#%E3%83%A2%E3%82%B8%E3%83%A5%E3%83%BC%E3%83%AB%E3%82%92%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB%E3%81%99%E3%82%8B)

[Drupal 8 入門 : カスタムモジュール作成編](https://www.studio-umi.jp/blog/14/182)

[Drupalのモジュール作成方法　Part.1](https://www.ffront.jp/drupalstudy/28)