CakePHP3のHtmlHelperのLink設定のまとめ。mailto、URL、Root／Homeのリンクなども

CakePHP3で HtmlHelperを使ってリンクを設定する方法をまとめてみた

Webサイト開発にはリンクは付き物。その設定方法を再確認してみた

　
CakePHP3で開発するサイト、アプリに限らず、Webサイトにはリンクがつきものです。
　
というわけで、この記事では、CakePHP3の HtmlHelperを使ってリンクを設定することに特化して解説していきます。
　
なお、この記事は、CakePHP3用に書いたものですが、確認したところ CakePHP4でも記述形式は同じですので、CakePHP4の記事として読み替えていただいて問題ありません。
　
違う点があるとすれば、テンプレートファイルが「***.ctp」か「***.php」か、といったところでしょうか。（テンプレートが配置されているフォルダの場所も異なりますね。）
　
　
【参考】CakePHP3　Cookbook　HtmlHelper
https://book.cakephp.org/3.0/ja/views/helpers/html.html
　
【参考】CakePHP3　Cookbook　UrlHelper
https://book.cakephp.org/3.0/ja/views/helpers/url.html
　
　
【参考】CakePHP4　Cookbook　HtmlHelper
https://book.cakephp.org/4/ja/views/helpers/html.html
　
【参考】CakePHP4　Cookbook　UrlHelper
https://book.cakephp.org/4/ja/views/helpers/url.html
　
　
フォームを作成する際に利用する FormHelperについては下記の記事を参考にしてください。
CakePHP3のForm Helperの使い方のまとめ
　
また、JavaScript、cssを読み込む設定については下記に記事を書いていますので参考にしてください。
CakePHP3でページごとに読み込むJavaScript、CSSを変える処理の解説
　
　

CakePHP3の HtmlHelperの Link設定の基本形

　
まず、CakePHP3の HtmlHelperの Link設定の基本形です。
　

$this->Html->link("アンカーテキスト",
                  "リンクのパス");

　
　
「アンカーテキスト」は、「<a></a>」で囲まれたリンクが設定される個所のテキストです。
　
具体的には、下記のように記述すると、その下にある HTMLが生成されます。
　

// sample.ctpへの記述
<?= $this->Html->link("アンカーテキスト",
                      "/samples/view/1") ?>

// 生成される HTML
<a href="/samples/view/1">アンカーテキスト</a>

　
「/samples/view/1」の指定は、「/」から記述を始め、ドキュメントルートからのパスを指定します。
相対パスの設定はできません。
　
　

CakePHP3の HtmlHelperのリンクに URLを指定する場合

　
URLを指定してリンクを設定する方法は、基本形でパスを指定するのと同様に 2つめのパラメーターに URLを指定することで設定できます。
　

// sample.ctpへの記述
<?= $this->Html->link("アンカーテキスト",
                      "http://example.com/test.html") ?>

// 生成される HTML
<a href="http://example.com/test.html">アンカーテキスト</a>

　
　
URLを記述する方法は、前項の基本形の設定を理解していれば分かるだろうとも思いますが、Cookbookに説明がないため、私はこの方法が分からずかなりの期間悩んでいました。
　
　

アンカーリンクを翻訳対象とする方法

　
アンカーテキストの部分を翻訳対象にする場合は下記の様に「__(" ")」でテキストを囲みます。
　

<?= $this->Html->link(__("Anchor Text")) ?>

　
CakePHP3の日本語翻訳機能については下記の記事を参考にしてください、。
CakePHP3のメッセージ日本語化の設定（国際化と地域化の機能の使い方の解説）
　
　

　
　

HtmlHelperで Controller、Actionを指定してリンクを設定する方法

　
前項のリンク設定は基本形ではあるものの、一般的にはこちらの Controller、Actionを指定してリンクを設定するほうが多いでしょう。
　

// sample.ctpへの記述
<?= $this->Html->link("アンカーテキスト",
                      ["plugin"=>"CakeDC/Users",
                       "controller"=>"UsersLinks",
                       "action"=>"newView",
                       12345]) ?>

