レガシーPHPリファクタ 29:PEAR::Pagerの密結合を解消し、DTOとマッパーでビューをクリーンに保つ

2007年に執筆した『Smarty動的Webサイト構築入門』のサンプルコードリポジトリのメンテナンスを行っています。本連載では、レガシーなPHPとSmartyで書かれたコードを、現代的なPHPの設計思想や機能を使ってどのようにリファクタリングしていくかを実践形式で紹介しています。

今回は、ページネーションライブラリとして広く使われていた PEAR::Pager のテンプレートおよびコントローラー周りのリファクタリングを取り上げます。


4.6章 スクリーンショット


修正前の状態と課題

修正前は、テンプレートやコントローラーで PEAR::Pager の固有メソッドや動的プロパティに強く依存していました。

修正前のテンプレート (index.tpl)

全{$Pager->numItems()}件中 {$Pager->ExOffsetFrom}件目~{$Pager->ExOffsetTo}件目 | 
全{$Pager->numPages()}ページ中 {$Pager->getCurrentPageID()}ページ目 | 
表示件数{$Pager->getPerPageSelectBox(1, 20, 1, true, $perpage_params)}

{if not $Pager->isFirstPage()}
<a href="{$Pager->ExFirstPageLink}">&lt;&lt;先頭へ</a>
{else}
&lt;&lt;先頭へ
{/if}

{if $Pager->getPreviousPageID()}
<a href="{$Pager->ExPreviousPageLink}">&lt;前へ</a>
{else}
&lt;前へ
{/if}

{$Pager->getPageSelectBox($popup_params)}
{$Pager->ExLinks}

{if $Pager->getNextPageID()}
<a href="{$Pager->ExNextPageLink}">次へ&gt;</a>
{else}
次へ&gt;
{/if}

{if not $Pager->isLastPage()}
<a href="{$Pager->ExLastPageLink}">最後へ&gt;&gt;</a>
{else}
最後へ&gt;&gt;
{/if}

{$Pager->getCurrentPageID()}/{$Pager->numPages()}ページ

修正前のコントローラー (index.php)

$pager = Pager::factory($params);

// Pagerクラスにプロパティを追加する
$pager->ExOffsetFrom   = $from;
$pager->ExOffsetTo     = $to;
$links = $pager->getLinks();
$pager->ExLinks = $links['pages'];
$pager->ExFirstPageLink    = '';
$pager->ExLastPageLink     = '';
$pager->ExPreviousPageLink = '';
$pager->ExNextPageLink     = '';

if (preg_match('/href="(.*?)"/', $links['first'], $matches)) {
    $pager->ExFirstPageLink    = $matches[1];
}
if (preg_match('/href="(.*?)"/', $links['last'], $matches)) {
    $pager->ExLastPageLink    = $matches[1];
}
if (preg_match('/href="(.*?)"/', $links['back'], $matches)) {
    $pager->ExPreviousPageLink    = $matches[1];
}
if (preg_match('/href="(.*?)"/', $links['next'], $matches)) {
    $pager->ExNextPageLink    = $matches[1];
}

抱えていた主な問題点

  1. ライブラリへの過度な依存: テンプレート内で $Pager->getPerPageSelectBox() や $Pager->getPageSelectBox() といった PEAR::Pager 特有のメソッドを直接呼び出していた。
  2. 動的プロパティの多用: Pager インスタンスに ExOffsetFrom などのカスタムプロパティを動的に生やしていた。
  3. 密結合による移行の困難さ: テンプレートがライブラリの内部構造に依存しているため、将来的に別のページネーションライブラリへ置き換えることが極めて困難な状態だった。

リファクタリング方針

  • 1ページあたりの表示件数の selectbox を Smarty 標準の {html_options} に置き換える。
  • 現在のページ番号の selectbox も同様に Smarty 標準の {html_options} に置き換える。
  • 軽量な PagerDto クラスを用意し、PEAR::Pager のインスタンスからマッパー経由で DTO を生成するようにする。
  • Smarty テンプレートへは PEAR::Pager オブジェクトではなく、プレーンな PagerDto を渡す。

修正後の実装

1. 修正後のテンプレート (index.tpl)

全{$pagerDto->numItems}件中 {$pagerDto->offsetFrom}件目~{$pagerDto->offsetTo}件目 | 
全{$pagerDto->numPages}ページ中 {$pagerDto->currentPageID}ページ目 | 
表示件数{html_options
    name="setPerPage"
    options=$perPageOptions
    selected=$currentPerPage
    onchange='document.forms["perPage"].submit()'
}

