CakePHP3のコンポーネントクラスを導入して共通処理をまとめるまでの基礎部分を行います。コンポーネントを併用する事で重複メソッドが無くなり見通しも良くメンテナンスしやすいソースコードになります。開発チームみんなが幸せになれる。それがコンポーネントです。

CakePHP3のコンポーネントとは？導入から共通処理をまとめる入門編

今回は、CakePHP3 のコンポーネントクラスを導入して共通処理をまとめるまでの基礎部分を行います。
<h2 id="contents">Contents</h2>
<ol>
<li><a href="#%E9%96%8B%E7%99%BA%E7%92%B0%E5%A2%83">開発環境</a></li>
<li><a href="#%E3%82%B3%E3%83%B3%E3%83%9D%E3%83%BC%E3%83%8D%E3%83%B3%E3%83%88">コンポーネント</a></li>
<li><a href="#%E3%82%B3%E3%83%B3%E3%83%9D%E3%83%BC%E3%83%8D%E3%83%B3%E3%83%88%E7%94%9F%E6%88%90">コンポーネント生成</a></li>
<li><a href="#%E3%82%B3%E3%83%B3%E3%83%9D%E3%83%BC%E3%83%8D%E3%83%B3%E3%83%88%E5%AE%9F%E8%A3%85">コンポーネント実装</a></li>
<li><a href="#%E3%82%B3%E3%83%B3%E3%83%9D%E3%83%BC%E3%83%8D%E3%83%B3%E3%83%88%E3%81%AE%E8%AA%AD%E3%81%BF%E8%BE%BC%E3%81%BF%E4%BD%BF%E7%94%A8">コンポーネントの読み込み・使用</a></li>
<li><a href="#%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%A9%E3%81%B8%E3%81%AE%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9">コントローラへのアクセス</a></li>
<li><a href="#%E3%82%B3%E3%83%B3%E3%83%9D%E3%83%BC%E3%83%8D%E3%83%B3%E3%83%88%E5%86%85%E3%81%A7%E4%BB%96%E3%81%AE%E3%82%B3%E3%83%B3%E3%83%9D%E3%83%BC%E3%83%8D%E3%83%B3%E3%83%88%E3%82%92%E4%BD%BF%E3%81%86">コンポーネント内で他のコンポーネントを使う</a></li>
<li><a href="#%E3%82%B3%E3%83%B3%E3%83%9D%E3%83%BC%E3%83%8D%E3%83%B3%E3%83%88%E7%B6%99%E6%89%BF%E3%81%AB%E3%82%88%E3%82%8B%E7%8B%AC%E8%87%AA%E5%87%A6%E7%90%86%E3%81%B8%E3%81%AE%E7%BD%AE%E3%81%8D%E6%8F%9B%E3%81%88%E8%BF%BD%E5%8A%A0">コンポーネント継承による独自処理への置き換え・追加</a></li>
</ol>
<h2 id="開発環境">開発環境</h2>
今回の開発環境は以下の通りです。
<ul>
<li>Linux CentOS 7</li>
<li>Apache 2.4</li>
<li>PHP 7.2</li>
<li>CakePHP 3.5</li>
</ul>
CakePHP のルートディレクトリを「cakephp/」とします。
<h2 id="コンポーネント">コンポーネント</h2>
コンポーネントとは、広義には部品や要素など、ある何かを形作るための１部の事を指します。
そして CakePHP3 でもまさしく、コントローラ上で使う共通処理を「コンポーネント」という形でまとめる事が出来ます。
小さな処理を部品化（＝コンポーネント化）する事で、それらを使い回し、効率の良い開発が行える。という事になります。この場合では、共通化とも置き換えられます。
公式 CookBook にも記載がある通り、そのメソッド、コピペしようと思ったらコンポーネントにまとめてね！という事です。開発チームみんなが幸せになれる。それがコンポーネントです。
という事で、作業に入っていきます。
<h2 id="コンポーネント生成">コンポーネント生成</h2>
まずはコンポーネントファイルを生成します。 CakePHP ルートディレクトリへ移動し、以下の bake コマンドを叩きます。
<pre><code class="hljs language-shell"># CakePHP のルートディレクトリへ移動する
cd /path/to/cakephp

