CakePHP3のユーザ管理・ログイン認証プラグインCakeDC/Usersのインストール解説・3.6以降対応

2017/04/08 2022/03/31

CakePHP3のユーザ認証管理プラグイン CakeDC/Usersとは

CakeDCとは？

　
CakeDCは、CakePHPを開発した Larry Masters氏が設立した Cake Development Corporationという団体で、CakePHPなどを利用してシステム開発などを請け負う団体です。
　
また、今回紹介するようなユーザ管理、認証管理などを行うプラグイン Usersなどの開発、提供も行っています。
　
　
CakePHPというフレームワークは無償で利用できますので、ユーザが増えても CakePHPを作った方々の収益にはならないため、収益を上げるための事業を行っているのが CakeDCということになるのでしょうか。
　
CakeDCについては下記に案内があります。英語ですが．．．
　https://www.cakedc.com/about
　
　

CakeDC/Usersプラグインとは？

　
今回は、そんな CakePHPを作った方々が提供している CakeDC謹製の Usersというプラグインの紹介です。
　
この Usersプラグインは、会員管理システムを提供するもので、会員の新規登録、ログイン認証、および、管理側で管理する会員管理の仕組みなどをプラグインとして提供するものです。
　
具体的な機能に関しては以下のようなものがあります。
　

ユーザ登録
メールで送信されたトークンによるアカウント確認
ユーザログイン（メールアドレス／パスワード）
ソーシャルログイン（Twitter、Facebook）
メールでトークンを要求し、新しいパスワードを入力することによってパスワードをリセット
ユーザ管理（登録／更新／削除）
シンプルな権限管理
シンプルな Rbacとスーパーユーザの承認
Cookie機能を使用した RememberMe（ログイン状態を保存する）
ユーザ登録時に reCAPTCHA使用

　
※「Rbac」とは？
Rbacとは、ロールベースアクセス制御（Role-based access control）のことで、ユーザはロール（権限）が割り当てられ、そのロールによってアクセス制御をする仕組みのことです。
　
詳細は下記を参照してください。
https://github.com/CakeDC/users/blob/3.1.5/Docs/Documentation/Overview.md
　
　
ちなみに、CakeDC/Usersプラグインをインストールして認証されたページの確認をする際は、あらかじめ何かしらの情報を管理するページがあると検証が分かりやすくなるでしょう。
CakeDC/Usersプラグインを導入するとユーザの管理画面は構築されますが、そのほかの管理画面を、例えば「CakePHP3でファイルのアップロード処理を自作・解説付き・その１」で紹介したような、Newsの CMSなどを Bakeで構築しておくと、ユーザ管理画面と Newsの管理画面など複数の画面で認証ができているかの確認ができますので、あらかじめ作成しておくことをおススメします。
　
　

CakePHP3のユーザ認証管理プラグイン CakeDC/Usersの導入解説

CakeDC/Usersのインストール、設定方法

　
CakeDC/Usersのインストール、設定方法に関する目次
　

１．コンポーザーを使って CakeDC/Usersプラグインをインストール
２．CakeDC/Usersをロードする処理を記述
３．migrationsコマンドで Usersテーブルを構築
４．管理権限ユーザを作成
５．AppController.phpにコンポーネントをロードする処理を記述
６．Usersプラグインの動作確認

CakeDC/Usersのユーザ登録、ログイン、管理側の一覧画面などの URL
CakeDC/Usersがインストールされる場所
参考サイト

　
　
インストールしたのち、設定情報を標準設定から変更する場合や、テンプレートファイルを更新する場合の対応方法は下記の別記事として書いていますので、あわせて参考にしてください。
　
CakePHP3のCakeDC/Usersの画面、メール本文テンプレートのカスタマイズ方法解説
 CakePHP3のCakeDC/Usersのログイン後のリダイレクトとユーザ権限管理の設定解説
 CakePHP3のCakeDC/UsersのUserHelperでログアウトやreCAPTCHAをカスタマイズ
 Google reCAPTCHAのSite key、Secret keyの取得方法・20170408バージョン
 CakePHP3のCakeDC/Usersのバリデーションのカスタマイズ方法解説
　
CakePHP4 に対応した記事は書きに書いていますのでこちらも参考にしてください。
CakePHP4のユーザ管理・ログイン認証プラグインCakeDC/Usersのインストール解説
　

PHPフレームワーク CakePHP 3入門

１．コンポーザーを使って CakeDC/Usersプラグインをインストール

　
コンポーザーを使って CakeDC/Usersプラグインをインストールします。
　
下記コマンドを実行します。

composer require cakedc/users

