レガシーPHPリファクタ 28:ソートUIの近代化

はじめに

2007年に執筆した『Smarty動的Webサイト構築入門』のサンプルコードリポジトリを現在もメンテナンスしています。

今回は、本書の第4章(第4.6節)で登場する「ソートナビゲーター(昇順・降順ボタンの切り替え)」の実装を取り上げます。

修正前は、PHP側(サービスクラス)が <img> タグやURL生成ロジック、HTML文字列の組み立てを抱え込み、テンプレート側で複雑なオプション設定を行う密結合な設計になっていました。 これを、「サーバー側は静的な構造とデータ属性のみを出力し、動的な振る舞いはすべてJavaScriptに任せる」というモダンな設計へリファクタリングした実践例をご紹介します。


1. 修正前のコードと問題点

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

  {$sortNavigator->setOption('asc_current' , '<img src="images/btn_asc_current.gif"  alt="" border="0" />')}
  {$sortNavigator->setOption('asc_link'    , '<img src="images/btn_asc.gif"          alt="" border="0" />')}
  {$sortNavigator->setOption('desc_current', '<img src="images/btn_desc_current.gif" alt="" border="0" />')}
  {$sortNavigator->setOption('desc_link'   , '<img src="images/btn_desc.gif"         alt="" border="0" />')}

  <table border="0" cellspacing="0">
  <tr>
    <th>ID      <br />{$sortNavigator->show('id')}</th>
    <th>カテゴリ<br />{$sortNavigator->show('category')}</th>
    <th>タイトル<br />{$sortNavigator->show('title')}</th>
    <th class="comment">コメント<br />{$sortNavigator->show('comment')}</th>
    <th>日付    <br />{$sortNavigator->show('time')}</th>
  </tr>

修正前のPHPクラス (SortNavigator.php)

<?php

namespace SmartyBook\chapter4_6\src;

class SortNavigator
{
    private string $sortKey;
    private string $sortDirection;
    /** @var array<string, string> */
    private array $vars;

    public function __construct(string $sortKey, string $sortDirection)
    {
        $this->vars['asc_current' ] = '△';
        $this->vars['asc_link'    ] = '▲';
        $this->vars['asc_title'   ] = '昇順';
        $this->vars['desc_current'] = '▽';
        $this->vars['desc_link'   ] = '▼';
        $this->vars['desc_title'  ] = '降順';
        $this->vars['separator'   ] = '';

        $this->vars['sortKeyUrlVar' ] = 'sort_key';
        $this->vars['sortDirectionUrlVar'] = 'sort_direction';

        $this->sortKey  = $sortKey;
        $this->sortDirection = $sortDirection;
    }

    public function setOption(string $key, string $value): void
    {
        if (isset($this->vars[$key])) {
            $this->vars[$key] = $value;
        }
    }

    public function show(string $sortKey): void
    {
        $asc_navi  = $this->showLink($sortKey, 'asc');
        $desc_navi = $this->showLink($sortKey, 'desc');

        $buf = $asc_navi . $this->vars['separator'] . $desc_navi;
        print $buf;
    }

    public function showLink(string $sortKey, string $sortDirection): string
    {
        if (($sortKey == $this->sortKey) && ($sortDirection == $this->sortDirection)) {
            if ($sortDirection == 'asc') {
                $text  = $this->vars['asc_current'];
            } else {
                $text  = $this->vars['desc_current'];
            }
            $buf = $text;
        } else {
            if ($sortDirection == 'asc') {
                $text  = $this->vars['asc_link' ];
                $title = $this->vars['asc_title'];
            } else {
                $text  = $this->vars['desc_link' ];
                $title = $this->vars['desc_title'];
            }

            $vars = [
                $this->vars['sortKeyUrlVar' ] => $sortKey,
                $this->vars['sortDirectionUrlVar'] => $sortDirection,
                'pageID'                   => 1,
            ];
            $html = [];
            $html['href' ] = $_SERVER['SCRIPT_NAME'] . '?' . $this->replaceQuery($_SERVER['QUERY_STRING'], $vars);
            $html['title'] = $title;
            $html['text' ] = $text;

            $buf = <<<EOT
<a href="{$html['href']}" title="{$html['title']}">{$html['text']}</a>
EOT;
            $buf = ltrim($buf);
        }

        return $buf;
    }