# bake コマンドでコンポーネントファイルを生成する
bin/cake bake component Common

# 実行結果
[demo@localhost cakephp]# bin/cake bake component Common

Creating file /var/www/html/cakephp/src/Controller/Component/CommonComponent.php
Wrote `/var/www/html/cakephp/src/Controller/Component/CommonComponent.php`
Deleted `/var/www/html/cakephp/src/Controller/Component/empty`

Baking test case for App\Controller\Component\CommonComponent ...
Deleted `/var/www/html/cakephp/tests/TestCase/Controller/Component/empty`

Creating file /var/www/html/cakephp/tests/TestCase/Controller/Component/CommonComponentTest.php
Wrote `/var/www/html/cakephp/tests/TestCase/Controller/Component/CommonComponentTest.php`
</code></pre>
cakephp/src/Controller/Component 配下に CommonComponent.php が生成されます。
<pre><code class="hljs language-shell">cakephp
├─ src
│   ├─ Controller
│   │   ├─ Component
│   │   │   └─ CommonComponent.php
</code></pre>
初期ソースはこんな感じです。
<dl class="description_setting">
<dt>cakephp/src/Controller/Component/CommonComponent.php</dt>
<dd>
<pre><code class="hljs language-php">&#x3C;?php
namespace App\Controller\Component;

use Cake\Controller\Component;
use Cake\Controller\ComponentRegistry;

/**
 * Common component
 */
class CommonComponent extends Component
{

 /**
 * Default configuration.
 *
 * @var array
 */
 protected $_defaultConfig = [];
}
</code></pre>
</dd>
</dl>
<h2 id="コンポーネント実装">コンポーネント実装</h2>
それでは生成したコンポーネントクラスに機能を実装します。今回は、渡ってきた引き数が 10 よりも大きいかで真偽を返す簡単なメソッドを記述しました。
<dl class="description_setting">
<dt>cakephp/src/Controller/Component/CommonComponent.php</dt>
<dd>
<pre><code class="hljs language-php">&#x3C;?php
namespace App\Controller\Component;

use Cake\Controller\Component;

/**
 * Common component
 */
class CommonApiComponent extends Component
{
 protected $_defaultConfig = [];

 /**
 * 引数の値が10よりも大きい事を返却する
 * @param $number
 * @return bool
 */
 public function abcd($number)
 {
 if($number > 10) {
 return true;
 } else {
 return false;
 }
 }
}
</code></pre>
</dd>
</dl>
こういった簡単なものから、Table オブジェクトを使った DB 系のアクションなど、コンポーネントでは必要なものを読み込んで柔軟に記述していく事が出来ます。
<h2 id="コンポーネントの読み込み使用">コンポーネントの読み込み・使用</h2>
作成したコンポーネントを使用する際も手順は極めてシンプルです。例えば、SampleController に以下のように実装します。
<pre><code class="hljs language-php">&#x3C;?php
namespace App\Controller;

use App\Controller\AppController;
use Cake\ORM\TableRegistry;

class SampleController extends AppController
{
 public function initialize()
 {
 parent::initialize();
 $this->loadComponent('Common');　// コンポーネントの読み込み
 }