1	composer require cakedc/users

　
　
バージョンに関するエラーが表示されてインストール出来ない場合は、下記のように最新バージョン以外のバージョンを指定してインストールを試してみてください。
前者は「8.5」を指定する方法で、後者は「8系の最新版」を指定する方法となります。
　

composer require cakedc/users:8.5
composer require cakedc/users:8.*

1 2	composer require cakedc/users:8.5 composer require cakedc/users:8.*

　
　
コンポーザーの使い方については「CakePHP3でcomposerを利用してライブラリ・プラグインをインストールする方法」を参照してください。
　
　

２．CakeDC/Usersをロードする処理を記述

　
インストールした Usersプラグインをロードする処理を記述します。
具体的には、/config/bootstrap.phpの 215行目辺りにプラグインをロードする処理を記述します。
　

Plugin::load('CakeDC/Users', ['routes' => true, 'bootstrap' => true]);

1	Plugin::load('CakeDC/Users', ['routes' => true, 'bootstrap' => true]);

　
「Plugin::loadAll();」の設定をしている場合は、すべてのプラグインがロードされますので、個別の設定は必要ありません。
　
　
CakePHP 3.6.0 以降では、プラグインを読み込むための記述方法が変更になっています。
そのため、CakePHP 3.6.0 以降では下記のように記述します。
　

\App\Application::addPlugin('CakeDC/Users',['routes' => true, 'bootstrap' => true]);

1	\App\Application::addPlugin('CakeDC/Users',['routes' => true, 'bootstrap' => true]);

　
※下記の「Cookbook・プラグイン」のページでは、プラグインの読み込みを「/src/Application.php」に記述する方法が記載されていますが、「/config/bootstrap.php」に記述する場合は、上記のような書き方になります。
https://book.cakephp.org/3.0/ja/plugins.html#id4
　

CakePHP 3.6以降ではプラグインのロードの手続きが変わる

\Cake\Core\Plugin::load('CakeDC/Users');

1	\Cake\Core\Plugin::load('CakeDC/Users');

また、プラグインをロードする記述の方法として、上記のように記述する方法もあります。
　
この記述方法は、基本的には「Plugin::load('CakeDC/Users')」と同じです。
　
この記述方法では、CakePHP 3.6以降になると下記のエラー（Deprecated）が表示されるようになります。
「『Plugin::load()』は非推奨になりますので、『Application::addPlugin()』を使ってください」という内容です。
　
Deprecated (16384): Plugin::load() is deprecated. Use Application::addPlugin() instead. This method will be removed in 4.0.0. - C:\xampp\htdocs\config\bootstrap.php, line: 205 You can disable deprecation warnings by setting Error.errorLevel to E_ALL & ~E_USER_DEPRECATED in your config/app.php. [CORE\src\Core\functions.php, line 311]
　
　
　

３．migrationsコマンドで Usersテーブルを構築

　
Usersプラグインで利用するテーブルを構築します。
　
テーブルを構築するために migrationsコマンドを実行します。

bin/cake migrations migrate -p CakeDC/Users

1	bin/cake migrations migrate -p CakeDC/Users

　
この migrationsコマンドを実行することで、データベースに 3つのテーブルが作成されます。
ユーザーと資格情報が格納される「Users」と、ソーシャル・ログイン機能のトークンが格納され管理される「social_accounts」です。加えて、CakeDC/Usersがバージョンアップして作られるようになった「cake_d_c_users_phinxlog」です。
　
　
上記コマンドは、基本的には開発中のアプリのルートフォルダで実行しますが、もし、cakeコマンドにパスが通っていないときは、「bin」フォルダの中に入って「cake migrations migrate -p CakeDC/Users」を実行してみてください。
　
　

４．管理権限ユーザを作成

　
構築するユーザ管理システムの管理者権限のユーザを作成します。
　
下記コマンドを実行し、新しいユーザ（superadmin）を登録します。

bin/cake users addSuperuser

1	bin/cake users addSuperuser

　
このコマンドを実行すると、ユーザ管理画面を利用するために必要な、完全な管理権限が与えられているスーパーユーザが作成されます。
（管理権限の詳細な設定については、/vendor/cakedc/users/src/Auth/SuperuserAuthorize クラスを参照してください。）
　
コマンドを実行すると、下記の様に処理が実行され、画面が表示されます。
　

C:\xampp\htdocs\cake\bin>cake users addSuperuser

Welcome to CakePHP v3.3.11 Console
---------------------------------------------------------------
App : src
Path: C:\xampp\htdocs\cake\src\
PHP : 5.6.24
---------------------------------------------------------------
Superuser added:
Id: aa54db31-837d-410f-b768-9fa4378eca12
Username: superadmin
Email: superadmin@example.com
Password: 60f14679af96edc8a23450a188f9a8b8