    public function replaceQuery(string $query, array $vars): string
    {
        $tmpVars = [];
        parse_str($query, $tmpVars);

        foreach ($vars as $key => $val) {
            $tmpVars[$key] = $val;
        }

        $buf = http_build_query($tmpVars);
        return $buf;
    }
}

💡 修正前の主な問題点

  1. クラスの役割の曖昧さ(サービスクラスかデータクラスか): レガシーコードにありがちですが、SortNavigator クラスは setOption で内部の状態(表示文字列やパラメータ名など)を次々と保持・変更していく仕様になっていました。「HTMLをレンダリングするサービスクラス」なのか「設定を保持するデータクラス」なのかが非常に曖昧で、インスタンスの責務が肥大化していました。
  2. HTML文字列のPHP内ハードコード: SortNavigator クラスが <a> タグや <img> タグの文字列を直接組み立てて出力しており、デザインの変更がPHPコードの修正を伴う。
  3. テンプレートの煩雑化: テンプレートの冒頭で setOption を何度も呼び出してアイコンのHTMLを設定し、さらに各 th タグ内でメソッドを呼び出しているため、マークアップの見通しが非常に悪い。
  4. 責務の混在: ビューの表現、URLの組み立て、クエリパラメータの置換といった処理が1つのサービスクラスに集中している。

2. リファクタリングの方針検討

Smartyの解説書籍のサンプルコードであるため、以下のようなアプローチが考えられました。

  • 案1:Smartyプラグイン(関数)としてリファクタする
    • Smartyの枠組みの中に閉じこもる方法ですが、テンプレートの複雑さが残り、現代のフロントエンド開発との乖離が埋まりません。
  • 案2:HTMLを静的な構造にし、動的制御はJavaScript(データ属性)に逃がす
    • PHP側やSmartyの複雑なオブジェクト操作を全廃し、HTMLは純粋な構造のみを記述。アクティブ状態の切り替えやURL生成はJSに任せるアプローチです。

レガシーシステムの現実的な「省エネ・リファクタ」として、今回は案2を採用しました。差分(diff)はやや大きく見えますが、保守性や関心の分離の観点で圧倒的にメリットが大きくなります。


3. リファクタ後のコード

修正後のテンプレート (templates/pages/chapter4_6/index.tpl)

smartybook/templates/pages/chapter4_6/index.tpl at ae7cd26b1982604adb4a74e93cd2798b07605068 · ninton/smartybook
Smarty動的Webサイト構築入門サンプルソース. Contribute to ninton/smartybook development by creating an account on GitHub.
  <table style="border: none;">
  {* サーバー側からは静的な構造と初期データ属性のみを出力 *}
  <tr id="sortable-header" data-script-name="{$smarty.server.SCRIPT_NAME}" data-current-sort="{$sortKey|escape}" data-current-dir="{$sortDirection|escape}">
    <th data-sort-key="id">
      ID<br />
      <span class="sort-buttons">
        <a href="#" data-direction="asc" title="昇順"><img src="images/btn_asc.gif" alt="" /></a>
        <a href="#" data-direction="desc" title="降順"><img src="images/btn_desc.gif" alt="" /></a>
      </span>
    </th>
    <th data-sort-key="category">
      カテゴリ<br />
      <span class="sort-buttons">
        <a href="#" data-direction="asc" title="昇順"><img src="images/btn_asc.gif" alt="" /></a>
        <a href="#" data-direction="desc" title="降順"><img src="images/btn_desc.gif" alt="" /></a>
      </span>
    </th>
    <th data-sort-key="title">
      タイトル<br />
      <span class="sort-buttons">
        <a href="#" data-direction="asc" title="昇順"><img src="images/btn_asc.gif" alt="" /></a>
        <a href="#" data-direction="desc" title="降順"><img src="images/btn_desc.gif" alt="" /></a>
      </span>
    </th>
    <th class="comment" data-sort-key="comment">
      コメント<br />
      <span class="sort-buttons">
        <a href="#" data-direction="asc" title="昇順"><img src="images/btn_asc.gif" alt="" /></a>
        <a href="#" data-direction="desc" title="降順"><img src="images/btn_desc.gif" alt="" /></a>
      </span>
    </th>
    <th data-sort-key="time">
      日付<br />
      <span class="sort-buttons">
        <a href="#" data-direction="asc" title="昇順"><img src="images/btn_asc.gif" alt="" /></a>
        <a href="#" data-direction="desc" title="降順"><img src="images/btn_desc.gif" alt="" /></a>
      </span>
    </th>
  </tr>