// 生成される HTML
<a href="/users/users-links/new-view/12345">アンカーテキスト</a>

　
　
cakephp3の規約では、プラグイン名、コントローラー名は「パスカルケース（頭文字を大文字にする）」で、アクション名は「キャメルバック（1単語目はすべて小文字で2単語目以降は頭文字を大文字にする）」となっていますので、「"controller"=>"UsersLinks","action"=>"newView"」と記述することが正しい記述方法です。
　
ですが、Controllerも Actionも「UsersLinks」のほか、「usersLinks」「users-links」と記述しても正しいリンクが設定されます。
　
CakePHP3　Cookbook　CakePHPの規約
https://book.cakephp.org/3.0/ja/intro/conventions.html
　
　
「"plugin"=>""」「"controller"=>""」は任意です。
設定しない場合は、現在のプラグイン、コントローラーがデフォルトとして設定されます。
　
また、プラグインが使用されているページから使用していないページにリンクを貼る場合は、「"plugin"=>null」もしくは「"plugin"=>false」を記述します。
　
　

トップページにリンクを設定する方法

　
トップページ（そのサイトのドキュメントルートのページ）にリンクを貼りたい場合は、下記のように null（もしくは false）を設定します。
　

// sample.ctpへの記述
<?= $this->Html->link("アンカーテキスト",
                      ["plugin"=>null,
                       "controller"=>null,
                       "action"=>"/"]) ?>
　
// もしくは
<?= $this->Html->link("アンカーテキスト",
                      ["plugin"=>null,
                       "controller"=>"/"]) ?>
　
// 生成される HTML
<a href="/">アンカーテキスト</a>

　
前項で書きましたが、「null」の代わりに「false」と記述しても問題ありません。
　
また、「"action"=>"/"」の部分は、「"action"=>null」としても問題ない場合が多くあります。
ただ、ルーティングの設定によっては正しくトップページにリンクされない場合がありますので、「"action"=>"/"」としておくほうが無難なようです。
コントローラーの指定も「"controller"=>"/"」としても問題ありません。
　
　
また、トップページにリンクを貼る際、ルーティングでトップページに指定しているコントローラー、アクションを指定する方法もあります。
　

// routes.phpの設定
<?= $routes->connect("/",
                     ["controller"=>"UsersLinks",
                      "action"=>"newView"]) ?>

　
上記のように「/config/routes.php」に設定してある場合は、下記のようにそのコントローラー、アクションを指定することでトップページにリンクが設定されます。
　

// sample.ctpへの記述
<?= $this->Html->link("アンカーテキスト",
                      ["controller"=>"UsersLinks",
                       "action"=>"newView"]) ?>

// 生成される HTML
<a href="/">アンカーテキスト</a>

　
ただ、この記述方法の場合は、ルーティングのトップページの設定を変更した場合に、リンク先がトップページではなくなってしまいますので注意が必要です。
　
　

リンクを絶対 URLで記述する場合は「"_full"=>false」を指定

　
また、生成されるリンクを絶対 URLにしたい場合は「"_full"=>true」を追加します。（デフォルトは「"_full"=>false」となっています。）
　

// sample.ctpへの記述
<?= $this->Html->link("アンカーテキスト",
                      ["plugin"=>"CakeDC/Users",
                       "controller"=>"UsersLinks",
                       "action"=>"newView",
                       12345,
                       "_full"=>true]) ?>

// 生成される HTML
<a href="http://example.com/users/users-links/new-view/12345">アンカーテキスト</a>

リンクのパラメーターはいくつでも追加できる

　
前項のパラメーターは「12345」だけでしたが、パラメーターは複数設定することもできます。
例えば、下記は検索のパラメーターとして 2つの条件を付与する想定です。
　

// sample.ctpへの記述
<?= $this->Html->link("アンカーテキスト",
                      ["plugin"=>"CakeDC/Users",
                       "controller"=>"UsersLinks",
                       "action"=>"search",
                       鈴木,
                       スズキ]) ?>

// 生成される HTML
<a href="/users/users-links/search/鈴木/スズキ">アンカーテキスト</a>

　
また、上記のパラメーターを受け取るアクション側は下記の様になります。
　

// UsersLinksController.php 内の searchアクションの設定
public function search ($user_name, $user_kana){
    アクションの処理
}

　
また、パラメータの取得に関しては下記にも記事を書いていますので、併せて参考にしてください。
「CakePHP3で現在処理しているコントローラー名、アクション名を取得する方法」
「CakePHP4で現在処理しているコントローラー名、アクション名を取得する方法」
　
　