 public function index()
 {
 $number = 12;
 // $number が 10 より大きいかを確認する
 $ret = $this->CommonApi->abcd($number);

 printr($ret);
 }
}
</code></pre>
コンストラクタである initialize() で Common コンポーネントを読み込んでいます。コンポーネントはまず読み込みを行う事で使用できるようになります。
ちなみに initialize 内でなくても、index() など通常のアクションの中からでも読み込む事が可能です。
そして index() アクションでは 
$this->CommonApi->abcd(); 
の形でコンポーネントを使う事が出来ます。
基本的な流れは以上です。
<h2 id="コントローラへのアクセス">コントローラへのアクセス</h2>
コンポーネントは通常コントローラからコールされて使われますが、その中でコンポーネントからコントローラへアクセスする事も出来ます。
以下はコンポーネントクラスでの記述です。
<pre><code class="hljs language-php">public function abcd()
{
 // 現在のコントローラーに アクセス
 $controller = $this->_registry->getController();

 // メンバ変数を参照したり
 $param = $controller->hoge;
 
 // メソッドもコール出来る
 $result = $controller->getMyTreasure();
}
</code></pre>
_registry から getController() で現在のコントローラを呼ぶ事が出来ます。
そしてそこからメンバ変数を参照したり、メソッドを実行したりもできます。
コントローラからコンポーネントへ値やインスタンスを渡さなくて良かったりするので地味に便利です。
<h2 id="コンポーネント内で他のコンポーネントを使う">コンポーネント内で他のコンポーネントを使う</h2>
あるコンポーネントの中で、他のコンポーネントを呼び出して使いたい場合があります。その場合は、以下のように記述します。
<pre><code class="hljs language-php">&#x3C;?php
namespace App\Controller\Component;

use Cake\Controller\Component;

class CommonComponent extends Component
{

 // 他のコンポーネントを読み込む
 public $components = ['OtherOne', 'OtherTwo', 'OtherThree'];

 public function index()
 {
 // 読み込んだコンポーネントを使用する
 $ret = $this->OtherOne->hoge();
 }
}
</code></pre>
メンバ変数 $components にて、配列の形でコンポーネントを指定すれば、そのまま利用可能になります。
<h2 id="コンポーネント継承による独自処理への置き換え追加">コンポーネント継承による独自処理への置き換え・追加</h2>
コントローラ内で読み込んでいるコンポーネントに対して、狙った部分だけ置き換えたり付け加えたりも出来ます。
その場合は、追加もしくは置き換えようとしている独自処理をコンポーネントとして作成し、それらを適宜コントローラで切り替えていく事ができます。
例えば既存の Hoge コンポーネントに対して、ある部分で処理を付け加えて使用したいとします。
まずは追加メソッドを実装したコンポーネントを作成します。 cakephp/src/Controller/Component 配下に MyHogeComponent.php を作成し、以下のように実装します。
<dl class="description_setting">
<dt>cakephp/src/Controller/Component/MyHogeComponent.php</dt>
<dd>
<pre><code class="hljs language-php">&#x3C;?php
namespace App\Controller\Component;

use Cake\Controller\Component\HogeComponent;

class MyHogeComponent extends HogeComponent
{
 public function plusMethod()
 {
 // 処理
 }
}
</code></pre>
</dd>
</dl>
HogeComponent を継承し、適宜追加分のメソッドを記述したり、HogeComponent 内の置き換えたい処理を記述したりします。
独自コンポーネントの作成が終わったら、コントローラへ次のように記述します。
<dl class="description_setting">
<dt>cakephp/src/Controller/SamplesController.php</dt>
<dd>
<pre><code class="hljs language-php">class SamplesController extends AppController
{
 public function initialize()
 {
 $this->loadComponent('Hoge', [
 'className' => 'MyHoge'
 ]);
 }
}
</code></pre>
</dd>
</dl>
loadComponent() する際に、オプションで className プロパティを設定する事で、コンポーネントを置き換える事が出来ます。
上記例の場合は、Sample コントローラに対しては Hoge コンポーネントを継承し独自処理を追加した MyHoge コンポーネントを割り当てることができる。というわけです。
<h2 id="まとめ">まとめ</h2>
作業は以上です。コンポーネントを併用する事で、重複メソッドが無くなり見通しも良くメンテナンスしやすいソースコードになるので、是非試してみてください。

Author