修正後のJavaScript (smartybook/chapter4_6/js/sortNavigator.js)

smartybook/smartybook/chapter4_6/js/index.js at ae7cd26b1982604adb4a74e93cd2798b07605068 · ninton/smartybook
Smarty動的Webサイト構築入門サンプルソース. Contribute to ninton/smartybook development by creating an account on GitHub.
const headerRow = document.getElementById('sortable-header');
if (headerRow) {
  initTableSort(headerRow);
}

/**
 * @param {HTMLElement} headerRow - ソート対象のテーブルヘッダー行
 */
function initTableSort(headerRow) {
  // PHP側で確定したソート状態を利用する
  const currentSort = headerRow.dataset.currentSort || 'id';
  const currentDir = headerRow.dataset.currentDir || 'asc';

  // 2. 現在アクティブなソート項目のアイコンを _current.gif に差し替え
  const thElements = headerRow.querySelectorAll('th[data-sort-key]');
  thElements.forEach((th) => {
    const sortKey = /** @type {HTMLElement} */ (th).dataset.sortKey;
    // noinspection JSIncompatibleTypesComparison PhpStormの誤検知
    if (sortKey === currentSort) {
      const targetLink = Array.from(th.querySelectorAll('a[data-direction]'))
        .find((link) => /** @type {HTMLElement} */ (link).dataset.direction === currentDir)
        ?.querySelector('img');
      if (targetLink) {
        targetLink.src = targetLink.src.replace('.gif', '_current.gif');
      }
    }
  });

  // ソート先を設定し、ブラウザー標準のリンク操作を維持する
  /** @type {NodeListOf<HTMLAnchorElement>} */
  const links = headerRow.querySelectorAll('th[data-sort-key] a[data-direction]');
  links.forEach((link) => {
    const th = link.closest('th');
    if (!th) return;

    const sortKey = th.dataset.sortKey;
    const direction = link.dataset.direction;
    if (!sortKey || !direction) return; // 必須の属性値が存在しない場合はスキップ

    const params = new URLSearchParams(window.location.search);
    params.set('sort_key', sortKey);
    params.set('sort_direction', direction);
    params.set('pageID', '1'); // ソート変更時は1ページ目に戻す
    const scriptName = headerRow.dataset.scriptName || window.location.pathname;
    link.href = `${scriptName}?${params.toString()}`;
  });
}

(※PHP側の SortNavigator クラスファイル自体は不要になるため完全に削除しました)


4. リファクタリングのメリット

  1. 責務の分離(SeP)の徹底
  • PHP側: ソートキーや方向といった「状態(データ)」をテンプレートへ渡すことに専念し、UI生成の責務から完全に解放されました。
  • HTML側: 誰が読んでも構造が追いやすいクリーンなマークアップになりました。
  • JS側: 状態に応じたアイコンの切り替えやURLパラメータの構築という「振る舞い」をスマートに一括処理します。
  1. テンプレートの可読性向上
  • 煩雑な setOption の初期化コードやPHPメソッドの呼び出しが消え、フロントエンドエンジニアがHTML/CSSを安全に触れる環境になりました。
  1. 設定の柔軟性と保守性
  • 以前はHTMLの断片がPHPコード内にハードコードされていましたが、マークアップ側へ完全に移行したため、画像パスの変更やデザインの改修が容易になりました。

まとめ

修正前の SortNavigator クラスの呼び出し部分は、一見するとテンプレートがすっきり整然としているように見えます。

  {$sortNavigator->setOption('asc_current' , '<img src="images/btn_asc_current.gif"  alt="" border="0" />')}
  {$sortNavigator->setOption('asc_link'    , '<img src="images/btn_asc.gif"          alt="" border="0" />')}

    <th>ID      <br />{$sortNavigator->show('id')}</th>
    <th>カテゴリ<br />{$sortNavigator->show('category')}</th>

しかし、この実装では、SortNavigator クラスが内部で何をしているのかコード単体では追うことができませんでした。 また、実際にブラウザで出力されるHTML構造や描画結果を確認するため、何度もブラウザのHTMLソースを開いて確認し直す必要がありました。

「呼び出しを整然と見せること」と「保守しやすいこと」はイコールではない――それを痛感したレガシーコードならではの一幕でした。

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