C:\xampp\htdocs\cake\bin>

C:\xampp\htdocs\cake\bin>cake users addSuperuser

Welcome to CakePHP v3.3.11 Console

---------------------------------------------------------------

App : src

Path: C:\xampp\htdocs\cake\src\

PHP : 5.6.24

---------------------------------------------------------------

Superuser added:

Id: aa54db31-837d-410f-b768-9fa4378eca12

Username: superadmin

Email: superadmin@example.com

Password: 60f14679af96edc8a23450a188f9a8b8

C:\xampp\htdocs\cake\bin>

　
パスワードは、ここにしか表示されませんので、しっかり保存しておきましょう。
　
　

５．AppController.phpにコンポーネントをロードする処理を記述

　
AppController.phpに「CakeDC/Users.UsersAuth」のコンポーネントをロードする処理を記載します。
　
対象ファイルは「src/Controller/AppController.php」で、「initialize()」にコンポーネントのロード処理を記述します。
下記の 7行目のように追記します。
　

    public function initialize()
    {
        parent::initialize();
         ：
        中略
         ：
        $this->loadComponent('CakeDC/Users.UsersAuth');
    }

public function initialize()

{

parent::initialize();

：

中略

：

$this->loadComponent('CakeDC/Users.UsersAuth');

}

６．Usersプラグインの動作確認

　
前項までの手順で標準的な設定は完了です。
設定した内容が間違っていないか、ログインの確認を行います。
　
ログイン画面の URLは以下になります。
　http://example.com/login
　
上記でアクセスできない場合は、下記を入力してみてください。
　http://example.com/users/users/login
　
ログインに使う ID、PASSは、「４．管理権限ユーザを作成」で作成した「superadmin」とそのパスワードになります。
　
ログアウトする場合の URLは以下になります。
下記のログアウト URLを入力すると、ログアウト処理が実行され、ログイン画面にリダイレクトします。
　http://example.com/logout
　
　
ちなみに、先に説明した Newsの管理画面を作っておいた場合、それらの管理画面もログイン認証を行わないと画面が表示されなくなっていることが確認できます。
　http://example.com/news
　
　
　

CakeDC/Usersのユーザ登録、ログイン、管理側の一覧画面などの URL

　
インストールした CakeDC/Usersで構築された各画面の URLを記載します。
　
ログイン画面
　http://example.com/login
　
ログアウト URL
　http://example.com/logout
　
管理側のユーザ一覧画面
　http://example.com/users/users/
　
管理側のユーザ登録・更新・削除・詳細画面
　http://example.com/users/users/add
　http://example.com/users/users/edit/:id
　http://example.com/users/users/delete/:id
　http://example.com/users/users/view/:id
　※add以外は、アクセス時にパラメータとして IDが必要です
　
ユーザ側の新規登録画面
　http://example.com/users/users/register
　
ユーザ側のユーザ登録時のメール認証のメール再送信画面
　http://example.com/users/users/resend-token-validation
　
ユーザ側のユーザプロフィール画面（ログイン時）
　http://example.com//users/users/profile
　
ユーザ側のパスワード変更画面（ログイン時）
　http://example.com/users/users/change-password
　
ユーザ側のパスワードリセット画面（メールアドレス入力画面）
　http://example.com/users/users/request-reset-password
　
　
　

CakeDC/Usersがインストールされる場所

　
コンポーザーを使って CakeDC/Usersプラグインをインストールすると、下記の場所にプラグイン関連ファイル一式が設置されます。
　/vendor/cakedc/users
　
下記の場所が CakeDC/Usersの設定ファイルが設置されています。
　/vendor/cakedc/users/config
　
下記の場所に、プラグインのコントローラーの実際の処理が記述してあるファイルが設置されています。
　/vendor/cakedc/users/src/Controller/Traits
　
下記の場所には CakeDC/Usersの入力画面、一覧画面などのテンプレートが設置されています。
　/vendor/cakedc/users/src/Template
　
ただし、「/vendor/cakedc/users」にあるファイル一式はコアファイルですので、これらのファイルは更新しません。
例えば、テンプレートファイルをカスタマイズする場合は、「/src/Template/Plugin/CakeDC/Users」に必要なファイルをコピーしてからカスタマイズを行います。
　
ユーザの新規登録画面の解説と、テンプレートのカスタマイズなどの解説は「CakePHP3のCakeDC/Usersの画面、メール本文テンプレートのカスタマイズ方法解説」に書いていますので、こちらを参照してください。
　
　
　