リンクに URLクエリパラメータを指定する方法　2023.12.28　追記

　
リンクに URLクエリパラメータを指定したい場合は、キーとして「?」を指定し、値を配列で指定します。
　

// sample.ctpへの記述
<?= $this->Html->link("アンカーテキスト",
                      ["plugin"=>"CakeDC/Users",
                       "controller"=>"UsersLinks",
                       "action"=>"newView",
                       "?"=>["xxx"=>000,"yyy"=>111]
                       ]) ?>
 
// 生成される HTML
<a href="/users/users-links/new-view?xxx=000&yyy=111">アンカーテキスト</a>

リンクにパラメータと URLクエリパラメータの両方を指定する方法　2023.12.28　追記

　
先に紹介したパラメータと URLクリエパラメータの両方を指定することも出来ます。
　

// sample.ctpへの記述
<?= $this->Html->link("アンカーテキスト",
                      ["plugin"=>"CakeDC/Users",
                       "controller"=>"UsersLinks",
                       "action"=>"newView",
                       12345,
                       23456,
                       "?"=>["xxx"=>000,"yyy"=>111]
                       ]) ?>
 
// 生成される HTML
<a href="/users/users-links/new-view/12345/23456?xxx=000&yyy=111">アンカーテキスト</a>

リンクに class、id、targetを指定する場合

　
リンク設定の基本形に対して、class、id、targetを指定する場合は、3つ目のパラメーターとして配列で指定します。
　
具体的には、下記のように記述すると、その下にある HTMLが生成されます。
　

// sample.ctpへの記述
<?= $this->Html->link("アンカーテキスト",
                      ["plugin"=>"CakeDC/Users",
                       "controller"=>"UsersLinks",
                       "action"=>"newView",
                       12345],
                      ["class"=>"button",
                       "id"=>"view",
                       "target"=>"_blank"]) ?>

// 生成される HTML
<a href="/users/users-links/new-view/12345" class="button" id="view" target="_blank" rel="noopener noreferrer">アンカーテキスト</a>

　
　
最初に解説をしたリンク設定の基本形の場合も 3つ目のパラメータとして指定をします。
　

// sample.ctpへの記述
<?= $this->Html->link("アンカーテキスト",
                      "/samples/view/1",
                      ["class"=>"button",
                       "id"=>"view",
                       "target"=>"_blank"]) ?>

// 生成される HTML
<a href="/samples/view/1" class="button" id="view" target="_blank" rel="noopener noreferrer">アンカーテキスト</a>

リンクに JavaScriptの確認ダイアログを表示する設定

　
CakePHP3ではレコードを削除するリンクをクリックすると表示される「このレコードを削除しますか？」のダイアログですが、これをリンクに設定する方法が用意されています。
　
下記のように 3つ目のパラメーターとして「"confirm"=>""」を指定します。
　

// sample.ctpへの記述
<?= $this->Html->link("アンカーテキスト",
                      ["plugin"=>"CakeDC/Users",
                       "controller"=>"UsersLinks",
                       "action"=>"newView",
                       12345],
                      ["confirm"=>"このレコードを削除してよろしいですか？"]) ?>

// 生成される HTML
<a href="/users/users-links/new-view/12345" onclick="if (confirm("このレコードを削除してよろしいですか？")) { return true; } return false;">アンカーテキスト</a>

　
　
また、3つ目のパラメーターとして「class」などの指定をしている場合は、3つ目のパラメーターの配列の中に追記します。
　

// classも同時に設定する場合
<?= $this->Html->link("アンカーテキスト",
                      ["plugin"=>"CakeDC/Users",
                       "controller"=>"UsersLinks",
                       "action"=>"newView",
                       12345],
                      ["class"=>"button",
                       "confirm"=>"このレコードを削除してよろしいですか？"]) ?>

画像にリンク設定をする方法

　
リンクを設定するアンカーテキスト部分に画像を設定するときは下記のように設定します。
　

// sample.ctpへの記述
<?= $this->Html->link($this->Html->image("cake.power.gif"),
                      ["action"=>"newView",
                       1],
                      ["escape"=>false]) ?>

// 生成される HTML
<a href="/cake3_1/topics/new-view/1"><img src="/cake3_1/img/cake.power.gif" alt=""/></a>

　
ポイントは、3つ目のパラメーターとして設定する「"escape"=>false」です。
これを追加することで、1つ目のパラメーターとして設定している画像の設定がエスケープされずに処理されます。
　
　
「"escape"=>false」を設定しないと、画像のリンク（imgタグ）がエスケープ処理されるため、imgタグがタグとして認識されなくなります。
　