{if $pagerDto->firstPageHref}
<a href="{$pagerDto->firstPageHref}">&lt;&lt;先頭へ</a>
{else}
&lt;&lt;先頭へ
{/if}

{if $pagerDto->previousPageHref}
<a href="{$pagerDto->previousPageHref}">&lt;前へ</a>
{else}
&lt;前へ
{/if}

{html_options
    name="pageID"
    options=$pageOptions
    selected=$pagerDto->currentPageID
    onchange="let url = new window.URL(document.location.href); url.searchParams.set('pageID', this.value); document.location.href = url.href;"
}
{$pagerDto->links}

{if $pagerDto->nextPageHref}
<a href="{$pagerDto->nextPageHref}">次へ&gt;</a>
{else}
次へ&gt;
{/if}

{if $pagerDto->lastPageHref}
<a href="{$pagerDto->lastPageHref}">最後へ&gt;&gt;</a>
{else}
最後へ&gt;&gt;
{/if}

{$pagerDto->currentPageID}/{$pagerDto->numPages}ページ

2. 修正後のコントローラー (index.php)

$pager = Pager::factory($params);

$pagerDto = PearPagerMapper::toDto($pager);

3. PagerDto (PagerDto.php)

final readonly class PagerDto
{
    public function __construct(
        public int $currentPageID = 0,
        public int $numPages = 0,
        public int $numItems = 0,
        public int $offsetFrom = 0,
        public int $offsetTo = 0,
        public string $links = '',
        public string $firstPageHref = '',
        public string $lastPageHref = '',
        public string $previousPageHref = '',
        public string $nextPageHref = '',
    ) {
    }
}

4. マッパークラス (PearPagerMapper.php)

final class PearPagerMapper
{
    public static function toDto(Pager $pager): PagerDto
    {
        list($offsetFrom, $offsetTo) = $pager->getOffsetByPageId();
        $links = $pager->getLinks();

        return new PagerDto(
            currentPageID: $pager->getCurrentPageID(),
            numPages: $pager->numPages(),
            numItems: $pager->numItems(),
            offsetFrom:       $offsetFrom,
            offsetTo:         $offsetTo,
            links:            $links['pages'] ?? '',
            firstPageHref:    self::extractHref($links['first'] ?? ''),
            lastPageHref:     self::extractHref($links['last'] ?? ''),
            previousPageHref: self::extractHref($links['back'] ?? ''),
            nextPageHref:     self::extractHref($links['next'] ?? ''),
        );
    }

    private static function extractHref(string $html): string
    {
        if (preg_match('/href="(.*?)"/', $html, $matches)) {
            return $matches[1];
        }
        return '';
    }
}

今回のリファクタリングにおける主なメリット

今回のリファクタリングにおける最大のメリットは、「PEAR::Pager というレガシーな外部ライブラリへの密結合を解消し、DTO(Data Transfer Object)とマッパーパターンによって関心事の分離(Separation of Concerns)を徹底したこと」 です。

  1. テンプレートからレガシーライブラリの依存を完全排除 ビュー層がプレゼンテーションの責務に専念できるようになり、テンプレートが依存するのはプレーンなプロパティを持つ PagerDto と Smarty 標準の {html_options} のみとなりました。
  2. データ変換・抽出ロジックのカプセル化 コントローラーに散在していた動的プロパティの付与や preg_match による正規表現抽出処理が、すべて PearPagerMapper に隠蔽されました。
  3. final readonly class による不変性と型安全性の確保 PHPのモダンな機能を活用することで、意図せぬプロパティの書き換えを防ぎ、IDEの補完や静的解析の恩恵を最大限に受けられます。
  4. 描画処理の標準化({html_options} の活用) 独自のセレクトボックス生成メソッドへの依存をなくしました。

本質的な考察:なぜ「自分たちの DTO」に変換するのか?

本質は 「PagerDto が自分たちの制御下にあるプレーンなデータ構造であること」 にあります。

  • anti-corruption レイヤーとしてのマッパー: 外部ライブラリの独自の仕様や泥臭い実装がアプリケーションやビューに直接漏れ出すのを防ぐ防壁となります。
  • 将来の捨てやすさの担保: もし将来別のライブラリや自前ロジックへ移行したくなった場合でも、修正が必要なのは PearPagerMapper の1箇所だけで済みます。

サードパーティ製ライブラリのオブジェクトをそのままビューに渡さず、自分たちのドメインに馴染んだ綺麗な DTO にマッピングしてコントロール下に置くアプローチは、レガシーシステムのモダナイゼーションにおいて極めて強力なプラクティスです。

タイトルとURLをコピーしました