// sample.ctpへの記述
<?= $this->Html->link($this->Html->image("cake.power.gif"),
                      ["action"=>"newView",
                       1]) ?>

// 生成される HTML
<a href="/users/users-links/new-view/1"><img src="/img/cake.power.gif" alt=""/></a>

// ブラウザに表示される文字列
<img src="/img/cake.power.gif" alt=""/>

画像にリンクを設定するけどエスケープする範囲を限定する方法

　
前項で設定する「"escape"=>false」は、リンクの属性もエスケープ対象としてしまいます。
そのため、「"escapeTitle"=>false」を使い、タイトルだけをエスケープすることもできます。
　

// sample.ctpへの記述
<?= $this->Html->link($this->Html->image("cake.power.gif"),
                      ["action"=>"newView",
                       1],
                      ["escapeTitle"=>false,
                       "title"=>'hi "howdy"']) ?>

// 生成される HTML
><a href="/cake3_1/topics/new-view/1" title="hi "howdy""><img src="/cake3_1/img/cake.power.gif" alt=""/></a>

　
　
「"escape"=>false」のままだと、下記のように「title="hi "howdy""」の部分が正しくエスケープされていませんので、想定している title属性の設定になっていません。
　

// sample.ctpへの記述
<?= $this->Html->link($this->Html->image("cake.power.gif"),
                      ["action"=>"newView",
                       1],
                      ["escape"=>false,
                       "title"=>'hi "howdy"']) ?>

// 生成される HTML
><a href="/cake3_1/topics/new-view/1" title="hi "howdy""><img src="/cake3_1/img/cake.power.gif" alt=""/></a>

mailtoのリンクを設定する方法

　
mailtoのリンクを設定する場合は下記の様に設定します。
　

// sample.ctpへの記述
<?= $this->Html->link("アンカーテキスト", "mailto:" . "メールアドレス") ?>

// 生成される HTML
<a href="mailto:メールアドレス">アンカーテキスト</a>

　
この mailtoの設定方法は、最初に紹介したリンク設定の基本形の理解ができていれば、この記述方法にたどり着ける可能性はあるようにも思いますが、URLのリンクを設定する方法と同じく、Cookbookに設定方法が記載されていないため、かなり悩みました。
　
そして、この「mailto」のリンク設定方法を知ったときの驚きで、この記事を書いたと言っても過言ではありません。
　
　

テキスト内のメールアドレスに自動的に mailtoリンクを設定する方法

　
前項の設定は、あらかじめメールアドレスを表示することが分かっている個所に mailtoのリンクを設定する方法です。
　
CakePHP3では、それに加えて、文章内にあるメールアドレスに自動的に mailtoのリンクを設定する方法も用意されています。
　

// sample.ctpへの記述
<?php $myText = 'For more information regarding our world-famous ' .
                'pastries and desserts, contact info@example.com';
      $linkedText = $this->Text->autoLinkEmails($myText);
      echo $linkedText;
?>

// 生成される HTML
For more information regarding our world-famous pastries and desserts, contact <a href="mailto:info@example.com">info@example.com</a>

　
上記のように、メールアドレスを含む文章を「autoLinkEmails()」に通すことで自動的に mailtoのリンクを設定してくれます。
　
この「autoLinkEmails()」は、非常に便利な機能ですが、個人的には前項の普通の mailtoのリンクの解説を Cookbookに書いていてほしかったです．．．
　
　

アンカーテキストに HTMLタグを入れたい場合　2023.12.28　追記

　
アンカーテキストの中に HTMLのタグを入れたい場合は、アンカーに画像を使用したい場合と同じく「"escape"=>false」を使用します。
（linkの処理はデフォルトでは「"escape"=>true」となっていて、デフォルトのままでは HTMLタグはエスケープ（無効化）されます。）
　

// sample.ctpへの記述
<?= $this->Html->link('アンカーリンク<span>ここだけ</span>アンカーリンク',
                      ["action"=>"newView",
                       1],
                      ["escape"=>false]) ?>
　
// 生成される HTML
<a href="/cake3_1/topics/new-view/1">アンカーリンク<span>ここだけ</span>アンカーリンク</a>

CakePHP3の関連記事