# Table of Contents

- [Welcome | CakePHP](#welcome-cakephp)
- [Not Found | CakePHP](#not-found-cakephp)
- [ページが見つかりません。 | CakePHP](#-cakephp)
- [Appendices | CakePHP](#appendices-cakephp)
- [付録 | CakePHP](#-cakephp)
- [Url | CakePHP](#url-cakephp)
- [Tutorials & Examples | CakePHP](#tutorials-examples-cakephp)
- [Using CakePHP | CakePHP](#using-cakephp-cakephp)
- [Bookmarker Tutorial | CakePHP](#bookmarker-tutorial-cakephp)
- [Bookmarker Tutorial Part 2 | CakePHP](#bookmarker-tutorial-part-2-cakephp)
- [Phinx Migrations | CakePHP](#phinx-migrations-cakephp)
- [Content Management Tutorial | CakePHP](#content-management-tutorial-cakephp)
- [CMS Tutorial - Tags and Users | CakePHP](#cms-tutorial-tags-and-users-cakephp)
- [Blog Tutorial - Authentication and Authorization | CakePHP](#blog-tutorial-authentication-and-authorization-cakephp)
- [Form | CakePHP](#form-cakephp)
- [Upgrade Tool | CakePHP](#upgrade-tool-cakephp)
- [Flash | CakePHP](#flash-cakephp)
- [CMS Tutorial - Authentication | CakePHP](#cms-tutorial-authentication-cakephp)
- [ビューセル | CakePHP](#-cakephp)
- [Security | CakePHP](#security-cakephp)
- [Views | CakePHP](#views-cakephp)
- [Blog Tutorial - Part 2 | CakePHP](#blog-tutorial-part-2-cakephp)
- [チュートリアルと例 | CakePHP](#-cakephp)
- [Bake コンソール - 2.x](#bake-2-x)
- [Bake でコード生成 - 2.x](#bake-2-x)
- [Chronos - 2.x](#chronos-2-x)
- [ElasticSearch - 3.x](#elasticsearch-3-x)
- [Chronos - 1.x](#chronos-1-x)
- [ElasticSearch - 2.x](#elasticsearch-2-x)
- [Bake コンソール - 1.x](#bake-1-x)
- [Migrations - 3.x](#migrations-3-x)
- [Migrations - 2.x](#migrations-2-x)
- [Debug Kit - 3.x](#debug-kit-3-x)
- [ビュー | CakePHP](#-cakephp)
- [コンテンツ管理チュートリアル | CakePHP](#-cakephp)
- [クイック スタート - 3.x](#-3-x)
- [Quick Start - 3.x](#quick-start-3-x)
- [アップグレードツール | CakePHP](#-cakephp)
- [セキュリティ | CakePHP](#-cakephp)
- [CMS チュートリアル - 認証 | CakePHP](#cms-cakephp)
- [Flash | CakePHP](#flash-cakephp)
- [Themes | CakePHP](#themes-cakephp)
- [データの検証 | CakePHP](#-cakephp)
- [プラグイン | CakePHP](#-cakephp)
- [JSON and XML views | CakePHP](#json-and-xml-views-cakephp)
- [View Cells | CakePHP](#view-cells-cakephp)
- [CMS Tutorial - Creating the Database | CakePHP](#cms-tutorial-creating-the-database-cakephp)
- [Time | CakePHP](#time-cakephp)
- [Helpers | CakePHP](#helpers-cakephp)
- [Session | CakePHP](#session-cakephp)
- [Rss | CakePHP](#rss-cakephp)
- [Plugins | CakePHP](#plugins-cakephp)
- [Number | CakePHP](#number-cakephp)
- [Text | CakePHP](#text-cakephp)
- [CMS Tutorial - Creating the Articles Controller | CakePHP](#cms-tutorial-creating-the-articles-controller-cakephp)
- [Breadcrumbs | CakePHP](#breadcrumbs-cakephp)
- [Blog Tutorial | CakePHP](#blog-tutorial-cakephp)
- [Paginator | CakePHP](#paginator-cakephp)
- [ヘルパー | CakePHP](#-cakephp)
- [Blog Tutorial - Part 3 | CakePHP](#blog-tutorial-part-3-cakephp)
- [Html | CakePHP](#html-cakephp)
- [クイックスタートガイド | CakePHP](#-cakephp)
- [Quick Start Guide | CakePHP](#quick-start-guide-cakephp)
- [Form | CakePHP](#form-cakephp)
- [CakePHP 6 (dev) Documentation - Build Better Web Applications Faster | CakePHP](#cakephp-6-dev-documentation-build-better-web-applications-faster-cakephp)
- [Welcome | CakePHP](#welcome-cakephp)
- [Welcome | CakePHP](#welcome-cakephp)
- [Url | CakePHP](#url-cakephp)
- [CakePHP の利用 | CakePHP](#cakephp-cakephp)
- [ブックマークチュートリアル | CakePHP](#-cakephp)
- [ブックマークチュートリアル パート2 | CakePHP](#-2-cakephp)
- [Phinx マイグレーション | CakePHP](#phinx-cakephp)
- [CMS チュートリアル - タグとユーザー | CakePHP](#cms-cakephp)
- [シンプルな認証と認可のアプリケーション | CakePHP](#-cakephp)
- [ブログチュートリアル - パート2 | CakePHP](#-2-cakephp)
- [CMS チュートリアル - データベース作成 | CakePHP](#cms-cakephp)
- [<no title> - 2.x](#-no-title-2-x)
- [CMS チュートリアル - Articles コントローラーの作成 | CakePHP](#cms-articles-cakephp)
- [Bake の拡張 - 2.x](#bake-2-x)
- [<no title> - 2.x](#-no-title-2-x)
- [Contents - 3.x](#contents-3-x)
- [<no title> - 1.x](#-no-title-1-x)
- [<no title> - 1.x](#-no-title-1-x)
- [<no title> - 3.x](#-no-title-3-x)
- [Contents - 2.x](#contents-2-x)
- [<no title> - 2.x](#-no-title-2-x)
- [Bake でコード生成 - 1.x](#bake-1-x)
- [Contents - 3.x](#contents-3-x)
- [<no title> - 3.x](#-no-title-3-x)
- [Contents - 3.x](#contents-3-x)
- [JSON と XML ビュー | CakePHP](#json-xml-cakephp)
- [Debug Kit - 4.x](#debug-kit-4-x)
- [Bake の拡張 - 1.x](#bake-1-x)
- [ポリシーリゾルバー - 3.x](#-3-x)
- [Policies - 3.x](#policies-3-x)
- [AuthorizationComponent - 3.x](#authorizationcomponent-3-x)
- [認可の確認 - 3.x](#-3-x)
- [認証機能 - 3.x](#-3-x)
- [リクエスト認証ミドルウェア - 3.x](#-3-x)
- [2.0 Migration Guide - 3.x](#2-0-migration-guide-3-x)
- [認可ミドルウェア - 3.x](#-3-x)
- [Identifiers - 3.x](#identifiers-3-x)
- [Identity Objects - 3.x](#identity-objects-3-x)
- [認証 Component - 3.x](#-component-3-x)
- [Password Hashers - 3.x](#password-hashers-3-x)
- [URL チェッカー - 3.x](#url-3-x)
- [認証コンポーネントから移行 - 3.x](#-3-x)
- [View Helper - 3.x](#view-helper-3-x)
- [認証によるテスト - 3.x](#-3-x)
- [クイック スタート - 2.x](#-2-x)
- [Middleware - 3.x](#middleware-3-x)
- [Quick Start - 2.x](#quick-start-2-x)
- [<no title> - 4.x](#-no-title-4-x)
- [Form Protection Component | CakePHP](#form-protection-component-cakephp)
- [Timestamp | CakePHP](#timestamp-cakephp)
- [CounterCache | CakePHP](#countercache-cakephp)
- [App Class | CakePHP](#app-class-cakephp)
- [Registry Objects | CakePHP](#registry-objects-cakephp)
- [Security Utility | CakePHP](#security-utility-cakephp)
- [Plugin Class | CakePHP](#plugin-class-cakephp)
- [Constants & Functions | CakePHP](#constants-functions-cakephp)
- [Flash | CakePHP](#flash-cakephp)
- [Inflector | CakePHP](#inflector-cakephp)
- [Cache Tool | CakePHP](#cache-tool-cakephp)
- [Request Handling | CakePHP](#request-handling-cakephp)
- [FlashHelper | CakePHP](#flashhelper-cakephp)
- [TextHelper | CakePHP](#texthelper-cakephp)
- [HtmlHelper | CakePHP](#htmlhelper-cakephp)
- [Sessions | CakePHP](#sessions-cakephp)
- [SessionHelper | CakePHP](#sessionhelper-cakephp)
- [Filesystem | CakePHP](#filesystem-cakephp)
- [Tree | CakePHP](#tree-cakephp)
- [Xml | CakePHP](#xml-cakephp)
- [Running Shells as Cron Jobs | CakePHP](#running-shells-as-cron-jobs-cakephp)
- [Security | CakePHP](#security-cakephp)
- [TimeHelper | CakePHP](#timehelper-cakephp)
- [Console Commands | CakePHP](#console-commands-cakephp)
- [I18N Tool | CakePHP](#i18n-tool-cakephp)
- [Server Tool | CakePHP](#server-tool-cakephp)
- [Schema Cache Tool | CakePHP](#schema-cache-tool-cakephp)
- [Data Sanitization | CakePHP](#data-sanitization-cakephp)
- [CakeNumber | CakePHP](#cakenumber-cakephp)
- [Inflector | CakePHP](#inflector-cakephp)
- [Deleting Data | CakePHP](#deleting-data-cakephp)
- [Timestamp | CakePHP](#timestamp-cakephp)
- [Logging | CakePHP](#logging-cakephp)
- [Text | CakePHP](#text-cakephp)
- [Translate | CakePHP](#translate-cakephp)
- [Checking HTTP Cache | CakePHP](#checking-http-cache-cakephp)
- [Command Input/Output | CakePHP](#command-input-output-cakephp)
- [Pagination | CakePHP](#pagination-cakephp)
- [Folder & File | CakePHP](#folder-file-cakephp)
- [App Class | CakePHP](#app-class-cakephp)
- [CounterCache | CakePHP](#countercache-cakephp)
- [Schema System | CakePHP](#schema-system-cakephp)
- [Flash | CakePHP](#flash-cakephp)
- [Security | CakePHP](#security-cakephp)
- [Date & Time | CakePHP](#date-time-cakephp)
- [Http Client | CakePHP](#http-client-cakephp)
- [RssHelper | CakePHP](#rsshelper-cakephp)
- [CakeTime | CakePHP](#caketime-cakephp)
- [Code Generation with Bake | CakePHP](#code-generation-with-bake-cakephp)
- [Test shell | CakePHP](#test-shell-cakephp)
- [Development | CakePHP](#development-cakephp)
- [PaginatorHelper | CakePHP](#paginatorhelper-cakephp)
- [Events System | CakePHP](#events-system-cakephp)
- [Mailer | CakePHP](#mailer-cakephp)
- [Security | CakePHP](#security-cakephp)
- [ACL Shell | CakePHP](#acl-shell-cakephp)
- [Upgrade shell | CakePHP](#upgrade-shell-cakephp)
- [Completion Shell | CakePHP](#completion-shell-cakephp)
- [HttpSocket | CakePHP](#httpsocket-cakephp)
- [App Class | CakePHP](#app-class-cakephp)
- [Content Security Policy Middleware | CakePHP](#content-security-policy-middleware-cakephp)
- [NumberHelper | CakePHP](#numberhelper-cakephp)
- [Components | CakePHP](#components-cakephp)
- [REST | CakePHP](#rest-cakephp)
- [Validation | CakePHP](#validation-cakephp)
- [Internationalization & Localization | CakePHP](#internationalization-localization-cakephp)
- [Command Objects | CakePHP](#command-objects-cakephp)
- [Sessions | CakePHP](#sessions-cakephp)
- [Configuration | CakePHP](#configuration-cakephp)

---

# Welcome | CakePHP

[Skip to content](https://book.cakephp.org/3.x#VPContent)

On this page

Welcome [​](https://book.cakephp.org/3.x#welcome)

==================================================

Unsupported Version

You are viewing documentation for an **unsupported version** of CakePHP. For the most recent stable version, please visit the [official documentation](https://book.cakephp.org/)
.

CakePHP 3 is a web development framework running on PHP **7.4** (min. PHP _5.6_). Read [CakePHP at a Glance](https://book.cakephp.org/intro.html)
 to get an introduction to the fundamentals of CakePHP 3.

The CakePHP cookbook is an openly developed and community editable documentation project. Notice the pencil icon button fixated against the right wall; it will direct you to the GitHub online editor of the active page, allowing you to contribute any additions, deletions, or corrections to the documentation.

**Read the Book Anywhere**

![image](https://book.cakephp.org/3.x/read-the-book.jpg)

Enjoy the CakePHP cookbook almost anywhere. Available as both a PDF and EPUB, you can now read it on more devices, as well as offline.

*   [PDF](https://book.cakephp.org/_downloads/en/CakePHPBook.pdf)
    
*   [EPUB](https://book.cakephp.org/_downloads/en/CakePHP.epub)
    
*   [Original Source](https://github.com/cakephp/docs)
    

Getting Help [​](https://book.cakephp.org/3.x#getting-help)

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

If you're stuck, there are a number of places [you can get help](https://book.cakephp.org/intro/where-to-get-help.html)
.

First Steps [​](https://book.cakephp.org/3.x#first-steps)

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

Learning a new framework can be intimidating and exciting at the same time. To help you along, we have created a cookbook packed with examples and recipes to get the common tasks completed. If you are new, you should start off with the [Quick Start Guide](https://book.cakephp.org/quickstart.html)
 as it will give you a quick tour of what CakePHP has to offer and how it works.

After you've finished the Quickstart tutorial, you can brush up on the key elements in a CakePHP application:

*   The [CakePHP request cycle](https://book.cakephp.org/intro.html#request-cycle)
    
*   The [conventions](https://book.cakephp.org/intro/conventions.html)
     that CakePHP uses.
*   [Controllers](https://book.cakephp.org/controllers.html)
     handle requests and co-ordinate your models and the responses your application creates.
*   [Views](https://book.cakephp.org/views.html)
     are the presentation layer in your application. They give you powerful tools to create HTML, JSON and the other outputs your application needs.
*   [Models](https://book.cakephp.org/orm.html)
     are the key ingredient in any application. They handle validation, and domain logic within your application.

---

# Not Found | CakePHP

[Skip to content](https://book.cakephp.org/3.x/404.html#VPContent)

Return to top

orphan  
True

Not Found [​](https://book.cakephp.org/3.x/404.html#not-found)

===============================================================

The page you're looking for cannot be found. Try using the search bar to find what you're looking for.

---

# ページが見つかりません。 | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/404.html#VPContent)

Return to top

orphan  
True

ページが見つかりません。 [​](https://book.cakephp.org/3.x/ja/404.html#%E3%83%98%E3%82%9A%E3%83%BC%E3%82%B7%E3%82%99%E3%81%8B%E3%82%99%E8%A6%8B%E3%81%A4%E3%81%8B%E3%82%8A%E3%81%BE%E3%81%9B%E3%82%93%E3%80%82)

===================================================================================================================================================================================================

お探しのページが見つかりません。お探しのページを見つけるために検索バーをお試しください。

---

# Appendices | CakePHP

[Skip to content](https://book.cakephp.org/3.x/appendices.html#VPContent)

On this page

Appendices [​](https://book.cakephp.org/3.x/appendices.html#appendices)

========================================================================

Appendices contain information regarding the new features introduced in each version and the migration path between versions.

3.x Migration Guide [​](https://book.cakephp.org/3.x/appendices.html#_3-x-migration-guide)

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

*   [3.x Migration Guide](https://book.cakephp.org/3.x/appendices/3-x-migration-guide.html)
    

Forwards Compatibility Shimming [​](https://book.cakephp.org/3.x/appendices.html#forwards-compatibility-shimming)

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

FC shimming can prepare your 3.x app for the next major release (4.x).

If you already want to shim 4.x behavior in 3.x, check out the [Shim plugin](https://github.com/dereuromark/cakephp-shim)
 that can help mitigate some BC breaking changes. The closer your 3.x app is to 4.x, the smaller will be the diff of changes, and the smoother will be the final upgrade.

General Information [​](https://book.cakephp.org/3.x/appendices.html#general-information)

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

*   [CakePHP Development Process](https://book.cakephp.org/3.x/appendices/cakephp-development-process.html)
    
*   [Glossary](https://book.cakephp.org/3.x/appendices/glossary.html)

---

# 付録 | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/appendices.html#VPContent)

On this page

付録 [​](https://book.cakephp.org/3.x/ja/appendices.html#%E4%BB%98%E9%8C%B2)

===========================================================================

ここでは、各バージョンで導入された新機能に関する情報と、 バージョン間の移行手順を解説します。

3.x 移行ガイド [​](https://book.cakephp.org/3.x/ja/appendices.html#_3-x-%E7%A7%BB%E8%A1%8C%E3%82%AB%E3%82%99%E3%82%A4%E3%83%88%E3%82%99)

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

*   [3.x 移行ガイド](https://book.cakephp.org/3.x/ja/appendices/3-x-migration-guide.html)
    

一般的な情報 [​](https://book.cakephp.org/3.x/ja/appendices.html#%E4%B8%80%E8%88%AC%E7%9A%84%E3%81%AA%E6%83%85%E5%A0%B1)

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

*   [CakePHP の開発プロセス](https://book.cakephp.org/3.x/ja/appendices/cakephp-development-process.html)
    
*   [用語集](https://book.cakephp.org/3.x/ja/appendices/glossary.html)

---

# Url | CakePHP

[Skip to content](https://book.cakephp.org/3.x/views/helpers/url.html#VPContent)

Return to top

Url [​](https://book.cakephp.org/3.x/views/helpers/url.html#url)

=================================================================

`class` Cake\\View\\Helper\\**UrlHelper**(View $view, array $config = \[\])

The UrlHelper makes it easy for you to generate URLs from your other helpers. It also gives you a single place to customize how URLs are generated by overriding the core helper with an application one. See the [Aliasing Helpers](https://book.cakephp.org/3.x/views/helpers.html#aliasing-helpers)
 section for how to do this.

Generating URLs [​](https://book.cakephp.org/3.x/views/helpers/url.html#generating-urls)

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

`method` Cake\\View\\Helper\\UrlHelper::**build**(mixed $url = null, boolean|array $full = false)

Returns a URL pointing to a combination of controller and action. If `$url` is empty, it returns the `REQUEST_URI`, otherwise it generates the URL for the controller and action combo. If `full` is `true`, the full base URL will be prepended to the result:

    echo $this->Url->build([\
        "controller" => "Posts",\
        "action" => "view",\
        "bar",\
    ]);
    
    // Output
    /posts/view/bar

1  
2  
3  
4  
5  
6  
7  
8  

Here are a few more usage examples:

URL with extension:

    echo $this->Url->build([\
        "controller" => "Posts",\
        "action" => "list",\
        "_ext" => "rss",\
    ]);
    
    // Output
    /posts/list.rss

1  
2  
3  
4  
5  
6  
7  
8  

URL (starting with '/') with the full base URL prepended:

    echo $this->Url->build('/posts', true);
    
    // Output
    http://somedomain.com/posts

1  
2  
3  
4  

URL with GET parameters and fragment anchor:

    echo $this->Url->build([\
        "controller" => "Posts",\
        "action" => "search",\
        "?" => ["foo" => "bar"],\
        "#" => "first",\
    ]);
    
    // Output
    /posts/search?foo=bar#first

1  
2  
3  
4  
5  
6  
7  
8  
9  

The above example uses the `?` key which is useful when you want to be explicit about the query string parameters you are using, or if you want a query string parameter that shares a name with one of your route placeholders.

URL for named route:

    // Assuming a route is setup as a named route:
    // $router->connect(
    //     '/products/:slug',
    //     [\
    //         'controller' => 'Products',\
    //         'action' => 'view',\
    //     ],
    //     [\
    //         '_name' => 'product-page',\
    //     ]
    // );
    
    echo $this->Url->build(['_name' => 'product-page', 'slug' => 'i-m-slug']);
    // Will result in:
    /products/i-m-slug

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

The 2nd parameter allows you to define options controlling HTML escaping, and whether or not the base path should be added:

    $this->Url->build('/posts', [\
        'escape' => false,\
        'fullBase' => true,\
    ]);

1  
2  
3  
4  

URL with asset timestamp wrapped by a `<link rel="preload"/>`, here pre-loading a font. Note: The file must exist and `Configure::read('Asset.timestamp')` must return `true` or `'force'` for the timestamp to be appended:

    echo $this->Html->meta([\
        'rel' => 'preload',\
        'href' => $this->Url->assetUrl(\
            '/assets/fonts/yout-font-pack/your-font-name.woff2'\
        ),\
        'as' => 'font',\
    ]);

1  
2  
3  
4  
5  
6  
7  

Added in version 3.3.5

`build()` accepts an array as the 2nd argument as of 3.3.5

Added in version 3.6.0

The `timestamp` option was added to `build()`.

If you are generating URLs for CSS, Javascript or image files there are helper methods for each of these asset types:

    // Outputs /img/icon.png
    $this->Url->image('icon.png');
    
    // Outputs /js/app.js
    $this->Url->script('app.js');
    
    // Outputs /css/app.css
    $this->Url->css('app.css');
    
    // Force timestamps for one method call.
    $this->Url->css('app.css', ['timestamp' => 'force']);
    
    // Or disable timestamps for one method call.
    $this->Url->css('app.css', ['timestamp' => false]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

Added in version 3.2.4

The asset helper methods were added in 3.2.4.

Added in version 3.6.0

The `timestamp` option was added to asset helper methods.

For further information check [Router::url](https://api.cakephp.org/3.x/class-Cake.Routing.Router.html#_url)
 in the API.

---

# Tutorials & Examples | CakePHP

[Skip to content](https://book.cakephp.org/3.x/tutorials-and-examples.html#VPContent)

Return to top

Tutorials & Examples [​](https://book.cakephp.org/3.x/tutorials-and-examples.html#tutorials-examples)

======================================================================================================

In this section, you can walk through typical CakePHP applications to see how all of the pieces come together.

Alternatively, you can refer to the non-official CakePHP plugin repository [CakePackages](https://plugins.cakephp.org/)
 and the [Bakery](https://bakery.cakephp.org/)
 for existing applications and components.

*   [Content Management Tutorial](https://book.cakephp.org/3.x/tutorials-and-examples/cms/installation.html)
    
*   [CMS Tutorial - Creating the Database](https://book.cakephp.org/3.x/tutorials-and-examples/cms/database.html)
    
*   [CMS Tutorial - Creating the Articles Controller](https://book.cakephp.org/3.x/tutorials-and-examples/cms/articles-controller.html)
    
*   [CMS Tutorial - Tags and Users](https://book.cakephp.org/3.x/tutorials-and-examples/cms/tags-and-users.html)
    
*   [CMS Tutorial - Authentication](https://book.cakephp.org/3.x/tutorials-and-examples/cms/authentication.html)

---

# Using CakePHP | CakePHP

[Skip to content](https://book.cakephp.org/3.x/topics.html#VPContent)

Return to top

Using CakePHP [​](https://book.cakephp.org/3.x/topics.html#using-cakephp)

==========================================================================

Introduction to all the key parts of CakePHP:

*   [Installation](https://book.cakephp.org/3.x/installation.html)
    
*   [Configuration](https://book.cakephp.org/3.x/development/configuration.html)
    
*   [Routing](https://book.cakephp.org/3.x/development/routing.html)
    
*   [Request & Response Objects](https://book.cakephp.org/3.x/controllers/request-response.html)
    
*   [Controllers](https://book.cakephp.org/3.x/controllers.html)
    
*   [Components](https://book.cakephp.org/3.x/controllers/components.html)
    
*   [The Pages Controller](https://book.cakephp.org/3.x/controllers/pages-controller.html)
    
*   [Views](https://book.cakephp.org/3.x/views.html)
    
*   [View Cells](https://book.cakephp.org/3.x/views/cells.html)
    
*   [Helpers](https://book.cakephp.org/3.x/views/helpers.html)
    
*   [JSON and XML views](https://book.cakephp.org/3.x/views/json-and-xml-views.html)
    
*   [Database Access & ORM](https://book.cakephp.org/3.x/orm.html)
    
*   [Table Objects](https://book.cakephp.org/3.x/orm/table-objects.html)
    
*   [Query Builder](https://book.cakephp.org/3.x/orm/query-builder.html)
    
*   [Entities](https://book.cakephp.org/3.x/orm/entities.html)
    
*   [Error & Exception Handling](https://book.cakephp.org/3.x/development/errors.html)
    
*   [Caching](https://book.cakephp.org/3.x/core-libraries/caching.html)
    
*   [Logging](https://book.cakephp.org/3.x/core-libraries/logging.html)
    
*   [Modelless Forms](https://book.cakephp.org/3.x/core-libraries/form.html)
    
*   [Sessions](https://book.cakephp.org/3.x/development/sessions.html)
    
*   [REST](https://book.cakephp.org/3.x/development/rest.html)
    
*   [AuthComponent](https://book.cakephp.org/3.x/controllers/components/authentication.html)
    
*   [Pagination](https://book.cakephp.org/3.x/controllers/components/pagination.html)
    
*   [Cross Site Request Forgery](https://book.cakephp.org/3.x/controllers/components/csrf.html)
    
*   [Email](https://book.cakephp.org/3.x/core-libraries/email.html)
    
*   [Form](https://book.cakephp.org/3.x/views/helpers/form.html)
    
*   [Html](https://book.cakephp.org/3.x/views/helpers/html.html)
    
*   [Validation](https://book.cakephp.org/3.x/core-libraries/validation.html)
    
*   [Testing](https://book.cakephp.org/3.x/development/testing.html)
    
*   [Deployment](https://book.cakephp.org/3.x/deployment.html)
    
*   [Console Tools, Shells & Tasks](https://book.cakephp.org/3.x/console-and-shells.html)
    
*   [Contributing](https://book.cakephp.org/3.x/contributing.html)
    
*   [Tutorials & Examples](https://book.cakephp.org/3.x/tutorials-and-examples.html)

---

# Bookmarker Tutorial | CakePHP

[Skip to content](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/intro.html#VPContent)

Return to top

Bookmarker Tutorial [​](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/intro.html#bookmarker-tutorial)

======================================================================================================================

This tutorial will walk you through the creation of a simple bookmarking application (bookmarker). To start with, we'll be installing CakePHP, creating our database, and using the tools CakePHP provides to get our application up fast.

Here's what you'll need:

1.  A database server. We're going to be using MySQL server in this tutorial. You'll need to know enough about SQL in order to create a database: CakePHP will be taking the reins from there. Since we're using MySQL, also make sure that you have `pdo_mysql` enabled in PHP.
2.  Basic PHP knowledge.

Before starting you should make sure that you have got an up to date PHP version:

    php -v

1  

You should at least have got installed PHP _5.6_ (CLI) or higher. Your webserver's PHP version must also be of _5.6_ or higher, and should best be the same version your command line interface (CLI) PHP version is of. If you'd like to see the completed application, checkout [cakephp/bookmarker](https://github.com/cakephp/bookmarker-tutorial)
. Let's get started!

Getting CakePHP [​](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/intro.html#getting-cakephp)

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

The easiest way to install CakePHP is to use Composer. Composer is a simple way of installing CakePHP from your terminal or command line prompt. First, you'll need to download and install Composer if you haven't done so already. If you have cURL installed, it's as easy as running the following:

    curl -s https://getcomposer.org/installer | php
    

Or, you can download `composer.phar` from the [Composer website](https://getcomposer.org/download/)
.

Then simply type the following line in your terminal from your installation directory to install the CakePHP application skeleton in the **bookmarker** directory:

    php composer.phar create-project --prefer-dist cakephp/app:"^3.10" bookmarker
    

If you downloaded and ran the [Composer Windows Installer](https://getcomposer.org/Composer-Setup.exe)
, then type the following line in your terminal from your installation directory (ie. C:\\wamp\\www\\dev\\cakephp3):

    composer self-update && composer create-project --prefer-dist cakephp/app:"^3.10" bookmarker
    

The advantage to using Composer is that it will automatically complete some important set up tasks, such as setting the correct file permissions and creating your **config/app.php** file for you.

There are other ways to install CakePHP. If you cannot or don't want to use Composer, check out the [Installation](https://book.cakephp.org/3.x/installation.html)
 section.

Regardless of how you downloaded and installed CakePHP, once your set up is completed, your directory setup should look something like the following:

    /bookmarker
        /bin
        /config
        /logs
        /plugins
        /src
        /tests
        /tmp
        /vendor
        /webroot
        .editorconfig
        .gitignore
        .htaccess
        .travis.yml
        composer.json
        index.php
        phpunit.xml.dist
        README.md
    

Now might be a good time to learn a bit about how CakePHP's directory structure works: check out the [CakePHP Folder Structure](https://book.cakephp.org/3.x/intro/cakephp-folder-structure.html)
 section.

Checking our Installation [​](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/intro.html#checking-our-installation)

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

We can quickly check that our installation is correct, by checking the default home page. Before you can do that, you'll need to start the development server:

    bin/cake server
    

NOTE

For Windows, the command needs to be `bin\cake server` (note the backslash).

This will start PHP's built-in webserver on port 8765. Open up **[http://localhost:8765](http://localhost:8765/)
** in your web browser to see the welcome page. All the bullet points should be checkmarks other than CakePHP being able to connect to your database. If not, you may need to install additional PHP extensions, or set directory permissions.

Creating the Database [​](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/intro.html#creating-the-database)

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

Next, let's set up the database for our bookmarking application. If you haven't already done so, create an empty database for use in this tutorial, with a name of your choice, e.g. `cake_bookmarks`. You can execute the following SQL to create the necessary tables:

    CREATE TABLE users (
        id INT AUTO_INCREMENT PRIMARY KEY,
        email VARCHAR(255) NOT NULL,
        password VARCHAR(255) NOT NULL,
        created DATETIME,
        modified DATETIME
    );
    
    CREATE TABLE bookmarks (
        id INT AUTO_INCREMENT PRIMARY KEY,
        user_id INT NOT NULL,
        title VARCHAR(50),
        description TEXT,
        url TEXT,
        created DATETIME,
        modified DATETIME,
        FOREIGN KEY user_key (user_id) REFERENCES users(id)
    );
    
    CREATE TABLE tags (
        id INT AUTO_INCREMENT PRIMARY KEY,
        title VARCHAR(255),
        created DATETIME,
        modified DATETIME,
        UNIQUE KEY (title)
    );
    
    CREATE TABLE bookmarks_tags (
        bookmark_id INT NOT NULL,
        tag_id INT NOT NULL,
        PRIMARY KEY (bookmark_id, tag_id),
        FOREIGN KEY tag_key(tag_id) REFERENCES tags(id),
        FOREIGN KEY bookmark_key(bookmark_id) REFERENCES bookmarks(id)
    );

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  

You may have noticed that the `bookmarks_tags` table used a composite primary key. CakePHP supports composite primary keys almost everywhere, making it easier to build multi-tenanted applications.

The table and column names we used were not arbitrary. By using CakePHP's [naming conventions](https://book.cakephp.org/3.x/intro/conventions.html)
, we can leverage CakePHP better and avoid having to configure the framework. CakePHP is flexible enough to accommodate even inconsistent legacy database schemas, but adhering to the conventions will save you time.

Database Configuration [​](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/intro.html#database-configuration)

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

Next, let's tell CakePHP where our database is and how to connect to it. For many, this will be the first and last time you will need to configure anything.

The configuration should be pretty straightforward: just replace the values in the `Datasources.default` array in the **config/app.php** file with those that apply to your setup. A sample completed configuration array might look something like the following:

    return [\
        // More configuration above.\
        'Datasources' => [\
            'default' => [\
                'className' => 'Cake\Database\Connection',\
                'driver' => 'Cake\Database\Driver\Mysql',\
                'persistent' => false,\
                'host' => 'localhost',\
                'username' => 'cakephp',\
                'password' => 'AngelF00dC4k3~',\
                'database' => 'cake_bookmarks',\
                'encoding' => 'utf8',\
                'timezone' => 'UTC',\
                'cacheMetadata' => true,\
            ],\
        ],\
        // More configuration below.\
    ];

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

Once you've saved your **config/app.php** file, you should see that 'CakePHP is able to connect to the database' section have a checkmark.

NOTE

A copy of CakePHP's default configuration file is found in **config/app.default.php**.

Generating Scaffold Code [​](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/intro.html#generating-scaffold-code)

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

Because our database is following the CakePHP conventions, we can use the [bake console](https://book.cakephp.org/3.x/bake/usage.html)
 application to quickly generate a basic application. In your command line run the following commands:

    // On Windows you'll need to use bin\cake instead.
    bin/cake bake all users
    bin/cake bake all bookmarks
    bin/cake bake all tags

1  
2  
3  
4  

This will generate the controllers, models, views, their corresponding test cases, and fixtures for our users, bookmarks and tags resources. If you've stopped your server, restart it and go to **[http://localhost:8765/bookmarks](http://localhost:8765/bookmarks)
**.

You should see a basic but functional application providing data access to your application's database tables. Once you're at the list of bookmarks, add a few users, bookmarks, and tags.

Adding Password Hashing [​](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/intro.html#adding-password-hashing)

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

When you created your users (by visiting **[http://localhost:8765/users](http://localhost:8765/users)
**), you probably noticed that the passwords were stored in plain text. This is pretty bad from a security point of view, so let's get that fixed.

This is also a good time to talk about the model layer in CakePHP. In CakePHP, we separate the methods that operate on a collection of objects, and a single object into different classes. Methods that operate on the collection of entities are put in the `Table` class, while features belonging to a single record are put on the `Entity` class.

For example, password hashing is done on the individual record, so we'll implement this behavior on the entity object. Because, we want to hash the password each time it is set, we'll use a mutator/setter method. CakePHP will call convention based setter methods any time a property is set in one of your entities. Let's add a setter for the password. In **src/Model/Entity/User.php** add the following:

    namespace App\Model\Entity;
    
    use Cake\Auth\DefaultPasswordHasher; //include this line
    use Cake\ORM\Entity;
    
    class User extends Entity
    {
        // Code from bake.
    
        protected function _setPassword($value)
        {
            $hasher = new DefaultPasswordHasher();
            return $hasher->hash($value);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

Now update one of the users you created earlier, if you change their password, you should see a hashed password instead of the original value on the list or view pages. CakePHP hashes passwords with [bcrypt](https://codahale.com/how-to-safely-store-a-password/)
 by default. You can also use sha1 or md5 if you're working with an existing database.

NOTE

If the password doesn't get hashed, make sure you followed the same case for the password member of the class while naming the setter function

Getting Bookmarks with a Specific Tag [​](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/intro.html#getting-bookmarks-with-a-specific-tag)

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

Now that we're storing passwords safely, we can build out some more interesting features in our application. Once you've amassed a collection of bookmarks, it is helpful to be able to search through them by tag. Next we'll implement a route, controller action, and finder method to search through bookmarks by tag.

Ideally, we'd have a URL that looks like **[http://localhost:8765/bookmarks/tagged/funny/cat/gifs](http://localhost:8765/bookmarks/tagged/funny/cat/gifs)
**. This would let us find all the bookmarks that have the 'funny', 'cat' or 'gifs' tags. Before we can implement this, we'll add a new route. Your **config/routes.php** should look like:

    <?php
    use Cake\Routing\Route\DashedRoute;
    use Cake\Routing\Router;
    
    Router::defaultRouteClass(DashedRoute::class);
    
    // New route we're adding for our tagged action.
    // The trailing `*` tells CakePHP that this action has
    // passed parameters.
    Router::scope(
        '/bookmarks',
        ['controller' => 'Bookmarks'],
        function ($routes) {
            $routes->connect('/tagged/*', ['action' => 'tags']);
        }
    );
    
    Router::scope('/', function ($routes) {
        // Connect the default home and /pages/* routes.
        $routes->connect('/', [\
            'controller' => 'Pages',\
            'action' => 'display', 'home'\
        ]);
        $routes->connect('/pages/*', [\
            'controller' => 'Pages',\
            'action' => 'display'\
        ]);
    
        // Connect the conventions based default routes.
        $routes->fallbacks();
    });

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  

The above defines a new 'route' which connects the **/bookmarks/tagged/** path, to `BookmarksController::tags()`. By defining routes, you can isolate how your URLs look, from how they are implemented. If we were to visit **[http://localhost:8765/bookmarks/tagged](http://localhost:8765/bookmarks/tagged)
**, we would see a helpful error page from CakePHP informing you that the controller action does not exist. Let's implement that missing method now. In **src/Controller/BookmarksController.php** add the following:

    public function tags()
    {
        // The 'pass' key is provided by CakePHP and contains all
        // the passed URL path segments in the request.
        $tags = $this->request->getParam('pass');
    
        // Use the BookmarksTable to find tagged bookmarks.
        $bookmarks = $this->Bookmarks->find('tagged', [\
            'tags' => $tags\
        ]);
    
        // Pass variables into the view template context.
        $this->set([\
            'bookmarks' => $bookmarks,\
            'tags' => $tags\
        ]);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

To access other parts of the request data, consult the [Cake Request](https://book.cakephp.org/3.x/controllers/request-response.html#cake-request)
 section.

### Creating the Finder Method [​](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/intro.html#creating-the-finder-method)

In CakePHP we like to keep our controller actions slim, and put most of our application's logic in the models. If you were to visit the **/bookmarks/tagged** URL now you would see an error that the `findTagged()` method has not been implemented yet, so let's do that. In **src/Model/Table/BookmarksTable.php** add the following:

    // The $query argument is a query builder instance.
    // The $options array will contain the 'tags' option we passed
    // to find('tagged') in our controller action.
    public function findTagged(Query $query, array $options)
    {
        $bookmarks = $this->find()
            ->select(['id', 'url', 'title', 'description']);
    
        if (empty($options['tags'])) {
            $bookmarks
                ->leftJoinWith('Tags')
                ->where(['Tags.title IS' => null]);
        } else {
            $bookmarks
                ->innerJoinWith('Tags')
                ->where(['Tags.title IN ' => $options['tags']]);
        }
    
        return $bookmarks->group(['Bookmarks.id']);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  

We just implemented a [custom finder method](https://book.cakephp.org/3.x/orm/retrieving-data-and-resultsets.html#custom-find-methods)
. This is a very powerful concept in CakePHP that allows you to package up re-usable queries. Finder methods always get a [Query Builder](https://book.cakephp.org/3.x/orm/query-builder.html)
 object and an array of options as parameters. Finders can manipulate the query and add any required conditions or criteria. When complete, finder methods must return a modified query object. In our finder we've leveraged the `innerJoinWith()`, `where()` and `group()` methods which allow us to find distinct bookmarks that have a matching tag. When no tags are provided we use a `leftJoinWith()` and modify the 'where' condition, finding bookmarks without tags.

### Creating the View [​](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/intro.html#creating-the-view)

Now if you visit the **/bookmarks/tagged** URL, CakePHP will show an error letting you know that you have not made a view file. Next, let's build the view file for our `tags()` action. In **src/Template/Bookmarks/tags.ctp** put the following content:

    <h1>
        Bookmarks tagged with
        <?= $this->Text->toList(h($tags)) ?>
    </h1>
    
    <section>
    <?php foreach ($bookmarks as $bookmark): ?>
        <article>
            <!-- Use the HtmlHelper to create a link -->
            <h4><?= $this->Html->link($bookmark->title, $bookmark->url) ?></h4>
            <small><?= h($bookmark->url) ?></small>
    
            <!-- Use the TextHelper to format text -->
            <?= $this->Text->autoParagraph(h($bookmark->description)) ?>
        </article>
    <?php endforeach; ?>
    </section>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

In the above code we use the [Html](https://book.cakephp.org/3.x/views/helpers/html.html)
 and [Text](https://book.cakephp.org/3.x/views/helpers/text.html)
 helpers to assist in generating our view output. We also use the `h` shortcut function to HTML encode output. You should remember to always use `h()` when outputting user data to prevent HTML injection issues.

The **tags.ctp** file we just created follows the CakePHP conventions for view template files. The convention is to have the template use the lower case and underscored version of the controller action name.

You may notice that we were able to use the `$tags` and `$bookmarks` variables in our view. When we use the `set()` method in our controller, we set specific variables to be sent to the view. The view will make all passed variables available in the templates as local variables.

You should now be able to visit the **/bookmarks/tagged/funny** URL and see all the bookmarks tagged with 'funny'.

So far, we've created a basic application to manage bookmarks, tags and users. However, everyone can see everyone else's tags. In the next chapter, we'll implement authentication and restrict the visible bookmarks to only those that belong to the current user.

Now continue to [Bookmarker Tutorial Part 2](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/part-two.html)
 to continue building your application or [dive into the documentation](https://book.cakephp.org/3.x/topics.html)
 to learn more about what CakePHP can do for you.

---

# Bookmarker Tutorial Part 2 | CakePHP

[Skip to content](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/part-two.html#VPContent)

Return to top

Bookmarker Tutorial Part 2 [​](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/part-two.html#bookmarker-tutorial-part-2)

=======================================================================================================================================

After finishing [the first part of this tutorial](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/intro.html)
 you should have a very basic bookmarking application. In this chapter we'll be adding authentication and restricting the bookmarks each user can see/modify to only the ones they own.

Adding Login [​](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/part-two.html#adding-login)

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

In CakePHP, authentication is handled by [Components](https://book.cakephp.org/3.x/controllers/components.html)
. Components can be thought of as ways to create reusable chunks of controller code related to a specific feature or concept. Components can also hook into the controller's event life-cycle and interact with your application that way. To get started, we'll add the [AuthComponent](https://book.cakephp.org/3.x/controllers/components/authentication.html)
 to our application. We'll pretty much want every method to require authentication, so we'll add AuthComponent in our AppController:

    // In src/Controller/AppController.php
    namespace App\Controller;
    
    use Cake\Controller\Controller;
    
    class AppController extends Controller
    {
        public function initialize()
        {
            $this->loadComponent('Flash');
            $this->loadComponent('Auth', [\
                'authenticate' => [\
                    'Form' => [\
                        'fields' => [\
                            'username' => 'email',\
                            'password' => 'password'\
                        ]\
                    ]\
                ],\
                'loginAction' => [\
                    'controller' => 'Users',\
                    'action' => 'login'\
                ],\
                'unauthorizedRedirect' => $this->referer() // If unauthorized, return them to page they were just on\
            ]);
    
            // Allow the display action so our pages controller
            // continues to work.
            $this->Auth->allow(['display']);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  

We've just told CakePHP that we want to load the `Flash` and `Auth` components. In addition, we've customized the configuration of AuthComponent, as our users table uses `email` as the username. Now, if you go to any URL you'll be kicked to **/users/login**, which will show an error page as we have not written that code yet. So let's create the login action:

    // In src/Controller/UsersController.php
    public function login()
    {
        if ($this->request->is('post')) {
            $user = $this->Auth->identify();
            if ($user) {
                $this->Auth->setUser($user);
                return $this->redirect($this->Auth->redirectUrl());
            }
            $this->Flash->error('Your username or password is incorrect.');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

And in **src/Template/Users/login.ctp** add the following:

    <h1>Login</h1>
    <?= $this->Form->create() ?>
    <?= $this->Form->control('email') ?>
    <?= $this->Form->control('password') ?>
    <?= $this->Form->button('Login') ?>
    <?= $this->Form->end() ?>

1  
2  
3  
4  
5  
6  

NOTE

The `control()` method is available since 3.4. For prior versions you can use the `input()` method instead.

Now that we have a simple login form, we should be able to log in with one of the users that has a hashed password.

NOTE

If none of your users have hashed passwords, comment the `loadComponent('Auth')` line. Then go and edit the user, saving a new password for them.

Adding Logout [​](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/part-two.html#adding-logout)

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

Now that people can log in, you'll probably want to provide a way to log out as well. Again, in the `UsersController`, add the following code:

    public function initialize()
    {
        parent::initialize();
        $this->Auth->allow(['logout']);
    }
    
    public function logout()
    {
        $this->Flash->success('You are now logged out.');
        return $this->redirect($this->Auth->logout());
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

This code whitelists the `logout` action as a public action, and implements the logout method. Now you can visit `/users/logout` to log out. You should then be sent to the login page.

Enabling Registrations [​](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/part-two.html#enabling-registrations)

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

If you aren't logged in and you try to visit **/users/add** you will be kicked to the login page. We should fix that as we want to allow people to sign up for our application. In the `UsersController` add the following:

    public function initialize()
    {
        parent::initialize();
        // Add the 'add' action to the allowed actions list.
        $this->Auth->allow(['logout', 'add']);
    }

1  
2  
3  
4  
5  
6  

The above tells `AuthComponent` that the `add()` action does _not_ require authentication or authorization. You may want to take the time to clean up the **Users/add.ctp** and remove the misleading links, or continue on to the next section. We won't be building out user editing, viewing or listing in this tutorial so they will not work as `AuthComponent` will deny you access to those controller actions.

Restricting Bookmark Access [​](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/part-two.html#restricting-bookmark-access)

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

Now that users can log in, we'll want to limit the bookmarks they can see to the ones they made. We'll do this using an 'authorization' adapter. Since our requirements are pretty simple, we can write some simple code in our `BookmarksController`. But before we do that, we'll want to tell the AuthComponent how our application is going to authorize actions. In your `AppController` add the following:

    public function isAuthorized($user)
    {
        return false;
    }

1  
2  
3  
4  

Also, add the following to the configuration for `Auth` in your `AppController`:

    'authorize' => 'Controller',

1  

Your `initialize()` method should now look like:

    public function initialize()
    {
        $this->loadComponent('Flash');
        $this->loadComponent('Auth', [\
            'authorize'=> 'Controller',//added this line\
            'authenticate' => [\
                'Form' => [\
                    'fields' => [\
                        'username' => 'email',\
                        'password' => 'password'\
                    ]\
                ]\
            ],\
            'loginAction' => [\
                'controller' => 'Users',\
                'action' => 'login'\
            ],\
            'unauthorizedRedirect' => $this->referer()\
        ]);
    
        // Allow the display action so our pages controller
        // continues to work.
        $this->Auth->allow(['display']);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  

We'll default to denying access, and incrementally grant access where it makes sense. First, we'll add the authorization logic for bookmarks. In your `BookmarksController` add the following:

    public function isAuthorized($user)
    {
        $action = $this->request->getParam('action');
    
        // The add and index actions are always allowed.
        if (in_array($action, ['index', 'add', 'tags'])) {
            return true;
        }
        // All other actions require an id.
        if (!$this->request->getParam('pass.0')) {
            return false;
        }
    
        // Check that the bookmark belongs to the current user.
        $id = $this->request->getParam('pass.0');
        $bookmark = $this->Bookmarks->get($id);
        if ($bookmark->user_id == $user['id']) {
            return true;
        }
        return parent::isAuthorized($user);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  

Now if you try to view, edit or delete a bookmark that does not belong to you, you should be redirected back to the page you came from. If no error message is displayed, add the following to your layout:

    // In src/Template/Layout/default.ctp
    <?= $this->Flash->render() ?>

1  
2  

You should now see the authorization error messages.

Fixing List view and Forms [​](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/part-two.html#fixing-list-view-and-forms)

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

While view and delete are working, edit, add and index have a few problems:

1.  When adding a bookmark you can choose the user.
2.  When editing a bookmark you can choose the user.
3.  The list page shows bookmarks from other users.

Let's tackle the add form first. To begin with remove the `control('user_id')` from **src/Template/Bookmarks/add.ctp**. With that removed, we'll also update the `add()` action from **src/Controller/BookmarksController.php** to look like:

    public function add()
    {
        $bookmark = $this->Bookmarks->newEntity();
        if ($this->request->is('post')) {
            $bookmark = $this->Bookmarks->patchEntity($bookmark, $this->request->getData());
            $bookmark->user_id = $this->Auth->user('id');
            if ($this->Bookmarks->save($bookmark)) {
                $this->Flash->success('The bookmark has been saved.');
                return $this->redirect(['action' => 'index']);
            }
            $this->Flash->error('The bookmark could not be saved. Please, try again.');
        }
        $tags = $this->Bookmarks->Tags->find('list');
        $this->set(compact('bookmark', 'tags'));
        $this->set('_serialize', ['bookmark']);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  

By setting the entity property with the session data, we remove any possibility of the user modifying which user a bookmark is for. We'll do the same for the edit form and action. Your `edit()` action from **src/Controller/BookmarksController.php** should look like:

    public function edit($id = null)
    {
        $bookmark = $this->Bookmarks->get($id, [\
            'contain' => ['Tags']\
        ]);
        if ($this->request->is(['patch', 'post', 'put'])) {
            $bookmark = $this->Bookmarks->patchEntity($bookmark, $this->request->getData());
            $bookmark->user_id = $this->Auth->user('id');
            if ($this->Bookmarks->save($bookmark)) {
                $this->Flash->success('The bookmark has been saved.');
                return $this->redirect(['action' => 'index']);
            }
            $this->Flash->error('The bookmark could not be saved. Please, try again.');
        }
        $tags = $this->Bookmarks->Tags->find('list');
        $this->set(compact('bookmark', 'tags'));
        $this->set('_serialize', ['bookmark']);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

### List View [​](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/part-two.html#list-view)

Now, we only need to show bookmarks for the currently logged in user. We can do that by updating the call to `paginate()`. Make your `index()` action from **src/Controller/BookmarksController.php** look like:

    public function index()
    {
        $this->paginate = [\
            'conditions' => [\
                'Bookmarks.user_id' => $this->Auth->user('id'),\
            ]\
        ];
        $this->set('bookmarks', $this->paginate($this->Bookmarks));
        $this->set('_serialize', ['bookmarks']);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

We should also update the `tags()` action and the related finder method, but we'll leave that as an exercise you can complete on your own.

Improving the Tagging Experience [​](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/part-two.html#improving-the-tagging-experience)

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

Right now, adding new tags is a difficult process, as the `TagsController` disallows all access. Instead of allowing access, we can improve the tag selection UI by using a comma separated text field. This will let us give a better experience to our users, and use some more great features in the ORM.

### Adding a Computed Field [​](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/part-two.html#adding-a-computed-field)

Because we'll want a simple way to access the formatted tags for an entity, we can add a virtual/computed field to the entity. In **src/Model/Entity/Bookmark.php** add the following:

    use Cake\Collection\Collection;
    
    protected function _getTagString()
    {
        if (isset($this->_properties['tag_string'])) {
            return $this->_properties['tag_string'];
        }
        if (empty($this->tags)) {
            return '';
        }
        $tags = new Collection($this->tags);
        $str = $tags->reduce(function ($string, $tag) {
            return $string . $tag->title . ', ';
        }, '');
        return trim($str, ', ');
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  

This will let us access the `$bookmark->tag_string` computed property. We'll use this property in controls later on. Remember to add the `tag_string` property to the `_accessible` list in your entity, as we'll want to 'save' it later on.

In **src/Model/Entity/Bookmark.php** add the `tag_string` to `$_accessible` this way:

    protected $_accessible = [\
        'user_id' => true,\
        'title' => true,\
        'description' => true,\
        'url' => true,\
        'user' => true,\
        'tags' => true,\
        'tag_string' => true,\
    ];

1  
2  
3  
4  
5  
6  
7  
8  
9  

### Updating the Views [​](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/part-two.html#updating-the-views)

With the entity updated we can add a new control for our tags. In **src/Template/Bookmarks/add.ctp** and **src/Template/Bookmarks/edit.ctp**, replace the existing `tags._ids` control with the following:

    echo $this->Form->control('tag_string', ['type' => 'text']);

1  

### Persisting the Tag String [​](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/part-two.html#persisting-the-tag-string)

Now that we can view existing tags as a string, we'll want to save that data as well. Because we marked the `tag_string` as accessible, the ORM will copy that data from the request into our entity. We can use a `beforeSave()` hook method to parse the tag string and find/build the related entities. Add the following to **src/Model/Table/BookmarksTable.php**:

    public function beforeSave($event, $entity, $options)
    {
        if ($entity->tag_string) {
            $entity->tags = $this->_buildTags($entity->tag_string);
        }
    }
    
    protected function _buildTags($tagString)
    {
        // Trim tags
        $newTags = array_map('trim', explode(',', $tagString));
        // Remove all empty tags
        $newTags = array_filter($newTags);
        // Reduce duplicated tags
        $newTags = array_unique($newTags);
    
        $out = [];
        $query = $this->Tags->find()
            ->where(['Tags.title IN' => $newTags]);
    
        // Remove existing tags from the list of new tags.
        foreach ($query->extract('title') as $existing) {
            $index = array_search($existing, $newTags);
            if ($index !== false) {
                unset($newTags[$index]);
            }
        }
        // Add existing tags.
        foreach ($query as $tag) {
            $out[] = $tag;
        }
        // Add new tags.
        foreach ($newTags as $tag) {
            $out[] = $this->Tags->newEntity(['title' => $tag]);
        }
        return $out;
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  

While this code is a bit more complicated than what we've done so far, it helps to showcase how powerful the ORM in CakePHP is. You can manipulate query results using the [Collections](https://book.cakephp.org/3.x/core-libraries/collections.html)
 methods, and handle scenarios where you are creating entities on the fly with ease.

Wrapping Up [​](https://book.cakephp.org/3.x/tutorials-and-examples/bookmarks/part-two.html#wrapping-up)

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

We've expanded our bookmarking application to handle authentication and basic authorization/access control scenarios. We've also added some nice UX improvements by leveraging the FormHelper and ORM capabilities.

Thanks for taking the time to explore CakePHP. Next, you can complete the [Blog Tutorial](https://book.cakephp.org/3.x/tutorials-and-examples/blog/blog.html)
, learn more about the [Database Access & ORM](https://book.cakephp.org/3.x/orm.html)
, or you can peruse the [Using CakePHP](https://book.cakephp.org/3.x/topics.html)
.

---

# Phinx Migrations | CakePHP

[Skip to content](https://book.cakephp.org/3.x/phinx.html#VPContent)

Return to top

Phinx Migrations [​](https://book.cakephp.org/3.x/phinx.html#phinx-migrations)

===============================================================================

This page has [moved](https://book.cakephp.org/phinx/)
.

---

# Content Management Tutorial | CakePHP

[Skip to content](https://book.cakephp.org/3.x/tutorials-and-examples/cms/installation.html#VPContent)

Return to top

Content Management Tutorial [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/installation.html#content-management-tutorial)

=======================================================================================================================================

This tutorial will walk you through the creation of a simple `CMS (Content Management System)` application. To start with, we'll be installing CakePHP, creating our database, and building simple article management.

Here's what you'll need:

1.  A database server. We're going to be using MySQL server in this tutorial. You'll need to know enough about SQL in order to create a database, and run SQL snippets from the tutorial. CakePHP will handle building all the queries your application needs. Since we're using MySQL, also make sure that you have `pdo_mysql` enabled in PHP.
2.  Basic PHP knowledge.

Before starting you should make sure that you have got an up to date PHP version:

    php -v

1  

You should at least have got installed PHP _5.6_ (CLI) or higher. Your webserver's PHP version must also be of _5.6_ or higher, and should be the same version your command line interface (CLI) PHP is.

Getting CakePHP [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/installation.html#getting-cakephp)

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

The easiest way to install CakePHP is to use Composer. Composer is a simple way of installing CakePHP from your terminal or command line prompt. First, you'll need to download and install Composer if you haven't done so already. If you have cURL installed, it's as easy as running the following:

    curl -s https://getcomposer.org/installer | php

1  

Or, you can download `composer.phar` from the [Composer website](https://getcomposer.org/download/)
.

Then simply type the following line in your terminal from your installation directory to install the CakePHP application skeleton in the **cms** directory of the current working directory:

    php composer.phar create-project --prefer-dist cakephp/app:"^3.10" cms

1  

If you downloaded and ran the [Composer Windows Installer](https://getcomposer.org/Composer-Setup.exe)
, then type the following line in your terminal from your installation directory (ie. C:\\wamp\\www\\dev\\cakephp3):

    composer self-update && composer create-project --prefer-dist cakephp/app:"^3.10" cms

1  

The advantage to using Composer is that it will automatically complete some important set up tasks, such as setting the correct file permissions and creating your **config/app.php** file for you.

There are other ways to install CakePHP. If you cannot or don't want to use Composer, check out the [Installation](https://book.cakephp.org/3.x/installation.html)
 section.

Regardless of how you downloaded and installed CakePHP, once your set up is completed, your directory setup should look something like the following:

    /cms
      /bin
      /config
      /logs
      /plugins
      /src
      /tests
      /tmp
      /vendor
      /webroot
      .editorconfig
      .gitignore
      .htaccess
      .travis.yml
      composer.json
      index.php
      phpunit.xml.dist
      README.md
    

Now might be a good time to learn a bit about how CakePHP's directory structure works: check out the [CakePHP Folder Structure](https://book.cakephp.org/3.x/intro/cakephp-folder-structure.html)
 section.

If you get lost during this tutorial, you can see the finished result [on GitHub](https://github.com/cakephp/cms-tutorial)
.

Checking our Installation [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/installation.html#checking-our-installation)

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

We can quickly check that our installation is correct, by checking the default home page. Before you can do that, you'll need to start the development server:

    cd /path/to/our/app
    
    bin/cake server

1  
2  
3  

NOTE

For Windows, the command needs to be `bin\cake server` (note the backslash).

This will start PHP's built-in webserver on port 8765. Open up **[http://localhost:8765](http://localhost:8765/)
** in your web browser to see the welcome page. All the bullet points should be green chef hats other than CakePHP being able to connect to your database. If not, you may need to install additional PHP extensions, or set directory permissions.

Next, we will build our [Database and create our first model](https://book.cakephp.org/3.x/tutorials-and-examples/cms/database.html)
.

---

# CMS Tutorial - Tags and Users | CakePHP

[Skip to content](https://book.cakephp.org/3.x/tutorials-and-examples/cms/tags-and-users.html#VPContent)

Return to top

CMS Tutorial - Tags and Users [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/tags-and-users.html#cms-tutorial-tags-and-users)

===========================================================================================================================================

With the basic article creation functionality built, we need to enable multiple authors to work in our CMS. Previously, we built all the models, views and controllers by hand. This time around we're going to use [Bake Console](https://book.cakephp.org/3.x/bake.html)
 to create our skeleton code. Bake is a powerful code generation `CLI (Command Line Interface)` tool that leverages the conventions CakePHP uses to create skeleton `CRUD (Create, Read, Update, Delete)` applications very efficiently. We're going to use `bake` to build our users code:

    cd /path/to/our/app
    
    bin/cake bake model users
    bin/cake bake controller users
    bin/cake bake template users

1  
2  
3  
4  
5  

These 3 commands will generate:

*   The Table, Entity, Fixture files.
*   The Controller
*   The CRUD templates.
*   Test cases for each generated class.

Bake will also use the CakePHP conventions to infer the associations, and validation your models have.

Adding Tagging to Articles [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/tags-and-users.html#adding-tagging-to-articles)

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

With multiple users able to access our small `CMS` it would be nice to have a way to categorize our content. We'll use tags and tagging to allow users to create free-form categories and labels for their content. Again, we'll use `bake` to quickly generate some skeleton code for our application:

    # Generate all the code at once.
    bin/cake bake all tags

1  
2  

Once you have the scaffold code created, create a few sample tags by going to **[http://localhost:8765/tags/add](http://localhost:8765/tags/add)
**.

Now that we have a Tags table, we can create an association between Articles and Tags. We can do so by adding the following to the `initialize` method on the ArticlesTable:

    public function initialize(array $config)
    {
        $this->addBehavior('Timestamp');
        $this->belongsToMany('Tags'); // Add this line
    }

1  
2  
3  
4  
5  

This association will work with this simple definition because we followed CakePHP conventions when creating our tables. For more information, read [Associations - Linking Tables Together](https://book.cakephp.org/3.x/orm/associations.html)
.

Updating Articles to Enable Tagging [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/tags-and-users.html#updating-articles-to-enable-tagging)

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

Now that our application has tags, we need to enable users to tag their articles. First, update the `add` action to look like:

    // in src/Controller/ArticlesController.php
    
    namespace App\Controller;
    
    use App\Controller\AppController;
    
    class ArticlesController extends AppController
    {
        public function add()
        {
            $article = $this->Articles->newEntity();
            if ($this->request->is('post')) {
                $article = $this->Articles->patchEntity($article, $this->request->getData());
    
                // Hardcoding the user_id is temporary, and will be removed later
                // when we build authentication out.
                $article->user_id = 1;
    
                if ($this->Articles->save($article)) {
                    $this->Flash->success(__('Your article has been saved.'));
                    return $this->redirect(['action' => 'index']);
                }
                $this->Flash->error(__('Unable to add your article.'));
            }
            // Get a list of tags.
            $tags = $this->Articles->Tags->find('list');
    
            // Set tags to the view context
            $this->set('tags', $tags);
    
            $this->set('article', $article);
        }
    
        // Other actions
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  

The added lines load a list of tags as an associative array of `id => title`. This format will let us create a new tag input in our template. Add the following to the PHP block of controls in **src/Template/Articles/add.ctp**:

    echo $this->Form->control('tags._ids', ['options' => $tags]);

1  

This will render a multiple select element that uses the `$tags` variable to generate the select box options. You should now create a couple new articles that have tags, as in the following section we'll be adding the ability to find articles by tags.

You should also update the `edit` method to allow adding or editing tags. The edit method should now look like:

    public function edit($slug)
    {
        $article = $this->Articles
            ->findBySlug($slug)
            ->contain('Tags') // load associated Tags
            ->firstOrFail();
        if ($this->request->is(['post', 'put'])) {
            $this->Articles->patchEntity($article, $this->request->getData());
            if ($this->Articles->save($article)) {
                $this->Flash->success(__('Your article has been updated.'));
                return $this->redirect(['action' => 'index']);
            }
            $this->Flash->error(__('Unable to update your article.'));
        }
    
        // Get a list of tags.
        $tags = $this->Articles->Tags->find('list');
    
        // Set tags to the view context
        $this->set('tags', $tags);
    
        $this->set('article', $article);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  

Remember to add the new tags multiple select control we added to the **add.ctp** template to the **src/Template/Articles/edit.ctp** template as well.

Finding Articles By Tags [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/tags-and-users.html#finding-articles-by-tags)

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

Once users have categorized their content, they will want to find that content by the tags they used. For this feature we'll implement a route, controller action, and finder method to search through articles by tag.

Ideally, we'd have a URL that looks like **[http://localhost:8765/articles/tagged/funny/cat/gifs](http://localhost:8765/articles/tagged/funny/cat/gifs)
**. This would let us find all the articles that have the 'funny', 'cat' or 'gifs' tags. Before we can implement this, we'll add a new route. Your **config/routes.php** should look like:

    <?php
    use Cake\Http\Middleware\CsrfProtectionMiddleware;
    use Cake\Routing\RouteBuilder;
    use Cake\Routing\Router;
    use Cake\Routing\Route\DashedRoute;
    
    Router::defaultRouteClass(DashedRoute::class);
    
    Router::scope('/', function (RouteBuilder $routes) {
        // Register scoped middleware for in scopes.
        $routes->registerMiddleware('csrf', new CsrfProtectionMiddleware([\
            'httpOnly' => true\
        ]));
        $routes->applyMiddleware('csrf');
        $routes->connect('/', ['controller' => 'Pages', 'action' => 'display', 'home']);
        $routes->connect('/pages/*', ['controller' => 'Pages', 'action' => 'display']);
        $routes->fallbacks(DashedRoute::class);
    });
    // Add this
    // New route we're adding for our tagged action.
    // The trailing `*` tells CakePHP that this action has
    // passed parameters.
    Router::scope('/articles', function (RouteBuilder $routes) {
        $routes->connect('/tagged/*', ['controller' => 'Articles', 'action' => 'tags']);
    });

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  

The above defines a new 'route' which connects the **/articles/tagged/** path, to `ArticlesController::tags()`. By defining routes, you can isolate how your URLs look, from how they are implemented. If we were to visit **[http://localhost:8765/articles/tagged](http://localhost:8765/articles/tagged)
**, we would see a helpful error page from CakePHP informing you that the controller action does not exist. Let's implement that missing method now. In **src/Controller/ArticlesController.php** add the following:

    public function tags()
    {
        // The 'pass' key is provided by CakePHP and contains all
        // the passed URL path segments in the request.
        $tags = $this->request->getParam('pass');
    
        // Use the ArticlesTable to find tagged articles.
        $articles = $this->Articles->find('tagged', [\
            'tags' => $tags\
        ]);
    
        // Pass variables into the view template context.
        $this->set([\
            'articles' => $articles,\
            'tags' => $tags\
        ]);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

To access other parts of the request data, consult the [Cake Request](https://book.cakephp.org/3.x/controllers/request-response.html#cake-request)
 section.

Since passed arguments are passed as method parameters, you could also write the action using PHP's variadic argument:

    public function tags(...$tags)
    {
        // Use the ArticlesTable to find tagged articles.
        $articles = $this->Articles->find('tagged', [\
            'tags' => $tags\
        ]);
    
        // Pass variables into the view template context.
        $this->set([\
            'articles' => $articles,\
            'tags' => $tags\
        ]);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

### Creating the Finder Method [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/tags-and-users.html#creating-the-finder-method)

In CakePHP we like to keep our controller actions slim, and put most of our application's logic in the model layer. If you were to visit the **/articles/tagged** URL now you would see an error that the `findTagged()` method has not been implemented yet, so let's do that. In **src/Model/Table/ArticlesTable.php** add the following:

    // add this use statement right below the namespace declaration to import
    // the Query class
    use Cake\ORM\Query;
    
    // The $query argument is a query builder instance.
    // The $options array will contain the 'tags' option we passed
    // to find('tagged') in our controller action.
    public function findTagged(Query $query, array $options)
    {
        $columns = [\
            'Articles.id', 'Articles.user_id', 'Articles.title',\
            'Articles.body', 'Articles.published', 'Articles.created',\
            'Articles.slug',\
        ];
    
        $query = $query
            ->select($columns)
            ->distinct($columns);
    
        if (empty($options['tags'])) {
            // If there are no tags provided, find articles that have no tags.
            $query->leftJoinWith('Tags')
                ->where(['Tags.title IS' => null]);
        } else {
            // Find articles that have one or more of the provided tags.
            $query->innerJoinWith('Tags')
                ->where(['Tags.title IN' => $options['tags']]);
        }
    
        return $query->group(['Articles.id']);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  

We just implemented a [custom finder method](https://book.cakephp.org/3.x/orm/retrieving-data-and-resultsets.html#custom-find-methods)
. This is a very powerful concept in CakePHP that allows you to package up re-usable queries. Finder methods always get a [Query Builder](https://book.cakephp.org/3.x/orm/query-builder.html)
 object and an array of options as parameters. Finders can manipulate the query and add any required conditions or criteria. When complete, finder methods must return a modified query object. In our finder we've leveraged the `distinct()` and `leftJoin()` methods which allow us to find distinct articles that have a 'matching' tag.

### Creating the View [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/tags-and-users.html#creating-the-view)

Now if you visit the **/articles/tagged** URL again, CakePHP will show a new error letting you know that you have not made a view file. Next, let's build the view file for our `tags()` action. In **src/Template/Articles/tags.ctp** put the following content:

    <h1>
        Articles tagged with
        <?= $this->Text->toList(h($tags), 'or') ?>
    </h1>
    
    <section>
    <?php foreach ($articles as $article): ?>
        <article>
            <!-- Use the HtmlHelper to create a link -->
            <h4><?= $this->Html->link(
                $article->title,
                ['controller' => 'Articles', 'action' => 'view', $article->slug]
            ) ?></h4>
            <span><?= h($article->created) ?></span>
        </article>
    <?php endforeach; ?>
    </section>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

In the above code we use the [Html](https://book.cakephp.org/3.x/views/helpers/html.html)
 and [Text](https://book.cakephp.org/3.x/views/helpers/text.html)
 helpers to assist in generating our view output. We also use the `h` shortcut function to HTML encode output. You should remember to always use `h()` when outputting data to prevent HTML injection issues.

The **tags.ctp** file we just created follows the CakePHP conventions for view template files. The convention is to have the template use the lower case and underscored version of the controller action name.

You may notice that we were able to use the `$tags` and `$articles` variables in our view template. When we use the `set()` method in our controller, we set specific variables to be sent to the view. The View will make all passed variables available in the template scope as local variables.

You should now be able to visit the **/articles/tagged/funny** URL and see all the articles tagged with 'funny'.

Improving the Tagging Experience [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/tags-and-users.html#improving-the-tagging-experience)

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

Right now, adding new tags is a cumbersome process, as authors need to pre-create all the tags they want to use. We can improve the tag selection UI by using a comma separated text field. This will let us give a better experience to our users, and use some more great features in the ORM.

### Adding a Computed Field [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/tags-and-users.html#adding-a-computed-field)

Because we'll want a simple way to access the formatted tags for an entity, we can add a virtual/computed field to the entity. In **src/Model/Entity/Article.php** add the following:

    // add this use statement right below the namespace declaration to import
    // the Collection class
    use Cake\Collection\Collection;
    
    // Update the accessible property to contain `tag_string`
    protected $_accessible = [\
        //other fields...\
        'tag_string' => true\
    ];
    
    protected function _getTagString()
    {
        if (isset($this->_properties['tag_string'])) {
            return $this->_properties['tag_string'];
        }
        if (empty($this->tags)) {
            return '';
        }
        $tags = new Collection($this->tags);
        $str = $tags->reduce(function ($string, $tag) {
            return $string . $tag->title . ', ';
        }, '');
        return trim($str, ', ');
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  

This will let us access the `$article->tag_string` computed property. We'll use this property in controls later on.

### Updating the Views [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/tags-and-users.html#updating-the-views)

With the entity updated we can add a new control for our tags. In **src/Template/Articles/add.ctp** and **src/Template/Articles/edit.ctp**, replace the existing `tags._ids` control with the following:

    echo $this->Form->control('tag_string', ['type' => 'text']);

1  

We'll also need to update the article view template. In **src/Template/Articles/view.ctp** add the line as shown:

    <!-- File: src/Template/Articles/view.ctp -->
    
    <h1><?= h($article->title) ?></h1>
    <p><?= h($article->body) ?></p>
    // Add the following line
    <p><b>Tags:</b> <?= h($article->tag_string) ?></p>

1  
2  
3  
4  
5  
6  

### Persisting the Tag String [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/tags-and-users.html#persisting-the-tag-string)

Now that we can view existing tags as a string, we'll want to save that data as well. Because we marked the `tag_string` as accessible, the ORM will copy that data from the request into our entity. We can use a `beforeSave()` hook method to parse the tag string and find/build the related entities. Add the following to **src/Model/Table/ArticlesTable.php**:

    public function beforeSave($event, $entity, $options)
    {
        if ($entity->tag_string) {
            $entity->tags = $this->_buildTags($entity->tag_string);
        }
    
        // Other code
    }
    
    protected function _buildTags($tagString)
    {
        // Trim tags
        $newTags = array_map('trim', explode(',', $tagString));
        // Remove all empty tags
        $newTags = array_filter($newTags);
        // Reduce duplicated tags
        $newTags = array_unique($newTags);
    
        $out = [];
        $query = $this->Tags->find()
            ->where(['Tags.title IN' => $newTags]);
    
        // Remove existing tags from the list of new tags.
        foreach ($query->extract('title') as $existing) {
            $index = array_search($existing, $newTags);
            if ($index !== false) {
                unset($newTags[$index]);
            }
        }
        // Add existing tags.
        foreach ($query as $tag) {
            $out[] = $tag;
        }
        // Add new tags.
        foreach ($newTags as $tag) {
            $out[] = $this->Tags->newEntity(['title' => $tag]);
        }
        return $out;
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  

If you now create or edit articles, you should be able to save tags as a comma separated list of tags, and have the tags and linking records automatically created.

While this code is a bit more complicated than what we've done so far, it helps to showcase how powerful the ORM in CakePHP is. You can manipulate query results using the [Collections](https://book.cakephp.org/3.x/core-libraries/collections.html)
 methods, and handle scenarios where you are creating entities on the fly with ease.

Auto-populating the Tag String [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/tags-and-users.html#auto-populating-the-tag-string)

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

Before we finish up, we'll need a mechanism that will load the associated tags (if any) whenever we load an article.

In your **src/Model/Table/ArticlesTable.php**, change:

    public function initialize(array $config)
    {
        $this->addBehavior('Timestamp');
        // Change this line
        $this->belongsToMany('Tags', [\
            'joinTable' => 'articles_tags',\
            'dependent' => true\
        ]);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  

This will tell the Articles table model that there is a join table associated with tags. The 'dependent' option tells the table to delete any associated records from the join table if an article is deleted.

Lastly, update the findBySlug() method calls in **src/Controller/ArticlesController.php**:

    public function edit($slug)
    {
        // Update this line
        $article = $this->Articles->findBySlug($slug)->contain(['Tags'])
            ->firstOrFail();
    ...
    }
    
    public function view($slug = null)
    {
        // Update this line
        $article = $this->Articles->findBySlug($slug)->contain(['Tags'])
            ->firstOrFail();
        $this->set(compact('article'));
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

The contain() method tells the ArticlesTable object to also populate the Tags association when the article is loaded. Now when tag\_string is called for an Article entity, there will be data present to create the string!

Next we'll be adding [authentication](https://book.cakephp.org/3.x/tutorials-and-examples/cms/authentication.html)
.

---

# Blog Tutorial - Authentication and Authorization | CakePHP

[Skip to content](https://book.cakephp.org/3.x/tutorials-and-examples/blog-auth-example/auth.html#VPContent)

Return to top

Blog Tutorial - Authentication and Authorization [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog-auth-example/auth.html#blog-tutorial-authentication-and-authorization)

=====================================================================================================================================================================================

Following our [Blog Tutorial](https://book.cakephp.org/3.x/tutorials-and-examples/blog/blog.html)
 example, imagine we wanted to secure access to certain URLs, based on the logged-in user. We also have another requirement: to allow our blog to have multiple authors who can create, edit, and delete their own articles while disallowing other authors from making changes to articles they do not own.

Creating All User-Related Code [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog-auth-example/auth.html#creating-all-user-related-code)

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

First, let's create a new table in our blog database to hold our users' data:

    CREATE TABLE users (
        id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
        username VARCHAR(50),
        password VARCHAR(255),
        role VARCHAR(20),
        created DATETIME DEFAULT NULL,
        modified DATETIME DEFAULT NULL
    );

1  
2  
3  
4  
5  
6  
7  
8  

We have adhered to the CakePHP conventions in naming tables, but we're also taking advantage of another convention: By using the username and password columns in a users table, CakePHP will be able to auto-configure most things for us when implementing the user login.

Next step is to create our UsersTable class, responsible for finding, saving and validating any user data:

    // src/Model/Table/UsersTable.php
    namespace App\Model\Table;
    
    use Cake\ORM\Table;
    use Cake\Validation\Validator;
    
    class UsersTable extends Table
    {
        public function validationDefault(Validator $validator)
        {
            return $validator
                ->notEmpty('username', 'A username is required')
                ->notEmpty('password', 'A password is required')
                ->notEmpty('role', 'A role is required')
                ->add('role', 'inList', [\
                    'rule' => ['inList', ['admin', 'author']],\
                    'message' => 'Please enter a valid role'\
                ]);
        }
    
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  

Let's also create our UsersController. The following content corresponds to parts of a basic baked UsersController class using the code generation utilities bundled with CakePHP:

    // src/Controller/UsersController.php
    
    namespace App\Controller;
    
    use App\Controller\AppController;
    use Cake\Event\Event;
    
    class UsersController extends AppController
    {
        public function beforeFilter(Event $event)
        {
            parent::beforeFilter($event);
            $this->Auth->allow('add');
        }
    
        public function index()
        {
            $this->set('users', $this->Users->find('all'));
        }
    
        public function view($id)
        {
            $user = $this->Users->get($id);
            $this->set(compact('user'));
        }
    
        public function add()
        {
            $user = $this->Users->newEntity();
            if ($this->request->is('post')) {
                // Prior to 3.4.0 $this->request->data() was used.
                $user = $this->Users->patchEntity($user, $this->request->getData());
                if ($this->Users->save($user)) {
                    $this->Flash->success(__('The user has been saved.'));
                    return $this->redirect(['action' => 'add']);
                }
                $this->Flash->error(__('Unable to add the user.'));
            }
            $this->set('user', $user);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40  
41  

In the same way we created the views for our articles by using the code generation tool, we can implement the user views. For the purpose of this tutorial, we will show just the add.ctp:

    <!-- src/Template/Users/add.ctp -->
    
    <div class="users form">
    <?= $this->Form->create($user) ?>
        <fieldset>
            <legend><?= __('Add User') ?></legend>
            <?= $this->Form->control('username') ?>
            <?= $this->Form->control('password') ?>
            <?= $this->Form->control('role', [\
                'options' => ['admin' => 'Admin', 'author' => 'Author']\
            ]) ?>
       </fieldset>
    <?= $this->Form->button(__('Submit')); ?>
    <?= $this->Form->end() ?>
    </div>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

Authentication (Login and Logout) [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog-auth-example/auth.html#authentication-login-and-logout)

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

We're now ready to add our authentication layer. In CakePHP this is handled by the `Cake\Controller\Component\AuthComponent`, a class responsible for requiring login for certain actions, handling user login and logout, and also authorizing logged-in users to the actions they are allowed to reach.

To add this component to your application open your **src/Controller/AppController.php** file and add the following lines:

    // src/Controller/AppController.php
    
    namespace App\Controller;
    
    use Cake\Controller\Controller;
    use Cake\Event\Event;
    
    class AppController extends Controller
    {
        //...
    
        public function initialize()
        {
            $this->loadComponent('Flash');
            $this->loadComponent('Auth', [\
                'loginRedirect' => [\
                    'controller' => 'Articles',\
                    'action' => 'index'\
                ],\
                'logoutRedirect' => [\
                    'controller' => 'Pages',\
                    'action' => 'display',\
                    'home'\
                ]\
            ]);
        }
    
        public function beforeFilter(Event $event)
        {
            $this->Auth->allow(['index', 'view', 'display']);
        }
        //...
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  

There is not much to configure, as we used the conventions for the users table. We just set up the URLs that will be loaded after the login and logout actions is performed, in our case to `/articles/` and `/` respectively.

What we did in the `beforeFilter()` function was to tell the AuthComponent to not require a login for all `index()` and `view()` actions, in every controller. We want our visitors to be able to read and list the entries without registering in the site.

Now, we need to be able to register new users, save their username and password, and more importantly, hash their password so it is not stored as plain text in our database. Let's tell the AuthComponent to let un-authenticated users access the users add function and implement the login and logout action:

    // src/Controller/UsersController.php
    namespace App\Controller;
    
    use App\Controller\AppController;
    use Cake\Event\Event;
    
    class UsersController extends AppController
    {
        // Other methods..
    
        public function beforeFilter(Event $event)
        {
            parent::beforeFilter($event);
            // Allow users to register and logout.
            // You should not add the "login" action to allow list. Doing so would
            // cause problems with normal functioning of AuthComponent.
            $this->Auth->allow(['add', 'logout']);
        }
    
        public function login()
        {
            if ($this->request->is('post')) {
                $user = $this->Auth->identify();
                if ($user) {
                    $this->Auth->setUser($user);
                    return $this->redirect($this->Auth->redirectUrl());
                }
                $this->Flash->error(__('Invalid username or password, try again'));
            }
        }
    
        public function logout()
        {
            return $this->redirect($this->Auth->logout());
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  

Password hashing is not done yet, we need an Entity class for our User in order to handle its own specific logic. Create the **src/Model/Entity/User.php** entity file and add the following:

    // src/Model/Entity/User.php
    namespace App\Model\Entity;
    
    use Cake\Auth\DefaultPasswordHasher;
    use Cake\ORM\Entity;
    
    class User extends Entity
    {
        // Make all fields mass assignable except for primary key field "id".
        protected $_accessible = [\
            '*' => true,\
            'id' => false\
        ];
    
        // ...
    
        protected function _setPassword($password)
        {
            if (strlen($password) > 0) {
                return (new DefaultPasswordHasher)->hash($password);
            }
        }
    
        // ...
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  

Now every time the password property is assigned to the user it will be hashed using the `DefaultPasswordHasher` class. We're just missing a template view file for the login function. Open up your **src/Template/Users/login.ctp** file and add the following lines:

    <!-- File: src/Template/Users/login.ctp -->
    
    <div class="users form">
    <?= $this->Flash->render() ?>
    <?= $this->Form->create() ?>
        <fieldset>
            <legend><?= __('Please enter your username and password') ?></legend>
            <?= $this->Form->control('username') ?>
            <?= $this->Form->control('password') ?>
        </fieldset>
    <?= $this->Form->button(__('Login')); ?>
    <?= $this->Form->end() ?>
    </div>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

You can now register a new user by accessing the `/users/add` URL and log in with the newly created credentials by going to `/users/login` URL. Also, try to access any other URL that was not explicitly allowed such as `/articles/add`, you will see that the application automatically redirects you to the login page.

And that's it! It looks too simple to be true. Let's go back a bit to explain what happened. The `beforeFilter()` function is telling the AuthComponent to not require a login for the `add()` action in addition to the `index()` and `view()` actions that were already allowed in the AppController's `beforeFilter()` function.

The `login()` action calls the `$this->Auth->identify()` function in the AuthComponent, and it works without any further config because we are following conventions as mentioned earlier. That is, having a Users table with a username and a password column, and use a form posted to a controller with the user data. This function returns whether the login was successful or not, and in the case it succeeds, then we redirect the user to the configured redirection URL that we used when adding the AuthComponent to our application.

The logout works by just accessing the `/users/logout` URL and will redirect the user to the configured logoutUrl formerly described. This URL is the result of the `AuthComponent::logout()` function on success.

Authorization (who's allowed to access what) [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog-auth-example/auth.html#authorization-who-s-allowed-to-access-what)

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

As stated before, we are converting this blog into a multi-user authoring tool, and in order to do this, we need to modify the articles table a bit to add the reference to the Users table:

    ALTER TABLE articles ADD COLUMN user_id INT(11);

1  

Also, a small change in the ArticlesController is required to store the currently logged in user as a reference for the created article:

    // src/Controller/ArticlesController.php
    
    public function add()
    {
        $article = $this->Articles->newEntity();
        if ($this->request->is('post')) {
            // Prior to 3.4.0 $this->request->data() was used.
            $article = $this->Articles->patchEntity($article, $this->request->getData());
            // Added this line
            $article->user_id = $this->Auth->user('id');
            // You could also do the following
            //$newData = ['user_id' => $this->Auth->user('id')];
            //$article = $this->Articles->patchEntity($article, $newData);
            if ($this->Articles->save($article)) {
                $this->Flash->success(__('Your article has been saved.'));
                return $this->redirect(['action' => 'index']);
            }
            $this->Flash->error(__('Unable to add your article.'));
        }
        $this->set('article', $article);
    
        // Just added the categories list to be able to choose
        // one category for an article
        $categories = $this->Articles->Categories->find('treeList');
        $this->set(compact('categories'));
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  

The `user()` function provided by the component returns any column from the currently logged in user. We used this method to add the data into the request info that is saved.

Let's secure our app to prevent some authors from editing or deleting the others' articles. Basic rules for our app are that admin users can access every URL, while normal users (the author role) can only access the permitted actions. Again, open the AppController class and add a few more options to the Auth config:

    // src/Controller/AppController.php
    
    public function initialize()
    {
        $this->loadComponent('Flash');
        $this->loadComponent('Auth', [\
            'authorize' => ['Controller'], // Added this line\
            'loginRedirect' => [\
                'controller' => 'Articles',\
                'action' => 'index'\
            ],\
            'logoutRedirect' => [\
                'controller' => 'Pages',\
                'action' => 'display',\
                'home'\
            ]\
        ]);
    }
    
    public function isAuthorized($user)
    {
        // Admin can access every action
        if (isset($user['role']) && $user['role'] === 'admin') {
            return true;
        }
    
        // Default deny
        return false;
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  

We just created a simple authorization mechanism. Users with the `admin` role will be able to access any URL in the site when logged-in. All other users -- those with the `author` role -- will have the same access as users who aren't logged-in.

This is not exactly what we want. We need to supply more rules to our `isAuthorized()` method. However instead of doing it in AppController, we'll delegate supplying those extra rules to each individual controller. The rules we're going to add to ArticlesController should permit authors to create articles but prevent authors from editing articles they do not own. Add the following content to your **ArticlesController.php**:

    // src/Controller/ArticlesController.php
    
    public function isAuthorized($user)
    {
        // All registered users can add articles
        // Prior to 3.4.0 $this->request->param('action') was used.
        if ($this->request->getParam('action') === 'add') {
            return true;
        }
    
        // The owner of an article can edit and delete it
        // Prior to 3.4.0 $this->request->param('action') was used.
        if (in_array($this->request->getParam('action'), ['edit', 'delete'])) {
            // Prior to 3.4.0 $this->request->params('pass.0')
            $articleId = (int)$this->request->getParam('pass.0');
            if ($this->Articles->isOwnedBy($articleId, $user['id'])) {
                return true;
            }
        }
    
        return parent::isAuthorized($user);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  

We're now overriding the AppController's `isAuthorized()` call and internally checking if the parent class is already authorizing the user. If he isn't, then just allow him to access the add action, and conditionally access edit and delete. One final thing has not been implemented. To tell whether or not the user is authorized to edit the article, we're calling a `isOwnedBy()` function in the Articles table. Let's then implement that function:

    // src/Model/Table/ArticlesTable.php
    
    public function isOwnedBy($articleId, $userId)
    {
        return $this->exists(['id' => $articleId, 'user_id' => $userId]);
    }

1  
2  
3  
4  
5  
6  

This concludes our simple authentication and authorization tutorial. For securing the UsersController you can follow the same technique we did for ArticlesController. You could also be more creative and code something more general in AppController based on your own rules.

Should you need more control, we suggest you read the complete Auth guide in the [AuthComponent](https://book.cakephp.org/3.x/controllers/components/authentication.html)
 section where you will find more about configuring the component, creating custom Authorization classes, and much more.

### Suggested Follow-up Reading [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog-auth-example/auth.html#suggested-follow-up-reading)

1.  [Code Generation with Bake](https://book.cakephp.org/3.x/bake/usage.html)
     Generating basic CRUD code
2.  [AuthComponent](https://book.cakephp.org/3.x/controllers/components/authentication.html)
    : User registration and login

---

# Form | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/views/helpers/form.html#VPContent)

Return to top

Form [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#form)

=======================================================================

`class` Cake\\View\\Helper\\**FormHelper**(View $view, array $config = \[\])

FormHelper は、フォーム作成時の力作業のほとんどを代行してくれます。 FormHelper は、フォームを素早く作成し、検証、再配置、レイアウトを効率化します。 FormHelper は、柔軟でもあります。通常は規約に沿ってほとんどのことをやってくれますが、 特定のメソッドを使って必要な機能だけを使うこともできます。

フォームの開始 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%83%95%E3%82%A9%E3%83%BC%E3%83%A0%E3%81%AE%E9%96%8B%E5%A7%8B)

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

`method` Cake\\View\\Helper\\FormHelper::**create**(mixed $context = null, array $options = \[\])

*   `$context` - フォームが定義されているコンテキスト。 ORM エンティティー、 ORM 結果セット、 メタデータの配列もしくは `false/null` (モデルのないフォームを作成するため) です。
*   `$options` - オプションまたは HTML 属性の配列。

FormHelper を活用するために最初に使うメソッドは `create()` です。 このメソッドは、フォームの開始タグを出力します。

パラメーターはすべてオプションです。 `create()` が、パラメーターなしで呼ばれた場合、 現在の URL を元に現在のコントローラーに送信するためのフォームを作ろうとしているものとみなします。 フォーム送信のためのデフォルトのメソッドは POST です。 `UsersController::add()` のビューの中で `create()` を呼んだ場合、描画されたビューの中で次のような出力が表示されます。

    <form method="post" action="/users/add">

1  

`$context` 引数は、フォームの「コンテキスト」として使用されます。 いくつかの組み込みフォームのコンテキストがあり、独自に追加することができます。次のセクションで説明します。 組み込みのプロバイダーは、 `$context` の次の値とマップします。

*   `Entity` インスタンスまたはイテレーターは、 [EntityContext](https://api.cakephp.org/3.x/class-Cake.View.Form.EntityContext.html)
     にマップされます。このコンテキストは、FormHelper が組み込みの ORM の結果を処理できるようにします。
*   `schema` キーを含む配列は、 [ArrayContext](https://api.cakephp.org/3.x/class-Cake.View.Form.ArrayContext.html)
     にマップされます。これは単純なデータ構造を作成してフォームを構築することができます。
*   `null` と `false` は、 [NullContext](https://api.cakephp.org/3.x/class-Cake.View.Form.NullContext.html)
     にマップされます。 このコンテキストクラスは、FormHelper が必要とするインターフェイスを単に満たすだけです。 このコンテキストは、ORM の永続性を必要としない短いフォームを作成したい場合に便利です。

すべてのコンテキストクラスは、リクエストデータにアクセスできるため、フォームを簡単に作成できます。

コンテキストを持ったフォームが作成されると、作成したすべてのコントロールはアクティブなコンテキストを使用します。 ORM バックエンドフォームの場合、FormHelper は関連データ、検証エラー、およびスキーマメタデータに アクセスできます。 `end()` メソッドを使用したり、再度 `create()` を呼び出すことによって、 アクティブなコンテキストを閉じることができます。

エンティティーのフォームを作成するには、次の手順を実行します。 :

    // /articles/add において
    // $article は、空の Article エンティティーである必要があります。
    echo $this->Form->create($article);

1  
2  
3  

出力結果:

    <form method="post" action="/articles/add">

1  

これは ArticlesController の `add()` アクションにフォームデータを POST します。 また、編集フォームを作成するために、同じロジックを使用することができます。 FormHelper は、 _追加_ または _編集_ のフォームを作成するかどうかを自動的に検出するために、 `Entity` オブジェクトを使用します。 提供されたエンティティーが「新しくない」場合は、 _編集_ フォームとして作成されます。

例えば、 **[http://example.org/articles/edit/5](http://example.org/articles/edit/5)
** を閲覧すると、次のことができます。 :

    // src/Controller/ArticlesController.php:
    public function edit($id = null)
    {
        if (empty($id)) {
            throw new NotFoundException;
        }
        $article = $this->Articles->get($id);
        // 保存ロジックがここに入ります
        $this->set('article', $article);
    }
    
    // View/Articles/edit.ctp:
    // $article->isNew() は false なので、編集フォームが得られます
    <?= $this->Form->create($article) ?>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

出力結果:

    <form method="post" action="/articles/edit/5">
    <input type="hidden" name="_method" value="PUT" />

1  
2  

NOTE

これは _編集_ フォームなので、デフォルトの HTTP メソッドを上書きするために hidden `input` フィールドが生成されます。

場合によっては、フォームの `action` の URL の最後にエンティティーの ID が自動的に付加されます。 URL に ID が付加されることを避けたい場合、 `$options['url']` に `'/my-acount'` や `\Cake\Routing\Router::url(['controller' => 'Users', 'action' => 'myAccount'])` のように文字列を渡すことができます。

### フォーム作成のためのオプション [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%83%95%E3%82%A9%E3%83%BC%E3%83%A0%E4%BD%9C%E6%88%90%E3%81%AE%E3%81%9F%E3%82%81%E3%81%AE%E3%82%AA%E3%83%95%E3%82%9A%E3%82%B7%E3%83%A7%E3%83%B3)

`$options` 配列は、ほとんどのフォーム設定が行われる場所です。この特別な配列には、 form タグの生成方法に影響を与えるさまざまなキーと値のペアが含まれます。 有効な値:

*   `'type'` - 作成するフォームの種類を選択できます。type が未指定の場合、 フォームコンテキストに基づいて自動的に決まります。 有効な値:
    *   `'get'` - フォームの method に HTTP GET を設定します。
    *   `'file'` - フォームの method に POST を設定し、 `enctype` に "multipart/form-data" を設定します。
    *   `'post'` - method に POST を設定します。
    *   `'put', 'delete', 'patch'` - フォームの送信時に、HTTP メソッドを PUT、 DELETE もしくは PATCH に上書きします。
*   `'method'` - 有効な値は、上記と同じです。フォームの method を明示的に上書きできます。
*   `'url'` - フォームを送信する URL を指定します。文字列および URL 配列を指定できます。
*   `'encoding'` - フォームに `accept-charset` エンコーディングをセットします。 デフォルトは、 `Configure::read('App.encoding')` です。
*   `'enctype'` - 明示的にフォームのエンコーディングをセットできます。
*   `'templates'` - このフォームで使用したいテンプレート。指定したテンプレートは、 既に読み込まれたテンプレートの上にマージされます。 `/config` のファイル名 (拡張子を除く) か、 使用したいテンプレートの配列のいずれかを指定します。
*   `'context'` - フォームコンテキストクラスの追加オプション。(例えば、 `EntityContext` は、フォームのベースとなる特定の Table クラスを設定するための `'table'` オプションを受け付けます。)
*   `'idPrefix'` - 生成された ID 属性のプレフィックス。
*   `'templateVars'` - `formStart` テンプレートのためのテンプレート変数を提供することができます。
*   `autoSetCustomValidity` - コントロールの HTML5 検証メッセージでカスタム必須および notBlank 検証メッセージを使用するには、 `true` を設定します。デフォルトは `false` です。

TIP

上記のオプションの他に、 `$options` 引数の中で、 作成した `form` 要素に渡したい 有効な HTML 属性を指定できます。

### クエリー文字列からフォームの値を取得 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%82%AF%E3%82%A8%E3%83%AA%E3%83%BC%E6%96%87%E5%AD%97%E5%88%97%E3%81%8B%E3%82%89%E3%83%95%E3%82%A9%E3%83%BC%E3%83%A0%E3%81%AE%E5%80%A4%E3%82%92%E5%8F%96%E5%BE%97)

Added in version 3.4.0

FormHelper の値ソースは、input タグなどの描画される要素がどこから値を受け取るかを定義します。

デフォルトでは、FormHelper は、「コンテキスト」をもとにその値を描画します。 `EntityContext` などのデフォルトのコンテキストは、現在のエンティティーや `$request->getData()` からデータを取得します。

しかし、クエリー文字列から読み込む必要があるフォームを構築している場合は、 `FormHelper` の `valueSource()` を使って、どこから入力データを読み込むかを変更できます。 :

    // コンテキストでクエリー文字列の優先順位をつける
    echo $this->Form->create($article, [\
        'valueSources' => ['query', 'context']\
    ]);
    
    // 同じ効果:
    echo $this->Form
        ->setValueSources(['query', 'context'])
        ->create($articles);
    
    // クエリー文字列からのみのデータの読み取り
    echo $this->Form->create($article);
    $this->Form->setValueSources('query');
    
    // 同じ効果:
    echo $this->Form->create($article, ['valueSources' => 'query']);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  

サポートするソースは、 `context`, `data` そして `query` です。 単一または複数のソースを使用できます。 `FormHelper` によって生成されたウィジェットは 設定した順序でソースから値を集めます。

`end()` が呼ばれた時、値ソースはデフォルト (`['context']`) にリセットされます。

### フォームの HTTP メソッドを変更 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%83%95%E3%82%A9%E3%83%BC%E3%83%A0%E3%81%AE-http-%E3%83%A1%E3%82%BD%E3%83%83%E3%83%88%E3%82%99%E3%82%92%E5%A4%89%E6%9B%B4)

`type` オプションを使用することにより、フォームが使用する HTTP メソッドを変更することができます。 :

    echo $this->Form->create($article, ['type' => 'get']);

1  

出力結果:

    <form method="get" action="/articles/edit/5">

1  

`type` の値に `'file'` を指定すると、フォームの送信方法は、'POST' に変更し、form タグに "multipart/form-data" の `enctype` が含まれます。 これは、フォーム内部に file 要素がある場合に使用されます。 適切な `enctype` 属性が存在しない場合は、ファイルのアップロードが機能しない原因となります。

例:

    echo $this->Form->create($article, ['type' => 'file']);

1  

出力結果:

    <form enctype="multipart/form-data" method="post" action="/articles/add">

1  

`'type'` の値として `'put'` 、 `'patch'` または `'delete'` を使用すると、 フォームは機能的に 'post' フォームに相当しますが、送信されると、HTTP リクエストメソッドは、 それぞれ 'PUT'、 'PATCH' または 'DELETE' で上書きされます。 これで、CakePHP は、ウェブブラウザーで適切な REST サポートをエミュレートすることができます。

### フォームの URL を設定 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%83%95%E3%82%A9%E3%83%BC%E3%83%A0%E3%81%AE-url-%E3%82%92%E8%A8%AD%E5%AE%9A)

`url` オプションを使うと、フォームを現在のコントローラーやアプリケーションの別のコントローラーの 特定のアクションに向けることができます。

例えば、フォームを現在のコントローラーの `publish()` アクションに向けるには、次のような `$options` 配列を与えます。 :

    echo $this->Form->create($article, ['url' => ['action' => 'publish']]);

1  

出力結果:

    <form method="post" action="/articles/publish">

1  

目的のフォームアクションが現在のコントローラーにない場合は、フォームアクションの完全な URL を指定できます。 出力される URL は CakePHP アプリケーションに対する相対になります。 :

    echo $this->Form->create(null, [\
        'url' => [\
            'controller' => 'Articles',\
            'action' => 'publish'\
        ]\
    ]);

1  
2  
3  
4  
5  
6  

出力結果:

    <form method="post" action="/articles/publish">

1  

または外部ドメインを指定することができます。 :

    echo $this->Form->create(null, [\
        'url' => 'https://www.google.com/search',\
        'type' => 'get'\
    ]);

1  
2  
3  
4  

出力結果:

    <form method="get" action="https://www.google.com/search">

1  

フォームアクションに URL を出力したくない場合、 `'url' => false` を使用してください。

### カスタムバリデーターの利用 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%A0%E3%83%8F%E3%82%99%E3%83%AA%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%83%BC%E3%81%AE%E5%88%A9%E7%94%A8)

多くの場合、モデルには複数の検証セットがあり、コントローラーアクションが適用される 特定の検証ルールに基づいて必要なフィールドに FormHelper を設定する必要があります。 たとえば、Users テーブルには、アカウントの登録時にのみ適用される特定の検証ルールがあります。 :

    echo $this->Form->create($user, [\
        'context' => ['validator' => 'register']\
    ]);

1  
2  
3  

上記では `UsersTable::validationRegister()` で定義されている `register` バリデーターの中で定義されたルールを `$user` と関連するすべてのアソシエーションに使用します。 関連付けられたエンティティーのフォームを作成する場合は、配列を使用して各アソシエーションの検証ルールを 定義できます。 :

    echo $this->Form->create($user, [\
        'context' => [\
            'validator' => [\
                'Users' => 'register',\
                'Comments' => 'default'\
            ]\
        ]\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  

上記は、ユーザーには `register` 、そしてユーザーのコメントには `default` を使用します。

### コンテキストクラスの作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%82%B3%E3%83%B3%E3%83%86%E3%82%AD%E3%82%B9%E3%83%88%E3%82%AF%E3%83%A9%E3%82%B9%E3%81%AE%E4%BD%9C%E6%88%90)

組み込みのコンテキストクラスは基本的なケースをカバーすることを目的としていますが、 異なる ORM を使用している場合は新しいコンテキストクラスを作成する必要があります。 このような状況では、 [Cake\\View\\Form\\ContextInterface](https://api.cakephp.org/3.x/class-Cake.View.Form.ContextInterface.html)
 を実装する必要があります。 このインターフェイスを実装すると、新しいコンテキストを FormHelper に追加することができます。 `View.beforeRender` イベントリスナーやアプリケーションビュークラスで行うのが最善の方法です。 :

    $this->Form->addContextProvider('myprovider', function ($request, $data) {
        if ($data['entity'] instanceof MyOrmClass) {
            return new MyProvider($request, $data);
        }
    });

1  
2  
3  
4  
5  

コンテキストのファクトリー関数では、正しいエンティティータイプのフォームオプションを確認するための ロジックを追加できます。一致する入力データが見つかった場合は、オブジェクトを返すことができます。 一致するものがない場合は null を返します。

フォームコントロールの作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%83%95%E3%82%A9%E3%83%BC%E3%83%A0%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%AB%E3%81%AE%E4%BD%9C%E6%88%90)

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

`method` Cake\\View\\Helper\\FormHelper::**control**(string $fieldName, array $options = \[\])

*   `$fieldName` - `'Modelname.fieldname'` の形式のフィールド名。
*   `$options` - [Control Specific Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#control-specific-options)
     や (様々な HTML 要素を生成するために `control()` が内部的に使用する) 他のメソッドのオプション、および有効な HTML 属性を 含むオプション配列。

`control()` メソッドを使うと完全なフォームコントロールを生成できます。これらのコントロールには、 必要に応じて、囲い込む `div` 、 `label` 、コントロールウィジェット、および検証エラーが含まれます。 フォームコンテキストでメタデータを使用することにより、このメソッドは各フィールドに適切な コントロールタイプを選択します。内部的に `control()` は FormHelper の他のメソッドを使います。

TIP

`control()` メソッドによって生成されたフィールドは、このページでは一般的に "入力" と呼ばれますが、技術的にいえば、 `control()` メソッドは、 HTML の `input` 型の要素だけでなく、他の HTML フォーム要素 (`select` 、 `button` 、 `textarea` など) も生成できることに注意してください。

デフォルトでは、 `control()` メソッドは、次のウィジェットテンプレートを使用します。 :

    'inputContainer' => '<div class="input {{type}}{{required}}">{{content}}</div>'
    'input' => '<input type="{{type}}" name="{{name}}"{{attrs}}/>'

1  
2  

検証エラーが発生した場合は、以下も使われます。 :

    'inputContainerError' => '<div class="input {{type}}{{required}} error">{{content}}{{error}}</div>'

1  

作成されたコントロールの型（生成された要素タイプを指定する追加のオプションを指定しない場合）は、 モデルの内部で推測され、列のデータ型に依存します。

作成されるコントロールの型は、カラムのデータ型に依存します。

カラムの型  
得られたフォームのフィールド

string, uuid (char, varchar, その他)  
text

boolean, tinyint(1)  
checkbox

decimal  
number

float  
number

integer  
number

text  
textarea

text で、名前が password, passwd  
password

text で、名前が email  
email

text で、名前が tel, telephone, または phone  
tel

date  
day, month, および year の select

datetime, timestamp  
day, month, year, hour, minute, および meridian の select

time  
hour, minute, および meridian の select

binary  
file

`$options` パラメーターを使うと、必要な場合に特定のコントロールタイプを選択することができます。 :

    echo $this->Form->control('published', ['type' => 'checkbox']);

1  

TIP

とても些細なことですが、 `control()` フォームメソッドを使用して特定の要素を生成すると、 デフォルトでは `div` の囲い込みが常に生成されます。特定のフォームメソッド（例えば `$this->Form->checkbox('published');` ）を使用して同じタイプの要素を生成すると、 ほとんどの場合、 `div` の囲い込みが生成されません。 あなたのニーズに応じて、どちらかを使うことができます。

モデルのフィールドの検証ルールで入力が必須であり、空を許可しない場合は、囲い込む `div` は、 クラス名に `required` が追加されます。 `required` オプションを使用して自動的に必須フラグを無効にすることができます。 :

    echo $this->Form->control('title', ['required' => false]);

1  

フォーム全体のブラウザー検証トリガーをスキップするには、 `Cake\View\Helper\FormHelper::submit()` を使って生成する入力ボタンに対して `'formnovalidate' => true` オプションを設定したり、 `Cake\View\Helper\FormHelper::create()` のオプションで `'novalidate' => true` を設定できます。

たとえば、Users モデルに _username_ (varchar), _password_ (varchar), _approved_ (datetime) および _quote_ (text) のフィールドがあるとします。FormHelper の `control()` メソッドを使用すると、 これらのフォームフィールドすべてに適切なコントロールを作成できます。 :

    echo $this->Form->create($user);
    // 以下は、テキスト入力を生成します
    echo $this->Form->control('username');
    // 以下は、パスワード入力を生成します
    echo $this->Form->control('password');
    // 'approved' を datetime か timestamp フィールドとみなし、
    // 以下は、日・月・年・時・分を生成します
    echo $this->Form->control('approved');
    // 以下は、テキストエリア要素を生成します
    echo $this->Form->control('quote');
    
    echo $this->Form->button('Add');
    echo $this->Form->end();

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

日付フィールドのいくつかのオプションを示すより広範な例:

    echo $this->Form->control('birth_dt', [\
        'label' => '生年月日',\
        'minYear' => date('Y') - 70,\
        'maxYear' => date('Y') - 18,\
    ]);

1  
2  
3  
4  
5  

特定の [Control Specific Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#control-specific-options)
 に加えて、選択された (または CakePHP によって推論された) コントロールタイプや HTML 属性 (例えば `onfocus`) に対応する特定のメソッドによって 受け入れられるオプションを指定することができます。

_belongsTo_ または _hasOne_ を使用していて `select` フィールドを作成する場合は、 Users コントローラーに次のものを追加できます（User _belongsTo_ Group を前提とします）。 :

    $this->set('groups', $this->Users->Groups->find('list'));

1  

その後、ビューテンプレートに以下を追加します。 :

    echo $this->Form->control('group_id', ['options' => $groups]);

1  

_belongsToMany_ で関連付く Groups の `select` ボックスを作成するには、 UsersController に以下を追加します。 :

    $this->set('groups', $this->Users->Groups->find('list'));

1  

その後、ビューテンプレートに以下を追加します。 :

    echo $this->Form->control('groups._ids', ['options' => $groups]);

1  

モデル名が2つ以上の単語 (たとえば "UserGroup") で構成されている場合、 `set()` を使用してデータを渡すときは、データを次のように複数形と [ローワーキャメルケース](https://en.wikipedia.org/wiki/Camel_case#Variations_and_synonyms)
 で名前を付ける必要があります。 :

    $this->set('userGroups', $this->UserGroups->find('list'));

1  

NOTE

送信ボタンを生成するために `FormHelper::control()` を使用しないでください。 代わりに `Cake\View\Helper\FormHelper::submit()` を使用してください。

### フィールドの命名規則 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%83%95%E3%82%A3%E3%83%BC%E3%83%AB%E3%83%88%E3%82%99%E3%81%AE%E5%91%BD%E5%90%8D%E8%A6%8F%E5%89%87)

コントロールウィジェットを作成するときは、フィールドの名前をフォームのエンティティーに一致する属性の後に 指定する必要があります。たとえば、 `$article` エンティティーのフォームを作成した場合、 そのプロパティーの名前を付けたフィールドを作成します。例えば `title` 、 `body` と `published` 。

`association.fieldname` を最初のパラメーターとして渡すことで、関連するモデルや任意のモデルの コントロールを作成できます。 :

    echo $this->Form->control('association.fieldname');

1  

フィールド名のドットは、ネストされたリクエストデータに変換されます。 たとえば、 `0.comments.body` という名前のフィールドを作成した場合、 `0[comments][body]` のような名前属性が得られます。 この規則により、ORM でデータを簡単に保存できます。 さまざまなアソシエーションタイプの詳細は、 [Associated Form Inputs](https://book.cakephp.org/3.x/ja/views/helpers/form.html#associated-form-inputs)
 セクションにあります。

datetime に関連するコントロールを作成する場合、FormHelper はフィールドのサフィックスを追加します。 `year` 、 `month` 、 `day` 、 `hour` 、 `minute` 、または `meridian` というフィールドが追加されていることがあります。エンティティーがマーシャリングされると、 これらのフィールドは自動的に `DateTime` オブジェクトに変換されます。

### コントロールのオプション [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%AB%E3%81%AE%E3%82%AA%E3%83%95%E3%82%9A%E3%82%B7%E3%83%A7%E3%83%B3)

`FormHelper::control()` は、その `$options` 引数を通して、多数のオプションをサポートしています。 `control()` 自身のオプションに加えて、生成されたコントロールタイプに対するオプションと HTML 属性を受け付けます。以下は `FormHelper::control()` で特有のオプションについて説明します。

*   `$options['type']` - 生成するためのウィジェットタイプを指定する文字列。 [Automagic Form Elements](https://book.cakephp.org/3.x/ja/views/helpers/form.html#automagic-form-elements)
     にあるフィールド型に加えて、 `'file'` 、 `'password'` 、 および HTML5 でサポートされているすべてのタイプを作成することもできます。 `'type'` を指定することで、モデルの設定を上書きして、コントロールのタイプを強制することができます。 デフォルトは `null` 。
    
    例:
    
        echo $this->Form->control('field', ['type' => 'file']);
        echo $this->Form->control('email', ['type' => 'email']);
    
    1  
    2  
    
    出力結果:
    
        <div class="input file">
            <label for="field">Field</label>
            <input type="file" name="field" value="" id="field" />
        </div>
        <div class="input email">
            <label for="email">Email</label>
            <input type="email" name="email" value="" id="email" />
        </div>
    
    1  
    2  
    3  
    4  
    5  
    6  
    7  
    8  
    
*   `$options['label']` - 文字列の見出しや [ラベルのオプション](https://book.cakephp.org/3.x/ja/views/helpers/form.html#create-label)
     の配列。 このキーは、通常は `input` HTML 要素に付随するラベル内に表示したい文字列に設定することができます。 デフォルトは `null` です。
    
    例:
    
        echo $this->Form->control('name', [\
            'label' => 'The User Alias'\
        ]);
    
    1  
    2  
    3  
    
    出力結果:
    
        <div class="input">
            <label for="name">The User Alias</label>
            <input name="name" type="text" value="" id="name" />
        </div>
    
    1  
    2  
    3  
    4  
    
    あるいは、 `label` 要素の出力を無効にするには、このキーに `false` を設定します。
    
    例:
    
        echo $this->Form->control('name', ['label' => false]);
    
    1  
    
    出力結果:
    
        <div class="input">
            <input name="name" type="text" value="" id="name" />
        </div>
    
    1  
    2  
    3  
    
    これに配列を設定すると、 `label` 要素の追加オプションが提供されます。 これを行う場合、配列中の `text` キーを使ってラベルテキストをカスタマイズすることができます。
    
    例:
    
        echo $this->Form->control('name', [\
            'label' => [\
                'class' => 'thingy',\
                'text' => 'The User Alias'\
            ]\
        ]);
    
    1  
    2  
    3  
    4  
    5  
    6  
    
    出力結果:
    
        <div class="input">
            <label for="name" class="thingy">The User Alias</label>
            <input name="name" type="text" value="" id="name" />
        </div>
    
    1  
    2  
    3  
    4  
    
*   `$options['options']` - ここには、アイテムの配列を引数として必要とする `radio` や `select` のようなウィジェットのために、生成される要素を含む配列を提供することができます (詳細は、 [Create Radio Button](https://book.cakephp.org/3.x/ja/views/helpers/form.html#create-radio-button)
     と [Create Select Picker](https://book.cakephp.org/3.x/ja/views/helpers/form.html#create-select-picker)
     をご覧ください)。 デフォルトは、 `null` です。
    
*   `$options['error']` - このキーを使用すると、デフォルトのモデルエラーメッセージを 無効にすることができ、たとえば国際化メッセージを設定するために使用できます。 エラーメッセージの出力とフィールドクラスを無効にするには、 `'error'` キーを `false` に設定してください。デフォルトは `null` 。
    
    例:
    
        echo $this->Form->control('name', ['error' => false]);
    
    1  
    
    モデルのエラーメッセージを上書きするには、 元の検証エラーメッセージと一致するキーを持つ配列を使用します。
    
    例:
    
        $this->Form->control('name', [\
            'error' => ['Not long enough' => __('This is not long enough')]\
        ]);
    
    1  
    2  
    3  
    
    上記のように、モデルにある各検証ルールに対してエラーメッセージを設定することができます。 さらに、フォームに国際化メッセージを提供することもできます。
    
*   `$options['nestedInput']` - チェックボックスとラジオボタンで使用。 input 要素を `label` 要素の内側か外側に生成するかどうかを制御します。 `control()` がチェックボックスやラジオボタンを生成する時、これに `false` を設定して、 `label` 要素の外側に HTML の `input` 要素を強制的に生成することができます。
    
    一方、任意のコントロールタイプに対して、これを `true` に設定することで、 生成された input 要素をラベルの中に強制的に入れることができます。 これをラジオボタンで変更する場合は、デフォルトの [radioWrapper](https://book.cakephp.org/3.x/ja/views/helpers/form.html#create-radio-button)
     テンプレートも変更する必要があります。生成されるコントロールタイプによっては、 デフォルトが `true` や `false` になります。
    
*   `$options['templates']` - この入力に使用するテンプレート。 指定したテンプレートは、既に読み込まれたテンプレートの上にマージされます。 このオプションは、ロードするテンプレートを含む `/config` のファイル名 (拡張子を除く) か、 使用するテンプレートの配列のいずれかです。
    
*   `$options['labelOptions']` - これを `false` に設定すると nestedWidgets の周りのラベルを無効にします。または、 `label` タグに提供される属性の配列を設定します。
    

コントロールの特定のタイプを生成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%AB%E3%81%AE%E7%89%B9%E5%AE%9A%E3%81%AE%E3%82%BF%E3%82%A4%E3%83%95%E3%82%9A%E3%82%92%E7%94%9F%E6%88%90)

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

汎用的な `control()` メソッドに加えて、 `FormHelper` には様々な種類の コントロールタイプを生成するために個別のメソッドがあります。 これらは、コントロールウィジェットそのものを生成するのに使えますが、 完全に独自のフォームレイアウトを生成するために `Cake\View\Helper\FormHelper::label()` や `Cake\View\Helper\FormHelper::error()` といった 他のメソッドを組み合わせることができます。

### 特定のコントロールのための共通オプション [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E7%89%B9%E5%AE%9A%E3%81%AE%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%AB%E3%81%AE%E3%81%9F%E3%82%81%E3%81%AE%E5%85%B1%E9%80%9A%E3%82%AA%E3%83%95%E3%82%9A%E3%82%B7%E3%83%A7%E3%83%B3)

さまざまなコントロール要素メソッドは、共通のオプションをサポートしており、 使用されるフォームメソッドに応じて、 `$options` または `$attributes` 配列の引数の中に 指定する必要があります。これらのオプションはすべて、 `control()` でもサポートされています。 繰り返しを減らすために、すべてのコントロールメソッドで共有される共通オプションは次の通りです。

*   `'id'` - このキーを設定すると、コントロールの DOM id の値が強制的に設定されます。 これにより、設定可能な `'idPrefix'` が上書きされます。
    
*   `'default'` コントロールフィールドのデフォルト値を設定します。 この値は、フォームに渡されるデータにそのフィールドに関する値が含まれていない場合 (または、一切データが渡されない場合) に使われます。 明示的なデフォルト値は、スキーマで定義されたデフォルト値を上書きします。
    
    使用例:
    
        echo $this->Form->text('ingredient', ['default' => 'Sugar']);
    
    1  
    
    `select` フィールドを持つ例（"Medium" サイズがデフォルトで選択されます） :
    
        $sizes = ['s' => 'Small', 'm' => 'Medium', 'l' => 'Large'];
        echo $this->Form->select('size', $sizes, ['default' => 'm']);
    
    1  
    2  
    
    NOTE
    
    checkbox をチェックする目的では `default` は使えません。その代わり、コントローラーで `$this->request->getData()` の中の値をセットするか、またはコントロールオプションの `checked` を `true` にします。
    
    デフォルト値への代入の際 `false` を使うのは注意が必要です。 `false` 値はコントロールフィールドのオプションを無効または除外するために使われます。 そのため `'default' => false` では値を全く設定しません。 代わりに `'default' => 0` を使用してください。
    
*   `'value'` - コントロールフィールドに特定の値を設定するために使用します。 これは、Form、Entity、 `request->getData()` などのコンテキストから 注入される可能性のある値を上書きします。
    
    NOTE
    
    コンテキストや valuesSource から値を取得しないようにフィールドを設定したい場合、 `'value'` を `''` に設定する必要があります (もしくは `null` に設定) 。
    

上記のオプションに加えて、任意の HTML 属性を混在させることができます。 特に規定のないオプション名は HTML 属性として扱われ、生成された HTML のコントロール要素に反映されます。

Changed in version 3.3.0

3.3.0 では、FormHelper は、自動的にデータベーススキーマで定義されたデフォルト値を使用します。 `schemaDefault` オプションを `false` に設定することで、この動作を無効にすることができます。

input 要素の作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#input-%E8%A6%81%E7%B4%A0%E3%81%AE%E4%BD%9C%E6%88%90)

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

FormHelper で利用可能なメソッドには、さらに特定のフォーム要素を作成するためのものがあります。 これらのメソッドの多くでは、特別な `$options` や `$attributes` パラメーターを指定できます。 ただし、この場合、このパラメーターは主に (フォーム要素の DOM id の値のような) HTML タグの属性を 指定するために使われます。

### テキスト入力の作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%83%86%E3%82%AD%E3%82%B9%E3%83%88%E5%85%A5%E5%8A%9B%E3%81%AE%E4%BD%9C%E6%88%90)

`method` Cake\\View\\Helper\\FormHelper::**text**(string $name, array $options)

*   `$name` - `'Modelname.fieldname'` の形式のフィールド名。
*   `$options` - [General Control Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#general-control-options)
     や有効な HTML 属性を含むオプション配列。

シンプルな `text` 型の `input` HTML 要素を作成します。

例:

    echo $this->Form->text('username', ['class' => 'users']);

1  

出力結果:

    <input name="username" type="text" class="users">

1  

### パスワード入力の作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%83%8F%E3%82%9A%E3%82%B9%E3%83%AF%E3%83%BC%E3%83%88%E3%82%99%E5%85%A5%E5%8A%9B%E3%81%AE%E4%BD%9C%E6%88%90)

`method` Cake\\View\\Helper\\FormHelper::**password**(string $fieldName, array $options)

*   `$fieldName` - `'Modelname.fieldname'` の形式のフィールド名。
*   `$options` - [General Control Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#general-control-options)
     や有効な HTML 属性を含むオプション配列。

シンプルな `password` 型の `input` 要素を作成します。

例:

    echo $this->Form->password('password');

1  

出力結果:

    <input name="password" value="" type="password">

1  

### 非表示入力の作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E9%9D%9E%E8%A1%A8%E7%A4%BA%E5%85%A5%E5%8A%9B%E3%81%AE%E4%BD%9C%E6%88%90)

`method` Cake\\View\\Helper\\FormHelper::**hidden**(string $fieldName, array $options)

*   `$fieldName` - `'Modelname.fieldname'` の形式のフィールド名。
*   `$options` - [General Control Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#general-control-options)
     や有効な HTML 属性を含むオプション配列。

非表示のフォーム入力を作成します。

例:

    echo $this->Form->hidden('id');

1  

出力結果:

    <input name="id" value="10" type="hidden" />

1  

### テキストエリアの作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%83%86%E3%82%AD%E3%82%B9%E3%83%88%E3%82%A8%E3%83%AA%E3%82%A2%E3%81%AE%E4%BD%9C%E6%88%90)

`method` Cake\\View\\Helper\\FormHelper::**textarea**(string $fieldName, array $options)

*   `$fieldName` - `'Modelname.fieldname'` の形式のフィールド名。
*   `$options` - [General Control Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#general-control-options)
     やテキストエリア特有のオプション (下記参照) と、有効な HTML 属性を含むオプション配列。

textarea コントロールフィールドを作成します。使用されるデフォルトのウィジェットテンプレートは、 :

    'textarea' => '<textarea name="{{name}}"{{attrs}}>{{value}}</textarea>'

1  

例:

    echo $this->Form->textarea('notes');

1  

出力結果:

    <textarea name="notes"></textarea>

1  

フォームが編集されると（すなわち、配列 `$this->request->getData()` に `User` モデルに渡すために保存された情報が含まれている場合）、生成される HTML には `notes` フィールドに対応する値が自動的に含まれます。

例:

    <textarea name="notes" id="notes">
    このテキストは編集されます。
    </textarea>

1  
2  
3  

**テキストエリアのオプション**

[General Control Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#general-control-options)
 に加えて、 `textarea()` はいくつかの固有のオプションを サポートします。

*   `'escape'` - テキストエリアの内容をエスケープするかどうかを指定します。 デフォルトは `true` です。
    
    例:
    
        echo $this->Form->textarea('notes', ['escape' => false]);
        // もしくは....
        echo $this->Form->control('notes', ['type' => 'textarea', 'escape' => false]);
    
    1  
    2  
    3  
    
*   `'rows', 'cols'` - これらの2つのキーを使用して、 `textarea` フィールドの行数と列数を 指定する HTML 属性を設定することができます。
    
    例:
    
        echo $this->Form->textarea('comment', ['rows' => '5', 'cols' => '5']);
    
    1  
    
    出力結果:
    
        <textarea name="comment" cols="5" rows="5">
        </textarea>
    
    1  
    2  
    

### セレクト、チェックボックス、ラジオコントロールの作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%82%BB%E3%83%AC%E3%82%AF%E3%83%88%E3%80%81%E3%83%81%E3%82%A7%E3%83%83%E3%82%AF%E3%83%9B%E3%82%99%E3%83%83%E3%82%AF%E3%82%B9%E3%80%81%E3%83%A9%E3%82%B7%E3%82%99%E3%82%AA%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%AB%E3%81%AE%E4%BD%9C%E6%88%90)

これらのコントロールは、いくつかの共通点といくつかのオプションを共有し、 それらは簡単に参照するために、このサブセクションで全てグループ化します。

#### セレクト、チェックボックス、ラジオに関するオプション [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%82%BB%E3%83%AC%E3%82%AF%E3%83%88%E3%80%81%E3%83%81%E3%82%A7%E3%83%83%E3%82%AF%E3%83%9B%E3%82%99%E3%83%83%E3%82%AF%E3%82%B9%E3%80%81%E3%83%A9%E3%82%B7%E3%82%99%E3%82%AA%E3%81%AB%E9%96%A2%E3%81%99%E3%82%8B%E3%82%AA%E3%83%95%E3%82%9A%E3%82%B7%E3%83%A7%E3%83%B3)

`select()` 、 `checkbox()` そして `radio()` によって共有されるオプションは次の通りです。 (各メソッドの独自のセクションには、そのメソッド特有のオプションが記述されています。)

*   `'value'` - 影響を受ける要素の値を設定または選択します。
    
    *   チェックボックスの場合、 `input` 要素に割り当てられた HTML の `'value'` 属性を、 値として提供するものに設定します。
        
    *   ラジオボタンまたは選択ピッカーの場合は、フォームが描画されるときに選択される要素を定義します (この場合、 `'value'` は有効で存在する要素の値を割り当てなければなりません)。 `date()` 、 `time()` 、 `dateTime()` のようなセレクト型コントロールと 組み合わせて使用することもできます。 :
        
            echo $this->Form->time('close_time', [\
                'value' => '13:30:00'\
            ]);
        
        1  
        2  
        3  
        
    
    NOTE
    
    `date()` および `dateTime()` コントロールの `'value'` キーには、 UNIX タイムスタンプまたは DateTime オブジェクトを使用することもできます。
    
    `multiple` 属性を `true` に設定した `select` コントロールでは、 デフォルトで選択したい値の配列を使うことができます。 :
    
        // 値に 1 と 3 を持つ HTML <option> 要素が事前選択されて描画されます。
        echo $this->Form->select(
            'rooms',
            [1, 2, 3, 4, 5],
            [\
                'multiple' => true,\
                'value' => [1, 3]\
            ]
        );
    
    1  
    2  
    3  
    4  
    5  
    6  
    7  
    8  
    9  
    
*   `'empty'` - `radio()` と `select()` に適用します。デフォルトは `false` です。
    
    *   `radio()` に渡して `true` を設定すると、最初のラジオボタンとして追加の入力要素を作成し、 値を `''` に、ラベルを `'empty'` にします。ラベルキャプションを制御する場合は、 このオプションを文字列に設定します。
        
    *   `select` メソッドに渡されると、ドロップダウンリストに空の値を持つ空白の HTML `option` 要素が作成されます。空の値を空の `option` の代わりに表示させたい場合は、 `'empty'` に文字列を渡します。 :
        
            echo $this->Form->select(
                'field',
                [1, 2, 3, 4, 5],
                ['empty' => '(一つ選ぶ)']
            );
        
        1  
        2  
        3  
        4  
        5  
        
        出力結果:
        
            <select name="field">
                <option value="">(一つ選ぶ)</option>
                <option value="0">1</option>
                <option value="1">2</option>
                <option value="2">3</option>
                <option value="3">4</option>
                <option value="4">5</option>
            </select>
        
        1  
        2  
        3  
        4  
        5  
        6  
        7  
        8  
        
*   `'hiddenField'` - チェックボックスとラジオボタンの場合、デフォルトでは、 メインの要素とともに hidden `input` 要素も作成されます。そのため、 値の指定がなくても、 `$this->request->getData()` の中のキーは必ず存在します。 その値のデフォルトは、チェックボックスの場合は `0` 、ラジオボタンの場合は `''` です。
    
    デフォルト出力の例:
    
        <input type="hidden" name="published" value="0" />
        <input type="checkbox" name="published" value="1" />
    
    1  
    2  
    
    これは `'hiddenField'` を `false` とすることで無効にできます。 :
    
        echo $this->Form->checkbox('published', ['hiddenField' => false]);
    
    1  
    
    出力結果:
    
        <input type="checkbox" name="published" value="1">
    
    1  
    
    フォーム上に複数のコントロールブロックを作成してグループ化する場合は、 最初のコントロールを除くすべての入力で、このパラメーターを `false` に設定する必要があります。 hidden 入力がページ上の複数の場所にある場合は、入力値の最後のグループだけが保存されます。
    
    この例では Tertiary Colors だけが渡され、Primary Colors は上書きされます。
    
        <h2>Primary Colors</h2>
        <input type="hidden" name="color" value="0" />
        <label for="color-red">
            <input type="checkbox" name="color[]" value="5" id="color-red" />
            Red
        </label>
        
        <label for="color-blue">
            <input type="checkbox" name="color[]" value="5" id="color-blue" />
            Blue
        </label>
        
        <label for="color-yellow">
            <input type="checkbox" name="color[]" value="5" id="color-yellow" />
            Yellow
        </label>
        
        <h2>Tertiary Colors</h2>
        <input type="hidden" name="color" value="0" />
        <label for="color-green">
            <input type="checkbox" name="color[]" value="5" id="color-green" />
            Green
        </label>
        <label for="color-purple">
            <input type="checkbox" name="color[]" value="5" id="color-purple" />
            Purple
        </label>
        <label for="color-orange">
            <input type="checkbox" name="color[]" value="5" id="color-orange" />
            Orange
        </label>
    
    1  
    2  
    3  
    4  
    5  
    6  
    7  
    8  
    9  
    10  
    11  
    12  
    13  
    14  
    15  
    16  
    17  
    18  
    19  
    20  
    21  
    22  
    23  
    24  
    25  
    26  
    27  
    28  
    29  
    30  
    31  
    
    2番目の入力グループで `'hiddenField'` を無効にすると、この動作を防ぐことができます。
    
    'N' のように 0 以外の別の hidden フィールド値を設定することができます。 :
    
        echo $this->Form->checkbox('published', [\
            'value' => 'Y',\
            'hiddenField' => 'N',\
        ]);
    
    1  
    2  
    3  
    4  
    

#### オプションの作成にコレクションを使用 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%82%AA%E3%83%95%E3%82%9A%E3%82%B7%E3%83%A7%E3%83%B3%E3%81%AE%E4%BD%9C%E6%88%90%E3%81%AB%E3%82%B3%E3%83%AC%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3%E3%82%92%E4%BD%BF%E7%94%A8)

オプション配列の作成に Collection クラスを使うことができます。 この方法は、すでにエンティティーのコレクションを持っていて、 そこから select 要素を作成したい場合に理想的です。

`combine` メソッドを使って、基本的なオプションの配列を作ることができます。 :

    $options = $examples->combine('id', 'name');

1  

配列を拡張して特別な属性を追加することもできます。 以下は、 コレクションの `map` メソッドを使って option 要素にデータ属性を作成します。 :

    $options = $examples->map(function ($value, $key) {
        return [\
            'value' => $value->id,\
            'text' => $value->name,\
            'data-created' => $value->created\
        ];
    });

1  
2  
3  
4  
5  
6  
7  

#### チェックボックスの作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%83%81%E3%82%A7%E3%83%83%E3%82%AF%E3%83%9B%E3%82%99%E3%83%83%E3%82%AF%E3%82%B9%E3%81%AE%E4%BD%9C%E6%88%90)

`method` Cake\\View\\Helper\\FormHelper::**checkbox**(string $fieldName, array $options)

*   `$fieldName` - `'Modelname.fieldname'` の形式のフィールド名。
*   `$options` - 上記の [General Control Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#general-control-options)
     または [Checkbox Radio Select Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#checkbox-radio-select-options)
     、チェックボックス特有のオプション (下記参照) と有効な HTML 属性を含むオプション配列。

`checkbox` フォーム要素を作成します。使用されるウィジェットテンプレートは、 :

    'checkbox' => '<input type="checkbox" name="{{name}}" value="{{value}}"{{attrs}}>'

1  

**チェックボックスのオプション**

*   `'checked'` - このチェックボックスをオンにするかどうかを示すブール値。 デフォルトは `false` です。
*   `'disabled'` - 入力不可のチェックボックスを作成。

このメソッドは、関連する隠しフォームの `input` 要素も生成し、 指定されたフィールドのデータの送信を強制します。

例:

    echo $this->Form->checkbox('done');

1  

出力結果:

    <input type="hidden" name="done" value="0">
    <input type="checkbox" name="done" value="1">

1  
2  

`$options` 配列を使って checkbox の値を指定することもできます。

例:

    echo $this->Form->checkbox('done', ['value' => 555]);

1  

出力結果:

    <input type="hidden" name="done" value="0">
    <input type="checkbox" name="done" value="555">

1  
2  

FormHelper で hidden 入力を作成したくない場合は、 `'hiddenField'` を使います。

例:

    echo $this->Form->checkbox('done', ['hiddenField' => false]);

1  

出力結果:

    <input type="checkbox" name="done" value="1">

1  

#### ラジオボタンの作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%83%A9%E3%82%B7%E3%82%99%E3%82%AA%E3%83%9B%E3%82%99%E3%82%BF%E3%83%B3%E3%81%AE%E4%BD%9C%E6%88%90)

`method` Cake\\View\\Helper\\FormHelper::**radio**(string $fieldName, array $options, array $attributes)

*   `$fieldName` - `'Modelname.fieldname'` の形式のフィールド名。
*   `$options` - 少なくともラジオボタンのラベルを含むオプション配列。 値や HTML 属性を含むこともできます。この配列がない場合、メソッドは hidden 入力 を生成する (`'hiddenField'` が `true` の場合)、または全く要素がない (`'hiddenField'` が `false` の場合) かのいずれかです。
*   `$attributes` - [General Control Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#general-control-options)
     または [Checkbox Radio Select Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#checkbox-radio-select-options)
     、ラジオボタン特有の属性 (下記参照)と 有効な HTML 属性を含むオプション配列。

radio ボタン入力を作成します。使用されるデフォルトのウィジェットテンプレートは、 :

    'radio' => '<input type="radio" name="{{name}}" value="{{value}}"{{attrs}}>'
    'radioWrapper' => '{{label}}'

1  
2  

**ラジオボタンの属性**

*   `'label'` - ウィジェットのラベルを表示するかどうかを示すブール値、または、全てのラベルに適用する 属性の配列。 `class` 属性が定義されている場合、チェックされたボタンの `class` 属性に `selected` が追加されます。デフォルトは `true` 。
*   `'hiddenField'` - `true` に設定すると、 `''` の値を持つ非表示の入力がインクルードされます。 これは、非連続的なラジオセットを作成する場合に便利です。デフォルトは `true` 。
*   `'disabled'` - すべてのラジオボタンを無効にするには `true` または `'disabled'` に設定します。デフォルトは `false` 。

`$options` 引数を通してラジオボタンのラベルの見出しを指定してください。

例:

    $this->Form->radio('gender', ['Masculine','Feminine','Neuter']);

1  

出力結果:

    <input name="gender" value="" type="hidden">
    <label for="gender-0">
        <input name="gender" value="0" id="gender-0" type="radio">
        Masculine
    </label>
    <label for="gender-1">
        <input name="gender" value="1" id="gender-1" type="radio">
        Feminine
    </label>
    <label for="gender-2">
        <input name="gender" value="2" id="gender-2" type="radio">
        Neuter
    </label>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

一般に `$options` は単純な `キー => 値` のペアです。 ただし、カスタム属性をラジオボタンに配置する必要がある場合は、拡張形式を使用することができます。

例:

    echo $this->Form->radio(
        'favorite_color',
        [\
            ['value' => 'r', 'text' => 'Red', 'style' => 'color:red;'],\
            ['value' => 'u', 'text' => 'Blue', 'style' => 'color:blue;'],\
            ['value' => 'g', 'text' => 'Green', 'style' => 'color:green;'],\
        ]
    );

1  
2  
3  
4  
5  
6  
7  
8  

出力結果:

    <input type="hidden" name="favorite_color" value="">
    <label for="favorite-color-r">
        <input type="radio" name="favorite_color" value="r" style="color:red;" id="favorite-color-r">
        Red
    </label>
    <label for="favorite-color-u">
        <input type="radio" name="favorite_color" value="u" style="color:blue;" id="favorite-color-u">
        Blue
    </label>
    <label for="favorite-color-g">
        <input type="radio" name="favorite_color" value="g" style="color:green;" id="favorite-color-g">
        Green
    </label>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

#### 選択ピッカーの作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E9%81%B8%E6%8A%9E%E3%83%92%E3%82%9A%E3%83%83%E3%82%AB%E3%83%BC%E3%81%AE%E4%BD%9C%E6%88%90)

`method` Cake\\View\\Helper\\FormHelper::**select**(string $fieldName, array $options, array $attributes)

*   `$fieldName` - `'Modelname.fieldname'` の形式のフィールド名。 これは、 `select` 要素の `name` 属性を提供します。
*   `$options` - 選択ピッカーの項目のリストを含むオプション配列。 この配列がない場合、メソッドは、中に `option` 要素が一つもない空の `select` HTML 要素のみを生成します。
*   `$attributes` - [General Control Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#general-control-options)
     または [Checkbox Radio Select Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#checkbox-radio-select-options)
     または select 特有のオプション (下記参照)と、 有効な HTML 属性を含むオプション配列。

`$options` 配列の項目で設定された `select` 要素を作成します。 `$attributes['value']` が提供された場合、指定された値を持つ HTML `option` 要素が 選択ピッカーが描画される際に選択されて表示されます。

デフォルトでは、 `select` は次のウィジェットテンプレートを使用します。 :

    'select' => '<select name="{{name}}"{{attrs}}>{{content}}</select>'
    'option' => '<option value="{{value}}"{{attrs}}>{{text}}</option>'

1  
2  

以下も使用します。 :

    'optgroup' => '<optgroup label="{{label}}"{{attrs}}>{{content}}</optgroup>'
    'selectMultiple' => '<select name="{{name}}[]" multiple="multiple"{{attrs}}>{{content}}</select>'

1  
2  

**選択ピッカーの属性**

*   `'multiple'` - `true` をセットすると、選択ピッカー内で複数選択ができます。 `'checkbox'` をセットすると、複数チェックボックスが代わりに作成されます。 デフォルトは `null` です。
*   `'escape'` - ブール値。 `true` の場合、選択ピッカー内の `option` 要素の内容は エンコードされた HTML エンティティーになります。デフォルトは `true` です。
*   `'val'` - 選択ピッカーで値を事前に選択できるようにします。
*   `'disabled'` - `disabled` 属性を制御します。 `true` をセットした場合、選択ピッカー全体を無効にします。 配列をセットした場合、配列に含まれている値を持つ特定の `option` のみ無効にします。

`$options` 引数は、 `select` コントロールの `option` 要素の内容を手動で指定できます。

例:

    echo $this->Form->select('field', [1, 2, 3, 4, 5]);

1  

出力結果:

    <select name="field">
        <option value="0">1</option>
        <option value="1">2</option>
        <option value="2">3</option>
        <option value="3">4</option>
        <option value="4">5</option>
    </select>

1  
2  
3  
4  
5  
6  
7  

`$options` の配列はキーと値のペアとしても指定することができます。

例:

    echo $this->Form->select('field', [\
        'Value 1' => 'Label 1',\
        'Value 2' => 'Label 2',\
        'Value 3' => 'Label 3'\
    ]);

1  
2  
3  
4  
5  

出力結果:

    <select name="field">
        <option value="Value 1">Label 1</option>
        <option value="Value 2">Label 2</option>
        <option value="Value 3">Label 3</option>
    </select>

1  
2  
3  
4  
5  

optgroup 付きで `select` を生成したい場合は、データを階層形式 (ネストした配列) で渡すだけです。 これは複数のチェックボックスとラジオボタンでも機能しますが、 `optgroup` の代わりに `fieldset` 要素で囲みます。

例:

    $options = [\
        'Group 1' => [\
            'Value 1' => 'Label 1',\
            'Value 2' => 'Label 2'\
        ],\
        'Group 2' => [\
            'Value 3' => 'Label 3'\
        ]\
    ];
    echo $this->Form->select('field', $options);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

出力結果:

    <select name="field">
        <optgroup label="Group 1">
            <option value="Value 1">Label 1</option>
            <option value="Value 2">Label 2</option>
        </optgroup>
        <optgroup label="Group 2">
            <option value="Value 3">Label 3</option>
        </optgroup>
    </select>

1  
2  
3  
4  
5  
6  
7  
8  
9  

`option` タグ内で HTML 属性を生成するには:

    $options = [\
        [ 'text' => 'Description 1', 'value' => 'value 1', 'attr_name' => 'attr_value 1' ],\
        [ 'text' => 'Description 2', 'value' => 'value 2', 'attr_name' => 'attr_value 2' ],\
        [ 'text' => 'Description 3', 'value' => 'value 3', 'other_attr_name' => 'other_attr_value' ],\
    ];
    echo $this->Form->select('field', $options);

1  
2  
3  
4  
5  
6  

出力結果:

    <select name="field">
        <option value="value 1" attr_name="attr_value 1">Description 1</option>
        <option value="value 2" attr_name="attr_value 2">Description 2</option>
        <option value="value 3" other_attr_name="other_attr_value">Description 3</option>
    </select>

1  
2  
3  
4  
5  

**属性による選択ピッカーの制御**

`$attributes` パラメーター内の特定のオプションを使用することにより、 `select()` メソッドの特定の振る舞いを制御することができます。

*   `'empty'` - `$attributes` 引数の中で `'empty'` キーを `true` にセットすると (デフォルトの値は `false`)、ドロップダウンリストの先頭に空の値の空白オプションを追加できます。
    
    例:
    
        $options = ['M' => 'Male', 'F' => 'Female'];
        echo $this->Form->select('gender', $options, ['empty' => true]);
    
    1  
    2  
    
    出力結果:
    
        <select name="gender">
            <option value=""></option>
            <option value="M">Male</option>
            <option value="F">Female</option>
        </select>
    
    1  
    2  
    3  
    4  
    5  
    
*   `'escape'` - `select()` メソッドは `'escape'` という属性が使用でき、 ブール値を受け取り、HTML エンティティーに select オプションの内容をエンコードするかどうかを決定します。
    
    例:
    
        // これで、各オプション要素の内容の HTML エンコードを止められます
        $options = ['M' => 'Male', 'F' => 'Female'];
        echo $this->Form->select('gender', $options, ['escape' => false]);
    
    1  
    2  
    3  
    
*   `'multiple'` - `true` にセットすると、選択ピッカーは複数選択ができます。
    
    例:
    
        echo $this->Form->select('field', $options, ['multiple' => true]);
    
    1  
    
    または、関連するチェックボックスのリストを出力するために `'multiple'` を `'checkbox'` に設定します。 :
    
        $options = [\
            'Value 1' => 'Label 1',\
            'Value 2' => 'Label 2'\
        ];
        echo $this->Form->select('field', $options, [\
            'multiple' => 'checkbox'\
        ]);
    
    1  
    2  
    3  
    4  
    5  
    6  
    7  
    
    出力結果:
    
        <input name="field" value="" type="hidden">
        <div class="checkbox">
          <label for="field-1">
           <input name="field[]" value="Value 1" id="field-1" type="checkbox">
           Label 1
           </label>
        </div>
        <div class="checkbox">
           <label for="field-2">
           <input name="field[]" value="Value 2" id="field-2" type="checkbox">
           Label 2
           </label>
        </div>
    
    1  
    2  
    3  
    4  
    5  
    6  
    7  
    8  
    9  
    10  
    11  
    12  
    13  
    
*   `'disabled'` - このオプションを設定して、すべてまたは一部の `select` の `option` 項目を 無効にすることができます。すべての項目を無効にするには、 `'disabled'` に `true` を 設定します。特定の項目のみを無効にするには、無効にする項目をキーに含む配列を `'disabled'` に 設定してください。
    
    すべてのチェックボックスを無効にするには disabled を `true` にします。
    
    例:
    
        $options = [\
            'M' => 'Masculine',\
            'F' => 'Feminine',\
            'N' => 'Neuter'\
        ];
        echo $this->Form->select('gender', $options, [\
            'disabled' => ['M', 'N']\
        ]);
    
    1  
    2  
    3  
    4  
    5  
    6  
    7  
    8  
    
    出力結果:
    
        <select name="gender">
            <option value="M" disabled="disabled">Masculine</option>
            <option value="F">Feminine</option>
            <option value="N" disabled="disabled">Neuter</option>
        </select>
    
    1  
    2  
    3  
    4  
    5  
    
    このオプションは `'multiple'` が `'checkbox'` に設定されている場合にも有効です。 :
    
        $options = [\
            'Value 1' => 'Label 1',\
            'Value 2' => 'Label 2'\
        ];
        echo $this->Form->select('field', $options, [\
            'multiple' => 'checkbox',\
            'disabled' => ['Value 1']\
        ]);
    
    1  
    2  
    3  
    4  
    5  
    6  
    7  
    8  
    
    出力結果:
    
        <input name="field" value="" type="hidden">
        <div class="checkbox">
           <label for="field-1">
           <input name="field[]" disabled="disabled" value="Value 1" type="checkbox">
           Label 1
           </label>
        </div>
        <div class="checkbox">
           <label for="field-2">
           <input name="field[]" value="Value 2" id="field-2" type="checkbox">
           Label 2
           </label>
        </div>
    
    1  
    2  
    3  
    4  
    5  
    6  
    7  
    8  
    9  
    10  
    11  
    12  
    13  
    

### ファイル入力の作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E5%85%A5%E5%8A%9B%E3%81%AE%E4%BD%9C%E6%88%90)

`method` Cake\\View\\Helper\\FormHelper::**file**(string $fieldName, array $options)

*   `$fieldName` - `'Modelname.fieldname'` の形式のフィールド名。
*   `$options` - [General Control Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#general-control-options)
     や有効な HTML 属性を含むオプション配列。

フォームの中にファイルアップロードフィールドを作成します。 デフォルトで使用されるウィジェットテンプレートは:

    'file' => '<input type="file" name="{{name}}"{{attrs}}>'

1  

フォームにファイルアップロードフィールドを追加するためには、まずフォームの enctype に `'multipart/form-data'` がセットされていることを確認してください。

まずは、次のように `create()` メソッドを使用してください。 :

    echo $this->Form->create($document, ['enctype' => 'multipart/form-data']);
    // または
    echo $this->Form->create($document, ['type' => 'file']);

1  
2  
3  

次にフォームのビューファイルに以下のいずれかを追加します。 :

    echo $this->Form->control('submittedfile', [\
        'type' => 'file'\
    ]);
    
    // または
    echo $this->Form->file('submittedfile');

1  
2  
3  
4  
5  
6  

NOTE

HTML 自体の制限により、'file' タイプの入力フィールドにデフォルト値を設定することはできません。 フォームを表示するたびに、内部の値は空に設定されます。

フォームの送信に際して file フィールドは、フォームを受信しようとしているスクリプトに対して拡張された data 配列を提供します。

CakePHP が Windows サーバー上にインストールされている場合、上記の例について、 送信されるデータ配列内の値は次のように構成されます (Unix 環境では `'tmp_name'` が異なったパスになります)。 :

    $this->request->data['submittedfile']
    
    // 次の配列を含みます:
    [\
        'name' => 'conference_schedule.pdf',\
        'type' => 'application/pdf',\
        'tmp_name' => 'C:/WINDOWS/TEMP/php1EE.tmp',\
        'error' => 0, // Windows の場合、文字列になります。\
        'size' => 41737,\
    ];

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

この配列は PHP 自身によって生成されます。PHP が file フィールドを通してデータを どう処理しているのかについては、 [PHP マニュアルのファイルアップロードのセクションをご覧ください](https://secure.php.net/features.file-upload)
 。

NOTE

`$this->Form->file()` を使う場合、 `$this->Form->create()` の中の `'type'` オプションを `'file'` に設定することで、フォームのエンコーディングのタイプを設定できます。

### 日付と時刻に関するコントロールの作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E6%97%A5%E4%BB%98%E3%81%A8%E6%99%82%E5%88%BB%E3%81%AB%E9%96%A2%E3%81%99%E3%82%8B%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%AB%E3%81%AE%E4%BD%9C%E6%88%90)

日時関連の方法は、多くの共通の特性とオプションを共有しているため、 このサブセクションにまとめられています。

#### 日付と時刻のコントロールの共通オプション [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E6%97%A5%E4%BB%98%E3%81%A8%E6%99%82%E5%88%BB%E3%81%AE%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%AB%E3%81%AE%E5%85%B1%E9%80%9A%E3%82%AA%E3%83%95%E3%82%9A%E3%82%B7%E3%83%A7%E3%83%B3)

これらのオプションは、日付と時刻に関するコントロールに共通します。

*   `'empty'` - `true` の場合、余分の空の `option` HTML 要素が、 `select` の中のリストの先頭に追加されます。文字列の場合、 その文字列は空の要素として表示されます。デフォルトは `true` です。
*   `'default'` | `value` - 2つのいずれかを使用して、 フィールドに表示されるデフォルト値を設定します。 フィールド名と一致する `$this->request->getData()` の値は、この値を上書きします。 デフォルトが指定されていない場合、 `time()` が使用されます。 - `'year', 'month', 'day', 'hour', 'minute', 'second', 'meridian'` -これらのオプションを使用すると、コントロール要素が生成されるかどうか制御できます。 これらのオプションを `false` にセットすることにより、特定の選択ピッカーの生成を 無効にすることができます (デフォルトでは、使用されたメソッドの中で描画されます) 。 さらに、各オプションでは、HTML 属性を指定した `select` 要素に渡すことができます。

#### 日付関連コントロールのオプション [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E6%97%A5%E4%BB%98%E9%96%A2%E9%80%A3%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%AB%E3%81%AE%E3%82%AA%E3%83%95%E3%82%9A%E3%82%B7%E3%83%A7%E3%83%B3)

これらのオプションは、日付関連のメソッド、つまり `year()` 、 `month()` 、 `day()` 、 `dateTime()` そして `date()` に関連しています。

*   `'monthNames'` - `false` の場合は、選択ピッカーの月の表示で テキストの代わりに2桁の数字が使用されます。配列をセットした場合 (例 `['01' => 'Jan', '02' => 'Feb', ...]`)、指定された配列が使用されます。
*   `'minYear'` - 年の select フィールドで使用される最小の年。
*   `'maxYear'` - 年の select フィールドで使用される最大の年。
*   `'orderYear'` - 年選択ピッカー内の年の値の順序。 利用可能な値は `'asc'` と `'desc'` 。デフォルトは `'desc'` です。
*   `'year', 'month', 'day'` - これらのオプションを使用すると、コントロール要素が生成されるかどうか制御できます。 これらのオプションを `false` にセットすることにより、特定の選択ピッカーの生成を 無効にすることができます (デフォルトでは、使用されたメソッドの中で描画されます) 。 さらに、各オプションでは、HTML 属性を指定した `select` 要素に渡すことができます。

#### 時刻関連コントロールのオプション [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E6%99%82%E5%88%BB%E9%96%A2%E9%80%A3%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%AB%E3%81%AE%E3%82%AA%E3%83%95%E3%82%9A%E3%82%B7%E3%83%A7%E3%83%B3)

これらのオプションは、時刻関連のメソッド、 `hour()` 、 `minute()` 、 `second()` 、 `dateTime()` そして `time()` に関連しています。

*   `'interval'` - 分選択ピッカーの `option` 要素の中に表示される分の値の間隔。 デフォルトは 1 です。
*   `'round'` - 値が一定の間隔にきちんと収まらないときに、いずれかの方向に丸めるようにしたい場合は、 `up` または `down` に設定します。デフォルトは `null` です。
*   `timeFormat` - `dateTime()` と `time()` に適用されます。 選択ピッカーで使用する時刻の書式は、 `12` または `24` のいずれかです。 このオプションに `24` 以外の何かをセットした場合、書式は自動的に `12` がセットされ、 秒選択ピッカーの右側に `meridian` 選択ピッカーが自動的に表示されます。 デフォルトは 24 です。
*   `format` - `hour()` に適用されます。 選択ピッカーで使用する時刻の書式は、 `12` または `24` のいずれかです。 `12` をセットした場合、 `meridian` 選択ピッカーは自動的に表示されません。 それを追加するか、フォームコンテキストから適切な期間を推論する方法を提供するかは、 あなた次第です。デフォルトは 24 です。
*   `second` - `dateTime()` と `time()` に適用されます。 秒を有効にするために `true` に設定します。デフォルトは `false` です。
*   `'hour', 'minute', 'second', 'meridian'` - これらのオプションを使用すると、コントロール要素が生成されるかどうか制御できます。 これらのオプションを `false` にセットすることにより、特定の選択ピッカーの生成を 無効にすることができます (デフォルトでは、使用されたメソッドの中で描画されます) 。 さらに、各オプションでは、HTML 属性を指定した `select` 要素に渡すことができます。

#### 日時入力の作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E6%97%A5%E6%99%82%E5%85%A5%E5%8A%9B%E3%81%AE%E4%BD%9C%E6%88%90)

`method` Cake\\View\\Helper\\FormHelper::**dateTime**($fieldName, $options = \[\])

*   `$fieldName` - `select` 要素の HTML `name` 属性のプレフィックスとして使用される文字列。
*   `$options` - [General Control Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#general-control-options)
     または日時特有のオプション (下記参照)、 そして有効な HTML 属性を含むオプション配列。

日付と時刻の `select` 要素のセットを生成します。

コントロールの順序、およびコントロール間の要素/内容を制御するには、 `dateWidget` テンプレートを上書きします。デフォルトで `dateWidget` テンプレートは:

    {{year}}{{month}}{{day}}{{hour}}{{minute}}{{second}}{{meridian}}

1  

オプションを指定せずにメソッドを呼び出すと、デフォルトでは、年（4桁）、月（英語の完全名）、 曜日（数値）、時間（数値）、分（数値）の5つの選択ピッカーが生成されます。

例:

    <?= $this->form->dateTime('registered') ?>

1  

出力結果:

    <select name="registered[year]">
        <option value="" selected="selected"></option>
        <option value="2022">2022</option>
        ...
        <option value="2012">2012</option>
    </select>
    <select name="registered[month]">
        <option value="" selected="selected"></option>
        <option value="01">January</option>
        ...
        <option value="12">December</option>
    </select>
    <select name="registered[day]">
        <option value="" selected="selected"></option>
        <option value="01">1</option>
        ...
        <option value="31">31</option>
    </select>
    <select name="registered[hour]">
        <option value="" selected="selected"></option>
        <option value="00">0</option>
        ...
        <option value="23">23</option>
    </select>
    <select name="registered[minute]">
        <option value="" selected="selected"></option>
        <option value="00">00</option>
        ...
        <option value="59">59</option>
    </select>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  

特定の select ボックスにカスタムクラス/属性を含む datetime コントロールを作成するには、 `$options` 引数の中で各コンポーネントのオプションの配列として指定します。

例:

    echo $this->Form->dateTime('released', [\
        'year' => [\
            'class' => 'year-classname',\
        ],\
        'month' => [\
            'class' => 'month-class',\
            'data-type' => 'month',\
        ],\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  

これは、次の2つの選択ピッカーを作成します。

    <select name="released[year]" class="year-class">
        <option value="" selected="selected"></option>
        <option value="00">0</option>
        <option value="01">1</option>
        <!-- .. 以下省略 .. -->
    </select>
    <select name="released[month]" class="month-class" data-type="month">
        <option value="" selected="selected"></option>
        <option value="01">January</option>
        <!-- .. 以下省略 .. -->
    </select>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

#### 日付コントロールの作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E6%97%A5%E4%BB%98%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%AB%E3%81%AE%E4%BD%9C%E6%88%90)

`method` Cake\\View\\Helper\\FormHelper::**date**($fieldName, $options = \[\])

*   `$fieldName` - `select` 要素の HTML `name` 属性のプレフィックスとして使用される文字列。
*   `$options` - [General Control Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#general-control-options)
     、 [Datetime Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#datetime-options)
     、 適用可能な [Time Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#time-options)
     、そして有効な HTML 属性を含むオプション配列。

デフォルトでは、年（4桁）、月（英語の完全名）、日（数値）の値が設定された 3つの選択ピッカーを作成します。

生成された `select` 要素をさらに制御するには、オプションを追加します。

例:

    // 今年が 2017 年だと仮定すると、これは日ピッカーを無効にし、年ピッカーの空の
    // オプションを削除し、最低年を制限し、年の HTML 属性を追加し、
    // 月の文字列の 'empty' オプションを追加し、月を数値に変更します。
    <?php
        echo $this->Form->date('registered', [\
            'minYear' => 2018,\
            'monthNames' => false, // 月は数字で表示されます。\
            'empty' => [\
                'year' => false, // 年選択コントロールは空の値のオプションを持ちません。\
                'month' => 'Choose month...' // しかしながら、月選択コントロールは持ちます。\
            ],\
            'day' => false, // 日付選択コントールを表示しない。\
            'year' => [\
                'class' => 'cool-years',\
                'title' => 'Registration Year'\
            ]\
        ]);
    ?>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

出力結果:

    <select class= "cool-years" name="registered[year]" title="Registration Year">
        <option value="2022">2022</option>
        <option value="2021">2021</option>
        ...
        <option value="2018">2018</option>
    </select>
    <select name="registered[month]">
        <option value="" selected="selected">Choose month...</option>
        <option value="01">1</option>
        ...
        <option value="12">12</option>
    </select>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

#### 時間コントロールの作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E6%99%82%E9%96%93%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%AB%E3%81%AE%E4%BD%9C%E6%88%90)

`method` Cake\\View\\Helper\\FormHelper::**time**($fieldName, $options = \[\])

*   `$fieldName` - `select` 要素の HTML `name` 属性のプレフィックスとして使用される文字列。
*   `$options` - [General Control Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#general-control-options)
     、 [Datetime Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#datetime-options)
     、 適用可能な [Time Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#time-options)
     、そして有効な HTML 属性を含むオプション配列。

デフォルトでは、 24 時間と 60 分の値が入力された２つの `select` 要素 (`hour` と `minute`) を生成します。さらに、HTML 属性は、特定のコンポーネントごとに `$options` で指定することができます。 `$options['empty']` が `false` の場合、選択ピッカーは空のデフォルトオプションを含みません。

たとえば、15 分単位で選択できる時間範囲を作成し、各 select ボックスにクラスを適用するには、 次のようにします。 :

    echo $this->Form->time('released', [\
        'interval' => 15,\
        'hour' => [\
            'class' => 'foo-class',\
        ],\
        'minute' => [\
            'class' => 'bar-class',\
        ],\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  

これは、次の2つの選択ピッカーを作成します。

    <select name="released[hour]" class="foo-class">
        <option value="" selected="selected"></option>
        <option value="00">0</option>
        <option value="01">1</option>
        <!-- .. 中略 .. -->
        <option value="22">22</option>
        <option value="23">23</option>
    </select>
    <select name="released[minute]" class="bar-class">
        <option value="" selected="selected"></option>
        <option value="00">00</option>
        <option value="15">15</option>
        <option value="30">30</option>
        <option value="45">45</option>
    </select>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

#### 年コントロールの作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E5%B9%B4%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%AB%E3%81%AE%E4%BD%9C%E6%88%90)

`method` Cake\\View\\Helper\\FormHelper::**year**(string $fieldName, array $options = \[\])

*   `$fieldName` - `select` 要素の HTML `name` 属性のプレフィックスとして使用される文字列。
*   `$options` - [General Control Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#general-control-options)
     、 [Datetime Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#datetime-options)
     、 適用可能な [Time Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#time-options)
     、そして有効な HTML 属性を含むオプション配列。

`minYear` から `maxYear` （これらのオプションが提供されているとき）、 または今日から数えて-5年から+5年までの値を持つ `select` 要素を作成します。 さらに、HTML 属性は、 `$options` で指定することができます。 `$options ['empty']` が `false` の場合、選択ピッカーはリスト内に空の項目を含みません。

たとえば、2000 年から今年までの年を作成するには、次のようにします。 :

    echo $this->Form->year('purchased', [\
        'minYear' => 2000,\
        'maxYear' => date('Y')\
    ]);

1  
2  
3  
4  

2009 年だった場合は、次のようになるでしょう。

    <select name="purchased[year]">
    <option value=""></option>
    <option value="2009">2009</option>
    <option value="2008">2008</option>
    <option value="2007">2007</option>
    <option value="2006">2006</option>
    <option value="2005">2005</option>
    <option value="2004">2004</option>
    <option value="2003">2003</option>
    <option value="2002">2002</option>
    <option value="2001">2001</option>
    <option value="2000">2000</option>
    </select>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

#### 月コントロールの作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E6%9C%88%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%AB%E3%81%AE%E4%BD%9C%E6%88%90)

`method` Cake\\View\\Helper\\FormHelper::**month**(string $fieldName, array $attributes)

*   `$fieldName` - `select` 要素の HTML `name` 属性のプレフィックスとして使用される文字列。
*   `$attributes` - [General Control Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#general-control-options)
     、 [Datetime Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#datetime-options)
     、 適用可能な [Time Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#time-options)
     、そして有効な HTML 属性を含むオプション配列。

月の名前を列挙した `select` 要素を作成します。

例:

    echo $this->Form->month('mob');

1  

出力結果:

    <select name="mob[month]">
    <option value=""></option>
    <option value="01">January</option>
    <option value="02">February</option>
    <option value="03">March</option>
    <option value="04">April</option>
    <option value="05">May</option>
    <option value="06">June</option>
    <option value="07">July</option>
    <option value="08">August</option>
    <option value="09">September</option>
    <option value="10">October</option>
    <option value="11">November</option>
    <option value="12">December</option>
    </select>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

`'monthNames'` 属性に独自の月の名前を配列で設定することもできます。 また `false` を指定すると、月が数字で表示されます。

例:

    echo $this->Form->month('mob', ['monthNames' => false]);

1  

NOTE

デフォルトの月は、CakePHP の [国際化と地域化](https://book.cakephp.org/3.x/ja/core-libraries/internationalization-and-localization.html)
 機能でローカライズすることができます。

#### 日コントロールの作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E6%97%A5%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%AB%E3%81%AE%E4%BD%9C%E6%88%90)

`method` Cake\\View\\Helper\\FormHelper::**day**(string $fieldName, array $attributes)

*   `$fieldName` - `select` 要素の HTML `name` 属性のプレフィックスとして使用される文字列。
*   `$attributes` - [General Control Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#general-control-options)
     、 [Datetime Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#datetime-options)
     、 適用可能な [Time Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#time-options)
     、そして有効な HTML 属性を含むオプション配列。

（数字の）日を列挙する `select` 要素を作成します。

あなたの選択した指示テキストで空の `option` を作成するには（たとえば、 最初のオプションは 'Day'）、 `'empty'` パラメーターにテキストを指定できます。

例:

    echo $this->Form->day('created', ['empty' => 'Day']);

1  

出力結果:

    <select name="created[day]">
        <option value="" selected="selected">Day</option>
        <option value="01">1</option>
        <option value="02">2</option>
        <option value="03">3</option>
        ...
        <option value="31">31</option>
    </select>

1  
2  
3  
4  
5  
6  
7  
8  

#### 時間コントロールの作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E6%99%82%E9%96%93%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%AB%E3%81%AE%E4%BD%9C%E6%88%90-1)

`method` Cake\\View\\Helper\\FormHelper::**hour**(string $fieldName, array $attributes)

*   `$fieldName` - `select` 要素の HTML `name` 属性のプレフィックスとして使用される文字列。
*   `$attributes` - [General Control Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#general-control-options)
     、 [Datetime Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#datetime-options)
     、 適用可能な [Time Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#time-options)
     、そして有効な HTML 属性を含むオプション配列。

時を列挙した `select` 要素を作成します。

`format` オプションを使用して、12 時間または 24 時間のピッカーを作成することができます。 :

    echo $this->Form->hour('created', [\
        'format' => 12\
    ]);
    echo $this->Form->hour('created', [\
        'format' => 24\
    ]);

1  
2  
3  
4  
5  
6  

#### 分コントロールの作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E5%88%86%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%AB%E3%81%AE%E4%BD%9C%E6%88%90)

`method` Cake\\View\\Helper\\FormHelper::**minute**(string $fieldName, array $attributes)

*   `$fieldName` - `select` 要素の HTML `name` 属性のプレフィックスとして使用される文字列。
*   `$attributes` - [General Control Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#general-control-options)
     、 [Datetime Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#datetime-options)
     、 適用可能な [Time Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#time-options)
     、そして有効な HTML 属性を含むオプション配列。

分の値を列挙した `select` 要素を作成します。 `interval` オプションを使用して特定の値のみを含む選択ピッカーを作成することができます。

たとえば、10 分ずつ増やしたい場合は、次のようにします。 :

    // ビューテンプレートファイルの中で
    echo $this->Form->minute('arrival', [\
        'interval' => 10\
    ]);

1  
2  
3  
4  

これは、以下を出力します。

    <select name="arrival[minute]">
        <option value="" selected="selected"></option>
        <option value="00">00</option>
        <option value="10">10</option>
        <option value="20">20</option>
        <option value="30">30</option>
        <option value="40">40</option>
        <option value="50">50</option>
    </select>

1  
2  
3  
4  
5  
6  
7  
8  
9  

#### 午前と午後コントロールの作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E5%8D%88%E5%89%8D%E3%81%A8%E5%8D%88%E5%BE%8C%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%AB%E3%81%AE%E4%BD%9C%E6%88%90)

`method` Cake\\View\\Helper\\FormHelper::**meridian**(string $fieldName, array $attributes)

*   `$fieldName` - `select` 要素の HTML `name` 属性のプレフィックスとして使用される文字列。
*   `$attributes` - [General Control Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#general-control-options)
     と有効な HTML 属性を含むオプション配列。

'am' と 'pm' を列挙した `select` 要素を生成します。これは、時間の書式を `24` の代わりに `12` をセットした時に便利で、時間が属する期間を指定することができます。

ラベルの作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%83%A9%E3%83%98%E3%82%99%E3%83%AB%E3%81%AE%E4%BD%9C%E6%88%90)

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

`method` Cake\\View\\Helper\\FormHelper::**label**(string $fieldName, string $text, array $options)

*   `$fieldName` - `'Modelname.fieldname'` の形式のフィールド名。
*   `$text` - ラベルの見出しテキストを指定するためのオプション文字列。
*   `$options` - オプション。[General Control Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#general-control-options)
     と有効な HTML 属性を含む配列。

`label` 要素を作成します。引数の `$fieldName` は、要素の HTML `for` 属性を 生成するために使われます。 `$text` が未定義の場合、 `$fieldName` はラベルの `text` 属性を変えるために使われます。

例:

    echo $this->Form->label('name');
    echo $this->Form->label('name', 'Your username');

1  
2  

出力結果:

    <label for="name">Name</label>
    <label for="name">Your username</label>

1  
2  

第３パラメーター `$options` に id や class を設定できます。 :

    echo $this->Form->label('name', null, ['id' => 'user-label']);
    echo $this->Form->label('name', 'Your username', ['class' => 'highlight']);

1  
2  

出力結果:

    <label for="name" id="user-label">Name</label>
    <label for="name" class="highlight">Your username</label>

1  
2  

エラーの表示と確認 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%82%A8%E3%83%A9%E3%83%BC%E3%81%AE%E8%A1%A8%E7%A4%BA%E3%81%A8%E7%A2%BA%E8%AA%8D)

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

FormHelper は、フィールドエラーを簡単にチェックしたり、必要に応じてカスタマイズされた エラーメッセージを表示できる、いくつかのメソッドを公開しています。

### エラーの表示 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%82%A8%E3%83%A9%E3%83%BC%E3%81%AE%E8%A1%A8%E7%A4%BA)

`method` Cake\\View\\Helper\\FormHelper::**error**(string $fieldName, mixed $text, array $options)

*   `$fieldName` - `'Modelname.fieldname'` の形式のフィールド名。
*   `$text` - オプション。エラーメッセージを提供する文字列または配列。 配列の場合、 キー名 => メッセージのハッシュになります。デフォルトは `null` 。
*   `$options` - `'escape'` キーのブール値のみを含みます。これは、 エラーメッセージの内容を HTML エスケープするかどうかを定義します。デフォルトは `true` です。

検証エラーが発生した際に、与えられたフィールドの `$text` で指定された、 検証エラーメッセージを表示します。フィールドの `$text` がない場合、 そのフィールドのデフォルトの検証エラーメッセージが使用されます。

次のテンプレートウィジェットを使います。 :

    'error' => '<div class="error-message">{{content}}</div>'
    'errorList' => '<ul>{{content}}</ul>'
    'errorItem' => '<li>{{text}}</li>'

1  
2  
3  

`'errorList'` と `'errorItem'` テンプレートは、１つのフィールドに複数の エラーメッセージを書式化するために使用されます。

例:

    // TicketsTable に 'notEmpty' 検証ルールがある場合:
    public function validationDefault(Validator $validator)
    {
        $validator
            ->requirePresence('ticket', 'create')
            ->notEmpty('ticket');
    }
    
    // そして、 Templates/Tickets/add.ctp の中が次のような場合:
    echo $this->Form->text('ticket');
    
    if ($this->Form->isFieldError('ticket')) {
        echo $this->Form->error('ticket', 'Completely custom error message!');
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

もし、 _Ticket_ フィールドの値を指定せずにフォームの _Submit_ ボタンをクリックした場合、 フォームは次のように出力されます。

    <input name="ticket" class="form-error" required="required" value="" type="text">
    <div class="error-message">Completely custom error message!</div>

1  
2  

NOTE

`Cake\View\Helper\FormHelper::control()` を使用している時、 デフォルトではエラーは描画されますので、 `isFieldError()` を使用したり、 手動で `error()` を呼び出す必要はありません。

TIP

あるモデルのフィールドを使用して、 `control()` で複数のフォームフィールドを生成し、 それぞれ同じ検証エラーメッセージを表示させたい場合、それぞれの [検証ルール](https://book.cakephp.org/3.x/ja/core-libraries/validation.html#creating-validators)
 の中でカスタムエラーメッセージを 定義する方が良いでしょう。

Add examples.

### エラーの確認 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%82%A8%E3%83%A9%E3%83%BC%E3%81%AE%E7%A2%BA%E8%AA%8D)

`method` Cake\\View\\Helper\\FormHelper::**isFieldError**(string $fieldName)

*   `$fieldName` - `'Modelname.fieldname'` の形式のフィールド名。

指定された `$fieldName` に有効な検証エラーがある場合は `true` を返します。 そうでなければ `fales` を返します。

例:

    if ($this->Form->isFieldError('gender')) {
        echo $this->Form->error('gender');
    }

1  
2  
3  

HTML5 検証メッセージにバリデーションメッセージを表示 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#html5-%E6%A4%9C%E8%A8%BC%E3%83%A1%E3%83%83%E3%82%BB%E3%83%BC%E3%82%B7%E3%82%99%E3%81%AB%E3%83%8F%E3%82%99%E3%83%AA%E3%83%86%E3%82%99%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%83%A1%E3%83%83%E3%82%BB%E3%83%BC%E3%82%B7%E3%82%99%E3%82%92%E8%A1%A8%E7%A4%BA)

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

Added in version 3.7.0

`autoSetCustomValidity` FormHelper オプションが `true` に設定されている場合、 デフォルトのブラウザーの HTML5 必須メッセージの代わりに、フィールドの必須および notBlank バリデーションメッセージに対するエラーメッセージが使用されます。 このオプションを有効にすると、フィールドに `onvalid` と `oninvalid` イベント属性が追加されます。 例えば、 :

    <input type="text" name="field" required onvalid="this.setCustomValidity('')" oninvalid="this.setCustomValidity('Custom notBlank message')" />

1  

カスタム Javascript を使用してこれらのイベントを手動で設定したい場合は、 `autoSetCustomValidity` オプションを `false` に設定して、 代わりに 特別な `customValidityMessage` テンプレート変数を使用することができます。 このテンプレート変数はフィールドが必須の場合に追加されます。 :

    // テンプレート例
    [\
        'input' => '<input type="{{type}}" name="{{name}}" data-error-message="{{customValidityMessage}}" {{attrs}}/>',\
    ]
    
    // このような input が作成されます
    <input type="text" name="field" required data-error-message="Custom notBlank message" />

1  
2  
3  
4  
5  
6  
7  

それから Javascript を使って `onvalid` と `oninvalid` イベントを好きなように設定できます。

ボタンと submit 要素の作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%83%9B%E3%82%99%E3%82%BF%E3%83%B3%E3%81%A8-submit-%E8%A6%81%E7%B4%A0%E3%81%AE%E4%BD%9C%E6%88%90)

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

### Submit 要素の作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#submit-%E8%A6%81%E7%B4%A0%E3%81%AE%E4%BD%9C%E6%88%90)

`method` Cake\\View\\Helper\\FormHelper::**submit**(string $caption, array $options)

*   `$caption` - ボタンのテキスト見出しまたは画像へのパスを提供するオプション文字列。 デフォルトは、 `'Submit'` です。
*   `$options` - [General Control Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#general-control-options)
     、または submit 特有のオプション (下記参照) 。

`$caption` を値としてもつ `submit` タイプの `input` 要素を作成します。 指定された `$caption` が画像の URL である場合 (つまり、 '😕/' を含む文字列または、拡張子 '.jpg, .jpe, .jpeg, .gif' を含む場合)、画像の送信ボタンが生成され、指定された画像が 存在する場合は、それを使用します。最初の文字が '/' の場合、画像は _webroot_ からの 相対パスになり、最初の文字が '/' ではない場合、画像は _webroot/img_ からの相対パスになります。

デフォルトで次のウィジェットテンプレートを使用します。 :

    'inputSubmit' => '<input type="{{type}}"{{attrs}}/>'
    'submitContainer' => '<div class="submit">{{content}}</div>'

1  
2  

**Submit のオプション**

*   `'type'` - リセットボタンを生成するためにこのオプションに `'reset'` を設定します。 デフォルトは `'submit'` です。
*   `'templateVars'` - input 要素や、そのコンテナーにテンプレート変数を追加するために、 この配列を設定します。
*   その他の指定された属性は `input` 要素に割り当てられます。

例:

    echo $this->Form->submit('Click me');

1  

出力結果:

    <div class="submit"><input value="Click me" type="submit"></div>

1  

見出しテキストの代わりに見出しパラメーターとして画像への相対 URL または 絶対 URL を渡すことができます。 :

    echo $this->Form->submit('ok.png');

1  

出力結果:

    <div class="submit"><input type="image" src="/img/ok.png"></div>

1  

submit 入力は、基本的なテキストやイメージが必要な場合に便利です。 より複雑なボタンの内容が必要な場合は、 `button()` を使用してください。

### ボタン要素の作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%83%9B%E3%82%99%E3%82%BF%E3%83%B3%E8%A6%81%E7%B4%A0%E3%81%AE%E4%BD%9C%E6%88%90)

`method` Cake\\View\\Helper\\FormHelper::**button**(string $title, array $options = \[\])

*   `$title` - ボタンの見出しテキストを提供する必須の文字列。
*   `$options` - [General Control Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#general-control-options)
     やボタン特有のオプション (下記参照)と 有効な HTML 属性を含むオプション配列。

指定されたタイトルと `'button'` のデフォルトタイプの HTML ボタンを作成します。

**ボタンのオプション**

*   `$options['type']` - これを設定すると、次の3つの button タイプのどれかが出力されます。
    1.  `'submit'` - `$this->Form->submit()` と同様に送信ボタンを作成します。 しかしながら、 `submit()` のように `div` の囲い込みは生成しません。 これがデフォルトのタイプです。
    2.  `'reset'` - フォームのリセットボタンを作成します。
    3.  `'button'` - 標準の押しボタンを作成します。
*   `$options['escape']` - ブール値。 `true` をセットした場合、 `$title` で指定された値を HTML エンコードします。デフォルトは `false` です。

例:

    echo $this->Form->button('ボタン');
    echo $this->Form->button('別のボタン', ['type' => 'button']);
    echo $this->Form->button('フォームのリセット', ['type' => 'reset']);
    echo $this->Form->button('フォームの送信', ['type' => 'submit']);

1  
2  
3  
4  

出力結果:

    <button type="submit">ボタン</button>
    <button type="button">別のボタン</button>
    <button type="reset">フォームのリセット</button>
    <button type="submit">フォームの送信</button>

1  
2  
3  
4  

`'escape'` オプションの使用例:

    // エスケープされた HTML を描画します。
    echo $this->Form->button('<em>Submit Form</em>', [\
        'type' => 'submit',\
        'escape' => true\
    ]);

1  
2  
3  
4  
5  

フォームを閉じる [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%83%95%E3%82%A9%E3%83%BC%E3%83%A0%E3%82%92%E9%96%89%E3%81%97%E3%82%99%E3%82%8B)

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

`method` Cake\\View\\Helper\\FormHelper::**end**($secureAttributes = \[\])

*   `$secureAttributes` - オプション。SecurityComponent 用に生成された非表示の input 要素に HTML 属性として渡されるセキュアな属性を提供できます。

`end()` は、フォームを閉じて完成します。 多くの場合、 `end()` は終了タグだけを出力しますが、 `end()` を使うと、 FormHelper が `Cake\Controller\Component\SecurityComponent` に必要な hidden フォーム要素を挿入できるようになります。

    <?= $this->Form->create(); ?>
    
    <!-- フォーム要素はここにあります -->
    
    <?= $this->Form->end(); ?>

1  
2  
3  
4  
5  

生成された hidden 入力に属性を追加する必要がある場合は、 `$secureAttributes` 引数を使用できます。 :

    echo $this->Form->end(['data-type' => 'hidden']);

1  

出力結果:

    <div style="display:none;">
        <input type="hidden" name="_Token[fields]" data-type="hidden"
            value="2981c38990f3f6ba935e6561dc77277966fabd6d%3AAddresses.id">
        <input type="hidden" name="_Token[unlocked]" data-type="hidden"
            value="address%7Cfirst_name">
    </div>

1  
2  
3  
4  
5  
6  

NOTE

アプリケーションで `Cake\Controller\Component\SecurityComponent` を使用している場合は、必ずフォームを `end()` で終わらせてください。

単独のボタンと POST リンクの作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E5%8D%98%E7%8B%AC%E3%81%AE%E3%83%9B%E3%82%99%E3%82%BF%E3%83%B3%E3%81%A8-post-%E3%83%AA%E3%83%B3%E3%82%AF%E3%81%AE%E4%BD%9C%E6%88%90)

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

### POST ボタンの作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#post-%E3%83%9B%E3%82%99%E3%82%BF%E3%83%B3%E3%81%AE%E4%BD%9C%E6%88%90)

`method` Cake\\View\\Helper\\FormHelper::**postButton**(string $title, mixed $url, array $options = \[\])

*   `$title` - ボタンの見出しテキストを提供する必須の文字列。 デフォルトでは HTML エンコードされません。
*   `$url` - 文字列や配列として提供される URL。
*   `$options` - [General Control Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#general-control-options)
     、特定のオプション（下記参照）と 有効な HTML 属性を含むオプション配列。

デフォルトでは、POST で送信する `<form>` 要素で囲まれた `<button>` タグを作成します。 また、デフォルトでは、SecurityComponent のために非表示入力フィールドも生成します。

**POST ボタンのオプション**

*   `'data'` - hidden 入力に渡すキーと値の配列。
*   `'method'` - 使用するリクエスト方法。例えば、 `'delete'` をセットすると、 HTTP/1.1 DELETE リクエストをシミュレートします。デフォルトは `'post'` です。
*   `'form'` - `FormHelper::create()` に渡す任意のオプションの配列。
*   また、 `postButton()` メソッドは、 `button()` メソッドで有効なオプションも受け付けます。

例:

    // Templates/Tickets/index.ctp の中で
    <?= $this->Form->postButton('Delete Record', ['controller' => 'Tickets', 'action' => 'delete', 5]) ?>

1  
2  

出力結果:

    <form method="post" accept-charset="utf-8" action="/Rtools/tickets/delete/5">
        <div style="display:none;">
            <input name="_method" value="POST" type="hidden">
        </div>
        <button type="submit">Delete Record</button>
        <div style="display:none;">
            <input name="_Token[fields]" value="186cfbfc6f519622e19d1e688633c4028229081f%3A" type="hidden">
            <input name="_Token[unlocked]" value="" type="hidden">
            <input name="_Token[debug]" value="%5B%22%5C%2FRtools%5C%2Ftickets%5C%2Fdelete%5C%2F1%22%2C%5B%5D%2C%5B%5D%5D" type="hidden">
        </div>
    </form>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

このメソッドは `form` 要素を作成します。 なので、開かれたフォームの中でこのメソッドを使用しないでください。 代わりに `Cake\View\Helper\FormHelper::submit()` または `Cake\View\Helper\FormHelper::button()` を使用して、 開かれたフォームの中でボタンを作成してください。

### POST リンクの作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#post-%E3%83%AA%E3%83%B3%E3%82%AF%E3%81%AE%E4%BD%9C%E6%88%90)

`method` Cake\\View\\Helper\\FormHelper::**postLink**(string $title, mixed $url = null, array $options = \[\])

*   `$title` - `<a>` タグに囲まれたテキストを提供する必須の文字列。
*   `$url` - オプション。フォームの URL (相対 URL 、または `http://` で始まる外部 URL) を含む文字列または配列。
*   `$options` - [General Control Options](https://book.cakephp.org/3.x/ja/views/helpers/form.html#general-control-options)
     、特有のオプション（下記参照）と 有効な HTML 属性を含むオプション配列。

HTML リンクを作成しますが、指定した方法 (デフォルトは POST)で URL にアクセスします。 ブラウザーで有効にするには JavaScript が必要です。

**POST リンクのオプション**

*   `'data'` - hidden 入力に渡すキーと値の配列。
*   `'method'` - 使用するリクエスト方法。例えば、 `'delete'` をセットすると、 HTTP/1.1 DELETE リクエストをシミュレートします。デフォルトは `'post'` です。
*   `'confirm'` - クリック時に表示される確認メッセージ。デフォルトは `null` です。
*   `'block'` - ビューブロック `'postLink'` へフォームの追加するために このオプションに `true` をセットしたり、カスタムブロック名を指定します。 デフォルトは `null` です。
*   また、 `postLink` メソッドは、 `link()` メソッドの有効なオプションを受け付けます。

このメソッドは `<form>` 要素を作成します。 このメソッドを既存のフォームの中で使いたい場合は、 `block` オプションを使用して、 新しいフォームがメインフォームの外部でレンダリング可能な [ビューブロック](https://book.cakephp.org/3.x/ja/views.html#view-blocks)
 に設定されるようにする必要があります。

あなたが探しているものがフォームを送信するボタンであれば、代わりに `Cake\View\Helper\FormHelper::button()` または `Cake\View\Helper\FormHelper::submit()` を使用してください。

NOTE

開いているフォームの中に postLink を入れないように注意してください。 代わりに、 `block` オプションを使ってフォームを [ビューブロック](https://book.cakephp.org/3.x/ja/views.html#view-blocks)
 にバッファリングしてください。

FormHelper で使用するテンプレートのカスタマイズ [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#formhelper-%E3%81%A6%E3%82%99%E4%BD%BF%E7%94%A8%E3%81%99%E3%82%8B%E3%83%86%E3%83%B3%E3%83%95%E3%82%9A%E3%83%AC%E3%83%BC%E3%83%88%E3%81%AE%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%9E%E3%82%A4%E3%82%B9%E3%82%99)

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

CakePHP の多くのヘルパーと同じように、FormHelper は、 作成する HTML をフォーマットするための文字列テンプレートを使用しています。 既定のテンプレートは、合理的な既定値のセットを意図していますが、 アプリケーションに合わせてテンプレートをカスタマイズする必要があるかもしれません。

ヘルパーが読み込まれたときにテンプレートを変更するには、コントローラーにヘルパーを含めるときに `templates` オプションを設定することができます。 :

    // View クラスの中で
    $this->loadHelper('Form', [\
        'templates' => 'app_form',\
    ]);

1  
2  
3  
4  

これは、\*\*config/app\_form.php\*\*ファイルを作成し **config/app\_form.php** の中のタグを読み込みます。 このファイルには、名前で索引付けされたテンプレートの配列が含まれている必要があります。 :

    // config/app_form.php の中で
    return [\
        'inputContainer' => '<div class="form-control">{{content}}</div>',\
    ];

1  
2  
3  
4  

定義したテンプレートは、ヘルパーに含まれるデフォルトのテンプレートを置き換えます。 置き換えられていないテンプレートは引き続きデフォルト値を使用します。 `setTemplates()` メソッドを使って実行時にテンプレートを変更することもできます。 :

    $myTemplates = [\
        'inputContainer' => '<div class="form-control">{{content}}</div>',\
    ];
    $this->Form->setTemplates($myTemplates);
    // 3.4 より前
    $this->Form->templates($myTemplates);

1  
2  
3  
4  
5  
6  

WARNING

パーセント記号 (`%`) を含むテンプレート文字列には特別な注意が必要です。 この文字の先頭に `%%` のようにもう一つパーセンテージを付ける必要があります。 なぜなら、内部的なテンプレートは `sprintf()` で使用されるためにコンパイルされているからです。 例: `'<div style="width:%%"></div>'`

### テンプレート一覧 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%83%86%E3%83%B3%E3%83%95%E3%82%9A%E3%83%AC%E3%83%BC%E3%83%88%E4%B8%80%E8%A6%A7)

デフォルトのテンプレートのリスト、それらのデフォルトのフォーマット、そして期待される変数は [FormHelper API ドキュメント](https://api.cakephp.org/3.x/class-Cake.View.Helper.FormHelper.html#%24_defaultConfig)
 で見つけることができます。

#### 異なるカスタムコントロールコンテナーの使用 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E7%95%B0%E3%81%AA%E3%82%8B%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%A0%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%AB%E3%82%B3%E3%83%B3%E3%83%86%E3%83%8A%E3%83%BC%E3%81%AE%E4%BD%BF%E7%94%A8)

これらのテンプレートに加えて、 `control()` メソッドはコントロールコンテナーごとに異なるテンプレートを 使用しようとします。たとえば、datetime コントロールを作成する場合、 `datetimeContainer` が存在する場合にはそれが使用されます。 そのコンテナーがない場合、 `inputContainer` テンプレートが使用されます。 例えば:

    // 独自の HTML で囲まれた radio を追加
    $this->Form->templates([\
        'radioContainer' => '<div class="form-radio">{{content}}</div>'\
    ]);
    
    // 独自の div で囲まれた radio セットを作成
    echo $this->Form->control('email_notifications', [\
        'options' => ['y', 'n'],\
        'type' => 'radio'\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

#### 異なるカスタムフォームグループの使用 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E7%95%B0%E3%81%AA%E3%82%8B%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%A0%E3%83%95%E3%82%A9%E3%83%BC%E3%83%A0%E3%82%AF%E3%82%99%E3%83%AB%E3%83%BC%E3%83%95%E3%82%9A%E3%81%AE%E4%BD%BF%E7%94%A8)

コンテナーの制御と同様に、 `control()` メソッドはフォームグループごとに異なるテンプレートを 使用しようとします。フォームグループは、ラベルとコントロールの組み合わせです。 例えば、radio 入力を作成する時、 `radioFormGroup` が存在する場合、それが使用されます。 そのテンプレートが存在しない場合、デフォルトでは、ラベル＆入力の各セットは、 `formGroup` テンプレートを使用して描画されます。

例:

    // 独自の radio フォームグループを追加
    $this->Form->setTemplates([\
        'radioFormGroup' => '<div class="radio">{{label}}{{input}}</div>'\
    ]);

1  
2  
3  
4  

### テンプレートにテンプレート変数を追加 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%83%86%E3%83%B3%E3%83%95%E3%82%9A%E3%83%AC%E3%83%BC%E3%83%88%E3%81%AB%E3%83%86%E3%83%B3%E3%83%95%E3%82%9A%E3%83%AC%E3%83%BC%E3%83%88%E5%A4%89%E6%95%B0%E3%82%92%E8%BF%BD%E5%8A%A0)

カスタムテンプレートにテンプレートプレースホルダを追加し、 コントロールを生成するときにプレースホルダを設定することができます。

例:

    // help プレースホルダ付きでテンプレートを追加
    $this->Form->setTemplates([\
        'inputContainer' => '<div class="input {{type}}{{required}}">\
            {{content}} <span class="help">{{help}}</span></div>'\
    ]);
    
    // help 変数を設定し入力を生成
    echo $this->Form->control('password', [\
        'templateVars' => ['help' => '少なくとも 8 文字の長さ。']\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

出力結果:

    <div class="input password">
        <label for="password">
            Password
        </label>
        <input name="password" id="password" type="password">
        <span class="help">少なくとも 8 文字の長さ。</span>
    </div>

1  
2  
3  
4  
5  
6  
7  

Added in version 3.1

templateVars オプションは 3.1.0 で追加されました。

### チェックボックスとラジオのラベル外への移動 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%83%81%E3%82%A7%E3%83%83%E3%82%AF%E3%83%9B%E3%82%99%E3%83%83%E3%82%AF%E3%82%B9%E3%81%A8%E3%83%A9%E3%82%B7%E3%82%99%E3%82%AA%E3%81%AE%E3%83%A9%E3%83%98%E3%82%99%E3%83%AB%E5%A4%96%E3%81%B8%E3%81%AE%E7%A7%BB%E5%8B%95)

デフォルトでは、CakePHP は、 `control()` で作成されたチェックボックスと `control()` と `radio()` の両方で作成されたラジオボタンをラベル要素内でネストします。 これにより、人気の CSS フレームワークとの統合に役立ちます。 ラベルの外に checkbox/radio 入力を配置する必要がある場合は、 テンプレートを変更することで行うことができます。 :

    $this->Form->setTemplates([\
        'nestingLabel' => '{{hidden}}{{input}}<label{{attrs}}>{{text}}</label>',\
        'formGroup' => '{{input}}{{label}}',\
    ]);

1  
2  
3  
4  

これにより、ラジオボタンとチェックボックスがラベルの外側に描画されます。

フォーム全体の生成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%83%95%E3%82%A9%E3%83%BC%E3%83%A0%E5%85%A8%E4%BD%93%E3%81%AE%E7%94%9F%E6%88%90)

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

### 複数のコントロールの作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E8%A4%87%E6%95%B0%E3%81%AE%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%AB%E3%81%AE%E4%BD%9C%E6%88%90)

`method` Cake\\View\\Helper\\FormHelper::**controls**(array $fields = \[\], $options = \[\])

*   `$fields` - 生成するフィールドの配列。指定した各フィールドのカスタムタイプ、 ラベル、その他のオプションを設定できます。
*   `$options` - オプション。オプションの配列。有効なキーは:
    1.  `'fieldset'` - filedset を無効にするために `false` を設定してください。 空の配列を渡すと、fieldset は有効になります。 HTML 属性として適用するパラメーターの配列を `fieldset` タグに渡すこともできます。
    2.  `legend` - `legend` のテキストをカスタマイズするための文字列。 生成された入力セットの legend を無効にするために `false` を設定してください。

`fieldset` で囲まれた指定された一連のコントロールセットを生成します。 生成されたフィールドを含めることで指定できます。 :

    echo $this->Form->controls([\
        'name',\
        'email'\
    ]);

1  
2  
3  
4  

オプションを使用して legend のテキストをカスタマイズすることができます。 :

    echo $this->Form->controls($fields, ['legend' => 'Update news post']);

1  

`$fields` パラメーターで追加のオプションを定義することによって、 生成されたコントロールをカスタマイズすることができます。 :

    echo $this->Form->controls([\
        'name' => ['label' => 'カスタムラベル']\
    ]);

1  
2  
3  

`$fields` をカスタマイズする場合、生成された legend/fieldset を制御するために `$options` パラメーターを使用することができます。

例えば:

    echo $this->Form->controls(
        [\
            'name' => ['label' => 'カスタムラベル']\
        ],
        ['legend' => 'Update your post']
    );

1  
2  
3  
4  
5  
6  

`fieldset` を無効にすると、 `legend` は出力されません。

### エンティティー全体のコントロールを作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%82%A8%E3%83%B3%E3%83%86%E3%82%A3%E3%83%86%E3%82%A3%E3%83%BC%E5%85%A8%E4%BD%93%E3%81%AE%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%AB%E3%82%92%E4%BD%9C%E6%88%90)

`method` Cake\\View\\Helper\\FormHelper::**allControls**(array $fields, $options = \[\])

*   `$fields` - オプション。生成するフィールドのカスタマイズ配列。 カスタムタイプ、ラベル、その他のオプションを設定できます。
*   `$options` - オプション。オプションの配列。有効なキーは:
    1.  `'fieldset'` - これに `false` を設定すると fieldset が無効になります。 空の場合、fieldset は有効になります。パラメーターの配列を渡すと、 `fieldset` の HTML 属性として適用されます。
    2.  `legend` - `legend` テキストをカスタマイズするための文字列。 これに `false` を設定すると、生成されたコントロールセットの `legend` が無効になります。

このメソッドは `controls()` と密接に関係していますが、 `$fields` 引数は 現在のトップレベルエンティティーの _全ての_ フィールドにデフォルト設定されています。 生成されたコントロールから特定のフィールドを除外するには、 `$fields` パラメーターで `false` を設定します。 :

    echo $this->Form->allControls(['password' => false]);
    // 3.4.0 より前の場合:
    echo $this->Form->allInputs(['password' => false]);

1  
2  
3  

関連データの入力を作成 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E9%96%A2%E9%80%A3%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%81%AE%E5%85%A5%E5%8A%9B%E3%82%92%E4%BD%9C%E6%88%90)

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

関連するデータのフォームを作成するのは簡単で、エンティティーのデータ内のパスに密接に関連しています。 次のテーブルリレーションを仮定します。

*   Authors HasOne Profiles
*   Authors HasMany Articles
*   Articles HasMany Comments
*   Articles BelongsTo Authors
*   Articles BelongsToMany Tags

アソシエーション付きで読み込まれた記事を編集していた場合、次のコントロールを作成できます。 :

    $this->Form->create($article);
    
    // Article コントロール
    echo $this->Form->control('title');
    
    // Author コントロール (belongsTo)
    echo $this->Form->control('author.id');
    echo $this->Form->control('author.first_name');
    echo $this->Form->control('author.last_name');
    
    // Author の profile (belongsTo + hasOne)
    echo $this->Form->control('author.profile.id');
    echo $this->Form->control('author.profile.username');
    
    // 別々の入力として、
    // Tags コントロール (belongsToMany)
    echo $this->Form->control('tags.0.id');
    echo $this->Form->control('tags.0.name');
    echo $this->Form->control('tags.1.id');
    echo $this->Form->control('tags.1.name');
    
    // 結合テーブルの入力 (articles_tags)
    echo $this->Form->control('tags.0._joinData.starred');
    echo $this->Form->control('tags.1._joinData.starred');
    
    // Comments コントロール (hasMany)
    echo $this->Form->control('comments.0.id');
    echo $this->Form->control('comments.0.comment');
    echo $this->Form->control('comments.1.id');
    echo $this->Form->control('comments.1.comment');

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  

上記のコントロールは、コントローラー内の次のコードを使用して完成したエンティティーグラフに マーシャリングすることができます。 :

    $article = $this->Articles->patchEntity($article, $this->request->getData(), [\
        'associated' => [\
            'Authors',\
            'Authors.Profiles',\
            'Tags',\
            'Comments'\
        ]\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  

上記の例は、各エンティティーと結合データレコードに対して別々の入力を持つ、 多数の関連するデータセットの拡張された例を示しています。 また、多数の関連に属する複数選択入力を作成することもできます。 :

    // belongsToMany の複数選択要素
    // _joinData をサポートしません
    echo $this->Form->control('tags._ids', [\
        'type' => 'select',\
        'multiple' => true,\
        'options' => $tagList,\
    ]);

1  
2  
3  
4  
5  
6  
7  

独自ウィジェットの追加 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E7%8B%AC%E8%87%AA%E3%82%A6%E3%82%A3%E3%82%B7%E3%82%99%E3%82%A7%E3%83%83%E3%83%88%E3%81%AE%E8%BF%BD%E5%8A%A0)

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

CakePHP を使うと、アプリケーションに独自のコントロールウィジェットを簡単に追加でき、 他のコントロールタイプと同様に使用することができます。 すべてのコアコントロールタイプはウィジェットとして実装されています。 つまり、独自の実装でコアウィジェットを上書きすることができます。

### Widget クラスの構築 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#widget-%E3%82%AF%E3%83%A9%E3%82%B9%E3%81%AE%E6%A7%8B%E7%AF%89)

Widget クラスは、とても単純で必須のインターフェイスを持っています。 これらは `Cake\View\Widget\WidgetInterface` を実装しなければなりません。 このインターフェイスを実装するには、 `render(array $data)` メソッドと `secureFields(array $data)` メソッドが必要です。 `render()` メソッドは、ウィジェットを構築するためのデータ配列を受け取り、 ウィジェットの HTML 文字列を返すことが期待されています。 `secureFields()` メソッドは、同様にデータ配列を受け取り、 このウィジェットで保護するフィールドのリストを含む配列を返すことが期待されています。 CakePHP がウィジェットを構築している場合、最初の引数として `Cake\View\StringTemplate` インスタンスを取得し、その後にあなたが定義した依存関係が続くことが期待できます。 autocomplete ウィジェットを作成したい場合、以下を実行できます。 :

    namespace App\View\Widget;
    
    use Cake\View\Form\ContextInterface;
    use Cake\View\Widget\WidgetInterface;
    
    class AutocompleteWidget implements WidgetInterface
    {
    
        protected $_templates;
    
        public function __construct($templates)
        {
            $this->_templates = $templates;
        }
    
        public function render(array $data, ContextInterface $context)
        {
            $data += [\
                'name' => '',\
            ];
            return $this->_templates->format('autocomplete', [\
                'name' => $data['name'],\
                'attrs' => $this->_templates->formatAttributes($data, ['name'])\
            ]);
        }
    
        public function secureFields(array $data)
        {
            return [$data['name']];
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  

明らかに、これは非常に簡単な例ですが、独自ウィジェットの構築方法を示しています。

### ウィジェットの使用 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#%E3%82%A6%E3%82%A3%E3%82%B7%E3%82%99%E3%82%A7%E3%83%83%E3%83%88%E3%81%AE%E4%BD%BF%E7%94%A8)

FormHelper を読み込むときや、 `addWidget()` メソッドを使って独自のウィジェットを読み込むことができます。 FormHelper を読み込むとき、ウィジェットは設定として定義されます。 :

    // View クラスの中で
    $this->loadHelper('Form', [\
        'widgets' => [\
            'autocomplete' => ['Autocomplete']\
        ]\
    ]);

1  
2  
3  
4  
5  
6  

あなたのウィジェットが他のウィジェットを必要とする場合は、それらの依存関係を宣言することによって FormHelper に取り込ませることができます。 :

    $this->loadHelper('Form', [\
        'widgets' => [\
            'autocomplete' => [\
                'App\View\Widget\AutocompleteWidget',\
                'text',\
                'label'\
            ]\
        ]\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  

上記の例では、 `autocomplete` ウィジェットは `text` と `label` ウィジェットに依存します。 ウィジェットがビューにアクセスする必要がある場合は、 `_view` 'ウィジェット' を使用してください。 autocomplete ウィジェットが作成されると、 `text` と `label` の名前に関連するウィジェットオブジェクトが渡されます。 `addWidget()` メソッドを使ってウィジェットを追加すると、次のようになります。 :

    // classname の使用。
    $this->Form->addWidget(
        'autocomplete',
        ['Autocomplete', 'text', 'label']
    );
    
    // インスタンスの使用 - 依存関係を解決する必要があります。
    // 3.6.0 より前は、ウィジェットの取得に widgetRegistry() を使用。
    $autocomplete = new AutocompleteWidget(
        $this->Form->getTemplater(),
        $this->Form->getWidgetLocator()->get('text'),
        $this->Form->getWidgetLocator()->get('label'),
    );
    $this->Form->addWidget('autocomplete', $autocomplete);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

追加/置換されると、ウィジェットはコントロールの 'type' として使用できます。 :

    echo $this->Form->control('search', ['type' => 'autocomplete']);

1  

これは、 `controls()` とまったく同じように `label` と囲い込む `div` を持つ独自ウィジェットを作成します。 あるいは、マジックメソッドを使用してコントロールウィジェットだけを作成することもできます。 :

    echo $this->Form->autocomplete('search', $options);

1  

SecurityComponent との連携 [​](https://book.cakephp.org/3.x/ja/views/helpers/form.html#securitycomponent-%E3%81%A8%E3%81%AE%E9%80%A3%E6%90%BA)

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

`Cake\Controller\Component\SecurityComponent` には、 フォームをより安全で安全にするためのいくつかの機能があります。 コントローラーに `SecurityComponent` を含めるだけで、 フォームの改ざん防止機能が自動的に有効になります。

SecurityComponent を利用する際は、前述のようにフォームを閉じる際は、 必ず `Cake\View\Helper\FormHelper::end()` を使う必要があります。 これにより特別な `_Token` 入力が生成されます。

`method` Cake\\View\\Helper\\FormHelper::**unlockField**($name)

*   `$name` - オプション。ドット区切りのフィールド名。

`SecurityComponent` によるフィールドのハッシュ化が行われないようにフィールドのロックを 解除します。またこれにより、そのフィールドを JavaScript で操作できるようになります。 `$name` には入力のためのエンティティーのプロパティー名を指定します。 :

    $this->Form->unlockField('id');

1  

`method` Cake\\View\\Helper\\FormHelper::**secure**(array $fields = \[\], array $secureAttributes = \[\])

*   `$fields` - オプション。ハッシュの生成に使用するフィールドの一覧を含む配列。 指定がない場合、 `$this->fields` が使用されます。
*   `$secureAttributes` - オプション。生成される hidden 入力要素の中に渡す HTML 属性の配列。

フォームで使用されるフィールドに基づくセキュリティーハッシュをもつ 非表示の `input` フィールドを生成し、または、保護されたフォームが使用されていない場合は 空の文字列を生成します。 `$secureAttributes` を設定した場合、これらの HTML 属性は、 SecurityCompnent によって生成された非表示の input タグの中にマージされます。 これは、 `'form'` のような HTML5 属性を設定するのに特に便利です。

---

# Upgrade Tool | CakePHP

[Skip to content](https://book.cakephp.org/3.x/upgrade-tool.html#VPContent)

Return to top

Upgrade Tool [​](https://book.cakephp.org/3.x/upgrade-tool.html#upgrade-tool)

==============================================================================

Upgrading to CakePHP 3 from CakePHP 2.x requires a number of transformations that can be automated, such as adding namespaces. To assist in making these mechanical changes easier, CakePHP provides a CLI based upgrade tool.

Installation [​](https://book.cakephp.org/3.x/upgrade-tool.html#installation)

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

The upgrade tool is installed as a standalone application. You'll need to clone the upgrade tool with git, and install the dependencies with composer:

    git clone https://github.com/cakephp/upgrade.git -b 3.x
    cd upgrade
    php ../composer.phar install
    

At this point you should be able to get the help for the upgrade tool:

    cd upgrade
    bin/cake upgrade --help
    

The above should output something like the following:

    Welcome to CakePHP v3.0.8 Console
    ---------------------------------------------------------------
    App : src
    Path: /Users/markstory/Sites/cake_plugins/upgrade/src/
    ---------------------------------------------------------------
    A shell to help automate upgrading from CakePHP 2.x to 3.x. Be sure to
    have a backup of your application before running these commands.
    
    Usage:
    cake upgrade [subcommand] [-h] [-v] [-q]
    
    Subcommands:
    
    locations           Move files/directories around. Run this *before*
                        adding namespaces with the namespaces command.
    namespaces          Add namespaces to files based on their file path.
                        Only run this *after* you have moved files.
    app_uses            Replace App::uses() with use statements
    rename_classes      Rename classes that have been moved/renamed. Run
                        after replacing App::uses() with use statements.
    rename_collections  Rename HelperCollection, ComponentCollection, and
                        TaskCollection. Will also rename component
                        constructor arguments and _Collection properties on
                        all objects.
    method_names        Update many of the methods that were renamed during
                        2.x -> 3.0
    method_signatures   Update many of the method signatures that were
                        changed during 2.x -> 3.0
    fixtures            Update fixtures to use new index/constraint
                        features. This is necessary before running tests.
    tests               Update test cases regarding fixtures.
    i18n                Update translation functions regarding placeholders.
    skeleton            Add basic skeleton files and folders from the "app"
                        repository.
    prefixed_templates  Move view templates for prefixed actions.
    all                 Run all tasks except for skeleton. That task should
                        only be run manually, and only for apps (not
                        plugins).
    
    To see help on a subcommand use `cake upgrade [subcommand] --help`
    
    Options:
    
    --help, -h     Display this help.
    --verbose, -v  Enable verbose output.
    --quiet, -q    Enable quiet output.

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40  
41  
42  
43  
44  
45  
46  

Usage [​](https://book.cakephp.org/3.x/upgrade-tool.html#usage)

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

Once you have correctly installed the upgrade tool, you are ready to start using it on a 2.x application.

WARNING

Make sure you have backups/version control for your application's code.

It is also a good idea to make a backup/commits after each sub-command.

To start off run the `locations` command:

    # View the options for the command
    bin/cake upgrade locations --help
    
    # Run the command in dry run mode.
    bin/cake upgrade locations --dry-run /path/to/app

1  
2  
3  
4  
5  

The above will give a dry run output of what would happen. When you are ready to run the command for real, remove the `--dry-run` flag. By using the `--git` flag the upgrade tool can automate moving files in git.

Once file locations have been updated, you can add namespaces to your code using the `namespaces` command:

    # View the options for the command
    bin/cake upgrade namespaces --help
    
    # Run the command in dry run mode
    bin/cake upgrade namespaces --dry-run /path/to/app
    
    # Run the command for real
    bin/cake upgrade namespaces /path/to/app

1  
2  
3  
4  
5  
6  
7  
8  

After these two commands, you can run the remaining subcommands in any order.

---

# Flash | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/views/helpers/flash.html#VPContent)

Return to top

Flash [​](https://book.cakephp.org/3.x/ja/views/helpers/flash.html#flash)

==========================================================================

`class` Cake\\View\\Helper\\**FlashHelper**(View $view, array $config = \[\])

FlashHelperは、 [FlashComponent](https://book.cakephp.org/3.x/ja/controllers/components/flash.html)
 によって `$_SESSION` にセットされたフラッシュメッセージを描画する方法を提供しています。 [FlashComponent](https://book.cakephp.org/3.x/ja/controllers/components/flash.html)
 および FlashHelper はフラッシュメッセージを描画するためのエレメントを使用します。 フラッシュエレメントは **src/Template/Element/Flash** ディレクトリー以下に存在します。 CakePHP の App テンプレートには、 **success.ctp** 、 **default.ctp** と **error.ctp** の 3つのフラッシュエレメントが付属しています。

フラッシュメッセージの描画 [​](https://book.cakephp.org/3.x/ja/views/helpers/flash.html#%E3%83%95%E3%83%A9%E3%83%83%E3%82%B7%E3%83%A5%E3%83%A1%E3%83%83%E3%82%BB%E3%83%BC%E3%82%B7%E3%82%99%E3%81%AE%E6%8F%8F%E7%94%BB)

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

フラッシュメッセージを描画するためには、テンプレートファイルの中で FlashHelper の `render()` メソッドを使用します。 :

    <?= $this->Flash->render() ?>

1  

デフォルトでは、CakePHP は、フラッシュメッセージのためにセッション中の "flash" キーを使用します。 しかし、 [FlashComponent](https://book.cakephp.org/3.x/ja/controllers/components/flash.html)
 の中でフラッシュメッセージを 設定した時にキーを指定した場合、そのキーを指定して描画します。 :

    <?= $this->Flash->render('other') ?>

1  

FlashComponent の中で設定したオプションを上書きすることもできます。 :

    // コントローラーの中で
    $this->Flash->set('The user has been saved.', [\
        'element' => 'success'\
    ]);
    
    // テンプレートファイルの中で、 success.ctp の代わりに great_success.ctp を使用
    <?= $this->Flash->render('flash', [\
        'element' => 'great_success'\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  

NOTE

フラッシュメッセージの独自テンプレートを作成する場合、全てのユーザーデータを適切に HTML エンコードしてください。CakePHP は、フラッシュメッセージのパラメーターをエスケープしません。

Added in version 3.1

[FlashComponent](https://book.cakephp.org/3.x/ja/controllers/components/flash.html)
 はメッセージをスタックしています。 複数のフラッシュメッセージをセットした場合、 `render()` を呼び出すと、それぞれのメッセージが 設定された順番でそれぞれのエレメントの中で描画されます。

使用できる配列オプションについてもっと知りたい場合は、 [FlashComponent](https://book.cakephp.org/3.x/ja/controllers/components/flash.html)
 セクションをご覧ください。

ルーティングのプレフィックスとフラッシュメッセージ [​](https://book.cakephp.org/3.x/ja/views/helpers/flash.html#%E3%83%AB%E3%83%BC%E3%83%86%E3%82%A3%E3%83%B3%E3%82%AF%E3%82%99%E3%81%AE%E3%83%95%E3%82%9A%E3%83%AC%E3%83%95%E3%82%A3%E3%83%83%E3%82%AF%E3%82%B9%E3%81%A8%E3%83%95%E3%83%A9%E3%83%83%E3%82%B7%E3%83%A5%E3%83%A1%E3%83%83%E3%82%BB%E3%83%BC%E3%82%B7%E3%82%99)

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

Added in version 3.0.1

設定したルーティングのプレフィックスがある場合、フラッシュエレメントを **src/Template/{Prefix}/Element/Flash** に置きます。 これにより、アプリケーションの各部分に特定のメッセージレイアウトを設定できます。 例えば、フロントエンドと管理者のセクションで異なるレイアウトを使用する場合です。

フラッシュメッセージとテーマ [​](https://book.cakephp.org/3.x/ja/views/helpers/flash.html#%E3%83%95%E3%83%A9%E3%83%83%E3%82%B7%E3%83%A5%E3%83%A1%E3%83%83%E3%82%BB%E3%83%BC%E3%82%B7%E3%82%99%E3%81%A8%E3%83%86%E3%83%BC%E3%83%9E)

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

FlashHelper は、メッセージを描画するために標準のエレメントを使用し、指定したテーマに従います。 そのため、テーマが **src/Template/Element/Flash/error.ctp** ファイルを持つ場合、 エレメントやビューと同様に使用されます。

---

# CMS Tutorial - Authentication | CakePHP

[Skip to content](https://book.cakephp.org/3.x/tutorials-and-examples/cms/authentication.html#VPContent)

Return to top

CMS Tutorial - Authentication [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/authentication.html#cms-tutorial-authentication)

===========================================================================================================================================

Now that our CMS has users, we should enable them to login, and apply some basic access control to the article creation & editing experiences.

Adding Password Hashing [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/authentication.html#adding-password-hashing)

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

If you were to create/update a user at this point in time, you might notice that the passwords are stored in plain text. This is really bad from a security point of view, so lets fix that.

This is also a good time to talk about the model layer in CakePHP. In CakePHP, we separate the methods that operate on a collection of objects, and a single object into different classes. Methods that operate on the collection of entities are put in the `Table` class, while features belonging to a single record are put on the `Entity` class.

For example, password hashing is done on the individual record, so we'll implement this behavior on the entity object. Because we want to hash the password each time it is set, we'll use a mutator/setter method. CakePHP will call convention based setter methods any time a property is set in one of your entities. Let's add a setter for the password. In **src/Model/Entity/User.php** add the following:

    <?php
    namespace App\Model\Entity;
    
    use Cake\Auth\DefaultPasswordHasher; // Add this line
    use Cake\ORM\Entity;
    
    class User extends Entity
    {
        // Code from bake.
    
        // Add this method
        protected function _setPassword($value)
        {
            if (strlen($value)) {
                $hasher = new DefaultPasswordHasher();
    
                return $hasher->hash($value);
            }
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  

Now, point your browser to **[http://localhost:8765/users](http://localhost:8765/users)
** to see a list of users. You can edit the default user that was created during [Installation](https://book.cakephp.org/3.x/installation.html)
. If you change that user's password, you should see a hashed password instead of the original value on the list or view pages. CakePHP hashes passwords with [bcrypt](https://codahale.com/how-to-safely-store-a-password/)
 by default. You can also use SHA-1 or MD5 if you're working with an existing database, but we recommend bcrypt for all new applications.

NOTE

Create a hashed password for at least one of the user accounts now! It will be needed in the next steps.

### Adding Login [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/authentication.html#adding-login)

In CakePHP, authentication is handled by [Components](https://book.cakephp.org/3.x/controllers/components.html)
. Components can be thought of as ways to create reusable chunks of controller code related to a specific feature or concept. Components can hook into the controller's event life-cycle and interact with your application that way. To get started, we'll add the [AuthComponent](https://book.cakephp.org/3.x/controllers/components/authentication.html)
 to our application. We'll want the create, update and delete methods to require authentication, so we'll add AuthComponent in our AppController:

    // In src/Controller/AppController.php
    namespace App\Controller;
    
    use Cake\Controller\Controller;
    
    class AppController extends Controller
    {
        public function initialize()
        {
            // Existing code
    
            $this->loadComponent('Auth', [\
                'authenticate' => [\
                    'Form' => [\
                        'fields' => [\
                            'username' => 'email',\
                            'password' => 'password'\
                        ]\
                    ]\
                ],\
                'loginAction' => [\
                    'controller' => 'Users',\
                    'action' => 'login'\
                ],\
                 // If unauthorized, return them to page they were just on\
                'unauthorizedRedirect' => $this->referer()\
            ]);
    
            // Allow the display action so our PagesController
            // continues to work. Also enable the read only actions.
            $this->Auth->allow(['display', 'view', 'index']);
        }
    
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  

We've just told CakePHP that we want to load the `Auth` component. We've customized the configuration of AuthComponent, as our users table uses `email` as the username. Now, if you go any protected URL, such as `/articles/add`, you'll be redirected to **/users/login**, which will show an error page as we have not written that code yet. So let's create the login action:

    // In src/Controller/UsersController.php
    public function login()
    {
        if ($this->request->is('post')) {
            $user = $this->Auth->identify();
            if ($user) {
                $this->Auth->setUser($user);
                return $this->redirect($this->Auth->redirectUrl());
            }
            $this->Flash->error('Your username or password is incorrect.');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

Create a new template **src/Template/Users/login.ctp** and add the following:

    <h1>Login</h1>
    <?= $this->Form->create() ?>
    <?= $this->Form->control('email') ?>
    <?= $this->Form->control('password') ?>
    <?= $this->Form->button('Login') ?>
    <?= $this->Form->end() ?>

1  
2  
3  
4  
5  
6  

Now that we have a simple login form, we should be able to log in with one of the users that has a hashed password.

NOTE

If none of your users have hashed passwords, comment the `loadComponent('Auth')` block and `$this->Auth->allow()` calls. Then go and edit the user, saving a new password for them. After saving a new password for the user, make sure to uncomment the lines we just temporarily commented!

Try it out! Before logging in, visit `/articles/add`. Since this action is not allowed, you will be redirected to the login page. After logging in successfully, CakePHP will automatically redirect you back to `/articles/add`.

### Adding Logout [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/authentication.html#adding-logout)

Now that people can log in, you'll probably want to provide a way to log out as well. Again, in the `UsersController`, add the following code:

    public function initialize()
    {
        parent::initialize();
        $this->Auth->allow(['logout']);
    }
    
    public function logout()
    {
        $this->Flash->success('You are now logged out.');
        return $this->redirect($this->Auth->logout());
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

This code adds the `logout` action to the list of actions that do not require authentication and implements the logout method. Now you can visit `/users/logout` to log out. You should then be sent to the login page.

### Enabling Registrations [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/authentication.html#enabling-registrations)

If you aren't logged in and you try to visit **/users/add** you will be redirected to the login page. We should fix that as we want to allow people to sign up for our application. In the `UsersController` add the following:

    public function initialize()
    {
        parent::initialize();
        // Add the 'add' action to the allowed actions list.
        $this->Auth->allow(['logout', 'add']);
    }

1  
2  
3  
4  
5  
6  

The above tells `AuthComponent` that the `add()` action of the `UsersController` does _not_ require authentication or authorization. You may want to take the time to clean up the **Users/add.ctp** and remove the misleading links, or continue on to the next section. We won't be building out user editing, viewing or listing in this tutorial, but that is an exercise you can complete on your own.

### Restricting Article Access [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/authentication.html#restricting-article-access)

Now that users can log in, we'll want to limit users to only edit articles that they created. We'll do this using an 'authorization' adapter. Since our requirements are basic, we can use a controller hook method in our `ArticlesController`. But before we do that, we'll want to tell the `AuthComponent` how our application is going to authorize actions. Update your `AppController` adding the following:

    public function isAuthorized($user)
    {
        // By default deny access.
        return false;
    }

1  
2  
3  
4  
5  

Next we'll tell `AuthComponent` that we want to use controller hook methods for authorization. Your `AppController::initialize()` method should now look like:

    public function initialize()
    {
        // Existing code
    
        $this->loadComponent('Flash');
        $this->loadComponent('Auth', [\
            // Added this line\
            'authorize'=> 'Controller',\
            'authenticate' => [\
                'Form' => [\
                    'fields' => [\
                        'username' => 'email',\
                        'password' => 'password'\
                    ]\
                ]\
            ],\
            'loginAction' => [\
                'controller' => 'Users',\
                'action' => 'login'\
            ],\
             // If unauthorized, return them to page they were just on\
            'unauthorizedRedirect' => $this->referer()\
        ]);
    
        // Allow the display action so our pages controller
        // continues to work. Also enable the read only actions.
        $this->Auth->allow(['display', 'view', 'index']);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  

We'll default to denying access, and incrementally grant access where it makes sense. First, we'll add the authorization logic for articles. In your `ArticlesController` add the following:

    public function isAuthorized($user)
    {
        $action = $this->request->getParam('action');
        // The add and tags actions are always allowed to logged in users.
        if (in_array($action, ['add', 'tags'])) {
            return true;
        }
    
        // All other actions require a slug.
        $slug = $this->request->getParam('pass.0');
        if (!$slug) {
            return false;
        }
    
        // Check that the article belongs to the current user.
        $article = $this->Articles->findBySlug($slug)->first();
    
        return $article->user_id === $user['id'];
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  

Now if you try to edit or delete an article that does not belong to you, you should be redirected back to the page you came from. If no error message is displayed, add the following to your layout:

    // In src/Template/Layout/default.ctp
    <?= $this->Flash->render() ?>

1  
2  

Next you should add the `tags` action to the actions allowed for unauthenticated users, by adding the following to `initialize()` in **src/Controller/ArticlesController.php**:

    $this->Auth->allow(['tags']);

1  

While the above is fairly simplistic it illustrates how you could build more complex logic that combines the current user and request data to build flexible authorization logic.

### Fixing the Add & Edit Actions [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/authentication.html#fixing-the-add-edit-actions)

While we've blocked access to the edit action, we're still open to users changing the `user_id` attribute of articles during edit. We will solve these problems next. First up is the `add` action.

When creating articles, we want to fix the `user_id` to be the currently logged in user. Replace your add action with the following:

    // in src/Controller/ArticlesController.php
    
    public function add()
    {
        $article = $this->Articles->newEntity();
        if ($this->request->is('post')) {
            $article = $this->Articles->patchEntity($article, $this->request->getData());
    
            // Changed: Set the user_id from the session.
            $article->user_id = $this->Auth->user('id');
    
            if ($this->Articles->save($article)) {
                $this->Flash->success(__('Your article has been saved.'));
                return $this->redirect(['action' => 'index']);
            }
            $this->Flash->error(__('Unable to add your article.'));
        }
        $this->set('article', $article);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  

Next we'll update the `edit` action. Replace the edit method with the following:

    // in src/Controller/ArticlesController.php
    
    public function edit($slug)
    {
        $article = $this->Articles
            ->findBySlug($slug)
            ->contain('Tags') // load associated Tags
            ->firstOrFail();
    
        if ($this->request->is(['post', 'put'])) {
            $this->Articles->patchEntity($article, $this->request->getData(), [\
                // Added: Disable modification of user_id.\
                'accessibleFields' => ['user_id' => false]\
            ]);
            if ($this->Articles->save($article)) {
                $this->Flash->success(__('Your article has been updated.'));
                return $this->redirect(['action' => 'index']);
            }
            $this->Flash->error(__('Unable to update your article.'));
        }
        $this->set('article', $article);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  

Here we're modifying which properties can be mass-assigned, via the options for `patchEntity()`. See the [Changing Accessible Fields](https://book.cakephp.org/3.x/orm/saving-data.html#changing-accessible-fields)
 section for more information. Remember to remove the `user_id` control from **src/Template/Articles/edit.ctp** as we no longer need it.

### Wrapping Up [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/authentication.html#wrapping-up)

We've built a simple CMS application that allows users to login, post articles, tag them, explore posted articles by tag, and applied basic access control to articles. We've also added some nice UX improvements by leveraging the FormHelper and ORM capabilities.

Thank you for taking the time to explore CakePHP. Next, you should learn more about the [Database Access & ORM](https://book.cakephp.org/3.x/orm.html)
, or you peruse the [Using CakePHP](https://book.cakephp.org/3.x/topics.html)
.

---

# ビューセル | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/views/cells.html#VPContent)

Return to top

ビューセル [​](https://book.cakephp.org/3.x/ja/views/cells.html#%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC%E3%82%BB%E3%83%AB)

===================================================================================================================

ビューセルはビュー処理やテンプレート出力を実行できる小さな小さなコントローラーです。 セルのアイディアは [Ruby のセル](https://github.com/trailblazer/cells)
 から拝借したもので、 同様の役割と目的を果たします。

セルを使う時 [​](https://book.cakephp.org/3.x/ja/views/cells.html#%E3%82%BB%E3%83%AB%E3%82%92%E4%BD%BF%E3%81%86%E6%99%82)

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

セルは、モデルとの対話、ビュー処理、および出力処理を必要とする、再利用可能なページ部品を 構築するのに理想的です。単純な例はオンライン店舗の買い物かご、あるいは CMS のデータ駆動型の ナビゲーションメニューなどになるでしょう。

セルの作成 [​](https://book.cakephp.org/3.x/ja/views/cells.html#%E3%82%BB%E3%83%AB%E3%81%AE%E4%BD%9C%E6%88%90)

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

セルを作成するには、 **src/View/Cell** にクラスを、 **src/Template/Cell/** にテンプレートを 定義します。この例では、ユーザーの通知受信トレイにいくつかのメッセージを表示するために セルを作ることにします。まず、クラスファイルを作ります。中身はこのようになります。 :

    namespace App\View\Cell;
    
    use Cake\View\Cell;
    
    class InboxCell extends Cell
    {
    
        public function display()
        {
        }
    
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

このファイルを **src/View/Cell/InboxCell.php** に保存します。ご覧の通り、 CakePHP の他のクラスと同様に、セルはいくつかの規約を持っています。

*   セルは `App\View\Cell` 名前空間に置かれます。もしプラグインの中でセルを作るのであれば、 その名前空間は `PluginName\View\Cell` になります。
*   クラス名は Cell で終わらなければなりません。
*   クラスは `Cake\View\Cell` を継承しなければなりません。

私たちのセルには空の `display()` メソッドを追加しましたが、これはセルを描画する時の 規約上の既定のメソッドです。この文書の後ろで、他のメソッドの使い方についても扱います。 さて、ファイル **src/Template/Cell/Inbox/display.ctp** を作成しましょう。 これは、私たちの新しいセルのためのテンプレートになります。

`bake` を使って手早くこのスタブコードを生成することもできます。 :

    bin/cake bake cell Inbox
    

これは上記で作成したコードを生成してくれるでしょう。

セルの実装 [​](https://book.cakephp.org/3.x/ja/views/cells.html#%E3%82%BB%E3%83%AB%E3%81%AE%E5%AE%9F%E8%A3%85)

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

ユーザー同士で互いにメッセージを送りあえるアプリケーションを開発しているとしましょう。 私たちは `Messages` モデルを持っていて、そして AppController を汚さずに 未読メッセージの数を表示したいとします。これはまさにセルを使用するケースです。 先ほど作ったクラスに、以下を追加します。 :

    namespace App\View\Cell;
    
    use Cake\View\Cell;
    
    class InboxCell extends Cell
    {
    
        public function display()
        {
            $this->loadModel('Messages');
            $unread = $this->Messages->find('unread');
            $this->set('unread_count', $unread->count());
        }
    
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

セルは `ModelAwareTrait` と `ViewVarsTrait` を使用しているため、コントローラーに とてもよく似たふるまいをします。コントローラー中とまったく同じように、 `loadModel()` や `set()` メソッドを使うことができます。テンプレートファイルの中に、 以下を追加します。 :

    <!-- src/Template/Cell/Inbox/display.ctp -->
    <div class="notification-icon">
        未読メッセージが <?= $unread_count ?> 件あります。
    </div>

1  
2  
3  
4  

NOTE

セルのテンプレートは分離したスコープを持っていて、現在のコントローラーのアクション または他のセル用のテンプレートやレイアウトを描画するのに使われたビューのインスタンスを 共有しません。したがって、アクションのテンプレートやレイアウト中でのヘルパーの呼び出し あるいはブロックのセットなどには気付きません。

セルの呼び出し [​](https://book.cakephp.org/3.x/ja/views/cells.html#%E3%82%BB%E3%83%AB%E3%81%AE%E5%91%BC%E3%81%B2%E3%82%99%E5%87%BA%E3%81%97)

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

セルは `cell()` メソッドを使ってビューから呼び出すことができて、下のいずれのコンテキストでも 同様に動きます。 :

    // アプリケーションのセルの呼び出し
    $cell = $this->cell('Inbox');
    
    // プラグインのセルの呼び出し
    $cell = $this->cell('Messaging.Inbox');

1  
2  
3  
4  
5  

上記は当該の名前のセルを呼び出して、その `display()` メソッドを実行します。 以下のようにして、他のメソッドを実行することもできます。 :

    // Inbox セル上の expanded() メソッドを実行します
    $cell = $this->cell('Inbox::expanded');

1  
2  

もしもリクエスト中でどのセルを呼び出すかを決定するためのコントローラー処理が必要な場合、 コントローラー中で `cell()` メソッドを有効にするために `CellTrait` を使用することができます。 :

    namespace App\Controller;
    
    use App\Controller\AppController;
    use Cake\View\CellTrait;
    
    class DashboardsController extends AppController
    {
        use CellTrait;
    
        // 他のコード。
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

セルに引数を渡す [​](https://book.cakephp.org/3.x/ja/views/cells.html#%E3%82%BB%E3%83%AB%E3%81%AB%E5%BC%95%E6%95%B0%E3%82%92%E6%B8%A1%E3%81%99)

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

セルをより柔軟にするために、パラメーター付きのセルのメソッドが必要になることも多いでしょう。 添字付きの配列として `cell()` の第二、第三引数を使用することで、アクションのパラメーターや、 追加のオプションをセルクラスに渡すことができます。 :

    $cell = $this->cell('Inbox::recent', ['-3 days']);

1  

上記は以下のような関数の定義になるでしょう。 :

    public function recent($since)
    {
    }

1  
2  
3  

ビューの描画 [​](https://book.cakephp.org/3.x/ja/views/cells.html#%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC%E3%81%AE%E6%8F%8F%E7%94%BB)

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

セルが呼び出されて実行された後は、おそらくそれを描画したいはずです。セルを描画するための 最も簡単な方法はそれをエコーすることです。 :

    <?= $cell ?>

1  

これはアクション名を小文字にしてアンダースコアー区切りにしたものに一致するテンプレートを 描画します。例えば **display.ctp** です。

セルはテンプレートを描画するために `View` を使用しますので、もし必要であれば セルのテンプレートの中で追加のセルを呼び出すこともできます。

NOTE

セルをエコーすると PHP のマジックメソッド `__toString()` を使用するため 致命的なエラーが発生した際にファイル名や行番号を表示するのを抑制してしまいます。 意味のあるエラーメッセージを得るためには、例えば `<?= $cell->render() ?>` のようにして、 `Cell::render()` メソッドを使用することを推奨します。

### 別のテンプレートの描画 [​](https://book.cakephp.org/3.x/ja/views/cells.html#%E5%88%A5%E3%81%AE%E3%83%86%E3%83%B3%E3%83%95%E3%82%9A%E3%83%AC%E3%83%BC%E3%83%88%E3%81%AE%E6%8F%8F%E7%94%BB)

規約ではセルは実行するアクションに一致するテンプレートを描画します。 もし、異なるビューテンプレートを描画する必要があれば、セルを描画する時に 使用するテンプレートを指定することができます。 :

    // 明示的に render() を呼び出します
    echo $this->cell('Inbox::recent', ['-3 days'])->render('messages');
    
    // セルをエコーする前にテンプレートを設定します。
    $cell = $this->cell('Inbox');
    $cell->viewBuilder()->setTemplate('messages');
    // 3.4 より前
    $cell->viewBuilder()->template('messages');
    // 3.1 より前
    $cell->template = 'messages';
    echo $cell;

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

### セルの出力のキャッシュ [​](https://book.cakephp.org/3.x/ja/views/cells.html#%E3%82%BB%E3%83%AB%E3%81%AE%E5%87%BA%E5%8A%9B%E3%81%AE%E3%82%AD%E3%83%A3%E3%83%83%E3%82%B7%E3%83%A5)

もしも出力内容が頻繁には変わらない、あるいはアプリケーションのパフォーマンス向上のために、 セルを描画する際にその出力をキャッシュしたいかもしれません。キャッシュを有効にする、あるいは 設定するために、セルを作成する時に `cache` オプションを定義することができます。 :

    // 既定の設定と生成キーを使用してキャッシュします
    $cell = $this->cell('Inbox', [], ['cache' => true]);
    
    // 特定のキャッシュ設定と生成キーでキャッシュします
    $cell = $this->cell('Inbox', [], ['cache' => ['config' => 'cell_cache']]);
    
    // 使用するキーと設定を指定します。
    $cell = $this->cell('Inbox', [], [\
        'cache' => ['config' => 'cell_cache', 'key' => 'inbox_' . $user->id]\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

キーが生成される場合には、そのクラスとテンプレートの名前をアンダースコアー区切りにしたものが 使用されます。

NOTE

各セルを描画するために新しい `View` インスタンスが作成され、それらの新しいオブジェクトは メインのテンプレート／レイアウトとはコンテキストを共有しません。各セルは内包されていて、 `View::cell()` の呼び出しの引数として渡された変数にのみアクセスが可能です。

セル内のデータのページ制御 [​](https://book.cakephp.org/3.x/ja/views/cells.html#%E3%82%BB%E3%83%AB%E5%86%85%E3%81%AE%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%81%AE%E3%83%98%E3%82%9A%E3%83%BC%E3%82%B7%E3%82%99%E5%88%B6%E5%BE%A1)

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

ページ制御された結果セットを描画するセルを作成するには、ORM の `Paginator` クラスを利用します。 ユーザーのお気に入りメッセージをページ制御する例は次のようになります。 :

    namespace App\View\Cell;
    
    use Cake\View\Cell;
    use Cake\Datasource\Paginator;
    
    class FavoritesCell extends Cell
    {
        public function display($user)
        {
            $this->loadModel('Messages');
    
            // paginator の作成
            $paginator = new Paginator();
    
            // モデルをページ制御
            $results = $paginator->paginate(
                $this->Messages,
                $this->request->getQueryParams(),
                [\
                    // パラメーター付きカスタムファインダーを使用\
                    'finder' => ['favorites' => [$user]],\
    \
                    // スコープ指定のクエリー文字列パラメーターを使用\
                    'scope' => 'favorites',\
                ]
            );
    
            $paging = $paginator->getPagingParams() + (array)$request->getParam('paging');
            $this->request = $this->request->withParam('paging', $paging));
    
            $this->set('favorites', $results);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  

上記のセルは、 [スコープ指定のページ制御パラメーター](https://book.cakephp.org/3.x/ja/controllers/components/pagination.html#paginating-multiple-queries)
 を使用して `Messages` モデルをページ制御します。

Added in version 3.5.0

`Cake\Datasource\Paginator` は 3.5.0 で追加されました。

セルのオプション [​](https://book.cakephp.org/3.x/ja/views/cells.html#%E3%82%BB%E3%83%AB%E3%81%AE%E3%82%AA%E3%83%95%E3%82%9A%E3%82%B7%E3%83%A7%E3%83%B3)

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

セルは、セルオブジェクトの作成時にプロパティーに変換されるコンストラクターオプションを宣言できます。 :

    namespace App\View\Cell;
    
    use Cake\View\Cell;
    use Cake\Datasource\Paginator;
    
    class FavoritesCell extends Cell
    {
        protected $_validCellOptions = ['limit'];
    
        protected $limit = 3;
    
        public function display($userId)
        {
            $this->loadModel('Users');
            $result = $this->Users->find('friends', ['for' => $userId]);
            $this->set('favorites', $result);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

ここでは、 `$limit` プロパティーを定義し、 `limit` をセルのオプションとして追加しました。 これにより、セルの作成時にオプションを定義することができます。 :

    $cell = $this->cell('Favorites', [$user->id], ['limit' => 10])

1  

セルのオプションは、データをプロパティーとして使用してデフォルト値を オーバーライドできるようにする場合に便利です。

---

# Security | CakePHP

[Skip to content](https://book.cakephp.org/3.x/security.html#VPContent)

Return to top

Security [​](https://book.cakephp.org/3.x/security.html#security)

==================================================================

CakePHP provides you some tools to secure your application. The following sections cover those tools:

*   [Security Utility](https://book.cakephp.org/3.x/core-libraries/security.html)
    
*   [Cross Site Request Forgery](https://book.cakephp.org/3.x/controllers/components/csrf.html)
    
*   [Security Component](https://book.cakephp.org/3.x/controllers/components/security.html)

---

# Views | CakePHP

[Skip to content](https://book.cakephp.org/3.x/views.html#VPContent)

Return to top

Views [​](https://book.cakephp.org/3.x/views.html#views)

=========================================================

`class` Cake\\View\\**View**

Views are the **V** in MVC. Views are responsible for generating the specific output required for the request. Often this is in the form of HTML, XML, or JSON, but streaming files and creating PDFs that users can download are also responsibilities of the View Layer.

CakePHP comes with a few built-in View classes for handling the most common rendering scenarios:

*   To create XML or JSON webservices you can use the [JSON and XML views](https://book.cakephp.org/3.x/views/json-and-xml-views.html)
    .
*   To serve protected files, or dynamically generated files, you can use [Cake Response File](https://book.cakephp.org/3.x/controllers/request-response.html#cake-response-file)
    .
*   To create multiple themed views, you can use [Themes](https://book.cakephp.org/3.x/views/themes.html)
    .

The App View [​](https://book.cakephp.org/3.x/views.html#the-app-view)

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

`AppView` is your application’s default View class. `AppView` itself extends the `Cake\View\View` class included in CakePHP and is defined in **src/View/AppView.php** as follows:

    <?php
    namespace App\View;
    
    use Cake\View\View;
    
    class AppView extends View
    {
    }

1  
2  
3  
4  
5  
6  
7  
8  

You can use your `AppView` to load helpers that will be used for every view rendered in your application. CakePHP provides an `initialize()` method that is invoked at the end of a View’s constructor for this kind of use:

    <?php
    namespace App\View;
    
    use Cake\View\View;
    
    class AppView extends View
    {
        public function initialize()
        {
            // Always enable the MyUtils Helper
            $this->loadHelper('MyUtils');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

View Templates [​](https://book.cakephp.org/3.x/views.html#view-templates)

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

The view layer of CakePHP is how you speak to your users. Most of the time your views will be rendering HTML/XHTML documents to browsers, but you might also need to reply to a remote application via JSON, or output a CSV file for a user.

CakePHP template files have a default extension of **.ctp** (CakePHP Template) and utilize the [alternative PHP syntax](https://php.net/manual/en/control-structures.alternative-syntax.php)
 for control structures and output. These files contain the logic necessary to prepare the data received from the controller into a presentation format that is ready for your audience.

### Alternative Echos [​](https://book.cakephp.org/3.x/views.html#alternative-echos)

Echo, or print a variable in your template:

    <?php echo $variable; ?>

1  

Using Short Tag support:

    <?= $variable ?>

1  

### Alternative Control Structures [​](https://book.cakephp.org/3.x/views.html#alternative-control-structures)

Control structures, like `if`, `for`, `foreach`, `switch`, and `while` can be written in a simplified format. Notice that there are no braces. Instead, the end brace for the `foreach` is replaced with `endforeach`. Each of the control structures listed above has a similar closing syntax: `endif`, `endfor`, `endforeach`, and `endwhile`. Also notice that instead of using a `semicolon` after each structure (except the last one), there is a `colon`.

The following is an example using `foreach`:

    <ul>
    <?php foreach ($todo as $item): ?>
      <li><?= $item ?></li>
    <?php endforeach; ?>
    </ul>

1  
2  
3  
4  
5  

Another example, using if/elseif/else. Notice the colons:

    <?php if ($username === 'sally'): ?>
       <h3>Hi Sally</h3>
    <?php elseif ($username === 'joe'): ?>
       <h3>Hi Joe</h3>
    <?php else: ?>
       <h3>Hi unknown user</h3>
    <?php endif; ?>

1  
2  
3  
4  
5  
6  
7  

If you'd prefer using a templating language like [Twig](https://twig.sensiolabs.org/)
, a subclass of View will bridge your templating language and CakePHP.

Template files are stored in **src/Template/**, in a folder named after the controller that uses the files, and named after the action it corresponds to. For example, the view file for the `Products` controller's `view()` action, would normally be found in **src/Template/Products/view.ctp**.

The view layer in CakePHP can be made up of a number of different parts. Each part has different uses, and will be covered in this chapter:

*   **templates**: Templates are the part of the page that is unique to the action being run. They form the meat of your application's response.
*   **elements**: small, reusable bits of view code. Elements are usually rendered inside views.
*   **layouts**: template files that contain presentational code that wraps many interfaces in your application. Most views are rendered inside a layout.
*   **helpers**: these classes encapsulate view logic that is needed in many places in the view layer. Among other things, helpers in CakePHP can help you build forms, build AJAX functionality, paginate model data, or serve RSS feeds.
*   **cells**: these classes provide miniature controller-like features for creating self contained UI components. See the [View Cells](https://book.cakephp.org/3.x/views/cells.html)
     documentation for more information.

### View Variables [​](https://book.cakephp.org/3.x/views.html#view-variables)

Any variables you set in your controller with `set()` will be available in both the view and the layout your action renders. In addition, any set variables will also be available in any element. If you need to pass additional variables from the view to the layout you can either call `set()` in the view template, or use a [View Blocks](https://book.cakephp.org/3.x/views.html#view-blocks)
.

You should remember to **always** escape any user data before outputting it as CakePHP does not automatically escape output. You can escape user content with the `h()` function:

    <?= h($user->bio); ?>

1  

### Setting View Variables [​](https://book.cakephp.org/3.x/views.html#setting-view-variables)

`method` Cake\\View\\View::**set**(string $var, mixed $value)

Views have a `set()` method that is analogous to the `set()` found in Controller objects. Using set() from your view file will add the variables to the layout and elements that will be rendered later. See [Setting View Variables](https://book.cakephp.org/3.x/controllers.html#setting-view-variables)
 for more information on using `set()`.

In your view file you can do:

    $this->set('activeMenuButton', 'posts');

1  

Then, in your layout, the `$activeMenuButton` variable will be available and contain the value 'posts'.

### Extending Views [​](https://book.cakephp.org/3.x/views.html#extending-views)

View extending allows you to wrap one view in another. Combining this with [view blocks](https://book.cakephp.org/3.x/views.html#view-blocks)
 gives you a powerful way to keep your views `DRY`. For example, your application has a sidebar that needs to change depending on the specific view being rendered. By extending a common view file, you can avoid repeating the common markup for your sidebar, and only define the parts that change:

    <!-- src/Template/Common/view.ctp -->
    <h1><?= h($this->fetch('title')) ?></h1>
    <?= $this->fetch('content') ?>
    
    <div class="actions">
        <h3>Related actions</h3>
        <ul>
        <?= $this->fetch('sidebar') ?>
        </ul>
    </div>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

The above view file could be used as a parent view. It expects that the view extending it will define the `sidebar` and `title` blocks. The `content` block is a special block that CakePHP creates. It will contain all the uncaptured content from the extending view. Assuming our view file has a `$post` variable with the data about our post, the view could look like:

    <!-- src/Template/Posts/view.ctp -->
    <?php
    $this->extend('/Common/view');
    
    $this->assign('title', $post->title);
    
    $this->start('sidebar');
    ?>
    <li>
    <?php
    echo $this->Html->link('edit', [\
        'action' => 'edit',\
        $post->id\
    ]);
    ?>
    </li>
    <?php $this->end(); ?>
    
    // The remaining content will be available as the 'content' block
    // In the parent view.
    <?= h($post->body) ?>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  

The post view above shows how you can extend a view, and populate a set of blocks. Any content not already in a defined block will be captured and put into a special block named `content`. When a view contains a call to `extend()`, execution continues to the bottom of the current view file. Once it is complete, the extended view will be rendered. Calling `extend()` more than once in a view file will override the parent view that will be processed next:

    $this->extend('/Common/view');
    $this->extend('/Common/index');

1  
2  

The above will result in **/Common/index.ctp** being rendered as the parent view to the current view.

You can nest extended views as many times as necessary. Each view can extend another view if desired. Each parent view will get the previous view's content as the `content` block.

NOTE

You should avoid using `content` as a block name in your application. CakePHP uses this for uncaptured content in extended views.

You can get the list of all populated blocks using the `blocks()` method:

    $list = $this->blocks();

1  

Using View Blocks [​](https://book.cakephp.org/3.x/views.html#using-view-blocks)

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

View blocks provide a flexible API that allows you to define slots or blocks in your views/layouts that will be defined elsewhere. For example, blocks are ideal for implementing things such as sidebars, or regions to load assets at the bottom/top of the layout. Blocks can be defined in two ways: either as a capturing block, or by direct assignment. The `start()`, `append()`, `prepend()`, `assign()`, `fetch()`, and `end()` methods allow you to work with capturing blocks:

    // Create the sidebar block.
    $this->start('sidebar');
    echo $this->element('sidebar/recent_topics');
    echo $this->element('sidebar/recent_comments');
    $this->end();
    
    // Append into the sidebar later on.
    $this->start('sidebar');
    echo $this->fetch('sidebar');
    echo $this->element('sidebar/popular_topics');
    $this->end();

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

You can also append into a block using `append()`:

    $this->append('sidebar');
    echo $this->element('sidebar/popular_topics');
    $this->end();
    
    // The same as the above.
    $this->append('sidebar', $this->element('sidebar/popular_topics'));

1  
2  
3  
4  
5  
6  

If you need to clear or overwrite a block there are a couple of alternatives. The `reset()` method will clear or overwrite a block at any time. The `assign()` method with an empty content string can also be used to clear the specified block.:

    // Clear the previous content from the sidebar block.
    $this->reset('sidebar');
    
    // Assigning an empty string will also clear the sidebar block.
    $this->assign('sidebar', '');

1  
2  
3  
4  
5  

Added in version 3.2

View::reset() was added in 3.2

Assigning a block's content is often useful when you want to convert a view variable into a block. For example, you may want to use a block for the page title, and sometimes assign the title as a view variable in the controller:

    // In view file or layout above $this->fetch('title')
    $this->assign('title', $title);

1  
2  

The `prepend()` method allows you to prepend content to an existing block:

    // Prepend to sidebar
    $this->prepend('sidebar', 'this content goes on top of sidebar');

1  
2  

### Displaying Blocks [​](https://book.cakephp.org/3.x/views.html#displaying-blocks)

You can display blocks using the `fetch()` method. `fetch()` will output a block, returning '' if a block does not exist:

    <?= $this->fetch('sidebar') ?>

1  

You can also use fetch to conditionally show content that should surround a block should it exist. This is helpful in layouts, or extended views where you want to conditionally show headings or other markup:

    // In src/Template/Layout/default.ctp
    <?php if ($this->fetch('menu')): ?>
    <div class="menu">
        <h3>Menu options</h3>
        <?= $this->fetch('menu') ?>
    </div>
    <?php endif; ?>

1  
2  
3  
4  
5  
6  
7  

You can also provide a default value for a block if it does not exist. This allows you to add placeholder content when a block does not exist. You can provide a default value using the second argument:

    <div class="shopping-cart">
        <h3>Your Cart</h3>
        <?= $this->fetch('cart', 'Your cart is empty') ?>
    </div>

1  
2  
3  
4  

### Using Blocks for Script and CSS Files [​](https://book.cakephp.org/3.x/views.html#using-blocks-for-script-and-css-files)

The `HtmlHelper` ties into view blocks, and its `script()`, `css()`, and `meta()` methods each update a block with the same name when used with the `block = true` option:

    <?php
    // In your view file
    $this->Html->script('carousel', ['block' => true]);
    $this->Html->css('carousel', ['block' => true]);
    ?>
    
    // In your layout file.
    <!DOCTYPE html>
    <html lang="en">
        <head>
        <title><?= h($this->fetch('title')) ?></title>
        <?= $this->fetch('script') ?>
        <?= $this->fetch('css') ?>
        </head>
        // Rest of the layout follows

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

The `Cake\View\Helper\HtmlHelper` also allows you to control which block the scripts and CSS go to:

    // In your view
    $this->Html->script('carousel', ['block' => 'scriptBottom']);
    
    // In your layout
    <?= $this->fetch('scriptBottom') ?>

1  
2  
3  
4  
5  

Layouts [​](https://book.cakephp.org/3.x/views.html#layouts)

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

A layout contains presentation code that wraps around a view. Anything you want to see in all of your views should be placed in a layout.

CakePHP's default layout is located at **src/Template/Layout/default.ctp**. If you want to change the overall look of your application, then this is the right place to start, because controller-rendered view code is placed inside of the default layout when the page is rendered.

Other layout files should be placed in **src/Template/Layout**. When you create a layout, you need to tell CakePHP where to place the output of your views. To do so, make sure your layout includes a place for `$this->fetch('content')` Here's an example of what a default layout might look like:

    <!DOCTYPE html>
    <html lang="en">
    <head>
    <title><?= h($this->fetch('title')) ?></title>
    <link rel="shortcut icon" href="favicon.ico" type="image/x-icon">
    <!-- Include external files and scripts here (See HTML helper for more info.) -->
    <?php
    echo $this->fetch('meta');
    echo $this->fetch('css');
    echo $this->fetch('script');
    ?>
    </head>
    <body>
    
    <!-- If you'd like some sort of menu to
    show up on all of your views, include it here -->
    <div id="header">
        <div id="menu">...</div>
    </div>
    
    <!-- Here's where I want my views to be displayed -->
    <?= $this->fetch('content') ?>
    
    <!-- Add a footer to each displayed page -->
    <div id="footer">...</div>
    
    </body>
    </html>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  

The `script`, `css` and `meta` blocks contain any content defined in the views using the built-in HTML helper. Useful for including JavaScript and CSS files from views.

NOTE

When using `HtmlHelper::css()` or `HtmlHelper::script()` in template files, specify `'block' => true` to place the HTML source in a block with the same name. (See API for more details on usage).

The `content` block contains the contents of the rendered view.

You can set the `title` block content from inside your view file:

    $this->assign('title', 'View Active Users');

1  

Empty values for the `title` block will be automatically replaced with a representation of the current template path, such as `'Admin/Articles'`.

You can create as many layouts as you wish: just place them in the **src/Template/Layout** directory, and switch between them inside of your controller actions using the controller or view's `$layout` property:

    // From a controller
    public function view()
    {
        // Set the layout.
        $this->viewBuilder()->setLayout('admin');
    
        // Before 3.4
        $this->viewBuilder()->layout('admin');
    
        // Before 3.1
        $this->layout = 'admin';
    }
    
    // From a view file
    $this->layout = 'loggedin';

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

For example, if a section of my site included a smaller ad banner space, I might create a new layout with the smaller advertising space and specify it as the layout for all controllers' actions using something like:

    namespace App\Controller;
    
    class UsersController extends AppController
    {
        public function viewActive()
        {
            $this->set('title', 'View Active Users');
            $this->viewBuilder()->setLayout('default_small_ad');
    
            // or the following before 3.4
            $this->viewBuilder()->layout('default_small_ad');
    
            // or the following before 3.1
            $this->layout = 'default_small_ad';
        }
    
        public function viewImage()
        {
            $this->viewBuilder()->setLayout('image');
    
            // Output user image
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  

Besides a default layout CakePHP's official skeleton app also has an 'ajax' layout. The Ajax layout is handy for crafting AJAX responses - it's an empty layout. (Most AJAX calls only require a bit of markup in return, rather than a fully-rendered interface.)

The skeleton app also has a default layout to help generate RSS.

### Using Layouts from Plugins [​](https://book.cakephp.org/3.x/views.html#using-layouts-from-plugins)

If you want to use a layout that exists in a plugin, you can use `plugin syntax`. For example, to use the contact layout from the Contacts plugin:

    namespace App\Controller;
    
    class UsersController extends AppController
    {
        public function viewActive()
        {
            $this->viewBuilder()->setLayout('Contacts.contact');
            // or the following before 3.4
            $this->viewBuilder()->layout('Contacts.contact');
            // or the following before 3.1
            $this->layout = 'Contacts.contact';
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

Elements [​](https://book.cakephp.org/3.x/views.html#elements)

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

`method` Cake\\View\\View::**element**(string $elementPath, array $data, array $options = \[\])

Many applications have small blocks of presentation code that need to be repeated from page to page, sometimes in different places in the layout. CakePHP can help you repeat parts of your website that need to be reused. These reusable parts are called Elements. Ads, help boxes, navigational controls, extra menus, login forms, and callouts are often implemented in CakePHP as elements. An element is basically a mini-view that can be included in other views, in layouts, and even within other elements. Elements can be used to make a view more readable, placing the rendering of repeating elements in its own file. They can also help you re-use content fragments in your application.

Elements live in the **src/Template/Element/** folder, and have the .ctp filename extension. They are output using the element method of the view:

    echo $this->element('helpbox');

1  

### Passing Variables into an Element [​](https://book.cakephp.org/3.x/views.html#passing-variables-into-an-element)

You can pass data to an element through the element's second argument:

    echo $this->element('helpbox', [\
        "helptext" => "Oh, this text is very helpful."\
    ]);

1  
2  
3  

Inside the element file, all the passed variables are available as members of the parameter array. In the above example, the **src/Template/Element/helpbox.ctp** file can use the `$helptext` variable:

    // Inside src/Template/Element/helpbox.ctp
    echo $helptext; // Outputs "Oh, this text is very helpful."

1  
2  

Keep in mind that in those view vars are merged with the view vars from the view itself. So all view vars set using `Controller::set()` in the controller and `View::set()` in the view itself are also available inside the element.

The `View::element()` method also supports options for the element. The options supported are 'cache' and 'callbacks'. An example:

    echo $this->element('helpbox', [\
            "helptext" => "This is passed to the element as $helptext",\
            "foobar" => "This is passed to the element as $foobar",\
        ],
        [\
            // uses the "long_view" cache configuration\
            "cache" => "long_view",\
            // set to true to have before/afterRender called for the element\
            "callbacks" => true\
        ]
    );

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

Element caching is facilitated through the `Cache` class. You can configure elements to be stored in any Cache configuration you've set up. This gives you a great amount of flexibility to decide where and for how long elements are stored. To cache different versions of the same element in an application, provide a unique cache key value using the following format:

    $this->element('helpbox', [], [\
            "cache" => ['config' => 'short', 'key' => 'unique value']\
        ]
    );

1  
2  
3  
4  

If you need more logic in your element, such as dynamic data from a datasource, consider using a View Cell instead of an element. Find out more [about View Cells](https://book.cakephp.org/3.x/views/cells.html)
.

### Caching Elements [​](https://book.cakephp.org/3.x/views.html#caching-elements)

You can take advantage of CakePHP view caching if you supply a cache parameter. If set to `true`, it will cache the element in the 'default' Cache configuration. Otherwise, you can set which cache configuration should be used. See [Caching](https://book.cakephp.org/3.x/core-libraries/caching.html)
 for more information on configuring `Cache`. A simple example of caching an element would be:

    echo $this->element('helpbox', [], ['cache' => true]);

1  

If you render the same element more than once in a view and have caching enabled, be sure to set the 'key' parameter to a different name each time. This will prevent each successive call from overwriting the previous `element()` call's cached result. For example:

    echo $this->element(
        'helpbox',
        ['var' => $var],
        ['cache' => ['key' => 'first_use', 'config' => 'view_long']]
    );
    
    echo $this->element(
        'helpbox',
        ['var' => $differenVar],
        ['cache' => ['key' => 'second_use', 'config' => 'view_long']]
    );

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

The above will ensure that both element results are cached separately. If you want all element caching to use the same cache configuration, you can avoid some repetition by setting `View::$elementCache` to the cache configuration you want to use. CakePHP will use this configuration when none is given.

### Requesting Elements from a Plugin [​](https://book.cakephp.org/3.x/views.html#requesting-elements-from-a-plugin)

If you are using a plugin and wish to use elements from within the plugin, just use the familiar `plugin syntax`. If the view is being rendered for a plugin controller/action, the plugin name will automatically be prefixed onto all elements used, unless another plugin name is present. If the element doesn't exist in the plugin, it will look in the main APP folder:

    echo $this->element('Contacts.helpbox');

1  

If your view is a part of a plugin, you can omit the plugin name. For example, if you are in the `ContactsController` of the Contacts plugin, the following:

    echo $this->element('helpbox');
    // and
    echo $this->element('Contacts.helpbox');

1  
2  
3  

are equivalent and will result in the same element being rendered.

For elements inside subfolder of a plugin (e.g., **plugins/Contacts/Template/Element/sidebar/helpbox.ctp**), use the following:

    echo $this->element('Contacts.sidebar/helpbox');

1  

### Routing prefix and Elements [​](https://book.cakephp.org/3.x/views.html#routing-prefix-and-elements)

Added in version 3.0.1

If you have a Routing prefix configured, the Element path resolution can switch to a prefix location, as Layouts and action View do. Assuming you have a prefix "Admin" configured and you call:

    echo $this->element('my_element');

1  

The element first be looked for in **src/Template/Admin/Element/**. If such a file does not exist, it will be looked for in the default location.

### Caching Sections of Your View [​](https://book.cakephp.org/3.x/views.html#caching-sections-of-your-view)

`method` Cake\\View\\View::**cache**(callable $block, array $options = \[\])

Sometimes generating a section of your view output can be expensive because of rendered [View Cells](https://book.cakephp.org/3.x/views/cells.html)
 or expensive helper operations. To help make your application run faster CakePHP provides a way to cache view sections:

    // Assuming some local variables
    echo $this->cache(function () use ($user, $article) {
        echo $this->cell('UserProfile', [$user]);
        echo $this->cell('ArticleFull', [$article]);
    }, ['key' => 'my_view_key']);

1  
2  
3  
4  
5  

By default cached view content will go into the `View::$elementCache` cache config, but you can use the `config` option to change this.

View Events [​](https://book.cakephp.org/3.x/views.html#view-events)

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

Like Controller, view trigger several events/callbacks that you can use to insert logic around the rendering life-cycle:

### Event List [​](https://book.cakephp.org/3.x/views.html#event-list)

*   `View.beforeRender`
*   `View.beforeRenderFile`
*   `View.afterRenderFile`
*   `View.afterRender`
*   `View.beforeLayout`
*   `View.afterLayout`

You can attach application [event listeners](https://book.cakephp.org/3.x/core-libraries/events.html)
 to these events or use [Helper Callbacks](https://book.cakephp.org/3.x/views/helpers.html#helper-api)
.

Creating Your Own View Classes [​](https://book.cakephp.org/3.x/views.html#creating-your-own-view-classes)

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

You may need to create custom view classes to enable new types of data views, or add additional custom view-rendering logic to your application. Like most components of CakePHP, view classes have a few conventions:

*   View class files should be put in **src/View**. For example: **src/View/PdfView.php**
*   View classes should be suffixed with `View`. For example: `PdfView`.
*   When referencing view class names you should omit the `View` suffix. For example: `$this->viewBuilder()->setClassName('Pdf');`.

You'll also want to extend `View` to ensure things work correctly:

    // In src/View/PdfView.php
    namespace App\View;
    
    use Cake\View\View;
    
    class PdfView extends View
    {
        public function render($view = null, $layout = null)
        {
            // Custom logic here.
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

Replacing the render method lets you take full control over how your content is rendered.

More About Views [​](https://book.cakephp.org/3.x/views.html#more-about-views)

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

*   [View Cells](https://book.cakephp.org/3.x/views/cells.html)
    
*   [Themes](https://book.cakephp.org/3.x/views/themes.html)
    
*   [JSON and XML views](https://book.cakephp.org/3.x/views/json-and-xml-views.html)
    
*   [Helpers](https://book.cakephp.org/3.x/views/helpers.html)

---

# Blog Tutorial - Part 2 | CakePHP

[Skip to content](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-two.html#VPContent)

Return to top

Blog Tutorial - Part 2 [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-two.html#blog-tutorial-part-2)

========================================================================================================================

Create an Article Model [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-two.html#create-an-article-model)

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

Models are the bread and butter of CakePHP applications. By creating a CakePHP model that will interact with our database, we'll have the foundation in place needed to do our view, add, edit, and delete operations later.

CakePHP's model class files are split between `Table` and `Entity` objects. `Table` objects provide access to the collection of entities stored in a specific table and go in **src/Model/Table**. The file we'll be creating will be saved to **src/Model/Table/ArticlesTable.php**. The completed file should look like this:

    // src/Model/Table/ArticlesTable.php
    
    namespace App\Model\Table;
    
    use Cake\ORM\Table;
    
    class ArticlesTable extends Table
    {
        public function initialize(array $config)
        {
            $this->addBehavior('Timestamp');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

Naming conventions are very important in CakePHP. By naming our Table object `ArticlesTable`, CakePHP can automatically infer that this Table object will be used in the `ArticlesController`, and will be tied to a database table called `articles`.

NOTE

CakePHP will dynamically create a model object for you if it cannot find a corresponding file in **src/Model/Table**. This also means that if you accidentally name your file wrong (i.e. articlestable.php or ArticleTable.php), CakePHP will not recognize any of your settings and will use the generated model instead.

For more on models, such as callbacks, and validation, check out the [Database Access & ORM](https://book.cakephp.org/3.x/orm.html)
 chapter of the Manual.

NOTE

If you completed [Part 1 of the Blog Tutorial](https://book.cakephp.org/3.x/tutorials-and-examples/blog/blog.html)
 and created the `articles` table in our Blog database you can leverage CakePHP's bake console and its code generation capabilities to create the `ArticlesTable` model:

    bin/cake bake model Articles

1  

For more on bake and its code generation features please visit [Code Generation with Bake](https://book.cakephp.org/3.x/bake/usage.html)
.

Create the Articles Controller [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-two.html#create-the-articles-controller)

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

Next, we'll create a controller for our articles. The controller is where all interaction with articles will happen. In a nutshell, it's the place where you play with the business logic contained in the models and get work related to articles done. We'll place this new controller in a file called **ArticlesController.php** inside the **src/Controller** directory. Here's what the basic controller should look like:

    // src/Controller/ArticlesController.php
    
    namespace App\Controller;
    
    class ArticlesController extends AppController
    {
    }

1  
2  
3  
4  
5  
6  
7  

Now, let's add an action to our controller. Actions often represent a single function or interface in an application. For example, when users request www.example.com/articles/index (which is also the same as www.example.com/articles/), they might expect to see a listing of articles. The code for that action would look like this:

    // src/Controller/ArticlesController.php
    
    namespace App\Controller;
    
    class ArticlesController extends AppController
    {
        public function index()
        {
            $articles = $this->Articles->find('all');
            $this->set(compact('articles'));
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

By defining function `index()` in our `ArticlesController`, users can now access the logic there by requesting www.example.com/articles/index. Similarly, if we were to define a function called `foobar()`, users would be able to access that at www.example.com/articles/foobar.

WARNING

You may be tempted to name your controllers and actions a certain way to obtain a certain URL. Resist that temptation. Follow [CakePHP Conventions](https://book.cakephp.org/3.x/intro/conventions.html)
 (capitalization, plural names, etc.) and create readable, understandable action names. You can map URLs to your code using [Routing](https://book.cakephp.org/3.x/development/routing.html)
 covered later on.

The single instruction in the action uses `set()` to pass data from the controller to the view (which we'll create next). The line sets the view variable called 'articles' equal to the return value of the `find('all')` method of the `ArticlesTable` object.

NOTE

If you completed [Part 1 of the Blog Tutorial](https://book.cakephp.org/3.x/tutorials-and-examples/blog/blog.html)
 and created the `articles` table in your Blog database you can leverage CakePHP's bake console and its code generation capabilities to create the ArticlesController class:

    bin/cake bake controller Articles

1  

For more on bake and its code generation features please visit [Code Generation with Bake](https://book.cakephp.org/3.x/bake/usage.html)
.

To learn more about CakePHP's controllers, check out the [Controllers](https://book.cakephp.org/3.x/controllers.html)
 chapter.

Creating Article Views [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-two.html#creating-article-views)

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

Now that we have our data flowing from our model, and our application logic is defined by our controller, let's create a view for the index action we created above.

CakePHP views are just presentation-flavored fragments that fit inside an application's layout. For most applications, they're HTML mixed with PHP, but they may end up as XML, CSV, or even binary data.

A layout is presentation code that is wrapped around a view. Multiple layouts can be defined, and you can switch between them, but for now, let's just use the default.

Remember in the last section how we assigned the 'articles' variable to the view using the `set()` method? That would hand down the query object collection to the view to be invoked with a `foreach` iteration.

CakePHP's template files are stored in **src/Template** inside a folder named after the controller they correspond to (we'll have to create a folder named 'Articles' in this case). To format this article data in a nice table, our view code might look something like this:

    <!-- File: src/Template/Articles/index.ctp -->
    
    <h1>Blog articles</h1>
    <table>
        <tr>
            <th>Id</th>
            <th>Title</th>
            <th>Created</th>
        </tr>
    
        <!-- Here is where we iterate through our $articles query object, printing out article info -->
    
        <?php foreach ($articles as $article): ?>
        <tr>
            <td><?= $article->id ?></td>
            <td>
                <?= $this->Html->link($article->title, ['action' => 'view', $article->id]) ?>
            </td>
            <td>
                <?= $article->created->format(DATE_RFC850) ?>
            </td>
        </tr>
        <?php endforeach; ?>
    </table>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  

Hopefully this should look somewhat simple.

You might have noticed the use of an object called `$this->Html`. This is an instance of the CakePHP `Cake\View\Helper\HtmlHelper` class. CakePHP comes with a set of view helpers that make things like linking, form output a snap. You can learn more about how to use them in [Helpers](https://book.cakephp.org/3.x/views/helpers.html)
, but what's important to note here is that the `link()` method will generate an HTML link with the given title (the first parameter) and URL (the second parameter).

When specifying URLs in CakePHP, it is recommended that you use the array format. This is explained in more detail in the section on Routes. Using the array format for URLs allows you to take advantage of CakePHP's reverse routing capabilities. You can also specify URLs relative to the base of the application in the form of `/controller/action/param1/param2` or use [named routes](https://book.cakephp.org/3.x/development/routing.html#named-routes)
.

At this point, you should be able to point your browser to [http://www.example.com/articles/index](http://www.example.com/articles/index)
. You should see your view, correctly formatted with the title and table listing of the articles.

If you happened to have clicked on one of the links we created in this view (that link a article's title to a URL `/articles/view/some\_id`), you were probably informed by CakePHP that the action hasn't yet been defined. If you were not so informed, either something has gone wrong, or you actually did define it already, in which case you are very sneaky. Otherwise, we'll create it in the `ArticlesController` now:

    // src/Controller/ArticlesController.php
    
    namespace App\Controller;
    
    class ArticlesController extends AppController
    {
        public function index()
        {
             $this->set('articles', $this->Articles->find('all'));
        }
    
        public function view($id = null)
        {
            $article = $this->Articles->get($id);
            $this->set(compact('article'));
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

The `set()` call should look familiar. Notice we're using `get()` rather than `find('all')` because we only really want a single article's information.

Notice that our view action takes a parameter: the ID of the article we'd like to see. This parameter is handed to the action through the requested URL. If a user requests `/articles/view/3`, then the value '3' is passed as `$id`.

We also do a bit of error checking to ensure a user is actually accessing a record. By using the `get()` function in the Articles table, we make sure the user has accessed a record that exists. In case the requested article is not present in the database, or the id is false the `get()` function will throw a `NotFoundException`.

Now let's create the view for our new 'view' action and place it in **src/Template/Articles/view.ctp**

    <!-- File: src/Template/Articles/view.ctp -->
    
    <h1><?= h($article->title) ?></h1>
    <p><?= h($article->body) ?></p>
    <p><small>Created: <?= $article->created->format(DATE_RFC850) ?></small></p>

1  
2  
3  
4  
5  

Verify that this is working by trying the links at `/articles/index` or manually requesting an article by accessing `/articles/view/{id}`, replacing `{id}` by an article 'id'.

Adding Articles [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-two.html#adding-articles)

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

Reading from the database and showing us the articles is a great start, but let's allow for the adding of new articles.

First, start by creating an `add()` action in the `ArticlesController`:

    // src/Controller/ArticlesController.php
    
    namespace App\Controller;
    
    use App\Controller\AppController;
    
    class ArticlesController extends AppController
    {
        public function initialize()
        {
            parent::initialize();
    
            $this->loadComponent('Flash'); // Include the FlashComponent
        }
    
        public function index()
        {
            $this->set('articles', $this->Articles->find('all'));
        }
    
        public function view($id)
        {
            $article = $this->Articles->get($id);
            $this->set(compact('article'));
        }
    
        public function add()
        {
            $article = $this->Articles->newEntity();
            if ($this->request->is('post')) {
                // Prior to 3.4.0 $this->request->data() was used.
                $article = $this->Articles->patchEntity($article, $this->request->getData());
                if ($this->Articles->save($article)) {
                    $this->Flash->success(__('Your article has been saved.'));
                    return $this->redirect(['action' => 'index']);
                }
                $this->Flash->error(__('Unable to add your article.'));
            }
            $this->set('article', $article);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40  
41  

NOTE

You need to include the [Flash](https://book.cakephp.org/3.x/controllers/components/flash.html)
 component in any controller where you will use it. If necessary, include it in your `AppController`.

Here's what the `add()` action does: if the HTTP method of the request was POST, try to save the data using the Articles model. If for some reason it doesn't save, just render the view. This gives us a chance to show the user validation errors or other warnings.

Every CakePHP request includes a `ServerRequest` object which is accessible using `$this->request`. The request object contains useful information regarding the request that was just received, and can be used to control the flow of your application. In this case, we use the `Cake\Http\ServerRequest::is()` method to check that the request is a HTTP POST request.

When a user uses a form to POST data to your application, that information is available in `$this->request->getData()` ( Or `$this->request->data()` for CakePHP v3.3 and under ). You can use the `pr()` or `debug()` functions to print it out if you want to see what it looks like.

We use FlashComponent's `success()` and `error()` methods to set a message to a session variable. These methods are provided using PHP's [magic method features](https://php.net/manual/en/language.oop5.overloading.php#object.call)
. Flash messages will be displayed on the page after redirection. In the layout we have `<?= $this->Flash->render() ?>` which displays the message and clears the corresponding session variable. The controller's `Cake\Controller\Controller::redirect` function redirects to another URL. The param `['action' => 'index']` translates to URL /articles i.e the index action of the `ArticlesController`. You can refer to `Cake\Routing\Router::url()` function on the [API](https://api.cakephp.org/)
 to see the formats in which you can specify a URL for various CakePHP functions.

Calling the `save()` method will check for validation errors and abort the save if any occur. We'll discuss how those errors are handled in the following sections.

Data Validation [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-two.html#data-validation)

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

CakePHP goes a long way toward taking the monotony out of form input validation. Everyone hates coding up endless forms and their validation routines. CakePHP makes it easier and faster.

To take advantage of the validation features, you'll need to use CakePHP's [Form](https://book.cakephp.org/3.x/views/helpers/form.html)
 helper in your views. The `Cake\View\Helper\FormHelper` is available by default to all views at `$this->Form`.

Here's our add view:

    <!-- File: src/Template/Articles/add.ctp -->
    
    <h1>Add Article</h1>
    <?php
        echo $this->Form->create($article);
        echo $this->Form->control('title');
        echo $this->Form->control('body', ['rows' => '3']);
        echo $this->Form->button(__('Save Article'));
        echo $this->Form->end();
    ?>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

We use the FormHelper to generate the opening tag for an HTML form. Here's the HTML that `$this->Form->create()` generates:

    <form method="post" action="/articles/add">

1  

If `create()` is called with no parameters supplied, it assumes you are building a form that submits via POST to the current controller's `add()` action (or `edit()` action when `id` is included in the form data).

The `$this->Form->control()` method is used to create form elements of the same name. The first parameter tells CakePHP which field they correspond to, and the second parameter allows you to specify a wide array of options - in this case, the number of rows for the textarea. There's a bit of introspection and automagic here: `control()` will output different form elements based on the model field specified.

The `$this->Form->end()` call ends the form. Outputting hidden inputs if CSRF/Form Tampering prevention is enabled.

Now let's go back and update our **src/Template/Articles/index.ctp** view to include a new "Add Article" link. Before the `<table>`, add the following line:

    <?= $this->Html->link('Add Article', ['action' => 'add']) ?>

1  

You may be wondering: how do I tell CakePHP about my validation requirements? Validation rules are defined in the model. Let's look back at our Articles model and make a few adjustments:

    // src/Model/Table/ArticlesTable.php
    
    namespace App\Model\Table;
    
    use Cake\ORM\Table;
    use Cake\Validation\Validator;
    
    class ArticlesTable extends Table
    {
        public function initialize(array $config)
        {
            $this->addBehavior('Timestamp');
        }
    
        public function validationDefault(Validator $validator)
        {
            $validator
                ->notEmpty('title')
                ->requirePresence('title')
                ->notEmpty('body')
                ->requirePresence('body');
    
            return $validator;
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  

The `validationDefault()` method tells CakePHP how to validate your data when the `save()` method is called. Here, we've specified that both the body and title fields must not be empty, and are required for both create and update operations. CakePHP's validation engine is strong, with a number of pre-built rules (credit card numbers, email addresses, etc.) and flexibility for adding your own validation rules. For more information on that setup, check the [Validation](https://book.cakephp.org/3.x/core-libraries/validation.html)
 documentation.

Now that your validation rules are in place, use the app to try to add an article with an empty title or body to see how it works. Since we've used the `Cake\View\Helper\FormHelper::control()` method of the FormHelper to create our form elements, our validation error messages will be shown automatically.

Editing Articles [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-two.html#editing-articles)

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

Post editing: here we go. You're a CakePHP pro by now, so you should have picked up a pattern. Make the action, then the view. Here's what the `edit()` action of the `ArticlesController` would look like:

    // src/Controller/ArticlesController.php
    
    public function edit($id = null)
    {
        $article = $this->Articles->get($id);
        if ($this->request->is(['post', 'put'])) {
            // Prior to 3.4.0 $this->request->data() was used.
            $this->Articles->patchEntity($article, $this->request->getData());
            if ($this->Articles->save($article)) {
                $this->Flash->success(__('Your article has been updated.'));
                return $this->redirect(['action' => 'index']);
            }
            $this->Flash->error(__('Unable to update your article.'));
        }
    
        $this->set('article', $article);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

This action first ensures that the user has tried to access an existing record. If they haven't passed in an `$id` parameter, or the article does not exist, we throw a `NotFoundException` for the CakePHP ErrorHandler to take care of.

Next the action checks whether the request is either a POST or a PUT request. If it is, then we use the POST data to update our article entity by using the `patchEntity()` method. Finally we use the table object to save the entity back or kick back and show the user validation errors.

The edit view might look something like this:

    <!-- File: src/Template/Articles/edit.ctp -->
    
    <h1>Edit Article</h1>
    <?php
        echo $this->Form->create($article);
        echo $this->Form->control('title');
        echo $this->Form->control('body', ['rows' => '3']);
        echo $this->Form->button(__('Save Article'));
        echo $this->Form->end();
    ?>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

This view outputs the edit form (with the values populated), along with any necessary validation error messages.

CakePHP will determine whether a `save()` generates an insert or an update statement based on the state of the entity.

You can now update your index view with links to edit specific articles:

    <!-- File: src/Template/Articles/index.ctp  (edit links added) -->
    
    <h1>Blog articles</h1>
    <p><?= $this->Html->link("Add Article", ['action' => 'add']) ?></p>
    <table>
        <tr>
            <th>Id</th>
            <th>Title</th>
            <th>Created</th>
            <th>Action</th>
        </tr>
    
    <!-- Here's where we iterate through our $articles query object, printing out article info -->
    
    <?php foreach ($articles as $article): ?>
        <tr>
            <td><?= $article->id ?></td>
            <td>
                <?= $this->Html->link($article->title, ['action' => 'view', $article->id]) ?>
            </td>
            <td>
                <?= $article->created->format(DATE_RFC850) ?>
            </td>
            <td>
                <?= $this->Html->link('Edit', ['action' => 'edit', $article->id]) ?>
            </td>
        </tr>
    <?php endforeach; ?>
    
    </table>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  

Deleting Articles [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-two.html#deleting-articles)

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

Next, let's make a way for users to delete articles. Start with a `delete()` action in the `ArticlesController`:

    // src/Controller/ArticlesController.php
    
    public function delete($id)
    {
        $this->request->allowMethod(['post', 'delete']);
    
        $article = $this->Articles->get($id);
        if ($this->Articles->delete($article)) {
            $this->Flash->success(__('The article with id: {0} has been deleted.', h($id)));
            return $this->redirect(['action' => 'index']);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

This logic deletes the article specified by `$id`, and uses `$this->Flash->success()` to show the user a confirmation message after redirecting them on to `/articles`. If the user attempts to do a delete using a GET request, the `allowMethod()` will throw an Exception. Uncaught exceptions are captured by CakePHP's exception handler, and a nice error page is displayed. There are many built-in [Exceptions](https://book.cakephp.org/3.x/development/errors.html)
 that can be used to indicate the various HTTP errors your application might need to generate.

Because we're just executing some logic and redirecting, this action has no view. You might want to update your index view with links that allow users to delete articles, however:

    <!-- File: src/Template/Articles/index.ctp (delete links added) -->
    
    <h1>Blog articles</h1>
    <p><?= $this->Html->link('Add Article', ['action' => 'add']) ?></p>
    <table>
        <tr>
            <th>Id</th>
            <th>Title</th>
            <th>Created</th>
            <th>Actions</th>
        </tr>
    
    <!-- Here's where we loop through our $articles query object, printing out article info -->
    
        <?php foreach ($articles as $article): ?>
        <tr>
            <td><?= $article->id ?></td>
            <td>
                <?= $this->Html->link($article->title, ['action' => 'view', $article->id]) ?>
            </td>
            <td>
                <?= $article->created->format(DATE_RFC850) ?>
            </td>
            <td>
                <?= $this->Form->postLink(
                    'Delete',
                    ['action' => 'delete', $article->id],
                    ['confirm' => 'Are you sure?'])
                ?>
                <?= $this->Html->link('Edit', ['action' => 'edit', $article->id]) ?>
            </td>
        </tr>
        <?php endforeach; ?>
    
    </table>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  

Using `Cake\View\Helper\FormHelper::postLink()` will create a link that uses JavaScript to do a POST request deleting our article.

WARNING

Allowing content to be deleted using GET requests is dangerous, as web crawlers could accidentally delete all your content.

NOTE

This view code also uses the `FormHelper` to prompt the user with a JavaScript confirmation dialog before they attempt to delete an article.

Routes [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-two.html#routes)

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

For some, CakePHP's default routing works well enough. Developers who are sensitive to user-friendliness and general search engine compatibility will appreciate the way that CakePHP's URLs map to specific actions. So we'll just make a quick change to routes in this tutorial.

For more information on advanced routing techniques, see [Routes Configuration](https://book.cakephp.org/3.x/development/routing.html#routes-configuration)
.

By default, CakePHP responds to a request for the root of your site (e.g., [http://www.example.com](http://www.example.com/)
) using its `PagesController`, rendering a view called "home". Instead, we'll replace this with our ArticlesController by creating a routing rule.

CakePHP's routing is found in **config/routes.php**. You'll want to comment out or remove the line that defines the default root route. It looks like this:

    $routes->connect('/', ['controller' => 'Pages', 'action' => 'display', 'home']);

1  

This line connects the URL '/' with the default CakePHP home page. We want it to connect with our own controller, so replace that line with this one:

    $routes->connect('/', ['controller' => 'Articles', 'action' => 'index']);

1  

This should connect users requesting '/' to the `index()` action of our `ArticlesController`.

NOTE

CakePHP also makes use of 'reverse routing'. If, with the above route defined, you pass `['controller' => 'Articles', 'action' => 'index']` to a function expecting an array, the resulting URL used will be '/'. It's therefore a good idea to always use arrays for URLs as this means your routes define where a URL goes, and also ensures that links point to the same place.

Conclusion [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-two.html#conclusion)

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

Keep in mind that this tutorial was very basic. CakePHP has _many_ more features to offer, and is flexible in ways we didn't wish to cover here for simplicity's sake. Use the rest of this manual as a guide for building more feature-rich applications.

Now that you've created a basic CakePHP application, you can either continue to [Blog Tutorial - Part 3](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-three.html)
, or start your own project. You can also peruse the [Using CakePHP](https://book.cakephp.org/3.x/topics.html)
 or [API](https://api.cakephp.org/)
 to learn more about CakePHP.

If you need help, there are many ways to get the help you need - please see the [Where to Get Help](https://book.cakephp.org/3.x/intro/where-to-get-help.html)
 page. Welcome to CakePHP!

### Suggested Follow-up Reading [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-two.html#suggested-follow-up-reading)

These are common tasks people learning CakePHP usually want to study next:

1.  [View Layouts](https://book.cakephp.org/3.x/views.html#view-layouts)
    : Customizing your website layout
2.  [View Elements](https://book.cakephp.org/3.x/views.html#view-elements)
    : Including and reusing view snippets
3.  [Code Generation with Bake](https://book.cakephp.org/3.x/bake/usage.html)
    : Generating basic CRUD code
4.  [Blog Tutorial - Authentication and Authorization](https://book.cakephp.org/3.x/tutorials-and-examples/blog-auth-example/auth.html)
    : User authentication and authorization tutorial

---

# チュートリアルと例 | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/tutorials-and-examples.html#VPContent)

Return to top

チュートリアルと例 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples.html#%E3%83%81%E3%83%A5%E3%83%BC%E3%83%88%E3%83%AA%E3%82%A2%E3%83%AB%E3%81%A8%E4%BE%8B)

=============================================================================================================================================================

このセクションで、典型的な CakePHP アプリケーションのデモンストレーションを行い、 全てのピースがどう組み合わさっていくかを学ぶことができます。

その他にも、既存のアプリケーションやコンポーネントについて、非公式の CakePHP プラグイン倉庫 [CakePackages](https://plugins.cakephp.org/)
 や、 [Bakery](https://bakery.cakephp.org/)
 を参考にすることもできます。

*   [コンテンツ管理チュートリアル](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/installation.html)
    
*   [CMS チュートリアル - データベース作成](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/database.html)
    
*   [CMS チュートリアル - Articles コントローラーの作成](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/articles-controller.html)
    
*   [CMS チュートリアル - タグとユーザー](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/tags-and-users.html)
    
*   [CMS チュートリアル - 認証](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/authentication.html)

---

# Bake コンソール - 2.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/bake/edit/2.x/docs/ja/index.rst)

[](https://book.cakephp.org/bake/2/ja/index.html#page-contents)

### Page Contents

*   [Bake コンソール](https://book.cakephp.org/bake/2/ja/index.html#)
    *   [インストール手順](https://book.cakephp.org/bake/2/ja/index.html#id1)
        

Bake コンソール[¶](https://book.cakephp.org/bake/2/ja/index.html#bake "この見出しへのパーマリンク")

==================================================================================

CakePHP の bake コンソールは、迅速に CakePHP を動作させるまでを支援します。 bake コンソールは、CakePHP の基本的な素材(モデル、ビヘイビアー、ビュー、ヘルパー、 コントローラー、コンポーネント、テストケース、フィクスチャー、プラグイン)を作成できます。 その為のスケルトンクラスについては、ここでは省略しますが、 bake は数分で完全に機能するアプリケーションを作成できます。 要するに、bake は足場の組まれたアプリケーションをいっぺんに手に入れるためにうってつけの方法です。

インストール手順[¶](https://book.cakephp.org/bake/2/ja/index.html#id1 "この見出しへのパーマリンク")

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

bake を使用したり拡張する前に、アプリケーションに bake をインストールしておいてください。 bake は Composer を使ってインストールするプラグインとして提供されています。

composer require \--dev cakephp/bake:"^2.0"

上記のコマンドは、bake を開発環境で使用するパッケージとしてインストールします。 この入れ方の場合、本番環境としてデプロイする際には、 bake はインストールされません。

Twig テンプレートを使用する場合、 `Cake/TwigView` プラグインをブートストラップとともに 読み込んでいることを確認してください。それを完全に省略して、 Bake プラグインにこのプラグインを読み込ませることもできます。

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# Bake でコード生成 - 2.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/bake/edit/2.x/docs/ja/usage.rst)

[](https://book.cakephp.org/bake/2/ja/usage.html#page-contents)

### Page Contents

*   [Bake でコード生成](https://book.cakephp.org/bake/2/ja/usage.html#)
    *   [Bake テーマオプション](https://book.cakephp.org/bake/2/ja/usage.html#id1)
        

Bake でコード生成[¶](https://book.cakephp.org/bake/2/ja/usage.html#bake "この見出しへのパーマリンク")

===================================================================================

cake コンソールは、 PHP CLI (command line interface) で実行します。 もしスクリプトの実行に問題があるなら、以下を満たしてください。

1.  PHP CLI がインストールされているか適切なモジュールが有効か確認してください (例：MySQL, intl)。
    
2.  データベースのホストが 'localhost' で問題があるなら、代わりに '127.0.0.1' を使って下さい。 PHP CLI でこの問題がおこる可能性があります。
    
3.  使っているコンピューターの設定に応じて、 `bin/cake bake` で使用する cake bash スクリプトの 実行権限を設定する必要があります。
    

bake を実行する前にデータベースとの接続を確認しましょう。

`bin/cake bake` を引数無しで実行すると可能なタスクを表示できます。

Windows システムの場合、 `bin\cake bake` を試してみてください。

それは以下のように表示されます。

$ bin/cake bake

Welcome to CakePHP v3.1.6 Console
\---------------------------------------------------------------
App : src
Path: /var/www/cakephp.dev/src/
PHP: 5.5.8
\---------------------------------------------------------------
The following commands can be used to generate skeleton code for your application.

Available bake commands:

\- all
\- behavior
\- cell
\- component
\- controller
\- fixture
\- form
\- helper
\- mailer
\- migration
\- migration\_snapshot
\- model
\- plugin
\- shell
\- shell\-helper
\- template
\- test

By using \`cake bake \[name\]\` you can invoke a specific bake task.

より詳しい各コマンドの情報を得るには、 `--help` オプションをつけ実行してください。

$ bin/cake bake controller \--help

Welcome to CakePHP v3.1.6 Console
\---------------------------------------------------------------
App : src
Path: /var/www/cakephp.dev/src/
\---------------------------------------------------------------
Bake a controller skeleton.

Usage:
cake bake controller \[subcommand\] \[options\] \[<name\>\]

Subcommands:

all  Bake all controllers with CRUD methods.

To see help on a subcommand use \`cake bake controller \[subcommand\] --help\`

Options:

\--help, \-h        Display this help.
\--verbose, \-v     Enable verbose output.
\--quiet, \-q       Enable quiet output.
\--plugin, \-p      Plugin to bake into.
\--force, \-f       Force overwriting existing files without prompting.
\--connection, \-c  The datasource connection to get data from.
                  (default: default)
\--theme, \-t       The theme to use when baking code.
\--components      The comma separated list of components to use.
\--helpers         The comma separated list of helpers to use.
\--prefix          The namespace/routing prefix to use.
\--no\-test         Do not generate a test skeleton.
\--no\-actions      Do not generate basic CRUD action methods.

Arguments:

name  Name of the controller to bake. Can use Plugin.name to bake
    controllers into plugins. (optional)

Bake テーマオプション[¶](https://book.cakephp.org/bake/2/ja/usage.html#id1 "この見出しへのパーマリンク")

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

テーマオプションは全 bake コマンドで一般的です。また、bake テンプレートファイルを変更することができます。 テーマを作るには、 [Bake テーマ作成ドキュメント](https://book.cakephp.org/bake/2/ja/development.html#creating-a-bake-theme)
 をご覧ください。

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# Chronos - 2.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/chronos/edit/2.x/docs/ja/index.rst)

[](https://book.cakephp.org/chronos/2/ja/#page-contents)

### Page Contents

*   [Chronos](https://book.cakephp.org/chronos/2/ja/#)
    *   [インストール](https://book.cakephp.org/chronos/2/ja/#id1)
        
    *   [概要](https://book.cakephp.org/chronos/2/ja/#id2)
        
    *   [インスタンスの作成](https://book.cakephp.org/chronos/2/ja/#id3)
        
    *   [イミュータブルオブジェクトの動作](https://book.cakephp.org/chronos/2/ja/#id4)
        
    *   [日付オブジェクト](https://book.cakephp.org/chronos/2/ja/#id5)
        
    *   [変更メソッド](https://book.cakephp.org/chronos/2/ja/#id6)
        
    *   [比較メソッド](https://book.cakephp.org/chronos/2/ja/#id7)
        
    *   [差の生成](https://book.cakephp.org/chronos/2/ja/#id8)
        
    *   [フォーマットの設定](https://book.cakephp.org/chronos/2/ja/#id9)
        
    *   [日付要素の抽出](https://book.cakephp.org/chronos/2/ja/#id10)
        
    *   [テストの支援](https://book.cakephp.org/chronos/2/ja/#id11)
        

Chronos[¶](https://book.cakephp.org/chronos/2/ja/#chronos "この見出しへのパーマリンク")

===========================================================================

Chronos (クロノス) は、 `DateTime` オブジェクトへの拡張の依存関係の無いコレクションを提供します。 便利なメソッドに加えて、Chronos は以下を提供します。

*   カレンダー日付のための `ChronosDate` オブジェクト
    
*   イミュータブルな日付と日時オブジェクト
    
*   プラグインのような翻訳システム。ライブラリーは英語のみの翻訳を含んでいます。 しかし、全ての言語サポートのために、 `cakephp/i18n` を使うことができます。
    

インストール[¶](https://book.cakephp.org/chronos/2/ja/#id1 "この見出しへのパーマリンク")

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

Chronos をインストールするためには、 `composer` を利用することができます。 アプリケーションの ROOT ディレクトリー（composer.json ファイルのある場所） で以下のように実行します。

php composer.phar require cakephp/chronos "@stable"

概要[¶](https://book.cakephp.org/chronos/2/ja/#id2 "この見出しへのパーマリンク")

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

Chronos は PHP が提供する DateTime オブジェクトのいくつかの拡張を提供します。 Chronos は `DateInterval` の拡張機能および、ミュータブル（変更可能）と イミュータブル（変更不可）な 日付/時刻 の派生系をカバーする5つのクラスを提供します。

*   `Cake\Chronos\Chronos` はイミュータブルな _日付と時刻_ オブジェクト。
    
*   `Cake\Chronos\ChronosDate` はイミュータブルな _日付_ オブジェクト。
    
*   `Cake\Chronos\MutableDateTime` はミュータブルな _日付と時刻_ オブジェクト。
    
*   `Cake\Chronos\MutableDate` はミュータブルな _日付_ オブジェクト。
    
*   `Cake\Chronos\ChronosInterval` は `DateInterval` の拡張機能。
    

最後に、もしあなたが Chronos が提供する 日付/時刻 のオブジェクトに対して型宣言を行ないたい場合、 `Cake\Chronos\ChronosInterface` を使用することができます。 全ての日付と時間のオブジェクトはこのインターフェイスを実装しています。

インスタンスの作成[¶](https://book.cakephp.org/chronos/2/ja/#id3 "この見出しへのパーマリンク")

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

Chronos または Date のインスタンスを取得するためには、多くの方法があります。 異なる引数セットで動作する多くのファクトリーメソッドがあります。

use Cake\\Chronos\\Chronos;

$now \= Chronos::now();
$today \= Chronos::today();
$yesterday \= Chronos::yesterday();
$tomorrow \= Chronos::tomorrow();

// 相対式のパース
$date \= Chronos::parse('+2 days, +3 hours');

// 日付と時間の整数値
$date \= Chronos::create(2015, 12, 25, 4, 32, 58);

// 日付または時間の整数値
$date \= Chronos::createFromDate(2015, 12, 25);
$date \= Chronos::createFromTime(11, 45, 10);

// 整形した値にパース
$date \= Chronos::createFromFormat('m/d/Y', '06/15/2015');

イミュータブルオブジェクトの動作[¶](https://book.cakephp.org/chronos/2/ja/#id4 "この見出しへのパーマリンク")

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

もしあなたが、PHP の `DateTime` オブジェクトを使用したことがあるなら、 _ミュータブル_ オブジェクトは簡単に使用できます。 Chronos はミュータブルオブジェクトを提供しますが、これは _イミュータブル_ オブジェクトにもなります。 イミュータブルオブジェクトはオブジェクトが変更されるたびにオブジェクトのコピーを作ります。 なぜなら、日時周りの変更メソッドは必ずしも透明でないため、データが誤って、 または開発者が知らない内に変更してしまうからです。 イミュータブルオブジェクトはデータが誤って変更されることを防止し、 順序ベースの依存関係の問題の無いコードを作ります。 不変性は、変更時に忘れずに変数を置き換える必要があることを意味しています。

// このコードはイミュータブルオブジェクトでは動作しません
$time\->addDay(1);
doSomething($time);
return $time

// このコードは期待通りに動作します
$time \= $time\->addDay(1);
$time \= doSomething($time);
return $time

各修正の戻り値をキャプチャーすることによって、コードは期待通りに動作します。 イミュータブルオブジェクトを持っていて、ミュータブルオブジェクトを作りたい場合、 `toMutable()` が使用できます。

$inplace \= $time\->toMutable();

日付オブジェクト[¶](https://book.cakephp.org/chronos/2/ja/#id5 "この見出しへのパーマリンク")

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

PHP は単純な DateTime オブジェクトだけを提供します。このクラスのカレンダー日付の表現で、 タイムゾーンおよび、本当に「日」の概念に属していないタイムコンポーネントを含むと、 少し厄介な可能性があります。 Chronos は日時表現のための `ChronosDate` オブジェクトを提供します。 これらのオブジェクトの時間とタイムゾーンは常に `00:00:00 UTC` に固定されており、 全ての書式/差分のメソッドは一日単位で動作します。

use Cake\\Chronos\\ChronosDate;

$today \= ChronosDate::today();

// 時間/タイムゾーンの変更は無視されます
$today\->modify('+1 hours');

// 出力 '2015-12-20'
echo $today;

変更メソッド[¶](https://book.cakephp.org/chronos/2/ja/#id6 "この見出しへのパーマリンク")

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

Chronos オブジェクトは細やかに値を変更できるメソッドを提供します。

// 日時の値のコンポーネントを設定
$halloween \= Chronos::create()
    \->year(2015)
    \->month(10)
    \->day(31)
    \->hour(20)
    \->minute(30);

また、日時の部分を相対的に変更することもできます。

$future \= Chronos::create()
    \->addYear(1)
    \->subMonth(2)
    \->addDays(15)
    \->addHours(20)
    \->subMinutes(2);

また、ある時間の中で、定義された時点に飛ぶことも可能です。

$time \= Chronos::create();
$time\->startOfDay();
$time\->endOfDay();
$time\->startOfMonth();
$time\->endOfMonth();
$time\->startOfYear();
$time\->endOfYear();
$time\->startOfWeek();
$time\->endOfWeek();

また、1週間中の特定の日にも飛べます。

$time\->next(ChronosInterface::TUESDAY);
$time\->previous(ChronosInterface::MONDAY);

DST の遷移の前後で日付/時間を変更すると、 あなたの操作で時間が増減するかもしれませんが、その結果、意図しない時間の値になります。 これらの問題を回避するには、最初にタイムゾーンを `UTC` に変更し、時間を変更します。

// 余分な時間が追加されました
$time \= new Chronos('2014-03-30 00:00:00', 'Europe/London');
debug($time\->modify('+24 hours')); // 2014-03-31 01:00:00

// 最初に UTC に切り替え、そして更新
$time \= $time\->setTimezone('UTC')
    \->modify('+24 hours');

時間を変更すると、元のタイムゾーンを追加してローカライズされた時間を取得することができます。

比較メソッド[¶](https://book.cakephp.org/chronos/2/ja/#id7 "この見出しへのパーマリンク")

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

Chronos の日付/時間オブジェクトの2つのインスタンスを様々な方法で比較することができます。

// 比較のフルセットが存在します
// ne, gt, lt, lte.
$first\->eq($second);
$first\->gte($second);

// カレントオブジェクトが2つのオブジェクトの間にあるかどうかを確認します。
$now\->between($start, $end);

// どちらの引数が最も近い (closest) か、または最も遠い (farthest) かを見つけます。
$now\->closest($june, $november);
$now\->farthest($june, $november);

また、与えられた値のカレンダーに当たる場所について問い合わせできます。

$now\->isToday();
$now\->isYesterday();
$now\->isFuture();
$now\->isPast();

// 曜日をチェック
$now\->isWeekend();

// 他の曜日のメソッドも全て存在します。
$now\->isMonday();

また、値が相対的な期間内にあったかどうかを見つけることができます。

$time\->wasWithinLast('3 days');
$time\->isWithinNext('3 hours');

差の生成[¶](https://book.cakephp.org/chronos/2/ja/#id8 "この見出しへのパーマリンク")

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

日時比較に加えて、2つの値の差や変化の計算は一般的なタスクです。

// 差をあらわす DateInterval を取得
$first\->diff($second);

// 特定の単位での差を取得
$first\->diffInHours($second);
$first\->diffInDays($second);
$first\->diffInWeeks($second);
$first\->diffInYears($second);

フィードやタイムラインで使用するのに適した、人が読める形式の差を生成することができます。

// 現在からの差
echo $date\->diffForHumans();

// 別の時点からの差
echo $date\->diffForHumans($other); // 1時間前;

フォーマットの設定[¶](https://book.cakephp.org/chronos/2/ja/#id9 "この見出しへのパーマリンク")

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

Chronos は、出力した日時オブジェクトを表示するための多くのメソッドを提供します。

// setToStringFormat() が制御するフォーマットを使用します
echo $date;

// 別の標準フォーマット
echo $time\->toAtomString();      // 1975-12-25T14:15:16-05:00
echo $time\->toCookieString();    // Thursday, 25-Dec-1975 14:15:16 EST
echo $time\->toIso8601String();   // 1975-12-25T14:15:16-05:00
echo $time\->toRfc822String();    // Thu, 25 Dec 75 14:15:16 -0500
echo $time\->toRfc850String();    // Thursday, 25-Dec-75 14:15:16 EST
echo $time\->toRfc1036String();   // Thu, 25 Dec 75 14:15:16 -0500
echo $time\->toRfc1123String();   // Thu, 25 Dec 1975 14:15:16 -0500
echo $time\->toRfc2822String();   // Thu, 25 Dec 1975 14:15:16 -0500
echo $time\->toRfc3339String();   // 1975-12-25T14:15:16-05:00
echo $time\->toRssString();       // Thu, 25 Dec 1975 14:15:16 -0500
echo $time\->toW3cString();       // 1975-12-25T14:15:16-05:00

// クォーター/週数を取得
echo $time\->toQuarter();         // 4;
echo $time\->toWeek();            // 52

// 一般的なフォーマット
echo $time\->toTimeString();           // 14:15:16
echo $time\->toDateString();           // 1975-12-25
echo $time\->toDateTimeString();       // 1975-12-25 14:15:16
echo $time\->toFormattedDateString();  // Dec 25, 1975
echo $time\->toDayDateTimeString();    // Thu, Dec 25, 1975 2:15 PM

日付要素の抽出[¶](https://book.cakephp.org/chronos/2/ja/#id10 "この見出しへのパーマリンク")

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

日付オブジェクトのプロパティーに直接アクセスして要素を取得することができます。

$time \= new Chronos('2015-12-31 23:59:58');
$time\->year;    // 2015
$time\->month;   // 12
$time\->day;     // 31
$time\->hour     // 23
$time\->minute   // 59
$time\->second   // 58

以下のプロパティーにもアクセスできます。 :

*   timezone
    
*   timezoneName
    
*   micro
    
*   dayOfWeek
    
*   dayOfMonth
    
*   dayOfYear
    
*   daysInMonth
    
*   timestamp
    
*   quarter
    

テストの支援[¶](https://book.cakephp.org/chronos/2/ja/#id11 "この見出しへのパーマリンク")

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

単体テストを書いている時、現在時刻を固定すると便利です。Chronos は、 各クラスの現在時刻を修正することができます。 テストスイートの bootstrap 処理に以下を含めることができます。

Chronos::setTestNow(Chronos::now());
MutableDateTime::setTestNow(MutableDateTime::now());
ChronosDate::setTestNow(ChronosDate::now());
MutableDate::setTestNow(MutableDate::now());

これでテストスイートが開始された時点で全てのオブジェクトの現在時刻を修正します。

例えば、 `Chronos` を過去のある瞬間に固定した場合、新たな `Chronos` のインスタンスが生成する `now` または相対時刻の文字列は、 固定された時刻の相対を返却します。

Chronos::setTestNow(new Chronos('1975-12-25 00:00:00'));

$time \= new Chronos(); // 1975-12-25 00:00:00
$time \= new Chronos('1 hour ago'); // 1975-12-24 23:00:00

固定をリセットするには、 `setTestNow()` をパラメーター無し、または `null` を設定して 再び呼び出してください。

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# ElasticSearch - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/elastic-search/edit/3.x/docs/ja/index.rst)

[](https://book.cakephp.org/elasticsearch/3/ja/#page-contents)

### Page Contents

*   [ElasticSearch](https://book.cakephp.org/elasticsearch/3/ja/#)
    *   [インストール](https://book.cakephp.org/elasticsearch/3/ja/#id2)
        
    *   [概要](https://book.cakephp.org/elasticsearch/3/ja/#id3)
        
    *   [Document オブジェクト](https://book.cakephp.org/elasticsearch/3/ja/#document)
        
    *   [インデックス付きドキュメントの検索](https://book.cakephp.org/elasticsearch/3/ja/#id4)
        
    *   [データのバリデーションとアプリケーションルールの使用](https://book.cakephp.org/elasticsearch/3/ja/#id5)
        
    *   [新しいドキュメントの保存](https://book.cakephp.org/elasticsearch/3/ja/#id6)
        
    *   [既存ドキュメントの更新](https://book.cakephp.org/elasticsearch/3/ja/#id7)
        
    *   [ドキュメントの削除](https://book.cakephp.org/elasticsearch/3/ja/#id8)
        
    *   [埋め込みドキュメント](https://book.cakephp.org/elasticsearch/3/ja/#id9)
        
    *   [Type インスタンスの取得](https://book.cakephp.org/elasticsearch/3/ja/#type)
        *   [レジストリーのフラッシュ](https://book.cakephp.org/elasticsearch/3/ja/#id10)
            
    *   [テストフィクスチャー](https://book.cakephp.org/elasticsearch/3/ja/#id11)
        

ElasticSearch[¶](https://book.cakephp.org/elasticsearch/3/ja/#elasticsearch "この見出しへのパーマリンク")

=============================================================================================

ElasticSearch プラグインは、[elasticsearch](https://www.elastic.co/products/elasticsearch)
 の上に ORM のような抽象化を提供します。そのプラグインは、テストの作成、 ドキュメントのインデックス作成、インデックスをより簡単に検索などの機能を提供します。

インストール[¶](https://book.cakephp.org/elasticsearch/3/ja/#id2 "この見出しへのパーマリンク")

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

ElasticSearch プラグインをインストールするには、 `composer` が利用できます。(composer.json ファイルが置かれている) アプリケーションの ROOT ディレクトリーから次のコマンドを実行します。

php composer.phar require cakephp/elastic\-search "@stable"

以下の1行をあなたのアプリケーションの **src/Application.php** ファイルに追加する必要があります。

$this\->addPlugin('Cake/ElasticSearch', \['bootstrap' \=> true\]);

// 3.6.0 より前は、Plugin::load() を使用する必要があります

追加で 'elastic' のデータソースの接続を **config/app.php** ファイルに設定する必要があります。 設定例は以下のようになります。

// config/app.php の中で
'Datasources' \=> \[\
    // 他のデータソース\
    'elastic' \=> \[\
        'className' \=> 'Cake\\ElasticSearch\\Datasource\\Connection',\
        'driver' \=> 'Cake\\ElasticSearch\\Datasource\\Connection',\
        'host' \=> '127.0.0.1',\
        'port' \=> 9200,\
        'index' \=> 'my\_apps\_index',\
    \],\
\]

概要[¶](https://book.cakephp.org/elasticsearch/3/ja/#id3 "この見出しへのパーマリンク")

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

ElasticSearch プラグインは elasticsearch インデックスと作用することを簡単にし、 [ORM](https://book.cakephp.org/3/ja/orm.html)
 に似たインタフェースを提供します。まず最初に `Type` オブジェクトを 作成しなければいけません。 `Type` オブジェクトは elasticsearch 内では "Repository" もしくは Table のようなクラスです。

// src/Model/Type/ArticlesType.php の中で
namespace App\\Model\\Type;

use Cake\\ElasticSearch\\Type;

class ArticlesType extends Type
{
}

コントローラーで Type クラスを利用できます。

public function beforeFilter(Event $event)
{
    parent::beforeFilter($event);
    // 'Elastic' プロバイダーを利用して Type を読み込む
    $this\->loadModel('Articles', 'Elastic');
}

public function add()
{
    $article \= $this\->Articles\->newEntity();
    if ($this\->request\->is('post')) {
        $article \= $this\->Articles\->patchEntity($article, $this\->request\->getData());
            if ($this\->Articles\->save($article)) {
            $this\->Flash\->success('It saved');
        }
    }
    $this\->set(compact('article'));
}

インデックスされた articles の基本的なビューを作成する必要があります。

// src/Template/Articles/add.ctp の中で
<?= $this\->Form\->create($article) ?>
<?\= $this\->Form\->control('title') ?>
<?\= $this\->Form\->control('body') ?>
<?\= $this\->Form\->button('Save') ?>
<?\= $this\->Form\->end() ?>

これで、フォームの送信が可能になり、新しいドキュメントが elasticsearch に追加されました。

Document オブジェクト[¶](https://book.cakephp.org/elasticsearch/3/ja/#document "この見出しへのパーマリンク")

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

ORM と同様に、Elasticsearch ODM は [エンティティー](https://book.cakephp.org/3.0/ja/orm/entities.html)
 のようなクラスを使用しています。 継承しなければならない基底クラスは `Cake\ElasticSearch\Document` です。 Document クラスは、アプリケーションやプラグイン内の `Model\Document` 名前空間に配置します。

namespace App\\Model\\Document;

use Cake\\ElasticSearch\\Document;

class Article extends Document
{
}

elasticsearch からのデータで Document を動作させるコンストラクターロジックの外側、 インターフェイスと `Document` によって提供される機能は、 [Entities](https://book.cakephp.org/3.0/ja/orm/entities.html)
 内にあるものと同じです。

インデックス付きドキュメントの検索[¶](https://book.cakephp.org/elasticsearch/3/ja/#id4 "この見出しへのパーマリンク")

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

いくつかのドキュメントをインデックスに登録した後、あなたはそれらを検索したいと思うでしょう。 ElasticSearch プラグインを使用すると、検索クエリーを構築するためのクエリービルダーを提供します。

$query \= $this\->Articles\->find()
    \->where(\[\
        'title' \=> 'special',\
        'or' \=> \[\
            'tags in' \=> \['cake', 'php'\],\
            'tags not in' \=> \['c#', 'java'\]\
        \]\
    \]);

foreach ($query as $article) {
    echo $article\->title;
}

フィルタリング条件を追加するために `QueryBuilder` を使用することができます。

$query\->where(function ($builder) {
    return $builder\->and(
        $builder\->gt('views', 99),
        $builder\->term('author.name', 'sally')
    );
});

[QueryBuilder のソース](https://github.com/cakephp/elastic-search/blob/master/src/QueryBuilder.php)
 は、多くの一般的に使用されるメソッドの例となるメソッドの完全なリストを持っています。

データのバリデーションとアプリケーションルールの使用[¶](https://book.cakephp.org/elasticsearch/3/ja/#id5 "この見出しへのパーマリンク")

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

ORMと同様に、ElasticSearch プラグインは、ドキュメントをマーシャリングするときに データを検証することができます。リクエストデータのバリデート、およびアプリケーションルールの 適用は、リレーショナルORMと同じ動作をします。詳細については、 [エンティティー構築前のデータ検証](https://book.cakephp.org/3.0/ja/orm/validation.html#validating-request-data)
 と [条件付き/動的なエラーメッセージ](https://book.cakephp.org/3.0/ja/orm/validation.html#id17)
 のセクションをご覧ください。

新しいドキュメントの保存[¶](https://book.cakephp.org/elasticsearch/3/ja/#id6 "この見出しへのパーマリンク")

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

elasticsearch にいくつかのデータをインデックスする準備ができたら、最初にインデックスが付けられる `Document` にデータを変換する必要があります。

$article \= $this\->Articles\->newEntity($data);
if ($this\->Articles\->save($article)) {
    // Document はインデックスされました
}

ドキュメントをマーシャリングするとき、 `associated` キーを使用してマーシャリングしたい 埋め込みドキュメントを指定することができます。

$article \= $this\->Articles\->newEntity($data, \['associated' \=> \['Comments'\]\]);

ドキュメントを保存すると、次のイベントがトリガーされます：

*   `Model.beforeSave` - ドキュメントが保存される前に発生します。 このイベントを停止することによって保存操作を防ぐことができます。
    
*   `Model.buildRules` - ルールチェッカーが最初に構築されているときに発生します。
    
*   `Model.afterSave` - ドキュメントが保存された後に発生します。
    

注釈

親ドキュメントとすべての埋め込みドキュメントを1つの操作で保存するため、 埋め込みドキュメントのためのイベントはありません。

既存ドキュメントの更新[¶](https://book.cakephp.org/elasticsearch/3/ja/#id7 "この見出しへのパーマリンク")

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

データの再インデックスが必要な場合、既存のエンティティーにパッチを適用すると再保存できます。

$query \= $this\->Articles\->find()\->where(\['user.name' \=> 'jill'\]);
foreach ($query as $doc) {
    $doc\->set($newProperties);
    $this\->Articles\->save($doc);
}

ドキュメントの削除[¶](https://book.cakephp.org/elasticsearch/3/ja/#id8 "この見出しへのパーマリンク")

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

ドキュメントを検索した後、それを削除することができます。

$doc \= $this\->Articles\->get($id);
$this\->Articles\->delete($doc);

また、特定の条件に一致するドキュメントを削除することができます。

$this\->Articles\->deleteAll(\['user.name' \=> 'bob'\]);

埋め込みドキュメント[¶](https://book.cakephp.org/elasticsearch/3/ja/#id9 "この見出しへのパーマリンク")

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

埋め込みドキュメントを定義することで、ドキュメント内の特定のプロパティーのパスに エンティティークラスを添付することができます。これは、親ドキュメント内のドキュメントに 独自の振る舞いを提供することができます。たとえば、あなたが記事に埋め込まれたコメントは、 特定のアプリケーション固有のメソッドを持っている場合があります。あなたが埋め込みドキュメントを 定義するために `embedOne` と `embedMany` を使用することができます。

// in src/Model/Type/ArticlesType.php
namespace App\\Model\\Type;

use Cake\\ElasticSearch\\Type;

class ArticlesType extends Type
{
    public function initialize()
    {
        $this\->embedOne('User');
        $this\->embedMany('Comments', \[\
            'entityClass' \=> 'MyComment'\
        \]);
    }
}

上記の `Article` ドキュメント上の2つの埋め込みドキュメントを作成します。 `User` 埋め込みは `App\Model\Document\User` のインスタンスに `user` プロパティーを変換します。 プロパティー名と一致していないクラス名を使用する埋め込みコメントを得るためには、カスタムクラス名を 設定するための `entityClass` オプションを使用することができます。

埋め込みドキュメントをセットアップしたら、 `find()` と `get` の結果は 正しい埋め込みドキュメントクラスのオブジェクトを返します。

$article \= $this\->Articles\->get($id);
// App\\Model\\Document\\User のインスタンス
$article\->user;

// App\\Model\\Document\\Comment インスタンスの配列
$article\->comments;

Type インスタンスの取得[¶](https://book.cakephp.org/elasticsearch/3/ja/#type "この見出しへのパーマリンク")

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

ORM と同様に、ElasticSearch プラグインは `Type` のインスタンスを取得するための ファクトリー/レジストリーを提供します。

use Cake\\ElasticSearch\\TypeRegistry;

$articles \= TypeRegistry::get('Articles');

### レジストリーのフラッシュ[¶](https://book.cakephp.org/elasticsearch/3/ja/#id10 "この見出しへのパーマリンク")

テストケースの中で、レジストリーをフラッシュすることができます。 そうすることでモックオブジェクトを使用したり、Type の依存関係を変更する際に便利です。

TypeRegistry::flush();

テストフィクスチャー[¶](https://book.cakephp.org/elasticsearch/3/ja/#id11 "この見出しへのパーマリンク")

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

ElasticSearch プラグインは、シームレスなテストスイートの統合を提供します。ちょうどデータベースの フィクスチャーのように、elasticsearch のためのテストフィクスチャーを作成することができます。 次のように Articles タイプのテストフィクスチャーを定義することができます。

namespace App\\Test\\Fixture;

use Cake\\ElasticSearch\\TestSuite\\TestFixture;

/\*\*
 \* Articles fixture
 \*/
class ArticlesFixture extends TestFixture
{
    /\*\*
     \* The table/type for this fixture.
     \*
     \* @var string
     \*/
    public $table \= 'articles';

    /\*\*
     \* The mapping data.
     \*
     \* @var array
     \*/
    public $schema \= \[\
        'id' \=> \['type' \=> 'integer'\],\
        'user' \=> \[\
            'type' \=> 'nested',\
            'properties' \=> \[\
                'username' \=> \['type' \=> 'string'\],\
            \]\
        \],\
        'title' \=> \['type' \=> 'string'\],\
        'body' \=> \['type' \=> 'string'\],\
    \];

    public $records \= \[\
        \[\
            'user' \=> \[\
                'username' \=> 'billy'\
            \],\
            'title' \=> 'First Post',\
            'body' \=> 'Some content'\
        \]\
    \];
}

`schema` プロパティーは [ネイティブ elasticsearch マッピングフォーマット](https://www.elastic.co/guide/en/elasticsearch/reference/1.5/mapping.html)
 を使用します。 安全にタイプ名およびトップレベルの `properties` キーを省略することができます。 フィクスチャーが作成されたら、あなたのテストの `fixtures` プロパティーに含めることによって、 あなたのテストケースで使用することができます。

public $fixtures \= \['app.Articles'\];

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# Chronos - 1.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/chronos/edit/1.x/docs/ja/index.rst)

[](https://book.cakephp.org/chronos/1/ja/#page-contents)

### Page Contents

*   [Chronos](https://book.cakephp.org/chronos/1/ja/#)
    *   [インストール](https://book.cakephp.org/chronos/1/ja/#id1)
        
    *   [概要](https://book.cakephp.org/chronos/1/ja/#id2)
        
    *   [インスタンスの作成](https://book.cakephp.org/chronos/1/ja/#id3)
        
    *   [イミュータブルオブジェクトの動作](https://book.cakephp.org/chronos/1/ja/#id4)
        
    *   [日付オブジェクト](https://book.cakephp.org/chronos/1/ja/#id5)
        
    *   [変更メソッド](https://book.cakephp.org/chronos/1/ja/#id6)
        
    *   [比較メソッド](https://book.cakephp.org/chronos/1/ja/#id7)
        
    *   [差の生成](https://book.cakephp.org/chronos/1/ja/#id8)
        
    *   [フォーマットの設定](https://book.cakephp.org/chronos/1/ja/#id9)
        
    *   [日付要素の抽出](https://book.cakephp.org/chronos/1/ja/#id10)
        
    *   [テストの支援](https://book.cakephp.org/chronos/1/ja/#id11)
        

Chronos[¶](https://book.cakephp.org/chronos/1/ja/#chronos "このヘッドラインへのパーマリンク")

==============================================================================

Chronos (クロノス) は、 `DateTime` オブジェクトへの拡張の依存関係の無いコレクションを提供します。 便利なメソッドに加えて、Chronos は以下を提供します。

*   カレンダー日付のための `Date` オブジェクト
    
*   イミュータブルな日付と日時オブジェクト
    
*   プラグインのような翻訳システム。ライブラリーは英語のみの翻訳を含んでいます。 しかし、全ての言語サポートのために、 `cakephp/i18n` を使うことができます。
    

インストール[¶](https://book.cakephp.org/chronos/1/ja/#id1 "このヘッドラインへのパーマリンク")

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

Chronos をインストールするためには、 `composer` を利用することができます。 アプリケーションの ROOT ディレクトリー（composer.json ファイルのある場所） で以下のように実行します。

php composer.phar require cakephp/chronos "@stable"

概要[¶](https://book.cakephp.org/chronos/1/ja/#id2 "このヘッドラインへのパーマリンク")

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

Chronos は PHP が提供する DateTime オブジェクトのいくつかの拡張を提供します。 Chronos は `DateInterval` の拡張機能および、ミュータブル（変更可能）と イミュータブル（変更不可）な 日付/時刻 の派生系をカバーする5つのクラスを提供します。

*   `Cake\Chronos\Chronos` はイミュータブルな _日付と時刻_ オブジェクト。
    
*   `Cake\Chronos\Date` はイミュータブルな _日付_ オブジェクト。
    
*   `Cake\Chronos\MutableDateTime` はミュータブルな _日付と時刻_ オブジェクト。
    
*   `Cake\Chronos\MutableDate` はミュータブルな _日付_ オブジェクト。
    
*   `Cake\Chronos\ChronosInterval` は `DateInterval` の拡張機能。
    

最後に、もしあなたが Chronos が提供する 日付/時刻 のオブジェクトに対して型宣言を行ないたい場合、 `Cake\Chronos\ChronosInterface` を使用することができます。 全ての日付と時間のオブジェクトはこのインターフェイスを実装しています。

インスタンスの作成[¶](https://book.cakephp.org/chronos/1/ja/#id3 "このヘッドラインへのパーマリンク")

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

Chronos または Date のインスタンスを取得するためには、多くの方法があります。 異なる引数セットで動作する多くのファクトリーメソッドがあります。

use Cake\\Chronos\\Chronos;

$now \= Chronos::now();
$today \= Chronos::today();
$yesterday \= Chronos::yesterday();
$tomorrow \= Chronos::tomorrow();

// 相対式のパース
$date \= Chronos::parse('+2 days, +3 hours');

// 日付と時間の整数値
$date \= Chronos::create(2015, 12, 25, 4, 32, 58);

// 日付または時間の整数値
$date \= Chronos::createFromDate(2015, 12, 25);
$date \= Chronos::createFromTime(11, 45, 10);

// 整形した値にパース
$date \= Chronos::createFromFormat('m/d/Y', '06/15/2015');

イミュータブルオブジェクトの動作[¶](https://book.cakephp.org/chronos/1/ja/#id4 "このヘッドラインへのパーマリンク")

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

もしあなたが、PHP の `DateTime` オブジェクトを使用したことがあるなら、 _ミュータブル_ オブジェクトは簡単に使用できます。 Chronos はミュータブルオブジェクトを提供しますが、これは _イミュータブル_ オブジェクトにもなります。 イミュータブルオブジェクトはオブジェクトが変更されるたびにオブジェクトのコピーを作ります。 なぜなら、日時周りの変更メソッドは必ずしも透明でないため、データが誤って、 または開発者が知らない内に変更してしまうからです。 イミュータブルオブジェクトはデータが誤って変更されることを防止し、 順序ベースの依存関係の問題の無いコードを作ります。 不変性は、変更時に忘れずに変数を置き換える必要があることを意味しています。

// このコードはイミュータブルオブジェクトでは動作しません
$time\->addDay(1);
doSomething($time);
return $time

// このコードは期待通りに動作します
$time \= $time\->addDay(1);
$time \= doSomething($time);
return $time

各修正の戻り値をキャプチャーすることによって、コードは期待通りに動作します。 イミュータブルオブジェクトを持っていて、ミュータブルオブジェクトを作りたい場合、 `toMutable()` が使用できます。

$inplace \= $time\->toMutable();

日付オブジェクト[¶](https://book.cakephp.org/chronos/1/ja/#id5 "このヘッドラインへのパーマリンク")

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

PHP は単純な DateTime オブジェクトだけを提供します。このクラスのカレンダー日付の表現で、 タイムゾーンおよび、本当に「日」の概念に属していないタイムコンポーネントを含むと、 少し厄介な可能性があります。 Chronos は日時表現のための `Date` オブジェクトを提供します。 これらのオブジェクトの時間とタイムゾーンは常に `00:00:00 UTC` に固定されており、 全ての書式/差分のメソッドは一日単位で動作します。

use Cake\\Chronos\\Date;

$today \= Date::today();

// 時間/タイムゾーンの変更は無視されます
$today\->modify('+1 hours');

// 出力 '2015-12-20'
echo $today;

変更メソッド[¶](https://book.cakephp.org/chronos/1/ja/#id6 "このヘッドラインへのパーマリンク")

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

Chronos オブジェクトは細やかに値を変更できるメソッドを提供します。

// 日時の値のコンポーネントを設定
$halloween \= Chronos::create()
    \->year(2015)
    \->month(10)
    \->day(31)
    \->hour(20)
    \->minute(30);

また、日時の部分を相対的に変更することもできます。

$future \= Chronos::create()
    \->addYear(1)
    \->subMonth(2)
    \->addDays(15)
    \->addHours(20)
    \->subMinutes(2);

また、ある時間の中で、定義された時点に飛ぶことも可能です。

$time \= Chronos::create();
$time\->startOfDay();
$time\->endOfDay();
$time\->startOfMonth();
$time\->endOfMonth();
$time\->startOfYear();
$time\->endOfYear();
$time\->startOfWeek();
$time\->endOfWeek();

また、1週間中の特定の日にも飛べます。

$time\->next(ChronosInterface::TUESDAY);
$time\->previous(ChronosInterface::MONDAY);

DST の遷移の前後で日付/時間を変更すると、 あなたの操作で時間が増減するかもしれませんが、その結果、意図しない時間の値になります。 これらの問題を回避するには、最初にタイムゾーンを `UTC` に変更し、時間を変更します。

// 余分な時間が追加されました
$time \= new Chronos('2014-03-30 00:00:00', 'Europe/London');
debug($time\->modify('+24 hours')); // 2014-03-31 01:00:00

// 最初に UTC に切り替え、そして更新
$time \= $time\->setTimezone('UTC')
    \->modify('+24 hours');

時間を変更すると、元のタイムゾーンを追加してローカライズされた時間を取得することができます。

比較メソッド[¶](https://book.cakephp.org/chronos/1/ja/#id7 "このヘッドラインへのパーマリンク")

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

Chronos の日付/時間オブジェクトの2つのインスタンスを様々な方法で比較することができます。

// 比較のフルセットが存在します
// ne, gt, lt, lte.
$first\->eq($second);
$first\->gte($second);

// カレントオブジェクトが2つのオブジェクトの間にあるかどうかを確認します。
$now\->between($start, $end);

// どちらの引数が最も近い (closest) か、または最も遠い (farthest) かを見つけます。
$now\->closest($june, $november);
$now\->farthest($june, $november);

また、与えられた値のカレンダーに当たる場所について問い合わせできます。

$now\->isToday();
$now\->isYesterday();
$now\->isFuture();
$now\->isPast();

// 曜日をチェック
$now\->isWeekend();

// 他の曜日のメソッドも全て存在します。
$now\->isMonday();

また、値が相対的な期間内にあったかどうかを見つけることができます。

$time\->wasWithinLast('3 days');
$time\->isWithinNext('3 hours');

差の生成[¶](https://book.cakephp.org/chronos/1/ja/#id8 "このヘッドラインへのパーマリンク")

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

日時比較に加えて、2つの値の差や変化の計算は一般的なタスクです。

// 差をあらわす DateInterval を取得
$first\->diff($second);

// 特定の単位での差を取得
$first\->diffInHours($second);
$first\->diffInDays($second);
$first\->diffInWeeks($second);
$first\->diffInYears($second);

フィードやタイムラインで使用するのに適した、人が読める形式の差を生成することができます。

// 現在からの差
echo $date\->diffForHumans();

// 別の時点からの差
echo $date\->diffForHumans($other); // 1時間前;

フォーマットの設定[¶](https://book.cakephp.org/chronos/1/ja/#id9 "このヘッドラインへのパーマリンク")

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

Chronos は、出力した日時オブジェクトを表示するための多くのメソッドを提供します。

// setToStringFormat() が制御するフォーマットを使用します
echo $date;

// 別の標準フォーマット
echo $time\->toAtomString();      // 1975-12-25T14:15:16-05:00
echo $time\->toCookieString();    // Thursday, 25-Dec-1975 14:15:16 EST
echo $time\->toIso8601String();   // 1975-12-25T14:15:16-05:00
echo $time\->toRfc822String();    // Thu, 25 Dec 75 14:15:16 -0500
echo $time\->toRfc850String();    // Thursday, 25-Dec-75 14:15:16 EST
echo $time\->toRfc1036String();   // Thu, 25 Dec 75 14:15:16 -0500
echo $time\->toRfc1123String();   // Thu, 25 Dec 1975 14:15:16 -0500
echo $time\->toRfc2822String();   // Thu, 25 Dec 1975 14:15:16 -0500
echo $time\->toRfc3339String();   // 1975-12-25T14:15:16-05:00
echo $time\->toRssString();       // Thu, 25 Dec 1975 14:15:16 -0500
echo $time\->toW3cString();       // 1975-12-25T14:15:16-05:00

// クォーター/週数を取得
echo $time\->toQuarter();         // 4;
echo $time\->toWeek();            // 52

// 一般的なフォーマット
echo $time\->toTimeString();           // 14:15:16
echo $time\->toDateString();           // 1975-12-25
echo $time\->toDateTimeString();       // 1975-12-25 14:15:16
echo $time\->toFormattedDateString();  // Dec 25, 1975
echo $time\->toDayDateTimeString();    // Thu, Dec 25, 1975 2:15 PM

日付要素の抽出[¶](https://book.cakephp.org/chronos/1/ja/#id10 "このヘッドラインへのパーマリンク")

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

日付オブジェクトのプロパティーに直接アクセスして要素を取得することができます。

$time \= new Chronos('2015-12-31 23:59:58');
$time\->year;    // 2015
$time\->month;   // 12
$time\->day;     // 31
$time\->hour     // 23
$time\->minute   // 59
$time\->second   // 58

以下のプロパティーにもアクセスできます。 :

*   timezone
    
*   timezoneName
    
*   micro
    
*   dayOfWeek
    
*   dayOfMonth
    
*   dayOfYear
    
*   daysInMonth
    
*   timestamp
    
*   quarter
    

テストの支援[¶](https://book.cakephp.org/chronos/1/ja/#id11 "このヘッドラインへのパーマリンク")

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

単体テストを書いている時、現在時刻を固定すると便利です。Chronos は、 各クラスの現在時刻を修正することができます。 テストスイートの bootstrap 処理に以下を含めることができます。

Chronos::setTestNow(Chronos::now());
MutableDateTime::setTestNow(MutableDateTime::now());
Date::setTestNow(Date::now());
MutableDate::setTestNow(MutableDate::now());

これでテストスイートが開始された時点で全てのオブジェクトの現在時刻を修正します。

例えば、 `Chronos` を過去のある瞬間に固定した場合、新たな `Chronos` のインスタンスが生成する `now` または相対時刻の文字列は、 固定された時刻の相対を返却します。

Chronos::setTestNow(new Chronos('1975-12-25 00:00:00'));

$time \= new Chronos(); // 1975-12-25 00:00:00
$time \= new Chronos('1 hour ago'); // 1975-12-24 23:00:00

固定をリセットするには、 `setTestNow()` をパラメーター無し、または `null` を設定して 再び呼び出してください。

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# ElasticSearch - 2.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/elastic-search/edit/master/docs/ja/index.rst)

[](https://book.cakephp.org/elasticsearch/2/ja/#page-contents)

### Page Contents

*   [ElasticSearch](https://book.cakephp.org/elasticsearch/2/ja/#)
    *   [インストール](https://book.cakephp.org/elasticsearch/2/ja/#id2)
        
    *   [概要](https://book.cakephp.org/elasticsearch/2/ja/#id3)
        
    *   [Document オブジェクト](https://book.cakephp.org/elasticsearch/2/ja/#document)
        
    *   [インデックス付きドキュメントの検索](https://book.cakephp.org/elasticsearch/2/ja/#id4)
        
    *   [データのバリデーションとアプリケーションルールの使用](https://book.cakephp.org/elasticsearch/2/ja/#id5)
        
    *   [新しいドキュメントの保存](https://book.cakephp.org/elasticsearch/2/ja/#id6)
        
    *   [既存ドキュメントの更新](https://book.cakephp.org/elasticsearch/2/ja/#id7)
        
    *   [ドキュメントの削除](https://book.cakephp.org/elasticsearch/2/ja/#id8)
        
    *   [埋め込みドキュメント](https://book.cakephp.org/elasticsearch/2/ja/#id9)
        
    *   [Type インスタンスの取得](https://book.cakephp.org/elasticsearch/2/ja/#type)
        *   [レジストリーのフラッシュ](https://book.cakephp.org/elasticsearch/2/ja/#id10)
            
    *   [テストフィクスチャー](https://book.cakephp.org/elasticsearch/2/ja/#id11)
        

ElasticSearch[¶](https://book.cakephp.org/elasticsearch/2/ja/#elasticsearch "このヘッドラインへのパーマリンク")

================================================================================================

ElasticSearch プラグインは、[elasticsearch](https://www.elastic.co/products/elasticsearch)
 の上に ORM のような抽象化を提供します。そのプラグインは、テストの作成、 ドキュメントのインデックス作成、インデックスをより簡単に検索などの機能を提供します。

インストール[¶](https://book.cakephp.org/elasticsearch/2/ja/#id2 "このヘッドラインへのパーマリンク")

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

ElasticSearch プラグインをインストールするには、 `composer` が利用できます。(composer.json ファイルが置かれている) アプリケーションの ROOT ディレクトリーから次のコマンドを実行します。

php composer.phar require cakephp/elastic\-search "^2.0"

以下の1行をあなたのアプリケーションの **src/Application.php** ファイルに追加する必要があります。

$this\->addPlugin('Cake/ElasticSearch', \['bootstrap' \=> true\]);

// 3.6.0 より前は、Plugin::load() を使用する必要があります

追加で 'elastic' のデータソースの接続を **config/app.php** ファイルに設定する必要があります。 設定例は以下のようになります。

// config/app.php の中で
'Datasources' \=> \[\
    // 他のデータソース\
    'elastic' \=> \[\
        'className' \=> 'Cake\\ElasticSearch\\Datasource\\Connection',\
        'driver' \=> 'Cake\\ElasticSearch\\Datasource\\Connection',\
        'host' \=> '127.0.0.1',\
        'port' \=> 9200,\
        'index' \=> 'my\_apps\_index',\
    \],\
\]

概要[¶](https://book.cakephp.org/elasticsearch/2/ja/#id3 "このヘッドラインへのパーマリンク")

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

ElasticSearch プラグインは elasticsearch インデックスと作用することを簡単にし、 [ORM](https://book.cakephp.org/3/ja/orm.html)
 に似たインタフェースを提供します。まず最初に `Type` オブジェクトを 作成しなければいけません。 `Type` オブジェクトは elasticsearch 内では "Repository" もしくは Table のようなクラスです。

// src/Model/Type/ArticlesType.php の中で
namespace App\\Model\\Type;

use Cake\\ElasticSearch\\Type;

class ArticlesType extends Type
{
}

コントローラーで Type クラスを利用できます。

public function beforeFilter(Event $event)
{
    parent::beforeFilter($event);
    // 'Elastic' プロバイダーを利用して Type を読み込む
    $this\->loadModel('Articles', 'Elastic');
}

public function add()
{
    $article \= $this\->Articles\->newEntity();
    if ($this\->request\->is('post')) {
        $article \= $this\->Articles\->patchEntity($article, $this\->request\->getData());
            if ($this\->Articles\->save($article)) {
            $this\->Flash\->success('It saved');
        }
    }
    $this\->set(compact('article'));
}

インデックスされた articles の基本的なビューを作成する必要があります。

// src/Template/Articles/add.ctp の中で
<?= $this\->Form\->create($article) ?>
<?\= $this\->Form\->control('title') ?>
<?\= $this\->Form\->control('body') ?>
<?\= $this\->Form\->button('Save') ?>
<?\= $this\->Form\->end() ?>

これで、フォームの送信が可能になり、新しいドキュメントが elasticsearch に追加されました。

Document オブジェクト[¶](https://book.cakephp.org/elasticsearch/2/ja/#document "このヘッドラインへのパーマリンク")

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

ORM と同様に、Elasticsearch ODM は [エンティティー](https://book.cakephp.org/3.0/ja/orm/entities.html)
 のようなクラスを使用しています。 継承しなければならない基底クラスは `Cake\ElasticSearch\Document` です。 Document クラスは、アプリケーションやプラグイン内の `Model\Document` 名前空間に配置します。

namespace App\\Model\\Document;

use Cake\\ElasticSearch\\Document;

class Article extends Document
{
}

elasticsearch からのデータで Document を動作させるコンストラクターロジックの外側、 インターフェイスと `Document` によって提供される機能は、 [Entities](https://book.cakephp.org/3.0/ja/orm/entities.html)
 内にあるものと同じです。

インデックス付きドキュメントの検索[¶](https://book.cakephp.org/elasticsearch/2/ja/#id4 "このヘッドラインへのパーマリンク")

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

いくつかのドキュメントをインデックスに登録した後、あなたはそれらを検索したいと思うでしょう。 ElasticSearch プラグインを使用すると、検索クエリーを構築するためのクエリービルダーを提供します。

$query \= $this\->Articles\->find()
    \->where(\[\
        'title' \=> 'special',\
        'or' \=> \[\
            'tags in' \=> \['cake', 'php'\],\
            'tags not in' \=> \['c#', 'java'\]\
        \]\
    \]);

foreach ($query as $article) {
    echo $article\->title;
}

フィルタリング条件を追加するために `QueryBuilder` を使用することができます。

$query\->where(function ($builder) {
    return $builder\->and(
        $builder\->gt('views', 99),
        $builder\->term('author.name', 'sally')
    );
});

[QueryBuilder のソース](https://github.com/cakephp/elastic-search/blob/master/src/QueryBuilder.php)
 は、多くの一般的に使用されるメソッドの例となるメソッドの完全なリストを持っています。

データのバリデーションとアプリケーションルールの使用[¶](https://book.cakephp.org/elasticsearch/2/ja/#id5 "このヘッドラインへのパーマリンク")

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

ORMと同様に、ElasticSearch プラグインは、ドキュメントをマーシャリングするときに データを検証することができます。リクエストデータのバリデート、およびアプリケーションルールの 適用は、リレーショナルORMと同じ動作をします。詳細については、 [エンティティー構築前のデータ検証](https://book.cakephp.org/3.0/ja/orm/validation.html#validating-request-data)
 と [条件付き/動的なエラーメッセージ](https://book.cakephp.org/3.0/ja/orm/validation.html#id17)
 のセクションをご覧ください。

新しいドキュメントの保存[¶](https://book.cakephp.org/elasticsearch/2/ja/#id6 "このヘッドラインへのパーマリンク")

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

elasticsearch にいくつかのデータをインデックスする準備ができたら、最初にインデックスが付けられる `Document` にデータを変換する必要があります。

$article \= $this\->Articles\->newEntity($data);
if ($this\->Articles\->save($article)) {
    // Document はインデックスされました
}

ドキュメントをマーシャリングするとき、 `associated` キーを使用してマーシャリングしたい 埋め込みドキュメントを指定することができます。

$article \= $this\->Articles\->newEntity($data, \['associated' \=> \['Comments'\]\]);

ドキュメントを保存すると、次のイベントがトリガーされます：

*   `Model.beforeSave` - ドキュメントが保存される前に発生します。 このイベントを停止することによって保存操作を防ぐことができます。
    
*   `Model.buildRules` - ルールチェッカーが最初に構築されているときに発生します。
    
*   `Model.afterSave` - ドキュメントが保存された後に発生します。
    

注釈

親ドキュメントとすべての埋め込みドキュメントを1つの操作で保存するため、 埋め込みドキュメントのためのイベントはありません。

既存ドキュメントの更新[¶](https://book.cakephp.org/elasticsearch/2/ja/#id7 "このヘッドラインへのパーマリンク")

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

データの再インデックスが必要な場合、既存のエンティティーにパッチを適用すると再保存できます。

$query \= $this\->Articles\->find()\->where(\['user.name' \=> 'jill'\]);
foreach ($query as $doc) {
    $doc\->set($newProperties);
    $this\->Articles\->save($doc);
}

ドキュメントの削除[¶](https://book.cakephp.org/elasticsearch/2/ja/#id8 "このヘッドラインへのパーマリンク")

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

ドキュメントを検索した後、それを削除することができます。

$doc \= $this\->Articles\->get($id);
$this\->Articles\->delete($doc);

また、特定の条件に一致するドキュメントを削除することができます。

$this\->Articles\->deleteAll(\['user.name' \=> 'bob'\]);

埋め込みドキュメント[¶](https://book.cakephp.org/elasticsearch/2/ja/#id9 "このヘッドラインへのパーマリンク")

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

埋め込みドキュメントを定義することで、ドキュメント内の特定のプロパティーのパスに エンティティークラスを添付することができます。これは、親ドキュメント内のドキュメントに 独自の振る舞いを提供することができます。たとえば、あなたが記事に埋め込まれたコメントは、 特定のアプリケーション固有のメソッドを持っている場合があります。あなたが埋め込みドキュメントを 定義するために `embedOne` と `embedMany` を使用することができます。

// in src/Model/Type/ArticlesType.php
namespace App\\Model\\Type;

use Cake\\ElasticSearch\\Type;

class ArticlesType extends Type
{
    public function initialize()
    {
        $this\->embedOne('User');
        $this\->embedMany('Comments', \[\
            'entityClass' \=> 'MyComment'\
        \]);
    }
}

上記の `Article` ドキュメント上の2つの埋め込みドキュメントを作成します。 `User` 埋め込みは `App\Model\Document\User` のインスタンスに `user` プロパティーを変換します。 プロパティー名と一致していないクラス名を使用する埋め込みコメントを得るためには、カスタムクラス名を 設定するための `entityClass` オプションを使用することができます。

埋め込みドキュメントをセットアップしたら、 `find()` と `get` の結果は 正しい埋め込みドキュメントクラスのオブジェクトを返します。

$article \= $this\->Articles\->get($id);
// App\\Model\\Document\\User のインスタンス
$article\->user;

// App\\Model\\Document\\Comment インスタンスの配列
$article\->comments;

Type インスタンスの取得[¶](https://book.cakephp.org/elasticsearch/2/ja/#type "このヘッドラインへのパーマリンク")

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

ORM と同様に、ElasticSearch プラグインは `Type` のインスタンスを取得するための ファクトリー/レジストリーを提供します。

use Cake\\ElasticSearch\\TypeRegistry;

$articles \= TypeRegistry::get('Articles');

### レジストリーのフラッシュ[¶](https://book.cakephp.org/elasticsearch/2/ja/#id10 "このヘッドラインへのパーマリンク")

テストケースの中で、レジストリーをフラッシュすることができます。 そうすることでモックオブジェクトを使用したり、Type の依存関係を変更する際に便利です。

TypeRegistry::flush();

テストフィクスチャー[¶](https://book.cakephp.org/elasticsearch/2/ja/#id11 "このヘッドラインへのパーマリンク")

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

ElasticSearch プラグインは、シームレスなテストスイートの統合を提供します。ちょうどデータベースの フィクスチャーのように、elasticsearch のためのテストフィクスチャーを作成することができます。 次のように Articles タイプのテストフィクスチャーを定義することができます。

namespace App\\Test\\Fixture;

use Cake\\ElasticSearch\\TestSuite\\TestFixture;

/\*\*
 \* Articles fixture
 \*/
class ArticlesFixture extends TestFixture
{
    /\*\*
     \* The table/type for this fixture.
     \*
     \* @var string
     \*/
    public $table \= 'articles';

    /\*\*
     \* The mapping data.
     \*
     \* @var array
     \*/
    public $schema \= \[\
        'id' \=> \['type' \=> 'integer'\],\
        'user' \=> \[\
            'type' \=> 'nested',\
            'properties' \=> \[\
                'username' \=> \['type' \=> 'string'\],\
            \]\
        \],\
        'title' \=> \['type' \=> 'string'\],\
        'body' \=> \['type' \=> 'string'\],\
    \];

    public $records \= \[\
        \[\
            'user' \=> \[\
                'username' \=> 'billy'\
            \],\
            'title' \=> 'First Post',\
            'body' \=> 'Some content'\
        \]\
    \];
}

`schema` プロパティーは [ネイティブ elasticsearch マッピングフォーマット](https://www.elastic.co/guide/en/elasticsearch/reference/1.5/mapping.html)
 を使用します。 安全にタイプ名およびトップレベルの `properties` キーを省略することができます。 フィクスチャーが作成されたら、あなたのテストの `fixtures` プロパティーに含めることによって、 あなたのテストケースで使用することができます。

public $fixtures \= \['app.Articles'\];

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# Bake コンソール - 1.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/bake/edit/1.x/docs/ja/index.rst)

[](https://book.cakephp.org/bake/1/ja/#page-contents)

### Page Contents

*   [Bake コンソール](https://book.cakephp.org/bake/1/ja/#)
    *   [インストール手順](https://book.cakephp.org/bake/1/ja/#id1)
        

Bake コンソール[¶](https://book.cakephp.org/bake/1/ja/#bake "このヘッドラインへのパーマリンク")

===========================================================================

CakePHP の bake コンソールは、迅速に CakePHP を動作させるまでを支援します。 bake コンソールは、CakePHP の基本的な素材(モデル、ビヘイビアー、ビュー、ヘルパー、 コントローラー、コンポーネント、テストケース、フィクスチャー、プラグイン)を作成できます。 その為のスケルトンクラスについては、ここでは省略しますが、 bake は数分で完全に機能するアプリケーションを作成できます。 要するに、bake は足場の組まれたアプリケーションをいっぺんに手に入れるためにうってつけの方法です。

インストール手順[¶](https://book.cakephp.org/bake/1/ja/#id1 "このヘッドラインへのパーマリンク")

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

bake を使用したり拡張する前に、アプリケーションに bake をインストールしておいてください。 bake は Composer を使ってインストールするプラグインとして提供されています。

composer require \--dev cakephp/bake:~1.0

上記のコマンドは、bake を開発環境で使用するパッケージとしてインストールします。 この入れ方の場合、本番環境としてデプロイする際には、 bake はインストールされません。

Twig テンプレートを使用する場合、 `WyriHaximus/TwigView` プラグインをブートストラップとともに 読み込んでいることを確認してください。それを完全に省略して、 Bake プラグインにこのプラグインを読み込ませることもできます。

[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://cakesf.herokuapp.com/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")
[#IRC](https://webchat.freenode.net/?channels=cakephp "IRC")

---

# Migrations - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/migrations/edit/3.x/docs/ja/index.rst)

[](https://book.cakephp.org/migrations/3/ja/#page-contents)

### Page Contents

*   [Migrations](https://book.cakephp.org/migrations/3/ja/#)
    *   [インストール](https://book.cakephp.org/migrations/3/ja/#id1)
        
    *   [概要](https://book.cakephp.org/migrations/3/ja/#id2)
        
    *   [マイグレーションファイルの作成](https://book.cakephp.org/migrations/3/ja/#id3)
        *   [シンタックス](https://book.cakephp.org/migrations/3/ja/#id5)
            *   [マイグレーションファイル名](https://book.cakephp.org/migrations/3/ja/#id6)
                
            *   [カラムの定義](https://book.cakephp.org/migrations/3/ja/#id8)
                
        *   [テーブルの作成](https://book.cakephp.org/migrations/3/ja/#id9)
            
        *   [既存のテーブルにカラムを追加](https://book.cakephp.org/migrations/3/ja/#id10)
            
        *   [テーブルにインデックスとしてカラムを追加](https://book.cakephp.org/migrations/3/ja/#id11)
            
        *   [フィールド長を指定](https://book.cakephp.org/migrations/3/ja/#id12)
            
        *   [テーブルから列を変更する](https://book.cakephp.org/migrations/3/ja/#id13)
            
        *   [テーブルからカラムを削除](https://book.cakephp.org/migrations/3/ja/#id14)
            
        *   [既存のデータベースからマイグレーションファイルを作成する](https://book.cakephp.org/migrations/3/ja/#id15)
            
    *   [２つのデータベース間の状態の差分を生成する](https://book.cakephp.org/migrations/3/ja/#id16)
        
    *   [コマンド](https://book.cakephp.org/migrations/3/ja/#id17)
        *   [`migrate` : マイグレーションを適用する](https://book.cakephp.org/migrations/3/ja/#migrate)
            
        *   [`rollback` : マイグレーションを戻す](https://book.cakephp.org/migrations/3/ja/#rollback)
            
        *   [`status` : マイグレーションのステータス](https://book.cakephp.org/migrations/3/ja/#status)
            
        *   [`mark_migrated` : マイグレーション済みとしてマーキングする](https://book.cakephp.org/migrations/3/ja/#mark-migrated)
            
        *   [`seed` : データベースの初期データ投入](https://book.cakephp.org/migrations/3/ja/#seed)
            *   [シーダーから別のシーダーの呼び出し](https://book.cakephp.org/migrations/3/ja/#id18)
                
        *   [`dump` : 差分を bake する機能のためのダンプファイルの生成](https://book.cakephp.org/migrations/3/ja/#dump-bake)
            
    *   [プラグイン内のマイグレーションファイルを使う](https://book.cakephp.org/migrations/3/ja/#id19)
        
    *   [非シェルの環境でマイグレーションを実行する](https://book.cakephp.org/migrations/3/ja/#id20)
        
    *   [小技と裏技](https://book.cakephp.org/migrations/3/ja/#id21)
        *   [主キーをカスタマイズする](https://book.cakephp.org/migrations/3/ja/#id22)
            
        *   [照合順序](https://book.cakephp.org/migrations/3/ja/#id23)
            
        *   [カラム名の更新と Table オブジェクトの使用](https://book.cakephp.org/migrations/3/ja/#table)
            
        *   [マイグレーションとデプロイメント](https://book.cakephp.org/migrations/3/ja/#id24)
            
        *   [テーブルのリネーム](https://book.cakephp.org/migrations/3/ja/#id25)
            
        *   [`schema.lock` ファイル生成のスキップ](https://book.cakephp.org/migrations/3/ja/#schema-lock)
            

Migrations[¶](https://book.cakephp.org/migrations/3/ja/#migrations "この見出しへのパーマリンク")

====================================================================================

マイグレーションは、バージョン管理システムを使用して追跡することができる PHP ファイルを 記述することによって、あなたのデータベースのスキーマ変更を行うための、コアチームによって サポートされているプラグインです。

それはあなたが時間をかけてあなたのデータベーステーブルを進化させることができます。 スキーマ変更の SQL を書く代わりに、このプラグインでは、直観的にデータベースの変更を 実現するための手段を使用することができます。

このプラグインは、データベースマイグレーションライブラリーの [Phinx](https://phinx.org/)
 のラッパーです。

インストール[¶](https://book.cakephp.org/migrations/3/ja/#id1 "この見出しへのパーマリンク")

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

初期状態で Migrations は、デフォルトのアプリケーションの雛形と一緒にインストールされます。 もしあなたがそれを削除して再インストールしたい場合は、（composer.json ファイルが 配置されている）アプリケーションルートディレクトリーから次のコマンドを実行します。

php composer.phar require cakephp/migrations "@stable"

\# また、composer がグローバルにインストールされていた場合は、

composer require cakephp/migrations "@stable"

このプラグインを使用するためには、あなたは、アプリケーションの **config/bootstrap.php** ファイルでロードする必要があります。あなたの **config/bootstrap.php** からプラグインを ロード・アンロードするために [CakePHP の Plugin シェル](https://book.cakephp.org/3.0/ja/console-and-shells/plugin-shell.html)
 が利用できます。 :

bin/cake plugin load Migrations

もしくは、あなたの **src/Application.php** ファイルを編集し、次の行を追加することで ロードすることができます。

$this\->addPlugin('Migrations');

// 3.6.0 より前は Plugin::load() を使用する必要があります

また、 [データベース設定](https://book.cakephp.org/3.0/en/orm/database-basics.html#database-configuration)
 の項で説明したように、 あなたの **config/app.php** ファイル内のデフォルトのデータベース構成を設定する必要が あります。

概要[¶](https://book.cakephp.org/migrations/3/ja/#id2 "この見出しへのパーマリンク")

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

マイグレーションは、基本的にはデータベースの変更の操作を PHP ファイルで表します。 マイグレーションファイルはテーブルを作成し、カラムの追加や削除、インデックスの作成や データの作成さえ可能です。

ここにマイグレーションの例があります。

<?php
use Migrations\\AbstractMigration;

class CreateProducts extends AbstractMigration
{
    /\*\*
     \* Change Method.
     \*
     \* More information on this method is available here:
     \* https://book.cakephp.org/phinx/0/en/migrations.html#the-change-method
     \* @return void
     \*/
    public function change()
    {
        $table \= $this\->table('products');
        $table\->addColumn('name', 'string', \[\
            'default' \=> null,\
            'limit' \=> 255,\
            'null' \=> false,\
        \]);
        $table\->addColumn('description', 'text', \[\
            'default' \=> null,\
            'null' \=> false,\
        \]);
        $table\->addColumn('created', 'datetime', \[\
            'default' \=> null,\
            'null' \=> false,\
        \]);
        $table\->addColumn('modified', 'datetime', \[\
            'default' \=> null,\
            'null' \=> false,\
        \]);
        $table\->create();
    }
}

マイグレーションは、データベースに `products` という名前のテーブルを追加します。 以下のカラムが定義します。

*   `id` カラムの型は、主キーの `integer`
    
*   `name` カラムの型は `string`
    
*   `description` カラムの型は `text`
    
*   `created` カラムの型は `datetime`
    
*   `modified` カラムの型は `datetime`
    

Tip

主キーのカラム名 `id` は、 **暗黙のうちに** 追加されます。

注釈

このファイルは変更を **適用後** にデータベースがどのようになるかを記述していることに 注意してください。この時点でデータベースに `products` テーブルは存在せず、 `products` テーブルを作って項目を追加することができるのと同様に、マイグレーションを `rollback` すればテーブルが消えてしまいます。

マイグレーションファイルを **config/Migrations** フォルダーに作成したら、下記の `migrations` コマンドを実行することでデータベースにテーブルを作成することがでます。 :

bin/cake migrations migrate

以下の `migrations` コマンドは、 `rollback` を実行するとあなたのデータベースから テーブルが削除されます。

bin/cake migrations rollback

マイグレーションファイルの作成[¶](https://book.cakephp.org/migrations/3/ja/#id3 "この見出しへのパーマリンク")

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

マイグレーションファイルは、あなたのアプリケーションの **config/Migration** ディレクトリーに配置します。マイグレーションファイルの名前には、先頭に **YYYYMMDDHHMMSS\_MigrationName.php** というように作成した日付を付けます。 以下がマイグレーションファイルの例です。

*   20160121163850\_CreateProducts.php
    
*   20160210133047\_AddRatingToProducts.php
    

マイグレーションファイルを作成する最も簡単な方法は `bake` CLI コマンドを使用することです。

マイグレーションファイルに記述可能なメソッドの一覧については、オフィシャルの [Phinx ドキュメント](https://book.cakephp.org/phinx/0/en/migrations.html)
 をご覧ください。

注釈

`bake` オプションを使用する場合、もし望むなら実行する前にマイグレーションを修正できます。

### シンタックス[¶](https://book.cakephp.org/migrations/3/ja/#id5 "この見出しへのパーマリンク")

以下の `bake` コマンドは、 `products` テーブルを追加するためのマイグレーションファイルを 作成します。 :

bin/cake bake migration CreateProducts name:string description:text created modified

あなたのデータベースにテーブルの作成、カラムの追加などをするために `bake` を使用する場合、 一般に以下の２点を指定します。

*   あなたが生成するマイグレーションの名前 (例えば、 `CreateProducts`)
    
*   マイグレーションで追加や削除を行うテーブルのカラム (例えば、 `name:string description:text created modified`)
    

規約のために、すべてのスキーマの変更がこれらのシェルコマンドで動作するわけではありません。

さらに、実行内容を完全に制御したいのであれば、空のマイグレーションファイルを 作る事ができます。

bin/cake migrations create MyCustomMigration

#### マイグレーションファイル名[¶](https://book.cakephp.org/migrations/3/ja/#id6 "この見出しへのパーマリンク")

マイグレーション名は下記のパターンに従うことができます。

*   (`/^(Create)(.*)/`) 指定したテーブルを作成します。
    
*   (`/^(Drop)(.*)/`) 指定したテーブルを削除します。フィールドの指定は無視されます。
    
*   (`/^(Add).*(?:To)(.*)/`) 指定したテーブルにカラム追加します。
    
*   (`/^(Remove).*(?:From)(.*)/`) 指定のテーブルのカラムを削除します。
    
*   (`/^(Alter)(.*)/`) 指定したテーブルを変更します。 CreateTable と AddField の別名。
    
*   (`/^(Alter).*(?:On)(.*)/`) 指定されたテーブルのフィールドを変更します。
    

マイグレーションの名前に `アンダースコアー_形式` を使用できます。例: create\_products

バージョン cakephp/migrations で追加: 1.5.2

マイグレーションファイル名のキャメルケースへの変換は [migrations プラグイン](https://github.com/cakephp/migrations/)
 の v1.5.2 に含まれます。 このプラグインのバージョンは、 CakePHP 3.1 以上のリリースで利用できます。 このプラグインのバージョン以前では、マイグレーション名はアンダースコアー形式です。 例: 20160121164955\_create\_products.php

警告

マイグレーション名は、マイグレーションのクラス名として使われます。そして、 クラス名はユニークでない場合、他のマイグレーションと衝突するかもしれません。この場合、後日、 名前を手動で上書きするか、単純にあなたが指定した名前に変更する必要があるかもしれません。

#### カラムの定義[¶](https://book.cakephp.org/migrations/3/ja/#id8 "この見出しへのパーマリンク")

コマンドラインでカラムを使用する場合には、次のようなパターンに従っている事を 覚えておくと便利です。

fieldName:fieldType?\[length\]:indexType:indexName

例えば、以下はメールアドレスのカラムを指定する方法です。

*   `email:string?`
    
*   `email:string:unique`
    
*   `email:string?[50]`
    
*   `email:string:unique:EMAIL_INDEX`
    
*   `email:string[120]:unique:EMAIL_INDEX`
    

fieldType の後のクエスチョンマークは、ヌルを許可するカラムを作成します。

`fieldType` のための `length` パラメーターは任意です。カッコの中に記述します。

フィールド名が `created` と `modified` 、それに `_at` サフィックス付きの 任意のフィールドなら、自動的に `datetime` 型が設定されます。

`Phinx` で一般的に利用可能なフィールドの型は次の通り:

*   string
    
*   text
    
*   integer
    
*   biginteger
    
*   float
    
*   decimal
    
*   datetime
    
*   timestamp
    
*   time
    
*   date
    
*   binary
    
*   boolean
    
*   uuid
    

未確定で無効な値のままのフィールド型を選ぶためのいくつかの発見的手法があります。 デフォルトのフィールド型は `string` です。

*   id: integer
    
*   created, modified, updated: datetime
    

### テーブルの作成[¶](https://book.cakephp.org/migrations/3/ja/#id9 "この見出しへのパーマリンク")

テーブルを作成するために `bake` が使えます。 :

bin/cake bake migration CreateProducts name:string description:text created modified

上記のコマンドラインは、よく似たマイグレーションファイルを生成します。

<?php
use Migrations\\AbstractMigration;

class CreateProducts extends AbstractMigration
{
    /\*\*
     \* Change Method.
     \*
     \* More information on this method is available here:
     \* https://book.cakephp.org/phinx/0/en/migrations.html#the-change-method
     \* @return void
     \*/
    public function change()
    {
        $table \= $this\->table('products');
        $table\->addColumn('name', 'string', \[\
            'default' \=> null,\
            'limit' \=> 255,\
            'null' \=> false,\
        \]);
        $table\->addColumn('description', 'text', \[\
            'default' \=> null,\
            'null' \=> false,\
        \]);
        $table\->addColumn('created', 'datetime', \[\
            'default' \=> null,\
            'null' \=> false,\
        \]);
        $table\->addColumn('modified', 'datetime', \[\
            'default' \=> null,\
            'null' \=> false,\
        \]);
        $table\->create();
    }
}

### 既存のテーブルにカラムを追加[¶](https://book.cakephp.org/migrations/3/ja/#id10 "この見出しへのパーマリンク")

もしコマンドラインのマイグレーション名が "AddXXXToYYY" といった 書式で、その後にカラム名と型が続けば、カラムの追加を行うコードを含んだ マイグレーションファイルが生成されます。 :

bin/cake bake migration AddPriceToProducts price:decimal

コマンドラインを実行すると下記のようなファイルが生成されます。

<?php
use Migrations\\AbstractMigration;

class AddPriceToProducts extends AbstractMigration
{
    public function change()
    {
        $table \= $this\->table('products');
        $table\->addColumn('price', 'decimal')
              \->update();
    }
}

### テーブルにインデックスとしてカラムを追加[¶](https://book.cakephp.org/migrations/3/ja/#id11 "この見出しへのパーマリンク")

カラムにインデックスを追加することも可能です。 :

bin/cake bake migration AddNameIndexToProducts name:string:index

このようなファイルが生成されます。

<?php
use Migrations\\AbstractMigration;

class AddNameIndexToProducts extends AbstractMigration
{
    public function change()
    {
        $table \= $this\->table('products');
        $table\->addColumn('name', 'string')
              \->addIndex(\['name'\])
              \->update();
    }
}

### フィールド長を指定[¶](https://book.cakephp.org/migrations/3/ja/#id12 "この見出しへのパーマリンク")

バージョン cakephp/migrations で追加: 1.4

もし、フィールド長を指定する必要がある場合、フィールドタイプにカギ括弧の中で指定できます。例:

bin/cake bake migration AddFullDescriptionToProducts full\_description:string\[60\]

上記のコマンドラインを実行すると生成されます。

<?php
use Migrations\\AbstractMigration;

class AddFullDescriptionToProducts extends AbstractMigration
{
    public function change()
    {
        $table \= $this\->table('products');
        $table\->addColumn('full\_description', 'string', \[\
            'default' \=> null,\
            'limit' \=> 60,\
            'null' \=> false,\
        \])
        \->update();
    }
}

長さが未指定の場合、いくつかのカラム型の長さは初期値が設定されます。

*   string: 255
    
*   integer: 11
    
*   biginteger: 20
    

### テーブルから列を変更する[¶](https://book.cakephp.org/migrations/3/ja/#id13 "この見出しへのパーマリンク")

同様に、移行名が「AlterXXXOnYYY」の形式の場合、コマンドラインを使用して、列を変更する移行を生成できます。

bin/cake bake migration AlterPriceOnProducts name:float

生成されます:

<?php
use Migrations\\AbstractMigration;

class AlterPriceFromProducts extends AbstractMigration
{
    public function change()
    {
        $table \= $this\->table('products');
        $table\->changeColumn('name', 'float');
        $table\->update();
    }
}

### テーブルからカラムを削除[¶](https://book.cakephp.org/migrations/3/ja/#id14 "この見出しへのパーマリンク")

もしマイグレーション名が "RemoveXXXFromYYY" であるなら、同様にコマンドラインを使用して、 カラム削除のマイグレーションファイルを生成することができます。 :

bin/cake bake migration RemovePriceFromProducts price

このようなファイルが生成されます。

<?php
use Migrations\\AbstractMigration;

class RemovePriceFromProducts extends AbstractMigration
{
    public function up()
    {
        $table \= $this\->table('products');
        $table\->removeColumn('price')
              \->save();
    }
}

注釈

removeColumn は不可逆ですので、 up メソッドの中で呼び出してください。 それに対する addColumn の呼び出しは、 down メソッドに追加してください。

### 既存のデータベースからマイグレーションファイルを作成する[¶](https://book.cakephp.org/migrations/3/ja/#id15 "この見出しへのパーマリンク")

もしあなたが既存のデータベースで、マイグレーションの使用を始めたい場合や、 あなたのアプリケーションのデータベースで初期状態のスキーマのバージョン管理を 行いたい場合、 `migration_snapshot` コマンドを実行します。 :

bin/cake bake migration\_snapshot Initial

これはデータベース内のすべてのテーブルの create 文を含んだ **YYYYMMDDHHMMSS\_Initial.php** と呼ばれるマイグレーションファイルを生成します。

デフォルトで、スナップショットは、 `default` 接続設定で定義されたデータベースに 接続することによって作成されます。 もし、異なるデータベースからスナップショットを bake する必要があるなら、 `--connection` オプションが使用できます。 :

bin/cake bake migration\_snapshot Initial \--connection my\_other\_connection

`--require-table` フラグを使用することによって対応するモデルクラスを定義したテーブルだけを 含まれることを確認することができます。 :

bin/cake bake migration\_snapshot Initial \--require-table

`--require-table` フラグを使用した時、シェルは、あなたのアプリケーションを通して `Table` クラスを見つけて、スナップショットのモデルテーブルのみ追加します。

プラグインのためのスナップショットを bake したい場合、同じロジックが暗黙的に適用されます。 そうするために、 `--plugin` オプションを使用する必要があります。 :

bin/cake bake migration\_snapshot Initial \--plugin MyPlugin

定義された `Table` オブジェクトモデルを持つテーブルだけプラグインのスナップショットに 追加されます。

注釈

プラグインのためのスナップショットを bake した時、マイグレーションファイルは、 あなたのプラグインの **config/Migrations** ディレクトリーに作成されます。

スナップショットを bake した時、phinx のログテーブルに自動的に追加されることに注意してください。

２つのデータベース間の状態の差分を生成する[¶](https://book.cakephp.org/migrations/3/ja/#id16 "この見出しへのパーマリンク")

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

バージョン cakephp/migrations で追加: 1.6.0

`migration_diff` の bake テンプレートを使用して２つのデータベースの状態の すべての差分をまとめたマイグレーションファイルを生成することができます。 そのためには、以下のコマンドを使用します。 :

bin/cake bake migration\_diff NameOfTheMigrations

現在のデータベースの状態からの比較のポイントを保持するために、migrations シェルは、 `migrate` もしくは `rollback` が呼ばれた後に "dump" ファイルを生成します。 ダンプファイルは、取得した時点でのあなたのデータベースの全スキーマの状態を含むファイルです。

一度ダンプファイルが生成されると、あなたのデータベース管理システムに直接行ったすべての変更は、 `bake migration_diff` コマンドが呼ばれた時に生成されたマイグレーションファイルに追加されます。

デフォルトでは、 `default` 接続設定に定義されたデータベースに接続することによって 差分が作成されます。もし、あなたが異なるデータソースから差分を bake する必要がある場合、 `--connection` オプションを使用できます。 :

bin/cake bake migration\_diff NameOfTheMigrations \--connection my\_other\_connection

もし、すでにマイグレーションの履歴を持つアプリケーション上で diff 機能を使用したい場合、 マニュアルで比較に使用するダンプファイルを作成する必要があります。 :

bin/cake migrations dump

データベースの状態は、あなたがダンプファイルを作成する前にマイグレーションを全て実行した状態と 同じでなければなりません。一度ダンプファイルが生成されると、あなたのデータベースの変更を始めて、 都合の良い時に `bake migration_diff` コマンドを使用することができます。

注釈

migrations シェルは、カラム名の変更は検知できません。

コマンド[¶](https://book.cakephp.org/migrations/3/ja/#id17 "この見出しへのパーマリンク")

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

### `migrate` : マイグレーションを適用する[¶](https://book.cakephp.org/migrations/3/ja/#migrate "この見出しへのパーマリンク")

マイグレーションファイルを生成したり記述したら、以下のコマンドを実行して 変更をデータベースに適用しましょう。 :

\# マイグレーションをすべて実行
bin/cake migrations migrate

\# 特定のバージョンに移行するためには、 \`\`--target\`\` オプション
\# （省略形は \`\`-t\`\` ）を使用します。
\# これはマイグレーションファイル名の前に付加されるタイムスタンプに対応しています。
bin/cake migrations migrate \-t 20150103081132

\# デフォルトで、マイグレーションファイルは、 \*\*config/Migrations\*\* ディレクトリーに
\# あります。 \`\`--source\`\` オプション (省略形は \`\`-s\`\`) を使用することで、
\# ディレクトリーを指定できます。
\# 次の例は、 \*\*config/Alternate\*\* ディレクトリー内でマイグレーションを実行します。
bin/cake migrations migrate \-s Alternate

\# \`\`--connection\`\` オプション (省略形は \`\`-c\`\`) を使用することで
\# \`\`default\`\` とは異なる接続でマイグレーションを実行できます。
bin/cake migrations migrate \-c my\_custom\_connection

\# マイグレーションは、プラグインのためにも実行できます。 \`\`--plugin\`\` オプション
\# (省略形は \`\`-p\`\`) を使用します。
bin/cake migrations migrate \-p MyAwesomePlugin

### `rollback` : マイグレーションを戻す[¶](https://book.cakephp.org/migrations/3/ja/#rollback "この見出しへのパーマリンク")

ロールバックコマンドは、このプラグインを実行する前の状態に戻すために使われます。 これは `migrate` コマンドの逆向きの動作をします。 :

\# あなたは \`\`rollback\`\` コマンドを使って以前のマイグレーション状態に戻すことができます。
bin/cake migrations rollback

\# また、特定のバージョンに戻すために、マイグレーションバージョン番号を引き渡すこともできます。
bin/cake migrations rollback \-t 20150103081132

`migrate` コマンドのように `--source` 、 `--connection` そして `--plugin` オプションが使用できます。

### `status` : マイグレーションのステータス[¶](https://book.cakephp.org/migrations/3/ja/#status "この見出しへのパーマリンク")

Status コマンドは、現在の状況とすべてのマイグレーションのリストを出力します。 あなたはマイグレーションが実行されたかを判断するために、このコマンドを使用することができます。 :

bin/cake migrations status

`--format` (省略形は `-f`) オプションを使用することで JSON 形式の文字列として結果を出力できます。 :

bin/cake migrations status \--format json

`migrate` コマンドのように `--source` 、 `--connection` そして `--plugin` オプションが使用できます。

### `mark_migrated` : マイグレーション済みとしてマーキングする[¶](https://book.cakephp.org/migrations/3/ja/#mark-migrated "この見出しへのパーマリンク")

バージョン 1.4.0 で追加.

時には、実際にはマイグレーションを実行せずにマークだけすることが便利な事もあります。 これを実行するためには、 `mark_migrated` コマンドを使用します。 コマンドは、他のコマンドとしてシームレスに動作します。

このコマンドを使用して、すべてのマイグレーションをマイグレーション済みとして マークすることができます。 :

bin/cake migrations mark\_migrated

また、 `--target` オプションを使用して、指定したバージョンに対して、 すべてマイグレーション済みとしてマークすることができます。 :

bin/cake migrations mark\_migrated \--target\=20151016204000

もし、指定したマイグレーションを処理中にマーク済みにしたくない場合、 `--exclude` フラグをつけて使用することができます。 :

bin/cake migrations mark\_migrated \--target\=20151016204000 \--exclude

最後に、指定したマイグレーションだけをマイグレーション済みとしてマークしたい場合、 `--only` フラグを使用できます。 :

bin/cake migrations mark\_migrated \--target\=20151016204000 \--only

`migrate` コマンドのように `--source` 、 `--connection` そして `--plugin` オプションが使用できます。

注釈

あなたが `cake bake migration_snapshot` コマンドでスナップショットを作成したとき、 自動的にマイグレーション済みとしてマーキングされてマイグレーションが作成されます。

バージョン 1.4.0 で非推奨: 以下のコマンドの使用方法は非推奨になりました。もし、あなたが 1.4.0 より前のバージョンの プラグインの場合のみに使用してください。

このコマンドは、引数としてマイグレーションバージョン番号を想定しています。 :

bin/cake migrations mark\_migrated 20150420082532

もし、すべてのマイグレーションをマイグレーション済みとしてマークしたい場合、 特別な値 `all` を使用できます。もし使用した場合、すべての見つかったマイグレーションを マイグレーション済みとしてマークします。 :

bin/cake migrations mark\_migrated all

### `seed` : データベースの初期データ投入[¶](https://book.cakephp.org/migrations/3/ja/#seed "この見出しへのパーマリンク")

1.5.5 より、データベースの初期データ投入のために `migrations` シェルが使用できます。 これは、 [Phinx ライブラリーの seed 機能](https://book.cakephp.org/phinx/0/en/seeding.html)
 を利用しています。デフォルトで、seed ファイルは、あなたのアプリケーションの `config/Seeds` ディレクトリーの中に置かれます。 [seed ファイル作成のための Phinx の命令](https://book.cakephp.org/phinx/0/en/seeding.html#creating-a-new-seed-class)
 を確認してください。

マイグレーションに関して、 seed ファイルのための `bake` インターフェースが提供されます。 :

\# これは、あなたのアプリケーションの config/Seeds ディレクトリー内に ArticlesSeed.php を作成します。
\# デフォルトでは、変換対象の seed は、 "tableized" バージョンの seed ファイル名です。
bin/cake bake seed Articles

\# \`\`--table\`\` オプションを使用することで seed ファイルに変換するテーブル名を指定します。
bin/cake bake seed Articles \--table my\_articles\_table

\# bake するプラグインを指定できます。
bin/cake bake seed Articles \--plugin PluginName

\# シーダーの生成時に別の接続を指定できます。
bin/cake bake seed Articles \--connection connection

バージョン cakephp/migrations で追加: 1.6.4

オプションの `--data`, `--limit` そして `--fields` は、 データベースからデータをエクスポートするために追加されました。

1.6.4 から、 `bake seed` コマンドは、 `--data` フラグを使用することによって、 データベースからエクスポートされたデータを元に seed ファイルを作成することができます。 :

bin/cake bake seed \--data Articles

デフォルトでは、テーブル内にある行を全てエクスポートします。 `--limit` オプションを 使用することによって、エクスポートされる行の数を制限できます。 :

\# 10 行のみエクスポート
bin/cake bake seed \--data \--limit 10 Articles

もし、seed ファイルの中にテーブルから選択したフィールドのみを含めたい場合、 `--fields` オプションが使用できます。そのオプションは、 フィールドのリストをカンマ区切りの値の文字列として含めます。 :

\# \`id\`, \`title\` そして \`excerpt\` フィールドのみをエクスポート
bin/cake bake seed \--data \--fields id,title,excerpt Articles

Tip

もちろん、同じコマンド呼び出し中に `--limit` と `--fields` オプションの両方が利用できます。

データベースの初期データ投入のために、 `seed` サブコマンドが使用できます。 :

\# パラメーターなしの seed サブコマンドは、対象のディレクトリーのアルファベット順で、
\# すべての利用可能なシーダーを実行します。
bin/cake migrations seed

\# \`--seed\` オプションを使用して実行するための一つだけシーダーを指定できます。
bin/cake migrations seed \--seed ArticlesSeed

\# 別のディレクトリーでシーダーを実行できます。
bin/cake migrations seed \--source AlternativeSeeds

\# プラグインのシーダーを実行できます
bin/cake migrations seed \--plugin PluginName

\# 指定したコネクションでシーダーを実行できます
bin/cake migrations seed \--connection connection

マイグレーションとは対照的にシーダーは追跡されないことに注意してください。 それは、同じシーダーは、複数回適用することができることを意味します。

#### シーダーから別のシーダーの呼び出し[¶](https://book.cakephp.org/migrations/3/ja/#id18 "この見出しへのパーマリンク")

バージョン cakephp/migrations で追加: 1.6.2

たいてい初期データ投入時は、データの挿入する順番は、規約違反しないように遵守しなければなりません。 デフォルトでは、アルファベット順でシーダーが実行されますが、独自にシーダーの実行順を定義するために `\Migrations\AbstractSeed::call()` メソッドが利用できます。

use Migrations\\AbstractSeed;

class DatabaseSeed extends AbstractSeed
{
    public function run(): void
    {
        $this\->call('AnotherSeed');
        $this\->call('YetAnotherSeed');

        // プラグインからシーダーを呼ぶためにプラグインドット記法が使えます
        $this\->call('PluginName.FromPluginSeed');
    }
}

注釈

もし、 `call()` メソッドを使いたい場合、Migrations プラグインの `AbstractSeed` クラスを継承していることを確認してください。このクラスは、リリース 1.6.2 で追加されました。

### `dump` : 差分を bake する機能のためのダンプファイルの生成[¶](https://book.cakephp.org/migrations/3/ja/#dump-bake "この見出しへのパーマリンク")

dump コマンドは、 `migration_diff` の bake テンプレートで使用するファイルを作成します。 :

bin/cake migrations dump

各生成されたダンプファイルは、生成元の接続固有のものです（そして、そのようにサフィックスされます）。 これは、アプリケーションが、異なるデータベースベンダーの複数のデータベースを扱う場合、 `bake migration_diff` コマンドで正しく差分を算出することができます。

ダンプファイルは、マイグレーションファイルと同じディレクトリーに作成されます。

`migrate` コマンドのように `--source` 、 `--connection` そして `--plugin` オプションが使用できます。

プラグイン内のマイグレーションファイルを使う[¶](https://book.cakephp.org/migrations/3/ja/#id19 "この見出しへのパーマリンク")

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

プラグインはマイグレーションファイルも提供することができます。 これはプラグインの移植性とインストールの容易さを高め、配布しやすくなるように意図されています。 Migrations プラグインの全てのコマンドは、プラグイン関連のマイグレーションを行うための `--plugin` か `-p` オプションをサポートしています。 :

bin/cake migrations status \-p PluginName

bin/cake migrations migrate \-p PluginName

非シェルの環境でマイグレーションを実行する[¶](https://book.cakephp.org/migrations/3/ja/#id20 "この見出しへのパーマリンク")

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

バージョン cakephp/migrations で追加: 1.2.0

migrations プラグインのバージョン 1.2 から、非シェル環境でも app から直接 `Migrations` クラスを使ってマイグレーションを実行できるようになりました。 これは CMS のプラグインインストーラーを作る時などに便利です。 `Migrations` クラスを使用すると、マイグレーションシェルから下記のコマンドを 実行することができます。:

*   migrate
    
*   rollback
    
*   markMigrated
    
*   status
    
*   seed
    

それぞれのコマンドは `Migrations` クラスのメソッドとして実装されています。

使い方は以下の通りです。

use Migrations\\Migrations;

$migrations \= new Migrations();

// 全てのマイグレーションバージョンとそのステータスの配列を返します。
$status \= $migrations\->status();

// 成功した場合、 true を返し、エラーが発生した場合、例外が投げられます。
$migrate \= $migrations\->migrate();

// 成功した場合、 true を返し、エラーが発生した場合、例外が投げられます。
$rollback \= $migrations\->rollback();

// 成功した場合、 true を返し、エラーが発生した場合、例外が投げられます。
$markMigrated \= $migrations\->markMigrated(20150804222900);

// 成功した場合、 true を返し、エラーが発生した場合、例外が投げられます。
$seeded \= $migrations\->seed();

メソッドはコマンドラインのオプションと同じパラメーター配列を受け取ります。

use Migrations\\Migrations;

$migrations \= new Migrations();

// 全てのマイグレーションバージョンとそのステータスの配列を返す
$status \= $migrations\->status(\['connection' \=> 'custom', 'source' \=> 'MyMigrationsFolder'\]);

あなたはシェルコマンドのように任意のオプションを引き渡すことができます。 唯一の例外は `markMigrated` コマンドで、第１引数にはマイグレーション済みとして マーキングしたいマイグレーションバージョン番号を渡し、第２引数にパラメーターの配列を 渡します。

必要に応じて、クラスのコンストラクターでこれらのパラメーターを引き渡すことができます。 それはデフォルトとして使用され、それぞれのメソッド呼び出しの時に引き渡されることを 防止します。

use Migrations\\Migrations;

$migrations \= new Migrations(\['connection' \=> 'custom', 'source' \=> 'MyMigrationsFolder'\]);

// 以下のすべての呼び出しは、マイグレーションクラスのコンストラクターに渡されたパラメーターを使用して行われます
$status \= $migrations\->status();
$migrate \= $migrations\->migrate();

個別の呼び出しでデフォルトのパラメーターを上書きしたい場合は、メソッド呼び出し時に引き渡します。

use Migrations\\Migrations;

$migrations \= new Migrations(\['connection' \=> 'custom', 'source' \=> 'MyMigrationsFolder'\]);

// この呼び出しでは "custom" コネクションを使用します。
$status \= $migrations\->status();
// こちらでは "default" コネクションを使用します。
$migrate \= $migrations\->migrate(\['connection' \=> 'default'\]);

小技と裏技[¶](https://book.cakephp.org/migrations/3/ja/#id21 "この見出しへのパーマリンク")

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

### 主キーをカスタマイズする[¶](https://book.cakephp.org/migrations/3/ja/#id22 "この見出しへのパーマリンク")

あなたがデータベースに新しいテーブルを作成する時、 `id` を主キーとして 自動生成したくない場合、 `table()` メソッドの第２引数を使うことができます。

<?php
use Migrations\\AbstractMigration;

class CreateProductsTable extends AbstractMigration
{
    public function change()
    {
        $table \= $this\->table('products', \['id' \=> false, 'primary\_key' \=> \['id'\]\]);
        $table
              \->addColumn('id', 'uuid')
              \->addColumn('name', 'string')
              \->addColumn('description', 'text')
              \->create();
    }
}

上記の例では、 `CHAR(36)` の `id` というカラムを主キーとして作成します。

注釈

独自の主キーをコマンドラインで指定した時、id フィールドの中の主キーとして注意してください。 そうしなければ、id フィールドが重複してエラーになります。例:

bin/cake bake migration CreateProducts id:uuid:primary name:string description:text created modified

さらに、Migrations 1.3 以降では 主キーに対処するための新しい方法が導入されました。 これを行うには、あなたのマイグレーションクラスは新しい `Migrations\AbstractMigration` クラスを継承する必要があります。 あなたは Migration クラスの `autoId` プロパティーに `false` を設定することで、 自動的な `id` カラムの生成をオフにすることができます。 あなたは手動で主キーカラムを作成し、テーブル宣言に追加する必要があります。

<?php
use Migrations\\AbstractMigration;

class CreateProductsTable extends AbstractMigration
{

    public $autoId \= false;

    public function up()
    {
        $table \= $this\->table('products');
        $table
            \->addColumn('id', 'integer', \[\
                'autoIncrement' \=> true,\
                'limit' \=> 11\
            \])
            \->addPrimaryKey('id')
            \->addColumn('name', 'string')
            \->addColumn('description', 'text')
            \->create();
    }
}

主キーを扱うこれまでの方法と比較すると、この方法は、unsigned や not や limit や comment など さらに多くの主キーの定義を操作することができるようになっています。

Bake で生成されたマイグレーションファイルとスナップショットは、この新しい方法を 必要に応じて使用します。

警告

主キーの操作ができるのは、テーブル作成時のみです。これはプラグインがサポートしている いくつかのデータベースサーバーの制限によるものです。

### 照合順序[¶](https://book.cakephp.org/migrations/3/ja/#id23 "この見出しへのパーマリンク")

もしデータベースのデフォルトとは別の照合順序を持つテーブルを作成する必要がある場合は、 `table()` メソッドのオプションとして定義することができます。:

<?php
use Migrations\\AbstractMigration;

class CreateCategoriesTable extends AbstractMigration
{
    public function change()
    {
        $table \= $this
            \->table('categories', \[\
                'collation' \=> 'latin1\_german1\_ci'\
            \])
            \->addColumn('title', 'string', \[\
                'default' \=> null,\
                'limit' \=> 255,\
                'null' \=> false,\
            \])
            \->create();
    }
}

ですが、これはテーブル作成時にしかできず、既存のテーブルに対してカラムを追加する時に テーブルやデータベースと異なる照合順序を指定する方法がないことに注意してください。 ただ `MySQL` と `SqlServer` だけはこの設定キーをサポートしています。

### カラム名の更新と Table オブジェクトの使用[¶](https://book.cakephp.org/migrations/3/ja/#table "この見出しへのパーマリンク")

カラムのリネームや移動とともに、あなたのデータベースから値を操作するために CakePHP ORM Table オブジェクトを使用している場合、 `update()` を呼んだ後に Table オブジェクトの新しいインスタンスを作成できることを確かめてください。 インスタンス上の Table オブジェクトに反映し保存されたスキーマをリフレッシュするために Table オブジェクトのレジストリーは、 `update()` が呼ばれた後にクリアされます。

### マイグレーションとデプロイメント[¶](https://book.cakephp.org/migrations/3/ja/#id24 "この見出しへのパーマリンク")

もし、アプリケーションをデプロイする時にプラグインを使用する場合、 テーブルのカラムメタデータを更新するように、必ず ORM キャッシュをクリアしてください。 そうしなければ、それらの新しいカラムの操作を実行する時に、カラムが存在しないエラーになります。 CakePHP コアは、この操作を行うために使用できる [スキーマキャッシュシェル](https://book.cakephp.org/3.0/ja/console-and-shells/schema-cache.html)
 を含みます。 :

// 3.6.0 より前の場合、orm\_cache を使用
bin/cake schema\_cache clear

このシェルについてもっと知りたい場合、クックブックの [スキーマキャッシュシェル](https://book.cakephp.org/3.0/ja/console-and-shells/schema-cache.html)
 セクションをご覧ください。

### テーブルのリネーム[¶](https://book.cakephp.org/migrations/3/ja/#id25 "この見出しへのパーマリンク")

プラグインは、 `rename()` メソッドを使用することでテーブルのリネームができます。 あなたのマイグレーションファイルの中で、以下のように記述できます。

public function up()
{
    $this\->table('old\_table\_name')
        \->rename('new\_table\_name')
        \->save();
}

### `schema.lock` ファイル生成のスキップ[¶](https://book.cakephp.org/migrations/3/ja/#schema-lock "この見出しへのパーマリンク")

バージョン cakephp/migrations で追加: 1.6.5

diff 機能を動作させるために、 **.lock** ファイルは、migrate、rollback または スナップショットの bake の度に生成され、指定された時点でのデータベーススキーマの状態を追跡します。 例えば本番環境上にデプロイするときなど、前述のコマンドに `--no-lock` オプションを使用することによって、このファイルの生成をスキップすることができます。 :

bin/cake migrations migrate \--no-lock

bin/cake migrations rollback \--no-lock

bin/cake bake migration\_snapshot MyMigration \--no-lock

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# Migrations - 2.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/migrations/edit/2.x/docs/ja/index.rst)

[](https://book.cakephp.org/migrations/2/ja/#page-contents)

### Page Contents

*   [Migrations](https://book.cakephp.org/migrations/2/ja/#)
    *   [インストール](https://book.cakephp.org/migrations/2/ja/#id1)
        
    *   [概要](https://book.cakephp.org/migrations/2/ja/#id2)
        
    *   [マイグレーションファイルの作成](https://book.cakephp.org/migrations/2/ja/#id3)
        *   [シンタックス](https://book.cakephp.org/migrations/2/ja/#id5)
            *   [マイグレーションファイル名](https://book.cakephp.org/migrations/2/ja/#id6)
                
            *   [カラムの定義](https://book.cakephp.org/migrations/2/ja/#id8)
                
        *   [テーブルの作成](https://book.cakephp.org/migrations/2/ja/#id9)
            
        *   [既存のテーブルにカラムを追加](https://book.cakephp.org/migrations/2/ja/#id10)
            
        *   [テーブルにインデックスとしてカラムを追加](https://book.cakephp.org/migrations/2/ja/#id11)
            
        *   [フィールド長を指定](https://book.cakephp.org/migrations/2/ja/#id12)
            
        *   [テーブルから列を変更する](https://book.cakephp.org/migrations/2/ja/#id13)
            
        *   [テーブルからカラムを削除](https://book.cakephp.org/migrations/2/ja/#id14)
            
        *   [既存のデータベースからマイグレーションファイルを作成する](https://book.cakephp.org/migrations/2/ja/#id15)
            
    *   [２つのデータベース間の状態の差分を生成する](https://book.cakephp.org/migrations/2/ja/#id16)
        
    *   [コマンド](https://book.cakephp.org/migrations/2/ja/#id17)
        *   [`migrate` : マイグレーションを適用する](https://book.cakephp.org/migrations/2/ja/#migrate)
            
        *   [`rollback` : マイグレーションを戻す](https://book.cakephp.org/migrations/2/ja/#rollback)
            
        *   [`status` : マイグレーションのステータス](https://book.cakephp.org/migrations/2/ja/#status)
            
        *   [`mark_migrated` : マイグレーション済みとしてマーキングする](https://book.cakephp.org/migrations/2/ja/#mark-migrated)
            
        *   [`seed` : データベースの初期データ投入](https://book.cakephp.org/migrations/2/ja/#seed)
            *   [シーダーから別のシーダーの呼び出し](https://book.cakephp.org/migrations/2/ja/#id18)
                
        *   [`dump` : 差分を bake する機能のためのダンプファイルの生成](https://book.cakephp.org/migrations/2/ja/#dump-bake)
            
    *   [プラグイン内のマイグレーションファイルを使う](https://book.cakephp.org/migrations/2/ja/#id19)
        
    *   [非シェルの環境でマイグレーションを実行する](https://book.cakephp.org/migrations/2/ja/#id20)
        
    *   [小技と裏技](https://book.cakephp.org/migrations/2/ja/#id21)
        *   [主キーをカスタマイズする](https://book.cakephp.org/migrations/2/ja/#id22)
            
        *   [照合順序](https://book.cakephp.org/migrations/2/ja/#id23)
            
        *   [カラム名の更新と Table オブジェクトの使用](https://book.cakephp.org/migrations/2/ja/#table)
            
        *   [マイグレーションとデプロイメント](https://book.cakephp.org/migrations/2/ja/#id24)
            
        *   [テーブルのリネーム](https://book.cakephp.org/migrations/2/ja/#id25)
            
        *   [`schema.lock` ファイル生成のスキップ](https://book.cakephp.org/migrations/2/ja/#schema-lock)
            

Migrations[¶](https://book.cakephp.org/migrations/2/ja/#migrations "このヘッドラインへのパーマリンク")

=======================================================================================

マイグレーションは、バージョン管理システムを使用して追跡することができる PHP ファイルを 記述することによって、あなたのデータベースのスキーマ変更を行うための、コアチームによって サポートされているプラグインです。

それはあなたが時間をかけてあなたのデータベーステーブルを進化させることができます。 スキーマ変更の SQL を書く代わりに、このプラグインでは、直観的にデータベースの変更を 実現するための手段を使用することができます。

このプラグインは、データベースマイグレーションライブラリーの [Phinx](https://phinx.org/)
 のラッパーです。

インストール[¶](https://book.cakephp.org/migrations/2/ja/#id1 "このヘッドラインへのパーマリンク")

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

初期状態で Migrations は、デフォルトのアプリケーションの雛形と一緒にインストールされます。 もしあなたがそれを削除して再インストールしたい場合は、（composer.json ファイルが 配置されている）アプリケーションルートディレクトリーから次のコマンドを実行します。

php composer.phar require cakephp/migrations "@stable"

\# また、composer がグローバルにインストールされていた場合は、

composer require cakephp/migrations "@stable"

このプラグインを使用するためには、あなたは、アプリケーションの **config/bootstrap.php** ファイルでロードする必要があります。あなたの **config/bootstrap.php** からプラグインを ロード・アンロードするために [CakePHP の Plugin シェル](https://book.cakephp.org/3.0/ja/console-and-shells/plugin-shell.html)
 が利用できます。 :

bin/cake plugin load Migrations

もしくは、あなたの **src/Application.php** ファイルを編集し、次の行を追加することで ロードすることができます。

$this\->addPlugin('Migrations');

// 3.6.0 より前は Plugin::load() を使用する必要があります

また、 [データベース設定](https://book.cakephp.org/3.0/en/orm/database-basics.html#database-configuration)
 の項で説明したように、 あなたの **config/app.php** ファイル内のデフォルトのデータベース構成を設定する必要が あります。

概要[¶](https://book.cakephp.org/migrations/2/ja/#id2 "このヘッドラインへのパーマリンク")

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

マイグレーションは、基本的にはデータベースの変更の操作を PHP ファイルで表します。 マイグレーションファイルはテーブルを作成し、カラムの追加や削除、インデックスの作成や データの作成さえ可能です。

ここにマイグレーションの例があります。

<?php
use Migrations\\AbstractMigration;

class CreateProducts extends AbstractMigration
{
    /\*\*
     \* Change Method.
     \*
     \* More information on this method is available here:
     \* https://book.cakephp.org/phinx/0/en/migrations.html#the-change-method
     \* @return void
     \*/
    public function change()
    {
        $table \= $this\->table('products');
        $table\->addColumn('name', 'string', \[\
            'default' \=> null,\
            'limit' \=> 255,\
            'null' \=> false,\
        \]);
        $table\->addColumn('description', 'text', \[\
            'default' \=> null,\
            'null' \=> false,\
        \]);
        $table\->addColumn('created', 'datetime', \[\
            'default' \=> null,\
            'null' \=> false,\
        \]);
        $table\->addColumn('modified', 'datetime', \[\
            'default' \=> null,\
            'null' \=> false,\
        \]);
        $table\->create();
    }
}

マイグレーションは、データベースに `products` という名前のテーブルを追加します。 以下のカラムが定義します。

*   `id` カラムの型は、主キーの `integer`
    
*   `name` カラムの型は `string`
    
*   `description` カラムの型は `text`
    
*   `created` カラムの型は `datetime`
    
*   `modified` カラムの型は `datetime`
    

ちなみに

主キーのカラム名 `id` は、 **暗黙のうちに** 追加されます。

注釈

このファイルは変更を **適用後** にデータベースがどのようになるかを記述していることに 注意してください。この時点でデータベースに `products` テーブルは存在せず、 `products` テーブルを作って項目を追加することができるのと同様に、マイグレーションを `rollback` すればテーブルが消えてしまいます。

マイグレーションファイルを **config/Migrations** フォルダーに作成したら、下記の `migrations` コマンドを実行することでデータベースにテーブルを作成することがでます。 :

bin/cake migrations migrate

以下の `migrations` コマンドは、 `rollback` を実行するとあなたのデータベースから テーブルが削除されます。 :

bin/cake migrations rollback

マイグレーションファイルの作成[¶](https://book.cakephp.org/migrations/2/ja/#id3 "このヘッドラインへのパーマリンク")

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

マイグレーションファイルは、あなたのアプリケーションの **config/Migration** ディレクトリーに配置します。マイグレーションファイルの名前には、先頭に **YYYYMMDDHHMMSS\_MigrationName.php** というように作成した日付を付けます。 以下がマイグレーションファイルの例です。

*   20160121163850\_CreateProducts.php
    
*   20160210133047\_AddRatingToProducts.php
    

マイグレーションファイルを作成する最も簡単な方法は `bake` CLI コマンドを使用することです。

マイグレーションファイルに記述可能なメソッドの一覧については、オフィシャルの [Phinx ドキュメント](https://book.cakephp.org/phinx/0/en/migrations.html)
 をご覧ください。

注釈

`bake` オプションを使用する場合、もし望むなら実行する前にマイグレーションを修正できます。

### シンタックス[¶](https://book.cakephp.org/migrations/2/ja/#id5 "このヘッドラインへのパーマリンク")

以下の `bake` コマンドは、 `products` テーブルを追加するためのマイグレーションファイルを 作成します。 :

bin/cake bake migration CreateProducts name:string description:text created modified

あなたのデータベースにテーブルの作成、カラムの追加などをするために `bake` を使用する場合、 一般に以下の２点を指定します。

*   あなたが生成するマイグレーションの名前 (例えば、 `CreateProducts`)
    
*   マイグレーションで追加や削除を行うテーブルのカラム (例えば、 `name:string description:text created modified`)
    

規約のために、すべてのスキーマの変更がこれらのシェルコマンドで動作するわけではありません。

さらに、実行内容を完全に制御したいのであれば、空のマイグレーションファイルを 作る事ができます。

.. code\-block:: bash

> bin/cake migrations create MyCustomMigration

#### マイグレーションファイル名[¶](https://book.cakephp.org/migrations/2/ja/#id6 "このヘッドラインへのパーマリンク")

マイグレーション名は下記のパターンに従うことができます。

*   (`/^(Create)(.*)/`) 指定したテーブルを作成します。
    
*   (`/^(Drop)(.*)/`) 指定したテーブルを削除します。フィールドの指定は無視されます。
    
*   (`/^(Add).*(?:To)(.*)/`) 指定したテーブルにカラム追加します。
    
*   (`/^(Remove).*(?:From)(.*)/`) 指定のテーブルのカラムを削除します。
    
*   (`/^(Alter)(.*)/`) 指定したテーブルを変更します。 CreateTable と AddField の別名。
    
*   (`/^(Alter).*(?:On)(.*)/`) 指定されたテーブルのフィールドを変更します。
    

マイグレーションの名前に `アンダースコアー_形式` を使用できます。例: create\_products

バージョン cakephp/migrations で追加: 1.5.2

マイグレーションファイル名のキャメルケースへの変換は [migrations プラグイン](https://github.com/cakephp/migrations/)
 の v1.5.2 に含まれます。 このプラグインのバージョンは、 CakePHP 3.1 以上のリリースで利用できます。 このプラグインのバージョン以前では、マイグレーション名はアンダースコアー形式です。 例: 20160121164955\_create\_products.php

警告

マイグレーション名は、マイグレーションのクラス名として使われます。そして、 クラス名はユニークでない場合、他のマイグレーションと衝突するかもしれません。この場合、後日、 名前を手動で上書きするか、単純にあなたが指定した名前に変更する必要があるかもしれません。

#### カラムの定義[¶](https://book.cakephp.org/migrations/2/ja/#id8 "このヘッドラインへのパーマリンク")

コマンドラインでカラムを使用する場合には、次のようなパターンに従っている事を 覚えておくと便利です。

fieldName:fieldType?\[length\]:indexType:indexName

例えば、以下はメールアドレスのカラムを指定する方法です。

*   `email:string?`
    
*   `email:string:unique`
    
*   `email:string?[50]`
    
*   `email:string:unique:EMAIL_INDEX`
    
*   `email:string[120]:unique:EMAIL_INDEX`
    

fieldType の後のクエスチョンマークは、ヌルを許可するカラムを作成します。

`fieldType` のための `length` パラメーターは任意です。カッコの中に記述します。

フィールド名が `created` と `modified` 、それに `_at` サフィックス付きの 任意のフィールドなら、自動的に `datetime` 型が設定されます。

`Phinx` で一般的に利用可能なフィールドの型は次の通り:

*   string
    
*   text
    
*   integer
    
*   biginteger
    
*   float
    
*   decimal
    
*   datetime
    
*   timestamp
    
*   time
    
*   date
    
*   binary
    
*   boolean
    
*   uuid
    

未確定で無効な値のままのフィールド型を選ぶためのいくつかの発見的手法があります。 デフォルトのフィールド型は `string` です。

*   id: integer
    
*   created, modified, updated: datetime
    

### テーブルの作成[¶](https://book.cakephp.org/migrations/2/ja/#id9 "このヘッドラインへのパーマリンク")

テーブルを作成するために `bake` が使えます。 :

bin/cake bake migration CreateProducts name:string description:text created modified

上記のコマンドラインは、よく似たマイグレーションファイルを生成します。

<?php
use Migrations\\AbstractMigration;

class CreateProducts extends AbstractMigration
{
    /\*\*
     \* Change Method.
     \*
     \* More information on this method is available here:
     \* https://book.cakephp.org/phinx/0/en/migrations.html#the-change-method
     \* @return void
     \*/
    public function change()
    {
        $table \= $this\->table('products');
        $table\->addColumn('name', 'string', \[\
            'default' \=> null,\
            'limit' \=> 255,\
            'null' \=> false,\
        \]);
        $table\->addColumn('description', 'text', \[\
            'default' \=> null,\
            'null' \=> false,\
        \]);
        $table\->addColumn('created', 'datetime', \[\
            'default' \=> null,\
            'null' \=> false,\
        \]);
        $table\->addColumn('modified', 'datetime', \[\
            'default' \=> null,\
            'null' \=> false,\
        \]);
        $table\->create();
    }
}

### 既存のテーブルにカラムを追加[¶](https://book.cakephp.org/migrations/2/ja/#id10 "このヘッドラインへのパーマリンク")

もしコマンドラインのマイグレーション名が "AddXXXToYYY" といった 書式で、その後にカラム名と型が続けば、カラムの追加を行うコードを含んだ マイグレーションファイルが生成されます。 :

bin/cake bake migration AddPriceToProducts price:decimal

コマンドラインを実行すると下記のようなファイルが生成されます。

<?php
use Migrations\\AbstractMigration;

class AddPriceToProducts extends AbstractMigration
{
    public function change()
    {
        $table \= $this\->table('products');
        $table\->addColumn('price', 'decimal')
              \->update();
    }
}

### テーブルにインデックスとしてカラムを追加[¶](https://book.cakephp.org/migrations/2/ja/#id11 "このヘッドラインへのパーマリンク")

カラムにインデックスを追加することも可能です。 :

bin/cake bake migration AddNameIndexToProducts name:string:index

このようなファイルが生成されます。

<?php
use Migrations\\AbstractMigration;

class AddNameIndexToProducts extends AbstractMigration
{
    public function change()
    {
        $table \= $this\->table('products');
        $table\->addColumn('name', 'string')
              \->addIndex(\['name'\])
              \->update();
    }
}

### フィールド長を指定[¶](https://book.cakephp.org/migrations/2/ja/#id12 "このヘッドラインへのパーマリンク")

バージョン cakephp/migrations で追加: 1.4

もし、フィールド長を指定する必要がある場合、フィールドタイプにカギ括弧の中で指定できます。例:

bin/cake bake migration AddFullDescriptionToProducts full\_description:string\[60\]

上記のコマンドラインを実行すると生成されます。

<?php
use Migrations\\AbstractMigration;

class AddFullDescriptionToProducts extends AbstractMigration
{
    public function change()
    {
        $table \= $this\->table('products');
        $table\->addColumn('full\_description', 'string', \[\
            'default' \=> null,\
            'limit' \=> 60,\
            'null' \=> false,\
        \])
        \->update();
    }
}

長さが未指定の場合、いくつかのカラム型の長さは初期値が設定されます。

*   string: 255
    
*   integer: 11
    
*   biginteger: 20
    

### テーブルから列を変更する[¶](https://book.cakephp.org/migrations/2/ja/#id13 "このヘッドラインへのパーマリンク")

同様に、移行名が「AlterXXXOnYYY」の形式の場合、コマンドラインを使用して、列を変更する移行を生成できます。

bin/cake bake migration AlterPriceOnProducts name:float

生成されます:

<?php
use Migrations\\AbstractMigration;

class AlterPriceFromProducts extends AbstractMigration
{
    public function change()
    {
        $table \= $this\->table('products');
        $table\->changeColumn('name', 'float');
        $table\->update();
    }
}

### テーブルからカラムを削除[¶](https://book.cakephp.org/migrations/2/ja/#id14 "このヘッドラインへのパーマリンク")

もしマイグレーション名が "RemoveXXXFromYYY" であるなら、同様にコマンドラインを使用して、 カラム削除のマイグレーションファイルを生成することができます。 :

bin/cake bake migration RemovePriceFromProducts price

このようなファイルが生成されます。

<?php
use Migrations\\AbstractMigration;

class RemovePriceFromProducts extends AbstractMigration
{
    public function up()
    {
        $table \= $this\->table('products');
        $table\->removeColumn('price')
              \->save();
    }
}

注釈

removeColumn は不可逆ですので、 up メソッドの中で呼び出してください。 それに対する addColumn の呼び出しは、 down メソッドに追加してください。

### 既存のデータベースからマイグレーションファイルを作成する[¶](https://book.cakephp.org/migrations/2/ja/#id15 "このヘッドラインへのパーマリンク")

もしあなたが既存のデータベースで、マイグレーションの使用を始めたい場合や、 あなたのアプリケーションのデータベースで初期状態のスキーマのバージョン管理を 行いたい場合、 `migration_snapshot` コマンドを実行します。 :

bin/cake bake migration\_snapshot Initial

これはデータベース内のすべてのテーブルの create 文を含んだ **YYYYMMDDHHMMSS\_Initial.php** と呼ばれるマイグレーションファイルを生成します。

デフォルトで、スナップショットは、 `default` 接続設定で定義されたデータベースに 接続することによって作成されます。 もし、異なるデータベースからスナップショットを bake する必要があるなら、 `--connection` オプションが使用できます。 :

bin/cake bake migration\_snapshot Initial --connection my\_other\_connection

`--require-table` フラグを使用することによって対応するモデルクラスを定義したテーブルだけを 含まれることを確認することができます。 :

bin/cake bake migration\_snapshot Initial --require-table

`--require-table` フラグを使用した時、シェルは、あなたのアプリケーションを通して `Table` クラスを見つけて、スナップショットのモデルテーブルのみ追加します。

プラグインのためのスナップショットを bake したい場合、同じロジックが暗黙的に適用されます。 そうするために、 `--plugin` オプションを使用する必要があります。 :

bin/cake bake migration\_snapshot Initial --plugin MyPlugin

定義された `Table` オブジェクトモデルを持つテーブルだけプラグインのスナップショットに 追加されます。

注釈

プラグインのためのスナップショットを bake した時、マイグレーションファイルは、 あなたのプラグインの **config/Migrations** ディレクトリーに作成されます。

スナップショットを bake した時、phinx のログテーブルに自動的に追加されることに注意してください。

２つのデータベース間の状態の差分を生成する[¶](https://book.cakephp.org/migrations/2/ja/#id16 "このヘッドラインへのパーマリンク")

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

バージョン cakephp/migrations で追加: 1.6.0

`migration_diff` の bake テンプレートを使用して２つのデータベースの状態の すべての差分をまとめたマイグレーションファイルを生成することができます。 そのためには、以下のコマンドを使用します。 :

bin/cake bake migration\_diff NameOfTheMigrations

現在のデータベースの状態からの比較のポイントを保持するために、migrations シェルは、 `migrate` もしくは `rollback` が呼ばれた後に "dump" ファイルを生成します。 ダンプファイルは、取得した時点でのあなたのデータベースの全スキーマの状態を含むファイルです。

一度ダンプファイルが生成されると、あなたのデータベース管理システムに直接行ったすべての変更は、 `bake migration_diff` コマンドが呼ばれた時に生成されたマイグレーションファイルに追加されます。

デフォルトでは、 `default` 接続設定に定義されたデータベースに接続することによって 差分が作成されます。もし、あなたが異なるデータソースから差分を bake する必要がある場合、 `--connection` オプションを使用できます。 :

bin/cake bake migration\_diff NameOfTheMigrations --connection my\_other\_connection

もし、すでにマイグレーションの履歴を持つアプリケーション上で diff 機能を使用したい場合、 マニュアルで比較に使用するダンプファイルを作成する必要があります。 :

bin/cake migrations dump

データベースの状態は、あなたがダンプファイルを作成する前にマイグレーションを全て実行した状態と 同じでなければなりません。一度ダンプファイルが生成されると、あなたのデータベースの変更を始めて、 都合の良い時に `bake migration_diff` コマンドを使用することができます。

注釈

migrations シェルは、カラム名の変更は検知できません。

コマンド[¶](https://book.cakephp.org/migrations/2/ja/#id17 "このヘッドラインへのパーマリンク")

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

### `migrate` : マイグレーションを適用する[¶](https://book.cakephp.org/migrations/2/ja/#migrate "このヘッドラインへのパーマリンク")

マイグレーションファイルを生成したり記述したら、以下のコマンドを実行して 変更をデータベースに適用しましょう。 :

\# マイグレーションをすべて実行
bin/cake migrations migrate

\# 特定のバージョンに移行するためには、 \`\`--target\`\` オプション
\# （省略形は \`\`-t\`\` ）を使用します。
\# これはマイグレーションファイル名の前に付加されるタイムスタンプに対応しています。
bin/cake migrations migrate -t 20150103081132

\# デフォルトで、マイグレーションファイルは、 \*\*config/Migrations\*\* ディレクトリーに
\# あります。 \`\`--source\`\` オプション (省略形は \`\`-s\`\`) を使用することで、
\# ディレクトリーを指定できます。
\# 次の例は、 \*\*config/Alternate\*\* ディレクトリー内でマイグレーションを実行します。
bin/cake migrations migrate -s Alternate

\# \`\`--connection\`\` オプション (省略形は \`\`-c\`\`) を使用することで
\# \`\`default\`\` とは異なる接続でマイグレーションを実行できます。
bin/cake migrations migrate -c my\_custom\_connection

\# マイグレーションは、プラグインのためにも実行できます。 \`\`--plugin\`\` オプション
\# (省略形は \`\`-p\`\`) を使用します。
bin/cake migrations migrate -p MyAwesomePlugin

### `rollback` : マイグレーションを戻す[¶](https://book.cakephp.org/migrations/2/ja/#rollback "このヘッドラインへのパーマリンク")

ロールバックコマンドは、このプラグインを実行する前の状態に戻すために使われます。 これは `migrate` コマンドの逆向きの動作をします。 :

\# あなたは \`\`rollback\`\` コマンドを使って以前のマイグレーション状態に戻すことができます。
bin/cake migrations rollback

\# また、特定のバージョンに戻すために、マイグレーションバージョン番号を引き渡すこともできます。
bin/cake migrations rollback -t 20150103081132

`migrate` コマンドのように `--source` 、 `--connection` そして `--plugin` オプションが使用できます。

### `status` : マイグレーションのステータス[¶](https://book.cakephp.org/migrations/2/ja/#status "このヘッドラインへのパーマリンク")

Status コマンドは、現在の状況とすべてのマイグレーションのリストを出力します。 あなたはマイグレーションが実行されたかを判断するために、このコマンドを使用することができます。 :

bin/cake migrations status

`--format` (省略形は `-f`) オプションを使用することで JSON 形式の文字列として結果を出力できます。 :

bin/cake migrations status --format json

`migrate` コマンドのように `--source` 、 `--connection` そして `--plugin` オプションが使用できます。

### `mark_migrated` : マイグレーション済みとしてマーキングする[¶](https://book.cakephp.org/migrations/2/ja/#mark-migrated "このヘッドラインへのパーマリンク")

バージョン 1.4.0 で追加.

時には、実際にはマイグレーションを実行せずにマークだけすることが便利な事もあります。 これを実行するためには、 `mark_migrated` コマンドを使用します。 コマンドは、他のコマンドとしてシームレスに動作します。

このコマンドを使用して、すべてのマイグレーションをマイグレーション済みとして マークすることができます。 :

bin/cake migrations mark\_migrated

また、 `--target` オプションを使用して、指定したバージョンに対して、 すべてマイグレーション済みとしてマークすることができます。 :

bin/cake migrations mark\_migrated --target\=20151016204000

もし、指定したマイグレーションを処理中にマーク済みにしたくない場合、 `--exclude` フラグをつけて使用することができます。 :

bin/cake migrations mark\_migrated --target\=20151016204000 --exclude

最後に、指定したマイグレーションだけをマイグレーション済みとしてマークしたい場合、 `--only` フラグを使用できます。 :

bin/cake migrations mark\_migrated --target\=20151016204000 --only

`migrate` コマンドのように `--source` 、 `--connection` そして `--plugin` オプションが使用できます。

注釈

あなたが `cake bake migration_snapshot` コマンドでスナップショットを作成したとき、 自動的にマイグレーション済みとしてマーキングされてマイグレーションが作成されます。

バージョン 1.4.0 で非推奨: 以下のコマンドの使用方法は非推奨になりました。もし、あなたが 1.4.0 より前のバージョンの プラグインの場合のみに使用してください。

このコマンドは、引数としてマイグレーションバージョン番号を想定しています。 :

bin/cake migrations mark\_migrated 20150420082532

もし、すべてのマイグレーションをマイグレーション済みとしてマークしたい場合、 特別な値 `all` を使用できます。もし使用した場合、すべての見つかったマイグレーションを マイグレーション済みとしてマークします。 :

bin/cake migrations mark\_migrated all

### `seed` : データベースの初期データ投入[¶](https://book.cakephp.org/migrations/2/ja/#seed "このヘッドラインへのパーマリンク")

1.5.5 より、データベースの初期データ投入のために `migrations` シェルが使用できます。 これは、 [Phinx ライブラリーの seed 機能](https://book.cakephp.org/phinx/0/en/seeding.html)
 を利用しています。デフォルトで、seed ファイルは、あなたのアプリケーションの `config/Seeds` ディレクトリーの中に置かれます。 [seed ファイル作成のための Phinx の命令](https://book.cakephp.org/phinx/0/en/seeding.html#creating-a-new-seed-class)
 を確認してください。

マイグレーションに関して、 seed ファイルのための `bake` インターフェースが提供されます。 :

\# これは、あなたのアプリケーションの config/Seeds ディレクトリー内に ArticlesSeed.php を作成します。
\# デフォルトでは、変換対象の seed は、 "tableized" バージョンの seed ファイル名です。
bin/cake bake seed Articles

\# \`\`--table\`\` オプションを使用することで seed ファイルに変換するテーブル名を指定します。
bin/cake bake seed Articles --table my\_articles\_table

\# bake するプラグインを指定できます。
bin/cake bake seed Articles --plugin PluginName

\# シーダーの生成時に別の接続を指定できます。
bin/cake bake seed Articles --connection connection

バージョン cakephp/migrations で追加: 1.6.4

オプションの `--data`, `--limit` そして `--fields` は、 データベースからデータをエクスポートするために追加されました。

1.6.4 から、 `bake seed` コマンドは、 `--data` フラグを使用することによって、 データベースからエクスポートされたデータを元に seed ファイルを作成することができます。 :

bin/cake bake seed --data Articles

デフォルトでは、テーブル内にある行を全てエクスポートします。 `--limit` オプションを 使用することによって、エクスポートされる行の数を制限できます。 :

\# 10 行のみエクスポート
bin/cake bake seed --data --limit 10 Articles

もし、seed ファイルの中にテーブルから選択したフィールドのみを含めたい場合、 `--fields` オプションが使用できます。そのオプションは、 フィールドのリストをカンマ区切りの値の文字列として含めます。 :

\# \`id\`, \`title\` そして \`excerpt\` フィールドのみをエクスポート
bin/cake bake seed --data --fields id,title,excerpt Articles

ちなみに

もちろん、同じコマンド呼び出し中に `--limit` と `--fields` オプションの両方が利用できます。

データベースの初期データ投入のために、 `seed` サブコマンドが使用できます。 :

\# パラメーターなしの seed サブコマンドは、対象のディレクトリーのアルファベット順で、
\# すべての利用可能なシーダーを実行します。
bin/cake migrations seed

\# \`--seed\` オプションを使用して実行するための一つだけシーダーを指定できます。
bin/cake migrations seed --seed ArticlesSeed

\# 別のディレクトリーでシーダーを実行できます。
bin/cake migrations seed --source AlternativeSeeds

\# プラグインのシーダーを実行できます
bin/cake migrations seed --plugin PluginName

\# 指定したコネクションでシーダーを実行できます
bin/cake migrations seed --connection connection

マイグレーションとは対照的にシーダーは追跡されないことに注意してください。 それは、同じシーダーは、複数回適用することができることを意味します。

#### シーダーから別のシーダーの呼び出し[¶](https://book.cakephp.org/migrations/2/ja/#id18 "このヘッドラインへのパーマリンク")

バージョン cakephp/migrations で追加: 1.6.2

たいてい初期データ投入時は、データの挿入する順番は、規約違反しないように遵守しなければなりません。 デフォルトでは、アルファベット順でシーダーが実行されますが、独自にシーダーの実行順を定義するために `\Migrations\AbstractSeed::call()` メソッドが利用できます。

use Migrations\\AbstractSeed;

class DatabaseSeed extends AbstractSeed
{
    public function run()
    {
        $this\->call('AnotherSeed');
        $this\->call('YetAnotherSeed');

        // プラグインからシーダーを呼ぶためにプラグインドット記法が使えます
        $this\->call('PluginName.FromPluginSeed');
    }
}

注釈

もし、 `call()` メソッドを使いたい場合、Migrations プラグインの `AbstractSeed` クラスを継承していることを確認してください。このクラスは、リリース 1.6.2 で追加されました。

### `dump` : 差分を bake する機能のためのダンプファイルの生成[¶](https://book.cakephp.org/migrations/2/ja/#dump-bake "このヘッドラインへのパーマリンク")

dump コマンドは、 `migration_diff` の bake テンプレートで使用するファイルを作成します。 :

bin/cake migrations dump

各生成されたダンプファイルは、生成元の接続固有のものです（そして、そのようにサフィックスされます）。 これは、アプリケーションが、異なるデータベースベンダーの複数のデータベースを扱う場合、 `bake migration_diff` コマンドで正しく差分を算出することができます。

ダンプファイルは、マイグレーションファイルと同じディレクトリーに作成されます。

`migrate` コマンドのように `--source` 、 `--connection` そして `--plugin` オプションが使用できます。

プラグイン内のマイグレーションファイルを使う[¶](https://book.cakephp.org/migrations/2/ja/#id19 "このヘッドラインへのパーマリンク")

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

プラグインはマイグレーションファイルも提供することができます。 これはプラグインの移植性とインストールの容易さを高め、配布しやすくなるように意図されています。 Migrations プラグインの全てのコマンドは、プラグイン関連のマイグレーションを行うための `--plugin` か `-p` オプションをサポートしています。 :

bin/cake migrations status -p PluginName

bin/cake migrations migrate -p PluginName

非シェルの環境でマイグレーションを実行する[¶](https://book.cakephp.org/migrations/2/ja/#id20 "このヘッドラインへのパーマリンク")

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

バージョン cakephp/migrations で追加: 1.2.0

migrations プラグインのバージョン 1.2 から、非シェル環境でも app から直接 `Migrations` クラスを使ってマイグレーションを実行できるようになりました。 これは CMS のプラグインインストーラーを作る時などに便利です。 `Migrations` クラスを使用すると、マイグレーションシェルから下記のコマンドを 実行することができます。:

*   migrate
    
*   rollback
    
*   markMigrated
    
*   status
    
*   seed
    

それぞれのコマンドは `Migrations` クラスのメソッドとして実装されています。

使い方は以下の通りです。

use Migrations\\Migrations;

$migrations \= new Migrations();

// 全てのマイグレーションバージョンとそのステータスの配列を返します。
$status \= $migrations\->status();

// 成功した場合、 true を返し、エラーが発生した場合、例外が投げられます。
$migrate \= $migrations\->migrate();

// 成功した場合、 true を返し、エラーが発生した場合、例外が投げられます。
$rollback \= $migrations\->rollback();

// 成功した場合、 true を返し、エラーが発生した場合、例外が投げられます。
$markMigrated \= $migrations\->markMigrated(20150804222900);

// 成功した場合、 true を返し、エラーが発生した場合、例外が投げられます。
$seeded \= $migrations\->seed();

メソッドはコマンドラインのオプションと同じパラメーター配列を受け取ります。

use Migrations\\Migrations;

$migrations \= new Migrations();

// 全てのマイグレーションバージョンとそのステータスの配列を返す
$status \= $migrations\->status(\['connection' \=> 'custom', 'source' \=> 'MyMigrationsFolder'\]);

あなたはシェルコマンドのように任意のオプションを引き渡すことができます。 唯一の例外は `markMigrated` コマンドで、第１引数にはマイグレーション済みとして マーキングしたいマイグレーションバージョン番号を渡し、第２引数にパラメーターの配列を 渡します。

必要に応じて、クラスのコンストラクターでこれらのパラメーターを引き渡すことができます。 それはデフォルトとして使用され、それぞれのメソッド呼び出しの時に引き渡されることを 防止します。

use Migrations\\Migrations;

$migrations \= new Migrations(\['connection' \=> 'custom', 'source' \=> 'MyMigrationsFolder'\]);

// 以下のすべての呼び出しは、マイグレーションクラスのコンストラクターに渡されたパラメーターを使用して行われます
$status \= $migrations\->status();
$migrate \= $migrations\->migrate();

個別の呼び出しでデフォルトのパラメーターを上書きしたい場合は、メソッド呼び出し時に引き渡します。

use Migrations\\Migrations;

$migrations \= new Migrations(\['connection' \=> 'custom', 'source' \=> 'MyMigrationsFolder'\]);

// この呼び出しでは "custom" コネクションを使用します。
$status \= $migrations\->status();
// こちらでは "default" コネクションを使用します。
$migrate \= $migrations\->migrate(\['connection' \=> 'default'\]);

小技と裏技[¶](https://book.cakephp.org/migrations/2/ja/#id21 "このヘッドラインへのパーマリンク")

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

### 主キーをカスタマイズする[¶](https://book.cakephp.org/migrations/2/ja/#id22 "このヘッドラインへのパーマリンク")

あなたがデータベースに新しいテーブルを作成する時、 `id` を主キーとして 自動生成したくない場合、 `table()` メソッドの第２引数を使うことができます。

<?php
use Migrations\\AbstractMigration;

class CreateProductsTable extends AbstractMigration
{
    public function change()
    {
        $table \= $this\->table('products', \['id' \=> false, 'primary\_key' \=> \['id'\]\]);
        $table
              \->addColumn('id', 'uuid')
              \->addColumn('name', 'string')
              \->addColumn('description', 'text')
              \->create();
    }
}

上記の例では、 `CHAR(36)` の `id` というカラムを主キーとして作成します。

注釈

独自の主キーをコマンドラインで指定した時、id フィールドの中の主キーとして注意してください。 そうしなければ、id フィールドが重複してエラーになります。例:

bin/cake bake migration CreateProducts id:uuid:primary name:string description:text created modified

さらに、Migrations 1.3 以降では 主キーに対処するための新しい方法が導入されました。 これを行うには、あなたのマイグレーションクラスは新しい `Migrations\AbstractMigration` クラスを継承する必要があります。 あなたは Migration クラスの `autoId` プロパティーに `false` を設定することで、 自動的な `id` カラムの生成をオフにすることができます。 あなたは手動で主キーカラムを作成し、テーブル宣言に追加する必要があります。

<?php
use Migrations\\AbstractMigration;

class CreateProductsTable extends AbstractMigration
{

    public $autoId \= false;

    public function up()
    {
        $table \= $this\->table('products');
        $table
            \->addColumn('id', 'integer', \[\
                'autoIncrement' \=> true,\
                'limit' \=> 11\
            \])
            \->addPrimaryKey('id')
            \->addColumn('name', 'string')
            \->addColumn('description', 'text')
            \->create();
    }
}

主キーを扱うこれまでの方法と比較すると、この方法は、unsigned や not や limit や comment など さらに多くの主キーの定義を操作することができるようになっています。

Bake で生成されたマイグレーションファイルとスナップショットは、この新しい方法を 必要に応じて使用します。

警告

主キーの操作ができるのは、テーブル作成時のみです。これはプラグインがサポートしている いくつかのデータベースサーバーの制限によるものです。

### 照合順序[¶](https://book.cakephp.org/migrations/2/ja/#id23 "このヘッドラインへのパーマリンク")

もしデータベースのデフォルトとは別の照合順序を持つテーブルを作成する必要がある場合は、 `table()` メソッドのオプションとして定義することができます。:

<?php
use Migrations\\AbstractMigration;

class CreateCategoriesTable extends AbstractMigration
{
    public function change()
    {
        $table \= $this
            \->table('categories', \[\
                'collation' \=> 'latin1\_german1\_ci'\
            \])
            \->addColumn('title', 'string', \[\
                'default' \=> null,\
                'limit' \=> 255,\
                'null' \=> false,\
            \])
            \->create();
    }
}

ですが、これはテーブル作成時にしかできず、既存のテーブルに対してカラムを追加する時に テーブルやデータベースと異なる照合順序を指定する方法がないことに注意してください。 ただ `MySQL` と `SqlServer` だけはこの設定キーをサポートしています。

### カラム名の更新と Table オブジェクトの使用[¶](https://book.cakephp.org/migrations/2/ja/#table "このヘッドラインへのパーマリンク")

カラムのリネームや移動とともに、あなたのデータベースから値を操作するために CakePHP ORM Table オブジェクトを使用している場合、 `update()` を呼んだ後に Table オブジェクトの新しいインスタンスを作成できることを確かめてください。 インスタンス上の Table オブジェクトに反映し保存されたスキーマをリフレッシュするために Table オブジェクトのレジストリーは、 `update()` が呼ばれた後にクリアされます。

### マイグレーションとデプロイメント[¶](https://book.cakephp.org/migrations/2/ja/#id24 "このヘッドラインへのパーマリンク")

もし、アプリケーションをデプロイする時にプラグインを使用する場合、 テーブルのカラムメタデータを更新するように、必ず ORM キャッシュをクリアしてください。 そうしなければ、それらの新しいカラムの操作を実行する時に、カラムが存在しないエラーになります。 CakePHP コアは、この操作を行うために使用できる [スキーマキャッシュシェル](https://book.cakephp.org/3.0/ja/console-and-shells/schema-cache.html)
 を含みます。 :

// 3.6.0 より前の場合、orm\_cache を使用
bin/cake schema\_cache clear

このシェルについてもっと知りたい場合、クックブックの [スキーマキャッシュシェル](https://book.cakephp.org/3.0/ja/console-and-shells/schema-cache.html)
 セクションをご覧ください。

### テーブルのリネーム[¶](https://book.cakephp.org/migrations/2/ja/#id25 "このヘッドラインへのパーマリンク")

プラグインは、 `rename()` メソッドを使用することでテーブルのリネームができます。 あなたのマイグレーションファイルの中で、以下のように記述できます。

public function up()
{
    $this\->table('old\_table\_name')
        \->rename('new\_table\_name')
        \->save();
}

### `schema.lock` ファイル生成のスキップ[¶](https://book.cakephp.org/migrations/2/ja/#schema-lock "このヘッドラインへのパーマリンク")

バージョン cakephp/migrations で追加: 1.6.5

diff 機能を動作させるために、 **.lock** ファイルは、migrate、rollback または スナップショットの bake の度に生成され、指定された時点でのデータベーススキーマの状態を追跡します。 例えば本番環境上にデプロイするときなど、前述のコマンドに `--no-lock` オプションを使用することによって、このファイルの生成をスキップすることができます。 :

bin/cake migrations migrate --no-lock

bin/cake migrations rollback --no-lock

bin/cake bake migration\_snapshot MyMigration --no-lock

[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://cakesf.herokuapp.com/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")
[#IRC](https://webchat.freenode.net/?channels=cakephp "IRC")

---

# Debug Kit - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/debug_kit/edit/3.x/docs/ja/index.rst)

[](https://book.cakephp.org/debugkit/3/ja/#page-contents)

### Page Contents

*   [Debug Kit](https://book.cakephp.org/debugkit/3/ja/#)
    *   [インストール](https://book.cakephp.org/debugkit/3/ja/#id1)
        
    *   [設定](https://book.cakephp.org/debugkit/3/ja/#id2)
        *   [データベース設定](https://book.cakephp.org/debugkit/3/ja/#id3)
            
    *   [ツールバーの使い方](https://book.cakephp.org/debugkit/3/ja/#id4)
        
    *   [履歴パネルを使用する](https://book.cakephp.org/debugkit/3/ja/#id5)
        
    *   [メールパネルを使用](https://book.cakephp.org/debugkit/3/ja/#id6)
        *   [プレビュークラスの作成](https://book.cakephp.org/debugkit/3/ja/#id7)
            
    *   [独自のパネルを開発する](https://book.cakephp.org/debugkit/3/ja/#id8)
        *   [パネルクラスを作成する](https://book.cakephp.org/debugkit/3/ja/#id9)
            
        *   [コールバック](https://book.cakephp.org/debugkit/3/ja/#id10)
            
        *   [パネルの構成要素](https://book.cakephp.org/debugkit/3/ja/#id11)
            
        *   [カスタムのタイトルとエレメント](https://book.cakephp.org/debugkit/3/ja/#id12)
            
        *   [パネルフックメソッド](https://book.cakephp.org/debugkit/3/ja/#id13)
            
        *   [他のプラグインのパネル](https://book.cakephp.org/debugkit/3/ja/#id14)
            
    *   [ヘルパー関数](https://book.cakephp.org/debugkit/3/ja/#id15)
        

Debug Kit[¶](https://book.cakephp.org/debugkit/3/ja/#debug-kit "このヘッドラインへのパーマリンク")

===================================================================================

DebugKit は、CakePHP アプリケーション用のデバッグツールバーと拡張デバッグツールを提供します。 アプリケーションの設定データ、ログメッセージ、SQL クエリー、およびタイミングデータをすばやく 確認できます。

警告

DebugKit は、シングルユーザーのローカル開発環境での使用を目的としています。 共有開発環境、ステージング環境、または設定データと環境変数を隠しておく必要がある環境では、 DebugKit を使用しないでください。

インストール[¶](https://book.cakephp.org/debugkit/3/ja/#id1 "このヘッドラインへのパーマリンク")

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

デフォルトで、DebugKit はデフォルトのアプリケーションスケルトンにインストールされています。 もし削除してしまって再インストールしたい場合は、以下のコマンドをアプリケーションの ルートディレクトリー (composer.json ファイルのある場所) で実行してください。

php composer.phar require \--dev cakephp/debug\_kit "~3.0"

そして以下のコマンドでプラグインを有効化する必要があります。

bin/cake plugin load DebugKit

設定[¶](https://book.cakephp.org/debugkit/3/ja/#id2 "このヘッドラインへのパーマリンク")

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

*   `DebugKit.panels` - DebugKit のパネルを有効化または無効化します。 次のようにして、任意の標準パネルを無効にすることができます。
    
    // DebugKit をロードする前に
    Configure::write('DebugKit.panels', \['DebugKit.Packages' \=> false\]);
    
*   `DebugKit.includeSchemaReflection` - スキーマリフレクションクエリーの ロギングを有効にするには、true に設定します。デフォルトは無効になっています。
    
*   `DebugKit.safeTld` - ローカル開発用のトップレベルドメインのホワイトリストを設定します。 これにより安全でないと判断したホスト上で DebugKit を表示できるようになります。
    
    // 例: http://foo.bar.dev または http://my-shop.local のドメインはローカルとして許可する
    Configure::write('DebugKit.safeTld', \['dev', 'local', 'example'\]);
    
*   `DebugKit.forceEnable` - DebugKit を強制的に表示します。これを使うときは注意してください。 通常は単純にローカルのトップレベルドメインをホワイトリストに追加したほうが安全です。 使用例:
    
    // DebugKit をロードする前に
    Configure::write('DebugKit.forceEnable', true);
    

### データベース設定[¶](https://book.cakephp.org/debugkit/3/ja/#id3 "このヘッドラインへのパーマリンク")

デフォルトでは DebugKit はアプリケーションの `/tmp` 内の SQLite データベースに パネルデータを保持します。もし pdo\_sqlite をインストールできない場合は、 **config/app.php** ファイル に `debug_kit` コネクションを定義すると DebugKit が異なるデータベースを使用するように設定できます。例:

/\*\*
 \* debug\_kit コネクションは DebugKit のメタデータを格納します。
 \*/
'debug\_kit' \=> \[\
    'className' \=> 'Cake\\Database\\Connection',\
    'driver' \=> 'Cake\\Database\\Driver\\Mysql',\
    'persistent' \=> false,\
    'host' \=> 'localhost',\
    //'port' => 'nonstandard\_port\_number',\
    'username' \=> 'dbusername',    // Your DB username here\
    'password' \=> 'dbpassword',    // Your DB password here\
    'database' \=> 'debug\_kit',\
    'encoding' \=> 'utf8',\
    'timezone' \=> 'UTC',\
    'cacheMetadata' \=> true,\
    'quoteIdentifiers' \=> false,\
    //'init' => \['SET GLOBAL innodb\_stats\_on\_metadata = 0'\],\
\],

**tmp/debug\_kit.sqlite** ファイルは、いつでも削除することができます。 DebugKit は、必要に応じて、それを再生成します。

ツールバーの使い方[¶](https://book.cakephp.org/debugkit/3/ja/#id4 "このヘッドラインへのパーマリンク")

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

DebugKit ツールバーは、いくつかのパネルで構成されています。これらのパネルは、 DebugKit をインストールしてロードした後、ブラウザーの右下隅にある CakePHP アイコンをクリックすると表示されます。各パネルは、パネルクラスとビューエレメントで構成されています。 一般的に、パネルは単一の種類の情報のコレクションの処理やログやリクエスト情報の表示を行います。 ツールバーからパネルを表示したり、独自のカスタムパネルを追加することを選択できます。

各パネルはアプリケーションの様々な側面を見せてくれます。

*   **Cache** リクエスト中のキャッシュの使用状況の確認とキャッシュのクリアー。
    
*   **Environment** PHP 及び CakePHP に関連する環境変数の表示。
    
*   **History** 以前のリクエストの一覧の表示と、以前のリクエストのツールバーデータの読み込みと表示。
    
*   **Include** タイプごとにグループ化されたインクルードファイルを表示。
    
*   **Log** このリクエスト中にログファイルに加えられたすべてのエントリーを表示。
    
*   **Packages** 現在のバージョンのパッケージの依存関係の一覧を表示し、 古いパッケージをチェックすることができます。
    
*   **Mail** このリクエスト中の全てのメール送信を表示し、 送信せずに開発中のメールのプレビューができます。
    
*   **Request** 現在のリクエスト、GET、POST、Cake パラメーター、現在のルート情報、クッキー情報の表示。
    
*   **Session** 現在のセッション情報の表示。
    
*   **Sql Logs** 各データベースコネクションの SQL ログの表示。
    
*   **Timer** リクエスト中に `DebugKit\DebugTimer` で設定されたすべてのタイマーと、 `DebugKit\DebugMemory` で収集されたメモリー使用状況の表示。
    
*   **Variables** コントローラーでセットされたビュー変数の表示。
    

履歴パネルを使用する[¶](https://book.cakephp.org/debugkit/3/ja/#id5 "このヘッドラインへのパーマリンク")

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

履歴パネルは DebugKit で最も勘違いされやすい機能の一つです。 エラーやリダイレクトを含む以前のリクエストのツールバーのデータを表示することができます。

![Screenshot of the history panel in debug kit.](https://book.cakephp.org/debugkit/3/_static/history-panel.png)

ご覧のようにパネルにはリクエストの一覧が含まれます。左側にドットがついているのがアクティブな リクエストです。どれかのリクエストをクリックするとそのリクエストのデータが読み込まれます。 履歴データがロードされると代替のデータが読み込まれたことを示すようにパネルのタイトルが遷移します。

Video of history panel in action.

メールパネルを使用[¶](https://book.cakephp.org/debugkit/3/ja/#id6 "このヘッドラインへのパーマリンク")

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

メールパネルは、リクエストの間に送信された全てのメールを追跡することができます。

Video of mail panel in action

メーラープレビューは、開発中のメールを簡単にプレビューすることができます。

Video of mail panel in action

### プレビュークラスの作成[¶](https://book.cakephp.org/debugkit/3/ja/#id7 "このヘッドラインへのパーマリンク")

メールを送信する前にプレビューするには、受信者と mailer メソッドに必要なテンプレート変数を 定義するプレビュークラスを作成する必要があります。

// src/Mailer/MailPreview/WelcomePreview.php の中で
namespace App\\Mailer\\Preview;

use DebugKit\\Mailer\\MailPreview;

class WelcomePreview extends MailPreview
{
    public function welcome()
    {
        $mailer \= $this\->getMailer('Welcome');
        // メーラーのテンプレート変数受信者を設定します。

        return $mailer;
    }
}

MailPreview クラスは、 アプリケーションまたはプラグインの `Mailer\Preview` 名前空間に存在し、 `Preview` を使用する必要があります。

独自のパネルを開発する[¶](https://book.cakephp.org/debugkit/3/ja/#id8 "このヘッドラインへのパーマリンク")

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

アプリケーションのデバッグを補助するための DebugKit の独自のカスタムパネルを 作成することができます。

### パネルクラスを作成する[¶](https://book.cakephp.org/debugkit/3/ja/#id9 "このヘッドラインへのパーマリンク")

パネルクラスは単に **src/Panel** ディレクトリーに設置してください。ファイル名はクラス名と 一致する必要があります。 つまり `MyCustomPanel` クラスは **src/Panel/MyCustomPanel.php** というファイル名であることを想定しています。

namespace App\\Panel;

use DebugKit\\DebugPanel;

/\*\*
 \* My Custom Panel
 \*/
class MyCustomPanel extends DebugPanel
{
    ...
}

カスタムパネルは `DebugPanel` クラスを拡張する必要があることに注意してください。

### コールバック[¶](https://book.cakephp.org/debugkit/3/ja/#id10 "このヘッドラインへのパーマリンク")

デフォルトではパネルオブジェクトには、現在のリクエストをフックすることができる 2つのコールバックがあります。パネルは `Controller.initialize` と `Controller.shutdown` のイベントを取得します。もしパネルが追加のイベントを 取得したい場合は、 `implementedEvents()` メソッドを使用し、 パネルが必要とするすべてのイベントを定義できます。

どのようにパネルを構築するかについてのいくつかの例として、ビルトインのパネルを参照してください。

### パネルの構成要素[¶](https://book.cakephp.org/debugkit/3/ja/#id11 "このヘッドラインへのパーマリンク")

各パネルはパネルのコンテンツを描画するためのビューエレメントがあることを想定しています。 エレメント名はアンダースコアー区切りのクラス名である必要があります。 たとえば、 `SessionPanel` は **session\_panel.ctp** という名前のエレメントを持ちます。 また、SqllogPanelは **sqllog\_panel.ctp** という名前のエレメントを持ちます。 これらのエレメントは **src/Template/Element** ディレクトリーのルートに設置する必要があります。

### カスタムのタイトルとエレメント[¶](https://book.cakephp.org/debugkit/3/ja/#id12 "このヘッドラインへのパーマリンク")

パネルは慣例を元にそのタイトルとエレメント名を補足します。もしカスタムのタイトルやエレメント名を 付けたい場合は、パネルの振る舞いをカスタムするメソッドを定義することができます。

*   `title()` - ツールバー上に表示されるタイトルを設定します
    
*   `elementName()` - 与えられたパネルがどのエレメントを使用するかを設定します
    

### パネルフックメソッド[¶](https://book.cakephp.org/debugkit/3/ja/#id13 "このヘッドラインへのパーマリンク")

また、パネルの動作や表示方法をカスタムするために以下のフックメソッドを実装することができます。

*   `shutdown(Event $event)` このメソッドは通常はパネルのデータの収集と準備を行います。
    
*   `summary()` パネルが折りたたまれている時に表示されるサマリーデータの文字列を 返すことができます。多くの場合、これは件数や短いサマリー情報です。
    
*   `data()` エレメントのコンテキストで使用されるパネルのデータを返します。 このフックメソッドは `shutdown()` で収集されるデータを更に操作することができます。 このメソッドはシリアライズ化可能なデータを **必ず** 返す必要があります。
    

### 他のプラグインのパネル[¶](https://book.cakephp.org/debugkit/3/ja/#id14 "このヘッドラインへのパーマリンク")

パネルはひとつの小さな違いを除き、[plugins](https://book.cakephp.org/3.0/ja/plugins.html)
 とほぼ同じ動作を提供します。レンダリング時にパネルのエレメントを配置できるように、 `public $plugin` にプラグインディレクトリーの名前を必ずセットする必要があります。

namespace MyPlugin\\Panel;

use DebugKit\\DebugPanel;

class MyCustomPanel extends DebugPanel
{
    public $plugin \= 'MyPlugin';
        ...
}

プラグインやアプリケーションパネルを使用するには、アプリケーションの DebugKit の設定を 更新します。

// src/Application.php の bootstrap() メソッドの中に追加
Configure::write('DebugKit.panels', \['App', 'MyPlugin.MyCustom'\]);
$this\->addPlugin('DebugKit', \['bootstrap' \=> true\]);

上記は、すべてのデフォルトのパネルと同じように `AppPanel` と `MyPlugin` の `MyCustomPanel` パネルを読みこみます。

ヘルパー関数[¶](https://book.cakephp.org/debugkit/3/ja/#id15 "このヘッドラインへのパーマリンク")

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

*   `sql()` ORM クエリーから SQL をダンプします。
    
*   `sqld()` ORM クエリーから SQL をダンプして終了します。
    

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# ビュー | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/views.html#VPContent)

Return to top

ビュー [​](https://book.cakephp.org/3.x/ja/views.html#%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC)

=========================================================================================

`class` Cake\\View\\**View**

ビュー (View) は MVC の **V** です。ビューはリクエストに対する出力を生成する役割を担います。 大抵の場合、これは HTML フォームや XML、JSON などですが、ファイルのストリーミングや、 ユーザーがダウンロード可能な PDF の生成もビューレイヤーの役割となります。

CakePHP では下記の典型的な描画シナリオに対応するためのいくつかの組み込みのビュークラスを 用意しています。

*   XML や JSON ウェブサービスを作成するには [JSON と XML ビュー](https://book.cakephp.org/3.x/ja/views/json-and-xml-views.html)
     を利用できます。
*   保護されたファイルや動的に生成されたファイルを提供するには [Cake Response File](https://book.cakephp.org/3.x/ja/controllers/request-response.html#cake-response-file)
     を利用できます。
*   複数テーマのビューを作成するには [テーマ](https://book.cakephp.org/3.x/ja/views/themes.html)
     を利用できます。

App ビュー [​](https://book.cakephp.org/3.x/ja/views.html#app-%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC)

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

`AppView` はアプリケーションの既定のビュークラスです。 `AppView` は自身が CakePHP に含まれる `Cake\View\View` クラスを継承していて、 **src/View/AppView.php** の中で次のように定義されています。

    <?php
    namespace App\View;
    
    use Cake\View\View;
    
    class AppView extends View
    {
    }

1  
2  
3  
4  
5  
6  
7  
8  

アプリケーション中で描画されるすべてのビューで使われるヘルパーを読み込むために `AppView` を使用することができます。こうした用途のために、CakePHP は View のコンストラクターの最後で呼び出される `initialize()` メソッドを提供します。

    <?php
    namespace App\View;
    
    use Cake\View\View;
    
    class AppView extends View
    {
    
        public function initialize()
        {
            // MyUtils ヘルパーをいつでも有効にする
            $this->loadHelper('MyUtils');
        }
    
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

ビューテンプレート [​](https://book.cakephp.org/3.x/ja/views.html#%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC%E3%83%86%E3%83%B3%E3%83%95%E3%82%9A%E3%83%AC%E3%83%BC%E3%83%88)

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

CakePHP のビューレイヤーは、どのようにユーザーに伝えるかです。ほとんどの場合、ビューは HTML/XHTML ドキュメントをブラウザーに返しますが、JSON を介して リモートアプリケーションに返答したり、CSV ファイルを出力する必要もあるかもしれません。

CakePHP のテンプレートファイルは既定の拡張子を **.ctp** (CakePHP Template) としており、 制御構造や出力のために [PHP 別の構文](https://php.net/manual/ja/control-structures.alternative-syntax.php)
 を利用することができます。 これらのファイルにはコントローラーから受け取ったデータを、 閲覧者のために用意した表示形式に整形するのに必要なロジックを入れます。

### 別の echo [​](https://book.cakephp.org/3.x/ja/views.html#%E5%88%A5%E3%81%AE-echo)

テンプレート中の変数を echo または print します。 :

    <?php echo $variable; ?>

1  

短いタグにも対応しています。 :

    <?= $variable ?>

1  

### 別の制御構文 [​](https://book.cakephp.org/3.x/ja/views.html#%E5%88%A5%E3%81%AE%E5%88%B6%E5%BE%A1%E6%A7%8B%E6%96%87)

`if` 、 `for` 、 `foreach` 、 `switch` 、そして `while` のような制御構文は単純な形式で書くことができます。括弧は必要ないことに注意してください。 代わりに、 `foreach` の閉じ括弧は `endforeach` に置き換えられています。 上記の各制御構造は `endif` 、 `endfor` 、 `endforeach` 、 `endwhile` のような閉じ構文を持っています。各制御構造の後（最後の一つを除いて）に `セミコロン (;)` ではなく、 `コロン (:)` があることにも注意してください。

以下は `foreach` の使用例です。

    <ul>
    <?php foreach ($todo as $item): ?>
      <li><?= $item ?></li>
    <?php endforeach; ?>
    </ul>

1  
2  
3  
4  
5  

別の例として、 if/elseif/else の用法です。コロンに注意してください。

    <?php if ($username === 'sally'): ?>
       <h3>やあ、Sally</h3>
    <?php elseif ($username === 'joe'): ?>
       <h3>やあ、Joe</h3>
    <?php else: ?>
       <h3>やあ、知らない人</h3>
    <?php endif; ?>

1  
2  
3  
4  
5  
6  
7  

もしも、 [Twig](https://twig.sensiolabs.org/)
 のようなテンプレート言語を使いたいのであれば、 ビューのサブクラスがテンプレート言語と CakePHP の橋渡しをしてくれるでしょう。

テンプレートファイルは **/src/Template/** の中の、ファイルを使用するコントローラーにちなんで 名付けられたフォルダーに置かれ、その対応するアクション名にちなんで名付けられます。 例えば、 `Products` コントローラーの `view()` アクションのビューファイルは通常、 **/src/Template/Products/view.ctp** となります。

CakePHP のビューレイヤーはいくつかの異なるパーツによって作り上げられています。 各パーツは異なる役割を持っており、この章で説明していきます。

*   **テンプレート**: テンプレートは実行中のアクション固有のページの一部分です。 アプリケーションの応答の中心となります。
*   **エレメント**: 小さな、再利用可能なちょっとしたコードです。エレメントは通常、 ビューの中で描画されます。
*   **レイアウト**: アプリケーションの多くのインターフェイスをくるむ表示コードを入れる テンプレートファイルです。ほとんどのビューはレイアウトの中に描画されます。
*   **ヘルパー**: これらのクラスはビューレイヤーの様々な場所で必要とされるロジックを カプセル化します。とりわけ、CakePHP のヘルパーはフォームの構築や AJAX 機能の構築、 モデルデータのページ切替、RSS フィードの提供などの手助けをしてくれます。
*   **cells**: これらのクラスは、自己完結型のUI部品を作成する 小さなコントローラー風の機能を提供します。 より詳しい情報は [ビューセル](https://book.cakephp.org/3.x/ja/views/cells.html)
     を参照してください。

### ビュー変数 [​](https://book.cakephp.org/3.x/ja/views.html#%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC%E5%A4%89%E6%95%B0)

コントローラーの中で `set()` で設定した変数は、 アクションが描画するビューやレイアウトの双方で使用可能です。 加えて、設定した変数はエレメントの中でも使用可能です。 もしも、追加の変数をビューからレイアウトに渡す必要があれば、 ビューテンプレートの中から `set()` を呼ぶか、 [View Blocks](https://book.cakephp.org/3.x/ja/views.html#view-blocks)
 が利用できます。

CakePHP は自動では出力をエスケープしませんので、ユーザーデータを出力する前には **いつも** エスケープしなければならないことを覚えておいてください。 `h()` 関数でユーザーコンテンツをエスケープできます。 :

    <?= h($user->bio); ?>

1  

### ビュー変数の設定 [​](https://book.cakephp.org/3.x/ja/views.html#%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC%E5%A4%89%E6%95%B0%E3%81%AE%E8%A8%AD%E5%AE%9A)

`method` Cake\\View\\View::**set**(string $var, mixed $value)

ビューにはコントローラーオブジェクトの `set()` と類似の `set()` メソッドがあります。 ビューファイルから set() を使うと後で描画されるレイアウトやエレメントに変数を追加できます。 `set()` の使い方のより詳しい情報は [Setting View Variables](https://book.cakephp.org/3.x/ja/controllers.html#setting-view-variables)
 を参照してください。

ビューファイルでは、次のように記述できます。 :

    $this->set('activeMenuButton', 'posts');

1  

そしてレイアウトでは、 `$activeMenuButton` 変数が使用でき、 'posts' という値を持ちます。

### ビューの継承 [​](https://book.cakephp.org/3.x/ja/views.html#%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC%E3%81%AE%E7%B6%99%E6%89%BF)

ビューの継承によって、あるビューを他のビューでくるむことができるようになります。 [ビューブロック](https://book.cakephp.org/3.x/ja/views.html#view-blocks)
 と組み合わせることでビューを `DRY` に保つための 強力な方法が得られます。例えば、あなたが作成しているアプリケーションの特定のビューで、 サイドバーの描画を変える必要があるとします。共通のビューファイルを継承することで、 サイドバーのマークアップの繰り返しを避けられ、そしてただ変化する場所を定義するだけです。

    <!-- src/Template/Common/view.ctp -->
    <h1><?= $this->fetch('title') ?></h1>
    <?= $this->fetch('content') ?>
    
    <div class="actions">
        <h3>関連アクション</h3>
        <ul>
        <?= $this->fetch('sidebar') ?>
        </ul>
    </div>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

上記のビューファイルを親ビューとして使うことができます。これは `sidebar` と `title` ブロックを定義しているビューが継承することを期待しています。 `content` ブロックは CakePHP が作る特別なブロックで、継承しているビューの捕捉されなかったすべての内容が入ります。 ビューファイルに投稿のデータが格納されている `$post` という変数があるとすれば、 ビューは次のようになります。

    <!-- src/Template/Posts/view.ctp -->
    <?php
    $this->extend('/Common/view');
    
    $this->assign('title', $post->title);
    
    $this->start('sidebar');
    ?>
    <li>
    <?php
    echo $this->Html->link('edit', [\
        'action' => 'edit',\
        $post->id\
    ]);
    ?>
    </li>
    <?php $this->end(); ?>
    
    // 残りの内容は親ビューの 'content' ブロックとして使用可能です。
    <?= h($post->body) ?>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  

上記の例はどのようにビューを継承できるかを示しており、ブロック一式を生成しています。 定義されたブロックの中に入っていないあらゆるコンテンツは捕捉され、 `content` という特別な名前のブロックに配置されます。ビューに `extend()` の呼び出しがある場合、 現在のビューファイルは最後まで実行されます。実行完了後、継承されたビューが描画されます。 一つのビューファイルで二回以上 `extend()` が呼び出される場合、 次に処理される親ビューを上書きします。 :

    $this->extend('/Common/view');
    $this->extend('/Common/index');

1  
2  

上記は `/Common/index.ctp` が現在のビューの親ビューとして描画される結果になります。

継承されたビューは好きなだけ入れ子にすることができます。必要に応じて 各ビューは他のビューを継承することができます。各親ビューは一つ前のビューの内容を `content` ブロックとして取得できます。

NOTE

`content` をブロック名として使うことは避けるべきです。 CakePHP は継承されたビューの中で捕捉されていないコンテンツとして扱ってしまいます。

`blocks()` メソッドを使って、存在するブロックを列挙することができます。 :

    $list = $this->blocks();

1  

ビューブロックの使用 [​](https://book.cakephp.org/3.x/ja/views.html#%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC%E3%83%95%E3%82%99%E3%83%AD%E3%83%83%E3%82%AF%E3%81%AE%E4%BD%BF%E7%94%A8)

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

ビューブロックはビュー/レイアウトの中のどこかで定義されるであろう、スロットやブロックを 定義できるようにする柔軟な API を提供します。例えばブロックは、サイドバーや、 レイアウトの末尾や先頭のアセット読込領域の実装に理想的です。 ブロックを実装するには二つの方法があります。捕捉するブロックとするか、直接割り当てるかです。 `start()` 、 `append()` 、 `prepend()` 、 `assign()` 、 `fetch()` 、 そして `end()` メソッドは捕捉するブロックと共に動作します。 :

    // sidebar ブロックを作成する。
    $this->start('sidebar');
    echo $this->element('sidebar/recent_topics');
    echo $this->element('sidebar/recent_comments');
    $this->end();
    
    // sidebar の末尾に追加する。
    $this->start('sidebar');
    echo $this->fetch('sidebar');
    echo $this->element('sidebar/popular_topics');
    $this->end();

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

`append()` を使ってブロックに追記することもできます。 :

    $this->append('sidebar');
    echo $this->element('sidebar/popular_topics');
    $this->end();
    
    // 上と同じです。
    $this->append('sidebar', $this->element('sidebar/popular_topics'));

1  
2  
3  
4  
5  
6  

もしあるブロックを消去または上書きする必要がある場合、二つほど選択肢があります。 `reset()` メソッドはいつでもブロックを消去または上書きします。 空文字での `assign()` メソッドも特定のブロックを消去するために使えます。 :

    // sidebar ブロックの以前の中身を消去します。
    $this->reset('sidebar');
    
    // 空文字を代入も sidebar ブロックを消去します。.
    $this->assign('sidebar', '');

1  
2  
3  
4  
5  

Added in version 3.2

3.2 で View::reset() が追加されました

ブロックのコンテンツへの代入は、ビュー変数をブロックに変換したい時にしばしば役に立ちます。 例えば、ページタイトルのためにブロックを使いたいかもしれませんし、 時にはコントローラーの中で、ビュー変数としてタイトルを代入するかもしれません。 :

    // ビューやレイアウトの中で $this->fetch('title') に
    $this->assign('title', $title);

1  
2  

`prepend()` メソッドは既存のブロックの先頭にコンテンツを追記することができます。 :

    // sidebar に前置します
    $this->prepend('sidebar', 'このコンテンツはサイドバーの先頭に来ます');

1  
2  

### ブロックの表示 [​](https://book.cakephp.org/3.x/ja/views.html#%E3%83%95%E3%82%99%E3%83%AD%E3%83%83%E3%82%AF%E3%81%AE%E8%A1%A8%E7%A4%BA)

ブロックの表示には `fetch()` メソッドを使います。`fetch()` は もしもブロックが存在しなかった場合に '' を返してブロックを出力します。 :

    <?= $this->fetch('sidebar') ?>

1  

fetch を使うとブロックが存在するかどうかによってブロックに囲まれたコンテンツの表示を 切り替えることができます。これはレイアウトや継承されたビューで 見出しや他のマークアップ表示を切り替えたい場合に役に立ちます。

    // src/Template/Layout/default.ctp の中で
    <?php if ($this->fetch('menu')): ?>
    <div class="menu">
        <h3>Menu options</h3>
        <?= $this->fetch('menu') ?>
    </div>
    <?php endif; ?>

1  
2  
3  
4  
5  
6  
7  

ブロックが存在しない場合の既定の値を指定することもできます。 これによって、ブロックが存在しない場合のプレースホルダーを追加することでききます。 既定値は第二引数で指定します。

    <div class="shopping-cart">
        <h3>買い物かご</h3>
        <?= $this->fetch('cart', '買い物かごが空です') ?>
    </div>

1  
2  
3  
4  

### スクリプトと CSS ファイルのためのブロック使用 [​](https://book.cakephp.org/3.x/ja/views.html#%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%95%E3%82%9A%E3%83%88%E3%81%A8-css-%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%81%AE%E3%81%9F%E3%82%81%E3%81%AE%E3%83%95%E3%82%99%E3%83%AD%E3%83%83%E3%82%AF%E4%BD%BF%E7%94%A8)

`HtmlHelper` はビューブロックと結び付いており、その `script()` 、 `css()` 、そして `meta()` メソッドは `block = true` のオプションで使われると 同名のブロックをそれぞれ更新します。

    <?php
    // ビューファイルの中で
    $this->Html->script('carousel', ['block' => true]);
    $this->Html->css('carousel', ['block' => true]);
    ?>
    
    // レイアウトファイルの中で
    <!DOCTYPE html>
    <html lang="en">
        <head>
        <title><?= $this->fetch('title') ?></title>
        <?= $this->fetch('script') ?>
        <?= $this->fetch('css') ?>
        </head>
        // 残りのレイアウトが続きます

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

`Cake\View\Helper\HtmlHelper` はスクリプトや CSS が入るブロックを 制御することもできます。 :

    // ビューファイルの中で
    $this->Html->script('carousel', ['block' => 'scriptBottom']);
    
    // レイアウトの中で
    <?= $this->fetch('scriptBottom') ?>

1  
2  
3  
4  
5  

レイアウト [​](https://book.cakephp.org/3.x/ja/views.html#%E3%83%AC%E3%82%A4%E3%82%A2%E3%82%A6%E3%83%88)

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

レイアウトにはビューをくるむ表示コードが入ります。すべてのビューから見えて欲しいものは レイアウトに配置されるべきです。

CakePHP の既定のレイアウトは **src/Template/Layout/default.ctp** に置かれます。 もし、アプリケーションの見栄え全体を変更したい場合、これが手始めとなり、 なぜならページが描画される時には、コントローラーによって描画されるビューのコードは、 既定のレイアウトの中に置かれるからです。

他のレイアウトファイルは **src/Template/Layout** に配置されるべきです。 レイアウトを作るとき、ビューの出力がどこに配置されるかを CakePHP に伝える必要があります。 そのために、レイアウトには `$this->fetch('content')` を入れるようにしてください。 これは既定のレイアウトがどのようなものかの一例です。

    <!DOCTYPE html>
    <html lang="en">
    <head>
    <title><?= h($this->fetch('title')) ?></title>
    <link rel="shortcut icon" href="favicon.ico" type="image/x-icon">
    <!-- 外部ファイルとスクリプトファイルがここに入れます (詳しくは HTML ヘルパーを参照。) -->
    <?php
    echo $this->fetch('meta');
    echo $this->fetch('css');
    echo $this->fetch('script');
    ?>
    </head>
    <body>
    
    <!-- もしすべてのビューでメニューを表示したい場合、ここに入れます -->
    <div id="header">
        <div id="menu">...</div>
    </div>
    
    <!-- ここがビューで表示されるようにしたい場所です -->
    <?= $this->fetch('content') ?>
    
    <!-- 表示される各ページにフッターを追加します -->
    <div id="footer">...</div>
    
    </body>
    </html>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  

`script` 、 `css` 、 `meta` ブロックには、組み込みの HTML ヘルパーを使って ビューで定義されたすべての内容が入ります。 ビューからの JavaScript と CSS ファイルを読み込むのに便利です。

NOTE

`HtmlHelper::css()` や `HtmlHelper::script()` を テンプレートファイルで使うとき、HTML ソースを同じ名前でブロックの中に配置するには `'block' => true` を指定してください。 (詳しい使い方は API を参照してください)

`content` ブロックは描画されたビューの内容が入ります。

`title` ブロックの内容をビューファイルから設定することができます。 :

    $this->assign('title', 'アクティブユーザー表示');

1  

`title` ブロックが空の値の場合、自動的に `'Admin/Articles'` のような 現在のテンプレートパスの表現に置き換えられます。

好きなだけレイアウトを作ることができます。 **src/Template/Layout** ディレクトリーに置いて、 コントローラーのアクションの中か、ビューの `$layout` プロパティーで切り替えるだけです。 :

    // コントローラーから
    public function view()
    {
        // レイアウトの設定
        $this->viewBuilder()->setLayout('admin');
    
        // 3.4 以前
        $this->viewBuilder()->layout('admin');
    
        // 3.1 以前
        $this->layout = 'admin';
    }
    
    // ビューファイルから
    $this->layout = 'loggedin';

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

例えば、サイトに小さな広告バナー枠があるとすれば、小さな広告枠のある新しいレイアウトを作って、 以下のように全コントローラーのアクションで指定するかもしれません。 :

    namespace App\Controller;
    
    class UsersController extends AppController
    {
        public function viewActive()
        {
            $this->set('title', 'アクティブユーザー表示');
            $this->viewBuilder()->setLayout('default_small_ad');
    
            // あるいは 3.4 以前では以下
            $this->viewBuilder()->layout('default_small_ad');
    
            // あるいは 3.1 以前では以下
            $this->layout = 'default_small_ad';
        }
    
        public function viewImage()
        {
            $this->viewBuilder()->setLayout('image');
    
            // ユーザー画像の出力
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  

既定のレイアウトの他に CakePHP の公式スケルトン app は 'ajax' レイアウトも持っています。 Ajax レイアウトは AJAX のレスポンスを組み立てるのに便利で、これは空のレイアウトです。 (ほとんどの AJAX 呼び出しは、完全に描画されたインターフェイスというよりも、 返却にちょっとしたマークアップを必要とするだけです。)

スケルトン app は RSS を生成するのを手助けする既定のレイアウトも持っています。

### プラグインのレイアウト使用 [​](https://book.cakephp.org/3.x/ja/views.html#%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E3%81%AE%E3%83%AC%E3%82%A4%E3%82%A2%E3%82%A6%E3%83%88%E4%BD%BF%E7%94%A8)

もしプラグインに存在するレイアウトを使いたい場合、 `プラグイン記法` を使うことが出来ます。例えば、 Contacts プラグインの contact レイアウトを使うには 次のようにします。 :

    namespace App\Controller;
    
    class UsersController extends AppController
    {
        public function viewActive()
        {
            $this->viewBuilder()->setLayout('Contacts.contact');
            // あるいは 3.4 以前では以下
            $this->viewBuilder()->layout('Contacts.contact');
            // あるいは 3.1 以前では以下
            $this->layout = 'Contacts.contact';
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

エレメント [​](https://book.cakephp.org/3.x/ja/views.html#%E3%82%A8%E3%83%AC%E3%83%A1%E3%83%B3%E3%83%88)

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

`method` Cake\\View\\View::**element**(string $elementPath, array $data, array $options = \[\])

多くのアプリケーションは、様々なページで、時には異なるレイアウトのページで、 繰り返し必要とされる表示コードの小さなブロックを持っています。CakePHP は再利用が必要な ウェブサイトのパーツを繰り返し使う手助けをします。この再利用可能なパーツはエレメントと 呼ばれます。広告、ヘルプボックス、ナビゲーションコントロール、追加のメニュー、 ログインフォーム、吹き出しは CakePHP ではしばしばエレメントとして実装されます。 エレメントは基本的に他のビュー、レイアウト、そして他のエレメントにさえも入れることができる 小さなビューです。エレメントは、繰り返し使う要素の描画を個別のファイルに収めるので、 ビューの可読性を高めるのに使えます。 アプリケーション内のコンテンツの一部を再利用する手助けにもなります。

エレメントは **src/Template/Element/** フォルダーの中に .ctp の拡張子を持つ名前で配置されます。 次の例はビューの element メソッドを使って出力しています。 :

    echo $this->element('helpbox');

1  

### エレメントに変数を渡す [​](https://book.cakephp.org/3.x/ja/views.html#%E3%82%A8%E3%83%AC%E3%83%A1%E3%83%B3%E3%83%88%E3%81%AB%E5%A4%89%E6%95%B0%E3%82%92%E6%B8%A1%E3%81%99)

element メソッドの第二引数を通してエレメントにデータを渡すことができます。 :

    echo $this->element('helpbox', [\
        "helptext" => "おお、このテキストはとても役に立つ。"\
    ]);

1  
2  
3  

エレメントファイルの内部では、引数で渡されたすべての変数を パラメーター配列のメンバーとして利用できます。(テンプレートファイルにおけるコントローラーの `Controller::set()` メソッドと同様の動作です。) 上記の例では **src/Template/Element/helpbox.ctp** の中で `$helptext` 変数が使えます。 :

    // src/Template/Element/helpbox.ctp の中で
    echo $helptext; // 出力 "おお、このテキストはとても役に立つ。"

1  
2  

`View::element()` メソッドは、エレメントのためのオプションもサポートしています。 サポートされるオプションは、 'cache' と 'callbacks' です。例えば:

    echo $this->element('helpbox', [\
            "helptext" => "これはエレメントに $helptext として渡されます",\
            "foobar" => "これはエレメントに $foobar として渡されます",\
        ],
        [\
            // "long_view" のキャッシュ設定を使います\
            "cache" => "long_view",\
            // エレメントから before/afterRender が呼び出されるには true に設定してください\
            "callbacks" => true\
        ]
    );

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

エレメントは `Cache` クラスを通じてキャッシュされます。 設定済みのキャッシュのいずれかにエレメントが保存されるように設定できます。 その結果、何処にいつまでエレメントを保存しておくのかを非常に柔軟に制御することができます。 あるアプリケーションの中で同じエレメントの異なるバージョンをキャッシュするためには、 次の書式を使って一意のキャッシュキーを提供してください。 :

    $this->element('helpbox', [], [\
            "cache" => ['config' => 'short', 'key' => 'unique value']\
        ]
    );

1  
2  
3  
4  

もしもエレメント中で、データソースからの動的なデータのような、さらなるロジックが必要であれば、 エレメントの代わりにビューセルを使用することを検討してください。 詳細は [ビューセルについて](https://book.cakephp.org/3.x/ja/views/cells.html)
 参照してください。

### エレメントのキャッシュ [​](https://book.cakephp.org/3.x/ja/views.html#%E3%82%A8%E3%83%AC%E3%83%A1%E3%83%B3%E3%83%88%E3%81%AE%E3%82%AD%E3%83%A3%E3%83%83%E3%82%B7%E3%83%A5)

キャッシュパラメーターを渡すだけで CakePHP のビューキャッシュの恩恵を得られます。 `true` を渡した場合、 'default' のキャッシュ設定に基づいてエレメントがキャッシュされます。 あるいは、どのキャッシュ設定を使うかを設定することができます。 `Cache` の設定についての詳細は [キャッシュ](https://book.cakephp.org/3.x/ja/core-libraries/caching.html)
 を参照してください。 エレメントキャッシュの単純な例は以下のようになります。 :

    echo $this->element('helpbox', [], ['cache' => true]);

1  

あるビューの中で同じエレメントを二回以上描画し、かつキャッシュが有効であれば、 毎回異なる名前の 'key' パラメーターを設定するようにしてください。 後続の呼び出しが、その前の `element()` の呼び出しでキャッシュされた結果を 上書してしまうのを避けることができるでしょう。例えば:

    echo $this->element(
        'helpbox',
        ['var' => $var],
        ['cache' => ['key' => 'first_use', 'config' => 'view_long']]
    );
    
    echo $this->element(
        'helpbox',
        ['var' => $differenVar],
        ['cache' => ['key' => 'second_use', 'config' => 'view_long']]
    );

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

上の例は、双方の element() の結果が別々にキャッシュされるようにします。 もしすべてのエレメントのキャッシュで同じ設定を使いたい場合、 `View::$elementCache` を設定することで繰り返しを避けられます。 CakePHP は element() に何も渡されなかった場合、この設定を使います。

### プラグインのエレメントの要求 [​](https://book.cakephp.org/3.x/ja/views.html#%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E3%81%AE%E3%82%A8%E3%83%AC%E3%83%A1%E3%83%B3%E3%83%88%E3%81%AE%E8%A6%81%E6%B1%82)

もしプラグインを使っていて、そのプラグインのエレメントを使いたければ、慣れ親しんだ `プラグイン記法` を使うだけでよいです。もしもビューが プラグインのコントローラー/アクションで描画される場合、他のプラグイン名が渡されなければ、 使用されるすべてのエレメントに対して自動的にそのプラグイン名が接頭されます。 もしエレメントがプラグインに存在しない場合、メインの APP フォルダーの中を探します。 :

    echo $this->element('Contacts.helpbox');

1  

もしビューがプラグインの一部であれば、プラグイン名を省略できます。 例えば、Contacts プラグインの `ContactsController` の中にいる場合、次の:

    echo $this->element('helpbox');
    // と
    echo $this->element('Contacts.helpbox');

1  
2  
3  

は等価で、描画されるエレメントは同じになります。

プラグインのサブフォルダー中のエレメント (例: **plugins/Contacts/Template/Element/sidebar/helpbox.ctp**) については、 以下を使ってください。 :

    echo $this->element('Contacts.sidebar/helpbox');

1  

### ルーティングプレフィックスとエレメント [​](https://book.cakephp.org/3.x/ja/views.html#%E3%83%AB%E3%83%BC%E3%83%86%E3%82%A3%E3%83%B3%E3%82%AF%E3%82%99%E3%83%95%E3%82%9A%E3%83%AC%E3%83%95%E3%82%A3%E3%83%83%E3%82%AF%E3%82%B9%E3%81%A8%E3%82%A8%E3%83%AC%E3%83%A1%E3%83%B3%E3%83%88)

Added in version 3.0.1

ルーティングプレフィックスを設定している場合、レイアウトやビューがそうであるように、 エレメントのパスの解決は、プレフィックスの場所に切り替わります。 "Admin" プレフィックスが設定されていて、次のように呼ぶとすれば:

    echo $this->element('my_element');

1  

エレメントはまず **src/Template/Admin/Element/** から探されます。 もしもファイルが存在しなければ、既定の場所から探されます。

### ビューの断片のキャッシュ [​](https://book.cakephp.org/3.x/ja/views.html#%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC%E3%81%AE%E6%96%AD%E7%89%87%E3%81%AE%E3%82%AD%E3%83%A3%E3%83%83%E3%82%B7%E3%83%A5)

`method` Cake\\View\\View::**cache**(callable $block, array $options = \[\])

時には、ビュー出力の断片を生成するのに時間がかかることがあります。 たとえば、 [ビューセル](https://book.cakephp.org/3.x/ja/views/cells.html)
 の描画や、時間のかかるヘルパーの操作など。 アプリケーションの実行を速くする手助けのために、 CakePHP はビューの断片をキャッシュする方法を提供します。 :

    // ローカル変数を想定しています
    echo $this->cache(function () use ($user, $article) {
        echo $this->cell('UserProfile', [$user]);
        echo $this->cell('ArticleFull', [$article]);
    }, ['key' => 'my_view_key']);

1  
2  
3  
4  
5  

既定ではキャッシュされたビューの内容は `View::$elementCache` のキャッシュ設定になりますが、 これを変更するために `config` オプションを使用できます。

ビューイベント [​](https://book.cakephp.org/3.x/ja/views.html#%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC%E3%82%A4%E3%83%98%E3%82%99%E3%83%B3%E3%83%88)

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

コントローラーと同様、ビューは、描画のライフサイクル回りのロジックを入れるために、 いくつかのイベント/コールバックを呼び出すことができます。

### イベント一覧 [​](https://book.cakephp.org/3.x/ja/views.html#%E3%82%A4%E3%83%98%E3%82%99%E3%83%B3%E3%83%88%E4%B8%80%E8%A6%A7)

*   `View.beforeRender`
*   `View.beforeRenderFile`
*   `View.afterRenderFile`
*   `View.afterRender`
*   `View.beforeLayout`
*   `View.afterLayout`

アプリケーションの [イベントリスナー](https://book.cakephp.org/3.x/ja/core-libraries/events.html)
 をこれらのイベントに アタッチする、または [ヘルパーコールバック](https://book.cakephp.org/3.x/ja/views/helpers.html#helper-api)
 を使うことができます。

独自のビュークラス作成 [​](https://book.cakephp.org/3.x/ja/views.html#%E7%8B%AC%E8%87%AA%E3%81%AE%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC%E3%82%AF%E3%83%A9%E3%82%B9%E4%BD%9C%E6%88%90)

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

データビューの新しいタイプを有効にしたり、 付加的なカスタムのビュー描画ロジックをアプリケーションに追加するために、 カスタムビュークラスを作成する必要があるかもしれません。 CakePHP のほとんどの構成要素と同様に、ビュークラスにはいくつかの規約があります。

*   ビュークラスは **src/View** に配置してください。例: **src/View/PdfView.php**
*   ビュークラス名には `View` をサフィックスとしてつけてください。 例: `PdfView`
*   ビュークラス名を参照するときは `View` サフィックスを省略する必要があります。 例: `$this->viewBuilder()->setClassName('Pdf');`.

また、正しく動作するように、 `View` を継承しましょう。 :

    // src/View/PdfView.php の中で
    namespace App\View;
    
    use Cake\View\View;
    
    class PdfView extends View
    {
        public function render($view = null, $layout = null)
        {
            // カスタムロジックをここに。
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

render メソッドを置き換えると、コンテンツがレンダリングされる方法を完全に制御できます。

ビューのより詳細 [​](https://book.cakephp.org/3.x/ja/views.html#%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC%E3%81%AE%E3%82%88%E3%82%8A%E8%A9%B3%E7%B4%B0)

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

*   [ビューセル](https://book.cakephp.org/3.x/ja/views/cells.html)
    
*   [テーマ](https://book.cakephp.org/3.x/ja/views/themes.html)
    
*   [JSON と XML ビュー](https://book.cakephp.org/3.x/ja/views/json-and-xml-views.html)
    
*   [ヘルパー](https://book.cakephp.org/3.x/ja/views/helpers.html)

---

# コンテンツ管理チュートリアル | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/installation.html#VPContent)

Return to top

コンテンツ管理チュートリアル [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/installation.html#%E3%82%B3%E3%83%B3%E3%83%86%E3%83%B3%E3%83%84%E7%AE%A1%E7%90%86%E3%83%81%E3%83%A5%E3%83%BC%E3%83%88%E3%83%AA%E3%82%A2%E3%83%AB)

================================================================================================================================================================================================================================

このチュートリアルは簡単な `CMS (Content Management System)` アプリケーションを作ります。 はじめに CakePHP のインストールを行い、データベースの作成、 そしてアプリケーションを素早く仕上げるための CakePHP が提供するツールを使います。

必要なもの:

1.  データベースサーバー。このチュートリアルでは MySQL サーバーを使います。 データベースを作成するための SQL の知識が必要です。CakePHP は、それを前提としています。 MySQL を使用するとき、 PHP で `pdo_mysql` が有効になっていることを確認してください。
2.  基礎的な PHP の知識。

始める前に、最新の PHP バージョンであることを確認してください。

    php -v

1  

最低でも PHP _5.6_ (CLI) 以上をインストールしてください。 あなたのウェブサーバーの PHP バージョンもまた、 _5.6_ 以上でなければなりません。 そして、コマンドラインインターフェイス (CLI) の PHP バージョンと同じバージョンにしてください。

CakePHP の取得 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/installation.html#cakephp-%E3%81%AE%E5%8F%96%E5%BE%97)

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

最も簡単な CakePHP のインストール方法は Composer を使う方法です。Composer は、 ターミナルやコマンドラインプロンプトから CakePHP をインストールのシンプルな方法です。 まだ準備ができていない場合、最初に Composer をダウンロードとインストールが必要です。 cURL がインストールされていたら、次のように実行するのが簡単です。

    curl -s https://getcomposer.org/installer | php

1  

もしくは [Composer のウェブサイト](https://getcomposer.org/download/)
 から `composer.phar` をダウンロードすることができます。

そして、インストールディレクトリーからターミナルに次の行を入力するだけで、現在の作業ディレクトリーの **cms** ディレクトリーに CakePHP アプリケーションのスケルトンをインストールすることができます。

    php composer.phar create-project --prefer-dist cakephp/app:^3.8 cms

1  

[Composer Windows Installer](https://getcomposer.org/Composer-Setup.exe)
 をダウンロードして実行した場合、インストールディレクトリー (例えば、 C:\\wamp\\www\\dev\\cakephp3) からターミナルに次の行を入力してください。

    composer self-update && composer create-project --prefer-dist cakephp/app:^3.8 cms

1  

Composer を使うメリットは、 正しいファイルパーミッションの設定や、 **config/app.php** ファイルの作成などのように、自動的に完全なセットアップをしてくれることです。

CakePHP をインストールする他の方法があります。 Composer を使いたくない場合、 [インストール](https://book.cakephp.org/3.x/ja/installation.html)
 セクションをご覧ください。

CakePHP のダウンロードやインストール方法にかかわらず、いったんセットアップが完了すると、 ディレクトリー構成は次のようになります。 :

    /cms
      /bin
      /config
      /logs
      /plugins
      /src
      /tests
      /tmp
      /vendor
      /webroot
      .editorconfig
      .gitignore
      .htaccess
      .travis.yml
      composer.json
      index.php
      phpunit.xml.dist
      README.md
    

CakePHP のディレクトリー構造がどのように働くかを学ぶのにいい機会かもしれません。 [CakePHP のフォルダー構成](https://book.cakephp.org/3.x/ja/intro/cakephp-folder-structure.html)
 セクションをご覧ください。

このチュートリアルで迷ったら、 [GitHub](https://github.com/cakephp/cms-tutorial)
 で完成した結果を見ることができます。

インストールの確認 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/installation.html#%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB%E3%81%AE%E7%A2%BA%E8%AA%8D)

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

デフォルトホームページを確認することで、インストールが正しいことをざっと確かめることができます。 その前に、開発用サーバーを起動する必要があります。

    cd /path/to/our/app
    
    bin/cake server

1  
2  
3  

NOTE

Windows では、このコマンドは `bin\cake server` (バックスラッシュ) です。

これで、 8765 ポートで PHP のビルトインウェブサーバーが起動します。ウェルカムページを見るために **[http://localhost:8765](http://localhost:8765/)
** をウェブブラウザーで開いてください。CakePHP がデータベース接続が 可能かどうか以外は、すべての確認事項が緑色のコック帽になるべきです。そうでなければ、PHP 拡張の 追加のインストールやディレクトリーのパーミッション設定が必要かもしれません。

次に、 [データベースの構築と最初のモデルの作成](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/database.html)
 をします。

---

# クイック スタート - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/authorization/edit/3.x/docs/ja/index.rst)

[](https://book.cakephp.org/authorization/3/ja/index.html#page-contents)

### Page Contents

*   [クイック スタート](https://book.cakephp.org/authorization/3/ja/index.html#)
    *   [インストール](https://book.cakephp.org/authorization/3/ja/index.html#id2)
        
    *   [はじめに](https://book.cakephp.org/authorization/3/ja/index.html#id3)
        
    *   [より詳しく](https://book.cakephp.org/authorization/3/ja/index.html#id4)
        

クイック スタート[¶](https://book.cakephp.org/authorization/3/ja/index.html#id1 "この見出しへのパーマリンク")

=========================================================================================

インストール[¶](https://book.cakephp.org/authorization/3/ja/index.html#id2 "この見出しへのパーマリンク")

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

プラグインをインストールするには、CakePHPから [composer](https://getcomposer.org/)
 を プロジェクトのルートディレクトリ (**composer.json** がある場所) で使用します。

php composer.phar require "cakephp/authorization:^2.0"

Authorization Plugin(認可プラグイン)のバージョン2はCakePHP4に対応しています。

プラグインを読み込むにはApplication.phpに下記の一業を追加します。 `src/Application.php`

$this\->addPlugin('Authorization');

はじめに[¶](https://book.cakephp.org/authorization/3/ja/index.html#id3 "この見出しへのパーマリンク")

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

Authorization pluginは、ミドルウェア層としてアプリケーションに組み込まれ、 オプションのコンポーネントで認可の確認を容易に行え行えます。 はじめに **src/Application.php** に以下のクラス使用を明示してください。:

use Authorization\\AuthorizationService;
use Authorization\\AuthorizationServiceInterface;
use Authorization\\AuthorizationServiceProviderInterface;
use Authorization\\Middleware\\AuthorizationMiddleware;
use Authorization\\Policy\\OrmResolver;
use Psr\\Http\\Message\\ResponseInterface;
use Psr\\Http\\Message\\ServerRequestInterface;

Applicationに `AuthorizationServiceProviderInterface` を追加してください:

class Application extends BaseApplication implements AuthorizationServiceProviderInterface

そして、Applicationの `middleware()` を以下のようにします(AuthorizationMiddlewareを加える):

public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue
{
    // Middleware provided by CakePHP
    $middlewareQueue\->add(new ErrorHandlerMiddleware(Configure::read('Error')))
        \->add(new AssetMiddleware())
        \->add(new RoutingMiddleware($this))
        \->add(new BodyParserMiddleware())

        // If you are using Authentication it should be \*before\* Authorization.
        \->add(new AuthenticationMiddleware($this));

        // Add the AuthorizationMiddleware \*after\* routing, body parser
        // and authentication middleware.
        \->add(new AuthorizationMiddleware($this));

    return $middlewareQueue();
}

`AuthorizationMiddleware` は `AuthenticationMiddleware` の **後** に置く必要があります。 これにより、認可の確認で使用する `identity` が使用できるようになります。

`AuthorizationMiddleware` はリクエスト処理が開始した際に、フックメソッドを呼び出します。 このフックメソッドで、使用したい `AuthorizationService` を定義できます。 以下のメソッドを **src/Application.php** に追加してください。:

public function getAuthorizationService(ServerRequestInterface $request): AuthorizationServiceInterface
{
    $resolver \= new OrmResolver();

    return new AuthorizationService($resolver);
}

これは、ORMエンティティとPolicyクラスをマッチングする、基本的な [ポリシーリゾルバー](https://book.cakephp.org/authorization/3/ja/policy-resolvers.html)
 を設定するものです。

次に、　`AppController` に `AuthorizationComponent` を加えます。 **src/Controller/AppController.php** の `initialize()` に下記を追加してください。:

$this\->loadComponent('Authorization.Authorization');

[AuthorizationComponent](https://book.cakephp.org/authorization/3/ja/component.html)
 を読み込むことで、以下のような認可チェックを行うことができます。

> public function edit($id = null) {
> 
> > $article = $this->Article->get($id); $this->Authorization->authorize($article, 'update');
> > 
> > // Rest of action
> 
> }

`authorize` を呼び出すことで、 [Policies](https://book.cakephp.org/authorization/3/ja/policies.html)
 を使用して、アクセス制御ルールを強制することができます。 [identity stored in the request](https://book.cakephp.org/authorization/3/ja/checking-authorization.html)
 を使えばどこでも権限を確認することができます。

より詳しく[¶](https://book.cakephp.org/authorization/3/ja/index.html#id4 "この見出しへのパーマリンク")

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

*   [Policies](https://book.cakephp.org/authorization/3/ja/policies.html)
    
*   [ポリシーリゾルバー](https://book.cakephp.org/authorization/3/ja/policy-resolvers.html)
    
*   [認可ミドルウェア](https://book.cakephp.org/authorization/3/ja/middleware.html)
    
*   [AuthorizationComponent](https://book.cakephp.org/authorization/3/ja/component.html)
    
*   [認可の確認](https://book.cakephp.org/authorization/3/ja/checking-authorization.html)
    
*   [リクエスト認証ミドルウェア](https://book.cakephp.org/authorization/3/ja/request-authorization-middleware.html)
    

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# Quick Start - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/authentication/edit/3.x/docs/ja/index.rst)

[](https://book.cakephp.org/authentication/3/ja/index.html#page-contents)

### Page Contents

*   [Quick Start](https://book.cakephp.org/authentication/3/ja/index.html#)
    *   [はじめに](https://book.cakephp.org/authentication/3/ja/index.html#id1)
        
    *   [ログインアクションの構成](https://book.cakephp.org/authentication/3/ja/index.html#id3)
        
    *   [Further Reading](https://book.cakephp.org/authentication/3/ja/index.html#further-reading)
        

Quick Start[¶](https://book.cakephp.org/authentication/3/ja/index.html#quick-start "このヘッドラインへのパーマリンク")

=======================================================================================================

CakePHPから [composer](https://getcomposer.org/)
 でプラグインをインストールします。 プロジェクトのルートディレクトリ( **composer.json** ファイルが置かれている場所です)

php composer.phar require "cakephp/authentication:^2.0"

プロジェクトの `src/Application.php` に以下の文を追加してプラグインをロードしてください。

public function bootstrap(): void
{
    parent::bootstrap();

    $this\->addPlugin('Authentication');
}

はじめに[¶](https://book.cakephp.org/authentication/3/ja/index.html#id1 "このヘッドラインへのパーマリンク")

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

認証プラグインは、ミドルウェアとしてアプリケーションと統合します。 [middleware](https://book.cakephp.org/4/en/controllers/middleware.html)
 また、認証されていないアクセスをより簡単にするためのコンポーネントとして使用することもできます。 まずはミドルウェアを適用してみましょう。

**src/Application.php** に以下のクラスを追加します。

インポート:

use Authentication\\AuthenticationService;
use Authentication\\AuthenticationServiceInterface;
use Authentication\\AuthenticationServiceProviderInterface;
use Authentication\\Identifier\\AbstractIdentifier;
use Authentication\\Middleware\\AuthenticationMiddleware;
use Cake\\Http\\MiddlewareQueue;
use Psr\\Http\\Message\\ServerRequestInterface;

次に、アプリケーションに実装されたインターフェースに `AuthenticationProviderInterface` を追加します。:

class Application extends BaseApplication implements AuthenticationServiceProviderInterface

次に、 `middleware()` メソッドに以下の AuthenticationMiddleware を追加します。:

$middleware\->add(new AuthenticationMiddleware($this));

注釈

両方ある場合は `AuthenticationMiddleware` の前に `AuthorizationMiddleware` を追加するようにしてください。

リクエストの処理を開始すると、 `AuthenticationMiddleware` はフックメソッドを呼び出します。 このフックメソッドにより、アプリケーションが使用したい `AuthenticationService` を定義することができます。 以下のメソッドを **src/Application.php** に記述します。:

/\*\*
 \* サービスプロバイダのインスタンスを返します。
 \*
 \* @param \\Psr\\Http\\Message\\ServerRequestInterface $request Request
 \* @return \\Authentication\\AuthenticationServiceInterface
 \*/
public function getAuthenticationService(ServerRequestInterface $request): AuthenticationServiceInterface
{
    $service \= new AuthenticationService();

    // 認証されていない場合にユーザーがどこにリダイレクトするかを定義します。
    $service\->setConfig(\[\
        'unauthenticatedRedirect' \=> '/users/login',\
        'queryParam' \=> 'redirect',\
    \]);

    $fields \= \[\
        AbstractIdentifier::CREDENTIAL\_USERNAME \=> 'email',\
        AbstractIdentifier::CREDENTIAL\_PASSWORD \=> 'password'\
    \];

    // 認証者を読み込みます。セッションを優先してください。
    $service\->loadAuthenticator('Authentication.Session');
    $service\->loadAuthenticator('Authentication.Form', \[\
        'fields' \=> $fields,\
        'loginUrl' \=> '/users/login'\
    \]);

    // 識別子を読み込みます。
    $service\->loadIdentifier('Authentication.Password', compact('fields'));

    return $service;
}

まず、ユーザーが認証されていない場合にどうするかを設定します。 次に、アプリケーションがユーザーを認証するための仕組みを定義する `Session` と `Form` [認証機能](https://book.cakephp.org/authentication/3/ja/authenticators.html)
 をアタッチします。 `Session` はセッション内のデータに基づいてユーザを識別し、 `Form` はログインフォームを `loginUrl` で扱うことを可能にします。

最後に、ログインしたユーザーを表す [identifier](https://book.cakephp.org/authentication/3/ja/identifiers.html)
 に変換するための [identity](https://book.cakephp.org/authentication/3/ja/identity-object.html)
 をアタッチします。

認証が確認できた場合、ミドルウェアは認証サービスを [属性](https://www.php-fig.org/psr/psr-7/)
. としてリクエストオブジェクトに追加します。

次に、 `AppController` に [認証 Component](https://book.cakephp.org/authentication/3/ja/authentication-component.html)
 を呼び出します。:

// in src/Controller/AppController.php
public function initialize()
{
    parent::initialize();

    $this\->loadComponent('Authentication.Authentication');
}

デフォルトでコンポーネントは、 **全て** のアクションに認証済みのユーザーを必要とします。 特定のコントローラでこの動作を無効にするには、 `allowUnauthenticated()` を使用してください。:

// コントローラの beforeFilter か initialize で、
// ログインしている必要のないview()とindex()を作成します。
$this\->Authentication\->allowUnauthenticated(\['view', 'index'\]);

ログインアクションの構成[¶](https://book.cakephp.org/authentication/3/ja/index.html#id3 "このヘッドラインへのパーマリンク")

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

アプリケーションにミドルウェアを適用したら、ユーザーがログインするための方法が必要になります。 基本的に次のように `UsersController` にloginアクションと追加します。:

public function login()
{
    $result \= $this\->Authentication\->getResult();
    // ユーザーがログインしている場合は、そのユーザーを送り出してください。
    if ($result\->isValid()) {
        $target \= $this\->Authentication\->getLoginRedirect() ?? '/home';
        return $this\->redirect($target);
    }
    if ($this\->request\->is('post')) {
        $this\->Flash\->error('ユーザー名とパスワードが無効です');
    }
}

前のセクションで述べたように、コントローラの `beforeFilter()` コールバックで `login` アクションにアクセスできるようにして、 認証されていないユーザがアクセスできるようにしてください。:

public function beforeFilter(\\Cake\\Event\\EventInterface $event)
{
    parent::beforeFilter($event);

    $this\->Authentication\->allowUnauthenticated(\['login'\]);
}

シンプルなlogoutアクションの追加:

public function logout()
{
    $this\->Authentication\->logout();
    return $this\->redirect(\['controller' \=> 'Users', 'action' \=> 'login'\]);
}

ログインするためには、ユーザーはハッシュ化されたパスワードを持つ必要があります。以下のようなことができます。 ユーザーがエンティティを使用してパスワードを更新すると、自動的にパスワードをハッシュ化します。:

// in src/Model/Entity/User.php
use Authentication\\PasswordHasher\\DefaultPasswordHasher;

class User extends Entity
{
    // ... other methods

    // Automatically hash passwords when they are changed.
    protected function \_setPassword(string $password)
    {
        $hasher \= new DefaultPasswordHasher();
        return $hasher\->hash($password);
    }
}

Further Reading[¶](https://book.cakephp.org/authentication/3/ja/index.html#further-reading "このヘッドラインへのパーマリンク")

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

*   [認証機能](https://book.cakephp.org/authentication/3/ja/authenticators.html)
    
*   [Identifiers](https://book.cakephp.org/authentication/3/ja/identifiers.html)
    
*   [Password Hashers](https://book.cakephp.org/authentication/3/ja/password-hashers.html)
    
*   [Identity Objects](https://book.cakephp.org/authentication/3/ja/identity-object.html)
    
*   [認証 Component](https://book.cakephp.org/authentication/3/ja/authentication-component.html)
    
*   [認証コンポーネントから移行](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html)
    
*   [URL チェッカー](https://book.cakephp.org/authentication/3/ja/url-checkers.html)
    
*   [認証によるテスト](https://book.cakephp.org/authentication/3/ja/testing.html)
    
*   [View Helper](https://book.cakephp.org/authentication/3/ja/view-helper.html)
    

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# アップグレードツール | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/upgrade-tool.html#VPContent)

Return to top

アップグレードツール [​](https://book.cakephp.org/3.x/ja/upgrade-tool.html#%E3%82%A2%E3%83%83%E3%83%95%E3%82%9A%E3%82%AF%E3%82%99%E3%83%AC%E3%83%BC%E3%83%88%E3%82%99%E3%83%84%E3%83%BC%E3%83%AB)

========================================================================================================================================================================================

CakePHP 2.x から CakePHP 3 にアップグレードするためには、多くの変換が必要となります。 それは、名前空間を追加するなど、自動化することができます。これらの機械的な変換を容易に 作成することを支援するために、CakePHP は CLI ベースのアップグレードツールを提供します。

インストール [​](https://book.cakephp.org/3.x/ja/upgrade-tool.html#%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB)

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

アップグレードツールは、スタンドアロンアプリケーションとしてインストールされています。 アップグレードツールを git clone して、composer で依存関係をインストールする必要があります。 :

    git clone https://github.com/cakephp/upgrade.git
    cd upgrade
    php ../composer.phar install
    

この時点で、アップグレードツールのヘルプを確認することができます。 :

    cd upgrade
    bin/cake upgrade --help
    

上記の出力は次のようになります。 :

    Welcome to CakePHP v3.0.8 Console
    ---------------------------------------------------------------
    App : src
    Path: /Users/markstory/Sites/cake_plugins/upgrade/src/
    ---------------------------------------------------------------
    A shell to help automate upgrading from CakePHP 2.x to 3.x. Be sure to
    have a backup of your application before running these commands.
    
    Usage:
    cake upgrade [subcommand] [-h] [-v] [-q]
    
    Subcommands:
    
    locations           Move files/directories around. Run this *before*
                        adding namespaces with the namespaces command.
    namespaces          Add namespaces to files based on their file path.
                        Only run this *after* you have moved files.
    app_uses            Replace App::uses() with use statements
    rename_classes      Rename classes that have been moved/renamed. Run
                        after replacing App::uses() with use statements.
    rename_collections  Rename HelperCollection, ComponentCollection, and
                        TaskCollection. Will also rename component
                        constructor arguments and _Collection properties on
                        all objects.
    method_names        Update many of the methods that were renamed during
                        2.x -> 3.0
    method_signatures   Update many of the method signatures that were
                        changed during 2.x -> 3.0
    fixtures            Update fixtures to use new index/constraint
                        features. This is necessary before running tests.
    tests               Update test cases regarding fixtures.
    i18n                Update translation functions regarding placeholders.
    skeleton            Add basic skeleton files and folders from the "app"
                        repository.
    prefixed_templates  Move view templates for prefixed actions.
    all                 Run all tasks except for skeleton. That task should
                        only be run manually, and only for apps (not
                        plugins).
    
    To see help on a subcommand use `cake upgrade [subcommand] --help`
    
    Options:
    
    --help, -h     Display this help.
    --verbose, -v  Enable verbose output.
    --quiet, -q    Enable quiet output.

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40  
41  
42  
43  
44  
45  
46  

使用法 [​](https://book.cakephp.org/3.x/ja/upgrade-tool.html#%E4%BD%BF%E7%94%A8%E6%B3%95)

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

アップグレードツールを正しくインストールしたら、2.x のアプリケーションに対して 使用を開始する準備ができています。

WARNING

アプリケーションのコードのバックアップやバージョン管理していることを確認してください。

各サブコマンドの後にバックアップやコミットすることも良いアイデアです。

`locations` コマンドの実行を開始するには:

    # コマンドのオプションを表示
    bin/cake upgrade locations --help
    
    # dry run モードでコマンドを実行
    bin/cake upgrade locations --dry-run /path/to/app

1  
2  
3  
4  
5  

上記は、何が起こるかの予行演習の出力が得られます。実際にコマンドを実行する準備ができたら、 `--dry-run` フラグを削除します。 `--git` フラグを使用することにより、 アップグレードツールは git の内のファイルの移動を自動化することができます。

ファイルの場所が更新されたら、 `namespaces` コマンドを使用してコードに名前空間を 追加することができます。 :

    # コマンドのオプションを表示
    bin/cake upgrade namespaces --help
    
    # dry run モードでコマンドを実行
    bin/cake upgrade namespaces --dry-run /path/to/app
    
    # 実際にコマンドを実行
    bin/cake upgrade namespaces /path/to/app

1  
2  
3  
4  
5  
6  
7  
8  

この2つのコマンドの後、任意の順序で残りのサブコマンドを実行することができます。

---

# セキュリティ | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/security.html#VPContent)

Return to top

セキュリティ [​](https://book.cakephp.org/3.x/ja/security.html#%E3%82%BB%E3%82%AD%E3%83%A5%E3%83%AA%E3%83%86%E3%82%A3)

=================================================================================================================

CakePHP はあなたのアプリケーションをセキュアにする幾つかのツールを提供します。 以下のセクションにこれらのツールを記載します。

*   [セキュリティユーティリティ](https://book.cakephp.org/3.x/ja/core-libraries/security.html)
    
*   [クロスサイトリクエストフォージェリ](https://book.cakephp.org/3.x/ja/controllers/components/csrf.html)
    
*   [Security コンポーネント](https://book.cakephp.org/3.x/ja/controllers/components/security.html)

---

# CMS チュートリアル - 認証 | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/authentication.html#VPContent)

Return to top

CMS チュートリアル - 認証 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/authentication.html#cms-%E3%83%81%E3%83%A5%E3%83%BC%E3%83%88%E3%83%AA%E3%82%A2%E3%83%AB-%E8%AA%8D%E8%A8%BC)

============================================================================================================================================================================================

CMS にはユーザーがいますので、ログインできるようにし、 記事の作成と編集の経験に基本的なアクセス制御を適用する必要があります。

パスワードハッシュ化の追加 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/authentication.html#%E3%83%8F%E3%82%9A%E3%82%B9%E3%83%AF%E3%83%BC%E3%83%88%E3%82%99%E3%83%8F%E3%83%83%E3%82%B7%E3%83%A5%E5%8C%96%E3%81%AE%E8%BF%BD%E5%8A%A0)

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

もしこの時点でユーザーを作成・更新していたとしたら、パスワードが平文で保存されることに気付いたかもしれません。 これは、セキュリティの観点から本当に悪いことですので、修正しましょう。

これはまた、CakePHP のモデル層について話す良い時期です。CakePHP では、 オブジェクトのコレクションに対して操作するメソッドと、単一のオブジェクトを別のクラスに分けています。 エンティティーのコレクションに対して操作するメソッドは `Table` クラスにあり、 一方、単一のレコードに属する機能は `Entity` クラスにあります。

例えば、パスワードのハッシュ化は個々のレコードで行われるため、 この動作をエンティティーオブジェクトに実装します。パスワードが設定されるたびにパスワードを ハッシュ化したいので、ミューテーター/セッターメソッドを使用します。CakePHP は、 エンティティーの1つにプロパティーが設定されているときはいつでも、規約に基づいたセッターメソッドを呼び出します。 パスワードのセッターを追加しましょう。 **src/Model/Entity/User.php** の中に次を追加してください。 :

    <?php
    namespace App\Model\Entity;
    
    use Cake\Auth\DefaultPasswordHasher; // この行を追加
    use Cake\ORM\Entity;
    
    class User extends Entity
    {
    
        // bake のコード
    
        // このメソッドの追加
        protected function _setPassword($value)
        {
            if (strlen($value)) {
                $hasher = new DefaultPasswordHasher();
    
                return $hasher->hash($value);
            }
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  

ここで、ブラウザーで **[http://localhost:8765/users](http://localhost:8765/users)
** にアクセスしてユーザーのリストを 見てください。 [インストール](https://book.cakephp.org/3.x/ja/installation.html)
 中に作成されたデフォルトユーザーを 編集することができます。ユーザーのパスワードを変更すると、リストやビューページでは 元の値の代わりにハッシュ化されたパスワードが表示されます。CakePHP は、デフォルトでは [bcrypt](https://codahale.com/how-to-safely-store-a-password/)
 を使って パスワードをハッシュ化します。既存のデータベースを使用している場合は SHA-1 または MD5 を 使用することもできますが、すべての新しいアプリケーションに対して bcrypt を推奨します。

### ログインの追加 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/authentication.html#%E3%83%AD%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E3%81%AE%E8%BF%BD%E5%8A%A0)

CakePHP での認証は、 [コンポーネント](https://book.cakephp.org/3.x/ja/controllers/components.html)
 によって処理されます。コンポーネントは、 特定の機能やコンセプトに関連するコントローラーコードの再利用可能なかたまりを作成する方法と 考えることができます。コンポーネントは、コントローラーのイベントライフサイクルにフックし、 その方法でアプリケーションとやりとりすることができます。まず、 [AuthComponent](https://book.cakephp.org/3.x/ja/controllers/components/authentication.html)
 をアプリケーションに追加します。 create、update、delete メソッドで認証が必要なので、AuthComponent を AppController に追加します。 :

    // src/Controller/AppController.php の中で
    namespace App\Controller;
    
    use Cake\Controller\Controller;
    
    class AppController extends Controller
    {
        public function initialize()
        {
            // 既存のコード
    
            $this->loadComponent('Auth', [\
                'authenticate' => [\
                    'Form' => [\
                        'fields' => [\
                            'username' => 'email',\
                            'password' => 'password'\
                        ]\
                    ]\
                ],\
                'loginAction' => [\
                    'controller' => 'Users',\
                    'action' => 'login'\
                ],\
                // コントローラーで isAuthorized を使用します\
                'authorize' => ['Controller'],\
                // 未認証の場合、直前のページに戻します\
                'unauthorizedRedirect' => $this->referer()\
            ]);
    
            // display アクションを許可して、PagesController が引き続き
            // 動作するようにします。また、読み取り専用のアクションを有効にします。
            $this->Auth->allow(['display', 'view', 'index']);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  

CakePHP に `Auth` コンポーネントをロードするように指示しました。users テーブルは ユーザー名として `email` を使用するので、AuthComponent の設定をカスタマイズしました。 今、 `/articles/add` のような保護された URL に行くと、 **/users/login** に リダイレクトされます。これはまだコードを書いていないので、エラーページを表示します。 login アクションを作成しましょう。 :

    // src/Controller/UsersController.php の中で
    public function login()
    {
        if ($this->request->is('post')) {
            $user = $this->Auth->identify();
            if ($user) {
                $this->Auth->setUser($user);
                return $this->redirect($this->Auth->redirectUrl());
            }
            $this->Flash->error('ユーザー名またはパスワードが不正です。');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

そして **src/Template/Users/login.ctp** に次を追加してください。 :

    <h1>ログイン</h1>
    <?= $this->Form->create() ?>
    <?= $this->Form->control('email') ?>
    <?= $this->Form->control('password') ?>
    <?= $this->Form->button('ログイン') ?>
    <?= $this->Form->end() ?>

1  
2  
3  
4  
5  
6  

シンプルなログインフォームが完成したので、ハッシュ化されたパスワードを持つユーザーで ログインできるはずです。

NOTE

もし、ハッシュ化されたパスワードを持つユーザーがいない場合、 `loadComponent('Auth')` ブロックと `$this->Auth->allow()` 呼び出しを コメントにしてください。その後、ユーザーのパスワードを保存して編集します。 ユーザーの新しいパスワードを保存した後、一時的にコメントした行を元に戻してください。

さぁやってみましょう！ログインする前に `/articles/add` にアクセスしてください。 この操作は許可されていないため、ログインページにリダイレクトされます。 ログインに成功すると、CakePHP は自動的に `/articles/add` にリダイレクトします。

### ログアウトの追加 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/authentication.html#%E3%83%AD%E3%82%AF%E3%82%99%E3%82%A2%E3%82%A6%E3%83%88%E3%81%AE%E8%BF%BD%E5%8A%A0)

ユーザーがログインできるようになったので、おそらくログアウトする方法を提供したいと思うでしょう。 もう一度、 `UsersController` に次のコードを追加してください。 :

    public function initialize()
    {
        parent::initialize();
        $this->Auth->allow(['logout']);
    }
    
    public function logout()
    {
        $this->Flash->success('ログアウトしました。');
        return $this->redirect($this->Auth->logout());
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

このコードは、認証を必要としないアクションのリストに `logout` アクションを追加し、 logout メソッドを実装します。ログアウトのために `/users/logout` にアクセスできます。 その時、ログインページへ送られます。

### ユーザー登録の有効化 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/authentication.html#%E3%83%A6%E3%83%BC%E3%82%B5%E3%82%99%E3%83%BC%E7%99%BB%E9%8C%B2%E3%81%AE%E6%9C%89%E5%8A%B9%E5%8C%96)

ログインせずに **/users/add** にアクセスしようとすると、ログインページにリダイレクトされます。 人々がアプリケーションにサインアップできるようにしたいので、修正する必要があります。 `UsersController` に以下を追加してください。 :

    public function initialize()
    {
        parent::initialize();
        // 許可アクションリストに 'add' アクションを追加
        $this->Auth->allow(['logout', 'add']);
    }

1  
2  
3  
4  
5  
6  

上記の例は、 `AuthComponent` に、 `UsersController` の `add()` アクションが 認証や認可を必要と _しない_ ことを伝えています。 **Users/add.ctp** をクリーンアップし、 誤解を招くリンクを削除することに時間をかけたり、次のセクションに進みたいでしょう。 このチュートリアルでは、ユーザーの編集、表示、リスト作成は行いませんが、それはあなた自身で 行うことができる練習です。

### 記事へのアクセスの制限 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/authentication.html#%E8%A8%98%E4%BA%8B%E3%81%B8%E3%81%AE%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9%E3%81%AE%E5%88%B6%E9%99%90)

ユーザーはログインできるようになったので、作成した記事のみを編集するようにユーザーを 制限したいと考えています。 'authorization' アダプターを使用してこれを行います。 私たちの要件は基本的なものなので、 `ArticlesController` にコントローラーフックメソッドを 使うことができます。しかし、これを行う前に、アプリケーションがアクションを許可する方法を 「AuthComponent」に伝えたいと思うでしょう。 `AppController` を更新して次を追加してください。 :

    public function isAuthorized($user)
    {
        // デフォルトでは、アクセスを拒否します。
        return false;
    }

1  
2  
3  
4  
5  

次に、 `AuthComponent` にコントローラーのフックメソッドを使用して認可を行いたいことを伝えます。 `AppController::initialize()` メソッドは次のようになります。 :

    public function initialize()
    {
        // 既存のコード
    
        $this->loadComponent('Flash');
        $this->loadComponent('Auth', [\
            // この行を追加しました\
            'authorize'=> 'Controller',\
            'authenticate' => [\
                'Form' => [\
                    'fields' => [\
                        'username' => 'email',\
                        'password' => 'password'\
                    ]\
                ]\
            ],\
            'loginAction' => [\
                'controller' => 'Users',\
                'action' => 'login'\
            ],\
             // 未認証の場合、直前のページに戻します\
            'unauthorizedRedirect' => $this->referer()\
        ]);
    
        // display アクションを許可して、PagesController が引き続き
        // 動作するようにします。また、読み取り専用のアクションを有効にします。
        $this->Auth->allow(['display', 'view', 'index']);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  

デフォルトではアクセスを拒否し、意味のある場所で段階的にアクセスを許可します。 まず、記事の認可ロジックを追加します。 `ArticlesController` に以下を追加してください。 :

    public function isAuthorized($user)
    {
        $action = $this->request->getParam('action');
        // add および tags アクションは、常にログインしているユーザーに許可されます。
        if (in_array($action, ['add', 'tags'])) {
            return true;
        }
    
        // 他のすべてのアクションにはスラッグが必要です。
        $slug = $this->request->getParam('pass.0');
        if (!$slug) {
            return false;
        }
    
        // 記事が現在のユーザーに属していることを確認します。
        $article = $this->Articles->findBySlug($slug)->first();
    
        return $article->user_id === $user['id'];
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  

あなたに属していない記事を編集または削除しようとすると、元のページにリダイレクトされるはずです。 エラーメッセージが表示されない場合は、レイアウトに以下を追加します。 :

    // src/Template/Layout/default.ctp の中で
    <?= $this->Flash->render() ?>

1  
2  

次に、 **src/Controller/ArticlesController.php** の `initialize()` に以下を追加して、 未認証のユーザーに許可されたアクションに `tags` アクションを追加してください。 :

    $this->Auth->allow(['tags']);

1  

上記は非常に単純ですが、柔軟性のある認証ロジックを構築するために、現在のユーザーと リクエストデータを組み合わせたより複雑なロジックを構築する方法を示しています。

### add と edit アクションの修正 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/authentication.html#add-%E3%81%A8-edit-%E3%82%A2%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3%E3%81%AE%E4%BF%AE%E6%AD%A3)

edit アクションへのアクセスをブロックしていますが、編集中の記事の `user_id` 属性を変更することはできます。次に、これらの問題を解決します。 最初は `add` アクションです。

記事を作成するときに、 `user_id` を現在ログインしているユーザーに修正したいと考えています。 add アクションを次のように置き換えます。 :

    // src/Controller/ArticlesController.php の中で
    
    public function add()
    {
        $article = $this->Articles->newEntity();
        if ($this->request->is('post')) {
            $article = $this->Articles->patchEntity($article, $this->request->getData());
    
            // 変更: セッションから user_id をセット
            $article->user_id = $this->Auth->user('id');
    
            if ($this->Articles->save($article)) {
                $this->Flash->success(__('Your article has been saved.'));
                return $this->redirect(['action' => 'index']);
            }
            $this->Flash->error(__('Unable to add your article.'));
        }
        $this->set('article', $article);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  

次は `edit` アクションを更新します。edit メソッドを次のように置き換えます。 :

    // src/Controller/ArticlesController.php の中で
    
    public function edit($slug)
    {
        $article = $this->Articles
            ->findBySlug($slug)
            ->contain('Tags') // 関連づけられた Tags を読み込む
            ->firstOrFail();
    
        if ($this->request->is(['post', 'put'])) {
            $this->Articles->patchEntity($article, $this->request->getData(), [\
                // 追加: user_id の更新を無効化\
                'accessibleFields' => ['user_id' => false]\
            ]);
            if ($this->Articles->save($article)) {
                $this->Flash->success(__('Your article has been updated.'));
                return $this->redirect(['action' => 'index']);
            }
            $this->Flash->error(__('Unable to update your article.'));
        }
        $this->set('article', $article);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  

ここでは、 `patchEntity()` のオプションを使って、どのプロパティーを一括代入できるかを変更しています。 詳しい情報は、 [Changing Accessible Fields](https://book.cakephp.org/3.x/ja/orm/saving-data.html#changing-accessible-fields)
 セクションをご覧ください。 **src/Templates/Articles/edit.ctp** から必要のなくなった `user_id` コントロールを 削除してください。

### できあがり [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/authentication.html#%E3%81%A6%E3%82%99%E3%81%8D%E3%81%82%E3%81%8B%E3%82%99%E3%82%8A)

ユーザーがログインしたり、記事を投稿したり、タグ付けしたり、投稿された記事をタグで検索したり、 記事への基本的なアクセス制御を適用したりできるシンプルな CMS アプリケーションを構築しました。 また、FormHelper と ORM の機能を活用して、UX のいくつかの改良点を追加しました。

CakePHP の探検にお時間をいただきありがとうございます。 次は、 [データベースアクセス & ORM](https://book.cakephp.org/3.x/ja/orm.html)
 についてもっと学んだり、 [CakePHP の利用](https://book.cakephp.org/3.x/ja/topics.html)
 を調べてみてください。

---

# Flash | CakePHP

[Skip to content](https://book.cakephp.org/3.x/views/helpers/flash.html#VPContent)

Return to top

Flash [​](https://book.cakephp.org/3.x/views/helpers/flash.html#flash)

=======================================================================

`class` Cake\\View\\Helper\\**FlashHelper**(View $view, array $config = \[\])

FlashHelper provides a way to render flash messages that were set in `$_SESSION` by [FlashComponent](https://book.cakephp.org/3.x/controllers/components/flash.html)
. [FlashComponent](https://book.cakephp.org/3.x/controllers/components/flash.html)
 and FlashHelper primarily use elements to render flash messages. Flash elements are found under the **src/Template/Element/Flash** directory. You'll notice that CakePHP's App template comes with three flash elements: **success.ctp**, **default.ctp**, and **error.ctp**.

Rendering Flash Messages [​](https://book.cakephp.org/3.x/views/helpers/flash.html#rendering-flash-messages)

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

To render a flash message, you can simply use FlashHelper's `render()` method in your template file:

    <?= $this->Flash->render() ?>

1  

By default, CakePHP uses a "flash" key for flash messages in a session. But, if you've specified a key when setting the flash message in [FlashComponent](https://book.cakephp.org/3.x/controllers/components/flash.html)
, you can specify which flash key to render:

    <?= $this->Flash->render('other') ?>

1  

You can also override any of the options that were set in FlashComponent:

    // In your Controller
    $this->Flash->set('The user has been saved.', [\
        'element' => 'success'\
    ]);
    
    // In your template file: Will use great_success.ctp instead of succcess.ctp
    <?= $this->Flash->render('flash', [\
        'element' => 'great_success'\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  

NOTE

When building custom flash message templates, be sure to properly HTML encode any user data. CakePHP won't escape flash message parameters for you.

Added in version 3.1

The [FlashComponent](https://book.cakephp.org/3.x/controllers/components/flash.html)
 now stacks messages. If you set multiple flash messages, when you call `render()`, each message will be rendered in its own elements, in the order they were set.

For more information about the available array options, please refer to the [FlashComponent](https://book.cakephp.org/3.x/controllers/components/flash.html)
 section.

Routing Prefix and Flash Messages [​](https://book.cakephp.org/3.x/views/helpers/flash.html#routing-prefix-and-flash-messages)

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

Added in version 3.0.1

If you have a Routing prefix configured, you can now have your Flash elements stored in **src/Template/{Prefix}/Element/Flash**. This way, you can have specific messages layouts for each part of your application. For instance, using different layouts for your front-end and admin section.

Flash Messages and Themes [​](https://book.cakephp.org/3.x/views/helpers/flash.html#flash-messages-and-themes)

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

The FlashHelper uses normal elements to render the messages and will therefore obey any theme you might have specified. So when your theme has a **src/Template/Element/Flash/error.ctp** file it will be used, just as with any Elements and Views.

---

# Themes | CakePHP

[Skip to content](https://book.cakephp.org/3.x/views/themes.html#VPContent)

Return to top

Themes [​](https://book.cakephp.org/3.x/views/themes.html#themes)

==================================================================

Themes in CakePHP are simply plugins that focus on providing template files. See the section on [Plugin Create Your Own](https://book.cakephp.org/3.x/plugins.html#plugin-create-your-own)
. You can take advantage of themes, making it easy to switch the look and feel of your page quickly. In addition to template files, they can also provide helpers and cells if your theming requires that. When using cells and helpers from your theme, you will need to continue using the `plugin syntax`.

To use themes, set the theme name in your controller's action or `beforeRender()` callback:

    class ExamplesController extends AppController
    {
        // For CakePHP before 3.1
        public $theme = 'Modern';
    
        public function beforeRender(\Cake\Event\Event $event)
        {
            $this->viewBuilder()->setTheme('Modern');
    
            // For CakePHP before 3.5
            $this->viewBuilder()->theme('Modern');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

Theme template files need to be within a plugin with the same name. For example, the above theme would be found in **plugins/Modern/src/Template**. It's important to remember that CakePHP expects PascalCase plugin/theme names. Beyond that, the folder structure within the **plugins/Modern/src/Template** folder is exactly the same as **src/Template/**.

For example, the view file for an edit action of a Posts controller would reside at **plugins/Modern/src/Template/Posts/edit.ctp**. Layout files would reside in **plugins/Modern/src/Template/Layout/**. You can provide customized templates for plugins with a theme as well. If you had a plugin named 'Cms', that contained a TagsController, the Modern theme could provide **plugins/Modern/src/Template/Plugin/Cms/Tags/edit.ctp** to replace the edit template in the plugin.

If a view file can't be found in the theme, CakePHP will try to locate the view file in the **src/Template/** folder. This way, you can create master template files and simply override them on a case-by-case basis within your theme folder.

If your theme also acts as a plugin, don't forget to ensure it is loaded in your application's `bootstrap` method. For example:

    // Load our plugin theme residing in the folder /plugins/Modern
    $this->addPlugin('Modern');

1  
2  

Theme Assets [​](https://book.cakephp.org/3.x/views/themes.html#theme-assets)

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

Because themes are standard CakePHP plugins, they can include any necessary assets in their webroot directory. This allows for easy packaging and distribution of themes. Whilst in development, requests for theme assets will be handled by `Cake\Routing\Dispatcher`. To improve performance for production environments, it's recommended that you [Symlink Assets](https://book.cakephp.org/3.x/deployment.html#symlink-assets)
.

All of CakePHP's built-in helpers are aware of themes and will create the correct paths automatically. Like template files, if a file isn't in the theme folder, it will default to the main webroot folder:

    // When in a theme with the name of 'purple_cupcake'
    $this->Html->css('main.css');
    
    // creates a path like
    /purple_cupcake/css/main.css
    
    // and links to
    plugins/PurpleCupcake/webroot/css/main.css

1  
2  
3  
4  
5  
6  
7  
8

---

# データの検証 | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/orm/validation.html#VPContent)

Return to top

データの検証 [​](https://book.cakephp.org/3.x/ja/orm/validation.html#%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%81%AE%E6%A4%9C%E8%A8%BC)

================================================================================================================================

[データを保存する](https://book.cakephp.org/3.x/ja/orm/saving-data.html)
 前におそらくそのデータが正しく 矛盾がないことを保証したいはずです。 CakePHP ではデータの検証には二つの段階があります:

1.  リクエストデータがエンティティーにコンバートされる前、 データ型や書式まわりのバリデーションルールが適用されます。
2.  データが保存される前、ドメインまたはアプリケーションルールが適用されます。 これらのルールはアプリケーションのデータの一貫性の保証に役立ちます。

エンティティー構築前のデータ検証 [​](https://book.cakephp.org/3.x/ja/orm/validation.html#%E3%82%A8%E3%83%B3%E3%83%86%E3%82%A3%E3%83%86%E3%82%A3%E3%83%BC%E6%A7%8B%E7%AF%89%E5%89%8D%E3%81%AE%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E6%A4%9C%E8%A8%BC)

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

データからエンティティーを構築する時、データの検証 (バリデーション) ができます。 データのバリデーションではデータの型、形状およびサイズなどを確認することができます。 既定ではリクエストデータがエンティティーに変換される前に検証が行われます。 もしも何らかのバリデーションルールが通らなかった場合、 返されたエンティティーはエラーを含んだ状態になります。 エラーのあるフィールドは返されたエンティティーには含まれません。 :

    $article = $articles->newEntity($this->request->getData());
    if ($article->errors()) {
        // エンティティー検証失敗。
    }

1  
2  
3  
4  

Added in version 3.4.0

`getErrors()` 関数は追加されました。

バリデーションが有効になっている状態でエンティティーを構築すると、次のことが起こります:

1.  バリデータオブジェクトが作成されます。
2.  `table` および `default` バリデーションプロバイダーが追加されます。
3.  命名に沿ったバリデーションメソッドが呼び出されます。たとえば `validationDefault` 。
4.  `Model.buildValidator` イベントが発動します。
5.  リクエストデータが検証されます。
6.  リクエストデータがそのカラム型に対応する型に変換されます。
7.  エラーがエンティティーにセットされます。
8.  正しいデータはエンティティーに設定されますが、 検証を通らなかったフィールドは除外されます。

もしもリクエストデータを変換する時にバリデーションを無効にしたければ、 `validate` オプションに偽を指定してください。 :

    $article = $articles->newEntity(
        $this->request->getData(),
        ['validate' => false]
    );

1  
2  
3  
4  

`patchEntity()` メソッドについても同じことが言えます。 :

    $article = $articles->patchEntity($article, $newData, [\
        'validate' => false\
    ]);

1  
2  
3  

既定のバリデーションセットの作成 [​](https://book.cakephp.org/3.x/ja/orm/validation.html#%E6%97%A2%E5%AE%9A%E3%81%AE%E3%83%8F%E3%82%99%E3%83%AA%E3%83%86%E3%82%99%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%82%BB%E3%83%83%E3%83%88%E3%81%AE%E4%BD%9C%E6%88%90)

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

バリデーションルールは規約ではテーブルクラス中で定義されます。 何のデータが検証されるかとあわせてどこで保存されるかも定義します。

テーブル中で既定のバリデーションオブジェクトを作るには、 `validationDefault()` 関数を作成します。 :

    use Cake\ORM\Table;
    use Cake\Validation\Validator;
    
    class ArticlesTable extends Table
    {
        public function validationDefault(Validator $validator)
        {
            $validator
                ->requirePresence('title', 'create')
                ->notEmpty('title');
    
            $validator
                ->allowEmpty('link')
                ->add('link', 'valid-url', ['rule' => 'url']);
    
            ...
    
            return $validator;
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  

有効なバリデーションメソッドやルールは `Validator` クラスによって提供され [Creating Validators](https://book.cakephp.org/3.x/ja/core-libraries/validation.html#creating-validators)
 の節に記載されています。

NOTE

バリデーションオブジェクトは主にユーザー入力の検証用に意図されています。 たとえば、フォームやその他の投稿されたリクエストデータです。

異なるバリデーションセットの使用 [​](https://book.cakephp.org/3.x/ja/orm/validation.html#%E7%95%B0%E3%81%AA%E3%82%8B%E3%83%8F%E3%82%99%E3%83%AA%E3%83%86%E3%82%99%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%82%BB%E3%83%83%E3%83%88%E3%81%AE%E4%BD%BF%E7%94%A8)

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

バリデーションを無効にすることに加えて 適用させたいバリデーションルールを選ぶこともできます。 :

    $article = $articles->newEntity(
        $this->request->getData(),
        ['validate' => 'update']
    );

1  
2  
3  
4  

上記は必要なルールを構築するために、そのテーブルインスタンスの `validationUpdate()` メソッドを呼び出します。既定では `validationDefault()` メソッドが使用されます。 記事テーブル用のバリデータの一例はこのようになります。 :

    class ArticlesTable extends Table
    {
        public function validationUpdate($validator)
        {
            $validator
                ->add('title', 'notEmpty', [\
                    'rule' => 'notEmpty',\
                    'message' => __('タイトルを設定してください'),\
                ])
                ->add('body', 'notEmpty', [\
                    'rule' => 'notEmpty',\
                    'message' => __('本文は必須です')\
                ]);
            return $validator;
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  

必要に応じていくつものバリデーションセットを設けることができます。 バリデーションルールセットの構築についてのより多くの情報は [バリデーション](https://book.cakephp.org/3.x/ja/core-libraries/validation.html)
 を参照してください。

### アソシエーションに異なるバリデーションセットを使用 [​](https://book.cakephp.org/3.x/ja/orm/validation.html#%E3%82%A2%E3%82%BD%E3%82%B7%E3%82%A8%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%81%AB%E7%95%B0%E3%81%AA%E3%82%8B%E3%83%8F%E3%82%99%E3%83%AA%E3%83%86%E3%82%99%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%82%BB%E3%83%83%E3%83%88%E3%82%92%E4%BD%BF%E7%94%A8)

バリデーションセットはアソシエーションごとに定義することもできます。 `newEntity()` または `patchEntity()` メソッドを使用する時、 変換されるアソシエーション各々に追加のオプションを渡すことができます。 :

    $data = [\
         'title' => '私の肩書き',\
         'body' => 'テキスト',\
         'user_id' => 1,\
         'user' => [\
             'username' => 'マーク'\
         ],\
         'comments' => [\
             ['body' => '一番目のコメント'],\
             ['body' => '二番目のコメント'],\
         ]\
     ];
    
     $article = $articles->patchEntity($article, $data, [\
         'validate' => 'update',\
         'associated' => [\
             'Users' => ['validate' => 'signup'],\
             'Comments' => ['validate' => 'custom']\
         ]\
     ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  

バリデータの組み合わせ [​](https://book.cakephp.org/3.x/ja/orm/validation.html#%E3%83%8F%E3%82%99%E3%83%AA%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%81%AE%E7%B5%84%E3%81%BF%E5%90%88%E3%82%8F%E3%81%9B)

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

バリデータオブジェクトはこのように構築されるので、 その構築過程を複数の手順に分割することは簡単です。 :

    // UsersTable.php
    
    public function validationDefault(Validator $validator)
    {
        $validator->notEmpty('username');
        $validator->notEmpty('password');
        $validator->add('email', 'valid-email', ['rule' => 'email']);
        ...
    
        return $validator;
    }
    
    public function validationHardened(Validator $validator)
    {
        $validator = $this->validationDefault($validator);
    
        $validator->add('password', 'length', ['rule' => ['lengthBetween', 8, 100]]);
        return $validator;
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  

上の手順では、 `hardened` バリデーションセットを使う時には `default` セット中で定義されているバリデーションルールも含むことになります。

バリデーションプロバイダー [​](https://book.cakephp.org/3.x/ja/orm/validation.html#%E3%83%8F%E3%82%99%E3%83%AA%E3%83%86%E3%82%99%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%83%95%E3%82%9A%E3%83%AD%E3%83%8F%E3%82%99%E3%82%A4%E3%82%BF%E3%82%99%E3%83%BC)

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

バリデーションルールは既知のあらゆるプロバイダーで定義されている関数を使うことができます。 既定では CakePHP はいくつかのプロバイダーを設定します:

1.  `table` プロバイダーではテーブルクラスまたはそのビヘイビアーのメソッドが有効です。
2.  コアの `Cake\Validation\Validation` クラスが `default` プロバイダーとしてセットアップされます。

バリデーションルールを作る時に、そのルールのプロバイダー名を指定できます。 たとえば、もしあなたのテーブルが `isValidRole` メソッドを持っているとすれば それをバリデーションルールとして使うことができます。 :

    use Cake\ORM\Table;
    use Cake\Validation\Validator;
    
    class UsersTable extends Table
    {
        public function validationDefault(Validator $validator)
        {
            $validator
                ->add('role', 'validRole', [\
                    'rule' => 'isValidRole',\
                    'message' => __('有効な権限を指定する必要があります'),\
                    'provider' => 'table',\
                ]);
            return $validator;
        }
    
        public function isValidRole($value, array $context)
        {
            return in_array($value, ['admin', 'editor', 'author'], true);
        }
    
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  

バリデーションルールにはクロージャも使うことができます。 :

    $validator->add('name', 'myRule', [\
        'rule' => function ($data, $provider) {\
            if ($data > 1) {\
                return true;\
            }\
            return '適切な値ではありません。';\
        }\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  

バリデーションメソッドは通らない時にエラーメッセージを返すことができます。 これは渡された値に動的に基づくエラーメッセージを作るための簡単な方法です。

テーブルからのバリデータ取得 [​](https://book.cakephp.org/3.x/ja/orm/validation.html#%E3%83%86%E3%83%BC%E3%83%95%E3%82%99%E3%83%AB%E3%81%8B%E3%82%89%E3%81%AE%E3%83%8F%E3%82%99%E3%83%AA%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E5%8F%96%E5%BE%97)

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

テーブルクラスにバリデーションセットを作成した後は、 名前を指定して結果のオブジェクトを取得できるようになります。 :

    $defaultValidator = $usersTable->validator('default');
    
    $hardenedValidator = $usersTable->validator('hardened');

1  
2  
3  

Deprecated in version 3.5.0

`validator()` は非推奨です。代わりに `getValidator()` を使用してください。

既定のバリデータクラス [​](https://book.cakephp.org/3.x/ja/orm/validation.html#%E6%97%A2%E5%AE%9A%E3%81%AE%E3%83%8F%E3%82%99%E3%83%AA%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%82%AF%E3%83%A9%E3%82%B9)

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

上述の通り、既定ではバリデーションメソッドは `Cake\Validation\Validator` のインスタンスを受け取ります。 そうではなくて、カスタムバリデータのインスタンスが毎回ほしいのであれば、 テーブルの `$_validatorClass` プロパティーを使うことができます。 :

    // あなたのテーブルクラスの中で
    public function initialize(array $config)
    {
        $this->_validatorClass = '\FullyNamespaced\Custom\Validator';
    }

1  
2  
3  
4  
5  

アプリケーションルールの適用 [​](https://book.cakephp.org/3.x/ja/orm/validation.html#%E3%82%A2%E3%83%95%E3%82%9A%E3%83%AA%E3%82%B1%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%83%AB%E3%83%BC%E3%83%AB%E3%81%AE%E9%81%A9%E7%94%A8)

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

[リクエストデータがエンティティーに変換される](https://book.cakephp.org/3.x/ja/orm/validation.html#validating-request-data)
 時、 基本的なデータ検証が行われますが、多くのアプリケーションは 基本的な検証が完了した後にのみ適用されるもっと複雑な検証も設けています。

バリデーションはデータの形式や構文が正しいことを保証する一方、 ルールは あなたのアプリケーションやネットワークの既存の状態に対してデータを比較することに 焦点を当てます。

この種のルールはしばしば「ドメインルール」や「アプリケーションルール」と言われます。 CakePHP は、エンティティーが保存される前に適用される「ルールチェッカー」を通して これを行います。いくつかのドメインルールの例は次のようになります:

*   メールアドレスの一意性の保証。
*   ステータス遷移や業務フローの手順 (たとえば、請求書のステータス更新)。
*   論理削除されたアイテムの更新の抑制。
*   使用量／料金の上限の強制。

ドメインルールは `save()` および `delete()` メソッドを呼ぶとチェックされます。

### ルールチェッカーの作成 [​](https://book.cakephp.org/3.x/ja/orm/validation.html#%E3%83%AB%E3%83%BC%E3%83%AB%E3%83%81%E3%82%A7%E3%83%83%E3%82%AB%E3%83%BC%E3%81%AE%E4%BD%9C%E6%88%90)

ルールチェッカークラスは一般にテーブルクラスの `buildRules()` メソッドで定義されます。ビヘイビアーや他のイベントの受け手は 与えられたテーブルクラスのルールチェッカーを受け取るために `Model.buildRules` イベントを使うことができます。 :

    use Cake\ORM\RulesChecker;
    
    // テーブルクラスの中で
    public function buildRules(RulesChecker $rules)
    {
        // 作成および更新操作に提供されるルールを追加
        $rules->add(function ($entity, $options) {
            // 失敗／成功を示す真偽値を返す
        }, 'ruleName');
    
        // 作成のルールを追加
        $rules->addCreate(function ($entity, $options) {
            // 失敗／成功を示す真偽値を返す
        }, 'ruleName');
    
        // 更新のルールを追加
        $rules->addUpdate(function ($entity, $options) {
            // 失敗／成功を示す真偽値を返す
        }, 'ruleName');
    
        // 削除のルールを追加
        $rules->addDelete(function ($entity, $options) {
            // 失敗／成功を示す真偽値を返す
        }, 'ruleName');
    
        return $rules;
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  

ルールの関数はチェックされるエンティティーとオプションの配列を期待します。 オプションの配列は `errorField` 、 `message` 、そして `repository` を含みます。 `repository` オプションはルールが追加されるテーブルクラスを含みます。 ルールはあらゆる `callable` を受け取るので、インスタンス関数を使うこともできます。 :

    $rules->addCreate([$this, 'uniqueEmail'], 'uniqueEmail');

1  

または呼び出し可能なクラスも使えます。 :

    $rules->addCreate(new IsUnique(['email']), 'uniqueEmail');

1  

ルールを追加する時、任意でルールが適用されるフィールドやエラーメッセージ を定義することができます。 :

    $rules->add([$this, 'isValidState'], 'validState', [\
        'errorField' => 'status',\
        'message' => 'この請求書はそのステータスに遷移できません。'\
    ]);

1  
2  
3  
4  

エンティティーの `errors()` メソッドを呼ぶとエラーを確認できます。 :

    $entity->errors(); // ドメインルールのエラーメッセージを含んでいます

1  

### 一意フィールドルールの作成 [​](https://book.cakephp.org/3.x/ja/orm/validation.html#%E4%B8%80%E6%84%8F%E3%83%95%E3%82%A3%E3%83%BC%E3%83%AB%E3%83%88%E3%82%99%E3%83%AB%E3%83%BC%E3%83%AB%E3%81%AE%E4%BD%9C%E6%88%90)

一意ルールは極めて一般的なので、CakePHP は一意フィールドの組み合わせを定義できる 単純なルールクラスを内包しています。 :

    use Cake\ORM\Rule\IsUnique;
    
    // 一つのフィールド
    $rules->add($rules->isUnique(['email']));
    
    // フィールドのリスト
    $rules->add($rules->isUnique(
        ['username', 'account_id'],
        'この username と account_id の組み合わせはすでに使用されています。'
    ));

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

外部キーフィールドのルールを設定する時には、 ルールでは列挙したフィールドのみが使われるのを覚えておくことが重要です。 これは `$user->account->id` を変更しても上記のルールは発動しないことを意味します。

### 外部キールール [​](https://book.cakephp.org/3.x/ja/orm/validation.html#%E5%A4%96%E9%83%A8%E3%82%AD%E3%83%BC%E3%83%AB%E3%83%BC%E3%83%AB)

制約を強制するためにデータベースエラーに頼ることもできますが、 ルールのコードはより良いユーザーエクスペリエンスを提供するのに役立ちます。 このために CakePHP は `ExistsIn` ルールクラスを内包しています。 :

    // 一つのフィールド
    $rules->add($rules->existsIn('article_id', 'Articles'));
    
    // 複数キー。複合主キーに役立ちます。
    $rules->add($rules->existsIn(['site_id', 'article_id'], 'Articles'));

1  
2  
3  
4  
5  

存在をチェックするための関連テーブルのフィールドは主キーの一部でなければなりません。

複合外部キーの null が可能な部分が null の時、 `existsIn` が通るように強制することができます。 :

    // 例: NodesTable の複合主キーは (id, site_id) です。
    // Node は、親 Node を参照しますが、必須ではありません。参照しない場合、parent_id が null になります。
    // たとえ null が可能なフィールド (parent_id のような) が null であっても、このルールが通ることを許可します。
    $rules->add($rules->existsIn(
        ['parent_id', 'site_id'], // Schema: parent_id NULL, site_id NOT NULL
        'ParentNodes',
        ['allowNullableNulls' => true]
    ));
    
    // それに加えて Node は、常に Site を参照してください。
    $rules->add($rules->existsIn(['site_id'], 'Sites'));

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

大部分の SQL データベースでは、複数カラムの `UNIQUE` インデックスは、 `NULL` は、それ自身と等しくないため、複数の null 値が存在することを許可します。 複数の null 値を許可することは、CakePHP のデフォルトの振る舞いですが、 `allowMultipleNulls` を使用することでユニークチェックに null 値を含むことができます。 :

    // null 値は `parent_id` と `site_id` の中に１つだけで存在できます。
    $rules->add($rules->existsIn(
        ['parent_id', 'site_id'],
        'ParentNodes',
        ['allowMultipleNulls' => false]
    ));

1  
2  
3  
4  
5  
6  

Added in version 3.3.0

`allowNullableNulls` と `allowMultipleNulls` オプションが追加されました。

### アソシエーションカウントルール [​](https://book.cakephp.org/3.x/ja/orm/validation.html#%E3%82%A2%E3%82%BD%E3%82%B7%E3%82%A8%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%82%AB%E3%82%A6%E3%83%B3%E3%83%88%E3%83%AB%E3%83%BC%E3%83%AB)

プロパティーやアソシエーションが正しい件数かどうかの検証が必要な場合、 `validCount()` ルールが利用できます。 :

    // ArticlesTable.php ファイルの中で
    // 記事にタグは５つ以内。
    $rules->add($rules->validCount('tags', 5, '<=', 'タグは 5 つまで持てます'));

1  
2  
3  

ルールに基づく件数を定義する際、第３引数は、比較演算子を定義します。 比較には `==`, `>=`, `<=`, `>`, `<`, そして `!=` が使えます。 プロパティーの件数が範囲内であることを保証するために、２つのルールを使用してください。 :

    // ArticlesTable.php ファイルの中で
    // タグは３つ以上、５つ以内
    $rules->add($rules->validCount('tags', 3, '>=', 'タグは 3 つ以上必要です'));
    $rules->add($rules->validCount('tags', 5, '<=', 'タグは 5 つ以下です'));

1  
2  
3  
4  

もしプロパティーが数えられない場合や存在しない場合、 `validCount` は `false` を返すことに注意してください。 :

    // もし tags が null の場合、保存操作は失敗します。
    $rules->add($rules->validCount('tags', 0, '<=', 'タグを持つことはできません'));

1  
2  

Added in version 3.3.0

`validCount()` メソッドは、3.3.0 で追加されました。

### エンティティーメソッドをルールとして使用 [​](https://book.cakephp.org/3.x/ja/orm/validation.html#%E3%82%A8%E3%83%B3%E3%83%86%E3%82%A3%E3%83%86%E3%82%A3%E3%83%BC%E3%83%A1%E3%82%BD%E3%83%83%E3%83%88%E3%82%99%E3%82%92%E3%83%AB%E3%83%BC%E3%83%AB%E3%81%A8%E3%81%97%E3%81%A6%E4%BD%BF%E7%94%A8)

ドメインルールとしてエンティティーのメソッドを使いたいかもしれません。 :

    $rules->add(function ($entity, $options) {
        return $entity->isOkLooking();
    }, 'ruleName');

1  
2  
3  

### 条件付きルールの使用 [​](https://book.cakephp.org/3.x/ja/orm/validation.html#%E6%9D%A1%E4%BB%B6%E4%BB%98%E3%81%8D%E3%83%AB%E3%83%BC%E3%83%AB%E3%81%AE%E4%BD%BF%E7%94%A8)

エンティティーデータに基づいて条件付きでルールを適用することができます。 :

    $rules->add(function ($entity, $options) use($rules) {
        if ($entity->role == 'admin') {
            $rule = $rules->existsIn('user_id', 'Admins');
    
            return $rule($entity, $options);
        }
        if ($entity->role == 'user') {
            $rule = $rules->existsIn('user_id', 'Users');
    
            return $rule($entity, $options);
        }
    
        return false;
    }, 'userExists');

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

### 条件付き/動的なエラーメッセージ [​](https://book.cakephp.org/3.x/ja/orm/validation.html#%E6%9D%A1%E4%BB%B6%E4%BB%98%E3%81%8D-%E5%8B%95%E7%9A%84%E3%81%AA%E3%82%A8%E3%83%A9%E3%83%BC%E3%83%A1%E3%83%83%E3%82%BB%E3%83%BC%E3%82%B7%E3%82%99)

ルールは、 [カスタムコールバック](https://book.cakephp.org/3.x/ja/orm/validation.html#creating-a-rules-checker)
 または [ルールオブジェクト](https://book.cakephp.org/3.x/ja/orm/validation.html#creating-custom-rule-objects)
 であり、 パスするかどうかを示すブーリアン型を返すか、検証がパスしなかったことを意味する文字列を返すことができ、 返された文字列はエラーメッセージとして使用されます。

`message` オプションで定義された既存のエラーメッセージは、 ルールから返されたエラーメッセージによって上書きされます。 :

    $rules->add(
        function ($entity, $options) {
            if (!$entity->length) {
                return false;
            }
    
            if ($entity->length < 10) {
                return '値が 10 より小さい場合のエラーメッセージ';
            }
    
            if ($entity->length > 20) {
                return '値が 20 より大きい場合のエラーメッセージ';
            }
    
            return true;
        },
        'ruleName',
        [\
            'errorField' => 'length',\
            'message' => '`false` が返された時に使われる一般的なエラーメッセージ'\
        ]
     );

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  

NOTE

返されたメッセージを実際に使用するためには、 `errorField` オプションも _指定しなければならない_ ことに注意してください。そうしなければ、ルールは単にパスしないだけで、 エンティティーにエラーメッセージが設定されません。

### 再利用可能なカスタムルールの作成 [​](https://book.cakephp.org/3.x/ja/orm/validation.html#%E5%86%8D%E5%88%A9%E7%94%A8%E5%8F%AF%E8%83%BD%E3%81%AA%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%A0%E3%83%AB%E3%83%BC%E3%83%AB%E3%81%AE%E4%BD%9C%E6%88%90)

カスタムドメインルールを再利用したい事もあるでしょう。それには、 独自の呼び出し可能なルールを作成することによって行います。 :

    use App\ORM\Rule\IsUniqueWithNulls;
    // ...
    public function buildRules(RulesChecker $rules)
    {
        $rules->add(new IsUniqueWithNulls(['parent_id', 'instance_id', 'name']), 'uniqueNamePerParent', [\
            'errorField' => 'name',\
            'message' => 'Name must be unique per parent.'\
        ]);
        return $rules;
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

そのようなルールを作成する方法の例として、コアのルールを確認してください。

### カスタムルールオブジェクト作成 [​](https://book.cakephp.org/3.x/ja/orm/validation.html#%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%A0%E3%83%AB%E3%83%BC%E3%83%AB%E3%82%AA%E3%83%95%E3%82%99%E3%82%B7%E3%82%99%E3%82%A7%E3%82%AF%E3%83%88%E4%BD%9C%E6%88%90)

もしもアプリケーションがよく再利用されるルールを持っているのであれば、 再利用可能なクラスにそうしたルールをまとめると役に立ちます。 :

    // src/Model/Rule/CustomRule.php の中で
    namespace App\Model\Rule;
    
    use Cake\Datasource\EntityInterface;
    
    class CustomRule
    {
        public function __invoke(EntityInterface $entity, array $options)
        {
            // 何かする
            return false;
        }
    }
    
    // カスタムルールの追加
    use App\Model\Rule\CustomRule;
    
    $rules->add(new CustomRule(...), 'ruleName');

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

カスタムルールクラスを作ることでコードを _重複がない状態_ (訳注：DRY = Don't Repeat Yourself の訳) に保つことができ、またドメインルールを簡単にテストできるようになります。

### ルールの無効化 [​](https://book.cakephp.org/3.x/ja/orm/validation.html#%E3%83%AB%E3%83%BC%E3%83%AB%E3%81%AE%E7%84%A1%E5%8A%B9%E5%8C%96)

エンティティーを保存する時、必要であればルールを無効にできます。 :

    $articles->save($article, ['checkRules' => false]);

1  

バリデーション対アプリケーションルール [​](https://book.cakephp.org/3.x/ja/orm/validation.html#%E3%83%8F%E3%82%99%E3%83%AA%E3%83%86%E3%82%99%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E5%AF%BE%E3%82%A2%E3%83%95%E3%82%9A%E3%83%AA%E3%82%B1%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%83%AB%E3%83%BC%E3%83%AB)

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

CakePHP の ORM は検証に二層のアプローチを使う点がユニークです。

一層目はバリデーションです。バリデーションルールは、ステートレスな方法の操作を意図しています。 それらは、形状、データ型、データの書式が正しいことを保証するために最もよく作用します。

二層目は、アプリケーションルールです。アプリケーションルールは、あなたのエンティティーの ステートフルなプロパティーのチェックに最もよく作用します。例えば、バリデーションルールは、 メールアドレスが有効なことを保証することができますが、アプリケーションルールは、 メールアドレスがユニークであることを保証できます。

すでに見てきた通りに、一層目は `newEntity()` か `patchEntity()` を呼ぶ時に `Validator` オブジェクトを通して行われます。 :

    $validatedEntity = $articlesTable->newEntity(
        $unsafeData,
        ['validate' => 'customName']
    );
    $validatedEntity = $articlesTable->patchEntity(
        $entity,
        $unsafeData,
        ['validate' => 'customName']
    );

1  
2  
3  
4  
5  
6  
7  
8  
9  

上記の例では、 `validationCustomName()` メソッドを使って定義される 「カスタム」バリデータを使用します。 :

    public function validationCustomName($validator)
    {
        $validator->add(...);
        return $validator;
    }

1  
2  
3  
4  
5  

バリデーションは文字列や配列を渡されることを想定しています。 それらがリクエストから得られるものですので:

    // src/Model/Table/UsersTable.php の中で
    public function validatePasswords($validator)
    {
        $validator->add('confirm_password', 'no-misspelling', [\
            'rule' => ['compareWith', 'password'],\
            'message' => 'パスワードが一致しません',\
        ]);
    
        ...
        return $validator;
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

バリデーションはエンティティーのプロパティーを直接設定した時には起動 **しません** 。 :

    $userEntity->email = 'not an email!!';
    $usersTable->save($userEntity);

1  
2  

上記の例では、バリデーションは `newEntity()` と `patchEntity()` メソッドのためにのみ起動されるので、エンティティーは保存されてしまうことになります。 検証の第二層がこの状況に対処します。

アプリケーションルールは上で説明したように `save()` か `delete()` が呼ばれるといつでもチェックされます。 :

    // src/Model/Table/UsersTable.php の中で
    public function buildRules(RulesChecker $rules)
    {
        $rules->add($rules->isUnique('email'));
        return $rules;
    }
    
    // アプリケーションのコード中のどこかで
    $userEntity->email = '[email protected]';
    $usersTable->save($userEntity); // 偽を返します

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

バリデーションは直接のユーザー入力を意図しており、アプリケーションルールは アプリケーション中で生成されたデータの変更に特化しています。 :

    // src/Model/Table/OrdersTable.php の中で
    public function buildRules(RulesChecker $rules)
    {
        $check = function($order) {
            if($order->shipping_mode !== 'free'){
                return true;
            }
            return $order->price >= 100;
        };
        $rules->add($check, [\
            'errorField' => 'shipping_mode',\
            'message' => '100ドル以下の注文を送料無料にはできません！'\
        ]);
        return $rules;
    }
    
    // アプリケーションのコード中のどこかで
    $order->price = 50;
    $order->shipping_mode = 'free';
    $ordersTable->save($order); // 偽を返します

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  

### バリデーションをアプリケーションルールとして使用 [​](https://book.cakephp.org/3.x/ja/orm/validation.html#%E3%83%8F%E3%82%99%E3%83%AA%E3%83%86%E3%82%99%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%82%92%E3%82%A2%E3%83%95%E3%82%9A%E3%83%AA%E3%82%B1%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%83%AB%E3%83%BC%E3%83%AB%E3%81%A8%E3%81%97%E3%81%A6%E4%BD%BF%E7%94%A8)

ある状況ではユーザーあるいはアプリケーションによって生成されたデータの 両方に対して同じ検証の処理を走らせたいかもしれません。 これは、エンティティーのプロパティーを直接設定するような CLI スクリプトを走らせる時に起こり得るでしょう。 :

    // src/Model/Table/UsersTable.php の中で
    public function validationDefault(Validator $validator)
    {
        $validator->add('email', 'valid', [\
            'rule' => 'email',\
            'message' => '無効なメールアドレスです'\
        ]);
        ...
        return $validator;
    }
    
    public function buildRules(RulesChecker $rules)
    {
        // アプリケーションルールの追加
        $rules->add(function($entity) {
            $data = $entity->extract($this->schema()->columns(), true);
            $validator = $this->validator('default');
            // Prior to 3.9 use $validator->errors()
            $errors = $validator->validate($data, $entity->isNew());
            $entity->errors($errors);
    
            return empty($errors);
        });
    
        ...
    
        return $rules;
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  

保存が実行されると、追加された新しいアプリケーションのおかげで失敗します。 :

    $userEntity->email = 'not an email!!!';
    $usersTable->save($userEntity);
    $userEntity->errors('email'); // 無効なメールアドレスです

1  
2  
3  

同じ結果が `newEntity()` や `patchEntity()` を使う時にも期待できます。 :

    $userEntity = $usersTable->newEntity(['email' => 'not an email!!']);
    $userEntity->errors('email'); // 無効なメールアドレスです

1  
2

---

# プラグイン | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/plugins.html#VPContent)

Return to top

プラグイン [​](https://book.cakephp.org/3.x/ja/plugins.html#%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3)

========================================================================================================================

CakePHP では、コントローラー・モデル・ビューの組み合わせを設定し、 他の CakePHP アプリケーションで使用できるよう事前にパッケージ化された アプリケーションプラグインとしてリリースできます。あなたのアプリケーションの１つに、 素敵なユーザー管理モジュールやシンプルなブログやウェブサービスモジュールを作成したら、 CakePHP プラグインとしてパッケージ化してみませんか？そうすれば、他のアプリケーションで 再利用したり、コミュニティーで共有したりすることができます！

CakePHP プラグインは、ホストアプリケーション自身とは基本的に分離されており、 一般的にきちんとパッケージ化され、他のアプリケーションではほとんど手間をかけずに 再利用できる明確な機能を提供します。アプリケーションとプラグインは、それぞれの空間で動作しますが、 アプリケーションの設定によって定義・共有される、アプリケーション固有のプロパティー （データベース接続パラメーターなど）を共有します。

CakePHP 3.0 では、それぞれのプラグインごとに最上位の名前空間 (例えば `DebugKit` と いったように) を定義します。規約により、プラグインはそのパッケージ名が名前空間の名前と なります。 もし別の名前空間名を使いたいなら、プラグインをロードする時に設定することが可能です。

Composer を使ったプラグインのインストール [​](https://book.cakephp.org/3.x/ja/plugins.html#composer-%E3%82%92%E4%BD%BF%E3%81%A3%E3%81%9F%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E3%81%AE%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB)

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

[Packagist](https://packagist.org/)
 には多くのプラグインがあり、 `Composer` を 使ってインストールが可能です。DebugKit をインストールには、下記のコマンドを実行します。

    php composer.phar require cakephp/debug_kit

1  

これによって最新の DebugKit をインストールして、あなたの **composer.json**, **composer.lock** ファイルを更新し、 **vendor/cakephp-plugins.php** とオートローダーも更新します。

プラグインの手動インストール [​](https://book.cakephp.org/3.x/ja/plugins.html#%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E3%81%AE%E6%89%8B%E5%8B%95%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB)

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

もしあなたがインストールしたいプラグインが packagist.org になければ、プラグインのコードを **plugins** ディレクトリーにコピーすることもできます。 例えば 'ContactManager' という名前のプラグインをインストールするなら、 `plugins` フォルダーの中に 'ContactManager' という名前のフォルダーを作り、この下にプラグインの src, tests といった フォルダーを作ります。

### プラグインクラスを手動で自動読み込み [​](https://book.cakephp.org/3.x/ja/plugins.html#%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E3%82%AF%E3%83%A9%E3%82%B9%E3%82%92%E6%89%8B%E5%8B%95%E3%81%A6%E3%82%99%E8%87%AA%E5%8B%95%E8%AA%AD%E3%81%BF%E8%BE%BC%E3%81%BF)

`composer` や `bake` を使ってプラグインをインストールするなら、 プラグインのためにクラスの自動読み込みの設定をする必要はありません。

一方、 `MyPlugin` という名前のプラグインを手動でインストールした場合、 アプリケーションの **composer.json** ファイルを次の情報を含むように更新する必要があります。

    {
        "autoload": {
            "psr-4": {
                "MyPlugin\\": "plugins/MyPlugin/src/"
            }
        },
        "autoload-dev": {
            "psr-4": {
                "MyPlugin\\Test\\": "plugins/MyPlugin/tests/"
            }
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

あなたのプラグインがベンダーの名前空間を使うなら、パスマッピングの名前空間は下記のように なるでしょう。

    {
        "autoload": {
            "psr-4": {
                "AcmeCorp\\Users\\": "plugins/AcmeCorp/Users/src/",
                "AcmeCorp\\Users\\Test\\": "plugins/AcmeCorp/Users/tests/"
            }
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  

そして、 Composer の自動読み込みキャッシュを初期化する必要があります。

    php composer.phar dumpautoload

1  

もしあなたが何らかの理由で Composer を使う事ができないのなら、 `Plugin` を使って 自動読み込みを行うこともできます。 :

    Plugin::load('ContactManager', ['autoload' => true]);

1  

Deprecated in version 3.7.0

Plugin::load() と `autoload` オプションは非推奨です。

NOTE

重要: `autoload` オプションは `addPlugin()` では使用できません。代わりに `composer dumpautoload` を使用してください。

プラグインの読み込み [​](https://book.cakephp.org/3.x/ja/plugins.html#%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E3%81%AE%E8%AA%AD%E3%81%BF%E8%BE%BC%E3%81%BF)

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

もし、プラグインのルート、コンソールコマンド、ミドルウェア、またはイベントリスナーが欲しい場合、 プラグインを読み込む必要があります。プラグインは、アプリケーションの `bootstrap()` 関数の中で 読み込まれます。 :

    // src/Application.php の中。3.6.0 以上が必要。
    use Cake\Http\BaseApplication;
    use ContactManager\Plugin as ContactManagerPlugin;
    
    class Application extends BaseApplication {
        public function bootstrap()
        {
            parent::bootstrap();
            // クラス名で contact manager プラグインを読み込み
            $this->addPlugin(ContactManagerPlugin::class);
    
            // '短縮名' でベンダーの名前空間付きプラグインを読み込み
            $this->addPlugin('AcmeCorp/ContactManager');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

単にプラグインのヘルパー、ビヘイビアー、またはコンポーネントが欲しいだけの場合、 プラグインを読み込む必要はありません。

3.6.0 より前の場合、 `Plugin::load()` を使ってください。 :

    // config/bootstrap.php の中で
    
    // 特定のプラグインを読み込みます。
    Plugin::load('ContactManager');
    
    // ベンダーの名前空間の特定のプラグインを読み込みます。
    Plugin::load('AcmeCorp/ContactManager');

1  
2  
3  
4  
5  
6  
7  

また、プラグインを有効にする便利なシェルコマンドがあります。次の行を実行してください。

    bin/cake plugin load ContactManager

1  

これは、アプリケーションの bootstrap メソッドを更新、 または `$this->addPlugin('ContactManager');` を bootstrap に書き込みます。

Added in version 3.6.0

`addPlugin()` が追加されました。

プラグインフックの設定 [​](https://book.cakephp.org/3.x/ja/plugins.html#%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E3%83%95%E3%83%83%E3%82%AF%E3%81%AE%E8%A8%AD%E5%AE%9A)

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

プラグインは、プラグインがアプリケーションの適切な部分に自分自身を注入できるようにする いくつかのフックを提供します。

フックは以下の通りです。

*   `bootstrap` プラグインのデフォルト設定ファイルの読み込み、 定数やその他のグローバル関数の定義に使用されます。
*   `routes` プラグインのルートをロードするために使用されます。 アプリケーションのルートがロードされた後に呼ばれます。
*   `middleware` プラグインのミドルウェアをアプリケーションの ミドルウェアキューに追加するために使用されます。
*   `console` アプリケーションのコマンドコレクションにコンソールコマンドを 追加するために使用されます。

プラグインをロードするとき、有効にするフックを設定できます。 デフォルトでは、 [Plugin Objects](https://book.cakephp.org/3.x/ja/plugins.html#plugin-objects)
 のないプラグインはすべてのフックを無効にします。 新しいスタイルのプラグインを使用すると、プラグイン作成者はデフォルトを設定できます。 これを利用者はアプリケーション中で変更可能です。 :

    // Application::bootstrap() の中で
    use ContactManager\Plugin as ContactManagerPlugin;
    
    // ContactManager プラグインのルートを無効化
    $this->addPlugin(ContactManagerPlugin::class, ['routes' => false]);

1  
2  
3  
4  
5  

フックを配列オプションで設定することも、 Plugin クラスで提供されるメソッドで設定することもできます。 :

    // Application::bootstrap() の中で
    use ContactManager\Plugin as ContactManagerPlugin;
    
    // フックを設定するために disable/enable を使用
    $plugin = new ContactManagerPlugin();
    
    $plugin->disable('bootstrap');
    $plugin->enable('routes');
    $this->addPlugin($plugin);

1  
2  
3  
4  
5  
6  
7  
8  
9  

Plugin オブジェクトは、名前とパス情報も知っています。 :

    $plugin = new ContactManagerPlugin();
    
    // プラグイン名を取得
    $name = $plugin->getName();
    
    // プラグインルートへのパスとその他のパス
    $path = $plugin->getPath();
    $path = $plugin->getConfigPath();
    $path = $plugin->getClassPath();

1  
2  
3  
4  
5  
6  
7  
8  
9  

### 古いスタイルのプラグイン [​](https://book.cakephp.org/3.x/ja/plugins.html#%E5%8F%A4%E3%81%84%E3%82%B9%E3%82%BF%E3%82%A4%E3%83%AB%E3%81%AE%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3)

3.6.0 より前は、 `bootstrap` と `routs` フックを有効にする必要があります。 古いスタイルのプラグインは、 `middleware` と `console` フックはサポートしません。 :

    // config/bootstrap.php の中、
    // または Application::bootstrap() の中で
    
    // loadAll() を使用
    Plugin::loadAll([\
        'Blog' => ['routes' => true],\
        'ContactManager' => ['bootstrap' => true],\
        'WebmasterTools' => ['bootstrap' => true, 'routes' => true],\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  

また、プラグインを個別に読み込むことができます。 :

    // blog を読み込み、routes をインクルード
    Plugin::load('Blog', ['routes' => true]);
    
    // 設定と初期化を行う bootstrap をインクルード
    Plugin::load('ContactManager', ['bootstrap' => true]);

1  
2  
3  
4  
5  

この設定スタイルは、プラグインの設定やルートを手動で `include()` や `require()` する必要がなく、自動で正しい時間と正しい場所で読み込まれます。

特定の設定を持たない全てのプラグインを読み込むデフォルトの `loadAll()` を設定できます。

次の例は、全てのプラグインの bootstrap を読み込み、 それに加えて Blog プラグインの routes を読み込みます。 :

    Plugin::loadAll([\
        ['bootstrap' => true],\
        'Blog' => ['routes' => true]\
    ]);

1  
2  
3  
4  

プラグインで指定された全てのファイルが実際に存在しないと、PHP が読み込めないファイルごとに 警告を出します。この潜在的な警告は、 `ignoreMissing` オプションを使用して避けることができます。 :

    Plugin::loadAll([\
        ['ignoreMissing' => true, 'bootstrap' => true],\
        'Blog' => ['routes' => true]\
    ]);

1  
2  
3  
4  

プラグインを読み込むとき、プラグイン名は名前空間名と一致すべきです。 例えば、最上位の名前空間が `Users` のプラグインがあるなら、このように読み込みます。 :

    Plugin::load('User');

1  

もしあなたが `AcmeCorp/Users` といったように、ベンダー名を最上位の名前空間名に したいのなら、このようにプラグインを読み込みます。 :

    Plugin::load('AcmeCorp/Users');

1  

クラス名は `プラグイン記法` を使うことで、適切に解決されるでしょう。

ほとんどのプラグインで、設定するための正確な手続きとデータベースのセットアップするための方法が、 ドキュメントに書かれています。他よりセットアップが必要なものもあります。

Deprecated in version 3.7.0

Plugin::load() と Plugin::loadAll() は非推奨です。

プラグインの利用 [​](https://book.cakephp.org/3.x/ja/plugins.html#%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E3%81%AE%E5%88%A9%E7%94%A8)

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

クラス名の前にプラグイン名を付けることで、プラグインのコントローラー、 モデル、コンポーネント、ビヘイビアーとヘルパーを参照できます。

例えば、あなたの画面で整形された連絡先情報を表示するために、 ContactManager プラグインの ContactInfoHelper を使いたいとしましょう。この場合、あなたのコントローラーの `$helpers` 配列にこのように記述します。 :

    public $helpers = ['ContactManager.ContactInfo'];

1  

NOTE

このドット区切りのクラス名は、 `プラグイン記法` と呼ばれます。

すると、あなたが作った他のヘルパー同様に、 `ContactInfoHelper` に アクセスできるようになります。 :

    echo $this->ContactInfo->address($contact);

1  

独自プラグインの作成 [​](https://book.cakephp.org/3.x/ja/plugins.html#%E7%8B%AC%E8%87%AA%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E3%81%AE%E4%BD%9C%E6%88%90)

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

動作サンプルとして、上記を参考に ContactManager を作りましょう。 まず始めに、プラグインの基本ディレクトリー構成を準備します。 それはこのようになります。 :

    /src
    /plugins
        /ContactManager
            /config
            /src
                /Plugin.php
                /Controller
                    /Component
                /Model
                    /Table
                    /Entity
                    /Behavior
                /View
                    /Helper
                /Template
                    /Layout
            /tests
                /TestCase
                /Fixture
            /webroot
    

プラグインフォルダーの名前が '\*\*ContactManager\*\*' になっています。このフォルダーが プラグインと同じ名前になる事が大切です。

プラグインフォルダーの中は CakePHP アプリケーションと同じような構成であることに気づく 思いますが、それが基本的な構成です。使わないフォルダーは作る必要はありません。 コンポーネントとビヘイビアーだけで定義されるプラグインもあれば、 'Template' ディレクトリーが 完全に省略されるプラグインもあります。

プラグインは、アプリケーションが持つ Config, Console, webroot 等といったディレクトリーも 設置できます。

### Bake を使ってプラグインを作成 [​](https://book.cakephp.org/3.x/ja/plugins.html#bake-%E3%82%92%E4%BD%BF%E3%81%A3%E3%81%A6%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E3%82%92%E4%BD%9C%E6%88%90)

プラグイン制作の過程は、Bake shell を使えば非常に簡単です。

プラグインを bake するのは以下のコマンドになります。

    bin/cake bake plugin ContactManager

1  

Bake を使用して、プラグインのクラスを作成できます。 例えばプラグインのコントローラーを bake するには

    bin/cake bake controller --plugin ContactManager Contacts

1  

もしコマンドラインで問題があれば、 [Bake でコード生成](https://book.cakephp.org/3.x/ja/bake/usage.html)
 の章を参照してください。 また、プラグインを作ったら必ずオートローダーを再作成してください。

    php composer.phar dumpautoload

1  

Plugin オブジェクト [​](https://book.cakephp.org/3.x/ja/plugins.html#plugin-%E3%82%AA%E3%83%95%E3%82%99%E3%82%B7%E3%82%99%E3%82%A7%E3%82%AF%E3%83%88)

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

Plugin オブジェクトを使用すると、プラグイン作成者は設定ロジックを定義し、 デフォルトのフックを定義し、ルート、ミドルウェア、およびコンソールコマンドをロードできます。 Plugin オブジェクトは、 **src/Plugin.php** にあります。 ContactManager プラグイン の場合、 Plugin クラスは、次のようになります。 :

    namespace ContactManager;
    
    use Cake\Core\BasePlugin;
    use Cake\Core\PluginApplicationInterface;
    
    class Plugin extends BasePlugin
    {
        public function middleware($middleware)
        {
            // ここにミドルウェアを追加。
            return $middleware;
        }
    
        public function console($commands)
        {
            // ここにコンソールコマンドを追加。
            return $commands;
        }
    
        public function bootstrap(PluginApplicationInterface $app)
        {
            // 定数を追加。デフォルトの設定をロード。
            // デフォルトでは、プラグインの中の `config/bootstrap.php` をロードします。
            parent::bootstrap($app);
        }
    
        public function routes($routes)
        {
            // ルートの追加。
            // デフォルトでは、プラグインの中の `config/routes.php` をロードします。
            parent::routes($routes);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  

Added in version 3.6.0

Plugin オブジェクトは 3.6.0 で追加されました。

プラグインのルート [​](https://book.cakephp.org/3.x/ja/plugins.html#%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E3%81%AE%E3%83%AB%E3%83%BC%E3%83%88)

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

プラグインは、ルートを含むルートファイルを提供できます。各プラグインは、 **config/routes.php** ファイルを含むことができます。このルートファイルは、 プラグインが追加された時、またはアプリケーションのルートファイルの中で ロードすることができます。ContactManager プラグインのルートを作成するためには、 **plugins/ContactManager/config/routes.php** の中に以下を記述してください。 :

    <?php
    use Cake\Routing\Route\DashedRoute;
    use Cake\Routing\Router;
    
    Router::plugin(
        'ContactManager',
        ['path' => '/contact-manager'],
        function ($routes) {
            $routes->get('/contacts', ['controller' => 'Contacts']);
            $routes->get('/contacts/:id', ['controller' => 'Contacts', 'action' => 'view']);
            $routes->put('/contacts/:id', ['controller' => 'Contacts', 'action' => 'update']);
        }
    );

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

上記のようにすれば、プラグインのデフォルトルートに接続できるでしょう。 このファイルをカスタマイズすることで、後から個別のルートを設定することができます。

コントローラーにアクセスする前に、プラグインがロードされ、ルートがロードされる必要があります。 **src/Application.php** に下記を追加してください。 :

    $this->addPlugin('ContactManager', ['routes' => true]);

1  

アプリケーションのルート一覧の中で、プラグインのルートをロードすることもできます。 これにより、プラグインのルートをロードする方法をより詳細に制御し、 追加のスコープやプレフィックスでプラグインのルートをラップすることができます。 :

    Router::scope('/', function ($routes) {
        // 他のルートに接続。
        $routes->scope('/backend', function ($routes) {
            $routes->loadPlugin('ContactManager');
        });
    });

1  
2  
3  
4  
5  
6  

上記の結果は、 `/backend/contact-manager/contacts` のような URL になります。

Added in version 3.5.0

`RouteBuilder::loadPlugin()` は 3.5.0 で追加されました。

プラグインのコントローラー [​](https://book.cakephp.org/3.x/ja/plugins.html#%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E3%81%AE%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%A9%E3%83%BC)

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

ContactManager プラグインのコントローラーは、 **plugins/ContactManager/src/Controller/** に設置されます。主にやりたい事は contacts の管理ですので、このプラグインには ContactsController が必要です。

そこで ContactsController を **plugins/ContactManager/src/Controller** に設置し、 このように書きます。 :

    // plugins/ContactManager/src/Controller/ContactsController.php
    namespace ContactManager\Controller;
    
    use ContactManager\Controller\AppController;
    
    class ContactsController extends AppController
    {
        public function index()
        {
            //...
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

まだ作っていないなら、 `AppController` も作りましょう。 :

    // plugins/ContactManager/src/Controller/AppController.php
    namespace ContactManager\Controller;
    
    use App\Controller\AppController as BaseController;
    
    class AppController extends BaseController
    {
    }

1  
2  
3  
4  
5  
6  
7  
8  

プラグインの `AppController` は、プラグイン内の全コントローラー共通のロジックを 持ちますが、使わないようでしたら作らなくても構いません。

これまでのところでアクセスするなら、 `/contact-manager/contacts` にアクセスして みてください。 "Missing Model" エラーが表示されるでしょうが、これはまだ Contact モデルが定義されていないためです。

もしあなたのアプリケーションが、CakePHP の提供するデフォルトルーティングを含むなら、 あなたのプラグインコントローラーへは下記のような URL でアクセスできます。 :

    // プラグインコントローラーの index にアクセスする
    /contact-manager/contacts
    
    // プラグインコントローラーのそれぞれのアクションにアクセスする
    /contact-manager/contacts/view/1

1  
2  
3  
4  
5  

もしあなたのアプリケーションでルーティングプレフィックスを定義しているなら、 CakePHP のデフォルトルーティングは下記の書式でルーティングします。 :

    /:prefix/:plugin/:controller
    /:prefix/:plugin/:controller/:action
    

特定ファイルにルーティングするようなプラグインの読み込み方法については、 [Plugin Configuration](https://book.cakephp.org/3.x/ja/plugins.html#plugin-configuration)
 のセクションをご覧ください。

bake で作っていないプラグインなら、クラスを自動的に読み込むために **composer.json** ファイルを編集して、あなたのプラグインを追加する必要があります。 これは [Autoloading Plugin Classes](https://book.cakephp.org/3.x/ja/plugins.html#autoloading-plugin-classes)
 に従って行うことができます。

プラグインのモデル [​](https://book.cakephp.org/3.x/ja/plugins.html#%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E3%81%AE%E3%83%A2%E3%83%86%E3%82%99%E3%83%AB)

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

プラグインのモデルは **plugins/ContactManager/src/Model** に設置されます。 既にこのプラグインの ContactsController は定義してありますから、このコントローラーの ためのテーブルとエンティティーを作成しましょう。 :

    // plugins/ContactManager/src/Model/Entity/Contact.php:
    namespace ContactManager\Model\Entity;
    
    use Cake\ORM\Entity;
    
    class Contact extends Entity
    {
    }
    
    // plugins/ContactManager/src/Model/Table/ContactsTable.php:
    namespace ContactManager\Model\Table;
    
    use Cake\ORM\Table;
    
    class ContactsTable extends Table
    {
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

エンティティークラスを作った時や関連付けを行いたい時など、あなたのプラグイン内のモデルを 参照したい場合には、プラグイン名とクラス名をドットで区切る必要があります。例えば:

    // plugins/ContactManager/src/Model/Table/ContactsTable.php:
    namespace ContactManager\Model\Table;
    
    use Cake\ORM\Table;
    
    class ContactsTable extends Table
    {
        public function initialize(array $config)
        {
            $this->hasMany('ContactManager.AltName');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

もし関連付け配列のキーにプラグインの接頭語をつけたくないのなら、代わりにこのような 構文が使えます。 :

    // plugins/ContactManager/src/Model/Table/ContactsTable.php:
    namespace ContactManager\Model\Table;
    
    use Cake\ORM\Table;
    
    class ContactsTable extends Table
    {
        public function initialize(array $config)
        {
            $this->hasMany('AltName', [\
                'className' => 'ContactManager.AltName',\
            ]);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

おなじみの `プラグイン記法` を使う事で、プラグインのテーブルを 読み込むために `TableRegistry` を使用することができます。 :

    use Cake\ORM\TableRegistry;
    
    // Prior to 3.6 use TableRegistry::get('ContactManager.Contacts')
    $contacts = TableRegistry::getTableLocator()->get('ContactManager.Contacts');

1  
2  
3  
4  

あるいは、コントローラーの処理の中で以下のように使用できます。 :

    $this->loadModel('ContactsMangager.Contacts');

1  

プラグインのビュー [​](https://book.cakephp.org/3.x/ja/plugins.html#%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E3%81%AE%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC)

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

ビューは通常のアプリケーション内と同じように動作します。 `plugins/[PluginName]/src/Template/` フォルダーの中の正しいフォルダー内に配置するだけです。 我々の ContactManager プラグインでは `ContactsController::index()` アクションに ビューが必要ですから、このような内容になります。 :

    // plugins/ContactManager/src/Template/Contacts/index.ctp:
    <h1>連絡先</h1>
    <p>ソート可能なあなたの連絡先一覧は次のとおりです</p>
    <!-- ソート可能な連絡先一覧はこちら....-->

1  
2  
3  
4  

プラグインは独自のレイアウトを提供することができます。 プラグインレイアウトを追加するためには、テンプレートファイルを `plugins/[PluginName]/src/Template/Layout` に配置します。 プラグインレイアウトをコントローラーで使用するには、下記のようにします。 :

    public $layout = 'ContactManager.admin';

1  

プラグインのプレフィックスを省略した場合は、レイアウトやビューファイルは通常のものを使用します。

NOTE

プラグインからのエレメントの使い方については、 [View Elements](https://book.cakephp.org/3.x/ja/views.html#view-elements)
 を参照してください。

### アプリケーション内からプラグインのテンプレートを上書き [​](https://book.cakephp.org/3.x/ja/plugins.html#%E3%82%A2%E3%83%95%E3%82%9A%E3%83%AA%E3%82%B1%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E5%86%85%E3%81%8B%E3%82%89%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E3%81%AE%E3%83%86%E3%83%B3%E3%83%95%E3%82%9A%E3%83%AC%E3%83%BC%E3%83%88%E3%82%92%E4%B8%8A%E6%9B%B8%E3%81%8D)

プラグインのビューはあるパスを使って上書きできます。 仮にあなたが 'ContactManager' という名前のプラグインを持っているとして、 **src/Template/Plugin/\[Plugin\]/\[Controller\]/\[view\].ctp** というファイルを作って そこにビューロジックを書いておけば、プラグインのテンプレートファイルを上書きすることができます。 Contacts コントローラーなら、次のようなファイルを作成します。 :

    src/Template/Plugin/ContactManager/Contacts/index.ctp
    

このファイルを作成すると、 **plugins/ContactManager/src/Template/Contacts/index.ctp** を上書きします。

もし、あなたのプラグインが composer の依存関係の中にある場合 (例えば 'Company/ContactManager')、 Custom コントローラーの 'index' ビューへのパスは、次の通りです。 :

    src/Template/Plugin/ContactManager/Contacts/index.ctp
    

このファイルを作成すると、 **vendor/Company/ContactManager/src/Template/Contacts/index.ctp** を上書きします。

プラグインがルーティングプレフィックスを実装する場合、上書きする アプリケーションテンプレートのパスにルーティングプレフィックスが含まなければなりません。 例えば、 'ContactManager' プラグインが 'admin' プレフィックスを実装する場合、 上書きするパスは、次の通りです。 :

    src/Template/Plugin/Company/ContactManager/Admin/Contact/index.ctp
    

プラグインのアセット [​](https://book.cakephp.org/3.x/ja/plugins.html#%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E3%81%AE%E3%82%A2%E3%82%BB%E3%83%83%E3%83%88)

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

プラグインのウェブアセット (PHP 以外のファイル） は、メインアプリケーションのアセットと 同様にプラグインの `webroot` ディレクトリーを介して配信されます。 :

    /plugins/ContactManager/webroot/
                                   css/
                                   js/
                                   img/
                                   flash/
                                   pdf/
    

通常の webroot と同じようにどのディレクトリーにどんなファイルでも置くことができます。

WARNING

ディスパッチャーを介して静的アセット (画像や JavaScript や CSS ファイル) を取り扱うことは 非常に非効率です。 詳細は [アプリケーションのパフォーマンスの向上](https://book.cakephp.org/3.x/ja/deployment.html#symlink-assets)
 をご覧ください。

### プラグイン内のアセットへのリンク [​](https://book.cakephp.org/3.x/ja/plugins.html#%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E5%86%85%E3%81%AE%E3%82%A2%E3%82%BB%E3%83%83%E3%83%88%E3%81%B8%E3%81%AE%E3%83%AA%E3%83%B3%E3%82%AF)

`Cake\View\Helper\HtmlHelper` の script, image, css メソッドを使って プラグイン内のアセットへのリンクを作りたい場合、 `プラグイン記法` が使えます。 :

    // /contact_manager/css/styles.css への URL を生成します
    echo $this->Html->css('ContactManager.styles');
    
    // /contact_manager/js/widget.js への URL を生成します
    echo $this->Html->script('ContactManager.widget');
    
    // /contact_manager/img/logo.jpg への URL を生成します
    echo $this->Html->image('ContactManager.logo');

1  
2  
3  
4  
5  
6  
7  
8  

プラグインのアセットは、デフォルトで `AssetMiddleware` ミドルウェアを 使用して提供されます。これは開発時のみ使用することが推奨されます。 本番環境ではパフォーマンスを向上させるために、 [プラグインのアセットをシンボリックリンク化](https://book.cakephp.org/3.x/ja/deployment.html#symlink-assets)
 すべきです。

もしあなたがヘルパーを使わないなら、プラグインのアセットを提供するためには URL の先頭に プラグイン名を付加します。 '/contact\_manager/js/some\_file.js' へのリンクで、 **plugins/ContactManager/webroot/js/some\_file.js** というアセットを提供します。

コンポーネント、ヘルパーとビヘイビアー [​](https://book.cakephp.org/3.x/ja/plugins.html#%E3%82%B3%E3%83%B3%E3%83%9B%E3%82%9A%E3%83%BC%E3%83%8D%E3%83%B3%E3%83%88%E3%80%81%E3%83%98%E3%83%AB%E3%83%8F%E3%82%9A%E3%83%BC%E3%81%A8%E3%83%92%E3%82%99%E3%83%98%E3%82%A4%E3%83%92%E3%82%99%E3%82%A2%E3%83%BC)

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

プラグインには通常の CakePHP アプリケーションと同じように、コンポーネント、ヘルパー、 ビヘイビアーを持つ事ができます。あなたはコンポーネント、ヘルパー、ビヘイビアーだけからなる プラグインを作る事もできます。これはコンポーネントを他のプロジェクトに簡単に導入すれば 再利用可能となるような素晴らしい方法です。

このようなコンポーネントを作る事は、実際、通常のアプリケーションとして作る事と同じであり、 特別な命名規則もありません。

プラグインの内部や外部からコンポーネントを参照する方法は、コンポーネント名の前に プラグイン名を付けるだけです。例えば:

    // 'ContactManager' プラグインのコンポーネントとして定義
    namespace ContactManager\Controller\Component;
    
    use Cake\Controller\Component;
    
    class ExampleComponent extends Component
    {
    }
    
    // コントローラーの中で
    public function initialize()
    {
        parent::initialize();
        $this->loadComponent('ContactManager.Example');
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

同じテクニックはヘルパーとビヘイビアーにも使えます。

コマンド [​](https://book.cakephp.org/3.x/ja/plugins.html#%E3%82%B3%E3%83%9E%E3%83%B3%E3%83%88%E3%82%99)

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

プラグインは、 `console()` フックの中で、コマンドを登録することができます。 デフォルトでは、プラグイン内のすべてのシェルとコマンドが自動検出され、 アプリケーションのコマンドリストに追加されます。 プラグインコマンドの先頭にはプラグイン名が付いています。例えば、 `ContactManager` プラグインによって提供される `UserCommand` は、 `contact_manager.user` と `user` の両方として登録されます。プレフィックスのない名前は、 アプリケーションや他のプラグインで使用されていないプラグインでのみ使用されます。

プラグインで各コマンドを定義することによって、コマンド名をカスタマイズすることができます。 :

    public function console($commands)
    {
        // ネストされたコマンドを作成
        $commands->add('bake model', ModelCommand::class);
        $commands->add('bake controller', ControllerCommand::class);
    
        return $commands;
    }

1  
2  
3  
4  
5  
6  
7  
8  

プラグインのテスト [​](https://book.cakephp.org/3.x/ja/plugins.html#%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E3%81%AE%E3%83%86%E3%82%B9%E3%83%88)

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

コントローラーやURLの生成をテストする場合、プラグインがルート `tests/bootstrap.php` に接続していることを確認してください。

詳細は [testing plugins](https://book.cakephp.org/3.x/ja/development/testing.html)
 ページを確認してください。

プラグインの公開 [​](https://book.cakephp.org/3.x/ja/plugins.html#%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E3%81%AE%E5%85%AC%E9%96%8B)

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

CakePHP のプラグインは [the packagist](https://packagist.org/)
 に公開しましょう。 こちらでは、他の人々は composer の依存関係として使用することができます。 [awesome-cakephp list](https://github.com/FriendsOfCake/awesome-cakephp)
 に申し込みできます。

パッケージ名にセマンティックな意味のある名前を選んでください。これは、理想を言えば、 "cakephp" をフレームワークとして依存関係を設定するべきです。 ベンダー名は、通常あなたの GitHub ユーザー名になります。 CakePHP 名前空間 (cakephp) を **使用しない** でください。 これは、CakePHP 自身のプラグインのために予約されています。 小文字と区切り文字のダッシュを使用することが決まりです。

もし、あなたの GitHub アカウントが "FooBar" で "Logging" プラグインを作成する場合、 foo-bar/cakephp-logging と名付けるといいでしょう。 そして、CakePHP 自身の "Localized" プラグンは、 cakephp/localized で見つけられます。

vendor/cakephp-plugins.php

プラグイン マップ ファイル [​](https://book.cakephp.org/3.x/ja/plugins.html#%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3-%E3%83%9E%E3%83%83%E3%83%95%E3%82%9A-%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB)

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

Composer 経由でインストールすると、 `vendor/cakephp-plugins.php` というファイルが 作られることに気付くかもしれません。この設定ファイルにはプラグイン名とファイルシステム上の 配置場所の情報が含まれています。これによって、プラグインを通常の検索パスの外の、標準の vendor ディレクトリーにインストールすることが可能になります。 `Plugin` クラスは `load()` や `loadAll()` でプラグインをロードする時に、このファイルを使って 場所を特定します。通常あなたはこのファイルを手動で編集する必要はなく、 Composer や `plugin-installer` パッケージが管理してくれます。

Mixer を使用したプラグインの管理 [​](https://book.cakephp.org/3.x/ja/plugins.html#mixer-%E3%82%92%E4%BD%BF%E7%94%A8%E3%81%97%E3%81%9F%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E3%81%AE%E7%AE%A1%E7%90%86)

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

CakePHP アプリケーションでプラグインを発見して管理する別の方法は、 [Mixer](https://github.com/CakeDC/mixer)
 です。これは Packagist からプラグインをインストールするのに 便利な CakePHP のプラグインです。また、既存のプラグインを管理するのにも役立ちます。

NOTE

重要: 本番環境でこれを使用しないでください。

---

# JSON and XML views | CakePHP

[Skip to content](https://book.cakephp.org/3.x/views/json-and-xml-views.html#VPContent)

Return to top

JSON and XML views [​](https://book.cakephp.org/3.x/views/json-and-xml-views.html#json-and-xml-views)

======================================================================================================

The `JsonView` and `XmlView` let you create JSON and XML responses, and integrate with the `Cake\Controller\Component\RequestHandlerComponent`.

By enabling `RequestHandlerComponent` in your application, and enabling support for the `json` and/or `xml` extensions, you can automatically leverage the new view classes. `JsonView` and `XmlView` will be referred to as data views for the rest of this page.

There are two ways you can generate data views. The first is by using the `_serialize` key, and the second is by creating normal template files.

Enabling Data Views in Your Application [​](https://book.cakephp.org/3.x/views/json-and-xml-views.html#enabling-data-views-in-your-application)

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

Before you can use the data view classes, you'll first need to load the `Cake\Controller\Component\RequestHandlerComponent` in your controller:

    public function initialize()
    {
        ...
        $this->loadComponent('RequestHandler');
    }

1  
2  
3  
4  
5  

This can be done in your `AppController` and will enable automatic view class switching on content types. You can also set the component up with the `viewClassMap` setting, to map types to your custom classes and/or map other data types.

You can optionally enable the json and/or xml extensions with [File Extensions](https://book.cakephp.org/3.x/development/routing.html#file-extensions)
. This will allow you to access the `JSON`, `XML` or any other special format views by using a custom URL ending with the name of the response type as a file extension such as `http://example.com/articles.json`.

By default, when not enabling [File Extensions](https://book.cakephp.org/3.x/development/routing.html#file-extensions)
, the request, the `Accept` header is used for, selecting which type of format should be rendered to the user. An example `Accept` format that is used to render `JSON` responses is `application/json`.

Using Data Views with the Serialize Key [​](https://book.cakephp.org/3.x/views/json-and-xml-views.html#using-data-views-with-the-serialize-key)

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

The `_serialize` key is a special view variable that indicates which other view variable(s) should be serialized when using a data view. This lets you skip defining template files for your controller actions if you don't need to do any custom formatting before your data is converted into json/xml.

If you need to do any formatting or manipulation of your view variables before generating the response, you should use template files. The value of `_serialize` can be either a string or an array of view variables to serialize:

    namespace App\Controller;
    
    class ArticlesController extends AppController
    {
        public function initialize()
        {
            parent::initialize();
            $this->loadComponent('RequestHandler');
        }
    
        public function index()
        {
            // Set the view vars that have to be serialized.
            $this->set('articles', $this->paginate());
            // Specify which view vars JsonView should serialize.
            $this->set('_serialize', 'articles');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

You can also define `_serialize` as an array of view variables to combine:

    namespace App\Controller;
    
    class ArticlesController extends AppController
    {
        public function initialize()
        {
            parent::initialize();
            $this->loadComponent('RequestHandler');
        }
    
        public function index()
        {
            // Some code that created $articles and $comments
    
            // Set the view vars that have to be serialized.
            $this->set(compact('articles', 'comments'));
    
            // Specify which view vars JsonView should serialize.
            $this->set('_serialize', ['articles', 'comments']);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  

Defining `_serialize` as an array has added the benefit of automatically appending a top-level `<response>` element when using `XmlView`. If you use a string value for `_serialize` and XmlView, make sure that your view variable has a single top-level element. Without a single top-level element the Xml will fail to generate.

Using a Data View with Template Files [​](https://book.cakephp.org/3.x/views/json-and-xml-views.html#using-a-data-view-with-template-files)

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

You should use template files if you need to do some manipulation of your view content before creating the final output. For example if we had articles, that had a field containing generated HTML, we would probably want to omit that from a JSON response. This is a situation where a view file would be useful:

    // Controller code
    class ArticlesController extends AppController
    {
        public function index()
        {
            $articles = $this->paginate('Articles');
            $this->set(compact('articles'));
        }
    }
    
    // View code - src/Template/Articles/json/index.ctp
    foreach ($articles as &$article) {
        unset($article->generated_html);
    }
    echo json_encode(compact('articles'));

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

You can do more complex manipulations, or use helpers to do formatting as well. The data view classes don't support layouts. They assume that the view file will output the serialized content.

NOTE

As of 3.1.0 until 3.5.0, AppController in the application skeleton automatically added `'_serialize' => true` to all XML/JSON requests. You will need to remove this code from the beforeRender callback or set `'_serialize' => false` in your controller's action if you want to use view files.

Creating XML Views [​](https://book.cakephp.org/3.x/views/json-and-xml-views.html#creating-xml-views)

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

`class` **XmlView**

By default when using `_serialize` the XmlView will wrap your serialized view variables with a `<response>` node. You can set a custom name for this node using the `_rootNode` view variable.

The XmlView class supports the `_xmlOptions` variable that allows you to customize the options used to generate XML, e.g. `tags` vs `attributes`.

An example of using `XmlView` would be to generate a [sitemap.xml](https://www.sitemaps.org/protocol.html)
. This document type requires that you change `_rootNode` and set attributes. Attributes are defined using the `@` prefix:

    public function sitemap()
    {
        $pages = $this->Pages->find();
        $urls = [];
        foreach ($pages as $page) {
            $urls[] = [\
                'loc' => Router::url(['controller' => 'Pages', 'action' => 'view', $page->slug, '_full' => true]),\
                'lastmod' => $page->modified->format('Y-m-d'),\
                'changefreq' => 'daily',\
                'priority' => '0.5'\
            ];
        }
    
        // Define a custom root node in the generated document.
        $this->set('_rootNode', 'urlset');
        $this->set([\
            // Define an attribute on the root node.\
            '@xmlns' => 'http://www.sitemaps.org/schemas/sitemap/0.9',\
            'url' => $urls\
        ]);
        $this->set('_serialize', ['@xmlns', 'url']);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  

Creating JSON Views [​](https://book.cakephp.org/3.x/views/json-and-xml-views.html#creating-json-views)

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

`class` **JsonView**

The JsonView class supports the `_jsonOptions` variable that allows you to customize the bit-mask used to generate JSON. See the [json\_encode](https://php.net/json_encode)
 documentation for the valid values of this option.

For example, to serialize validation error output of CakePHP entities in a consistent form of JSON do:

    // In your controller's action when saving failed
    $this->set('errors', $articles->errors());
    $this->set('_jsonOptions', JSON_FORCE_OBJECT);
    $this->set('_serialize', ['errors']);

1  
2  
3  
4  

### JSONP Responses [​](https://book.cakephp.org/3.x/views/json-and-xml-views.html#jsonp-responses)

When using `JsonView` you can use the special view variable `_jsonp` to enable returning a JSONP response. Setting it to `true` makes the view class check if query string parameter named "callback" is set and if so wrap the json response in the function name provided. If you want to use a custom query string parameter name instead of "callback" set `_jsonp` to required name instead of `true`.

Example Usage [​](https://book.cakephp.org/3.x/views/json-and-xml-views.html#example-usage)

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

While the [RequestHandlerComponent](https://book.cakephp.org/3.x/controllers/components/request-handling.html)
 can automatically set the view based on the request content-type or extension, you could also handle view mappings in your controller:

    // src/Controller/VideosController.php
    namespace App\Controller;
    
    use App\Controller\AppController;
    
    // Prior to 3.6 use Cake\Network\Exception\NotFoundException
    use Cake\Http\Exception\NotFoundException;
    
    class VideosController extends AppController
    {
        public function export($format = '')
        {
            $format = strtolower($format);
    
            // Format to view mapping
            $formats = [\
              'xml' => 'Xml',\
              'json' => 'Json',\
            ];
    
            // Error on unknown type
            if (!isset($formats[$format])) {
                throw new NotFoundException(__('Unknown format.'));
            }
    
            // Set Out Format View
            $this->viewBuilder()->className($formats[$format]);
    
            // Get data
            $videos = $this->Videos->find('latest');
    
            // Set Data View
            $this->set(compact('videos'));
            $this->set('_serialize', ['videos']);
    
            // Set Force Download
            // Prior to 3.4.0
            // $this->response->download('report-' . date('YmdHis') . '.' . $format);
            return $this->response->withDownload('report-' . date('YmdHis') . '.' . $format);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40  
41

---

# View Cells | CakePHP

[Skip to content](https://book.cakephp.org/3.x/views/cells.html#VPContent)

Return to top

View Cells [​](https://book.cakephp.org/3.x/views/cells.html#view-cells)

=========================================================================

View cells are small mini-controllers that can invoke view logic and render out templates. The idea of cells is borrowed from [cells in Ruby](https://github.com/trailblazer/cells)
, where they fulfill a similar role and purpose.

When to use Cells [​](https://book.cakephp.org/3.x/views/cells.html#when-to-use-cells)

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

Cells are ideal for building reusable page components that require interaction with models, view logic, and rendering logic. A simple example would be the cart in an online store, or a data-driven navigation menu in a CMS.

Creating a Cell [​](https://book.cakephp.org/3.x/views/cells.html#creating-a-cell)

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

To create a cell, define a class in **src/View/Cell** and a template in **src/Template/Cell/**. In this example, we'll be making a cell to display the number of messages in a user's notification inbox. First, create the class file. Its contents should look like:

    namespace App\View\Cell;
    
    use Cake\View\Cell;
    
    class InboxCell extends Cell
    {
        public function display()
        {
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

Save this file into **src/View/Cell/InboxCell.php**. As you can see, like other classes in CakePHP, Cells have a few conventions:

*   Cells live in the `App\View\Cell` namespace. If you are making a cell in a plugin, the namespace would be `PluginName\View\Cell`.
*   Class names should end in Cell.
*   Classes should inherit from `Cake\View\Cell`.

We added an empty `display()` method to our cell; this is the conventional default method when rendering a cell. We'll cover how to use other methods later in the docs. Now, create the file **src/Template/Cell/Inbox/display.ctp**. This will be our template for our new cell.

You can generate this stub code quickly using `bake`:

    bin/cake bake cell Inbox
    

Would generate the code we created above.

Implementing the Cell [​](https://book.cakephp.org/3.x/views/cells.html#implementing-the-cell)

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

Assume that we are working on an application that allows users to send messages to each other. We have a `Messages` model, and we want to show the count of unread messages without having to pollute AppController. This is a perfect use case for a cell. In the class we just made, add the following:

    namespace App\View\Cell;
    
    use Cake\View\Cell;
    
    class InboxCell extends Cell
    {
        public function display()
        {
            $this->loadModel('Messages');
            $unread = $this->Messages->find('unread');
            $this->set('unread_count', $unread->count());
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

Because Cells use the `ModelAwareTrait` and `ViewVarsTrait`, they behave very much like a controller would. We can use the `loadModel()` and `set()` methods just like we would in a controller. In our template file, add the following:

    <!-- src/Template/Cell/Inbox/display.ctp -->
    <div class="notification-icon">
        You have <?= $unread_count ?> unread messages.
    </div>

1  
2  
3  
4  

NOTE

Cell templates have an isolated scope that does not share the same View instance as the one used to render template and layout for the current controller action or other cells. Hence they are unaware of any helper calls made or blocks set in the action's template / layout and vice versa.

Loading Cells [​](https://book.cakephp.org/3.x/views/cells.html#loading-cells)

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

Cells can be loaded from views using the `cell()` method and works the same in both contexts:

    // Load an application cell
    $cell = $this->cell('Inbox');
    
    // Load a plugin cell
    $cell = $this->cell('Messaging.Inbox');

1  
2  
3  
4  
5  

The above will load the named cell class and execute the `display()` method. You can execute other methods using the following:

    // Run the expanded() method on the Inbox cell
    $cell = $this->cell('Inbox::expanded');

1  
2  

If you need controller logic to decide which cells to load in a request, you can use the `CellTrait` in your controller to enable the `cell()` method there:

    namespace App\Controller;
    
    use App\Controller\AppController;
    use Cake\View\CellTrait;
    
    class DashboardsController extends AppController
    {
        use CellTrait;
    
        // More code.
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

Passing Arguments to a Cell [​](https://book.cakephp.org/3.x/views/cells.html#passing-arguments-to-a-cell)

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

You will often want to parameterize cell methods to make cells more flexible. By using the second and third arguments of `cell()`, you can pass action parameters and additional options to your cell classes, as an indexed array:

    $cell = $this->cell('Inbox::recent', ['-3 days']);

1  

The above would match the following function signature:

    public function recent($since)
    {
    }

1  
2  
3  

Rendering a Cell [​](https://book.cakephp.org/3.x/views/cells.html#rendering-a-cell)

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

Once a cell has been loaded and executed, you'll probably want to render it. The easiest way to render a cell is to echo it:

    <?= $cell ?>

1  

This will render the template matching the lowercased and underscored version of our action name, e.g. **display.ctp**.

Because cells use `View` to render templates, you can load additional cells within a cell template if required.

NOTE

Echoing a cell uses the PHP `__toString()` magic method which prevents PHP from showing the filename and line number for any fatal errors raised. To obtain a meanful error message, it is recommended to use the `Cell::render()` method, for example `<?= $cell->render() ?>`.

### Rendering Alternate Templates [​](https://book.cakephp.org/3.x/views/cells.html#rendering-alternate-templates)

By convention cells render templates that match the action they are executing. If you need to render a different view template, you can specify the template to use when rendering the cell:

    // Calling render() explicitly
    echo $this->cell('Inbox::recent', ['-3 days'])->render('messages');
    
    // Set template before echoing the cell.
    $cell = $this->cell('Inbox');
    $cell->viewBuilder()->setTemplate('messages');
    // Before 3.4
    $cell->viewBuilder()->template('messages');
    // Before 3.1
    $cell->template = 'messages';
    echo $cell;

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

### Caching Cell Output [​](https://book.cakephp.org/3.x/views/cells.html#caching-cell-output)

When rendering a cell you may want to cache the rendered output if the contents don't change often or to help improve performance of your application. You can define the `cache` option when creating a cell to enable & configure caching:

    // Cache using the default config and a generated key
    $cell = $this->cell('Inbox', [], ['cache' => true]);
    
    // Cache to a specific cache config and a generated key
    $cell = $this->cell('Inbox', [], ['cache' => ['config' => 'cell_cache']]);
    
    // Specify the key and config to use.
    $cell = $this->cell('Inbox', [], [\
        'cache' => ['config' => 'cell_cache', 'key' => 'inbox_' . $user->id]\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

If a key is generated the underscored version of the cell class and template name will be used.

NOTE

A new `View` instance is used to render each cell and these new objects do not share context with the main template / layout. Each cell is self-contained and only has access to variables passed as arguments to the `View::cell()` call.

Paginating Data inside a Cell [​](https://book.cakephp.org/3.x/views/cells.html#paginating-data-inside-a-cell)

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

Creating a cell that renders a paginated result set can be done by leveraging the `Paginator` class of the ORM. An example of paginating a user's favorite messages could look like:

    namespace App\View\Cell;
    
    use Cake\View\Cell;
    use Cake\Datasource\Paginator;
    
    class FavoritesCell extends Cell
    {
        public function display($user)
        {
            $this->loadModel('Messages');
    
            // Create a paginator
            $paginator = new Paginator();
    
            // Paginate the model
            $results = $paginator->paginate(
                $this->Messages,
                $this->request->getQueryParams(),
                [\
                    // Use a parameterized custom finder.\
                    'finder' => ['favorites' => [$user]],\
    \
                    // Use scoped query string parameters.\
                    'scope' => 'favorites',\
                ]
            );
    
            $paging = $paginator->getPagingParams() + (array)$this->request->getParam('paging');
            $this->request = $this->request->withParam('paging', $paging);
    
            $this->set('favorites', $results);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  

The above cell would paginate the `Messages` model using [scoped pagination parameters](https://book.cakephp.org/3.x/controllers/components/pagination.html#paginating-multiple-queries)
.

Added in version 3.5.0

`Cake\Datasource\Paginator` was added in 3.5.0.

Cell Options [​](https://book.cakephp.org/3.x/views/cells.html#cell-options)

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

Cells can declare constructor options that are converted into properties when creating a cell object:

    namespace App\View\Cell;
    
    use Cake\View\Cell;
    use Cake\Datasource\Paginator;
    
    class FavoritesCell extends Cell
    {
        protected $_validCellOptions = ['limit'];
    
        protected $limit = 3;
    
        public function display($userId)
        {
            $this->loadModel('Users');
            $result = $this->Users->find('friends', ['for' => $userId]);
            $this->set('favorites', $result);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

Here we have defined a `$limit` property and add `limit` as a cell option. This will allow us to define the option when creating the cell:

    $cell = $this->cell('Favorites', [$user->id], ['limit' => 10])

1  

Cell options are handy when you want data available as properties allowing you to override default values.

---

# CMS Tutorial - Creating the Database | CakePHP

[Skip to content](https://book.cakephp.org/3.x/tutorials-and-examples/cms/database.html#VPContent)

Return to top

CMS Tutorial - Creating the Database [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/database.html#cms-tutorial-creating-the-database)

===================================================================================================================================================

Now that we have CakePHP installed, let's set up the database for our `CMS (Content Management System)` application. If you haven't already done so, create an empty database for use in this tutorial, with a name of your choice, e.g. `cake_cms`. You can execute the following SQL to create the necessary tables:

    USE cake_cms;
    
    CREATE TABLE users (
        id INT AUTO_INCREMENT PRIMARY KEY,
        email VARCHAR(255) NOT NULL,
        password VARCHAR(255) NOT NULL,
        created DATETIME,
        modified DATETIME
    );
    
    CREATE TABLE articles (
        id INT AUTO_INCREMENT PRIMARY KEY,
        user_id INT NOT NULL,
        title VARCHAR(255) NOT NULL,
        slug VARCHAR(191) NOT NULL,
        body TEXT,
        published BOOLEAN DEFAULT FALSE,
        created DATETIME,
        modified DATETIME,
        UNIQUE KEY (slug),
        FOREIGN KEY user_key (user_id) REFERENCES users(id)
    ) CHARSET=utf8mb4;
    
    CREATE TABLE tags (
        id INT AUTO_INCREMENT PRIMARY KEY,
        title VARCHAR(191),
        created DATETIME,
        modified DATETIME,
        UNIQUE KEY (title)
    ) CHARSET=utf8mb4;
    
    CREATE TABLE articles_tags (
        article_id INT NOT NULL,
        tag_id INT NOT NULL,
        PRIMARY KEY (article_id, tag_id),
        FOREIGN KEY tag_key(tag_id) REFERENCES tags(id),
        FOREIGN KEY article_key(article_id) REFERENCES articles(id)
    );
    
    INSERT INTO users (email, password, created, modified)
    VALUES
    ('[email protected]', 'secret', NOW(), NOW());
    
    INSERT INTO articles (user_id, title, slug, body, published, created, modified)
    VALUES
    (1, 'First Post', 'first-post', 'This is the first post.', 1, now(), now());

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40  
41  
42  
43  
44  
45  
46  

You may have noticed that the `articles_tags` table used a composite primary key. CakePHP supports composite primary keys almost everywhere allowing you to have simpler schemas that don't require additional `id` columns.

The table and column names we used were not arbitrary. By using CakePHP's [naming conventions](https://book.cakephp.org/3.x/intro/conventions.html)
, we can leverage CakePHP more effectively and avoid needing to configure the framework. While CakePHP is flexible enough to accommodate almost any database schema, adhering to the conventions will save you time as you can leverage the convention based defaults CakePHP provides.

Database Configuration [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/database.html#database-configuration)

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

Next, let's tell CakePHP where our database is and how to connect to it. Replace the values in the `Datasources.default` array in your **config/app\_local.php** file with those that apply to your setup. A sample completed configuration array might look something like the following:

    <?php
    return [\
        // More configuration above.\
        'Datasources' => [\
            'default' => [\
                'className' => 'Cake\Database\Connection',\
                'driver' => 'Cake\Database\Driver\Mysql',\
                'persistent' => false,\
                'host' => 'localhost',\
                'username' => 'cakephp',\
                'password' => 'AngelF00dC4k3~',\
                'database' => 'cake_cms',\
                'encoding' => 'utf8mb4',\
                'timezone' => 'UTC',\
                'cacheMetadata' => true,\
            ],\
        ],\
        // More configuration below.\
    ];

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  

Once you've saved your **config/app\_local.php** file, you should see that 'CakePHP is able to connect to the database' section have a green chef hat.

NOTE

A copy of CakePHP's default configuration file is found in **config/app.default.php**.

Creating our First Model [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/database.html#creating-our-first-model)

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

Models are the heart of a CakePHP applications. They enable us to read and modify our data. They allow us to build relations between our data, validate data, and apply application rules. Models build the foundations necessary to build our controller actions and templates.

CakePHP's models are composed of `Table` and `Entity` objects. `Table` objects provide access to the collection of entities stored in a specific table. They are stored in **src/Model/Table**. The file we'll be creating will be saved to **src/Model/Table/ArticlesTable.php**. The completed file should look like this:

    <?php
    // src/Model/Table/ArticlesTable.php
    namespace App\Model\Table;
    
    use Cake\ORM\Table;
    
    class ArticlesTable extends Table
    {
        public function initialize(array $config)
        {
            $this->addBehavior('Timestamp');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

We've attached the [Timestamp](https://book.cakephp.org/3.x/orm/behaviors/timestamp.html)
 behavior which will automatically populate the `created` and `modified` columns of our table. By naming our Table object `ArticlesTable`, CakePHP can use naming conventions to know that our model uses the `articles` table. CakePHP also uses conventions to know that the `id` column is our table's primary key.

NOTE

CakePHP will dynamically create a model object for you if it cannot find a corresponding file in **src/Model/Table**. This also means that if you accidentally name your file wrong (i.e. articlestable.php or ArticleTable.php), CakePHP will not recognize any of your settings and will use the generated model instead.

We'll also create an Entity class for our Articles. Entities represent a single record in the database, and provide row level behavior for our data. Our entity will be saved to **src/Model/Entity/Article.php**. The completed file should look like this:

    <?php
    // src/Model/Entity/Article.php
    namespace App\Model\Entity;
    
    use Cake\ORM\Entity;
    
    class Article extends Entity
    {
        protected $_accessible = [\
            '*' => true,\
            'id' => false,\
            'slug' => false,\
        ];
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

Our entity is quite slim right now, and we've only setup the `_accessible` property which controls how properties can be modified by [Entities Mass Assignment](https://book.cakephp.org/3.x/orm/entities.html#entities-mass-assignment)
.

We can't do much with our models right now, so next we'll create our first [Controller and Template](https://book.cakephp.org/3.x/tutorials-and-examples/cms/articles-controller.html)
 to allow us to interact with our model.

---

# Time | CakePHP

[Skip to content](https://book.cakephp.org/3.x/views/helpers/time.html#VPContent)

Return to top

Time [​](https://book.cakephp.org/3.x/views/helpers/time.html#time)

====================================================================

`class` Cake\\View\\Helper\\**TimeHelper**(View $view, array $config = \[\])

The TimeHelper allows for the quick processing of time related information. The TimeHelper has two main tasks that it can perform:

1.  It can format time strings.
2.  It can test time.

Using the Helper [​](https://book.cakephp.org/3.x/views/helpers/time.html#using-the-helper)

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

A common use of the TimeHelper is to offset the date and time to match a user's time zone. Lets use a forum as an example. Your forum has many users who may post messages at any time from any part of the world. An easy way to manage the time is to save all dates and times as GMT+0 or UTC. Uncomment the line `date_default_timezone_set('UTC');` in **config/bootstrap.php** to ensure your application's time zone is set to GMT+0.

Next add a time zone field to your users table and make the necessary modifications to allow your users to set their time zone. Now that we know the time zone of the logged in user we can correct the date and time on our posts using the TimeHelper:

    echo $this->Time->format(
      $post->created,
      \IntlDateFormatter::FULL,
      null,
      $user->time_zone
    );
    // Will display 'Saturday, August 22, 2011 at 11:53:00 PM GMT'
    // for a user in GMT+0. While displaying,
    // 'Saturday, August 22, 2011 at 03:53 PM GMT-8:00'
    // for a user in GMT-8

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

Most of TimeHelper's features are intended as backwards compatible interfaces for applications that are upgrading from older versions of CakePHP. Because the ORM returns `Cake\I18n\Time` instances for every `timestamp` and `datetime` column, you can use the methods there to do most tasks. For example, to read about the accepted formatting strings take a look at the [Cake\\I18n\\Time::i18nFormat()](https://api.cakephp.org/3.x/class-Cake.I18n.Time.html#_i18nFormat)
 method.

---

# Helpers | CakePHP

[Skip to content](https://book.cakephp.org/3.x/views/helpers.html#VPContent)

Return to top

Helpers [​](https://book.cakephp.org/3.x/views/helpers.html#helpers)

=====================================================================

Helpers are the component-like classes for the presentation layer of your application. They contain presentational logic that is shared between many views, elements, or layouts. This chapter will show you how to configure helpers. How to load helpers and use those helpers, and outline the simple steps for creating your own custom helpers.

CakePHP includes a number of helpers that aid in view creation. They assist in creating well-formed markup (including forms), aid in formatting text, times and numbers, and can even speed up AJAX functionality. For more information on the helpers included in CakePHP, check out the chapter for each helper:

*   [Breadcrumbs](https://book.cakephp.org/3.x/views/helpers/breadcrumbs.html)
    
*   [Flash](https://book.cakephp.org/3.x/views/helpers/flash.html)
    
*   [Form](https://book.cakephp.org/3.x/views/helpers/form.html)
    
*   [Html](https://book.cakephp.org/3.x/views/helpers/html.html)
    
*   [Number](https://book.cakephp.org/3.x/views/helpers/number.html)
    
*   [Paginator](https://book.cakephp.org/3.x/views/helpers/paginator.html)
    
*   [Rss](https://book.cakephp.org/3.x/views/helpers/rss.html)
    
*   [Session](https://book.cakephp.org/3.x/views/helpers/session.html)
    
*   [Text](https://book.cakephp.org/3.x/views/helpers/text.html)
    
*   [Time](https://book.cakephp.org/3.x/views/helpers/time.html)
    
*   [Url](https://book.cakephp.org/3.x/views/helpers/url.html)
    

Configuring Helpers [​](https://book.cakephp.org/3.x/views/helpers.html#configuring-helpers)

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

You load helpers in CakePHP by declaring them in a view class. An `AppView` class comes with every CakePHP application and is the ideal place to load helpers:

    class AppView extends View
    {
        public function initialize()
        {
            parent::initialize();
            $this->loadHelper('Html');
            $this->loadHelper('Form');
            $this->loadHelper('Flash');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

To load helpers from plugins use the `plugin syntax` used elsewhere in CakePHP:

    $this->loadHelper('Blog.Comment');

1  

You don't have to explicitly load Helpers that come from CakePHP or your application. These helpers can be lazily loaded upon first use. For example:

    // Loads the FormHelper if it has not already been loaded.
    $this->Form->create($article);

1  
2  

From within a plugin's views, plugin helpers can also be lazily loaded. For example, view templates in the 'Blog' plugin, can lazily load helpers from the same plugin.

### Conditionally Loading Helpers [​](https://book.cakephp.org/3.x/views/helpers.html#conditionally-loading-helpers)

You can use the current action name to conditionally load helpers:

    class AppView extends View
    {
        public function initialize()
        {
            parent::initialize();
            if ($this->request->getParam('action') === 'index') {
                $this->loadHelper('ListPage');
            }
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

You can also use your controller's `beforeRender` method to load helpers:

    class ArticlesController extends AppController
    {
        public function beforeRender(Event $event)
        {
            parent::beforeRender($event);
            $this->viewBuilder()->helpers(['MyHelper']);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  

### Configuration options [​](https://book.cakephp.org/3.x/views/helpers.html#configuration-options)

You can pass configuration options to helpers. These options can be used to set attribute values or modify the behavior of a helper:

    namespace App\View\Helper;
    
    use Cake\View\Helper;
    use Cake\View\View;
    
    class AwesomeHelper extends Helper
    {
        // initialize() hook is available since 3.2. For prior versions you can
        // override the constructor if required.
        public function initialize(array $config)
        {
            debug($config);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

Options can be specified when declaring helpers in controller as shown:

    namespace App\Controller;
    
    use App\Controller\AppController;
    
    class AwesomeController extends AppController
    {
        public $helpers = ['Awesome' => ['option1' => 'value1']];
    }

1  
2  
3  
4  
5  
6  
7  
8  

By default all configuration options will be merged with the `$_defaultConfig` property. This property should define the default values of any configuration your helper requires. For example:

    namespace App\View\Helper;
    
    use Cake\View\Helper;
    use Cake\View\StringTemplateTrait;
    
    class AwesomeHelper extends Helper
    {
        use StringTemplateTrait;
    
        protected $_defaultConfig = [\
            'errorClass' => 'error',\
            'templates' => [\
                'label' => '<label for="{{for}}">{{content}}</label>',\
            ],\
        ];
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  

Any configuration provided to your helper's constructor will be merged with the default values during construction and the merged data will be set to `_config`. You can use the `config()` method to read runtime configuration:

    // Read the errorClass config option.
    $class = $this->Awesome->config('errorClass');

1  
2  

Using helper configuration allows you to declaratively configure your helpers and keep configuration logic out of your controller actions. If you have configuration options that cannot be included as part of a class declaration, you can set those in your controller's beforeRender callback:

    class PostsController extends AppController
    {
        public function beforeRender(Event $event)
        {
            parent::beforeRender($event);
            $builder = $this->viewBuilder();
            $builder->helpers([\
                'CustomStuff' => $this->_getCustomStuffConfig(),\
            ]);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

### Aliasing Helpers [​](https://book.cakephp.org/3.x/views/helpers.html#aliasing-helpers)

One common setting to use is the `className` option, which allows you to create aliased helpers in your views. This feature is useful when you want to replace `$this->Html` or another common Helper reference with a custom implementation:

    // src/View/AppView.php
    class AppView extends View
    {
        public function initialize()
        {
            $this->loadHelper('Html', [\
                'className' => 'MyHtml'\
            ]);
        }
    }
    
    // src/View/Helper/MyHtmlHelper.php
    namespace App\View\Helper;
    
    use Cake\View\Helper\HtmlHelper;
    
    class MyHtmlHelper extends HtmlHelper
    {
        // Add your code to override the core HtmlHelper
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  

The above would _alias_ `MyHtmlHelper` to `$this->Html` in your views.

NOTE

Aliasing a helper replaces that instance anywhere that helper is used, including inside other Helpers.

Using Helpers [​](https://book.cakephp.org/3.x/views/helpers.html#using-helpers)

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

Once you've configured which helpers you want to use in your controller, each helper is exposed as a public property in the view. For example, if you were using the `HtmlHelper` you would be able to access it by doing the following:

    echo $this->Html->css('styles');

1  

The above would call the `css()` method on the HtmlHelper. You can access any loaded helper using `$this->{$helperName}`.

### Loading Helpers On The Fly [​](https://book.cakephp.org/3.x/views/helpers.html#loading-helpers-on-the-fly)

There may be situations where you need to dynamically load a helper from inside a view. You can use the view's `Cake\View\HelperRegistry` to do this:

    // Either one works.
    $mediaHelper = $this->loadHelper('Media', $mediaConfig);
    $mediaHelper = $this->helpers()->load('Media', $mediaConfig);

1  
2  
3  

The HelperRegistry is a [registry](https://book.cakephp.org/3.x/core-libraries/registry-objects.html)
 and supports the registry API used elsewhere in CakePHP.

Callback Methods [​](https://book.cakephp.org/3.x/views/helpers.html#callback-methods)

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

Helpers feature several callbacks that allow you to augment the view rendering process. See the [Helper Api](https://book.cakephp.org/3.x/views/helpers.html#helper-api)
 and the [Events System](https://book.cakephp.org/3.x/core-libraries/events.html)
 documentation for more information.

Creating Helpers [​](https://book.cakephp.org/3.x/views/helpers.html#creating-helpers)

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

You can create custom helper classes for use in your application or plugins. Like most components of CakePHP, helper classes have a few conventions:

*   Helper class files should be put in **src/View/Helper**. For example: **src/View/Helper/LinkHelper.php**
*   Helper classes should be suffixed with `Helper`. For example: `LinkHelper`.
*   When referencing helper class names you should omit the `Helper` suffix. For example: `$this->loadHelper('Link');`.

You'll also want to extend `Helper` to ensure things work correctly:

    /* src/View/Helper/LinkHelper.php */
    namespace App\View\Helper;
    
    use Cake\View\Helper;
    
    class LinkHelper extends Helper
    {
        public function makeEdit($title, $url)
        {
            // Logic to create specially formatted link goes here...
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

### Including Other Helpers [​](https://book.cakephp.org/3.x/views/helpers.html#including-other-helpers)

You may wish to use some functionality already existing in another helper. To do so, you can specify helpers you wish to use with a `$helpers` array, formatted just as you would in a controller:

    /* src/View/Helper/LinkHelper.php (using other helpers) */
    
    namespace App\View\Helper;
    
    use Cake\View\Helper;
    
    class LinkHelper extends Helper
    {
        public $helpers = ['Html'];
    
        public function makeEdit($title, $url)
        {
            // Use the HTML helper to output
            // Formatted data:
    
            $link = $this->Html->link($title, $url, ['class' => 'edit']);
    
            return '<div class="editOuter">' . $link . '</div>';
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  

### Using Your Helper [​](https://book.cakephp.org/3.x/views/helpers.html#using-your-helper)

Once you've created your helper and placed it in **src/View/Helper/**, you can load it in your views:

    class AppView extends View
    {
        public function initialize()
        {
            parent::initialize();
            $this->loadHelper('Link');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  

Once your helper has been loaded, you can use it in your views by accessing the matching view property:

    <!-- make a link using the new helper -->
    <?= $this->Link->makeEdit('Change this Recipe', '/recipes/edit/5') ?>

1  
2  

NOTE

The `HelperRegistry` will attempt to lazy load any helpers not specifically identified in your `Controller`.

### Accessing View Variables Inside Your Helper [​](https://book.cakephp.org/3.x/views/helpers.html#accessing-view-variables-inside-your-helper)

If you would like to access a View variable inside a helper, you can use `$this->_View->get()` like:

    class AwesomeHelper extends Helper
    {
        public $helpers = ['Html'];
    
        public function someMethod()
        {
            // set meta description
            echo $this->Html->meta(
                'description', $this->_View->get('metaDescription'), ['block' => 'meta']
            );
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

### Rendering A View Element Inside Your Helper [​](https://book.cakephp.org/3.x/views/helpers.html#rendering-a-view-element-inside-your-helper)

If you would like to render an Element inside your Helper you can use `$this->_View->element()` like:

    class AwesomeHelper extends Helper
    {
        public function someFunction()
        {
            // output directly in your helper
            echo $this->_View->element(
                '/path/to/element',
                ['foo'=>'bar','bar'=>'foo']
            );
    
            // or return it to your view
            return $this->_View->element(
                '/path/to/element',
                ['foo'=>'bar','bar'=>'foo']
            );
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

Helper Class [​](https://book.cakephp.org/3.x/views/helpers.html#helper-class)

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

`class` **Helper**

### Callbacks [​](https://book.cakephp.org/3.x/views/helpers.html#callbacks)

By implementing a callback method in a helper, CakePHP will automatically subscribe your helper to the relevant event. Unlike previous versions of CakePHP you should _not_ call `parent` in your callbacks, as the base Helper class does not implement any of the callback methods.

`method` Helper::**beforeRenderFile**(Event $event, $viewFile)

`method` Helper::**afterRenderFile**(Event $event, $viewFile, $content)

`method` Helper::**beforeRender**(Event $event, $viewFile)

`method` Helper::**afterRender**(Event $event, $viewFile)

`method` Helper::**beforeLayout**(Event $event, $layoutFile)

`method` Helper::**afterLayout**(Event $event, $layoutFile)

---

# Session | CakePHP

[Skip to content](https://book.cakephp.org/3.x/views/helpers/session.html#VPContent)

Return to top

Session [​](https://book.cakephp.org/3.x/views/helpers/session.html#session)

=============================================================================

`class` Cake\\View\\Helper\\**SessionHelper**(View $view, array $config = \[\])

Deprecated in version 3.0.0

The SessionHelper is deprecated in 3.x. Instead you should use either the [FlashHelper](https://book.cakephp.org/3.x/views/helpers/flash.html)
 or [access the session via the request](https://book.cakephp.org/3.x/development/sessions.html#accessing-session-object)
.

As a natural counterpart to the Session object, the Session Helper replicates most of the object's functionality and makes it available in your view.

The major difference between the SessionHelper and the Session object is that the helper does _not_ have the ability to write to the session.

As with the session object, data is read by using `dot notation` array structures:

    ['User' => [\
        'username' => '[email protected]'\
    ]];

1  
2  
3  

Given the previous array structure, the node would be accessed by `User.username`, with the dot indicating the nested array. This notation is used for all SessionHelper methods wherever a `$key` is used.

`method` Cake\\View\\Helper\\SessionHelper::**read**(string $key)

`method` Cake\\View\\Helper\\SessionHelper::**check**(string $key)

---

# Rss | CakePHP

[Skip to content](https://book.cakephp.org/3.x/views/helpers/rss.html#VPContent)

Return to top

Rss [​](https://book.cakephp.org/3.x/views/helpers/rss.html#rss)

=================================================================

`class` Cake\\View\\Helper\\**RssHelper**(View $view, array $config = \[\])

The RssHelper makes generating XML for [RSS feeds](https://en.wikipedia.org/wiki/RSS)
 easy.

Deprecated in version 3.5.0

RssHelper is deprecated as of 3.5.0, and will be removed in 4.0.0

Creating an RSS Feed with the RssHelper [​](https://book.cakephp.org/3.x/views/helpers/rss.html#creating-an-rss-feed-with-the-rsshelper)

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

This example assumes you have a Articles Controller, Articles Table and an Article Entity already created and want to make an alternative view for RSS.

Creating an XML/RSS version of your Articles index action is a snap with CakePHP. After a few simple steps you can simply append the desired extension .rss to `articles` making your URL `articles.rss`. This will work with the index action included as well so `articles/index` would become `articles/index.rss` Before we jump too far ahead trying to get our webservice up and running we need to do a few things. First extensions parsing needs to be activated, this is done in **config/routes.php**:

    Router::extensions('rss');

1  

In the call above we've activated the .rss extension. When using `Cake\Routing\Router::extensions()` you can pass a string or an array of extensions as first argument. This will activate each extension/content-type for use in your application. Now when the address `articles.rss` is requested you will get an XML version of your `articles` index action. However, first we need to edit the controller to add in the rss-specific code.

### Controller Code [​](https://book.cakephp.org/3.x/views/helpers/rss.html#controller-code)

It is a good idea to add RequestHandler to your ArticlesController's `initialize()` method. This will allow a lot of automagic to occur:

    public function initialize()
    {
        parent::initialize();
        $this->loadComponent('RequestHandler');
    }

1  
2  
3  
4  
5  

Before we can make an RSS version of our `articles` index action we need to get a few things in order. It may be tempting to put the channel metadata in the controller action and pass it to your view using the `Cake\Controller\Controller::set()` method but this is inappropriate. That information can also go in the view. That will come later though, for now if you have a different set of logic for the data used to make the RSS feed and the data for the HTML view you can use the `Cake\Controller\Component\RequestHandler::isRss()` method, otherwise your controller can stay the same:

    // Modify the Articles Controller action that corresponds to
    // the action which deliver the rss feed, which is the
    // Index action in our example.
    
    public function index()
    {
        if ($this->RequestHandler->isRss() ) {
            $articles = $this->Articles
                ->find()
                ->limit(20)
                ->order(['created' => 'desc']);
            $this->set(compact('articles'));
        } else {
            // this is not an Rss request, so deliver
            // data used by website's interface.
            $this->paginate = [\
                'order' => ['created' => 'desc'],\
                'limit' => 10\
            ];
            $this->set('articles', $this->paginate($this->Articles));
            $this->set('_serialize', ['articles']);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  

With all the View variables set we need to create an rss layout.

### Layout [​](https://book.cakephp.org/3.x/views/helpers/rss.html#layout)

An Rss layout is very simple, put the following contents in **src/Template/Layout/rss/default.ctp**:

    if (!isset($documentData)) {
        $documentData = [];
    }
    if (!isset($channelData)) {
        $channelData = [];
    }
    if (!isset($channelData['title'])) {
        $channelData['title'] = $this->fetch('title');
    }
    $channel = $this->Rss->channel([], $channelData, $this->fetch('content'));
    echo $this->Rss->document($documentData, $channel);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

It doesn't look like much but thanks to the power in the `RssHelper` it's doing a lot of lifting for us. We haven't set `$documentData` or `$channelData` in the controller, however in CakePHP your views can pass variables back to the layout. Which is where our `$channelData` array will come from setting all of the meta data for our feed.

Next up is view file for my articles index action. Much like the layout file we created, we need to create a **src/Template/Articles/rss/** directory and create a new **index.ctp** inside that folder. The contents of the file are below.

### View [​](https://book.cakephp.org/3.x/views/helpers/rss.html#view)

Our view, located at **src/Template/Articles/rss/index.ctp**, begins by setting the `$documentData` and `$channelData` variables for the layout, these contain all the metadata for our RSS feed. This is done by using the `Cake\View\View::set()` method which is analogous to the `Cake\Controller\Controller::set()` method. Here though we are passing the channel's metadata back to the layout:

    $this->set('channelData', [\
        'title' => __("Most Recent Articles"),\
        'link' => $this->Url->build('/', true),\
        'description' => __("Most recent articles."),\
        'language' => 'en-us'\
    ]);

1  
2  
3  
4  
5  
6  

The second part of the view generates the elements for the actual records of the feed. This is accomplished by looping through the data that has been passed to the view ($items) and using the `RssHelper::item()` method. The other method you can use, `RssHelper::items()` which takes a callback and an array of items for the feed. The callback method is usually called `transformRss()`. There is one downfall to this method, which is that you cannot use any of the other helper classes to prepare your data inside the callback method because the scope inside the method does not include anything that is not passed inside, thus not giving access to the TimeHelper or any other helper that you may need. The `RssHelper::item()` transforms the associative array into an element for each key value pair.

NOTE

You will need to modify the $link variable as appropriate to your application. You might also want to use a [virtual field](https://book.cakephp.org/3.x/orm/entities.html#entities-virtual-fields)
 in your Entity.

    foreach ($articles as $article) {
        $created = strtotime($article->created);
    
        $link = [\
            'controller' => 'Articles',\
            'action' => 'view',\
            'year' => date('Y', $created),\
            'month' => date('m', $created),\
            'day' => date('d', $created),\
            'slug' => $article->slug\
        ];
    
        // Remove & escape any HTML to make sure the feed content will validate.
        $body = h(strip_tags($article->body));
        $body = $this->Text->truncate($body, 400, [\
            'ending' => '...',\
            'exact'  => true,\
            'html'   => true,\
        ]);
    
        echo  $this->Rss->item([], [\
            'title' => $article->title,\
            'link' => $link,\
            'guid' => ['url' => $link, 'isPermaLink' => 'true'],\
            'description' => $body,\
            'pubDate' => $article->created\
        ]);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  

You can see above that we can use the loop to prepare the data to be transformed into XML elements. It is important to filter out any non-plain text characters out of the description, especially if you are using a rich text editor for the body of your blog. In the code above we used `strip_tags()` and `h()` to remove/escape any XML special characters from the content, as they could cause validation errors. Once we have set up the data for the feed, we can then use the `RssHelper::item()` method to create the XML in RSS format. Once you have all this setup, you can test your RSS feed by going to your site `/articles.rss` and you will see your new feed. It is always important that you validate your RSS feed before making it live. This can be done by visiting sites that validate the XML such as Feed Validator or the w3c site at [https://validator.w3.org/feed/](https://validator.w3.org/feed/)
.

NOTE

You may need to set the value of 'debug' in your core configuration to `false` to get a valid feed, because of the various debug information added automagically under higher debug settings that break XML syntax or feed validation rules.

---

# Plugins | CakePHP

[Skip to content](https://book.cakephp.org/3.x/plugins.html#VPContent)

Return to top

Plugins [​](https://book.cakephp.org/3.x/plugins.html#plugins)

===============================================================

CakePHP allows you to set up a combination of controllers, models, and views and release them as a pre-packaged application plugin that others can use in their CakePHP applications. If you've created great user management, a simple blog, or web service adapters in one of your applications, why not package it as a CakePHP plugin? This way you can reuse it in your other applications, and share with the community!

A CakePHP plugin is separate from the host application itself and generally provides some well-defined functionality that can be packaged up neatly, and reused with little effort in other applications. The application and the plugin operate in their own respective spaces, but share the application's configuration data (e.g. database connections, email transports)

In CakePHP 3.0 each plugin defines its own top-level namespace. For example: `DebugKit`. By convention, plugins use their package name as their namespace. If you'd like to use a different namespace, you can configure the plugin namespace, when plugins are loaded.

Installing a Plugin With Composer [​](https://book.cakephp.org/3.x/plugins.html#installing-a-plugin-with-composer)

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

Many plugins are available on [Packagist](https://packagist.org/)
 and can be installed with `Composer`. To install DebugKit, you would do the following:

    php composer.phar require cakephp/debug_kit

1  

This would install the latest version of DebugKit and update your **composer.json**, **composer.lock** file, update **vendor/cakephp-plugins.php**, and update your autoloader.

Manually Installing a Plugin [​](https://book.cakephp.org/3.x/plugins.html#manually-installing-a-plugin)

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

If the plugin you want to install is not available on packagist.org, you can clone or copy the plugin code into your **plugins** directory. Assuming you want to install a plugin named 'ContactManager', you should have a folder in **plugins** named 'ContactManager'. In this directory are the plugin's src, tests and any other directories.

### Manually Autoloading Plugin Classes [​](https://book.cakephp.org/3.x/plugins.html#manually-autoloading-plugin-classes)

If you install your plugins via `composer` or `bake` you shouldn't need to configure class autoloading for your plugins.

If we were installing a plugin named `MyPlugin` manually you would need to modify your application's **composer.json** file to contain the following information:

    {
        "autoload": {
            "psr-4": {
                "MyPlugin\\": "plugins/MyPlugin/src/"
            }
        },
        "autoload-dev": {
            "psr-4": {
                "MyPlugin\\Test\\": "plugins/MyPlugin/tests/"
            }
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

If you are using vendor namespaces for your plugins, the namespace to path mapping should resemble the following:

    {
        "autoload": {
            "psr-4": {
                "AcmeCorp\\Users\\": "plugins/AcmeCorp/Users/src/",
                "AcmeCorp\\Users\\Test\\": "plugins/AcmeCorp/Users/tests/"
            }
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  

Additionally, you will need to tell Composer to refresh its autoloading cache:

    php composer.phar dumpautoload

1  

If you are unable to use Composer for any reason, you can also configure autoloading with `Plugin`:

    Plugin::load('ContactManager', ['autoload' => true]);

1  

Deprecated in version 3.7.0

Plugin::load() and `autoload` option are deprecated.

NOTE

IMPORTANT: `autoload` option is not available on `addPlugin()`, you should use `composer dumpautoload` instead.

Loading a Plugin [​](https://book.cakephp.org/3.x/plugins.html#loading-a-plugin)

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

If you want to use a plugin's routes, console commands, middleware, or event listeners you will need to load the plugin. Plugins are loaded in your application's `bootstrap()` function:

    // In src/Application.php. Requires at least 3.6.0
    use Cake\Http\BaseApplication;
    use ContactManager\Plugin as ContactManagerPlugin;
    
    class Application extends BaseApplication {
        public function bootstrap()
        {
            parent::bootstrap();
            // Load the contact manager plugin by class name
            $this->addPlugin(ContactManagerPlugin::class);
    
            // Load a plugin with a vendor namespace by 'short name'
            $this->addPlugin('AcmeCorp/ContactManager');
    
            // Load a dev dependency that will not exist in production builds.
            $this->addOptionalPlugin('AcmeCorp/ContactManager');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

If you just want to use helpers, behaviors or components from a plugin you do not need to load a plugin.

Prior to 3.6.0, you should use `Plugin::load()`:

    // In config/bootstrap.php
    
    // Loads a single plugin
    Plugin::load('ContactManager');
    
    // Loads a plugin with a vendor namespace at top level.
    Plugin::load('AcmeCorp/ContactManager');

1  
2  
3  
4  
5  
6  
7  

There is also a handy shell command to enable the plugin. Execute the following line:

    bin/cake plugin load ContactManager

1  

This would update your application's bootstrap method, or put the `$this->addPlugin('ContactManager');` snippet in the bootstrap for you.

Added in version 3.6.0

`addPlugin()` was added.

Added in version 3.9.0

The `addOptionalPlugin()` method was added.

Plugin Hook Configuration [​](https://book.cakephp.org/3.x/plugins.html#plugin-hook-configuration)

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

Plugins offer several hooks that allow a plugin to inject itself into the appropriate parts of your application. The hooks are:

*   `bootstrap` Used to load plugin default configuration files, define constants and other global functions.
*   `routes` Used to load routes for a plugin. Fired after application routes are loaded.
*   `middleware` Used to add plugin middleware to an application's middleware queue.
*   `console` Used to add console commands to an application's command collection.

When loading plugins you can configure which hooks are enabled. By default plugins without a [Plugin Objects](https://book.cakephp.org/3.x/plugins.html#plugin-objects)
 have all hooks disabled. New style plugins allow plugin authors to set defaults, which can be configured by you in your appliation:

    // In Application::bootstrap()
    use ContactManager\Plugin as ContactManagerPlugin;
    
    // Disable routes for the ContactManager plugin
    $this->addPlugin(ContactManagerPlugin::class, ['routes' => false]);

1  
2  
3  
4  
5  

You can configure hooks with array options, or the methods provided by plugin classes:

    // In Application::bootstrap()
    use ContactManager\Plugin as ContactManagerPlugin;
    
    // Use the disable/enable to configure hooks.
    $plugin = new ContactManagerPlugin();
    
    $plugin->disable('bootstrap');
    $plugin->enable('routes');
    $this->addPlugin($plugin);

1  
2  
3  
4  
5  
6  
7  
8  
9  

Plugin objects also know their names and path information:

    $plugin = new ContactManagerPlugin();
    
    // Get the plugin name.
    $name = $plugin->getName();
    
    // Path to the plugin root, and other paths.
    $path = $plugin->getPath();
    $path = $plugin->getConfigPath();
    $path = $plugin->getClassPath();

1  
2  
3  
4  
5  
6  
7  
8  
9  

### Old Style Plugins [​](https://book.cakephp.org/3.x/plugins.html#old-style-plugins)

Prior to 3.6.0, you will need to enable the `bootstrap` and `routes` hooks. Old style plugins do not support `middleware` and `console` hooks:

    // In config/bootstrap.php,
    // or in Application::bootstrap()
    
    // Using loadAll()
    Plugin::loadAll([\
        'Blog' => ['routes' => true],\
        'ContactManager' => ['bootstrap' => true],\
        'WebmasterTools' => ['bootstrap' => true, 'routes' => true],\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  

Or you can load the plugins individually:

    // Loading just the blog and include routes
    Plugin::load('Blog', ['routes' => true]);
    
    // Include bootstrap configuration/initializer file.
    Plugin::load('ContactManager', ['bootstrap' => true]);

1  
2  
3  
4  
5  

With either approach you no longer need to manually `include()` or `require()` a plugin's configuration or routes file -- it happens automatically at the right time and place.

You can specify a set of defaults for `loadAll()` which will apply to every plugin that doesn't have a more specific configuration.

The following example will load the bootstrap file from all plugins, and additionally the routes from the Blog plugin:

    Plugin::loadAll([\
        ['bootstrap' => true],\
        'Blog' => ['routes' => true]\
    ]);

1  
2  
3  
4  

Note that all files specified should actually exist in the configured plugin(s) or PHP will give warnings for each file it cannot load. You can avoid potential warnings by using the `ignoreMissing` option:

    Plugin::loadAll([\
        ['ignoreMissing' => true, 'bootstrap' => true],\
        'Blog' => ['routes' => true]\
    ]);

1  
2  
3  
4  

When loading plugins, the plugin name used should match the namespace. For example, if you have a plugin with top level namespace `Users` you would load it using:

    Plugin::load('User');

1  

If you prefer to have your vendor name as top level and have a namespace like `AcmeCorp/Users`, then you would load the plugin as:

    Plugin::load('AcmeCorp/Users');

1  

This will ensure that classnames are resolved properly when using `plugin syntax`.

Most plugins will indicate the proper procedure for configuring them and setting up the database in their documentation.

Deprecated in version 3.7.0

Plugin::load() and Plugin::loadAll() are deprecated.

Using Plugin Classes [​](https://book.cakephp.org/3.x/plugins.html#using-plugin-classes)

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

You can reference a plugin's controllers, models, components, behaviors, and helpers by prefixing the name of the plugin.

For example, say you wanted to use the ContactManager plugin's ContactInfoHelper to output formatted contact information in one of your views. In your controller, your `$helpers` array could look like this:

    public $helpers = ['ContactManager.ContactInfo'];

1  

NOTE

This dot separated class name is referred to as `plugin syntax`.

You would then be able to access the `ContactInfoHelper` just like any other helper in your view, such as:

    echo $this->ContactInfo->address($contact);

1  

Plugins can use the models, components, behaviors and helpers provided by the application, or other plugins if necessary:

    // Use an application component
    $this->loadComponent('AppFlash');
    
    // Use another plugin's behavior
    $this->addBehavior('OtherPlugin.AuditLog');

1  
2  
3  
4  
5  

Creating Your Own Plugins [​](https://book.cakephp.org/3.x/plugins.html#creating-your-own-plugins)

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

As a working example, let's begin to create the ContactManager plugin referenced above. To start out, we'll set up our plugin's basic directory structure. It should look like this:

    /src
    /plugins
        /ContactManager
            /config
            /src
                /Plugin.php
                /Controller
                    /Component
                /Model
                    /Table
                    /Entity
                    /Behavior
                /View
                    /Helper
                /Template
                    /Layout
            /tests
                /TestCase
                /Fixture
            /webroot
    

Note the name of the plugin folder, '\*\*ContactManager\*\*'. It is important that this folder has the same name as the plugin.

Inside the plugin folder, you'll notice it looks a lot like a CakePHP application, and that's basically what it is. You don't have to include any of the folders you are not using. Some plugins might only define a Component and a Behavior, and in that case they can completely omit the 'Template' directory.

A plugin can also have basically any of the other directories that your application can, such as Config, Console, webroot, etc.

### Creating a Plugin Using Bake [​](https://book.cakephp.org/3.x/plugins.html#creating-a-plugin-using-bake)

The process of creating plugins can be greatly simplified by using bake.

In order to bake a plugin, use the following command:

    bin/cake bake plugin ContactManager

1  

Bake can be used to create classes in your plugin. For example to generate a plugin controller you could run:

    bin/cake bake controller --plugin ContactManager Contacts

1  

Please refer to the chapter [Code Generation with Bake](https://book.cakephp.org/3.x/bake/usage.html)
 if you have any problems with using the command line. Be sure to re-generate your autoloader once you've created your plugin:

    php composer.phar dumpautoload

1  

Plugin Objects [​](https://book.cakephp.org/3.x/plugins.html#plugin-objects)

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

Plugin Objects allow a plugin author to define set-up logic, define default hooks, load routes, middleware and console commands. Plugin objects live in **src/Plugin.php**. For our ContactManager plugin, our plugin class could look like:

    namespace ContactManager;
    
    use Cake\Core\BasePlugin;
    use Cake\Core\PluginApplicationInterface;
    
    class Plugin extends BasePlugin
    {
        public function middleware($middleware)
        {
            // Add middleware here.
            $middleware = parent::middleware($middleware);
    
            return $middleware;
        }
    
        public function console($commands)
        {
            // Add console commands here.
            $commands = parent::console($commands);
    
            return $commands;
        }
    
        public function bootstrap(PluginApplicationInterface $app)
        {
            // Add constants, load configuration defaults.
            // By default will load `config/bootstrap.php` in the plugin.
            parent::bootstrap($app);
            // Load another plugin through this plugin
            $app->addPlugin(\My\Plugin::class);
        }
    
        public function routes($routes)
        {
            // Add routes.
            // By default will load `config/routes.php` in the plugin.
            parent::routes($routes);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  

Added in version 3.6.0

Plugin Objects were added in 3.6.0

Plugin Routes [​](https://book.cakephp.org/3.x/plugins.html#plugin-routes)

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

Plugins can provide routes files containing their routes. Each plugin can contain a **config/routes.php** file. This routes file can be loaded when the plugin is added, or in the application's routes file. To create the ContactManager plugin routes, put the following into **plugins/ContactManager/config/routes.php**:

    <?php
    use Cake\Routing\Route\DashedRoute;
    use Cake\Routing\Router;
    
    Router::plugin(
        'ContactManager',
        ['path' => '/contact-manager'],
        function ($routes) {
            $routes->get('/contacts', ['controller' => 'Contacts']);
            $routes->get('/contacts/:id', ['controller' => 'Contacts', 'action' => 'view']);
            $routes->put('/contacts/:id', ['controller' => 'Contacts', 'action' => 'update']);
        }
    );

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

The above will connect default routes for your plugin. You can customize this file with more specific routes later on.

Before you can access your controllers, you'll need to ensure the plugin is loaded and the plugin routes are loaded. In your **src/Application.php** add the following:

    $this->addPlugin('ContactManager', ['routes' => true]);

1  

You can also load plugin routes in your application's routes list. Doing this provides you more control on how plugin routes are loaded and allows you to wrap plugin routes in additional scopes or prefixes:

    Router::scope('/', function ($routes) {
        // Connect other routes.
        $routes->scope('/backend', function ($routes) {
            $routes->loadPlugin('ContactManager');
        });
    });

1  
2  
3  
4  
5  
6  

The above would result in URLs like `/backend/contact-manager/contacts`.

Added in version 3.5.0

`RouteBuilder::loadPlugin()` was added in 3.5.0

Plugin Controllers [​](https://book.cakephp.org/3.x/plugins.html#plugin-controllers)

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

Controllers for our ContactManager plugin will be stored in **plugins/ContactManager/src/Controller/**. Since the main thing we'll be doing is managing contacts, we'll need a ContactsController for this plugin.

So, we place our new ContactsController in **plugins/ContactManager/src/Controller** and it looks like so:

    // plugins/ContactManager/src/Controller/ContactsController.php
    namespace ContactManager\Controller;
    
    use ContactManager\Controller\AppController;
    
    class ContactsController extends AppController
    {
        public function index()
        {
            //...
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

Also make the `AppController` if you don't have one already:

    // plugins/ContactManager/src/Controller/AppController.php
    namespace ContactManager\Controller;
    
    use App\Controller\AppController as BaseController;
    
    class AppController extends BaseController
    {
    }

1  
2  
3  
4  
5  
6  
7  
8  

A plugin's `AppController` can hold controller logic common to all controllers in a plugin but is not required if you don't want to use one.

If you want to access what we've got going thus far, visit `/contact-manager/contacts`. You should get a "Missing Model" error because we don't have a Contact model defined yet.

If your application includes the default routing CakePHP provides you will be able to access your plugin controllers using URLs like:

    // Access the index route of a plugin controller.
    /contact-manager/contacts
    
    // Any action on a plugin controller.
    /contact-manager/contacts/view/1

1  
2  
3  
4  
5  

If your application defines routing prefixes, CakePHP's default routing will also connect routes that use the following pattern:

    /:prefix/:plugin/:controller
    /:prefix/:plugin/:controller/:action
    

See the section on [Plugin Configuration](https://book.cakephp.org/3.x/plugins.html#plugin-configuration)
 for information on how to load plugin specific route files.

For plugins you did not create with bake, you will also need to edit the **composer.json** file to add your plugin to the autoload classes, this can be done as per the documentation [Autoloading Plugin Classes](https://book.cakephp.org/3.x/plugins.html#autoloading-plugin-classes)
.

Plugin Models [​](https://book.cakephp.org/3.x/plugins.html#plugin-models)

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

Models for the plugin are stored in **plugins/ContactManager/src/Model**. We've already defined a ContactsController for this plugin, so let's create the table and entity for that controller:

    // plugins/ContactManager/src/Model/Entity/Contact.php:
    namespace ContactManager\Model\Entity;
    
    use Cake\ORM\Entity;
    
    class Contact extends Entity
    {
    }
    
    // plugins/ContactManager/src/Model/Table/ContactsTable.php:
    namespace ContactManager\Model\Table;
    
    use Cake\ORM\Table;
    
    class ContactsTable extends Table
    {
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

If you need to reference a model within your plugin when building associations or defining entity classes, you need to include the plugin name with the class name, separated with a dot. For example:

    // plugins/ContactManager/src/Model/Table/ContactsTable.php:
    namespace ContactManager\Model\Table;
    
    use Cake\ORM\Table;
    
    class ContactsTable extends Table
    {
        public function initialize(array $config)
        {
            $this->hasMany('ContactManager.AltName');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

If you would prefer that the array keys for the association not have the plugin prefix on them, use the alternative syntax:

    // plugins/ContactManager/src/Model/Table/ContactsTable.php:
    namespace ContactManager\Model\Table;
    
    use Cake\ORM\Table;
    
    class ContactsTable extends Table
    {
        public function initialize(array $config)
        {
            $this->hasMany('AltName', [\
                'className' => 'ContactManager.AltName',\
            ]);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

You can use `TableRegistry` to load your plugin tables using the familiar `plugin syntax`:

    use Cake\ORM\TableRegistry;
    
    // Prior to 3.6 use TableRegistry::get('ContactManager.Contacts')
    $contacts = TableRegistry::getTableLocator()->get('ContactManager.Contacts');

1  
2  
3  
4  

Alternatively, from a controller context, you can use:

    $this->loadModel('ContactsManager.Contacts');

1  

Plugin Templates [​](https://book.cakephp.org/3.x/plugins.html#plugin-templates)

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

Views behave exactly as they do in normal applications. Just place them in the right folder inside of the `plugins/[PluginName]/src/Template/` folder. For our ContactManager plugin, we'll need a view for our `ContactsController::index()` action, so let's include that as well:

    // plugins/ContactManager/src/Template/Contacts/index.ctp:
    <h1>Contacts</h1>
    <p>Following is a sortable list of your contacts</p>
    <!-- A sortable list of contacts would go here....-->

1  
2  
3  
4  

Plugins can provide their own layouts. To add plugin layouts, place your template files inside `plugins/[PluginName]/src/Template/Layout`. To use a plugin layout in your controller you can do the following:

    public $layout = 'ContactManager.admin';

1  

If the plugin prefix is omitted, the layout/view file will be located normally.

NOTE

For information on how to use elements from a plugin, look up [View Elements](https://book.cakephp.org/3.x/views.html#view-elements)

### Overriding Plugin Templates from Inside Your Application [​](https://book.cakephp.org/3.x/plugins.html#overriding-plugin-templates-from-inside-your-application)

You can override any plugin views from inside your app using special paths. If you have a plugin called 'ContactManager' you can override the template files of the plugin with application specific view logic by creating files using the following template **src/Template/Plugin/\[Plugin\]/\[Controller\]/\[view\].ctp**. For the Contacts controller you could make the following file:

    src/Template/Plugin/ContactManager/Contacts/index.ctp
    

Creating this file would allow you to override **plugins/ContactManager/src/Template/Contacts/index.ctp**.

If your plugin is in a composer dependency (i.e. 'Company/ContactManager'), the path to the 'index' view of the Contacts controller will be:

    src/Template/Plugin/Company/ContactManager/Contacts/index.ctp
    

Creating this file would allow you to override **vendor/Company/ContactManager/src/Template/Contacts/index.ctp**.

If the plugin implements a routing prefix, you must include the routing prefix in your application template overrides. For example, if the 'ContactManager' plugin implemented an 'admin' prefix the overridng path would be:

    src/Template/Plugin/Company/ContactManager/Admin/Contact/index.ctp
    

Plugin Assets [​](https://book.cakephp.org/3.x/plugins.html#plugin-assets)

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

A plugin's web assets (but not PHP files) can be served through the plugin's `webroot` directory, just like the main application's assets:

    /plugins/ContactManager/webroot/
                                   css/
                                   js/
                                   img/
                                   flash/
                                   pdf/
    

You may put any type of file in any directory, just like a regular webroot.

WARNING

Handling static assets (such as images, JavaScript and CSS files) through the Dispatcher is very inefficient. See [Symlink Assets](https://book.cakephp.org/3.x/deployment.html#symlink-assets)
 for more information.

### Linking to Assets in Plugins [​](https://book.cakephp.org/3.x/plugins.html#linking-to-assets-in-plugins)

You can use the `plugin syntax` when linking to plugin assets using the `Cake\View\Helper\HtmlHelper`'s script, image, or css methods:

    // Generates a URL of /contact_manager/css/styles.css
    echo $this->Html->css('ContactManager.styles');
    
    // Generates a URL of /contact_manager/js/widget.js
    echo $this->Html->script('ContactManager.widget');
    
    // Generates a URL of /contact_manager/img/logo.jpg
    echo $this->Html->image('ContactManager.logo');

1  
2  
3  
4  
5  
6  
7  
8  

Plugin assets are served using the `AssetMiddleware` middleware by default. This is only recommended for development. In production you should [symlink plugin assets](https://book.cakephp.org/3.x/deployment.html#symlink-assets)
 to improve performance.

If you are not using the helpers, you can prepend /plugin\_name/ to the beginning of the URL for an asset within that plugin to serve it. Linking to '/contact\_manager/js/some\_file.js' would serve the asset **plugins/ContactManager/webroot/js/some\_file.js**.

Components, Helpers and Behaviors [​](https://book.cakephp.org/3.x/plugins.html#components-helpers-and-behaviors)

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

A plugin can have Components, Helpers and Behaviors just like a CakePHP application. You can even create plugins that consist only of Components, Helpers or Behaviors which can be a great way to build reusable components that can be dropped into any project.

Building these components is exactly the same as building it within a regular application, with no special naming convention.

Referring to your component from inside or outside of your plugin requires only that you prefix the plugin name before the name of the component. For example:

    // Component defined in 'ContactManager' plugin
    namespace ContactManager\Controller\Component;
    
    use Cake\Controller\Component;
    
    class ExampleComponent extends Component
    {
    }
    
    // Within your controllers
    public function initialize()
    {
        parent::initialize();
        $this->loadComponent('ContactManager.Example');
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

The same technique applies to Helpers and Behaviors.

Commands [​](https://book.cakephp.org/3.x/plugins.html#commands)

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

Plugins can register their commands inside the `console()` hook. By default all shells and commands in the plugin are auto-discovered and added to the application's command list. Plugin commands are prefixed with the plugin name. For example, the `UserCommand` provided by the `ContactManager` plugin would be registered as both `contact_manager.user` and `user`. The un-prefixed name will only be taken by a plugin if it is not used by the application, or another plugin.

You can customize the command names by defining each command in your plugin:

    public function console($commands)
    {
        // Create nested commands
        $commands->add('bake model', ModelCommand::class);
        $commands->add('bake controller', ControllerCommand::class);
    
        return $commands;
    }

1  
2  
3  
4  
5  
6  
7  
8  

Testing your Plugin [​](https://book.cakephp.org/3.x/plugins.html#testing-your-plugin)

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

If you are testing controllers or generating URLs, make sure your plugin connects routes `tests/bootstrap.php`.

For more information see [testing plugins](https://book.cakephp.org/3.x/development/testing.html)
 page.

Publishing your Plugin [​](https://book.cakephp.org/3.x/plugins.html#publishing-your-plugin)

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

CakePHP plugins should be published to [the packagist](https://packagist.org/)
. This way other people can use it as composer dependency. You can also propose your plugin to the [awesome-cakephp list](https://github.com/FriendsOfCake/awesome-cakephp)
.

Choose a semantically meaningful name for the package name. This should ideally be prefixed with the dependency, in this case "cakephp" as the framework. The vendor name will usually be your GitHub username. Do **not** use the CakePHP namespace (cakephp) as this is reserved to CakePHP owned plugins. The convention is to use lowercase letters and dashes as separator.

So if you created a plugin "Logging" with your GitHub account "FooBar", a good name would be foo-bar/cakephp-logging. And the CakePHP owned "Localized" plugin can be found under cakephp/localized respectively.

vendor/cakephp-plugins.php

Plugin Map File [​](https://book.cakephp.org/3.x/plugins.html#plugin-map-file)

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

When installing plugins via Composer, you may notice that **vendor/cakephp-plugins.php** is created. This configuration file contains a map of plugin names and their paths on the filesystem. It makes it possible for plugins to be installed into the standard vendor directory which is outside of the normal search paths. The `Plugin` class will use this file to locate plugins when they are loaded with `load()` or `loadAll()`. You generally won't need to edit this file by hand, as Composer and the `plugin-installer` package will manage it for you.

Manage Your Plugins using Mixer [​](https://book.cakephp.org/3.x/plugins.html#manage-your-plugins-using-mixer)

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

Another way to discover and manage plugins into your CakePHP application is [Mixer](https://github.com/CakeDC/mixer)
. It is a CakePHP plugin which helps you to install plugins from Packagist. It also helps you to manage your existing plugins.

NOTE

IMPORTANT: Do not use this in production environment.

---

# Number | CakePHP

[Skip to content](https://book.cakephp.org/3.x/views/helpers/number.html#VPContent)

Return to top

Number [​](https://book.cakephp.org/3.x/views/helpers/number.html#number)

==========================================================================

`class` Cake\\View\\Helper\\**NumberHelper**(View $view, array $config = \[\])

The NumberHelper contains convenient methods that enable display numbers in common formats in your views. These methods include ways to format currency, percentages, data sizes, format numbers to specific precisions and also to give you more flexibility with formatting numbers.

All of these functions return the formatted number; they do not automatically echo the output into the view.

Formatting Currency Values [​](https://book.cakephp.org/3.x/views/helpers/number.html#formatting-currency-values)

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

`method` Cake\\I18n\\Number::**currency**(mixed $value, string $currency = null, array $options = \[\])

This method is used to display a number in common currency formats (EUR, GBP, USD). Usage in a view looks like:

    // Called as NumberHelper
    echo $this->Number->currency($value, $currency);
    
    // Called as Number
    echo Number::currency($value, $currency);

1  
2  
3  
4  
5  

The first parameter, `$value`, should be a floating point number that represents the amount of money you are expressing. The second parameter is a string used to choose a predefined currency formatting scheme:

| $currency | 1234.56, formatted by currency type |
| --- | --- |
| EUR | €1.234,56 |
| GBP | £1,234.56 |
| USD | $1,234.56 |

The third parameter is an array of options for further defining the output. The following options are available:

| Option | Description |
| --- | --- |
| before | Text to display before the rendered number. |
| after | Text to display after the rendered number. |
| zero | The text to use for zero values; can be a string or a number. ie. 0, 'Free!'. |
| places | Number of decimal places to use, ie. 2 |
| precision | Maximal number of decimal places to use, ie. 2 |
| locale | The locale name to use for formatting number, ie. "fr\_FR". |
| fractionSymbol | String to use for fraction numbers, ie. ' cents'. |
| fractionPosition | Either 'before' or 'after' to place the fraction symbol. |
| pattern | An ICU number pattern to use for formatting the number ie. #,###.00 |
| useIntlCode | Set to `true` to replace the currency symbol with the international currency code. |

If `$currency` value is `null`, the default currency will be retrieved from `Cake\I18n\Number::defaultCurrency()`. To format currencies in an accounting format you should set the currency format:

    Number::setDefaultCurrencyFormat(Number::FORMAT_CURRENCY_ACCOUNTING);

1  

Added in version 3.9.0

Formatting currency as accounting values was added.

Setting the Default Currency [​](https://book.cakephp.org/3.x/views/helpers/number.html#setting-the-default-currency)

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

`method` Cake\\I18n\\Number::**defaultCurrency**($currency)

Setter/getter for the default currency. This removes the need to always pass the currency to `Cake\I18n\Number::currency()` and change all currency outputs by setting other default. If `$currency` is set to `false`, it will clear the currently stored value. By default, it will retrieve the `intl.default_locale` if set and 'en\_US' if not.

Formatting Floating Point Numbers [​](https://book.cakephp.org/3.x/views/helpers/number.html#formatting-floating-point-numbers)

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

`method` Cake\\I18n\\Number::**precision**(float $value, int $precision = 3, array $options = \[\])

This method displays a number with the specified amount of precision (decimal places). It will round in order to maintain the level of precision defined. :

    // Called as NumberHelper
    echo $this->Number->precision(456.91873645, 2);
    
    // Outputs
    456.92
    
    // Called as Number
    echo Number::precision(456.91873645, 2);

1  
2  
3  
4  
5  
6  
7  
8  

Formatting Percentages [​](https://book.cakephp.org/3.x/views/helpers/number.html#formatting-percentages)

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

`method` Cake\\I18n\\Number::**toPercentage**(mixed $value, int $precision = 2, array $options = \[\])

| Option | Description |
| --- | --- |
| multiply | Boolean to indicate whether the value has to be multiplied by 100. Useful for decimal percentages. |

Like `Cake\I18n\Number::precision()`, this method formats a number according to the supplied precision (where numbers are rounded to meet the given precision). This method also expresses the number as a percentage and appends the output with a percent sign. :

    // Called as NumberHelper. Output: 45.69%
    echo $this->Number->toPercentage(45.691873645);
    
    // Called as Number. Output: 45.69%
    echo Number::toPercentage(45.691873645);
    
    // Called with multiply. Output: 45.7%
    echo Number::toPercentage(0.45691, 1, [\
        'multiply' => true\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

Interacting with Human Readable Values [​](https://book.cakephp.org/3.x/views/helpers/number.html#interacting-with-human-readable-values)

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

`method` Cake\\I18n\\Number::**toReadableSize**(string $size)

This method formats data sizes in human readable forms. It provides a shortcut way to convert bytes to KB, MB, GB, and TB. The size is displayed with a two-digit precision level, according to the size of data supplied (i.e. higher sizes are expressed in larger terms):

    // Called as NumberHelper
    echo $this->Number->toReadableSize(0); // 0 Byte
    echo $this->Number->toReadableSize(1024); // 1 KB
    echo $this->Number->toReadableSize(1321205.76); // 1.26 MB
    echo $this->Number->toReadableSize(5368709120); // 5 GB
    
    // Called as Number
    echo Number::toReadableSize(0); // 0 Byte
    echo Number::toReadableSize(1024); // 1 KB
    echo Number::toReadableSize(1321205.76); // 1.26 MB
    echo Number::toReadableSize(5368709120); // 5 GB

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

Formatting Numbers [​](https://book.cakephp.org/3.x/views/helpers/number.html#formatting-numbers)

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

`method` Cake\\I18n\\Number::**format**(mixed $value, array $options = \[\])

This method gives you much more control over the formatting of numbers for use in your views (and is used as the main method by most of the other NumberHelper methods). Using this method might looks like:

    // Called as NumberHelper
    $this->Number->format($value, $options);
    
    // Called as Number
    Number::format($value, $options);

1  
2  
3  
4  
5  

The `$value` parameter is the number that you are planning on formatting for output. With no `$options` supplied, the number 1236.334 would output as 1,236. Note that the default precision is zero decimal places.

The `$options` parameter is where the real magic for this method resides.

*   If you pass an integer then this becomes the amount of precision or places for the function.
*   If you pass an associated array, you can use the following keys:

| Option | Description |
| --- | --- |
| places | Number of decimal places to use, ie. 2 |
| precision | Maximum number of decimal places to use, ie. 2 |
| pattern | An ICU number pattern to use for formatting the number ie. #,###.00 |
| locale | The locale name to use for formatting number, ie. "fr\_FR". |
| before | Text to display before the rendered number. |
| after | Text to display after the rendered number. |

Example:

    // Called as NumberHelper
    echo $this->Number->format('123456.7890', [\
        'places' => 2,\
        'before' => '¥ ',\
        'after' => ' !'\
    ]);
    // Output '¥ 123,456.79 !'
    
    echo $this->Number->format('123456.7890', [\
        'locale' => 'fr_FR'\
    ]);
    // Output '123 456,79 !'
    
    // Called as Number
    echo Number::format('123456.7890', [\
        'places' => 2,\
        'before' => '¥ ',\
        'after' => ' !'\
    ]);
    // Output '¥ 123,456.79 !'
    
    echo Number::format('123456.7890', [\
        'locale' => 'fr_FR'\
    ]);
    // Output '123 456,79 !'

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  

`method` Cake\\I18n\\Number::**ordinal**(mixed $value, array $options = \[\])

This method will output an ordinal number.

Examples:

    echo Number::ordinal(1);
    // Output '1st'
    
    echo Number::ordinal(2);
    // Output '2nd'
    
    echo Number::ordinal(2, [\
        'locale' => 'fr_FR'\
    ]);
    // Output '2e'
    
    echo Number::ordinal(410);
    // Output '410th'

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

Format Differences [​](https://book.cakephp.org/3.x/views/helpers/number.html#format-differences)

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

`method` Cake\\I18n\\Number::**formatDelta**(mixed $value, array $options = \[\])

This method displays differences in value as a signed number:

    // Called as NumberHelper
    $this->Number->formatDelta($value, $options);
    
    // Called as Number
    Number::formatDelta($value, $options);

1  
2  
3  
4  
5  

The `$value` parameter is the number that you are planning on formatting for output. With no `$options` supplied, the number 1236.334 would output as 1,236. Note that the default precision is zero decimal places.

The `$options` parameter takes the same keys as `Number::format()` itself:

| Option | Description |
| --- | --- |
| places | Number of decimal places to use, ie. 2 |
| precision | Maximum number of decimal places to use, ie. 2 |
| locale | The locale name to use for formatting number, ie. "fr\_FR". |
| before | Text to display before the rendered number. |
| after | Text to display after the rendered number. |

Example:

    // Called as NumberHelper
    echo $this->Number->formatDelta('123456.7890', [\
        'places' => 2,\
        'before' => '[',\
        'after' => ']'\
    ]);
    // Output '[+123,456.79]'
    
    // Called as Number
    echo Number::formatDelta('123456.7890', [\
        'places' => 2,\
        'before' => '[',\
        'after' => ']'\
    ]);
    // Output '[+123,456.79]'

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

WARNING

All symbols are UTF-8.

---

# Text | CakePHP

[Skip to content](https://book.cakephp.org/3.x/views/helpers/text.html#VPContent)

Return to top

Text [​](https://book.cakephp.org/3.x/views/helpers/text.html#text)

====================================================================

`class` Cake\\View\\Helper\\**TextHelper**(View $view, array $config = \[\])

The TextHelper contains methods to make text more usable and friendly in your views. It aids in enabling links, formatting URLs, creating excerpts of text around chosen words or phrases, highlighting key words in blocks of text, and gracefully truncating long stretches of text.

Linking Email addresses [​](https://book.cakephp.org/3.x/views/helpers/text.html#linking-email-addresses)

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

`method` Cake\\View\\Helper\\TextHelper::**autoLinkEmails**(string $text, array $options = \[\])

Adds links to the well-formed email addresses in $text, according to any options defined in `$options` (see `HtmlHelper::link()`). :

    $myText = 'For more information regarding our world-famous ' .
        'pastries and desserts, contact [email protected]';
    $linkedText = $this->Text->autoLinkEmails($myText);

1  
2  
3  

Output:

    For more information regarding our world-famous pastries and desserts,
    contact <a href="mailto:[email protected]">[email protected]</a>

1  
2  

This method automatically escapes its input. Use the `escape` option to disable this if necessary.

Linking URLs [​](https://book.cakephp.org/3.x/views/helpers/text.html#linking-urls)

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

`method` Cake\\View\\Helper\\TextHelper::**autoLinkUrls**(string $text, array $options = \[\])

Same as `autoLinkEmails()`, only this method searches for strings that start with https, http, ftp, or nntp and links them appropriately.

This method automatically escapes its input. Use the `escape` option to disable this if necessary.

Linking Both URLs and Email Addresses [​](https://book.cakephp.org/3.x/views/helpers/text.html#linking-both-urls-and-email-addresses)

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

`method` Cake\\View\\Helper\\TextHelper::**autoLink**(string $text, array $options = \[\])

Performs the functionality in both `autoLinkUrls()` and `autoLinkEmails()` on the supplied `$text`. All URLs and emails are linked appropriately given the supplied `$options`.

This method automatically escapes its input. Use the `escape` option to disable this if necessary.

Converting Text into Paragraphs [​](https://book.cakephp.org/3.x/views/helpers/text.html#converting-text-into-paragraphs)

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

`method` Cake\\View\\Helper\\TextHelper::**autoParagraph**(string $text)

Adds proper <p> around text where double-line returns are found, and <br> where single-line returns are found. :

    $myText = 'For more information
    regarding our world-famous pastries and desserts.
    
    contact [email protected]';
    $formattedText = $this->Text->autoParagraph($myText);

1  
2  
3  
4  
5  

Output:

    <p>For more information<br />
    regarding our world-famous pastries and desserts.</p>
    <p>contact [email protected]</p>

1  
2  
3  

Highlighting Substrings [​](https://book.cakephp.org/3.x/views/helpers/text.html#highlighting-substrings)

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

`method` Cake\\Utility\\Text::**highlight**(string $haystack, string $needle, array $options = \[\] )

Highlights `$needle` in `$haystack` using the `$options['format']` string specified or a default string.

Options:

*   `format` string - The piece of HTML with the phrase that will be highlighted
*   `html` bool - If `true`, will ignore any HTML tags, ensuring that only the correct text is highlighted

Example:

    // Called as TextHelper
    echo $this->Text->highlight(
        $lastSentence,
        'using',
        ['format' => '<span class="highlight">\1</span>']
    );
    
    // Called as Text
    use Cake\Utility\Text;
    
    echo Text::highlight(
        $lastSentence,
        'using',
        ['format' => '<span class="highlight">\1</span>']
    );

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

Output:

    Highlights $needle in $haystack <span class="highlight">using</span> the
    $options['format'] string specified  or a default string.
    

Removing Links [​](https://book.cakephp.org/3.x/views/helpers/text.html#removing-links)

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

`method` Cake\\Utility\\Text::**stripLinks**($text)

Strips the supplied `$text` of any HTML links.

Truncating Text [​](https://book.cakephp.org/3.x/views/helpers/text.html#truncating-text)

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

`method` Cake\\Utility\\Text::**truncate**(string $text, int $length = 100, array $options)

If `$text` is longer than `$length`, this method truncates it at `$length` and adds a suffix consisting of `'ellipsis'`, if defined. If `'exact'` is passed as `false`, the truncation will occur at the first whitespace after the point at which `$length` is exceeded. If `'html'` is passed as `true`, HTML tags will be respected and will not be cut off.

`$options` is used to pass all extra parameters, and has the following possible keys by default, all of which are optional:

    [\
        'ellipsis' => '...',\
        'exact' => true,\
        'html' => false\
    ]

1  
2  
3  
4  
5  

Example:

    // Called as TextHelper
    echo $this->Text->truncate(
        'The killer crept forward and tripped on the rug.',
        22,
        [\
            'ellipsis' => '...',\
            'exact' => false\
        ]
    );
    
    // Called as Text
    use Cake\Utility\Text;
    
    echo Text::truncate(
        'The killer crept forward and tripped on the rug.',
        22,
        [\
            'ellipsis' => '...',\
            'exact' => false\
        ]
    );

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  

Output:

    The killer crept...
    

Truncating the Tail of a String [​](https://book.cakephp.org/3.x/views/helpers/text.html#truncating-the-tail-of-a-string)

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

`method` Cake\\Utility\\Text::**tail**(string $text, int $length = 100, array $options)

If `$text` is longer than `$length`, this method removes an initial substring with length consisting of the difference and prepends a prefix consisting of `'ellipsis'`, if defined. If `'exact'` is passed as `false`, the truncation will occur at the first whitespace prior to the point at which truncation would otherwise take place.

`$options` is used to pass all extra parameters, and has the following possible keys by default, all of which are optional:

    [\
        'ellipsis' => '...',\
        'exact' => true\
    ]

1  
2  
3  
4  

Example:

    $sampleText = 'I packed my bag and in it I put a PSP, a PS3, a TV, ' .
        'a C# program that can divide by zero, death metal t-shirts'
    
    // Called as TextHelper
    echo $this->Text->tail(
        $sampleText,
        70,
        [\
            'ellipsis' => '...',\
            'exact' => false\
        ]
    );
    
    // Called as Text
    use Cake\Utility\Text;
    
    echo Text::tail(
        $sampleText,
        70,
        [\
            'ellipsis' => '...',\
            'exact' => false\
        ]
    );

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  

Output:

    ...a TV, a C# program that can divide by zero, death metal t-shirts
    

Extracting an Excerpt [​](https://book.cakephp.org/3.x/views/helpers/text.html#extracting-an-excerpt)

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

`method` Cake\\Utility\\Text::**excerpt**(string $haystack, string $needle, integer $radius=100, string $ellipsis="...")

Extracts an excerpt from `$haystack` surrounding the `$needle` with a number of characters on each side determined by `$radius`, and prefix/suffix with `$ellipsis`. This method is especially handy for search results. The query string or keywords can be shown within the resulting document. :

    // Called as TextHelper
    echo $this->Text->excerpt($lastParagraph, 'method', 50, '...');
    
    // Called as Text
    use Cake\Utility\Text;
    
    echo Text::excerpt($lastParagraph, 'method', 50, '...');

1  
2  
3  
4  
5  
6  
7  

Output:

    ... by $radius, and prefix/suffix with $ellipsis. This method is especially
    handy for search results. The query...
    

Converting an Array to Sentence Form [​](https://book.cakephp.org/3.x/views/helpers/text.html#converting-an-array-to-sentence-form)

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

`method` Cake\\Utility\\Text::**toList**(array $list, $and='and', $separator=', ')

Creates a comma-separated list where the last two items are joined with 'and':

    $colors = ['red', 'orange', 'yellow', 'green', 'blue', 'indigo', 'violet'];
    
    // Called as TextHelper
    echo $this->Text->toList($colors);
    
    // Called as Text
    use Cake\Utility\Text;
    
    echo Text::toList($colors);

1  
2  
3  
4  
5  
6  
7  
8  
9  

Output:

    red, orange, yellow, green, blue, indigo and violet

---

# CMS Tutorial - Creating the Articles Controller | CakePHP

[Skip to content](https://book.cakephp.org/3.x/tutorials-and-examples/cms/articles-controller.html#VPContent)

Return to top

CMS Tutorial - Creating the Articles Controller [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/articles-controller.html#cms-tutorial-creating-the-articles-controller)

====================================================================================================================================================================================

With our model created, we need a controller for our articles. Controllers in CakePHP handle HTTP requests and execute business logic contained in model methods, to prepare the response. We'll place this new controller in a file called **ArticlesController.php** inside the **src/Controller** directory. Here's what the basic controller should look like:

    <?php
    // src/Controller/ArticlesController.php
    
    namespace App\Controller;
    
    class ArticlesController extends AppController
    {
    }

1  
2  
3  
4  
5  
6  
7  
8  

Now, let's add an action to our controller. Actions are controller methods that have routes connected to them. For example, when a user requests **www.example.com/articles/index** (which is also the same as **www.example.com/articles**), CakePHP will call the `index` method of your `ArticlesController`. This method should query the model layer, and prepare a response by rendering a Template in the View. The code for that action would look like this:

    <?php
    // src/Controller/ArticlesController.php
    
    namespace App\Controller;
    
    class ArticlesController extends AppController
    {
        public function index()
        {
            $this->loadComponent('Paginator');
            $articles = $this->Paginator->paginate($this->Articles->find());
            $this->set(compact('articles'));
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

By defining function `index()` in our `ArticlesController`, users can now access the logic there by requesting **www.example.com/articles/index**. Similarly, if we were to define a function called `foobar()`, users would be able to access that at **www.example.com/articles/foobar**. You may be tempted to name your controllers and actions in a way that allows you to obtain specific URLs. Resist that temptation. Instead, follow the [CakePHP Conventions](https://book.cakephp.org/3.x/intro/conventions.html)
 creating readable, meaningful action names. You can then use [Routing](https://book.cakephp.org/3.x/development/routing.html)
 to connect the URLs you want to the actions you've created.

Our controller action is very simple. It fetches a paginated set of articles from the database, using the Articles Model that is automatically loaded via naming conventions. It then uses `set()` to pass the articles into the Template (which we'll create soon). CakePHP will automatically render the template after our controller action completes.

Create the Article List Template [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/articles-controller.html#create-the-article-list-template)

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

Now that we have our controller pulling data from the model, and preparing our view context, let's create a view template for our index action.

CakePHP view templates are presentation-flavored PHP code that is inserted inside the application's layout. While we'll be creating HTML here, Views can also generate JSON, CSV or even binary files like PDFs.

A layout is presentation code that is wrapped around a view. Layout files contain common site elements like headers, footers and navigation elements. Your application can have multiple layouts, and you can switch between them, but for now, let's just use the default layout.

CakePHP's template files are stored in **src/Template** inside a folder named after the controller they correspond to. So we'll have to create a folder named 'Articles' in this case. Add the following code to your application:

    <!-- File: src/Template/Articles/index.ctp -->
    
    <h1>Articles</h1>
    <table>
        <tr>
            <th>Title</th>
            <th>Created</th>
        </tr>
    
        <!-- Here is where we iterate through our $articles query object, printing out article info -->
    
        <?php foreach ($articles as $article): ?>
        <tr>
            <td>
                <?= $this->Html->link($article->title, ['action' => 'view', $article->slug]) ?>
            </td>
            <td>
                <?= $article->created->format(DATE_RFC850) ?>
            </td>
        </tr>
        <?php endforeach; ?>
    </table>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  

In the last section we assigned the 'articles' variable to the view using `set()`. Variables passed into the view are available in the view templates as local variables which we used in the above code.

You might have noticed the use of an object called `$this->Html`. This is an instance of the CakePHP [HtmlHelper](https://book.cakephp.org/3.x/views/helpers/html.html)
. CakePHP comes with a set of view helpers that make tasks like creating links, forms, and pagination buttons easy. You can learn more about [Helpers](https://book.cakephp.org/3.x/views/helpers.html)
 in their chapter, but what's important to note here is that the `link()` method will generate an HTML link with the given link text (the first parameter) and URL (the second parameter).

When specifying URLs in CakePHP, it is recommended that you use arrays or [named routes](https://book.cakephp.org/3.x/development/routing.html#named-routes)
. These syntaxes allow you to leverage the reverse routing features CakePHP offers.

At this point, you should be able to point your browser to **[http://localhost:8765/articles/index](http://localhost:8765/articles/index)
**. You should see your list view, correctly formatted with the title and table listing of the articles.

Create the View Action [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/articles-controller.html#create-the-view-action)

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

If you were to click one of the 'view' links in our Articles list page, you'd see an error page saying that action hasn't been implemented. Lets fix that now:

    // Add to existing src/Controller/ArticlesController.php file
    
    public function view($slug = null)
    {
        $article = $this->Articles->findBySlug($slug)->firstOrFail();
        $this->set(compact('article'));
    }

1  
2  
3  
4  
5  
6  
7  

While this is a simple action, we've used some powerful CakePHP features. We start our action off by using `findBySlug()` which is a [Dynamic Finder](https://book.cakephp.org/3.x/orm/retrieving-data-and-resultsets.html#dynamic-finders)
. This method allows us to create a basic query that finds articles by a given slug. We then use `firstOrFail()` to either fetch the first record, or throw a `NotFoundException`.

Our action takes a `$slug` parameter, but where does that parameter come from? If a user requests `/articles/view/first-post`, then the value 'first-post' is passed as `$slug` by CakePHP's routing and dispatching layers. If we reload our browser with our new action saved, we'd see another CakePHP error page telling us we're missing a view template; let's fix that.

Create the View Template [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/articles-controller.html#create-the-view-template)

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

Let's create the view for our new 'view' action and place it in **src/Template/Articles/view.ctp**

    <!-- File: src/Template/Articles/view.ctp -->
    
    <h1><?= h($article->title) ?></h1>
    <p><?= h($article->body) ?></p>
    <p><small>Created: <?= $article->created->format(DATE_RFC850) ?></small></p>
    <p><?= $this->Html->link('Edit', ['action' => 'edit', $article->slug]) ?></p>

1  
2  
3  
4  
5  
6  

You can verify that this is working by trying the links at `/articles/index` or manually requesting an article by accessing URLs like `/articles/view/first-post`.

Adding Articles [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/articles-controller.html#adding-articles)

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

With the basic read views created, we need to make it possible for new articles to be created. Start by creating an `add()` action in the `ArticlesController`. Our controller should now look like:

    // src/Controller/ArticlesController.php
    
    namespace App\Controller;
    
    use App\Controller\AppController;
    
    class ArticlesController extends AppController
    {
        public function initialize()
        {
            parent::initialize();
    
            $this->loadComponent('Paginator');
            $this->loadComponent('Flash'); // Include the FlashComponent
        }
    
        public function index()
        {
            $articles = $this->Paginator->paginate($this->Articles->find());
            $this->set(compact('articles'));
        }
    
        public function view($slug)
        {
            $article = $this->Articles->findBySlug($slug)->firstOrFail();
            $this->set(compact('article'));
        }
    
        public function add()
        {
            $article = $this->Articles->newEntity();
            if ($this->request->is('post')) {
                $article = $this->Articles->patchEntity($article, $this->request->getData());
    
                // Hardcoding the user_id is temporary, and will be removed later
                // when we build authentication out.
                $article->user_id = 1;
    
                if ($this->Articles->save($article)) {
                    $this->Flash->success(__('Your article has been saved.'));
                    return $this->redirect(['action' => 'index']);
                }
                $this->Flash->error(__('Unable to add your article.'));
            }
            $this->set('article', $article);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40  
41  
42  
43  
44  
45  
46  
47  

NOTE

You need to include the [Flash](https://book.cakephp.org/3.x/controllers/components/flash.html)
 component in any controller where you will use it. Often it makes sense to include it in your `AppController`.

Here's what the `add()` action does:

*   If the HTTP method of the request was POST, try to save the data using the Articles model.
*   If for some reason it doesn't save, just render the view. This gives us a chance to show the user validation errors or other warnings.

Every CakePHP request includes a request object which is accessible using `$this->request`. The request object contains information regarding the request that was just received. We use the `Cake\Http\ServerRequest::is()` method to check that the request is a HTTP POST request.

Our POST data is available in `$this->request->getData()`. You can use the `pr()` or `debug()` functions to print it out if you want to see what it looks like. To save our data, we first 'marshal' the POST data into an Article Entity. The Entity is then persisted using the ArticlesTable we created earlier.

After saving our new article we use FlashComponent's `success()` method to set a message into the session. The `success` method is provided using PHP's [magic method features](https://php.net/manual/en/language.oop5.overloading.php#object.call)
. Flash messages will be displayed on the next page after redirecting. In our layout we have `<?= $this->Flash->render() ?>` which displays flash messages and clears the corresponding session variable. Finally, after saving is complete, we use `Cake\Controller\Controller::redirect` to send the user back to the articles list. The param `['action' => 'index']` translates to URL `/articles` i.e the index action of the `ArticlesController`. You can refer to `Cake\Routing\Router::url()` function on the [API](https://api.cakephp.org/)
 to see the formats in which you can specify a URL for various CakePHP functions.

Create Add Template [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/articles-controller.html#create-add-template)

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

Here's our add view template:

    <!-- File: src/Template/Articles/add.ctp -->
    
    <h1>Add Article</h1>
    <?php
        echo $this->Form->create($article);
        // Hard code the user for now.
        echo $this->Form->control('user_id', ['type' => 'hidden', 'value' => 1]);
        echo $this->Form->control('title');
        echo $this->Form->control('body', ['rows' => '3']);
        echo $this->Form->button(__('Save Article'));
        echo $this->Form->end();
    ?>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

We use the FormHelper to generate the opening tag for an HTML form. Here's the HTML that `$this->Form->create()` generates:

    <form method="post" action="/articles/add">

1  

Because we called `create()` without a URL option, `FormHelper` assumes we want the form to submit back to the current action.

The `$this->Form->control()` method is used to create form elements of the same name. The first parameter tells CakePHP which field they correspond to, and the second parameter allows you to specify a wide array of options - in this case, the number of rows for the textarea. There's a bit of introspection and conventions used here. The `control()` will output different form elements based on the model field specified, and use inflection to generate the label text. You can customize the label, the input or any other aspect of the form controls using options. The `$this->Form->end()` call closes the form.

Now let's go back and update our **src/Template/Articles/index.ctp** view to include a new "Add Article" link. Before the `<table>`, add the following line:

    <?= $this->Html->link('Add Article', ['action' => 'add']) ?>

1  

Adding Simple Slug Generation [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/articles-controller.html#adding-simple-slug-generation)

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

If we were to save an Article right now, saving would fail as we are not creating a slug attribute, and the column is `NOT NULL`. Slug values are typically a URL-safe version of an article's title. We can use the [beforeSave() callback](https://book.cakephp.org/3.x/orm/table-objects.html#table-callbacks)
 of the ORM to populate our slug:

    // in src/Model/Table/ArticlesTable.php
    namespace App\Model\Table;
    
    use Cake\ORM\Table;
    // the Text class
    use Cake\Utility\Text;
    
    // Add the following method.
    
    public function beforeSave($event, $entity, $options)
    {
        if ($entity->isNew() && !$entity->slug) {
            $sluggedTitle = Text::slug($entity->title);
            // trim slug to maximum length defined in schema
            $entity->slug = substr($sluggedTitle, 0, 191);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

This code is simple, and doesn't take into account duplicate slugs. But we'll fix that later on.

Add Edit Action [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/articles-controller.html#add-edit-action)

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

Our application can now save articles, but we can't edit them. Lets rectify that now. Add the following action to your `ArticlesController`:

    // in src/Controller/ArticlesController.php
    
    // Add the following method.
    
    public function edit($slug)
    {
        $article = $this->Articles->findBySlug($slug)->firstOrFail();
        if ($this->request->is(['post', 'put'])) {
            $this->Articles->patchEntity($article, $this->request->getData());
            if ($this->Articles->save($article)) {
                $this->Flash->success(__('Your article has been updated.'));
                return $this->redirect(['action' => 'index']);
            }
            $this->Flash->error(__('Unable to update your article.'));
        }
    
        $this->set('article', $article);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

This action first ensures that the user has tried to access an existing record. If they haven't passed in an `$slug` parameter, or the article does not exist, a `NotFoundException` will be thrown, and the CakePHP ErrorHandler will render the appropriate error page.

Next the action checks whether the request is either a POST or a PUT request. If it is, then we use the POST/PUT data to update our article entity by using the `patchEntity()` method. Finally, we call `save()` set the appropriate flash message and either redirect or display validation errors.

Create Edit Template [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/articles-controller.html#create-edit-template)

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

The edit template should look like this:

    <!-- File: src/Template/Articles/edit.ctp -->
    
    <h1>Edit Article</h1>
    <?php
        echo $this->Form->create($article);
        echo $this->Form->control('user_id', ['type' => 'hidden']);
        echo $this->Form->control('title');
        echo $this->Form->control('body', ['rows' => '3']);
        echo $this->Form->button(__('Save Article'));
        echo $this->Form->end();
    ?>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

This template outputs the edit form (with the values populated), along with any necessary validation error messages.

You can now update your index view with links to edit specific articles:

    <!-- File: src/Template/Articles/index.ctp  (edit links added) -->
    
    <h1>Articles</h1>
    <p><?= $this->Html->link("Add Article", ['action' => 'add']) ?></p>
    <table>
        <tr>
            <th>Title</th>
            <th>Created</th>
            <th>Action</th>
        </tr>
    
    <!-- Here's where we iterate through our $articles query object, printing out article info -->
    
    <?php foreach ($articles as $article): ?>
        <tr>
            <td>
                <?= $this->Html->link($article->title, ['action' => 'view', $article->slug]) ?>
            </td>
            <td>
                <?= $article->created->format(DATE_RFC850) ?>
            </td>
            <td>
                <?= $this->Html->link('Edit', ['action' => 'edit', $article->slug]) ?>
            </td>
        </tr>
    <?php endforeach; ?>
    
    </table>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  

Update Validation Rules for Articles [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/articles-controller.html#update-validation-rules-for-articles)

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

Up until this point our Articles had no input validation done. Lets fix that by using [a validator](https://book.cakephp.org/3.x/orm/validation.html#validating-request-data)
:

    // src/Model/Table/ArticlesTable.php
    
    // add this use statement right below the namespace declaration to import
    // the Validator class
    use Cake\Validation\Validator;
    
    // Add the following method.
    public function validationDefault(Validator $validator)
    {
        $validator
            ->allowEmptyString('title', 'Title cannot be empty', false)
            ->minLength('title', 10)
            ->maxLength('title', 255);
    
        $validator
            ->allowEmptyString('body', 'Body cannot be empty', false)
            ->minLength('body', 10);
    
        return $validator;
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  

The `validationDefault()` method tells CakePHP how to validate your data when the `save()` method is called. Here, we've specified that both the title, and body fields must not be empty, and have certain length constraints.

CakePHP's validation engine is powerful and flexible. It provides a suite of frequently used rules for tasks like email addresses, IP addresses etc. and the flexibility for adding your own validation rules. For more information on that setup, check the [Validation](https://book.cakephp.org/3.x/core-libraries/validation.html)
 documentation.

Now that your validation rules are in place, use the app to try to add an article with an empty title or body to see how it works. Since we've used the `Cake\View\Helper\FormHelper::control()` method of the FormHelper to create our form elements, our validation error messages will be shown automatically.

Add Delete Action [​](https://book.cakephp.org/3.x/tutorials-and-examples/cms/articles-controller.html#add-delete-action)

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

Next, let's make a way for users to delete articles. Start with a `delete()` action in the `ArticlesController`:

    // src/Controller/ArticlesController.php
    
    public function delete($slug)
    {
        $this->request->allowMethod(['post', 'delete']);
    
        $article = $this->Articles->findBySlug($slug)->firstOrFail();
        if ($this->Articles->delete($article)) {
            $this->Flash->success(__('The {0} article has been deleted.', $article->title));
            return $this->redirect(['action' => 'index']);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

This logic deletes the article specified by `$slug`, and uses `$this->Flash->success()` to show the user a confirmation message after redirecting them to `/articles`. If the user attempts to delete an article using a GET request, `allowMethod()` will throw an exception. Uncaught exceptions are captured by CakePHP's exception handler, and a nice error page is displayed. There are many built-in [Exceptions](https://book.cakephp.org/3.x/development/errors.html)
 that can be used to indicate the various HTTP errors your application might need to generate.

WARNING

Allowing content to be deleted using GET requests is _very_ dangerous, as web crawlers could accidentally delete all your content. That is why we used `allowMethod()` in our controller.

Because we're only executing logic and redirecting to another action, this action has no template. You might want to update your index template with links that allow users to delete articles:

    <!-- File: src/Template/Articles/index.ctp  (delete links added) -->
    
    <h1>Articles</h1>
    <p><?= $this->Html->link("Add Article", ['action' => 'add']) ?></p>
    <table>
        <tr>
            <th>Title</th>
            <th>Created</th>
            <th>Action</th>
        </tr>
    
    <!-- Here's where we iterate through our $articles query object, printing out article info -->
    
    <?php foreach ($articles as $article): ?>
        <tr>
            <td>
                <?= $this->Html->link($article->title, ['action' => 'view', $article->slug]) ?>
            </td>
            <td>
                <?= $article->created->format(DATE_RFC850) ?>
            </td>
            <td>
                <?= $this->Html->link('Edit', ['action' => 'edit', $article->slug]) ?>
                <?= $this->Form->postLink(
                    'Delete',
                    ['action' => 'delete', $article->slug],
                    ['confirm' => 'Are you sure?'])
                ?>
            </td>
        </tr>
    <?php endforeach; ?>
    
    </table>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  

Using `Cake\View\Helper\FormHelper::postLink()` will create a link that uses JavaScript to do a POST request deleting our article.

NOTE

This view code also uses the `FormHelper` to prompt the user with a JavaScript confirmation dialog before they attempt to delete an article.

With a basic articles management setup, we'll create the [basic actions for our Tags and Users tables](https://book.cakephp.org/3.x/tutorials-and-examples/cms/tags-and-users.html)
.

---

# Breadcrumbs | CakePHP

[Skip to content](https://book.cakephp.org/3.x/views/helpers/breadcrumbs.html#VPContent)

Return to top

`class` Cake\\View\\Helper\\**BreadcrumbsHelper**(View $view, array $config = \[\])

Added in version 3.3.6

BreadcrumbsHelper provides a way to easily deal with the creation and rendering of a breadcrumbs trail for your app.

Creating a Breadcrumbs Trail [​](https://book.cakephp.org/3.x/views/helpers/breadcrumbs.html#creating-a-breadcrumbs-trail)

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

You can add a crumb to the list using the `add()` method. It takes three arguments:

*   **title** The string to be displayed as a the title of the crumb
*   **url** A string or an array of parameters that will be given to the [Url](https://book.cakephp.org/3.x/views/helpers/url.html)
    
*   **options** An array of attributes for the `item` and `itemWithoutLink` templates. See the section about [defining attributes for the item](https://book.cakephp.org/3.x/views/helpers/breadcrumbs.html#defining-attributes-item)
     for more information.

In addition to adding to the end of the trail, you can do a variety of operations:

    // Add at the end of the trail
    $this->Breadcrumbs->add(
        'Products',
        ['controller' => 'products', 'action' => 'index']
    );
    
    // Add multiple crumbs at the end of the trail
    $this->Breadcrumbs->add([\
        ['title' => 'Products', 'url' => ['controller' => 'products', 'action' => 'index']],\
        ['title' => 'Product name', 'url' => ['controller' => 'products', 'action' => 'view', 1234]]\
    ]);
    
    // Prepended crumbs will be put at the top of the list
    $this->Breadcrumbs->prepend(
        'Products',
        ['controller' => 'products', 'action' => 'index']
    );
    
    // Prepend multiple crumbs at the top of the trail, in the order given
    $this->Breadcrumbs->prepend([\
        ['title' => 'Products', 'url' => ['controller' => 'products', 'action' => 'index']],\
        ['title' => 'Product name', 'url' => ['controller' => 'products', 'action' => 'view', 1234]]\
    ]);
    
    // Insert in a specific slot. If the slot is out of
    // bounds, an exception will be raised.
    $this->Breadcrumbs->insertAt(
        2,
        'Products',
        ['controller' => 'products', 'action' => 'index']
    );
    
    // Insert before another crumb, based on the title.
    // If the named crumb title cannot be found,
    // an exception will be raised.
    $this->Breadcrumbs->insertBefore(
        'A product name', // the title of the crumb to insert before
        'Products',
        ['controller' => 'products', 'action' => 'index']
    );
    
    // Insert after another crumb, based on the title.
    // If the named crumb title cannot be found,
    // an exception will be raised.
    $this->Breadcrumbs->insertAfter(
        'A product name', // the title of the crumb to insert after
        'Products',
        ['controller' => 'products', 'action' => 'index']
    );

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40  
41  
42  
43  
44  
45  
46  
47  
48  
49  

Using these methods gives you the ability to work with CakePHP's 2-step rendering process. Since templates and layouts are rendered from the inside out (meaning, included elements are rendered first), this allows you to define precisely where you want to add a breadcrumb.

Rendering the Breadcrumbs Trail [​](https://book.cakephp.org/3.x/views/helpers/breadcrumbs.html#rendering-the-breadcrumbs-trail)

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

After adding crumbs to the trail, you can easily render it using the `render()` method. This method accepts two array arguments:

*   `$attributes` : An array of attributes that will applied to the `wrapper` template. This gives you the ability to add attributes to the HTML tag. It accepts the special `templateVars` key to allow the insertion of custom template variables in the template.
    
*   `$separator` : An array of attributes for the `separator` template. Possible properties are:
    
    *   `separator` The string to be displayed as a separator
    *   `innerAttrs` To provide attributes in case your separator is divided in two elements
    *   `templateVars` Allows the insertion of custom template variable in the template
    
    All other properties will be converted as HTML attributes and will replace the `attrs` key in the template. If you use the default for this option (empty), it will not render a separator.
    

Here is an example of how to render a trail:

    echo $this->Breadcrumbs->render(
        ['class' => 'breadcrumbs-trail'],
        ['separator' => '<i class="fa fa-angle-right"></i>']
    );

1  
2  
3  
4  

### Customizing the Output [​](https://book.cakephp.org/3.x/views/helpers/breadcrumbs.html#customizing-the-output)

The BreadcrumbsHelper internally uses the `StringTemplateTrait`, which gives the ability to easily customize output of various HTML strings. It includes four templates, with the following default declaration:

    [\
        'wrapper' => '<ul{{attrs}}>{{content}}</ul>',\
        'item' => '<li{{attrs}}><a href="{{url}}"{{innerAttrs}}>{{title}}</a></li>{{separator}}',\
        'itemWithoutLink' => '<li{{attrs}}><span{{innerAttrs}}>{{title}}</span></li>{{separator}}',\
        'separator' => '<li{{attrs}}><span{{innerAttrs}}>{{separator}}</span></li>'\
    ]

1  
2  
3  
4  
5  
6  

You can easily customize them using the `templates()` method from the `StringTemplateTrait`:

    $this->Breadcrumbs->templates([\
        'wrapper' => '<nav class="breadcrumbs"><ul{{attrs}}>{{content}}</ul></nav>',\
    ]);

1  
2  
3  

Since your templates will be rendered, the `templateVars` option allows you to add your own template variables in the various templates:

    $this->Breadcrumbs->templates([\
        'item' => '<li{{attrs}}>{{icon}}<a href="{{url}}"{{innerAttrs}}>{{title}}</a></li>{{separator}}'\
    ]);

1  
2  
3  

And to define the parameter, just specify it when adding the crumb to the trail:

    $this->Breadcrumbs->add(
        'Products',
        ['controller' => 'products', 'action' => 'index'],
        [\
            'templateVars' => [\
                'icon' => '<i class="fa fa-money"></i>'\
            ]\
        ]
    );

1  
2  
3  
4  
5  
6  
7  
8  
9  

### Defining Attributes for the Item [​](https://book.cakephp.org/3.x/views/helpers/breadcrumbs.html#defining-attributes-for-the-item)

If you want to apply specific HTML attributes to both the item and its sub-item , you can leverage the `innerAttrs` key, which the `$options` argument provides. Everything except `innerAttrs` and `templateVars` will be rendered as HTML attributes:

    $this->Breadcrumbs->add(
        'Products',
        ['controller' => 'products', 'action' => 'index'],
        [\
            'class' => 'products-crumb',\
            'data-foo' => 'bar',\
            'innerAttrs' => [\
                'class' => 'inner-products-crumb',\
                'id' => 'the-products-crumb'\
            ]\
        ]
    );
    
    // Based on the default template, this will render the following HTML :
    <li class="products-crumb" data-foo="bar">
        <a href="/products/index" class="inner-products-crumb" id="the-products-crumb">Products</a>
    </li>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

Clearing the Breadcrumbs [​](https://book.cakephp.org/3.x/views/helpers/breadcrumbs.html#clearing-the-breadcrumbs)

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

You can clear the bread crumbs using the `reset()` method. This can be useful when you want to transform the crumbs and overwrite the list:

    $crumbs = $this->Breadcrumbs->getCrumbs();
    $crumbs = collection($crumbs)->map(function ($crumb) {
        $crumb['options']['class'] = 'breadcrumb-item';
        return $crumb;
    })->toArray();
    
    $this->Breadcrumbs->reset()->add($crumbs);

1  
2  
3  
4  
5  
6  
7  

Added in version 3.4.0

The `reset()` method was added in 3.4.0

---

# Blog Tutorial | CakePHP

[Skip to content](https://book.cakephp.org/3.x/tutorials-and-examples/blog/blog.html#VPContent)

Return to top

Blog Tutorial [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/blog.html#blog-tutorial)

====================================================================================================

This tutorial will walk you through the creation of a simple blog application. We'll be installing CakePHP, creating a database, and creating enough application logic to list, add, edit, and delete blog articles.

Here's what you'll need:

1.  A running web server. We're going to assume you're using Apache, though the instructions for using other servers should be very similar. We might have to play a little with the server configuration, but most folks can get CakePHP up and running without any configuration at all. Make sure you have PHP _5.6_ or greater, and that the `mbstring` and `intl` extensions are enabled in PHP. 2. A database server. We're going to be using MySQL server in this tutorial. You'll need to know enough about SQL in order to create a database: CakePHP will be taking the reins from there. Since we're using MySQL, also make sure that you have `pdo_mysql` enabled in PHP. 3. Basic PHP knowledge.

Let's get started!

Getting CakePHP [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/blog.html#getting-cakephp)

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

The easiest way to install CakePHP is to use Composer. Composer is a simple way of installing CakePHP from your terminal or command line prompt. First, you'll need to download and install Composer if you haven't done so already. If you have cURL installed, it's as easy as running the following:

    curl -s https://getcomposer.org/installer | php
    

Or, you can download `composer.phar` from the [Composer website](https://getcomposer.org/download/)
.

Then simply type the following line in your terminal from your installation directory to install the CakePHP application skeleton in the directory that you wish to use it with. For this example we will be using "blog" but feel free to change it to something else.:

    php composer.phar create-project --prefer-dist cakephp/app:"^3.10" blog
    

In case you've already got composer installed globally, you may instead type:

    composer self-update && composer create-project --prefer-dist cakephp/app:"^3.10" blog
    

The advantage to using Composer is that it will automatically complete some important set up tasks, such as setting the correct file permissions and creating your config/app.php file for you.

There are other ways to install CakePHP. If you cannot or don't want to use Composer, check out the [Installation](https://book.cakephp.org/3.x/installation.html)
 section.

Regardless of how you downloaded and installed CakePHP, once your set up is completed, your directory setup should look something like the following:

    /cake_install
        /bin
        /config
        /logs
        /plugins
        /src
        /tests
        /tmp
        /vendor
        /webroot
        .editorconfig
        .gitignore
        .htaccess
        .travis.yml
        composer.json
        index.php
        phpunit.xml.dist
        README.md
    

Now might be a good time to learn a bit about how CakePHP's directory structure works: check out the [CakePHP Folder Structure](https://book.cakephp.org/3.x/intro/cakephp-folder-structure.html)
 section.

Directory Permissions on tmp and logs [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/blog.html#directory-permissions-on-tmp-and-logs)

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

The `tmp` and `logs` directories need to have proper permissions to be writable by your webserver. If you used Composer for the install, this should have been done for you and confirmed with a "Permissions set on <folder>" message. If you instead got an error message or want to do it manually, the best way would be to find out what user your webserver runs as (``<?= `whoami`; ?>``) and change the ownership of these two directories to that user. The final command you run (in \*nix) might look something like this:

    chown -R www-data tmp
    chown -R www-data logs
    

If for some reason CakePHP can't write to these directories, you'll be informed by a warning while not in production mode.

While not recommended, if you are unable to set the permissions to the same as your webserver, you can simply set write permissions on the folder by running a command such as:

    chmod -R 777 tmp
    chmod -R 777 logs
    

Creating the Blog Database [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/blog.html#creating-the-blog-database)

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

Next, let's set up the underlying MySQL database for our blog. If you haven't already done so, create an empty database for use in this tutorial, with a name of your choice, e.g. `cake_blog`. Right now, we'll just create a single table to store our articles. We'll also throw in a few articles to use for testing purposes. Execute the following SQL statements into your database:

    # First, create our articles table
    CREATE TABLE articles (
        id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
        title VARCHAR(50),
        body TEXT,
        created DATETIME DEFAULT NULL,
        modified DATETIME DEFAULT NULL
    );
    
    # Then insert some articles for testing:
    INSERT INTO articles (title,body,created)
        VALUES ('The title', 'This is the article body.', NOW());
    INSERT INTO articles (title,body,created)
        VALUES ('A title once again', 'And the article body follows.', NOW());
    INSERT INTO articles (title,body,created)
        VALUES ('Title strikes back', 'This is really exciting! Not.', NOW());

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  

The choices on table and column names are not arbitrary. If you follow CakePHP's database naming conventions, and CakePHP's class naming conventions (both outlined in [CakePHP Conventions](https://book.cakephp.org/3.x/intro/conventions.html)
), you'll be able to take advantage of a lot of free functionality and avoid configuration. CakePHP is flexible enough to accommodate even inconsistent legacy database schemas, but adhering to the conventions will save you time.

Check out [CakePHP Conventions](https://book.cakephp.org/3.x/intro/conventions.html)
 for more information, but it's suffice to say that naming our table 'articles' automatically hooks it to our Articles model, and having fields called 'modified' and 'created' will be automatically managed by CakePHP.

Database Configuration [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/blog.html#database-configuration)

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

Next, let's tell CakePHP where our database is and how to connect to it. For many, this will be the first and last time you will need to configure anything.

The configuration should be pretty straightforward: just replace the values in the `Datasources.default` array in the **config/app.php** file with those that apply to your setup. A sample completed configuration array might look something like the following:

    return [\
        // More configuration above.\
        'Datasources' => [\
            'default' => [\
                'className' => 'Cake\Database\Connection',\
                'driver' => 'Cake\Database\Driver\Mysql',\
                'persistent' => false,\
                'host' => 'localhost',\
                'username' => 'cake_blog',\
                'password' => 'AngelF00dC4k3~',\
                'database' => 'cake_blog',\
                'encoding' => 'utf8',\
                'timezone' => 'UTC'\
            ],\
        ],\
        // More configuration below.\
    ];

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

Once you've saved your **config/app.php** file, you should be able to open your browser and see the CakePHP welcome page. It should also tell you that your database connection file was found, and that CakePHP can successfully connect to the database.

NOTE

A copy of CakePHP's default configuration file is found in **config/app.default.php**.

Optional Configuration [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/blog.html#optional-configuration)

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

There are a few other items that can be configured. Most developers complete these laundry-list items, but they're not required for this tutorial. One is defining a custom string (or "salt") for use in security hashes.

The security salt is used for generating hashes. If you used Composer this too is taken care of for you during the install. Else you'd need to change the default salt value by editing **config/app.php**. It doesn't matter much what the new value is, as long as it's not guessable:

    'Security' => [\
        'salt' => 'something long and containing lots of different values.',\
    ],

1  
2  
3  

A Note on mod\_rewrite [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/blog.html#a-note-on-mod-rewrite)

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

Occasionally new users will run into mod\_rewrite issues. For example if the CakePHP welcome page looks a little funny (no images or CSS styles). This probably means mod\_rewrite is not functioning on your system. Please refer to the [Url Rewriting](https://book.cakephp.org/3.x/installation.html#url-rewriting)
 section to help resolve any issues you are having.

Now continue to [Blog Tutorial - Part 2](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-two.html)
 to start building your first CakePHP application.

---

# Paginator | CakePHP

[Skip to content](https://book.cakephp.org/3.x/views/helpers/paginator.html#VPContent)

Return to top

Paginator [​](https://book.cakephp.org/3.x/views/helpers/paginator.html#paginator)

===================================================================================

`class` Cake\\View\\Helper\\**PaginatorHelper**(View $view, array $config = \[\])

The PaginatorHelper is used to output pagination controls such as page numbers and next/previous links. It works in tandem with `PaginatorComponent`.

See also [Pagination](https://book.cakephp.org/3.x/controllers/components/pagination.html)
 for information on how to create paginated datasets and do paginated queries.

PaginatorHelper Templates [​](https://book.cakephp.org/3.x/views/helpers/paginator.html#paginatorhelper-templates)

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

Internally PaginatorHelper uses a series of simple HTML templates to generate markup. You can modify these templates to customize the HTML generated by the PaginatorHelper.

Templates use style placeholders. It is important to not add any spaces around the or the replacements will not work.

### Loading Templates from a File [​](https://book.cakephp.org/3.x/views/helpers/paginator.html#loading-templates-from-a-file)

When adding the PaginatorHelper in your controller, you can define the 'templates' setting to define a template file to load. This allows you to customize multiple templates and keep your code DRY:

    // In your AppView.php
    public function initialize()
    {
        ...
        $this->loadHelper('Paginator', ['templates' => 'paginator-templates']);
    }

1  
2  
3  
4  
5  
6  

This will load the file located at **config/paginator-templates.php**. See the example below for how the file should look like. You can also load templates from a plugin using `plugin syntax`:

    // In your AppView.php
    public function initialize()
    {
        ...
        $this->loadHelper('Paginator', ['templates' => 'MyPlugin.paginator-templates']);
    }

1  
2  
3  
4  
5  
6  

Whether your templates are in the primary application or a plugin, your templates file should look something like:

    return [\
        'number' => '<a href="{{url}}">{{text}}</a>',\
    ];

1  
2  
3  

### Changing Templates at Run-time [​](https://book.cakephp.org/3.x/views/helpers/paginator.html#changing-templates-at-run-time)

`method` Cake\\View\\Helper\\PaginatorHelper::**setTemplates**($templates)

This method allows you to change the templates used by PaginatorHelper at runtime. This can be useful when you want to customize templates for a particular method call:

    // Read the current template value.
    $result = $this->Paginator->getTemplates('number');
    // Prior to 3.4
    $result = $this->Paginator->templates('number');
    
    // Change a template
    $this->Paginator->setTemplates([\
        'number' => '<em><a href="{{url}}">{{text}}</a></em>'\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  

WARNING

Template strings containing a percentage sign (`%`) need special attention, you should prefix this character with another percentage so it looks like `%%`. The reason is that internally templates are compiled to be used with `sprintf()`. Example: '<div style="width:%%"></div>'

### Template Names [​](https://book.cakephp.org/3.x/views/helpers/paginator.html#template-names)

PaginatorHelper uses the following templates:

*   `nextActive` The active state for a link generated by next().
*   `nextDisabled` The disabled state for next().
*   `prevActive` The active state for a link generated by prev().
*   `prevDisabled` The disabled state for prev()
*   `counterRange` The template counter() uses when format == range.
*   `counterPages` The template counter() uses when format == pages.
*   `first` The template used for a link generated by first().
*   `last` The template used for a link generated by last()
*   `number` The template used for a link generated by numbers().
*   `current` The template used for the current page.
*   `ellipsis` The template used for ellipses generated by numbers().
*   `sort` The template for a sort link with no direction.
*   `sortAsc` The template for a sort link with an ascending direction.
*   `sortDesc` The template for a sort link with a descending direction.

Creating Sort Links [​](https://book.cakephp.org/3.x/views/helpers/paginator.html#creating-sort-links)

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

`method` Cake\\View\\Helper\\PaginatorHelper::**sort**($key, $title = null, $options = \[\])

Generates a sorting link. Sets querystring parameters for the sort and direction. Links will default to sorting by asc. After the first click, links generated with `sort()` will handle direction switching automatically. If the resultset is sorted 'asc' by the specified key the returned link will sort by 'desc'.

Accepted keys for `$options`:

*   `escape` Whether you want the contents HTML entity encoded, defaults to `true`.
*   `model` The model to use, defaults to `PaginatorHelper::defaultModel()`.
*   `direction` The default direction to use when this link isn't active.
*   `lock` Lock direction. Will only use the default direction then, defaults to `false`.

Assuming you are paginating some posts, and are on page one:

    echo $this->Paginator->sort('user_id');

1  

Output:

    <a href="/posts/index?page=1&amp;sort=user_id&amp;direction=asc">User Id</a>

1  

You can use the title parameter to create custom text for your link:

    echo $this->Paginator->sort('user_id', 'User account');

1  

Output:

    <a href="/posts/index?page=1&amp;sort=user_id&amp;direction=asc">User account</a>

1  

If you are using HTML like images in your links remember to set escaping off:

    echo $this->Paginator->sort(
      'user_id',
      '<em>User account</em>',
      ['escape' => false]
    );

1  
2  
3  
4  
5  

Output:

    <a href="/posts/index?page=1&amp;sort=user_id&amp;direction=asc"><em>User account</em></a>

1  

The direction option can be used to set the default direction for a link. Once a link is active, it will automatically switch directions like normal:

    echo $this->Paginator->sort('user_id', null, ['direction' => 'desc']);

1  

Output:

    <a href="/posts/index?page=1&amp;sort=user_id&amp;direction=desc">User Id</a>

1  

The lock option can be used to lock sorting into the specified direction:

    echo $this->Paginator->sort('user_id', null, ['direction' => 'asc', 'lock' => true]);

1  

`method` Cake\\View\\Helper\\PaginatorHelper::**sortDir**(string $model = null, mixed $options = \[\])

`method` Cake\\View\\Helper\\PaginatorHelper::**sortKey**(string $model = null, mixed $options = \[\])

Creating Page Number Links [​](https://book.cakephp.org/3.x/views/helpers/paginator.html#creating-page-number-links)

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

`method` Cake\\View\\Helper\\PaginatorHelper::**numbers**($options = \[\])

Returns a set of numbers for the paged result set. Uses a modulus to decide how many numbers to show on each side of the current page By default 8 links on either side of the current page will be created if those pages exist. Links will not be generated for pages that do not exist. The current page is also not a link.

Supported options are:

*   `before` Content to be inserted before the numbers.
    
*   `after` Content to be inserted after the numbers.
    
*   `model` Model to create numbers for, defaults to `PaginatorHelper::defaultModel()`.
    
*   `modulus` how many numbers to include on either side of the current page, defaults to 8.
    
*   `first` Whether you want first links generated, set to an integer to define the number of 'first' links to generate. Defaults to `false`. If a string is set a link to the first page will be generated with the value as the title:
    
        echo $this->Paginator->numbers(['first' => 'First page']);
    
    1  
    
*   `last` Whether you want last links generated, set to an integer to define the number of 'last' links to generate. Defaults to `false`. Follows the same logic as the `first` option. There is a `~PaginatorHelper::last()` method to be used separately as well if you wish.
    

While this method allows a lot of customization for its output. It is also ok to just call the method without any parameters. :

    echo $this->Paginator->numbers();

1  

Using the first and last options you can create links to the beginning and end of the page set. The following would create a set of page links that include links to the first 2 and last 2 pages in the paged results:

    echo $this->Paginator->numbers(['first' => 2, 'last' => 2]);

1  

Creating Jump Links [​](https://book.cakephp.org/3.x/views/helpers/paginator.html#creating-jump-links)

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

In addition to generating links that go directly to specific page numbers, you'll often want links that go to the previous and next links, first and last pages in the paged data set.

`method` Cake\\View\\Helper\\PaginatorHelper::**prev**($title = '<< Previous', $options = \[\])

`method` Cake\\View\\Helper\\PaginatorHelper::**next**($title = 'Next >>', $options = \[\])

`method` Cake\\View\\Helper\\PaginatorHelper::**first**($first = '<< first', $options = \[\])

`method` Cake\\View\\Helper\\PaginatorHelper::**last**($last = 'last >>', $options = \[\])

Creating Header Link Tags [​](https://book.cakephp.org/3.x/views/helpers/paginator.html#creating-header-link-tags)

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

PaginatorHelper can be used to create pagination link tags in your page `<head>` elements:

    // Create next/prev links for the current model.
    echo $this->Paginator->meta();
    
    // Create next/prev & first/last links for the current model.
    echo $this->Paginator->meta(['first' => true, 'last' => true]);

1  
2  
3  
4  
5  

Added in version 3.4.0

The `first` and `last` options were added in 3.4.0

Checking the Pagination State [​](https://book.cakephp.org/3.x/views/helpers/paginator.html#checking-the-pagination-state)

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

`method` Cake\\View\\Helper\\PaginatorHelper::**current**(string $model = null)

`method` Cake\\View\\Helper\\PaginatorHelper::**hasNext**(string $model = null)

`method` Cake\\View\\Helper\\PaginatorHelper::**hasPrev**(string $model = null)

`method` Cake\\View\\Helper\\PaginatorHelper::**hasPage**(string $model = null, integer $page = 1)

`method` Cake\\View\\Helper\\PaginatorHelper::**total**(string $model = null)

Creating a Page Counter [​](https://book.cakephp.org/3.x/views/helpers/paginator.html#creating-a-page-counter)

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

`method` Cake\\View\\Helper\\PaginatorHelper::**counter**($options = \[\])

Returns a counter string for the paged result set. Using a provided format string and a number of options you can create localized and application specific indicators of where a user is in the paged data set.

There are a number of options for `counter()`. The supported ones are:

*   `format` Format of the counter. Supported formats are 'range', 'pages' and custom. Defaults to pages which would output like '1 of 10'. In the custom mode the supplied string is parsed and tokens are replaced with actual values. The available tokens are:
    
    *   \- the current page displayed.
    *   \- total number of pages.
    *   \- current number of records being shown.
    *   \- the total number of records in the result set.
    *   \- number of the first record being displayed.
    *   \- number of the last record being displayed.
    *   \- The pluralized human form of the model name. If your model was 'RecipePage', would be 'recipe pages'.
    
    You could also supply only a string to the counter method using the tokens available. For example:
    
        echo $this->Paginator->counter(
            'Page {{page}} of {{pages}}, showing {{current}} records out of
             {{count}} total, starting on record {{start}}, ending on {{end}}'
        );
    
    1  
    2  
    3  
    4  
    
    Setting 'format' to range would output like '1 - 3 of 13':
    
        echo $this->Paginator->counter([\
            'format' => 'range'\
        ]);
    
    1  
    2  
    3  
    
*   `model` The name of the model being paginated, defaults to `PaginatorHelper::defaultModel()`. This is used in conjunction with the custom string on 'format' option.
    

Generating Pagination URLs [​](https://book.cakephp.org/3.x/views/helpers/paginator.html#generating-pagination-urls)

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

`method` Cake\\View\\Helper\\PaginatorHelper::**generateUrl**(array $options = \[\], $model = null, $full = false)

By default returns a full pagination URL string for use in non-standard contexts (i.e. JavaScript). :

    echo $this->Paginator->generateUrl(['sort' => 'title']);

1  

Creating a Limit Selectbox Control [​](https://book.cakephp.org/3.x/views/helpers/paginator.html#creating-a-limit-selectbox-control)

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

`method` Cake\\View\\Helper\\PaginatorHelper::**limitControl**(array $limits = \[\], $default = null, array $options = \[\])

Create a dropdown control that changes the `limit` query parameter:

    // Use the defaults.
    echo $this->Paginator->limitControl();
    
    // Define which limit options you want.
    echo $this->Paginator->limitControl([25 => 25, 50 => 50]);
    
    // Custom limits and set the selected option
    echo $this->Paginator->limitControl([25 => 25, 50 => 50], $user->perPage);

1  
2  
3  
4  
5  
6  
7  
8  

The generated form and control will automatically submit on change.

Added in version 3.5.0

The `limitControl()` method was added in 3.5.0

Configuring Pagination Options [​](https://book.cakephp.org/3.x/views/helpers/paginator.html#configuring-pagination-options)

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

`method` Cake\\View\\Helper\\PaginatorHelper::**options**($options = \[\])

Sets all the options for the PaginatorHelper. Supported options are:

*   `url` The URL of the paginating action. 'url' has a few sub options as well:
    
    *   `sort` The key that the records are sorted by.
    *   `direction` The direction of the sorting. Defaults to 'ASC'.
    *   `page` The page number to display.
    
    The above mentioned options can be used to force particular pages/directions. You can also append additional URL content into all URLs generated in the helper:
    
        $this->Paginator->options([\
            'url' => [\
                'sort' => 'email',\
                'direction' => 'desc',\
                'page' => 6,\
                'lang' => 'en'\
            ]\
        ]);
    
    1  
    2  
    3  
    4  
    5  
    6  
    7  
    8  
    
    The above adds the `en` route parameter to all links the helper will generate. It will also create links with specific sort, direction and page values. By default PaginatorHelper will merge in all of the current passed arguments and query string parameters.
    
*   `escape` Defines if the title field for links should be HTML escaped. Defaults to `true`.
    
*   `model` The name of the model being paginated, defaults to `PaginatorHelper::defaultModel()`.
    

Example Usage [​](https://book.cakephp.org/3.x/views/helpers/paginator.html#example-usage)

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

It's up to you to decide how to show records to the user, but most often this will be done inside HTML tables. The examples below assume a tabular layout, but the PaginatorHelper available in views doesn't always need to be restricted as such.

See the details on [PaginatorHelper](https://api.cakephp.org/3.x/class-Cake.View.Helper.PaginatorHelper.html)
 in the API. As mentioned, the PaginatorHelper also offers sorting features which can be integrated into your table column headers:

    <!-- src/Template/Posts/index.ctp -->
    <table>
        <tr>
            <th><?= $this->Paginator->sort('id', 'ID') ?></th>
            <th><?= $this->Paginator->sort('title', 'Title') ?></th>
        </tr>
           <?php foreach ($recipes as $recipe): ?>
        <tr>
            <td><?= $recipe->id ?> </td>
            <td><?= h($recipe->title) ?> </td>
        </tr>
        <?php endforeach; ?>
    </table>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

The links output from the `sort()` method of the `PaginatorHelper` allow users to click on table headers to toggle the sorting of the data by a given field.

It is also possible to sort a column based on associations:

    <table>
        <tr>
            <th><?= $this->Paginator->sort('title', 'Title') ?></th>
            <th><?= $this->Paginator->sort('Authors.name', 'Author') ?></th>
        </tr>
           <?php foreach ($recipes as $recipe): ?>
        <tr>
            <td><?= h($recipe->title) ?> </td>
            <td><?= h($recipe->author->name) ?> </td>
        </tr>
        <?php endforeach; ?>
    </table>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

NOTE

Sorting by columns in associated models requires setting these in the `PaginationComponent::paginate` property. Using the example above, the controller handling the pagination would need to set its `sortWhitelist` key as follows:

    $this->paginate = [\
        'sortWhitelist' => [\
            'Posts.title',\
            'Authors.name',\
        ],\
    ];

1  
2  
3  
4  
5  
6  

For more information on using the `sortWhitelist` option, please see [Control Which Fields Used For Ordering](https://book.cakephp.org/3.x/controllers/components/pagination.html#control-which-fields-used-for-ordering)
.

The final ingredient to pagination display in views is the addition of page navigation, also supplied by the PaginationHelper:

    // Shows the page numbers
    <?= $this->Paginator->numbers() ?>
    
    // Shows the next and previous links
    <?= $this->Paginator->prev('« Previous') ?>
    <?= $this->Paginator->next('Next »') ?>
    
    // Prints X of Y, where X is current page and Y is number of pages
    <?= $this->Paginator->counter() ?>

1  
2  
3  
4  
5  
6  
7  
8  
9  

The wording output by the counter() method can also be customized using special markers:

    <?= $this->Paginator->counter([\
        'format' => 'Page {{page}} of {{pages}}, showing {{current}} records out of\
                 {{count}} total, starting on record {{start}}, ending on {{end}}'\
    ]) ?>

1  
2  
3  
4  

Paginating Multiple Results [​](https://book.cakephp.org/3.x/views/helpers/paginator.html#paginating-multiple-results)

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

If you are [paginating multiple queries](https://book.cakephp.org/3.x/controllers/components/pagination.html#paginating-multiple-queries)
 you'll need to set the `model` option when generating pagination related elements. You can either use the `model` option on every method call you make to `PaginatorHelper`, or use `options()` to set the default model:

    // Pass the model option
    echo $this->Paginator->sort('title', ['model' => 'Articles']);
    
    // Set the default model.
    $this->Paginator->options(['model' => 'Articles']);
    echo $this->Paginator->sort('title');

1  
2  
3  
4  
5  
6  

By using the `model` option, `PaginatorHelper` will automatically use the `scope` defined in when the query was paginated.

Added in version 3.3.0

Multiple Pagination was added in 3.3.0

---

# ヘルパー | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/views/helpers.html#VPContent)

Return to top

ヘルパー [​](https://book.cakephp.org/3.x/ja/views/helpers.html#%E3%83%98%E3%83%AB%E3%83%8F%E3%82%9A%E3%83%BC)

===========================================================================================================

ヘルパーはアプリケーションのプレゼンテーション層のためのコンポーネントのようなクラスです。 多くのビューやエレメント、レイアウトで共有される表示ロジックを含んでいます。 この章では、ヘルパーを設定する方法を紹介します。ヘルパーの読み込み方法、 それらのヘルパーの使い方、独自のヘルパーを作成するための簡単な手順を概説します。

CakePHP にはビューの作成に役立つ多くのヘルパーがあります。それらは、整形式のマークアップ (フォーム含む)、テキスト、時間、数値の整形に役立ったり、 Ajax 機能 をスピードアップさせたりします。 CakePHP のヘルパーに関する詳細については、各ヘルパーの章をご覧ください。

*   [Breadcrumbs (パンくず)](https://book.cakephp.org/3.x/ja/views/helpers/breadcrumbs.html)
    
*   [Flash](https://book.cakephp.org/3.x/ja/views/helpers/flash.html)
    
*   [Form](https://book.cakephp.org/3.x/ja/views/helpers/form.html)
    
*   [Html](https://book.cakephp.org/3.x/ja/views/helpers/html.html)
    
*   [Number](https://book.cakephp.org/3.x/ja/views/helpers/number.html)
    
*   [Paginator](https://book.cakephp.org/3.x/ja/views/helpers/paginator.html)
    
*   [Rss](https://book.cakephp.org/3.x/ja/views/helpers/rss.html)
    
*   [Session](https://book.cakephp.org/3.x/ja/views/helpers/session.html)
    
*   [Text](https://book.cakephp.org/3.x/ja/views/helpers/text.html)
    
*   [Time](https://book.cakephp.org/3.x/ja/views/helpers/time.html)
    
*   [Url](https://book.cakephp.org/3.x/ja/views/helpers/url.html)
    

ヘルパーの設定 [​](https://book.cakephp.org/3.x/ja/views/helpers.html#%E3%83%98%E3%83%AB%E3%83%8F%E3%82%9A%E3%83%BC%E3%81%AE%E8%A8%AD%E5%AE%9A)

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

CakePHP でヘルパーを読み込むには、ビュークラスでヘルパーを宣言します。 `AppView` クラスは、すべての CakePHP アプリケーションが付属し、 ヘルパーを読み込むための理想的な場所です。 :

    class AppView extends View
    {
        public function initialize()
        {
            parent::initialize();
            $this->loadHelper('Html');
            $this->loadHelper('Form');
            $this->loadHelper('Flash');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

プラグインのヘルパーを読み込むには、CakePHP の他の場所でも使われている `プラグイン記法` を使います。 :

    $this->loadHelper('Blog.Comment');

1  

CakePHP やアプリケーションにあるヘルパーを明示的に読み込む必要はありません。 これらのヘルパーは、初回の使用時に遅延ロードされます。 例えば:

    // まだ読み込まれていなければ FormHelper を読み込みます。
    $this->Form->create($article);

1  
2  

プラグインのビュー内から、プラグインヘルパーを遅延ロードすることもできます。 例えば、'Blog' プラグインのビューテンプレートは、同じプラグインからヘルパーを 遅延ロードすることができます。

### 条件付きヘルパーの読み込み [​](https://book.cakephp.org/3.x/ja/views/helpers.html#%E6%9D%A1%E4%BB%B6%E4%BB%98%E3%81%8D%E3%83%98%E3%83%AB%E3%83%8F%E3%82%9A%E3%83%BC%E3%81%AE%E8%AA%AD%E3%81%BF%E8%BE%BC%E3%81%BF)

現在のアクション名を使用して、条件付きでヘルパーを読み込むことができます。 :

    class AppView extends View
    {
        public function initialize()
        {
            parent::initialize();
            if ($this->request->getParam('action') === 'index') {
                $this->loadHelper('ListPage');
            }
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

また、コントローラーの `beforeRender` メソッドを使用して、ヘルパーを読み込むことができます。 :

    class ArticlesController extends AppController
    {
        public function beforeRender(Event $event)
        {
            parent::beforeRender($event);
            $this->viewBuilder()->helpers(['MyHelper']);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  

### 設定オプション [​](https://book.cakephp.org/3.x/ja/views/helpers.html#%E8%A8%AD%E5%AE%9A%E3%82%AA%E3%83%95%E3%82%9A%E3%82%B7%E3%83%A7%E3%83%B3)

ヘルパーに設定オプションを渡すことができます。これらのオプションは、属性値を設定したり、 ヘルパーの振る舞いを変更するために使用することができます。 :

    namespace App\View\Helper;
    
    use Cake\View\Helper;
    use Cake\View\View;
    
    class AwesomeHelper extends Helper
    {
    
        // initialize() フックは 3.2 以降で使用可能です。前のバージョンで
        // 必要な場合は、コンストラクターをオーバーライドしてください。
        public function initialize(array $config)
        {
            debug($config);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

次に示すように、コントローラーのヘルパーを宣言するときにオプションを指定することができます。 :

    namespace App\Controller;
    
    use App\Controller\AppController;
    
    class AwesomeController extends AppController
    {
        public $helpers = ['Awesome' => ['option1' => 'value1']];
    }

1  
2  
3  
4  
5  
6  
7  
8  

デフォルトでは、すべての設定オプションは、 `$_defaultConfig` プロパティーとマージされます。 このプロパティーは、ヘルパーが必要とする設定のデフォルト値を定義する必要があります。例えば:

    namespace App\View\Helper;
    
    use Cake\View\Helper;
    use Cake\View\StringTemplateTrait;
    
    class AwesomeHelper extends Helper
    {
    
        use StringTemplateTrait;
    
        protected $_defaultConfig = [\
            'errorClass' => 'error',\
            'templates' => [\
                'label' => '<label for="{{for}}">{{content}}</label>',\
            ],\
        ];
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

ヘルパーのコンストラクターに提供される任意の設定は、構築時にデフォルト値とマージされ、 マージされたデータは、 `_config` に設定されます。 実行時設定を読み取るために `config()` メソッドを使用することができます。 :

    // errorClass 設定オプションを読み込み
    $class = $this->Awesome->config('errorClass');

1  
2  

ヘルパー設定を使用すると、宣言的にヘルパーを設定し、コントローラーロジックから設定ロジックを 削除することができます。クラス宣言の一部として組み込むことができない設定オプションがある場合は、 コントローラーの beforeRender コールバックで設定します。 :

    class PostsController extends AppController
    {
        public function beforeRender(Event $event)
        {
            parent::beforeRender($event);
            $builder = $this->viewBuilder();
            $builder->helpers([\
                'CustomStuff' => $this->_getCustomStuffConfig(),\
            ]);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

### ヘルパーの別名 [​](https://book.cakephp.org/3.x/ja/views/helpers.html#%E3%83%98%E3%83%AB%E3%83%8F%E3%82%9A%E3%83%BC%E3%81%AE%E5%88%A5%E5%90%8D)

共通設定の一つに `className` オプションがあります。 このオプションを使うとビュー内に別名のヘルパーを作成することができます。 この機能は `$this->Html` や他のヘルパーの参照を独自実装に置き換えたい時に便利です。 :

    // src/View/AppView.php
    class AppView extends View
    {
        public function initialize()
        {
            $this->loadHelper('Html', [\
                'className' => 'MyHtml'\
            ]);
        }
    }
    
    // src/View/Helper/MyHtmlHelper.php
    namespace App\View\Helper;
    
    use Cake\View\Helper\HtmlHelper;
    
    class MyHtmlHelper extends HtmlHelper
    {
        // コア HtmlHelper を上書きするコードを追加
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  

上記の例ではビューにて `MyHtmlHelper` に `$this->Html` という _別名_ をつけています。

NOTE

別名をつけられたヘルパーは、ヘルパーが使われるあらゆる場所のインスタンスを置き換えます。 これは、他のヘルパーの内部を含みます。

ヘルパーの使用 [​](https://book.cakephp.org/3.x/ja/views/helpers.html#%E3%83%98%E3%83%AB%E3%83%8F%E3%82%9A%E3%83%BC%E3%81%AE%E4%BD%BF%E7%94%A8)

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

コントローラーで使用するヘルパーを設定すると、各ヘルパーはビューのパブリックプロパティーとして公開されます。 例えば、 `HtmlHelper` を使用していた場合、次を実行することによってアクセスすることが できます。 :

    echo $this->Html->css('styles');

1  

上記は HtmlHelper の `css()` メソッドを呼び出します。 `$this->{$helperName}` を使用して任意の読み込まれたヘルパーにアクセスすることができます。

### ヘルパーの動的ロード [​](https://book.cakephp.org/3.x/ja/views/helpers.html#%E3%83%98%E3%83%AB%E3%83%8F%E3%82%9A%E3%83%BC%E3%81%AE%E5%8B%95%E7%9A%84%E3%83%AD%E3%83%BC%E3%83%88%E3%82%99)

ビュー内から動的にヘルパーを読み込む必要がある状況があるかもしれません。 これを行うには、 ビューの `Cake\View\HelperRegistry` を使用することができます。 :

    // どちらか１つが動作
    $mediaHelper = $this->loadHelper('Media', $mediaConfig);
    $mediaHelper = $this->helpers()->load('Media', $mediaConfig);

1  
2  
3  

HelperRegistry は [レジストリー](https://book.cakephp.org/3.x/ja/core-libraries/registry-objects.html)
 です。 そして、 CakePHP の他の場所で使用されるレジストリー API をサポートしています。

コールバックメソッド [​](https://book.cakephp.org/3.x/ja/views/helpers.html#%E3%82%B3%E3%83%BC%E3%83%AB%E3%83%8F%E3%82%99%E3%83%83%E3%82%AF%E3%83%A1%E3%82%BD%E3%83%83%E3%83%88%E3%82%99)

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

ヘルパーは、ビューレンダリングプロセスを強化するためのコールバックをいくつか備えています。 詳細は [Helper Api](https://book.cakephp.org/3.x/ja/views/helpers.html#helper-api)
 と [イベントシステム](https://book.cakephp.org/3.x/ja/core-libraries/events.html)
 ドキュメントをご覧ください。

ヘルパーの作成 [​](https://book.cakephp.org/3.x/ja/views/helpers.html#%E3%83%98%E3%83%AB%E3%83%8F%E3%82%9A%E3%83%BC%E3%81%AE%E4%BD%9C%E6%88%90)

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

アプリケーションやプラグインで使用するための独自のヘルパークラスを作成することができます。 CakePHP のコンポーネントと同様に、ヘルパークラスは、いくつかの規約があります。

*   ヘルパークラスファイルは、 **src/View/Helper** に置かれます。 例: **src/View/Helper/LinkHelper.php**
*   ヘルパークラスは、末尾に `Helper` を付ける必要があります。例: `LinkHelper` 。
*   ヘルパークラス名を参照するときは、 末尾の `Helper` を省略しなければなりません。 例: `$this->loadHelper('Link');` 。

また、正しく動作させるために `Helper` を継承します。 :

    /* src/View/Helper/LinkHelper.php */
    namespace App\View\Helper;
    
    use Cake\View\Helper;
    
    class LinkHelper extends Helper
    {
        public function makeEdit($title, $url)
        {
            // 特別な形式のリンクを作成するロジックをここに...
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

### 他のヘルパーの読み込み [​](https://book.cakephp.org/3.x/ja/views/helpers.html#%E4%BB%96%E3%81%AE%E3%83%98%E3%83%AB%E3%83%8F%E3%82%9A%E3%83%BC%E3%81%AE%E8%AA%AD%E3%81%BF%E8%BE%BC%E3%81%BF)

別のヘルパーに既に存在する機能を使用したい場合があります。 その場合、 `$helpers` 配列に使いたいヘルパーを明示することで実現出来ます。 フォーマットは、コントローラーで指定する場合と同じようにして下さい。 :

    /* src/View/Helper/LinkHelper.php (他のヘルパーを使用) */
    
    namespace App\View\Helper;
    
    use Cake\View\Helper;
    
    class LinkHelper extends Helper
    {
        public $helpers = ['Html'];
    
        public function makeEdit($title, $url)
        {
            // 出力に HTML ヘルパーを使用
            // 整形されたデータ:
    
            $link = $this->Html->link($title, $url, ['class' => 'edit']);
    
            return '<div class="editOuter">' . $link . '</div>';
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  

### 独自のヘルパーを使用 [​](https://book.cakephp.org/3.x/ja/views/helpers.html#%E7%8B%AC%E8%87%AA%E3%81%AE%E3%83%98%E3%83%AB%E3%83%8F%E3%82%9A%E3%83%BC%E3%82%92%E4%BD%BF%E7%94%A8)

ヘルパーを作成して **src/View/Helper/** に配置すると、ビューに読み込めます。 :

    class AppView extends View
    {
        public function initialize()
        {
            parent::initialize();
            $this->loadHelper('Link');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  

ヘルパーが読み込まれたら、一致するビュープロパティーにアクセスしてビュー内で使用できます。 :

    <!-- 新しいヘルパーを使用してリンクを作成 -->
    <?= $this->Link->makeEdit('レシピの変更', '/recipes/edit/5') ?>

1  
2  

NOTE

`HelperRegistry` は、 `コントローラー` で明示されていないヘルパーを 遅延ロードしようとします。

### ヘルパー内部でビュー変数にアクセス [​](https://book.cakephp.org/3.x/ja/views/helpers.html#%E3%83%98%E3%83%AB%E3%83%8F%E3%82%9A%E3%83%BC%E5%86%85%E9%83%A8%E3%81%A6%E3%82%99%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC%E5%A4%89%E6%95%B0%E3%81%AB%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9)

ヘルパー内部でビュー変数にアクセスしたい場合は、次のように `$this->_View->get()` を使用することができます。 :

    class AwesomeHelper extends Helper
    {
    
        public $helpers = ['Html'];
    
        public function someMethod()
        {
            // meta description の設定
            echo $this->Html->meta(
                'description', $this->_View->get('metaDescription'), ['block' => 'meta']
            );
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

### ヘルパー内部でビューエレメントの描画 [​](https://book.cakephp.org/3.x/ja/views/helpers.html#%E3%83%98%E3%83%AB%E3%83%8F%E3%82%9A%E3%83%BC%E5%86%85%E9%83%A8%E3%81%A6%E3%82%99%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC%E3%82%A8%E3%83%AC%E3%83%A1%E3%83%B3%E3%83%88%E3%81%AE%E6%8F%8F%E7%94%BB)

ヘルパー内部でエレメントを描画したい場合は、次のように `$this->_View->element()` を使用することができます。 :

    class AwesomeHelper extends Helper
    {
        public function someFunction()
        {
            // ヘルパー内で直接出力
            echo $this->_View->element(
                '/path/to/element',
                ['foo'=>'bar','bar'=>'foo']
            );
    
            // または、ビューに返す
            return $this->_View->element(
                '/path/to/element',
                ['foo'=>'bar','bar'=>'foo']
            );
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

Helper クラス [​](https://book.cakephp.org/3.x/ja/views/helpers.html#helper-%E3%82%AF%E3%83%A9%E3%82%B9)

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

`class` **Helper**

### コールバック [​](https://book.cakephp.org/3.x/ja/views/helpers.html#%E3%82%B3%E3%83%BC%E3%83%AB%E3%83%8F%E3%82%99%E3%83%83%E3%82%AF)

ヘルパーにコールバックメソッドを実装することで、CakePHP は関連するイベントにヘルパーを自動的に 登録します。以前のバージョンの CakePHP とは異なり、ヘルパークラスはコールバックメソッドを 実装していないので、あなたのコールバックでは `parent` を _コールしてはいけません_ 。

`method` Helper::**beforeRenderFile**(Event $event, $viewFile)

`method` Helper::**afterRenderFile**(Event $event, $viewFile, $content)

`method` Helper::**beforeRender**(Event $event, $viewFile)

`method` Helper::**afterRender**(Event $event, $viewFile)

`method` Helper::**beforeLayout**(Event $event, $layoutFile)

`method` Helper::**afterLayout**(Event $event, $layoutFile)

---

# Blog Tutorial - Part 3 | CakePHP

[Skip to content](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-three.html#VPContent)

Return to top

Blog Tutorial - Part 3 [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-three.html#blog-tutorial-part-3)

==========================================================================================================================

Create a Tree Category [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-three.html#create-a-tree-category)

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

Let's continue our blog application and imagine we want to categorize our articles. We want the categories to be ordered, and for this, we will use the [Tree behavior](https://book.cakephp.org/3.x/orm/behaviors/tree.html)
 to help us organize the categories.

But first, we need to modify our tables.

Migrations Plugin [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-three.html#migrations-plugin)

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

We will use the [migrations plugin](https://github.com/cakephp/migrations)
 to create a table in our database. If you already have an articles table in your database, erase it.

Now open your application's **composer.json** file. Normally you would see that the migrations plugin is already under `require`. If not, add it by executing:

    composer require cakephp/migrations:~1.0
    

The migrations plugin will now be in your application's **plugins** folder. Also, add `$this->addPlugin('Migrations');` to your application's `bootstrap` method.

Once the plugin is loaded, run the following command to create a migration file:

    bin/cake bake migration CreateArticles title:string body:text category_id:integer created modified
    

A migration file will be generated in the **/config/Migrations** folder with the following:

    <?php
    
    use Migrations\AbstractMigration;
    
    class CreateArticles extends AbstractMigration
    {
        public function change()
        {
            $table = $this->table('articles');
            $table->addColumn('title', 'string', [\
                'default' => null,\
                'limit' => 255,\
                'null' => false,\
            ]);
            $table->addColumn('body', 'text', [\
                'default' => null,\
                'null' => false,\
            ]);
            $table->addColumn('category_id', 'integer', [\
                'default' => null,\
                'limit' => 11,\
                'null' => false,\
            ]);
            $table->addColumn('created', 'datetime', [\
                'default' => null,\
                'null' => false,\
            ]);
            $table->addColumn('modified', 'datetime', [\
                'default' => null,\
                'null' => false,\
            ]);
            $table->create();
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  

Run another command to create a `categories` table. If you need to specify a field length, you can do it within brackets in the field type, ie:

    bin/cake bake migration CreateCategories parent_id:integer lft:integer[10] rght:integer[10] name:string[100] description:string created modified
    

This will generate the following file in **config/Migrations**:

    <?php
    
    use Migrations\AbstractMigration;
    
    class CreateCategories extends AbstractMigration
    {
        public function change()
        {
            $table = $this->table('categories');
            $table->addColumn('parent_id', 'integer', [\
                'default' => null,\
                'limit' => 11,\
                'null' => false,\
            ]);
            $table->addColumn('lft', 'integer', [\
                'default' => null,\
                'limit' => 10,\
                'null' => false,\
            ]);
            $table->addColumn('rght', 'integer', [\
                'default' => null,\
                'limit' => 10,\
                'null' => false,\
            ]);
            $table->addColumn('name', 'string', [\
                'default' => null,\
                'limit' => 100,\
                'null' => false,\
            ]);
            $table->addColumn('description', 'string', [\
                'default' => null,\
                'limit' => 255,\
                'null' => false,\
            ]);
            $table->addColumn('created', 'datetime', [\
                'default' => null,\
                'null' => false,\
            ]);
            $table->addColumn('modified', 'datetime', [\
                'default' => null,\
                'null' => false,\
            ]);
            $table->create();
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40  
41  
42  
43  
44  
45  

Now that the migration files are created, you can edit them before creating your tables. We need to change the `'null' => false` for the `parent_id` field with `'null' => true` because a top-level category has a null `parent_id`.

Run the following command to create your tables:

    bin/cake migrations migrate
    

Modifying the Tables [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-three.html#modifying-the-tables)

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

With our tables set up, we can now focus on categorizing our articles.

We suppose you already have the files (Tables, Controllers and Templates of Articles) from part 2. So we'll just add the references to categories.

We need to associate the Articles and Categories tables together. Open the **src/Model/Table/ArticlesTable.php** file and add the following:

    // src/Model/Table/ArticlesTable.php
    
    namespace App\Model\Table;
    
    use Cake\ORM\Table;
    
    class ArticlesTable extends Table
    {
        public function initialize(array $config)
        {
            $this->addBehavior('Timestamp');
            // Just add the belongsTo relation with CategoriesTable
            $this->belongsTo('Categories', [\
                'foreignKey' => 'category_id',\
            ]);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

Generate Skeleton Code for Categories [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-three.html#generate-skeleton-code-for-categories)

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

Create all files by launching bake commands:

    bin/cake bake model Categories
    bin/cake bake controller Categories
    bin/cake bake template Categories
    

Alternatively, you can bake all with just one line:

    bin/cake bake all Categories
    

The bake tool has created all your files in a snap. You can give them a quick read if you want re-familiarize yourself with how CakePHP works.

NOTE

If you are on Windows remember to use \\ instead of /.

You'll need to edit the following in **src/Template/Categories/add.ctp** and **src/Template/Categories/edit.ctp**:

    echo $this->Form->control('parent_id', [\
        'options' => $parentCategories,\
        'empty' => 'No parent category'\
    ]);

1  
2  
3  
4  

Attach TreeBehavior to CategoriesTable [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-three.html#attach-treebehavior-to-categoriestable)

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

The [TreeBehavior](https://book.cakephp.org/3.x/orm/behaviors/tree.html)
 helps you manage hierarchical Tree structures in database table. It uses the [MPTT logic](https://www.sitepoint.com/hierarchical-data-database-2/)
 to manage the data. MPTT tree structures are optimized for reads, which often makes them a good fit for read heavy applications like blogs.

If you open the **src/Model/Table/CategoriesTable.php** file, you'll see that the TreeBehavior has been attached to your CategoriesTable in the `initialize()` method. Bake adds this behavior to any Tables that contain `lft` and `rght` columns:

    $this->addBehavior('Tree');

1  

With the TreeBehavior attached you'll be able to access some features like reordering the categories. We'll see that in a moment.

But for now, you have to remove the following controls in your Categories add and edit template files:

    echo $this->Form->control('lft');
    echo $this->Form->control('rght');

1  
2  

In addition you should disable or remove the requirePresence from the validator for both the `lft` and `rght` columns in your CategoriesTable model:

    public function validationDefault(Validator $validator)
    {
        $validator
            ->add('id', 'valid', ['rule' => 'numeric'])
            ->allowEmptyString('id', 'create');
    
        $validator
            ->add('lft', 'valid', ['rule' => 'numeric'])
        //    ->requirePresence('lft', 'create')
            ->notEmpty('lft');
    
        $validator
            ->add('rght', 'valid', ['rule' => 'numeric'])
        //    ->requirePresence('rght', 'create')
            ->notEmpty('rght');
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  

These fields are automatically managed by the TreeBehavior when a category is saved.

Using your web browser, add some new categories using the `/yoursite/categories/add` controller action.

Reordering Categories with TreeBehavior [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-three.html#reordering-categories-with-treebehavior)

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

In your categories index template file, you can list the categories and re-order them.

Let's modify the index method in your **CategoriesController.php** and add `moveUp()` and `moveDown()` methods to be able to reorder the categories in the tree:

    class CategoriesController extends AppController
    {
        public function index()
        {
            $categories = $this->Categories->find()
                ->order(['lft' => 'ASC']);
            $this->set(compact('categories'));
            $this->set('_serialize', ['categories']);
        }
    
        public function moveUp($id = null)
        {
            $this->request->allowMethod(['post', 'put']);
            $category = $this->Categories->get($id);
            if ($this->Categories->moveUp($category)) {
                $this->Flash->success('The category has been moved Up.');
            } else {
                $this->Flash->error('The category could not be moved up. Please, try again.');
            }
            return $this->redirect($this->referer(['action' => 'index']));
        }
    
        public function moveDown($id = null)
        {
            $this->request->allowMethod(['post', 'put']);
            $category = $this->Categories->get($id);
            if ($this->Categories->moveDown($category)) {
                $this->Flash->success('The category has been moved down.');
            } else {
                $this->Flash->error('The category could not be moved down. Please, try again.');
            }
            return $this->redirect($this->referer(['action' => 'index']));
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  

In **src/Template/Categories/index.ctp** replace the existing content with:

    <div class="actions large-2 medium-3 columns">
        <h3><?= __('Actions') ?></h3>
        <ul class="side-nav">
            <li><?= $this->Html->link(__('New Category'), ['action' => 'add']) ?></li>
        </ul>
    </div>
    <div class="categories index large-10 medium-9 columns">
        <table cellpadding="0" cellspacing="0">
        <thead>
            <tr>
                <th>Id</th>
                <th>Parent Id</th>
                <th>Lft</th>
                <th>Rght</th>
                <th>Name</th>
                <th>Description</th>
                <th>Created</th>
                <th class="actions"><?= __('Actions') ?></th>
            </tr>
        </thead>
        <tbody>
        <?php foreach ($categories as $category): ?>
            <tr>
                <td><?= $category->id ?></td>
                <td><?= $category->parent_id ?></td>
                <td><?= $category->lft ?></td>
                <td><?= $category->rght ?></td>
                <td><?= h($category->name) ?></td>
                <td><?= h($category->description) ?></td>
                <td><?= h($category->created) ?></td>
                <td class="actions">
                    <?= $this->Html->link(__('View'), ['action' => 'view', $category->id]) ?>
                    <?= $this->Html->link(__('Edit'), ['action' => 'edit', $category->id]) ?>
                    <?= $this->Form->postLink(__('Delete'), ['action' => 'delete', $category->id], ['confirm' => __('Are you sure you want to delete # {0}?', $category->id)]) ?>
                    <?= $this->Form->postLink(__('Move down'), ['action' => 'moveDown', $category->id], ['confirm' => __('Are you sure you want to move down # {0}?', $category->id)]) ?>
                    <?= $this->Form->postLink(__('Move up'), ['action' => 'moveUp', $category->id], ['confirm' => __('Are you sure you want to move up # {0}?', $category->id)]) ?>
                </td>
            </tr>
        <?php endforeach; ?>
        </tbody>
        </table>
    </div>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40  
41  
42  

Modifying the ArticlesController [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-three.html#modifying-the-articlescontroller)

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

In our `ArticlesController`, we'll get the list of all the categories. This will allow us to choose a category for an Article when creating or editing it:

    // src/Controller/ArticlesController.php
    
    namespace App\Controller;
    
    // Prior to 3.6 use Cake\Network\Exception\NotFoundException
    use Cake\Http\Exception\NotFoundException;
    
    class ArticlesController extends AppController
    {
        // ...
    
        public function add()
        {
            $article = $this->Articles->newEntity();
            if ($this->request->is('post')) {
                // Prior to 3.4.0 $this->request->data() was used.
                $article = $this->Articles->patchEntity($article, $this->request->getData());
                if ($this->Articles->save($article)) {
                    $this->Flash->success(__('Your article has been saved.'));
                    return $this->redirect(['action' => 'index']);
                }
                $this->Flash->error(__('Unable to add your article.'));
            }
            $this->set('article', $article);
    
            // Just added the categories list to be able to choose
            // one category for an article
            $categories = $this->Articles->Categories->find('treeList');
            $this->set(compact('categories'));
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  

Modifying the Articles Templates [​](https://book.cakephp.org/3.x/tutorials-and-examples/blog/part-three.html#modifying-the-articles-templates)

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

The article add file should look something like this:

    <!-- File: src/Template/Articles/add.ctp -->
    
    <h1>Add Article</h1>
    <?php
    echo $this->Form->create($article);
    // just added the categories control
    echo $this->Form->control('category_id');
    echo $this->Form->control('title');
    echo $this->Form->control('body', ['rows' => '3']);
    echo $this->Form->button(__('Save Article'));
    echo $this->Form->end();

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

When you go to the address /yoursite/categories/add you should see a list of categories to choose.

---

# Html | CakePHP

[Skip to content](https://book.cakephp.org/3.x/views/helpers/html.html#VPContent)

Return to top

Html [​](https://book.cakephp.org/3.x/views/helpers/html.html#html)

====================================================================

`class` Cake\\View\\Helper\\**HtmlHelper**(View $view, array $config = \[\])

The role of the HtmlHelper in CakePHP is to make HTML-related options easier, faster, and more resilient to change. Using this helper will enable your application to be more light on its feet, and more flexible on where it is placed in relation to the root of a domain.

Many HtmlHelper methods include a `$attributes` parameter, that allow you to tack on any extra attributes on your tags. Here are a few examples of how to use the `$attributes` parameter:

    Desired attributes: <tag class="someClass" />
    Array parameter: ['class' => 'someClass']
    
    Desired attributes: <tag name="foo" value="bar" />
    Array parameter:  ['name' => 'foo', 'value' => 'bar']

1  
2  
3  
4  
5  

Inserting Well-Formatted Elements [​](https://book.cakephp.org/3.x/views/helpers/html.html#inserting-well-formatted-elements)

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

The most important task the HtmlHelper accomplishes is creating well formed markup. This section will cover some of the methods of the HtmlHelper and how to use them.

### Creating Charset Tags [​](https://book.cakephp.org/3.x/views/helpers/html.html#creating-charset-tags)

`method` Cake\\View\\Helper\\HtmlHelper::**charset**($charset=null)

Used to create a meta tag specifying the document's character. The default value is UTF-8. An example use:

    echo $this->Html->charset();

1  

Will output:

    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

1  

Alternatively, :

    echo $this->Html->charset('ISO-8859-1');

1  

Will output:

    <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />

1  

### Linking to CSS Files [​](https://book.cakephp.org/3.x/views/helpers/html.html#linking-to-css-files)

`method` Cake\\View\\Helper\\HtmlHelper::**css**(mixed $path, array $options = \[\])

Creates a link(s) to a CSS style-sheet. If the `block` option is set to `true`, the link tags are added to the `css` block which you can print inside the head tag of the document.

You can use the `block` option to control which block the link element will be appended to. By default it will append to the `css` block.

If key 'rel' in `$options` array is set to 'import' the stylesheet will be imported.

This method of CSS inclusion assumes that the CSS file specified resides inside the **webroot/css** directory if path doesn't start with a '/'. :

    echo $this->Html->css('forms');

1  

Will output:

    <link rel="stylesheet" href="/css/forms.css" />

1  

The first parameter can be an array to include multiple files. :

    echo $this->Html->css(['forms', 'tables', 'menu']);

1  

Will output:

    <link rel="stylesheet" href="/css/forms.css" />
    <link rel="stylesheet" href="/css/tables.css" />
    <link rel="stylesheet" href="/css/menu.css" />

1  
2  
3  

You can include CSS files from any loaded plugin using `plugin syntax`. To include **plugins/DebugKit/webroot/css/toolbar.css** you could use the following:

    echo $this->Html->css('DebugKit.toolbar.css');

1  

If you want to include a CSS file which shares a name with a loaded plugin you can do the following. For example if you had a `Blog` plugin, and also wanted to include **webroot/css/Blog.common.css**, you would:

    echo $this->Html->css('Blog.common.css', ['plugin' => false]);

1  

### Creating CSS Programatically [​](https://book.cakephp.org/3.x/views/helpers/html.html#creating-css-programatically)

`method` Cake\\View\\Helper\\HtmlHelper::**style**(array $data, boolean $oneline = true)

Builds CSS style definitions based on the keys and values of the array passed to the method. Especially handy if your CSS file is dynamic. :

    echo $this->Html->style([\
        'background' => '#633',\
        'border-bottom' => '1px solid #000',\
        'padding' => '10px'\
    ]);

1  
2  
3  
4  
5  

Will output:

    background:#633; border-bottom:1px solid #000; padding:10px;

1  

### Creating meta Tags [​](https://book.cakephp.org/3.x/views/helpers/html.html#creating-meta-tags)

`method` Cake\\View\\Helper\\HtmlHelper::**meta**(string|array $type, string $url = null, array $options = \[\])

This method is handy for linking to external resources like RSS/Atom feeds and favicons. Like css(), you can specify whether or not you'd like this tag to appear inline or appended to the `meta` block by setting the 'block' key in the $attributes parameter to `true`, ie - `['block' => true]`.

If you set the "type" attribute using the $attributes parameter, CakePHP contains a few shortcuts:

| type | translated value |
| --- | --- |
| html | text/html |
| rss | application/rss+xml |
| atom | application/atom+xml |
| icon | image/x-icon |

    <?= $this->Html->meta(
        'favicon.ico',
        '/favicon.ico',
        ['type' => 'icon']
    );
    ?>
    // Output (line breaks added)
    // Note: The helper code makes two meta tags to  ensure the
    // icon is downloaded by both newer and older browsers
    // which require different rel attribute values.
    <link
        href="/subdir/favicon.ico"
        type="image/x-icon"
        rel="icon"
    />
    <link
        href="/subdir/favicon.ico"
        type="image/x-icon"
        rel="shortcut icon"
    />
    
    <?= $this->Html->meta(
        'Comments',
        '/comments/index.rss',
        ['type' => 'rss']
    );
    ?>
    // Output (line breaks added)
    <link
        href="http://example.com/comments/index.rss"
        title="Comments"
        type="application/rss+xml"
        rel="alternate"
    />

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  

This method can also be used to add the meta keywords and descriptions. Example:

    <?= $this->Html->meta(
        'keywords',
        'enter any meta keyword here'
    );
    ?>
    // Output
    <meta name="keywords" content="enter any meta keyword here" />
    
    <?= $this->Html->meta(
        'description',
        'enter any meta description here'
    );
    ?>
    // Output
    <meta name="description" content="enter any meta description here" />

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

In addition to making predefined meta tags, you can create link elements:

    <?= $this->Html->meta([\
        'link' => 'http://example.com/manifest',\
        'rel' => 'manifest'\
    ]);
    ?>
    // Output
    <link href="http://example.com/manifest" rel="manifest"/>

1  
2  
3  
4  
5  
6  
7  

Any attributes provided to meta() when called this way will be added to the generated link tag.

### Creating DOCTYPE [​](https://book.cakephp.org/3.x/views/helpers/html.html#creating-doctype)

`method` Cake\\View\\Helper\\HtmlHelper::**docType**(string $type = 'html5')

Returns a (X)HTML DOCTYPE (document type declaration). Supply the document type according to the following table:

| type | translated value |
| --- | --- |
| html4-strict | HTML 4.01 Strict |
| html4-trans | HTML 4.01 Transitional |
| html4-frame | HTML 4.01 Frameset |
| html5 (default) | HTML5 |
| xhtml-strict | XHTML 1.0 Strict |
| xhtml-trans | XHTML 1.0 Transitional |
| xhtml-frame | XHTML 1.0 Frameset |
| xhtml11 | XHTML 1.1 |

    echo $this->Html->docType();
    // Outputs: <!DOCTYPE html>
    
    echo $this->Html->docType('html4-trans');
    // Outputs:
    // <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
    //    "http://www.w3.org/TR/html4/loose.dtd">

1  
2  
3  
4  
5  
6  
7  

### Linking to Images [​](https://book.cakephp.org/3.x/views/helpers/html.html#linking-to-images)

`method` Cake\\View\\Helper\\HtmlHelper::**image**(string $path, array $options = \[\])

Creates a formatted image tag. The path supplied should be relative to **webroot/img/**. :

    echo $this->Html->image('cake_logo.png', ['alt' => 'CakePHP']);

1  

Will output:

    <img src="/img/cake_logo.png" alt="CakePHP" />

1  

To create an image link specify the link destination using the `url` option in `$attributes`. :

    echo $this->Html->image("recipes/6.jpg", [\
        "alt" => "Brownies",\
        'url' => ['controller' => 'Recipes', 'action' => 'view', 6]\
    ]);

1  
2  
3  
4  

Will output:

    <a href="/recipes/view/6">
        <img src="/img/recipes/6.jpg" alt="Brownies" />
    </a>

1  
2  
3  

If you are creating images in emails, or want absolute paths to images you can use the `fullBase` option:

    echo $this->Html->image("logo.png", ['fullBase' => true]);

1  

Will output:

    <img src="http://example.com/img/logo.jpg" alt="" />

1  

You can include image files from any loaded plugin using `plugin syntax`. To include **plugins/DebugKit/webroot/img/icon.png** You could use the following:

    echo $this->Html->image('DebugKit.icon.png');

1  

If you want to include an image file which shares a name with a loaded plugin you can do the following. For example if you had a `Blog` plugin, and also wanted to include **webroot/img/Blog.icon.png**, you would:

    echo $this->Html->image('Blog.icon.png', ['plugin' => false]);

1  

If you would like the prefix of the URL to not be `/img`, you can override this setting by specifying the prefix in the `$options` array :

    echo $this->Html->image("logo.png", ['pathPrefix' => '']);

1  

Will output:

    <img src="logo.jpg" alt="" />

1  

### Creating Links [​](https://book.cakephp.org/3.x/views/helpers/html.html#creating-links)

`method` Cake\\View\\Helper\\HtmlHelper::**link**(string $title, mixed $url = null, array $options = \[\])

General purpose method for creating HTML links. Use `$options` to specify attributes for the element and whether or not the `$title` should be escaped. :

    echo $this->Html->link(
        'Enter',
        '/pages/home',
        ['class' => 'button', 'target' => '_blank']
    );

1  
2  
3  
4  
5  

Will output:

    <a href="/pages/home" class="button" target="_blank">Enter</a>

1  

Use `'_full'=>true` option for absolute URLs:

    echo $this->Html->link(
        'Dashboard',
        ['controller' => 'Dashboards', 'action' => 'index', '_full' => true]
    );

1  
2  
3  
4  

Will output:

    <a href="http://www.yourdomain.com/dashboards/index">Dashboard</a>

1  

Specify `confirm` key in options to display a JavaScript `confirm()` dialog:

    echo $this->Html->link(
        'Delete',
        ['controller' => 'Recipes', 'action' => 'delete', 6],
        ['confirm' => 'Are you sure you wish to delete this recipe?']
    );

1  
2  
3  
4  
5  

Will output:

    <a href="/recipes/delete/6"
        onclick="return confirm(
            'Are you sure you wish to delete this recipe?'
        );">
        Delete
    </a>

1  
2  
3  
4  
5  
6  

Query strings can also be created with `link()`. :

    echo $this->Html->link('View image', [\
        'controller' => 'Images',\
        'action' => 'view',\
        1,\
        '?' => ['height' => 400, 'width' => 500]\
    ]);

1  
2  
3  
4  
5  
6  

Will output:

    <a href="/images/view/1?height=400&width=500">View image</a>

1  

HTML special characters in `$title` will be converted to HTML entities. To disable this conversion, set the escape option to `false` in the `$options` array. :

    echo $this->Html->link(
        $this->Html->image("recipes/6.jpg", ["alt" => "Brownies"]),
        "recipes/view/6",
        ['escape' => false]
    );

1  
2  
3  
4  
5  

Will output:

    <a href="/recipes/view/6">
        <img src="/img/recipes/6.jpg" alt="Brownies" />
    </a>

1  
2  
3  

Setting `escape` to `false` will also disable escaping of attributes of the link. You can use the option `escapeTitle` to disable just escaping of title and not the attributes. :

    echo $this->Html->link(
        $this->Html->image('recipes/6.jpg', ['alt' => 'Brownies']),
        'recipes/view/6',
        ['escapeTitle' => false, 'title' => 'hi "howdy"']
    );

1  
2  
3  
4  
5  

Will output:

    <a href="/recipes/view/6" title="hi &quot;howdy&quot;">
        <img src="/img/recipes/6.jpg" alt="Brownies" />
    </a>

1  
2  
3  

Also check `Cake\View\Helper\UrlHelper::build()` method for more examples of different types of URLs.

### Linking to Videos and Audio Files [​](https://book.cakephp.org/3.x/views/helpers/html.html#linking-to-videos-and-audio-files)

`method` Cake\\View\\Helper\\HtmlHelper::**media**(string|array $path, array $options)

Options:

*   `type` Type of media element to generate, valid values are "audio" or "video". If type is not provided media type is guessed based on file's mime type.
*   `text` Text to include inside the video tag
*   `pathPrefix` Path prefix to use for relative URLs, defaults to 'files/'
*   `fullBase` If provided the src attribute will get a full address including domain name

Returns a formatted audio/video tag:

    <?= $this->Html->media('audio.mp3') ?>
    
    // Output
    <audio src="/files/audio.mp3"></audio>
    
    <?= $this->Html->media('video.mp4', [\
        'fullBase' => true,\
        'text' => 'Fallback text'\
    ]) ?>
    
    // Output
    <video src="http://www.somehost.com/files/video.mp4">Fallback text</video>
    
    <?= $this->Html->media(
        ['video.mp4', ['src' => 'video.ogg', 'type' => "video/ogg; codecs='theora, vorbis'"]],
        ['autoplay']
    ) ?>
    
    // Output
    <video autoplay="autoplay">
        <source src="/files/video.mp4" type="video/mp4"/>
        <source src="/files/video.ogg" type="video/ogg;
            codecs='theora, vorbis'"/>
    </video>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  

### Linking to Javascript Files [​](https://book.cakephp.org/3.x/views/helpers/html.html#linking-to-javascript-files)

`method` Cake\\View\\Helper\\HtmlHelper::**script**(mixed $url, mixed $options)

Include a script file(s), contained either locally or as a remote URL.

By default, script tags are added to the document inline. If you override this by setting `$options['block']` to `true`, the script tags will instead be added to the `script` block which you can print elsewhere in the document. If you wish to override which block name is used, you can do so by setting `$options['block']`.

`$options['once']` controls whether or not you want to include this script once per request or more than once. This defaults to `true`.

You can use $options to set additional properties to the generated script tag. If an array of script tags is used, the attributes will be applied to all of the generated script tags.

This method of JavaScript file inclusion assumes that the JavaScript file specified resides inside the **webroot/js** directory:

    echo $this->Html->script('scripts');

1  

Will output:

    <script src="/js/scripts.js"></script>

1  

You can link to files with absolute paths as well to link files that are not in **webroot/js**:

    echo $this->Html->script('/otherdir/script_file');

1  

You can also link to a remote URL:

    echo $this->Html->script('https://code.jquery.com/jquery.min.js');

1  

Will output:

    <script src="https://code.jquery.com/jquery.min.js"></script>

1  

The first parameter can be an array to include multiple files. :

    echo $this->Html->script(['jquery', 'wysiwyg', 'scripts']);

1  

Will output:

    <script src="/js/jquery.js"></script>
    <script src="/js/wysiwyg.js"></script>
    <script src="/js/scripts.js"></script>

1  
2  
3  

You can append the script tag to a specific block using the `block` option:

    echo $this->Html->script('wysiwyg', ['block' => 'scriptBottom']);

1  

In your layout you can output all the script tags added to 'scriptBottom':

    echo $this->fetch('scriptBottom');

1  

You can include script files from any loaded plugin using `plugin syntax`. To include **plugins/DebugKit/webroot/js/toolbar.js** You could use the following:

    echo $this->Html->script('DebugKit.toolbar.js');

1  

If you want to include a script file which shares a name with a loaded plugin you can do the following. For example if you had a `Blog` plugin, and also wanted to include **webroot/js/Blog.plugins.js**, you would:

    echo $this->Html->script('Blog.plugins.js', ['plugin' => false]);

1  

### Creating Inline Javascript Blocks [​](https://book.cakephp.org/3.x/views/helpers/html.html#creating-inline-javascript-blocks)

`method` Cake\\View\\Helper\\HtmlHelper::**scriptBlock**($code, $options = \[\])

To generate Javascript blocks from PHP view code, you can use one of the script block methods. Scripts can either be output in place, or buffered into a block:

    // Define a script block all at once, with the defer attribute.
    $this->Html->scriptBlock('alert("hi")', ['defer' => true]);
    
    // Buffer a script block to be output later.
    $this->Html->scriptBlock('alert("hi")', ['block' => true]);

1  
2  
3  
4  
5  

`method` Cake\\View\\Helper\\HtmlHelper::**scriptStart**($options = \[\])

`method` Cake\\View\\Helper\\HtmlHelper::**scriptEnd**()

You can use the `scriptStart()` method to create a capturing block that will output into a `<script>` tag. Captured script snippets can be output inline, or buffered into a block:

    // Append into the 'script' block.
    $this->Html->scriptStart(['block' => true]);
    echo "alert('I am in the JavaScript');";
    $this->Html->scriptEnd();

1  
2  
3  
4  

Once you have buffered javascript, you can output it as you would any other [View Block](https://book.cakephp.org/3.x/views.html#view-blocks)
:

    // In your layout
    echo $this->fetch('script');

1  
2  

### Creating Nested Lists [​](https://book.cakephp.org/3.x/views/helpers/html.html#creating-nested-lists)

`method` Cake\\View\\Helper\\HtmlHelper::**nestedList**(array $list, array $options = \[\], array $itemOptions = \[\])

Build a nested list (UL/OL) out of an associative array:

    $list = [\
        'Languages' => [\
            'English' => [\
                'American',\
                'Canadian',\
                'British',\
            ],\
            'Spanish',\
            'German',\
        ]\
    ];
    echo $this->Html->nestedList($list);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

Output:

    // Output (minus the whitespace)
    <ul>
        <li>Languages
            <ul>
                <li>English
                    <ul>
                        <li>American</li>
                        <li>Canadian</li>
                        <li>British</li>
                    </ul>
                </li>
                <li>Spanish</li>
                <li>German</li>
            </ul>
        </li>
    </ul>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  

### Creating Table Headings [​](https://book.cakephp.org/3.x/views/helpers/html.html#creating-table-headings)

`method` Cake\\View\\Helper\\HtmlHelper::**tableHeaders**(array $names, array $trOptions = null, array $thOptions = null)

Creates a row of table header cells to be placed inside of <table> tags. :

    echo $this->Html->tableHeaders(['Date', 'Title', 'Active']);

1  

Output:

    <tr>
        <th>Date</th>
        <th>Title</th>
        <th>Active</th>
    </tr>

1  
2  
3  
4  
5  

    echo $this->Html->tableHeaders(
        ['Date', 'Title','Active'],
        ['class' => 'status'],
        ['class' => 'product_table']
    );

1  
2  
3  
4  
5  

Output:

    <tr class="status">
         <th class="product_table">Date</th>
         <th class="product_table">Title</th>
         <th class="product_table">Active</th>
    </tr>

1  
2  
3  
4  
5  

You can set attributes per column, these are used instead of the defaults provided in the `$thOptions`:

    echo $this->Html->tableHeaders([\
        'id',\
        ['Name' => ['class' => 'highlight']],\
        ['Date' => ['class' => 'sortable']]\
    ]);

1  
2  
3  
4  
5  

Output:

    <tr>
        <th>id</th>
        <th class="highlight">Name</th>
        <th class="sortable">Date</th>
    </tr>

1  
2  
3  
4  
5  

### Creating Table Cells [​](https://book.cakephp.org/3.x/views/helpers/html.html#creating-table-cells)

`method` Cake\\View\\Helper\\HtmlHelper::**tableCells**(array $data, array $oddTrOptions = null, array $evenTrOptions = null, $useCount = false, $continueOddEven = true)

Creates table cells, in rows, assigning <tr> attributes differently for odd- and even-numbered rows. Wrap a single table cell within an \[\] for specific <td>-attributes. :

    echo $this->Html->tableCells([\
        ['Jul 7th, 2007', 'Best Brownies', 'Yes'],\
        ['Jun 21st, 2007', 'Smart Cookies', 'Yes'],\
        ['Aug 1st, 2006', 'Anti-Java Cake', 'No'],\
    ]);

1  
2  
3  
4  
5  

Output:

    <tr><td>Jul 7th, 2007</td><td>Best Brownies</td><td>Yes</td></tr>
    <tr><td>Jun 21st, 2007</td><td>Smart Cookies</td><td>Yes</td></tr>
    <tr><td>Aug 1st, 2006</td><td>Anti-Java Cake</td><td>No</td></tr>

1  
2  
3  

    echo $this->Html->tableCells([\
        ['Jul 7th, 2007', ['Best Brownies', ['class' => 'highlight']] , 'Yes'],\
        ['Jun 21st, 2007', 'Smart Cookies', 'Yes'],\
        ['Aug 1st, 2006', 'Anti-Java Cake', ['No', ['id' => 'special']]],\
    ]);

1  
2  
3  
4  
5  

Output:

    <tr>
        <td>
            Jul 7th, 2007
        </td>
        <td class="highlight">
            Best Brownies
        </td>
        <td>
            Yes
        </td>
    </tr>
    <tr>
        <td>
            Jun 21st, 2007
        </td>
        <td>
            Smart Cookies
        </td>
        <td>
            Yes
        </td>
    </tr>
    <tr>
        <td>
            Aug 1st, 2006
        </td>
        <td>
            Anti-Java Cake
        </td>
        <td id="special">
            No
        </td>
    </tr>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  

    echo $this->Html->tableCells(
        [\
            ['Red', 'Apple'],\
            ['Orange', 'Orange'],\
            ['Yellow', 'Banana'],\
        ],
        ['class' => 'darker']
    );

1  
2  
3  
4  
5  
6  
7  
8  

Output:

    <tr class="darker"><td>Red</td><td>Apple</td></tr>
    <tr><td>Orange</td><td>Orange</td></tr>
    <tr class="darker"><td>Yellow</td><td>Banana</td></tr>

1  
2  
3  

Changing the Tags Output by HtmlHelper [​](https://book.cakephp.org/3.x/views/helpers/html.html#changing-the-tags-output-by-htmlhelper)

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

`method` Cake\\View\\Helper\\HtmlHelper::**setTemplates**(array $templates)

Load an array of templates to add/replace templates:

    // Load specific templates.
    $this->Html->setTemplates([\
        'javascriptlink' => '<script src="{{url}}" type="text/javascript"{{attrs}}></script>'\
    ]);

1  
2  
3  
4  

You can load a configuration file containing templates using the templater directly:

    // Load a configuration file with templates.
    $this->Html->templater()->load('my_tags');

1  
2  

When loading files of templates, your file should look like:

    <?php
    return [\
        'javascriptlink' => '<script src="{{url}}" type="text/javascript"{{attrs}}></script>'\
    ];

1  
2  
3  
4  

WARNING

Template strings containing a percentage sign (`%`) need special attention, you should prefix this character with another percentage so it looks like `%%`. The reason is that internally templates are compiled to be used with `sprintf()`. Example: `<div style="width:%%"></div>`

Creating Breadcrumb Trails with HtmlHelper [​](https://book.cakephp.org/3.x/views/helpers/html.html#creating-breadcrumb-trails-with-htmlhelper)

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

`method` Cake\\View\\Helper\\HtmlHelper::**addCrumb**(string $name, string $link = null, mixed $options = null)

`method` Cake\\View\\Helper\\HtmlHelper::**getCrumbs**(string $separator = '»', string $startText = false)

`method` Cake\\View\\Helper\\HtmlHelper::**getCrumbList**(array $options = \[\], $startText = false)

Many applications have breadcrumb trails to ease end user navigations. You can create a breadcrumb trail in your app with some help from HtmlHelper. To make bread crumbs, first the following in your layout template:

    echo $this->Html->getCrumbs(' > ', 'Home');

1  

The `$startText` option can also accept an array. This gives more control over the generated first link:

    echo $this->Html->getCrumbs(' > ', [\
        'text' => $this->Html->image('home.png'),\
        'url' => ['controller' => 'Pages', 'action' => 'display', 'home'],\
        'escape' => false\
    ]);

1  
2  
3  
4  
5  

Any keys that are not `text` or `url` will be passed to `~HtmlHelper::link()` as the `$options` parameter.

Now, in your view you'll want to add the following to start the breadcrumb trails on each of the pages:

    $this->Html->addCrumb('Users', '/users');
    $this->Html->addCrumb('Add User', ['controller' => 'Users', 'action' => 'add']);

1  
2  

This will add the output of "\*\*Home > Users > Add User\*\*" in your layout where `getCrumbs` was added.

You can also fetch the crumbs formatted inside an HTML list:

    echo $this->Html->getCrumbList();

1  

As options you can use regular HTML parameter that fits in the `<ul>` (Unordered List) such as `class` and for the specific options, you have: `separator` (will be between the `<li>` elements), `firstClass` and `lastClass` like:

    echo $this->Html->getCrumbList(
        [\
            'firstClass' => false,\
            'lastClass' => 'active',\
            'class' => 'breadcrumb'\
        ],
        'Home'
    );

1  
2  
3  
4  
5  
6  
7  
8  

This method uses `Cake\View\Helper\HtmlHelper::tag()` to generate list and its elements. Works similar to `Cake\View\Helper\HtmlHelper::getCrumbs()`, so it uses options which every crumb was added with. You can use the `$startText` parameter to provide the first breadcrumb link/text. This is useful when you always want to include a root link. This option works the same as the `$startText` option for `Cake\View\Helper\HtmlHelper::getCrumbs()`.

---

# クイックスタートガイド | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/quickstart.html#VPContent)

Return to top

クイックスタートガイド [​](https://book.cakephp.org/3.x/ja/quickstart.html#%E3%82%AF%E3%82%A4%E3%83%83%E3%82%AF%E3%82%B9%E3%82%BF%E3%83%BC%E3%83%88%E3%82%AB%E3%82%99%E3%82%A4%E3%83%88%E3%82%99)

=======================================================================================================================================================================================

CakePHP を学ぶ最も良い方法はなにか作ってみることです。 簡単なコンテンツ管理アプリケーションから作ることを始めましょう。

コンテンツ管理チュートリアル [​](https://book.cakephp.org/3.x/ja/quickstart.html#%E3%82%B3%E3%83%B3%E3%83%86%E3%83%B3%E3%83%84%E7%AE%A1%E7%90%86%E3%83%81%E3%83%A5%E3%83%BC%E3%83%88%E3%83%AA%E3%82%A2%E3%83%AB)

===================================================================================================================================================================================================

このチュートリアルは簡単な `CMS (Content Management System)` アプリケーションを作ります。 はじめに CakePHP のインストールを行い、データベースの作成、 そしてアプリケーションを素早く仕上げるための CakePHP が提供するツールを使います。

必要なもの:

1.  データベースサーバー。このチュートリアルでは MySQL サーバーを使います。 データベースを作成するための SQL の知識が必要です。CakePHP は、それを前提としています。 MySQL を使用するとき、 PHP で `pdo_mysql` が有効になっていることを確認してください。
2.  基礎的な PHP の知識。

始める前に、最新の PHP バージョンであることを確認してください。

    php -v

1  

最低でも PHP _5.6_ (CLI) 以上をインストールしてください。 あなたのウェブサーバーの PHP バージョンもまた、 _5.6_ 以上でなければなりません。 そして、コマンドラインインターフェイス (CLI) の PHP バージョンと同じバージョンにしてください。

CakePHP の取得 [​](https://book.cakephp.org/3.x/ja/quickstart.html#cakephp-%E3%81%AE%E5%8F%96%E5%BE%97)

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

最も簡単な CakePHP のインストール方法は Composer を使う方法です。Composer は、 ターミナルやコマンドラインプロンプトから CakePHP をインストールのシンプルな方法です。 まだ準備ができていない場合、最初に Composer をダウンロードとインストールが必要です。 cURL がインストールされていたら、次のように実行するのが簡単です。

    curl -s https://getcomposer.org/installer | php

1  

もしくは [Composer のウェブサイト](https://getcomposer.org/download/)
 から `composer.phar` をダウンロードすることができます。

そして、インストールディレクトリーからターミナルに次の行を入力するだけで、現在の作業ディレクトリーの **cms** ディレクトリーに CakePHP アプリケーションのスケルトンをインストールすることができます。

    php composer.phar create-project --prefer-dist cakephp/app:^3.8 cms

1  

[Composer Windows Installer](https://getcomposer.org/Composer-Setup.exe)
 をダウンロードして実行した場合、インストールディレクトリー (例えば、 C:\\wamp\\www\\dev\\cakephp3) からターミナルに次の行を入力してください。

    composer self-update && composer create-project --prefer-dist cakephp/app:^3.8 cms

1  

Composer を使うメリットは、 正しいファイルパーミッションの設定や、 **config/app.php** ファイルの作成などのように、自動的に完全なセットアップをしてくれることです。

CakePHP をインストールする他の方法があります。 Composer を使いたくない場合、 [インストール](https://book.cakephp.org/installation.html)
 セクションをご覧ください。

CakePHP のダウンロードやインストール方法にかかわらず、いったんセットアップが完了すると、 ディレクトリー構成は次のようになります。 :

    /cms
      /bin
      /config
      /logs
      /plugins
      /src
      /tests
      /tmp
      /vendor
      /webroot
      .editorconfig
      .gitignore
      .htaccess
      .travis.yml
      composer.json
      index.php
      phpunit.xml.dist
      README.md
    

CakePHP のディレクトリー構造がどのように働くかを学ぶのにいい機会かもしれません。 [CakePHP のフォルダー構成](https://book.cakephp.org/intro/cakephp-folder-structure.html)
 セクションをご覧ください。

このチュートリアルで迷ったら、 [GitHub](https://github.com/cakephp/cms-tutorial)
 で完成した結果を見ることができます。

インストールの確認 [​](https://book.cakephp.org/3.x/ja/quickstart.html#%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB%E3%81%AE%E7%A2%BA%E8%AA%8D)

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

デフォルトホームページを確認することで、インストールが正しいことをざっと確かめることができます。 その前に、開発用サーバーを起動する必要があります。

    cd /path/to/our/app
    
    bin/cake server

1  
2  
3  

NOTE

Windows では、このコマンドは `bin\cake server` (バックスラッシュ) です。

これで、 8765 ポートで PHP のビルトインウェブサーバーが起動します。ウェルカムページを見るために **[http://localhost:8765](http://localhost:8765/)
** をウェブブラウザーで開いてください。CakePHP がデータベース接続が 可能かどうか以外は、すべての確認事項が緑色のコック帽になるべきです。そうでなければ、PHP 拡張の 追加のインストールやディレクトリーのパーミッション設定が必要かもしれません。

次に、 [データベースの構築と最初のモデルの作成](https://book.cakephp.org/tutorials-and-examples/cms/database.html)
 をします。

CMS チュートリアル - データベース作成 [​](https://book.cakephp.org/3.x/ja/quickstart.html#cms-%E3%83%81%E3%83%A5%E3%83%BC%E3%83%88%E3%83%AA%E3%82%A2%E3%83%AB-%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%83%98%E3%82%99%E3%83%BC%E3%82%B9%E4%BD%9C%E6%88%90)

===========================================================================================================================================================================================================================================

先ほどは CakePHP をインストールしましたので、 `CMS (Content Management System)` アプリケーションのためのデータベースをセットアップしましょう。まだセットアップしていない場合、 例えば `cake_cms` のように、あなたの好きな名前で、このチュートリアルで使用する空のデータベースを 作成してください。必要なテーブルを作成するために、以下の SQL を実行することができます。

    USE cake_cms;
    
    CREATE TABLE users (
        id INT AUTO_INCREMENT PRIMARY KEY,
        email VARCHAR(255) NOT NULL,
        password VARCHAR(255) NOT NULL,
        created DATETIME,
        modified DATETIME
    );
    
    CREATE TABLE articles (
        id INT AUTO_INCREMENT PRIMARY KEY,
        user_id INT NOT NULL,
        title VARCHAR(255) NOT NULL,
        slug VARCHAR(191) NOT NULL,
        body TEXT,
        published BOOLEAN DEFAULT FALSE,
        created DATETIME,
        modified DATETIME,
        UNIQUE KEY (slug),
        FOREIGN KEY user_key (user_id) REFERENCES users(id)
    ) CHARSET=utf8mb4;
    
    CREATE TABLE tags (
        id INT AUTO_INCREMENT PRIMARY KEY,
        title VARCHAR(191),
        created DATETIME,
        modified DATETIME,
        UNIQUE KEY (title)
    ) CHARSET=utf8mb4;
    
    CREATE TABLE articles_tags (
        article_id INT NOT NULL,
        tag_id INT NOT NULL,
        PRIMARY KEY (article_id, tag_id),
        FOREIGN KEY tag_key(tag_id) REFERENCES tags(id),
        FOREIGN KEY article_key(article_id) REFERENCES articles(id)
    );
    
    INSERT INTO users (email, password, created, modified)
    VALUES
    ('[email protected]', 'secret', NOW(), NOW());
    
    INSERT INTO articles (user_id, title, slug, body, published, created, modified)
    VALUES
    (1, 'First Post', 'first-post', 'This is the first post.', 1, now(), now());

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40  
41  
42  
43  
44  
45  
46  

複合主キーを持つ `articles_tags` テーブルにお気づきでしょうか。CakePHP は、 ほぼどこでも複合主キーをサポートしているので、追加の `id` カラムを必要としない 単純なスキーマを持つことができます。

私たちが使用するテーブルやカラムの名前は恣意的ではありませんでした。CakePHP の [命名規則](https://book.cakephp.org/intro/conventions.html)
 を使用することによって、CakePHP がより効果的になり、 フレームワークの設定を避けられます。CakePHP は、ほぼ全てのデータベーススキーマに対応できるくらい 十分に柔軟ですが、CakePHP がデフォルトで提供する規約に従うことで、時間を節約できます。

データベースの設定 [​](https://book.cakephp.org/3.x/ja/quickstart.html#%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%83%98%E3%82%99%E3%83%BC%E3%82%B9%E3%81%AE%E8%A8%AD%E5%AE%9A)

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

次に、どこにデータベースあるか、そしてどうやってデータベースに接続するかを CakePHP に伝えましょう。あなたのセットアップを適用するために **config/app\_local.php** ファイルの中の `Datasources.default` 配列の値を置き換えてください。 完全な設定配列の例は、以下のようになります。 :

    <?php
    return [\
        // 上には他の設定があります\
        'Datasources' => [\
            'default' => [\
                'className' => 'Cake\Database\Connection',\
                'driver' => 'Cake\Database\Driver\Mysql',\
                'persistent' => false,\
                'host' => 'localhost',\
                'username' => 'cakephp',\
                'password' => 'AngelF00dC4k3~',\
                'database' => 'cake_cms',\
                'encoding' => 'utf8mb4',\
                'timezone' => 'UTC',\
                'cacheMetadata' => true,\
            ],\
        ],\
        // 下には他の設定があります\
    ];

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  

一度 **config/app\_local.php** ファイルを保存して、 'CakePHP is able to connect to the database' が緑色のコック帽であることを確認してください。

NOTE

CakePHP のデフォルト設定ファイルの複製は **config/app.default.php** にあります。

最初のモデルの作成 [​](https://book.cakephp.org/3.x/ja/quickstart.html#%E6%9C%80%E5%88%9D%E3%81%AE%E3%83%A2%E3%83%86%E3%82%99%E3%83%AB%E3%81%AE%E4%BD%9C%E6%88%90)

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

モデルは、CakePHP アプリケーションの心臓部です。データを読んだり変更することができます。 それらは、データ間のリレーションの構築、データの検証、アプリケーションルールの適用をすることができます。 モデルは、コントローラーアクションとテンプレートを構築するために必要な基礎を構築します。

CakePHP のモデルは `Table` と `Entity` オブジェクトで構成されています。 `Table` オブジェクトは、指定されたテーブルの中に保存されたエンティティーの集合へのアクセスを提供します。 それらは **src/Model/Table** の中に保存されます。私たちが今から作成するファイルは、 **src/Model/Table/ArticlesTable.php** に保存されます。完成したファイルは次のようになります。 :

    <?php
    // src/Model/Table/ArticlesTable.php
    namespace App\Model\Table;
    
    use Cake\ORM\Table;
    
    class ArticlesTable extends Table
    {
        public function initialize(array $config)
        {
            $this->addBehavior('Timestamp');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

このテーブルの `created` や `modified` カラムを自動的に更新する [Timestamp](https://book.cakephp.org/orm/behaviors/timestamp.html)
 ビヘイビアーを追加しました。 Table オブジェクトを `ArticlesTable` と名付けることで、CakePHP は、命名規則により `articles` テーブルを使用するモデルであると解釈します。また、CakePHP は、 `id` カラムがテーブルの主キーであると解釈する規約を使用します。

NOTE

もし一致するファイルが **src/Model/Table** に見つけられなければ、CakePHP は動的に モデルオブジェクトを生成します。これはまた、不意に間違ったファイル名 (例えば、 articlestable.php や ArticleTable.php) をつけると、CakePHP はどの設定も認識できず、 代わりに生成されたモデルを使うことになるということも意味します。

また、Articles のための Entity クラスも作成します。エンティティーは、 データベースの１つのレコードを表し、データに対して行レベルの振る舞いを提供します。 このエンティティーは、 **src/Model/Entity/Article.php** に保存されます。 完成したファイルは、次のようになります。 :

    <?php
    // src/Model/Entity/Article.php
    namespace App\Model\Entity;
    
    use Cake\ORM\Entity;
    
    class Article extends Entity
    {
        protected $_accessible = [\
            '*' => true,\
            'id' => false,\
            'slug' => false,\
        ];
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

エンティティーは、今はとてもスリムです。そして、 [Entities Mass Assignment](https://book.cakephp.org/orm/entities.html#entities-mass-assignment)
 によって どのようにプロパティーを変更できるかを制御するプロパティー `_accessible` をセットアップしました。

このモデルは、今は動きませんが、次は最初の [コントローラーとテンプレート](https://book.cakephp.org/tutorials-and-examples/cms/articles-controller.html)
 を作成し、このモデルとのやりとりができるようにします。

CMS チュートリアル - Articles コントローラーの作成 [​](https://book.cakephp.org/3.x/ja/quickstart.html#cms-%E3%83%81%E3%83%A5%E3%83%BC%E3%83%88%E3%83%AA%E3%82%A2%E3%83%AB-articles-%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%A9%E3%83%BC%E3%81%AE%E4%BD%9C%E6%88%90)

===============================================================================================================================================================================================================================================================

モデルが作成できたので、記事のコントローラーが必要です。CakePHP のコントローラーは、 レスポンスを準備するために、HTTP リクエストを処理し、モデルのメソッドに含まれるビジネスロジックを 実行します。この新しいコントローラーは **src/Controller** ディレクトリーの中で **ArticlesController.php** と呼ばれるファイルに記述します。 基本的なコントローラーの外観は次の通りです。 :

    <?php
    // src/Controller/ArticlesController.php
    
    namespace App\Controller;
    
    class ArticlesController extends AppController
    {
    }

1  
2  
3  
4  
5  
6  
7  
8  

それでは、コントローラーにアクションを追加しましょう。アクションは、ルートに接続させる コントローラーのメソッドです。例えば、ユーザーが **www.example.com/articles/index** (**www.example.com/articles** と同じ) をリクエストした場合、CakePHP は、 `ArticlesController` の `index` メソッドを呼びます。このメソッドは、モデル層に問い合わせ、 ビューでテンプレートを描画してレスポンスの準備する必要があります。そのアクションのコードは、 次のようになります。 :

    <?php
    // src/Controller/ArticlesController.php
    
    namespace App\Controller;
    
    class ArticlesController extends AppController
    {
        public function index()
        {
            $this->loadComponent('Paginator');
            $articles = $this->Paginator->paginate($this->Articles->find());
            $this->set(compact('articles'));
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

`ArticlesController` の `index()` 関数を定義することで、ユーザーは、 **www.example.com/articles/index** をリクエストすることで、そこにあるロジックに アクセスできるようになります。同様に、 `foobar()` という関数を定義した場合、 ユーザーはそのメソッドに **www.example.com/articles/foobar** で、アクセスできます。 特定の URL を取得できるように、コントローラーとアクションの名前を付けたいという 誘惑に駆られるかもしれません。その誘惑に抗ってください。代わりに、 [CakePHP の規約](https://book.cakephp.org/intro/conventions.html)
 にしたがって、読みやすく意味のあるアクション名を作成してください。そうすれば [ルーティング](https://book.cakephp.org/development/routing.html)
 を使って、あなたが望む URL を、 あなたが作成したアクションに接続することができます。

このコントローラーのアクションはとてもシンプルです。 これは、命名規則によって自動的にロードされる Articles モデルを使用して、 データベースからページ分けされた記事を取得します。次に (これからすぐに作成する) テンプレートの中に記事を渡すために `set()` を使用します。CakePHP は、 コントローラーのアクションが完了した後、自動的にテンプレートを描画します。

記事一覧のテンプレート作成 [​](https://book.cakephp.org/3.x/ja/quickstart.html#%E8%A8%98%E4%BA%8B%E4%B8%80%E8%A6%A7%E3%81%AE%E3%83%86%E3%83%B3%E3%83%95%E3%82%9A%E3%83%AC%E3%83%BC%E3%83%88%E4%BD%9C%E6%88%90)

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

モデルからデータを取得し、ビューのコンテキストを準備するコントローラーを持っていますので、 index アクションのビューテンプレートを作成しましょう。

CakePHP のビューテンプレートは、アプリケーションのレイアウト内に挿入される表示用の PHP コードです。 ここで HTML が作成されますが、 View は JSON、CSV、または PDF などのバイナリファイルの生成もできます。

レイアウトは、ビューを囲む表示用のコードです。レイアウトファイルは、 ヘッダー・フッター・ナビゲーション要素のような一般的なサイトの要素が含まれます。 アプリケーションは、複数のレイアウトを持つことができ、それらを切り替えることができますが、 今回はデフォルトのレイアウトを使用しましょう。

CakePHP のテンプレートファイルは、 **src/Template** の中で 対応するコントローラーの名前をつけたフォルダーの中に保存されます。 今回の場合、 'Articles' という名前のフォルダーを作成する必要があります。 あなたのアプリケーションに以下のコードを追加してください。

    <!-- File: src/Template/Articles/index.ctp -->
    
    <h1>記事一覧</h1>
    <table>
        <tr>
            <th>タイトル</th>
            <th>作成日時</th>
        </tr>
    
        <!-- ここで、$articles クエリーオブジェクトを繰り返して、記事の情報を出力します -->
    
        <?php foreach ($articles as $article): ?>
        <tr>
            <td>
                <?= $this->Html->link($article->title, ['action' => 'view', $article->slug]) ?>
            </td>
            <td>
                <?= $article->created->format(DATE_RFC850) ?>
            </td>
        </tr>
        <?php endforeach; ?>
    </table>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  

前のセクションでは、 `set()` を使って 'articles' 変数をビューに割り当てました。 ビューに渡された変数は、上記のコードの中で使用したローカル変数として、 ビューテンプレートの中で利用できます。

`$this->Html` というオブジェクトを使っていることにお気づきでしょうか。 これは、 CakePHP の [HtmlHelper](https://book.cakephp.org/views/helpers/html.html)
 のインスタンスです。 CakePHP には、リンク、フォーム、ページ制御ボタンの作成などのタスクを簡単に行うための 一連のビューヘルパーが付属しています。 [ヘルパー](https://book.cakephp.org/views/helpers.html)
 について、 その章で詳しく学べますが、ここで重要なことは、 `link()` メソッドは、 与えられたリンクテキスト(第１パラメーター) と URL (第２パラメーター) を元に HTML リンクを生成することです。

CakePHP で URL を指定する際、配列や [名前付きルート](https://book.cakephp.org/development/routing.html#named-routes)
 が 推奨されます。これらの構文で、CakePHP が提供するリバースルーティング機能を 活用することができます。

この時点で、ブラウザーで **[http://localhost:8765/articles/index](http://localhost:8765/articles/index)
** を 見ることができるはずです。記事のタイトルとテーブルのリストで正しくフォーマットされた リストビューが表示されます。

view アクションの作成 [​](https://book.cakephp.org/3.x/ja/quickstart.html#view-%E3%82%A2%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3%E3%81%AE%E4%BD%9C%E6%88%90)

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

記事一覧の 'view' リンクの一つをクリックした際、アクションが実装されてないという エラーページが表示されるはずです。今から、それを修正しましょう。 :

    // 既存の src/Controller/ArticlesController.php ファイルに追加
    
    public function view($slug = null)
    {
        $article = $this->Articles->findBySlug($slug)->firstOrFail();
        $this->set(compact('article'));
    }

1  
2  
3  
4  
5  
6  
7  

これはシンプルなアクションですが、いくつかの強力な CakePHP 機能を使用しています。 [動的なファインダー](https://book.cakephp.org/orm/retrieving-data-and-resultsets.html#dynamic-finders)
 である `findBySlug()` を使用することにより アクションを開始します。このメソッドは、与えられたスラグによって記事を検索する基本的なクエリーを 作成することができます。その時、最初のレコードを取得するか `NotFoundException` を投げるか のいずれかをする `firstOrFail()` を使います。

このアクションは `$slug` パラメーターを持ちますが、そのパラメーターはどこから来るのでしょう？ ユーザーが `/articles/view/first-post` をリクエストした際、 値 'first-post' が CakePHP のルーティングとディスパッチレイヤーで `$slug` に渡されます。 新しいアクションを保存してブラウザーをリロードすると、別の CakePHP エラーページが表示され、 view テンプレートが見つからないことがわかります。それを修正しましょう。

view テンプレートの作成 [​](https://book.cakephp.org/3.x/ja/quickstart.html#view-%E3%83%86%E3%83%B3%E3%83%95%E3%82%9A%E3%83%AC%E3%83%BC%E3%83%88%E3%81%AE%E4%BD%9C%E6%88%90)

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

新しい 'view' アクションのビューを作成し、 **src/Template/Articles/view.ctp** に置きましょう。

    <!-- File: src/Template/Articles/view.ctp -->
    
    <h1><?= h($article->title) ?></h1>
    <p><?= h($article->body) ?></p>
    <p><small>作成日時: <?= $article->created->format(DATE_RFC850) ?></small></p>
    <p><?= $this->Html->link('Edit', ['action' => 'edit', $article->slug]) ?></p>

1  
2  
3  
4  
5  
6  

`/articles/index` のリンクを使うことによって、動作することを確認できますし、 `/articles/view/slug-name` のような URL にアクセスすることによって手動で記事を リクエストすることを確認できます。

記事の追加 [​](https://book.cakephp.org/3.x/ja/quickstart.html#%E8%A8%98%E4%BA%8B%E3%81%AE%E8%BF%BD%E5%8A%A0)

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

基本的な読み込みビューを作成できたので、新しい記事を作成できるようにする必要があります。 まず、 `ArticlesController` に `add()` アクションを作成してください。 コントローラーは次のようになります。 :

    // src/Controller/ArticlesController.php
    
    namespace App\Controller;
    
    use App\Controller\AppController;
    
    class ArticlesController extends AppController
    {
    
        public function initialize()
        {
            parent::initialize();
    
            $this->loadComponent('Paginator');
            $this->loadComponent('Flash'); // FlashComponent をインクルード
        }
    
        public function index()
        {
            $articles = $this->Paginator->paginate($this->Articles->find());
            $this->set(compact('articles'));
        }
    
        public function view($slug)
        {
            $article = $this->Articles->findBySlug($slug)->firstOrFail();
            $this->set(compact('article'));
        }
    
        public function add()
        {
            $article = $this->Articles->newEntity();
            if ($this->request->is('post')) {
                $article = $this->Articles->patchEntity($article, $this->request->getData());
    
                // user_id の決め打ちは一時的なもので、あとで認証を構築する際に削除されます。
                $article->user_id = 1;
    
                if ($this->Articles->save($article)) {
                    $this->Flash->success(__('Your article has been saved.'));
                    return $this->redirect(['action' => 'index']);
                }
                $this->Flash->error(__('Unable to add your article.'));
            }
            $this->set('article', $article);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40  
41  
42  
43  
44  
45  
46  
47  

NOTE

[フラッシュ](https://book.cakephp.org/controllers/components/flash.html)
 コンポーネントを、使用するコントローラーに含める 必要があります。また、 `AppController` に含めてもよいでしょう。

こちらがこの `add()` アクションの行うことです。

*   リクエストの HTTP メソッドが POST だった場合、Articles モデルを使用してデータを保存しようとします。
*   なんらかの理由で保存しなかった場合、ただビューを描画します。これは、ユーザーバリデーションエラーや その他の警告を表示する機会を与えてくれます。

全ての CakePHP のリクエストは、 `$this->request` を使用してアクセス可能なリクエストオブジェクトを 含みます。リクエストオブジェクトは、今受信したリクエストに関する情報を含みます。リクエストが HTTP POST リクエストであることを確認するために `Cake\Http\ServerRequest::is()` メソッドを 使用します。

POST データは、 `$this->request->getData()` で利用可能です。それがどのような内容かを 知りたい場合に `pr()` 関数や `debug()` 関数を使って出力することができます。 データを保存するために、まず POST データを Article エンティティーに 「変換 (marshal)」します。 エンティティーは、以前作成した ArticlesTable を使用して永続化されます。

新しい記事を保存した後、セッションにメッセージをセットするために FlashComponent の `success()` メソッドを使用します。 `success` メソッドは PHP の [マジックメソッド機能](https://php.net/manual/ja/language.oop5.overloading.php#object.call)
 を使用して提供されます。フラッシュメッセージは、リダイレクトした後の次のページ上で表示されます。 レイアウトの中に、フラッシュメッセージを表示し、対応するセッション変数をクリアする `<?= $this->Flash->render() ?>` があります。最後に、保存が完了した後、 `Cake\Controller\Controller::redirect` を使ってユーザーを記事一覧に戻します。 パラメーター `['action' => 'index']` は、例えば `ArticlesController` の index アクションの場合、 URL `/articles` に変換します。 [API](https://api.cakephp.org/)
 の `Cake\Routing\Router::url()` 関数を参照すると、様々な CakePHP 関数の URL を 指定できる書式を見ることができます。

add テンプレートの作成 [​](https://book.cakephp.org/3.x/ja/quickstart.html#add-%E3%83%86%E3%83%B3%E3%83%95%E3%82%9A%E3%83%AC%E3%83%BC%E3%83%88%E3%81%AE%E4%BD%9C%E6%88%90)

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

こちらが add ビューテンプレートです。

    <!-- File: src/Template/Articles/add.ctp -->
    
    <h1>記事の追加</h1>
    <?php
        echo $this->Form->create($article);
        // 今はユーザーを直接記述
        echo $this->Form->control('user_id', ['type' => 'hidden', 'value' => 1]);
        echo $this->Form->control('title');
        echo $this->Form->control('body', ['rows' => '3']);
        echo $this->Form->button(__('Save Article'));
        echo $this->Form->end();
    ?>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

FormHelper を使うと、 HTML フォームの開始タグを生成できます。 こちらが `$this->Form->create()` が生成する HTML です。

    <form method="post" action="/articles/add">

1  

URL オプションなしで `create()` を呼び出したので、 `FormHelper` は、フォームを 現在のアクションに戻したいと仮定します。

`$this->Form->control()` メソッドは、同じ名前のフォーム要素を作成するために使われます。 １番目のパラメーターは、どのフィールドに対応するかを CakePHP に伝えます。そして、２番目の パラメーターは、さまざまなオプションを指定できます。上記の場合、テキストエリアの行数などです。 ここではちょっとした内部情報の確認 (introspection) と規約の使用があります。 `control()` は、指定されたモデルフィールドにもとづいて異なるフォーム要素を出力し、 語形変化 (inflection) を使ってラベルを生成します。オプションを使用して、 フォームコントロールのラベル、入力、または、その他の要素をカスタマイズすることができます。 `$this->Form->end()` の呼び出しでフォームを閉じます。

さて、 **src/Template/Articles/index.ctp** ビューを更新して、新しい 「記事の追加」リンクを追加しましょう。 `<table>` の前に以下の行を追加してください。 :

    <?= $this->Html->link('記事の追加', ['action' => 'add']) ?>

1  

シンプルなスラグ生成の追加 [​](https://book.cakephp.org/3.x/ja/quickstart.html#%E3%82%B7%E3%83%B3%E3%83%95%E3%82%9A%E3%83%AB%E3%81%AA%E3%82%B9%E3%83%A9%E3%82%AF%E3%82%99%E7%94%9F%E6%88%90%E3%81%AE%E8%BF%BD%E5%8A%A0)

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

記事を今保存すると、スラグ属性は、作成されておらず、カラムは `NOT NULL` なので保存に失敗します。 スラグの値は、通常、URL セーフなバージョンの記事タイトルです。スラグを作成するために ORM の [beforeSave() コールバック](https://book.cakephp.org/orm/table-objects.html#table-callbacks)
 が使用できます。 :

    // src/Model/Table/ArticlesTable.php の中で
    namespace App\Model\Table;
    
    use Cake\ORM\Table;
    // Text クラス
    use Cake\Utility\Text;
    
    // 次のメソッドを追加してください。
    
    public function beforeSave($event, $entity, $options)
    {
        if ($entity->isNew() && !$entity->slug) {
            $sluggedTitle = Text::slug($entity->title);
            // スラグをスキーマで定義されている最大長に調整
            $entity->slug = substr($sluggedTitle, 0, 191);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

このコードはシンプルで、重複したスラグを考慮していません。しかし、後でそれを修正します。

edit アクションの追加 [​](https://book.cakephp.org/3.x/ja/quickstart.html#edit-%E3%82%A2%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3%E3%81%AE%E8%BF%BD%E5%8A%A0)

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

今のアプリケーションは、記事を保存できますが編集はできません。今から修正しましょう。 `ArticlesController` に次のアクションを追加してください。 :

    // src/Controller/ArticlesController.php の中で
    
    // 次のメソッドを追加してください。
    
    public function edit($slug)
    {
        $article = $this->Articles->findBySlug($slug)->firstOrFail();
        if ($this->request->is(['post', 'put'])) {
            $this->Articles->patchEntity($article, $this->request->getData());
            if ($this->Articles->save($article)) {
                $this->Flash->success(__('Your article has been updated.'));
                return $this->redirect(['action' => 'index']);
            }
            $this->Flash->error(__('Unable to update your article.'));
        }
    
        $this->set('article', $article);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

このアクションは、まずユーザーが既存のレコードにアクセスすることを確保します。 `$slug` パラメーターの中に渡されなかったり、記事が存在しなかった場合、 `NotFoundException` が投げられ、 CakePHP の ErrorHandler が、適切なエラーページを 描画します。

次に、このアクションはリクエストが POST または PUT いずれかのリクエストかどうかをチェックします。 そうであれば、POST/PUT データを元に、 `patchEntity()` メソッドを使って article エンティティーを更新します。最後に、 `save()` を呼び出して、 適切なフラッシュメッセージを設定し、リダイレクトするか検証エラーを表示します。

edit テンプレートの作成 [​](https://book.cakephp.org/3.x/ja/quickstart.html#edit-%E3%83%86%E3%83%B3%E3%83%95%E3%82%9A%E3%83%AC%E3%83%BC%E3%83%88%E3%81%AE%E4%BD%9C%E6%88%90)

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

edit テンプレートは次のようになります。

    <!-- File: src/Template/Articles/edit.ctp -->
    
    <h1>記事の編集</h1>
    <?php
        echo $this->Form->create($article);
        echo $this->Form->control('user_id', ['type' => 'hidden']);
        echo $this->Form->control('title');
        echo $this->Form->control('body', ['rows' => '3']);
        echo $this->Form->button(__('Save Article'));
        echo $this->Form->end();
    ?>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

このテンプレートは、編集フォーム（値が入力された状態）に加えて、 必要な検証エラーメッセージを出力します。

特定の記事を編集するためのリンクで index ビューを更新できるようになりました。

    <!-- File: src/Template/Articles/index.ctp  (編集リンク付き) -->
    
    <h1>記事一覧</h1>
    <p><?= $this->Html->link("記事の追加", ['action' => 'add']) ?></p>
    <table>
        <tr>
            <th>タイトル</th>
            <th>作成日時</th>
            <th>操作</th>
        </tr>
    
    <!-- ここで、$articles クエリーオブジェクトを繰り返して、記事情報を出力します -->
    
    <?php foreach ($articles as $article): ?>
        <tr>
            <td>
                <?= $this->Html->link($article->title, ['action' => 'view', $article->slug]) ?>
            </td>
            <td>
                <?= $article->created->format(DATE_RFC850) ?>
            </td>
            <td>
                <?= $this->Html->link('編集', ['action' => 'edit', $article->slug]) ?>
            </td>
        </tr>
    <?php endforeach; ?>
    
    </table>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  

Articles の検証ルールの更新 [​](https://book.cakephp.org/3.x/ja/quickstart.html#articles-%E3%81%AE%E6%A4%9C%E8%A8%BC%E3%83%AB%E3%83%BC%E3%83%AB%E3%81%AE%E6%9B%B4%E6%96%B0)

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

この時点まで、記事は入力検証が行われていませんでした。 [バリデーター](https://book.cakephp.org/orm/validation.html#validating-request-data)
 を使って修正しましょう。 :

    // src/Model/Table/ArticlesTable.php
    
    // この use 文を名前空間宣言のすぐ下に追加して、
    // Validator クラスをインポートします。
    use Cake\Validation\Validator;
    
    // 次のメソッドを追加してください。
    public function validationDefault(Validator $validator)
    {
        $validator
            ->allowEmptyString('title', false)
            ->minLength('title', 10)
            ->maxLength('title', 255)
    
            ->allowEmptyString('body', false)
            ->minLength('body', 10);
    
        return $validator;
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  

`validationDefault()` メソッドは、 `save()` メソッドが呼ばれる際のデータの検証方法を CakePHP に伝えます。ここでは、title フィールドと body フィールドの両方が空であってはならず、 長さに制約があることを指定しました。

CakePHP の検証エンジンは強力で柔軟性があります。メールアドレス、IP アドレスなどのようにタスクに 頻繁に使用されるルール一式を提供し、独自の検証ルールを追加する柔軟性を提供します。 その設定の詳細については、 [バリデーション](https://book.cakephp.org/core-libraries/validation.html)
 のドキュメントを確認してください。

さて、検証ルールが整いましたので、 それがどのように動くかを見るためにアプリを使って空のタイトルや本文で記事を追加してみてください。 FormHelper の `Cake\View\Helper\FormHelper::control()` メソッドを使用して、 フォーム要素を作成しているので、検証エラーメッセージが自動的に表示されます。

delete アクションの追加 [​](https://book.cakephp.org/3.x/ja/quickstart.html#delete-%E3%82%A2%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3%E3%81%AE%E8%BF%BD%E5%8A%A0)

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

次に、ユーザーが記事を削除する方法を作ってみましょう。 `ArticlesController` の中の `delete()` アクションから始めましょう。 :

    // src/Controller/ArticlesController.php
    
    public function delete($slug)
    {
        $this->request->allowMethod(['post', 'delete']);
    
        $article = $this->Articles->findBySlug($slug)->firstOrFail();
        if ($this->Articles->delete($article)) {
            $this->Flash->success(__('The {0} article has been deleted.', $article->title));
            return $this->redirect(['action' => 'index']);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

このロジックは `$slug` で指定された記事を削除し、 `$this->Flash->success()` を使って `/articles` にリダイレクトした後に確認メッセージを表示します。 ユーザーが GET リクエストを使って記事を削除しようとすると、 `allowMethod()` は例外をスローします。 キャッチされない例外は CakePHP の例外ハンドラによって捕捉され、素晴らしいエラーページが表示されます。 アプリケーションで生成する必要のあるさまざまな HTTP エラーを示すために使用できる組み込みの [例外](https://book.cakephp.org/development/errors.html)
 が多数あります。

WARNING

ウェブクローラーが誤ってすべてのコンテンツを削除する可能性があるため、 GET リクエストを使用してコンテンツを削除することは _とても_ 危険です。 それでコントローラーの中で `allowMethod()` を使ったのです。

私たちはロジックを実行して、別のアクションにリダイレクトしているだけなので、 このアクションにはテンプレートはありません。ユーザーが記事を削除できるリンク付きに index テンプレートを更新するといいでしょう。

    <!-- File: src/Template/Articles/index.ctp  (削除リンク付き) -->
    
    <h1>記事一覧</h1>
    <p><?= $this->Html->link("記事の追加", ['action' => 'add']) ?></p>
    <table>
        <tr>
            <th>タイトル</th>
            <th>作成日時</th>
            <th>操作</th>
        </tr>
    
    <!-- ここで、$articles クエリーオブジェクトを繰り返して、記事情報を出力します -->
    
    <?php foreach ($articles as $article): ?>
        <tr>
            <td>
                <?= $this->Html->link($article->title, ['action' => 'view', $article->slug]) ?>
            </td>
            <td>
                <?= $article->created->format(DATE_RFC850) ?>
            </td>
            <td>
                <?= $this->Html->link('編集', ['action' => 'edit', $article->slug]) ?>
                <?= $this->Form->postLink(
                    '削除',
                    ['action' => 'delete', $article->slug],
                    ['confirm' => 'よろしいですか?'])
                ?>
            </td>
        </tr>
    <?php endforeach; ?>
    
    </table>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  

`Cake\View\Helper\FormHelper::postLink()` を使用すると、 JavaScript を使用して記事を削除する POST リクエストを行うリンクが作成されます。

NOTE

また、このビューコードは `FormHelper` を使って記事を削除しようとする前に JavaScript の確認ダイアログを表示します。

基本的な記事管理のセットアップの後は、 [タグとユーザーテーブルの基本的な操作](https://book.cakephp.org/tutorials-and-examples/cms/tags-and-users.html)
 を作成します。

---

# Quick Start Guide | CakePHP

[Skip to content](https://book.cakephp.org/3.x/quickstart.html#VPContent)

Return to top

Quick Start Guide [​](https://book.cakephp.org/3.x/quickstart.html#quick-start-guide)

======================================================================================

The best way to experience and learn CakePHP is to sit down and build something. To start off we'll build a simple Content Management application.

Content Management Tutorial [​](https://book.cakephp.org/3.x/quickstart.html#content-management-tutorial)

==========================================================================================================

This tutorial will walk you through the creation of a simple `CMS (Content Management System)` application. To start with, we'll be installing CakePHP, creating our database, and building simple article management.

Here's what you'll need:

1.  A database server. We're going to be using MySQL server in this tutorial. You'll need to know enough about SQL in order to create a database, and run SQL snippets from the tutorial. CakePHP will handle building all the queries your application needs. Since we're using MySQL, also make sure that you have `pdo_mysql` enabled in PHP.
2.  Basic PHP knowledge.

Before starting you should make sure that you have got an up to date PHP version:

    php -v

1  

You should at least have got installed PHP _5.6_ (CLI) or higher. Your webserver's PHP version must also be of _5.6_ or higher, and should be the same version your command line interface (CLI) PHP is.

Getting CakePHP [​](https://book.cakephp.org/3.x/quickstart.html#getting-cakephp)

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

The easiest way to install CakePHP is to use Composer. Composer is a simple way of installing CakePHP from your terminal or command line prompt. First, you'll need to download and install Composer if you haven't done so already. If you have cURL installed, it's as easy as running the following:

    curl -s https://getcomposer.org/installer | php

1  

Or, you can download `composer.phar` from the [Composer website](https://getcomposer.org/download/)
.

Then simply type the following line in your terminal from your installation directory to install the CakePHP application skeleton in the **cms** directory of the current working directory:

    php composer.phar create-project --prefer-dist cakephp/app:"^3.10" cms

1  

If you downloaded and ran the [Composer Windows Installer](https://getcomposer.org/Composer-Setup.exe)
, then type the following line in your terminal from your installation directory (ie. C:\\wamp\\www\\dev\\cakephp3):

    composer self-update && composer create-project --prefer-dist cakephp/app:"^3.10" cms

1  

The advantage to using Composer is that it will automatically complete some important set up tasks, such as setting the correct file permissions and creating your **config/app.php** file for you.

There are other ways to install CakePHP. If you cannot or don't want to use Composer, check out the [Installation](https://book.cakephp.org/installation.html)
 section.

Regardless of how you downloaded and installed CakePHP, once your set up is completed, your directory setup should look something like the following:

    /cms
      /bin
      /config
      /logs
      /plugins
      /src
      /tests
      /tmp
      /vendor
      /webroot
      .editorconfig
      .gitignore
      .htaccess
      .travis.yml
      composer.json
      index.php
      phpunit.xml.dist
      README.md
    

Now might be a good time to learn a bit about how CakePHP's directory structure works: check out the [CakePHP Folder Structure](https://book.cakephp.org/intro/cakephp-folder-structure.html)
 section.

If you get lost during this tutorial, you can see the finished result [on GitHub](https://github.com/cakephp/cms-tutorial)
.

Checking our Installation [​](https://book.cakephp.org/3.x/quickstart.html#checking-our-installation)

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

We can quickly check that our installation is correct, by checking the default home page. Before you can do that, you'll need to start the development server:

    cd /path/to/our/app
    
    bin/cake server

1  
2  
3  

NOTE

For Windows, the command needs to be `bin\cake server` (note the backslash).

This will start PHP's built-in webserver on port 8765. Open up **[http://localhost:8765](http://localhost:8765/)
** in your web browser to see the welcome page. All the bullet points should be green chef hats other than CakePHP being able to connect to your database. If not, you may need to install additional PHP extensions, or set directory permissions.

Next, we will build our [Database and create our first model](https://book.cakephp.org/tutorials-and-examples/cms/database.html)
.

CMS Tutorial - Creating the Database [​](https://book.cakephp.org/3.x/quickstart.html#cms-tutorial-creating-the-database)

==========================================================================================================================

Now that we have CakePHP installed, let's set up the database for our `CMS (Content Management System)` application. If you haven't already done so, create an empty database for use in this tutorial, with a name of your choice, e.g. `cake_cms`. You can execute the following SQL to create the necessary tables:

    USE cake_cms;
    
    CREATE TABLE users (
        id INT AUTO_INCREMENT PRIMARY KEY,
        email VARCHAR(255) NOT NULL,
        password VARCHAR(255) NOT NULL,
        created DATETIME,
        modified DATETIME
    );
    
    CREATE TABLE articles (
        id INT AUTO_INCREMENT PRIMARY KEY,
        user_id INT NOT NULL,
        title VARCHAR(255) NOT NULL,
        slug VARCHAR(191) NOT NULL,
        body TEXT,
        published BOOLEAN DEFAULT FALSE,
        created DATETIME,
        modified DATETIME,
        UNIQUE KEY (slug),
        FOREIGN KEY user_key (user_id) REFERENCES users(id)
    ) CHARSET=utf8mb4;
    
    CREATE TABLE tags (
        id INT AUTO_INCREMENT PRIMARY KEY,
        title VARCHAR(191),
        created DATETIME,
        modified DATETIME,
        UNIQUE KEY (title)
    ) CHARSET=utf8mb4;
    
    CREATE TABLE articles_tags (
        article_id INT NOT NULL,
        tag_id INT NOT NULL,
        PRIMARY KEY (article_id, tag_id),
        FOREIGN KEY tag_key(tag_id) REFERENCES tags(id),
        FOREIGN KEY article_key(article_id) REFERENCES articles(id)
    );
    
    INSERT INTO users (email, password, created, modified)
    VALUES
    ('[email protected]', 'secret', NOW(), NOW());
    
    INSERT INTO articles (user_id, title, slug, body, published, created, modified)
    VALUES
    (1, 'First Post', 'first-post', 'This is the first post.', 1, now(), now());

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40  
41  
42  
43  
44  
45  
46  

You may have noticed that the `articles_tags` table used a composite primary key. CakePHP supports composite primary keys almost everywhere allowing you to have simpler schemas that don't require additional `id` columns.

The table and column names we used were not arbitrary. By using CakePHP's [naming conventions](https://book.cakephp.org/intro/conventions.html)
, we can leverage CakePHP more effectively and avoid needing to configure the framework. While CakePHP is flexible enough to accommodate almost any database schema, adhering to the conventions will save you time as you can leverage the convention based defaults CakePHP provides.

Database Configuration [​](https://book.cakephp.org/3.x/quickstart.html#database-configuration)

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

Next, let's tell CakePHP where our database is and how to connect to it. Replace the values in the `Datasources.default` array in your **config/app\_local.php** file with those that apply to your setup. A sample completed configuration array might look something like the following:

    <?php
    return [\
        // More configuration above.\
        'Datasources' => [\
            'default' => [\
                'className' => 'Cake\Database\Connection',\
                'driver' => 'Cake\Database\Driver\Mysql',\
                'persistent' => false,\
                'host' => 'localhost',\
                'username' => 'cakephp',\
                'password' => 'AngelF00dC4k3~',\
                'database' => 'cake_cms',\
                'encoding' => 'utf8mb4',\
                'timezone' => 'UTC',\
                'cacheMetadata' => true,\
            ],\
        ],\
        // More configuration below.\
    ];

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  

Once you've saved your **config/app\_local.php** file, you should see that 'CakePHP is able to connect to the database' section have a green chef hat.

NOTE

A copy of CakePHP's default configuration file is found in **config/app.default.php**.

Creating our First Model [​](https://book.cakephp.org/3.x/quickstart.html#creating-our-first-model)

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

Models are the heart of a CakePHP applications. They enable us to read and modify our data. They allow us to build relations between our data, validate data, and apply application rules. Models build the foundations necessary to build our controller actions and templates.

CakePHP's models are composed of `Table` and `Entity` objects. `Table` objects provide access to the collection of entities stored in a specific table. They are stored in **src/Model/Table**. The file we'll be creating will be saved to **src/Model/Table/ArticlesTable.php**. The completed file should look like this:

    <?php
    // src/Model/Table/ArticlesTable.php
    namespace App\Model\Table;
    
    use Cake\ORM\Table;
    
    class ArticlesTable extends Table
    {
        public function initialize(array $config)
        {
            $this->addBehavior('Timestamp');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

We've attached the [Timestamp](https://book.cakephp.org/orm/behaviors/timestamp.html)
 behavior which will automatically populate the `created` and `modified` columns of our table. By naming our Table object `ArticlesTable`, CakePHP can use naming conventions to know that our model uses the `articles` table. CakePHP also uses conventions to know that the `id` column is our table's primary key.

NOTE

CakePHP will dynamically create a model object for you if it cannot find a corresponding file in **src/Model/Table**. This also means that if you accidentally name your file wrong (i.e. articlestable.php or ArticleTable.php), CakePHP will not recognize any of your settings and will use the generated model instead.

We'll also create an Entity class for our Articles. Entities represent a single record in the database, and provide row level behavior for our data. Our entity will be saved to **src/Model/Entity/Article.php**. The completed file should look like this:

    <?php
    // src/Model/Entity/Article.php
    namespace App\Model\Entity;
    
    use Cake\ORM\Entity;
    
    class Article extends Entity
    {
        protected $_accessible = [\
            '*' => true,\
            'id' => false,\
            'slug' => false,\
        ];
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

Our entity is quite slim right now, and we've only setup the `_accessible` property which controls how properties can be modified by [Entities Mass Assignment](https://book.cakephp.org/orm/entities.html#entities-mass-assignment)
.

We can't do much with our models right now, so next we'll create our first [Controller and Template](https://book.cakephp.org/tutorials-and-examples/cms/articles-controller.html)
 to allow us to interact with our model.

CMS Tutorial - Creating the Articles Controller [​](https://book.cakephp.org/3.x/quickstart.html#cms-tutorial-creating-the-articles-controller)

================================================================================================================================================

With our model created, we need a controller for our articles. Controllers in CakePHP handle HTTP requests and execute business logic contained in model methods, to prepare the response. We'll place this new controller in a file called **ArticlesController.php** inside the **src/Controller** directory. Here's what the basic controller should look like:

    <?php
    // src/Controller/ArticlesController.php
    
    namespace App\Controller;
    
    class ArticlesController extends AppController
    {
    }

1  
2  
3  
4  
5  
6  
7  
8  

Now, let's add an action to our controller. Actions are controller methods that have routes connected to them. For example, when a user requests **www.example.com/articles/index** (which is also the same as **www.example.com/articles**), CakePHP will call the `index` method of your `ArticlesController`. This method should query the model layer, and prepare a response by rendering a Template in the View. The code for that action would look like this:

    <?php
    // src/Controller/ArticlesController.php
    
    namespace App\Controller;
    
    class ArticlesController extends AppController
    {
        public function index()
        {
            $this->loadComponent('Paginator');
            $articles = $this->Paginator->paginate($this->Articles->find());
            $this->set(compact('articles'));
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

By defining function `index()` in our `ArticlesController`, users can now access the logic there by requesting **www.example.com/articles/index**. Similarly, if we were to define a function called `foobar()`, users would be able to access that at **www.example.com/articles/foobar**. You may be tempted to name your controllers and actions in a way that allows you to obtain specific URLs. Resist that temptation. Instead, follow the [CakePHP Conventions](https://book.cakephp.org/intro/conventions.html)
 creating readable, meaningful action names. You can then use [Routing](https://book.cakephp.org/development/routing.html)
 to connect the URLs you want to the actions you've created.

Our controller action is very simple. It fetches a paginated set of articles from the database, using the Articles Model that is automatically loaded via naming conventions. It then uses `set()` to pass the articles into the Template (which we'll create soon). CakePHP will automatically render the template after our controller action completes.

Create the Article List Template [​](https://book.cakephp.org/3.x/quickstart.html#create-the-article-list-template)

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

Now that we have our controller pulling data from the model, and preparing our view context, let's create a view template for our index action.

CakePHP view templates are presentation-flavored PHP code that is inserted inside the application's layout. While we'll be creating HTML here, Views can also generate JSON, CSV or even binary files like PDFs.

A layout is presentation code that is wrapped around a view. Layout files contain common site elements like headers, footers and navigation elements. Your application can have multiple layouts, and you can switch between them, but for now, let's just use the default layout.

CakePHP's template files are stored in **src/Template** inside a folder named after the controller they correspond to. So we'll have to create a folder named 'Articles' in this case. Add the following code to your application:

    <!-- File: src/Template/Articles/index.ctp -->
    
    <h1>Articles</h1>
    <table>
        <tr>
            <th>Title</th>
            <th>Created</th>
        </tr>
    
        <!-- Here is where we iterate through our $articles query object, printing out article info -->
    
        <?php foreach ($articles as $article): ?>
        <tr>
            <td>
                <?= $this->Html->link($article->title, ['action' => 'view', $article->slug]) ?>
            </td>
            <td>
                <?= $article->created->format(DATE_RFC850) ?>
            </td>
        </tr>
        <?php endforeach; ?>
    </table>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  

In the last section we assigned the 'articles' variable to the view using `set()`. Variables passed into the view are available in the view templates as local variables which we used in the above code.

You might have noticed the use of an object called `$this->Html`. This is an instance of the CakePHP [HtmlHelper](https://book.cakephp.org/views/helpers/html.html)
. CakePHP comes with a set of view helpers that make tasks like creating links, forms, and pagination buttons easy. You can learn more about [Helpers](https://book.cakephp.org/views/helpers.html)
 in their chapter, but what's important to note here is that the `link()` method will generate an HTML link with the given link text (the first parameter) and URL (the second parameter).

When specifying URLs in CakePHP, it is recommended that you use arrays or [named routes](https://book.cakephp.org/development/routing.html#named-routes)
. These syntaxes allow you to leverage the reverse routing features CakePHP offers.

At this point, you should be able to point your browser to **[http://localhost:8765/articles/index](http://localhost:8765/articles/index)
**. You should see your list view, correctly formatted with the title and table listing of the articles.

Create the View Action [​](https://book.cakephp.org/3.x/quickstart.html#create-the-view-action)

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

If you were to click one of the 'view' links in our Articles list page, you'd see an error page saying that action hasn't been implemented. Lets fix that now:

    // Add to existing src/Controller/ArticlesController.php file
    
    public function view($slug = null)
    {
        $article = $this->Articles->findBySlug($slug)->firstOrFail();
        $this->set(compact('article'));
    }

1  
2  
3  
4  
5  
6  
7  

While this is a simple action, we've used some powerful CakePHP features. We start our action off by using `findBySlug()` which is a [Dynamic Finder](https://book.cakephp.org/orm/retrieving-data-and-resultsets.html#dynamic-finders)
. This method allows us to create a basic query that finds articles by a given slug. We then use `firstOrFail()` to either fetch the first record, or throw a `NotFoundException`.

Our action takes a `$slug` parameter, but where does that parameter come from? If a user requests `/articles/view/first-post`, then the value 'first-post' is passed as `$slug` by CakePHP's routing and dispatching layers. If we reload our browser with our new action saved, we'd see another CakePHP error page telling us we're missing a view template; let's fix that.

Create the View Template [​](https://book.cakephp.org/3.x/quickstart.html#create-the-view-template)

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

Let's create the view for our new 'view' action and place it in **src/Template/Articles/view.ctp**

    <!-- File: src/Template/Articles/view.ctp -->
    
    <h1><?= h($article->title) ?></h1>
    <p><?= h($article->body) ?></p>
    <p><small>Created: <?= $article->created->format(DATE_RFC850) ?></small></p>
    <p><?= $this->Html->link('Edit', ['action' => 'edit', $article->slug]) ?></p>

1  
2  
3  
4  
5  
6  

You can verify that this is working by trying the links at `/articles/index` or manually requesting an article by accessing URLs like `/articles/view/first-post`.

Adding Articles [​](https://book.cakephp.org/3.x/quickstart.html#adding-articles)

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

With the basic read views created, we need to make it possible for new articles to be created. Start by creating an `add()` action in the `ArticlesController`. Our controller should now look like:

    // src/Controller/ArticlesController.php
    
    namespace App\Controller;
    
    use App\Controller\AppController;
    
    class ArticlesController extends AppController
    {
        public function initialize()
        {
            parent::initialize();
    
            $this->loadComponent('Paginator');
            $this->loadComponent('Flash'); // Include the FlashComponent
        }
    
        public function index()
        {
            $articles = $this->Paginator->paginate($this->Articles->find());
            $this->set(compact('articles'));
        }
    
        public function view($slug)
        {
            $article = $this->Articles->findBySlug($slug)->firstOrFail();
            $this->set(compact('article'));
        }
    
        public function add()
        {
            $article = $this->Articles->newEntity();
            if ($this->request->is('post')) {
                $article = $this->Articles->patchEntity($article, $this->request->getData());
    
                // Hardcoding the user_id is temporary, and will be removed later
                // when we build authentication out.
                $article->user_id = 1;
    
                if ($this->Articles->save($article)) {
                    $this->Flash->success(__('Your article has been saved.'));
                    return $this->redirect(['action' => 'index']);
                }
                $this->Flash->error(__('Unable to add your article.'));
            }
            $this->set('article', $article);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40  
41  
42  
43  
44  
45  
46  
47  

NOTE

You need to include the [Flash](https://book.cakephp.org/controllers/components/flash.html)
 component in any controller where you will use it. Often it makes sense to include it in your `AppController`.

Here's what the `add()` action does:

*   If the HTTP method of the request was POST, try to save the data using the Articles model.
*   If for some reason it doesn't save, just render the view. This gives us a chance to show the user validation errors or other warnings.

Every CakePHP request includes a request object which is accessible using `$this->request`. The request object contains information regarding the request that was just received. We use the `Cake\Http\ServerRequest::is()` method to check that the request is a HTTP POST request.

Our POST data is available in `$this->request->getData()`. You can use the `pr()` or `debug()` functions to print it out if you want to see what it looks like. To save our data, we first 'marshal' the POST data into an Article Entity. The Entity is then persisted using the ArticlesTable we created earlier.

After saving our new article we use FlashComponent's `success()` method to set a message into the session. The `success` method is provided using PHP's [magic method features](https://php.net/manual/en/language.oop5.overloading.php#object.call)
. Flash messages will be displayed on the next page after redirecting. In our layout we have `<?= $this->Flash->render() ?>` which displays flash messages and clears the corresponding session variable. Finally, after saving is complete, we use `Cake\Controller\Controller::redirect` to send the user back to the articles list. The param `['action' => 'index']` translates to URL `/articles` i.e the index action of the `ArticlesController`. You can refer to `Cake\Routing\Router::url()` function on the [API](https://api.cakephp.org/)
 to see the formats in which you can specify a URL for various CakePHP functions.

Create Add Template [​](https://book.cakephp.org/3.x/quickstart.html#create-add-template)

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

Here's our add view template:

    <!-- File: src/Template/Articles/add.ctp -->
    
    <h1>Add Article</h1>
    <?php
        echo $this->Form->create($article);
        // Hard code the user for now.
        echo $this->Form->control('user_id', ['type' => 'hidden', 'value' => 1]);
        echo $this->Form->control('title');
        echo $this->Form->control('body', ['rows' => '3']);
        echo $this->Form->button(__('Save Article'));
        echo $this->Form->end();
    ?>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

We use the FormHelper to generate the opening tag for an HTML form. Here's the HTML that `$this->Form->create()` generates:

    <form method="post" action="/articles/add">

1  

Because we called `create()` without a URL option, `FormHelper` assumes we want the form to submit back to the current action.

The `$this->Form->control()` method is used to create form elements of the same name. The first parameter tells CakePHP which field they correspond to, and the second parameter allows you to specify a wide array of options - in this case, the number of rows for the textarea. There's a bit of introspection and conventions used here. The `control()` will output different form elements based on the model field specified, and use inflection to generate the label text. You can customize the label, the input or any other aspect of the form controls using options. The `$this->Form->end()` call closes the form.

Now let's go back and update our **src/Template/Articles/index.ctp** view to include a new "Add Article" link. Before the `<table>`, add the following line:

    <?= $this->Html->link('Add Article', ['action' => 'add']) ?>

1  

Adding Simple Slug Generation [​](https://book.cakephp.org/3.x/quickstart.html#adding-simple-slug-generation)

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

If we were to save an Article right now, saving would fail as we are not creating a slug attribute, and the column is `NOT NULL`. Slug values are typically a URL-safe version of an article's title. We can use the [beforeSave() callback](https://book.cakephp.org/orm/table-objects.html#table-callbacks)
 of the ORM to populate our slug:

    // in src/Model/Table/ArticlesTable.php
    namespace App\Model\Table;
    
    use Cake\ORM\Table;
    // the Text class
    use Cake\Utility\Text;
    
    // Add the following method.
    
    public function beforeSave($event, $entity, $options)
    {
        if ($entity->isNew() && !$entity->slug) {
            $sluggedTitle = Text::slug($entity->title);
            // trim slug to maximum length defined in schema
            $entity->slug = substr($sluggedTitle, 0, 191);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

This code is simple, and doesn't take into account duplicate slugs. But we'll fix that later on.

Add Edit Action [​](https://book.cakephp.org/3.x/quickstart.html#add-edit-action)

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

Our application can now save articles, but we can't edit them. Lets rectify that now. Add the following action to your `ArticlesController`:

    // in src/Controller/ArticlesController.php
    
    // Add the following method.
    
    public function edit($slug)
    {
        $article = $this->Articles->findBySlug($slug)->firstOrFail();
        if ($this->request->is(['post', 'put'])) {
            $this->Articles->patchEntity($article, $this->request->getData());
            if ($this->Articles->save($article)) {
                $this->Flash->success(__('Your article has been updated.'));
                return $this->redirect(['action' => 'index']);
            }
            $this->Flash->error(__('Unable to update your article.'));
        }
    
        $this->set('article', $article);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

This action first ensures that the user has tried to access an existing record. If they haven't passed in an `$slug` parameter, or the article does not exist, a `NotFoundException` will be thrown, and the CakePHP ErrorHandler will render the appropriate error page.

Next the action checks whether the request is either a POST or a PUT request. If it is, then we use the POST/PUT data to update our article entity by using the `patchEntity()` method. Finally, we call `save()` set the appropriate flash message and either redirect or display validation errors.

Create Edit Template [​](https://book.cakephp.org/3.x/quickstart.html#create-edit-template)

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

The edit template should look like this:

    <!-- File: src/Template/Articles/edit.ctp -->
    
    <h1>Edit Article</h1>
    <?php
        echo $this->Form->create($article);
        echo $this->Form->control('user_id', ['type' => 'hidden']);
        echo $this->Form->control('title');
        echo $this->Form->control('body', ['rows' => '3']);
        echo $this->Form->button(__('Save Article'));
        echo $this->Form->end();
    ?>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

This template outputs the edit form (with the values populated), along with any necessary validation error messages.

You can now update your index view with links to edit specific articles:

    <!-- File: src/Template/Articles/index.ctp  (edit links added) -->
    
    <h1>Articles</h1>
    <p><?= $this->Html->link("Add Article", ['action' => 'add']) ?></p>
    <table>
        <tr>
            <th>Title</th>
            <th>Created</th>
            <th>Action</th>
        </tr>
    
    <!-- Here's where we iterate through our $articles query object, printing out article info -->
    
    <?php foreach ($articles as $article): ?>
        <tr>
            <td>
                <?= $this->Html->link($article->title, ['action' => 'view', $article->slug]) ?>
            </td>
            <td>
                <?= $article->created->format(DATE_RFC850) ?>
            </td>
            <td>
                <?= $this->Html->link('Edit', ['action' => 'edit', $article->slug]) ?>
            </td>
        </tr>
    <?php endforeach; ?>
    
    </table>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  

Update Validation Rules for Articles [​](https://book.cakephp.org/3.x/quickstart.html#update-validation-rules-for-articles)

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

Up until this point our Articles had no input validation done. Lets fix that by using [a validator](https://book.cakephp.org/orm/validation.html#validating-request-data)
:

    // src/Model/Table/ArticlesTable.php
    
    // add this use statement right below the namespace declaration to import
    // the Validator class
    use Cake\Validation\Validator;
    
    // Add the following method.
    public function validationDefault(Validator $validator)
    {
        $validator
            ->allowEmptyString('title', 'Title cannot be empty', false)
            ->minLength('title', 10)
            ->maxLength('title', 255);
    
        $validator
            ->allowEmptyString('body', 'Body cannot be empty', false)
            ->minLength('body', 10);
    
        return $validator;
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  

The `validationDefault()` method tells CakePHP how to validate your data when the `save()` method is called. Here, we've specified that both the title, and body fields must not be empty, and have certain length constraints.

CakePHP's validation engine is powerful and flexible. It provides a suite of frequently used rules for tasks like email addresses, IP addresses etc. and the flexibility for adding your own validation rules. For more information on that setup, check the [Validation](https://book.cakephp.org/core-libraries/validation.html)
 documentation.

Now that your validation rules are in place, use the app to try to add an article with an empty title or body to see how it works. Since we've used the `Cake\View\Helper\FormHelper::control()` method of the FormHelper to create our form elements, our validation error messages will be shown automatically.

Add Delete Action [​](https://book.cakephp.org/3.x/quickstart.html#add-delete-action)

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

Next, let's make a way for users to delete articles. Start with a `delete()` action in the `ArticlesController`:

    // src/Controller/ArticlesController.php
    
    public function delete($slug)
    {
        $this->request->allowMethod(['post', 'delete']);
    
        $article = $this->Articles->findBySlug($slug)->firstOrFail();
        if ($this->Articles->delete($article)) {
            $this->Flash->success(__('The {0} article has been deleted.', $article->title));
            return $this->redirect(['action' => 'index']);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

This logic deletes the article specified by `$slug`, and uses `$this->Flash->success()` to show the user a confirmation message after redirecting them to `/articles`. If the user attempts to delete an article using a GET request, `allowMethod()` will throw an exception. Uncaught exceptions are captured by CakePHP's exception handler, and a nice error page is displayed. There are many built-in [Exceptions](https://book.cakephp.org/development/errors.html)
 that can be used to indicate the various HTTP errors your application might need to generate.

WARNING

Allowing content to be deleted using GET requests is _very_ dangerous, as web crawlers could accidentally delete all your content. That is why we used `allowMethod()` in our controller.

Because we're only executing logic and redirecting to another action, this action has no template. You might want to update your index template with links that allow users to delete articles:

    <!-- File: src/Template/Articles/index.ctp  (delete links added) -->
    
    <h1>Articles</h1>
    <p><?= $this->Html->link("Add Article", ['action' => 'add']) ?></p>
    <table>
        <tr>
            <th>Title</th>
            <th>Created</th>
            <th>Action</th>
        </tr>
    
    <!-- Here's where we iterate through our $articles query object, printing out article info -->
    
    <?php foreach ($articles as $article): ?>
        <tr>
            <td>
                <?= $this->Html->link($article->title, ['action' => 'view', $article->slug]) ?>
            </td>
            <td>
                <?= $article->created->format(DATE_RFC850) ?>
            </td>
            <td>
                <?= $this->Html->link('Edit', ['action' => 'edit', $article->slug]) ?>
                <?= $this->Form->postLink(
                    'Delete',
                    ['action' => 'delete', $article->slug],
                    ['confirm' => 'Are you sure?'])
                ?>
            </td>
        </tr>
    <?php endforeach; ?>
    
    </table>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  

Using `Cake\View\Helper\FormHelper::postLink()` will create a link that uses JavaScript to do a POST request deleting our article.

NOTE

This view code also uses the `FormHelper` to prompt the user with a JavaScript confirmation dialog before they attempt to delete an article.

With a basic articles management setup, we'll create the [basic actions for our Tags and Users tables](https://book.cakephp.org/tutorials-and-examples/cms/tags-and-users.html)
.

---

# Form | CakePHP

[Skip to content](https://book.cakephp.org/3.x/views/helpers/form.html#VPContent)

Return to top

Form [​](https://book.cakephp.org/3.x/views/helpers/form.html#form)

====================================================================

`class` Cake\\View\\Helper\\**FormHelper**(View $view, array $config = \[\])

The FormHelper does most of the heavy lifting in form creation. The FormHelper focuses on creating forms quickly, in a way that will streamline validation, re-population and layout. The FormHelper is also flexible - it will do almost everything for you using conventions, or you can use specific methods to get only what you need.

Starting a Form [​](https://book.cakephp.org/3.x/views/helpers/form.html#starting-a-form)

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

`method` Cake\\View\\Helper\\FormHelper::**create**(mixed $context = null, array $options = \[\])

*   `$context` - The context for which the form is being defined. Can be an ORM entity, ORM resultset, array of metadata or `false/null` (to make a model-less form).
*   `$options` - An array of options and/or HTML attributes.

The first method you'll need to use in order to take advantage of the FormHelper is `create()`. This method outputs an opening form tag.

All parameters are optional. If `create()` is called with no parameters supplied, it assumes you are building a form that submits to the current controller, via the current URL. The default method for form submission is POST. If you were to call `create()` inside the view for `UsersController::add()`, you would see something like the following output in the rendered view:

    <form method="post" action="/users/add">

1  

The `$context` argument is used as the form's 'context'. There are several built-in form contexts and you can add your own, which we'll cover below, in a following section. The built-in providers map to the following values of `$context`:

*   An `Entity` instance or an iterator will map to [EntityContext](https://api.cakephp.org/3.x/class-Cake.View.Form.EntityContext.html)
    ; this context class allows FormHelper to work with results from the built-in ORM.
*   An array containing the `'schema'` key, will map to [ArrayContext](https://api.cakephp.org/3.x/class-Cake.View.Form.ArrayContext.html)
     which allows you to create simple data structures to build forms against.
*   `null` and `false` will map to [NullContext](https://api.cakephp.org/3.x/class-Cake.View.Form.NullContext.html)
    ; this context class simply satisfies the interface FormHelper requires. This context is useful if you want to build a short form that doesn't require ORM persistence.

All context classes also have access to the request data, making it simpler to build forms.

Once a form has been created with a context, all controls you create will use the active context. In the case of an ORM backed form, FormHelper can access associated data, validation errors and schema metadata. You can close the active context using the `end()` method, or by calling `create()` again.

To create a form for an entity, do the following:

    // If you are on /articles/add
    // $article should be an empty Article entity.
    echo $this->Form->create($article);

1  
2  
3  

Output:

    <form method="post" action="/articles/add">

1  

This will POST the form data to the `add()` action of ArticlesController. However, you can also use the same logic to create an edit form. The FormHelper uses the `Entity` object to automatically detect whether to create an _add_ or _edit_ form. If the provided entity is not 'new', the form will be created as an _edit_ form.

For example, if we browse to **[http://example.org/articles/edit/5](http://example.org/articles/edit/5)
**, we could do the following:

    // src/Controller/ArticlesController.php:
    public function edit($id = null)
    {
        if (empty($id)) {
            throw new NotFoundException;
        }
        $article = $this->Articles->get($id);
        // Save logic goes here
        $this->set('article', $article);
    }
    
    // View/Articles/edit.ctp:
    // Since $article->isNew() is false, we will get an edit form
    <?= $this->Form->create($article) ?>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

Output:

    <form method="post" action="/articles/edit/5">
    <input type="hidden" name="_method" value="PUT" />

1  
2  

NOTE

Since this is an _edit_ form, a hidden `input` field is generated to override the default HTTP method.

In some cases, the entity's ID is automatically appended to the end of the form's `action` URL. If you would like to _avoid_ an ID being added to the URL, you can pass a string to `$options['url']`, such as `'/my-account'` or `\Cake\Routing\Router::url(['controller' => 'Users', 'action' => 'myAccount'])`.

### Options for Form Creation [​](https://book.cakephp.org/3.x/views/helpers/form.html#options-for-form-creation)

The `$options` array is where most of the form configuration happens. This special array can contain a number of different key-value pairs that affect the way the form tag is generated. Valid values:

*   `'type'` - Allows you to choose the type of form to create. If no type is provided then it will be autodetected based on the form context. Valid values:
    *   `'get'` - Will set the form method to HTTP GET.
    *   `'file'` - Will set the form method to POST and the `'enctype'` to "multipart/form-data".
    *   `'post'` - Will set the method to POST.
    *   `'put', 'delete', 'patch'` - Will override the HTTP method with PUT, DELETE or PATCH respectively, when the form is submitted.
*   `'method'` - Valid values are the same as above. Allows you to explicitly override the form's method.
*   `'url'` - Specify the URL the form will submit to. Can be a string or a URL array.
*   `'encoding'` - Sets the `accept-charset` encoding for the form. Defaults to `Configure::read('App.encoding')`.
*   `'enctype'` - Allows you to set the form encoding explicitly.
*   `'templates'` - The templates you want to use for this form. Any templates provided will be merged on top of the already loaded templates. Can be either a filename (without extension) from `/config` or an array of templates to use.
*   `'context'` - Additional options for the form context class. (For example the `EntityContext` accepts a `'table'` option that allows you to set the specific Table class the form should be based on.)
*   `'idPrefix'` - Prefix for generated ID attributes.
*   `'templateVars'` - Allows you to provide template variables for the `formStart` template.
*   `autoSetCustomValidity` - Set to `true` to use custom required and notBlank validation messages in the control's HTML5 validity message. Default is `false`.

TIP

Besides the above options you can provide, in the `$options` argument, any valid HTML attributes that you want to pass to the created `form` element.

### Getting form values from the query string [​](https://book.cakephp.org/3.x/views/helpers/form.html#getting-form-values-from-the-query-string)

Added in version 3.4.0

A FormHelper's values sources define where its rendered elements, such as input-tags, receive their values from.

By default FormHelper draws its values from the 'context'. The default contexts, such as `EntityContext`, will fetch data from the current entity, or from `$request->getData()`.

If however, you are building a form that needs to read from the query string, you can use `valueSource()` to change where `FormHelper` reads data input data from:

    // Prioritize query string over context:
    echo $this->Form->create($article, [\
        'valueSources' => ['query', 'context']\
    ]);
    
    // Same effect:
    echo $this->Form
        ->setValueSources(['query', 'context'])
        ->create($articles);
    
    // Only read data from the query string
    echo $this->Form->create($article);
    $this->Form->setValueSources('query');
    
    // Same effect:
    echo $this->Form->create($article, ['valueSources' => 'query']);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  

The supported sources are `context`, `data` and `query`. You can use one or more sources. Any widgets generated by `FormHelper` will gather their values from the sources, in the order you setup.

The value sources will be reset to the default (`['context']`) when `end()` is called.

### Changing the HTTP Method for a Form [​](https://book.cakephp.org/3.x/views/helpers/form.html#changing-the-http-method-for-a-form)

By using the `type` option you can change the HTTP method a form will use:

    echo $this->Form->create($article, ['type' => 'get']);

1  

Output:

    <form method="get" action="/articles/edit/5">

1  

Specifying a `'file'` value for `type`, changes the form submission method to 'post', and includes an `enctype` of "multipart/form-data" on the form tag. This is to be used if there are any file elements inside the form. The absence of the proper `enctype` attribute will cause the file uploads not to function.

E.g. :

    echo $this->Form->create($article, ['type' => 'file']);

1  

Output:

    <form enctype="multipart/form-data" method="post" action="/articles/add">

1  

When using `'put'`, `'patch'` or `'delete'` as `'type'` values, your form will be functionally equivalent to a 'post' form, but when submitted, the HTTP request method will be overridden with 'PUT', 'PATCH' or 'DELETE', respectively. This allows CakePHP to emulate proper REST support in web browsers.

### Setting a URL for the Form [​](https://book.cakephp.org/3.x/views/helpers/form.html#setting-a-url-for-the-form)

Using the `'url'` option allows you to point the form to a specific action in your current controller or another controller in your application.

For example, if you'd like to point the form to the `publish()` action of the current controller, you would supply an `$options` array, like the following:

    echo $this->Form->create($article, ['url' => ['action' => 'publish']]);

1  

Output:

    <form method="post" action="/articles/publish">

1  

If the desired form action isn't in the current controller, you can specify a complete URL for the form action. The supplied URL can be relative to your CakePHP application:

    echo $this->Form->create(null, [\
        'url' => [\
            'controller' => 'Articles',\
            'action' => 'publish'\
        ]\
    ]);

1  
2  
3  
4  
5  
6  

Output:

    <form method="post" action="/articles/publish">

1  

Or you can point to an external domain:

    echo $this->Form->create(null, [\
        'url' => 'https://www.google.com/search',\
        'type' => 'get'\
    ]);

1  
2  
3  
4  

Output:

    <form method="get" action="https://www.google.com/search">

1  

Use `'url' => false` if you don't want to output a URL as the form action.

### Using Custom Validators [​](https://book.cakephp.org/3.x/views/helpers/form.html#using-custom-validators)

Often models will have multiple validation sets, and you will want FormHelper to mark fields required based on a the specific validation rules your controller action is going to apply. For example, your Users table has specific validation rules that only apply when an account is being registered:

    echo $this->Form->create($user, [\
        'context' => ['validator' => 'register']\
    ]);

1  
2  
3  

The above will use the rules defined in the `register` validator, which are defined by `UsersTable::validationRegister()`, for `$user` and all related associations. If you are creating a form for associated entities, you can define validation rules for each association by using an array:

    echo $this->Form->create($user, [\
        'context' => [\
            'validator' => [\
                'Users' => 'register',\
                'Comments' => 'default'\
            ]\
        ]\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  

The above would use `register` for the user, and `default` for the user's comments.

### Creating context classes [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-context-classes)

While the built-in context classes are intended to cover the basic cases you'll encounter you may need to build a new context class if you are using a different ORM. In these situations you need to implement the [Cake\\View\\Form\\ContextInterface](https://api.cakephp.org/3.x/class-Cake.View.Form.ContextInterface.html)
 . Once you have implemented this interface you can wire your new context into the FormHelper. It is often best to do this in a `View.beforeRender` event listener, or in an application view class:

    $this->Form->addContextProvider('myprovider', function ($request, $data) {
        if ($data['entity'] instanceof MyOrmClass) {
            return new MyProvider($request, $data);
        }
    });

1  
2  
3  
4  
5  

Context factory functions are where you can add logic for checking the form options for the correct type of entity. If matching input data is found you can return an object. If there is no match return null.

Creating Form Controls [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-form-controls)

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

`method` Cake\\View\\Helper\\FormHelper::**control**(string $fieldName, array $options = \[\])

*   `$fieldName` - A field name in the form `'Modelname.fieldname'`.
*   `$options` - An optional array that can include both [Control Specific Options](https://book.cakephp.org/3.x/views/helpers/form.html#control-specific-options)
    , and options of the other methods (which `control()` employs internally to generate various HTML elements) as well as any valid HTML attributes.

The `control()` method lets you to generate complete form controls. These controls will include a wrapping `div`, `label`, control widget, and validation error if necessary. By using the metadata in the form context, this method will choose an appropriate control type for each field. Internally `control()` uses the other methods of FormHelper.

TIP

Please note that while the fields generated by the `control()` method are called generically "inputs" on this page, technically speaking, the `control()` method can generate not only all of the HTML `input` type elements, but also other HTML form elements (e.g. `select`, `button`, `textarea`).

By default the `control()` method will employ the following widget templates:

    'inputContainer' => '<div class="input {{type}}{{required}}">{{content}}</div>'
    'input' => '<input type="{{type}}" name="{{name}}"{{attrs}}/>'

1  
2  

In case of validation errors it will also use:

    'inputContainerError' => '<div class="input {{type}}{{required}} error">{{content}}{{error}}</div>'

1  

The type of control created (when we provide no additional options to specify the generated element type) is inferred via model introspection and depends on the column datatype:

Column Type  
Resulting Form Field

string, uuid (char, varchar, etc.)  
text

boolean, tinyint(1)  
checkbox

decimal  
number

float  
number

integer  
number

text  
textarea

text, with name of password, passwd  
password

text, with name of email  
email

text, with name of tel, telephone, or phone  
tel

date  
day, month, and year selects

datetime, timestamp  
day, month, year, hour, minute, and meridian selects

time  
hour, minute, and meridian selects

binary  
file

The `$options` parameter allows you to choose a specific control type if you need to:

    echo $this->Form->control('published', ['type' => 'checkbox']);

1  

TIP

As a small subtlety, generating specific elements via the `control()` form method will always also generate the wrapping `div`, by default. Generating the same type of element via one of the specific form methods (e.g. `$this->Form->checkbox('published');`) in most cases won't generate the wrapping `div`. Depending on your needs you can use one or another.

The wrapping `div` will have a `required` class name appended if the validation rules for the model's field indicate that it is required and not allowed to be empty. You can disable automatic `required` flagging using the `'required'` option:

    echo $this->Form->control('title', ['required' => false]);

1  

To skip browser validation triggering for the whole form you can set option `'formnovalidate' => true` for the input button you generate using `Cake\View\Helper\FormHelper::submit()` or set `'novalidate' => true` in options for `Cake\View\Helper\FormHelper::create()`.

For example, let's assume that your Users model includes fields for a _username_ (varchar), _password_ (varchar), _approved_ (datetime) and _quote_ (text). You can use the `control()` method of the FormHelper to create appropriate controls for all of these form fields:

    echo $this->Form->create($user);
    // The following generates a Text input
    echo $this->Form->control('username');
    // The following generates a Password input
    echo $this->Form->control('password');
    // Assuming 'approved' is a datetime or timestamp field the following
    //generates: Day, Month, Year, Hour, Minute
    echo $this->Form->control('approved');
    // The following generates a Textarea element
    echo $this->Form->control('quote');
    
    echo $this->Form->button('Add');
    echo $this->Form->end();

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

A more extensive example showing some options for a date field:

    echo $this->Form->control('birth_dt', [\
        'label' => 'Date of birth',\
        'minYear' => date('Y') - 70,\
        'maxYear' => date('Y') - 18,\
    ]);

1  
2  
3  
4  
5  

Besides the specific [Control Specific Options](https://book.cakephp.org/3.x/views/helpers/form.html#control-specific-options)
, you also can specify any option accepted by corresponding specific method for the chosen (or inferred by CakePHP) control type and any HTML attribute (for instance `onfocus`).

If you want to create a `select` form field while using a _belongsTo_ (or _hasOne_) relation, you can add the following to your UsersController (assuming your User _belongsTo_ Group):

    $this->set('groups', $this->Users->Groups->find('list'));

1  

Afterwards, add the following to your view template:

    echo $this->Form->control('group_id', ['options' => $groups]);

1  

To make a `select` box for a _belongsToMany_ Groups association you can add the following to your UsersController:

    $this->set('groups', $this->Users->Groups->find('list'));

1  

Afterwards, add the following to your view template:

    echo $this->Form->control('groups._ids', ['options' => $groups]);

1  

If your model name consists of two or more words (e.g. "UserGroups"), when passing the data using `set()` you should name your data in a pluralised and [lower camelCased](https://en.wikipedia.org/wiki/Camel_case#Variations_and_synonyms)
 format as follows:

    $this->set('userGroups', $this->UserGroups->find('list'));

1  

NOTE

You should not use `FormHelper::control()` to generate submit buttons. Use `Cake\View\Helper\FormHelper::submit()` instead.

### Field Naming Conventions [​](https://book.cakephp.org/3.x/views/helpers/form.html#field-naming-conventions)

When creating control widgets you should name your fields after the matching attributes in the form's entity. For example, if you created a form for an `$article` entity, you would create fields named after the properties. E.g. `title`, `body` and `published`.

You can create controls for associated models, or arbitrary models by passing in `association.fieldname` as the first parameter:

    echo $this->Form->control('association.fieldname');

1  

Any dots in your field names will be converted into nested request data. For example, if you created a field with a name `0.comments.body` you would get a name attribute that looks like `0[comments][body]`. This convention makes it easy to save data with the ORM. Details for the various association types can be found in the [Associated Form Inputs](https://book.cakephp.org/3.x/views/helpers/form.html#associated-form-inputs)
 section.

When creating datetime related controls, FormHelper will append a field-suffix. You may notice additional fields named `year`, `month`, `day`, `hour`, `minute`, or `meridian` being added. These fields will be automatically converted into `DateTime` objects when entities are marshalled.

### Options for Control [​](https://book.cakephp.org/3.x/views/helpers/form.html#options-for-control)

`FormHelper::control()` supports a large number of options via its `$options` argument. In addition to its own options, `control()` accepts options for the inferred/chosen generated control types (e.g. for `checkbox` or `textarea`), as well as HTML attributes. This subsection will cover the options specific to `FormHelper::control()`.

*   `$options['type']` - A string that specifies the widget type to be generated. In addition to the field types found in the [Automagic Form Elements](https://book.cakephp.org/3.x/views/helpers/form.html#automagic-form-elements)
    , you can also create `'file'`, `'password'`, and any other type supported by HTML5. By specifying a `'type'` you will force the type of the generated control, overriding model introspection. Defaults to `null`.
    
    E.g. :
    
        echo $this->Form->control('field', ['type' => 'file']);
        echo $this->Form->control('email', ['type' => 'email']);
    
    1  
    2  
    
    Output:
    
        <div class="input file">
            <label for="field">Field</label>
            <input type="file" name="field" value="" id="field" />
        </div>
        <div class="input email">
            <label for="email">Email</label>
            <input type="email" name="email" value="" id="email" />
        </div>
    
    1  
    2  
    3  
    4  
    5  
    6  
    7  
    8  
    
*   `$options['label']` - Either a string caption or an array of [options for the label](https://book.cakephp.org/3.x/views/helpers/form.html#create-label)
    . You can set this key to the string you would like to be displayed within the label that usually accompanies the `input` HTML element. Defaults to `null`.
    
    E.g. :
    
        echo $this->Form->control('name', [\
            'label' => 'The User Alias'\
        ]);
    
    1  
    2  
    3  
    
    Output:
    
        <div class="input">
            <label for="name">The User Alias</label>
            <input name="name" type="text" value="" id="name" />
        </div>
    
    1  
    2  
    3  
    4  
    
    Alternatively, set this key to `false` to disable the generation of the `label` element.
    
    E.g. :
    
        echo $this->Form->control('name', ['label' => false]);
    
    1  
    
    Output:
    
        <div class="input">
            <input name="name" type="text" value="" id="name" />
        </div>
    
    1  
    2  
    3  
    
    Set this to an array to provide additional options for the `label` element. If you do this, you can use a `'text'` key in the array to customize the label text.
    
    E.g. :
    
        echo $this->Form->control('name', [\
            'label' => [\
                'class' => 'thingy',\
                'text' => 'The User Alias'\
            ]\
        ]);
    
    1  
    2  
    3  
    4  
    5  
    6  
    
    Output:
    
        <div class="input">
            <label for="name" class="thingy">The User Alias</label>
            <input name="name" type="text" value="" id="name" />
        </div>
    
    1  
    2  
    3  
    4  
    
*   `$options['options']` - You can provide in here an array containing the elements to be generated for widgets such as `radio` or `select`, which require an array of items as an argument (see [Create Radio Button](https://book.cakephp.org/3.x/views/helpers/form.html#create-radio-button)
     and [Create Select Picker](https://book.cakephp.org/3.x/views/helpers/form.html#create-select-picker)
     for more details). Defaults to `null`.
    
*   `$options['error']` - Using this key allows you to override the default model error messages and can be used, for example, to set i18n messages. To disable the error message output & field classes set the `'error'` key to `false`. Defaults to `null`.
    
    E.g. :
    
        echo $this->Form->control('name', ['error' => false]);
    
    1  
    
    To override the model error messages use an array with the keys matching the original validation error messages.
    
    E.g. :
    
        $this->Form->control('name', [\
            'error' => ['Not long enough' => __('This is not long enough')]\
        ]);
    
    1  
    2  
    3  
    
    As seen above you can set the error message for each validation rule you have in your models. In addition you can provide i18n messages for your forms.
    
    To disable the HTML entity encoding for error messages only, the `'escape'` sub key can be used:
    
        $this->Form->control('name', [\
            'error' => ['escape' => false],\
        ]);
    
    1  
    2  
    3  
    
*   `$options['nestedInput']` - Used with checkboxes and radio buttons. Controls whether the input element is generated inside or outside the `label` element. When `control()` generates a checkbox or a radio button, you can set this to `false` to force the generation of the HTML `input` element outside of the `label` element.
    
    On the other hand you can set this to `true` for any control type to force the generated input element inside the label. If you change this for radio buttons then you need to also modify the default [radioWrapper](https://book.cakephp.org/3.x/views/helpers/form.html#create-radio-button)
     template. Depending on the generated control type it defaults to `true` or `false`.
    
*   `$options['templates']` - The templates you want to use for this input. Any specified templates will be merged on top of the already loaded templates. This option can be either a filename (without extension) in `/config` that contains the templates you want to load, or an array of templates to use.
    
*   `$options['labelOptions']` - Set this to `false` to disable labels around nestedWidgets or set it to an array of attributes to be provided to the `label` tag.
    

Generating Specific Types of Controls [​](https://book.cakephp.org/3.x/views/helpers/form.html#generating-specific-types-of-controls)

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

In addition to the generic `control()` method, `FormHelper` has specific methods for generating a number of different types of controls. These can be used to generate just the control widget itself, and combined with other methods like `Cake\View\Helper\FormHelper::label()` and `Cake\View\Helper\FormHelper::error()` to generate fully custom form layouts.

### Common Options For Specific Controls [​](https://book.cakephp.org/3.x/views/helpers/form.html#common-options-for-specific-controls)

Many of the various control element methods support a common set of options which, depending on the form method used, must be provided inside the `$options` or in the `$attributes` array argument. All of these options are also supported by the `control()` method. To reduce repetition, the common options shared by all control methods are as follows:

*   `'id'` - Set this key to force the value of the DOM id for the control. This will override the `'idPrefix'` that may be set.
    
*   `'default'` - Used to set a default value for the control field. The value is used if the data passed to the form does not contain a value for the field (or if no data is passed at all). An explicit default value will override any default values defined in the schema.
    
    Example usage:
    
        echo $this->Form->text('ingredient', ['default' => 'Sugar']);
    
    1  
    
    Example with `select` field (size "Medium" will be selected as default):
    
        $sizes = ['s' => 'Small', 'm' => 'Medium', 'l' => 'Large'];
        echo $this->Form->select('size', $sizes, ['default' => 'm']);
    
    1  
    2  
    
    NOTE
    
    You cannot use `default` to check a checkbox - instead you might set the value in `$this->request->getData()` in your controller, or set the control option `'checked'` to `true`.
    
    Beware of using `false` to assign a default value. A `false` value is used to disable/exclude options of a control field, so `'default' => false` would not set any value at all. Instead use `'default' => 0`.
    
*   `'value'` - Used to set a specific value for the control field. This will override any value that may else be injected from the context, such as Form, Entity or `request->getData()` etc.
    
    NOTE
    
    If you want to set a field to not render its value fetched from context or valuesSource you will need to set `'value'` to `''` (instead of setting it to `null`).
    

In addition to the above options, you can mixin any HTML attribute you wish to use. Any non-special option name will be treated as an HTML attribute, and applied to the generated HTML control element.

Changed in version 3.3.0

As of 3.3.0, FormHelper will automatically use any default values defined in your database schema. You can disable this behavior by setting the `schemaDefault` option to `false`.

Creating Input Elements [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-input-elements)

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

The rest of the methods available in the FormHelper are for creating specific form elements. Many of these methods also make use of a special `$options` or `$attributes` parameter. In this case, however, this parameter is used primarily to specify HTML tag attributes (such as the value or DOM id of an element in the form).

### Creating Text Inputs [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-text-inputs)

`method` Cake\\View\\Helper\\FormHelper::**text**(string $name, array $options)

*   `$name` - A field name in the form `'Modelname.fieldname'`.
*   `$options` - An optional array including any of the [General Control Options](https://book.cakephp.org/3.x/views/helpers/form.html#general-control-options)
     as well as any valid HTML attributes.

Creates a simple `input` HTML element of `text` type.

E.g. :

    echo $this->Form->text('username', ['class' => 'users']);

1  

Will output:

    <input name="username" type="text" class="users">

1  

### Creating Password Inputs [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-password-inputs)

`method` Cake\\View\\Helper\\FormHelper::**password**(string $fieldName, array $options)

*   `$fieldName` - A field name in the form `'Modelname.fieldname'`.
*   `$options` - An optional array including any of the [General Control Options](https://book.cakephp.org/3.x/views/helpers/form.html#general-control-options)
     as well as any valid HTML attributes.

Creates a simple `input` element of `password` type.

E.g. :

    echo $this->Form->password('password');

1  

Will output:

    <input name="password" value="" type="password">

1  

### Creating Hidden Inputs [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-hidden-inputs)

`method` Cake\\View\\Helper\\FormHelper::**hidden**(string $fieldName, array $options)

*   `$fieldName` - A field name in the form `'Modelname.fieldname'`.
*   `$options` - An optional array including any of the [General Control Options](https://book.cakephp.org/3.x/views/helpers/form.html#general-control-options)
     as well as any valid HTML attributes.

Creates a hidden form input.

E.g. :

    echo $this->Form->hidden('id');

1  

Will output:

    <input name="id" type="hidden" />

1  

### Creating Textareas [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-textareas)

`method` Cake\\View\\Helper\\FormHelper::**textarea**(string $fieldName, array $options)

*   `$fieldName` - A field name in the form `'Modelname.fieldname'`.
*   `$options` - An optional array including any of the [General Control Options](https://book.cakephp.org/3.x/views/helpers/form.html#general-control-options)
    , of the specific textarea options (see below) as well as any valid HTML attributes.

Creates a textarea control field. The default widget template used is:

    'textarea' => '<textarea name="{{name}}"{{attrs}}>{{value}}</textarea>'

1  

For example:

    echo $this->Form->textarea('notes');

1  

Will output:

    <textarea name="notes"></textarea>

1  

If the form is being edited (i.e. the array `$this->request->getData()` contains the information previously saved for the `User` entity), the value corresponding to `notes` field will automatically be added to the HTML generated.

Example:

    <textarea name="notes" id="notes">
        This text is to be edited.
    </textarea>

1  
2  
3  

**Options for Textarea**

In addition to the [General Control Options](https://book.cakephp.org/3.x/views/helpers/form.html#general-control-options)
, `textarea()` supports a couple of specific options:

*   `'escape'` - Determines whether or not the contents of the textarea should be escaped. Defaults to `true`.
    
    E.g. :
    
        echo $this->Form->textarea('notes', ['escape' => false]);
        // OR....
        echo $this->Form->control('notes', ['type' => 'textarea', 'escape' => false]);
    
    1  
    2  
    3  
    
*   `'rows', 'cols'` - You can use these two keys to set the HTML attributes which specify the number of rows and columns for the `textarea` field.
    
    E.g. :
    
        echo $this->Form->textarea('comment', ['rows' => '5', 'cols' => '5']);
    
    1  
    
    Output:
    
        <textarea name="comment" cols="5" rows="5">
        </textarea>
    
    1  
    2  
    

### Creating Select, Checkbox and Radio Controls [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-select-checkbox-and-radio-controls)

These controls share some commonalities and a few options and thus, they are all grouped in this subsection for easier reference.

#### Options for Select, Checkbox and Radio Controls [​](https://book.cakephp.org/3.x/views/helpers/form.html#options-for-select-checkbox-and-radio-controls)

You can find below the options which are shared by `select()`, `checkbox()` and `radio()` (the options particular only to one of the methods are described in each method's own section.)

*   `'value'` - Sets or selects the value of the affected element(s):
    
    *   For checkboxes, it sets the HTML `'value'` attribute assigned to the `input` element to whatever you provide as value.
        
    *   For radio buttons or select pickers it defines which element will be selected when the form is rendered (in this case `'value'` must be assigned a valid, existent element value). May also be used in combination with any select-type control, such as `date()`, `time()`, `dateTime()`:
        
            echo $this->Form->time('close_time', [\
                'value' => '13:30:00'\
            ]);
        
        1  
        2  
        3  
        
    
    NOTE
    
    The `'value'` key for `date()` and `dateTime()` controls may also have as value a UNIX timestamp, or a DateTime object.
    
    For a `select` control where you set the `'multiple'` attribute to `true`, you can provide an array with the values you want to select by default:
    
        // HTML <option> elements with values 1 and 3 will be rendered preselected
        echo $this->Form->select(
            'rooms',
            [1, 2, 3, 4, 5],
            [\
                'multiple' => true,\
                'value' => [1, 3]\
            ]
        );
    
    1  
    2  
    3  
    4  
    5  
    6  
    7  
    8  
    9  
    
*   `'empty'` - Applies to `radio()` and `select()`. Defaults to `false`.
    
    *   When passed to `radio()` and set to `true` it will create an extra input element as the first radio button, with a value of `''` and a label caption equal to the string `'empty'`. If you want to control the label caption set this option to a string instead.
        
    *   When passed to a `select` method, this creates a blank HTML `option` element with an empty value in your drop down list. If you want to have an empty value with text displayed instead of just a blank `option`, pass a string to `'empty'`:
        
            echo $this->Form->select(
                'field',
                [1, 2, 3, 4, 5],
                ['empty' => '(choose one)']
            );
        
        1  
        2  
        3  
        4  
        5  
        
        Output:
        
            <select name="field">
                <option value="">(choose one)</option>
                <option value="0">1</option>
                <option value="1">2</option>
                <option value="2">3</option>
                <option value="3">4</option>
                <option value="4">5</option>
            </select>
        
        1  
        2  
        3  
        4  
        5  
        6  
        7  
        8  
        
*   `'hiddenField'` - For checkboxes and radio buttons, by default, a hidden `input` element is also created, along with the main element, so that the key in `$this->request->getData()` will exist even without a value specified. For checkboxes its value defaults to `0` and for radio buttons to `''`.
    
    Example of default output:
    
        <input type="hidden" name="published" value="0" />
        <input type="checkbox" name="published" value="1" />
    
    1  
    2  
    
    This can be disabled by setting `'hiddenField'` to `false`:
    
        echo $this->Form->checkbox('published', ['hiddenField' => false]);
    
    1  
    
    Which outputs:
    
        <input type="checkbox" name="published" value="1">
    
    1  
    
    If you want to create multiple blocks of controls on a form, that are all grouped together, you should set this parameter to `false` on all controls except the first. If the hidden input is on the page in multiple places, only the last group of `inputs`' values will be saved.
    
    In this example, only the tertiary colors would be passed, and the primary colors would be overridden:
    
        <h2>Primary Colors</h2>
        <input type="hidden" name="color" value="0" />
        <label for="color-red">
            <input type="checkbox" name="color[]" value="5" id="color-red" />
            Red
        </label>
        
        <label for="color-blue">
            <input type="checkbox" name="color[]" value="5" id="color-blue" />
            Blue
        </label>
        
        <label for="color-yellow">
            <input type="checkbox" name="color[]" value="5" id="color-yellow" />
            Yellow
        </label>
        
        <h2>Tertiary Colors</h2>
        <input type="hidden" name="color" value="0" />
        <label for="color-green">
            <input type="checkbox" name="color[]" value="5" id="color-green" />
            Green
        </label>
        <label for="color-purple">
            <input type="checkbox" name="color[]" value="5" id="color-purple" />
            Purple
        </label>
        <label for="color-orange">
            <input type="checkbox" name="color[]" value="5" id="color-orange" />
            Orange
        </label>
    
    1  
    2  
    3  
    4  
    5  
    6  
    7  
    8  
    9  
    10  
    11  
    12  
    13  
    14  
    15  
    16  
    17  
    18  
    19  
    20  
    21  
    22  
    23  
    24  
    25  
    26  
    27  
    28  
    29  
    30  
    31  
    
    Disabling `'hiddenField'` on the second control group would prevent this behavior.
    
    You can set a hidden field to a value other than 0, such as 'N':
    
        echo $this->Form->checkbox('published', [\
            'value' => 'Y',\
            'hiddenField' => 'N',\
        ]);
    
    1  
    2  
    3  
    4  
    

#### Using Collections to build options [​](https://book.cakephp.org/3.x/views/helpers/form.html#using-collections-to-build-options)

It's possible to use the Collection class to build your options array. This approach is ideal if you already have a collection of entities and would like to build a select element from them.

You can use the `combine` method to build a basic options array.:

    $options = $examples->combine('id', 'name');

1  

It's also possible to add extra attributes by expanding the array. The following will create a data attribute on the option element, using the `map` collection method.:

    $options = $examples->map(function ($value, $key) {
        return [\
            'value' => $value->id,\
            'text' => $value->name,\
            'data-created' => $value->created\
        ];
    });

1  
2  
3  
4  
5  
6  
7  

#### Creating Checkboxes [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-checkboxes)

`method` Cake\\View\\Helper\\FormHelper::**checkbox**(string $fieldName, array $options)

*   `$fieldName` - A field name in the form `'Modelname.fieldname'`.
*   `$options` - An optional array including any of the [General Control Options](https://book.cakephp.org/3.x/views/helpers/form.html#general-control-options)
    , or of the [Checkbox Radio Select Options](https://book.cakephp.org/3.x/views/helpers/form.html#checkbox-radio-select-options)
     above, of the checkbox-specific options (see below), as well as any valid HTML attributes.

Creates a `checkbox` form element. The widget template used is:

    'checkbox' => '<input type="checkbox" name="{{name}}" value="{{value}}"{{attrs}}>'

1  

**Options for Checkboxes**

*   `'checked'` - Boolean to indicate whether this checkbox will be checked. Defaults to `false`.
*   `'disabled'` - Create a disabled checkbox input.

This method also generates an associated hidden form `input` element to force the submission of data for the specified field.

E.g. :

    echo $this->Form->checkbox('done');

1  

Will output:

    <input type="hidden" name="done" value="0">
    <input type="checkbox" name="done" value="1">

1  
2  

It is possible to specify the value of the checkbox by using the `$options` array.

E.g. :

    echo $this->Form->checkbox('done', ['value' => 555]);

1  

Will output:

    <input type="hidden" name="done" value="0">
    <input type="checkbox" name="done" value="555">

1  
2  

If you don't want the FormHelper to create a hidden input use `'hiddenField'`.

E.g. :

    echo $this->Form->checkbox('done', ['hiddenField' => false]);

1  

Will output:

    <input type="checkbox" name="done" value="1">

1  

#### Creating Radio Buttons [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-radio-buttons)

`method` Cake\\View\\Helper\\FormHelper::**radio**(string $fieldName, array $options, array $attributes)

*   `$fieldName` - A field name in the form `'Modelname.fieldname'`.
*   `$options` - An optional array containing at minimum the labels for the radio buttons. Can also contain values and HTML attributes. When this array is missing, the method will either generate only the hidden input (if `'hiddenField'` is `true`) or no element at all (if `'hiddenField'` is `false`).
*   `$attributes` - An optional array including any of the [General Control Options](https://book.cakephp.org/3.x/views/helpers/form.html#general-control-options)
    , or of the [Checkbox Radio Select Options](https://book.cakephp.org/3.x/views/helpers/form.html#checkbox-radio-select-options)
    , of the radio button specific attributes (see below), as well as any valid HTML attributes.

Creates a set of radio button inputs. The default widget templates used are:

    'radio' => '<input type="radio" name="{{name}}" value="{{value}}"{{attrs}}>'
    'radioWrapper' => '{{label}}'

1  
2  

**Attributes for Radio Buttons**

*   `'label'` - Boolean to indicate whether or not labels for widgets should be displayed, or an array of attributes to apply to all labels. In case a `class` attribute is defined, `selected` will be added to the `class` attribute of checked buttons. Defaults to `true`.
*   `'hiddenField'` - If set to `true` a hidden input with a value of `''` will be included. This is useful for creating radio sets that are non-continuous. Defaults to `true`.
*   `'disabled'` - Set to `true` or `'disabled'` to disable all the radio buttons. Defaults to `false`.

You must provide the label captions for the radio buttons via the `$options` argument.

For example:

    $this->Form->radio('gender', ['Masculine', 'Feminine', 'Neuter']);

1  

Will output:

    <input name="gender" value="" type="hidden">
    <label for="gender-0">
        <input name="gender" value="0" id="gender-0" type="radio">
        Masculine
    </label>
    <label for="gender-1">
        <input name="gender" value="1" id="gender-1" type="radio">
        Feminine
    </label>
    <label for="gender-2">
        <input name="gender" value="2" id="gender-2" type="radio">
        Neuter
    </label>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

Generally `$options` contains simple `key => value` pairs. However, if you need to put custom attributes on your radio buttons you can use an expanded format.

E.g. :

    echo $this->Form->radio(
        'favorite_color',
        [\
            ['value' => 'r', 'text' => 'Red', 'style' => 'color:red;'],\
            ['value' => 'u', 'text' => 'Blue', 'style' => 'color:blue;'],\
            ['value' => 'g', 'text' => 'Green', 'style' => 'color:green;'],\
        ]
    );

1  
2  
3  
4  
5  
6  
7  
8  

Will output:

    <input type="hidden" name="favorite_color" value="">
    <label for="favorite-color-r">
        <input type="radio" name="favorite_color" value="r" style="color:red;" id="favorite-color-r">
        Red
    </label>
    <label for="favorite-color-u">
        <input type="radio" name="favorite_color" value="u" style="color:blue;" id="favorite-color-u">
        Blue
    </label>
    <label for="favorite-color-g">
        <input type="radio" name="favorite_color" value="g" style="color:green;" id="favorite-color-g">
        Green
    </label>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

You can define additional attributes for an individual option's label as well:

    echo $this->Form->radio(
        'favorite_color',
        [\
            ['value' => 'r', 'text' => 'Red', 'label' => ['class' => 'red']],\
            ['value' => 'u', 'text' => 'Blue', 'label' => ['class' => 'blue']],\
        ]
    );

1  
2  
3  
4  
5  
6  
7  

Will output:

    <input type="hidden" name="favorite_color" value="">
    <label for="favorite-color-r" class="red">
        <input type="radio" name="favorite_color" value="r" style="color:red;" id="favorite-color-r">
        Red
    </label>
    <label for="favorite-color-u" class="blue">
        <input type="radio" name="favorite_color" value="u" style="color:blue;" id="favorite-color-u">
        Blue
    </label>

1  
2  
3  
4  
5  
6  
7  
8  
9  

If the `label` key is used on an option, the attributes in `$attributes['label']` will be ignored.

Changed in version 3.8.0

The `label` key in complex options was added.

#### Creating Select Pickers [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-select-pickers)

`method` Cake\\View\\Helper\\FormHelper::**select**(string $fieldName, array $options, array $attributes)

*   `$fieldName` - A field name in the form `'Modelname.fieldname'`. This will provide the `name` attribute of the `select` element.
*   `$options` - An optional array containing the list of items for the select picker. When this array is missing, the method will generate only the empty `select` HTML element without any `option` elements inside it.
*   `$attributes` - An optional array including any of the [General Control Options](https://book.cakephp.org/3.x/views/helpers/form.html#general-control-options)
    , or of the [Checkbox Radio Select Options](https://book.cakephp.org/3.x/views/helpers/form.html#checkbox-radio-select-options)
    , or of the select-specific attributes (see below), as well as any valid HTML attributes.

Creates a `select` element, populated with the items from the `$options` array. If `$attributes['value']` is provided, then the HTML `option` element(s) which have the specified value(s) will be shown as selected when rendering the select picker.

By default `select` uses the following widget templates:

    'select' => '<select name="{{name}}"{{attrs}}>{{content}}</select>'
    'option' => '<option value="{{value}}"{{attrs}}>{{text}}</option>'

1  
2  

May also use:

    'optgroup' => '<optgroup label="{{label}}"{{attrs}}>{{content}}</optgroup>'
    'selectMultiple' => '<select name="{{name}}[]" multiple="multiple"{{attrs}}>{{content}}</select>'

1  
2  

**Attributes for Select Pickers**

*   `'multiple'` - If set to `true` allows multiple selections in the select picker. If set to `'checkbox'`, multiple checkboxes will be created instead. Defaults to `null`.
*   `'escape'` - Boolean. If `true` the contents of the `option` elements inside the select picker will be HTML entity encoded. Defaults to `true`.
*   `'val'` - Allows preselecting a value in the select picker.
*   `'disabled'` - Controls the `disabled` attribute. If set to `true` disables the whole select picker. If set to an array it will disable only those specific `option` elements whose values are provided in the array.

The `$options` argument allows you to manually specify the contents of the `option` elements of a `select` control.

E.g. :

    echo $this->Form->select('field', [1, 2, 3, 4, 5]);

1  

Output:

    <select name="field">
        <option value="0">1</option>
        <option value="1">2</option>
        <option value="2">3</option>
        <option value="3">4</option>
        <option value="4">5</option>
    </select>

1  
2  
3  
4  
5  
6  
7  

The array for `$options` can also be supplied as key-value pairs.

E.g. :

    echo $this->Form->select('field', [\
        'Value 1' => 'Label 1',\
        'Value 2' => 'Label 2',\
        'Value 3' => 'Label 3'\
    ]);

1  
2  
3  
4  
5  

Output:

    <select name="field">
        <option value="Value 1">Label 1</option>
        <option value="Value 2">Label 2</option>
        <option value="Value 3">Label 3</option>
    </select>

1  
2  
3  
4  
5  

If you would like to generate a `select` with optgroups, just pass data in hierarchical format (nested array). This works on multiple checkboxes and radio buttons too, but instead of `optgroup` it wraps the elements in `fieldset` elements.

For example:

    $options = [\
        'Group 1' => [\
            'Value 1' => 'Label 1',\
            'Value 2' => 'Label 2'\
        ],\
        'Group 2' => [\
            'Value 3' => 'Label 3'\
        ]\
    ];
    echo $this->Form->select('field', $options);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

Output:

    <select name="field">
        <optgroup label="Group 1">
            <option value="Value 1">Label 1</option>
            <option value="Value 2">Label 2</option>
        </optgroup>
        <optgroup label="Group 2">
            <option value="Value 3">Label 3</option>
        </optgroup>
    </select>

1  
2  
3  
4  
5  
6  
7  
8  
9  

To generate HTML attributes within an `option` tag:

    $options = [\
        ['text' => 'Description 1', 'value' => 'value 1', 'attr_name' => 'attr_value 1'],\
        ['text' => 'Description 2', 'value' => 'value 2', 'attr_name' => 'attr_value 2'],\
        ['text' => 'Description 3', 'value' => 'value 3', 'other_attr_name' => 'other_attr_value'],\
    ];
    echo $this->Form->select('field', $options);

1  
2  
3  
4  
5  
6  

Output:

    <select name="field">
        <option value="value 1" attr_name="attr_value 1">Description 1</option>
        <option value="value 2" attr_name="attr_value 2">Description 2</option>
        <option value="value 3" other_attr_name="other_attr_value">Description 3</option>
    </select>

1  
2  
3  
4  
5  

**Controlling Select Pickers via Attributes**

By using specific options in the `$attributes` parameter you can control certain behaviors of the `select()` method.

*   `'empty'` - Set the `'empty'` key in the `$attributes` argument to `true` (the default value is `false`) to add a blank option with an empty value at the top of your dropdown list.
    
    For example:
    
        $options = ['M' => 'Male', 'F' => 'Female'];
        echo $this->Form->select('gender', $options, ['empty' => true]);
    
    1  
    2  
    
    Will output:
    
        <select name="gender">
            <option value=""></option>
            <option value="M">Male</option>
            <option value="F">Female</option>
        </select>
    
    1  
    2  
    3  
    4  
    5  
    
*   `'escape'` - The `select()` method allows for an attribute called `'escape'` which accepts a boolean value and determines whether to HTML entity encode the contents of the `select`'s `option` elements.
    
    E.g. :
    
        // This will prevent HTML-encoding the contents of each option element
        $options = ['M' => 'Male', 'F' => 'Female'];
        echo $this->Form->select('gender', $options, ['escape' => false]);
    
    1  
    2  
    3  
    
*   `'multiple'` - If set to `true`, the select picker will allow multiple selections.
    
    E.g. :
    
        echo $this->Form->select('field', $options, ['multiple' => true]);
    
    1  
    
    Alternatively, set `'multiple'` to `'checkbox'` in order to output a list of related checkboxes:
    
        $options = [\
            'Value 1' => 'Label 1',\
            'Value 2' => 'Label 2'\
        ];
        echo $this->Form->select('field', $options, [\
            'multiple' => 'checkbox'\
        ]);
    
    1  
    2  
    3  
    4  
    5  
    6  
    7  
    
    Output:
    
        <input name="field" value="" type="hidden">
        <div class="checkbox">
            <label for="field-1">
                <input name="field[]" value="Value 1" id="field-1" type="checkbox">
                Label 1
            </label>
        </div>
        <div class="checkbox">
            <label for="field-2">
                <input name="field[]" value="Value 2" id="field-2" type="checkbox">
                Label 2
            </label>
        </div>
    
    1  
    2  
    3  
    4  
    5  
    6  
    7  
    8  
    9  
    10  
    11  
    12  
    13  
    
*   `'disabled'` - This option can be set in order to disable all or some of the `select`'s `option` items. To disable all items set `'disabled'` to `true`. To disable only certain items, assign to `'disabled'` an array containing the keys of the items to be disabled.
    
    E.g. :
    
        $options = [\
            'M' => 'Masculine',\
            'F' => 'Feminine',\
            'N' => 'Neuter'\
        ];
        echo $this->Form->select('gender', $options, [\
            'disabled' => ['M', 'N']\
        ]);
    
    1  
    2  
    3  
    4  
    5  
    6  
    7  
    8  
    
    Will output:
    
        <select name="gender">
            <option value="M" disabled="disabled">Masculine</option>
            <option value="F">Feminine</option>
            <option value="N" disabled="disabled">Neuter</option>
        </select>
    
    1  
    2  
    3  
    4  
    5  
    
    This option also works when `'multiple'` is set to `'checkbox'`:
    
        $options = [\
            'Value 1' => 'Label 1',\
            'Value 2' => 'Label 2'\
        ];
        echo $this->Form->select('field', $options, [\
            'multiple' => 'checkbox',\
            'disabled' => ['Value 1']\
        ]);
    
    1  
    2  
    3  
    4  
    5  
    6  
    7  
    8  
    
    Output:
    
        <input name="field" value="" type="hidden">
        <div class="checkbox">
            <label for="field-1">
                <input name="field[]" disabled="disabled" value="Value 1" type="checkbox">
                Label 1
            </label>
        </div>
        <div class="checkbox">
            <label for="field-2">
                <input name="field[]" value="Value 2" id="field-2" type="checkbox">
                Label 2
            </label>
        </div>
    
    1  
    2  
    3  
    4  
    5  
    6  
    7  
    8  
    9  
    10  
    11  
    12  
    13  
    

### Creating File Inputs [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-file-inputs)

`method` Cake\\View\\Helper\\FormHelper::**file**(string $fieldName, array $options)

*   `$fieldName` - A field name in the form `'Modelname.fieldname'`.
*   `$options` - An optional array including any of the [General Control Options](https://book.cakephp.org/3.x/views/helpers/form.html#general-control-options)
     as well as any valid HTML attributes.

Creates a file upload field in the form. The widget template used by default is:

    'file' => '<input type="file" name="{{name}}"{{attrs}}>'

1  

To add a file upload field to a form, you must first make sure that the form enctype is set to `'multipart/form-data'`.

So start off with a `create()` method such as the following:

    echo $this->Form->create($document, ['enctype' => 'multipart/form-data']);
    // OR
    echo $this->Form->create($document, ['type' => 'file']);

1  
2  
3  

Next add a line that looks like either of the following two lines to your form's view template file:

    echo $this->Form->control('submittedfile', [\
        'type' => 'file'\
    ]);
    
    // OR
    echo $this->Form->file('submittedfile');

1  
2  
3  
4  
5  
6  

NOTE

Due to the limitations of HTML itself, it is not possible to put default values into input fields of type 'file'. Each time the form is displayed, the value inside will be empty.

Upon submission, file fields provide an expanded data array to the script receiving the form data.

For the example above, the values in the submitted data array would be organized as follows, if CakePHP was installed on a Windows server (the key `'tmp_name'` will contain a different path in a Unix environment):

    $this->request->data['submittedfile']
    
    // would contain the following array:
    [\
        'name' => 'conference_schedule.pdf',\
        'type' => 'application/pdf',\
        'tmp_name' => 'C:/WINDOWS/TEMP/php1EE.tmp',\
        'error' => 0, // On Windows this can be a string.\
        'size' => 41737,\
    ];

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

This array is generated by PHP itself, so for more detail on the way PHP handles data passed via file fields [read the PHP manual section on file uploads](https://php.net/features.file-upload)
.

NOTE

When using `$this->Form->file()`, remember to set the form encoding-type, by setting the `'type'` option to `'file'` in `$this->Form->create()`.

### Creating Date & Time Related Controls [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-date-time-related-controls)

The date and time related methods share a number of common traits and options and hence are grouped together into this subsection.

#### Common Options for Date & Time Controls [​](https://book.cakephp.org/3.x/views/helpers/form.html#common-options-for-date-time-controls)

These options are common for the date and time related controls:

*   `'empty'` - If `true` an extra, empty, `option` HTML element is added inside `select` at the top of the list. If a string, that string is displayed as the empty element. Defaults to `true`.
*   `'default'` | `value` - Use either of the two to set the default value to be shown by the field. A value in `$this->request->getData()` matching the field name will override this value. If no default is provided `time()` will be used. - `'year', 'month', 'day', 'hour', 'minute', 'second', 'meridian'` - These options allow you to control which control elements are generated or not. By setting any of these options to `false` you can disable the generation of that specific that select picker (if by default it would be rendered in the used method). In addition each option allows you to pass HTML attributes to that specific `select` element.

#### Options for Date-Related Controls [​](https://book.cakephp.org/3.x/views/helpers/form.html#options-for-date-related-controls)

These options are concerning the date-related methods - i.e. `year()`, `month()`, `day()`, `dateTime()` and `date()`:

*   `'monthNames'` - If `false`, 2 digit numbers will be used instead of text for displaying months in the select picker. If set to an array (e.g. `['01' => 'Jan', '02' => 'Feb', ...]`), the given array will be used.
*   `'minYear'` - The lowest value to use in the year select picker.
*   `'maxYear'` - The maximum value to use in the year select picker.
*   `'orderYear'` - The order of year values in the year select picker. Possible values are `'asc'` and `'desc'`. Defaults to `'desc'`.
*   `'year', 'month', 'day'` - These options allow you to control which control elements are generated or not. By setting any of these options to `false` you can disable the generation of that specific that select picker (if by default it would be rendered in the used method). In addition each option allows you to pass HTML attributes to that specific `select` element.

#### Options for Time-Related Controls [​](https://book.cakephp.org/3.x/views/helpers/form.html#options-for-time-related-controls)

These options are concerning the time-related methods - `hour()`, `minute()`, `second()`, `dateTime()` and `time()`:

*   `'interval'` - The interval in minutes between the values which are displayed in the `option` elements of the minutes select picker. Defaults to 1.
*   `'round'` - Set to `up` or `down` if you want to force rounding minutes in either direction when the value doesn't fit neatly into an interval. Defaults to `null`.
*   `timeFormat` - Applies to `dateTime()` and `time()`. The time format to use in the select picker; either `12` or `24`. When this option is set to anything else than `24` the format will be automatically set to `12` and the `meridian` select picker will be displayed automatically to the right of the seconds select picker. Defaults to 24.
*   `format` - Applies to `hour()`. The time format to use; either `12` or `24`. In case it's set to `12` the `meridian` select picker won't be automatically displayed. It's up to you to either add it or provide means to infer from the form context the right period of the day. Defaults to 24.
*   `second` - Applies to `dateTime()` and `time()`. Set to `true` to enable the seconds drop down. Defaults to `false`.
*   `'hour', 'minute', 'second', 'meridian'` - These options allow you to control which control elements are generated or not. By setting any of these options to `false` you can disable the generation of that specific that select picker (if by default it would be rendered in the used method). In addition each option allows you to pass HTML attributes to that specific `select` element.

#### Creating DateTime Controls [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-datetime-controls)

`method` Cake\\View\\Helper\\FormHelper::**dateTime**($fieldName, $options = \[\])

*   `$fieldName` - A string that will be used as a prefix for the HTML `name` attribute of the `select` elements.
*   `$options` - An optional array including any of the [General Control Options](https://book.cakephp.org/3.x/views/helpers/form.html#general-control-options)
    , or specific datetime options (see above), as well as any valid HTML attributes.

Creates a set of `select` elements for date and time.

To control the order of controls, and any elements/content between the controls you can override the `dateWidget` template. By default the `dateWidget` template is:

    {{year}}{{month}}{{day}}{{hour}}{{minute}}{{second}}{{meridian}}

1  

Calling the method without additional options will generate, by default, 5 select pickers, for: year (4 digits), month (full English name), day (num), hour (num), minutes (num).

For example :

    <?= $this->form->dateTime('registered') ?>

1  

Output:

    <select name="registered[year]">
        <option value="" selected="selected"></option>
        <option value="2022">2022</option>
        ...
        <option value="2012">2012</option>
    </select>
    <select name="registered[month]">
        <option value="" selected="selected"></option>
        <option value="01">January</option>
        ...
        <option value="12">December</option>
    </select>
    <select name="registered[day]">
        <option value="" selected="selected"></option>
        <option value="01">1</option>
        ...
        <option value="31">31</option>
    </select>
    <select name="registered[hour]">
        <option value="" selected="selected"></option>
        <option value="00">0</option>
        ...
        <option value="23">23</option>
    </select>
    <select name="registered[minute]">
        <option value="" selected="selected"></option>
        <option value="00">00</option>
        ...
        <option value="59">59</option>
    </select>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  

To create datetime controls with custom classes/attributes on a specific select box, you can provide them as arrays of options for each component, within the `$options` argument.

For example:

    echo $this->Form->dateTime('released', [\
        'year' => [\
            'class' => 'year-classname',\
        ],\
        'month' => [\
            'class' => 'month-class',\
            'data-type' => 'month',\
        ],\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  

Which would create the following two select pickers:

    <select name="released[year]" class="year-class">
        <option value="" selected="selected"></option>
        <option value="00">0</option>
        <option value="01">1</option>
        <!-- .. snipped for brevity .. -->
    </select>
    <select name="released[month]" class="month-class" data-type="month">
        <option value="" selected="selected"></option>
        <option value="01">January</option>
        <!-- .. snipped for brevity .. -->
    </select>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

#### Creating Date Controls [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-date-controls)

`method` Cake\\View\\Helper\\FormHelper::**date**($fieldName, $options = \[\])

*   `$fieldName` - A field name that will be used as a prefix for the HTML `name` attribute of the `select` elements.
*   `$options` - An optional array including any of the [General Control Options](https://book.cakephp.org/3.x/views/helpers/form.html#general-control-options)
    , of the [Datetime Options](https://book.cakephp.org/3.x/views/helpers/form.html#datetime-options)
    , any applicable [Time Options](https://book.cakephp.org/3.x/views/helpers/form.html#time-options)
    , as well as any valid HTML attributes.

Creates, by default, three select pickers populated with values for: year (4 digits), month (full English name) and day (numeric), respectively.

You can further control the generated `select` elements by providing additional options.

For example:

    // Assuming current year is 2017; this disables day picker, removes empty
    // option on year picker, limits lowest year, adds HTML attributes on year,
    // adds a string 'empty' option on month, changes month to numeric
    <?php
        echo $this->Form->date('registered', [\
            'minYear' => 2018,\
            'monthNames' => false, // Months are displayed as numbers\
            'empty' => [\
                'year' => false, // The year select control has no option for empty value\
                'month' => 'Choose month...', // The month select control does, though\
            ],\
            'day' => false, // Do not show day select control\
            'year' => [\
                'class' => 'cool-years',\
                'title' => 'Registration Year'\
            ]\
        ]);
    ?>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

Output:

    <select class= "cool-years" name="registered[year]" title="Registration Year">
        <option value="2022">2022</option>
        <option value="2021">2021</option>
        ...
        <option value="2018">2018</option>
    </select>
    <select name="registered[month]">
        <option value="" selected="selected">Choose month...</option>
        <option value="01">1</option>
        ...
        <option value="12">12</option>
    </select>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

#### Creating Time Controls [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-time-controls)

`method` Cake\\View\\Helper\\FormHelper::**time**($fieldName, $options = \[\])

*   `$fieldName` - A field name that will be used as a prefix for the HTML `name` attribute of the `select` elements.
*   `$options` - An optional array including any of the [General Control Options](https://book.cakephp.org/3.x/views/helpers/form.html#general-control-options)
    , of the [Datetime Options](https://book.cakephp.org/3.x/views/helpers/form.html#datetime-options)
    , any applicable [Time Options](https://book.cakephp.org/3.x/views/helpers/form.html#time-options)
    , as well as any valid HTML attributes.

Creates, by default, two `select` elements (`hour` and `minute`) populated with values for 24 hours and 60 minutes, respectively. Additionally, HTML attributes may be supplied in `$options` for each specific component. If `$options['empty']` is `false`, the select picker will not include an empty default option.

For example, to create a time range with minutes selectable in 15 minute increments, and to apply classes to the select boxes, you could do the following:

    echo $this->Form->time('released', [\
        'interval' => 15,\
        'hour' => [\
            'class' => 'foo-class',\
        ],\
        'minute' => [\
            'class' => 'bar-class',\
        ],\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  

Which would create the following two select pickers:

    <select name="released[hour]" class="foo-class">
        <option value="" selected="selected"></option>
        <option value="00">0</option>
        <option value="01">1</option>
        <!-- .. snipped for brevity .. -->
        <option value="22">22</option>
        <option value="23">23</option>
    </select>
    <select name="released[minute]" class="bar-class">
        <option value="" selected="selected"></option>
        <option value="00">00</option>
        <option value="15">15</option>
        <option value="30">30</option>
        <option value="45">45</option>
    </select>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

#### Creating Year Controls [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-year-controls)

`method` Cake\\View\\Helper\\FormHelper::**year**(string $fieldName, array $options = \[\])

*   `$fieldName` - A field name that will be used as a prefix for the HTML `name` attribute of the `select` element.
*   `$options` - An optional array including any of the [General Control Options](https://book.cakephp.org/3.x/views/helpers/form.html#general-control-options)
    , of the [Datetime Options](https://book.cakephp.org/3.x/views/helpers/form.html#datetime-options)
    , any applicable [Date Options](https://book.cakephp.org/3.x/views/helpers/form.html#date-options)
    , as well as any valid HTML attributes.

Creates a `select` element populated with the years from `minYear` to `maxYear` (when these options are provided) or else with values starting from -5 years to +5 years counted from today. Additionally, HTML attributes may be supplied in `$options`. If `$options['empty']` is `false`, the select picker will not include an empty item in the list.

For example, to create a year range from 2000 to the current year you would do the following:

    echo $this->Form->year('purchased', [\
        'minYear' => 2000,\
        'maxYear' => date('Y')\
    ]);

1  
2  
3  
4  

If it was 2009, you would get the following:

    <select name="purchased[year]">
        <option value=""></option>
        <option value="2009">2009</option>
        <option value="2008">2008</option>
        <option value="2007">2007</option>
        <option value="2006">2006</option>
        <option value="2005">2005</option>
        <option value="2004">2004</option>
        <option value="2003">2003</option>
        <option value="2002">2002</option>
        <option value="2001">2001</option>
        <option value="2000">2000</option>
    </select>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

#### Creating Month Controls [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-month-controls)

`method` Cake\\View\\Helper\\FormHelper::**month**(string $fieldName, array $attributes)

*   `$fieldName` - A field name that will be used as a prefix for the HTML `name` attribute of the `select` element.
*   `$attributes` - An optional array including any of the [General Control Options](https://book.cakephp.org/3.x/views/helpers/form.html#general-control-options)
    , of the [Datetime Options](https://book.cakephp.org/3.x/views/helpers/form.html#datetime-options)
    , any applicable [Date Options](https://book.cakephp.org/3.x/views/helpers/form.html#date-options)
    , as well as any valid HTML attributes.

Creates a `select` element populated with month names.

For example:

    echo $this->Form->month('mob');

1  

Will output:

    <select name="mob[month]">
        <option value=""></option>
        <option value="01">January</option>
        <option value="02">February</option>
        <option value="03">March</option>
        <option value="04">April</option>
        <option value="05">May</option>
        <option value="06">June</option>
        <option value="07">July</option>
        <option value="08">August</option>
        <option value="09">September</option>
        <option value="10">October</option>
        <option value="11">November</option>
        <option value="12">December</option>
    </select>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

You can pass in, your own array of months to be used by setting the `'monthNames'` attribute, or have months displayed as numbers by passing `false`.

E.g. :

    echo $this->Form->month('mob', ['monthNames' => false]);

1  

NOTE

The default months can be localized with CakePHP [Internationalization & Localization](https://book.cakephp.org/3.x/core-libraries/internationalization-and-localization.html)
 features.

#### Creating Day Controls [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-day-controls)

`method` Cake\\View\\Helper\\FormHelper::**day**(string $fieldName, array $attributes)

*   `$fieldName` - A field name that will be used as a prefix for the HTML `name` attribute of the `select` element.
*   `$attributes` - An optional array including any of the [General Control Options](https://book.cakephp.org/3.x/views/helpers/form.html#general-control-options)
    , of the [Datetime Options](https://book.cakephp.org/3.x/views/helpers/form.html#datetime-options)
    , any applicable [Date Options](https://book.cakephp.org/3.x/views/helpers/form.html#date-options)
    , as well as any valid HTML attributes.

Creates a `select` element populated with the (numerical) days of the month.

To create an empty `option` element with a prompt text of your choosing (e.g. the first option is 'Day'), you can supply the text in the `'empty'` parameter.

For example:

    echo $this->Form->day('created', ['empty' => 'Day']);

1  

Will output:

    <select name="created[day]">
        <option value="" selected="selected">Day</option>
        <option value="01">1</option>
        <option value="02">2</option>
        <option value="03">3</option>
        ...
        <option value="31">31</option>
    </select>

1  
2  
3  
4  
5  
6  
7  
8  

#### Creating Hour Controls [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-hour-controls)

`method` Cake\\View\\Helper\\FormHelper::**hour**(string $fieldName, array $attributes)

*   `$fieldName` - A field name that will be used as a prefix for the HTML `name` attribute of the `select` element.
*   `$attributes` - An optional array including any of the [General Control Options](https://book.cakephp.org/3.x/views/helpers/form.html#general-control-options)
    , of the [Datetime Options](https://book.cakephp.org/3.x/views/helpers/form.html#datetime-options)
    , any applicable [Time Options](https://book.cakephp.org/3.x/views/helpers/form.html#time-options)
    , as well as any valid HTML attributes.

Creates a `select` element populated with the hours of the day.

You can create either 12 or 24 hour pickers using the `'format'` option:

    echo $this->Form->hour('created', [\
        'format' => 12\
    ]);
    echo $this->Form->hour('created', [\
        'format' => 24\
    ]);

1  
2  
3  
4  
5  
6  

#### Creating Minute Controls [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-minute-controls)

`method` Cake\\View\\Helper\\FormHelper::**minute**(string $fieldName, array $attributes)

*   `$fieldName` - A field name that will be used as a prefix for the HTML `name` attribute of the `select` element.
*   `$attributes` - An optional array including any of the [General Control Options](https://book.cakephp.org/3.x/views/helpers/form.html#general-control-options)
    , of the [Datetime Options](https://book.cakephp.org/3.x/views/helpers/form.html#datetime-options)
    , any applicable [Time Options](https://book.cakephp.org/3.x/views/helpers/form.html#time-options)
    , as well as any valid HTML attributes.

Creates a `select` element populated with values for the minutes of the hour. You can create a select picker that only contains specific values by using the `'interval'` option.

For example, if you wanted 10 minutes increments you would do the following:

    // In your view template file
    echo $this->Form->minute('arrival', [\
        'interval' => 10\
    ]);

1  
2  
3  
4  

This would output:

    <select name="arrival[minute]">
        <option value="" selected="selected"></option>
        <option value="00">00</option>
        <option value="10">10</option>
        <option value="20">20</option>
        <option value="30">30</option>
        <option value="40">40</option>
        <option value="50">50</option>
    </select>

1  
2  
3  
4  
5  
6  
7  
8  
9  

#### Creating Meridian Controls [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-meridian-controls)

`method` Cake\\View\\Helper\\FormHelper::**meridian**(string $fieldName, array $attributes)

*   `$fieldName` - A field name that will be used as a prefix for the HTML `name` attribute of the `select` element.
*   `$attributes` - An optional array including any of the [General Control Options](https://book.cakephp.org/3.x/views/helpers/form.html#general-control-options)
     as well as any valid HTML attributes.

Creates a `select` element populated with 'am' and 'pm'. This is useful when the hour format is set to `12` instead of `24`, as it allows to specify the period of the day to which the hour belongs.

Creating Labels [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-labels)

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

`method` Cake\\View\\Helper\\FormHelper::**label**(string $fieldName, string $text, array $options)

*   `$fieldName` - A field name in the form `'Modelname.fieldname'`.
*   `$text` - An optional string providing the label caption text.
*   `$options` - Optional. Array containing any of the [General Control Options](https://book.cakephp.org/3.x/views/helpers/form.html#general-control-options)
     as well as any valid HTML attributes.

Creates a `label` element. The argument `$fieldName` is used for generating the HTML `for` attribute of the element; if `$text` is undefined, `$fieldName` will also be used to inflect the label's `text` attribute.

E.g. :

    echo $this->Form->label('name');
    echo $this->Form->label('name', 'Your username');

1  
2  

Output:

    <label for="name">Name</label>
    <label for="name">Your username</label>

1  
2  

With the third parameter `$options` you can set the id or class:

    echo $this->Form->label('name', null, ['id' => 'user-label']);
    echo $this->Form->label('name', 'Your username', ['class' => 'highlight']);

1  
2  

Output:

    <label for="name" id="user-label">Name</label>
    <label for="name" class="highlight">Your username</label>

1  
2  

Displaying and Checking Errors [​](https://book.cakephp.org/3.x/views/helpers/form.html#displaying-and-checking-errors)

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

FormHelper exposes a couple of methods that allow us to easily check for field errors and when necessary display customized error messages.

### Displaying Errors [​](https://book.cakephp.org/3.x/views/helpers/form.html#displaying-errors)

`method` Cake\\View\\Helper\\FormHelper::**error**(string $fieldName, mixed $text, array $options)

*   `$fieldName` - A field name in the form `'Modelname.fieldname'`.
*   `$text` - Optional. A string or array providing the error message(s). If an array, then it should be a hash of key names => messages. Defaults to `null`.
*   `$options` - An optional array that can only contain a boolean with the key `'escape'`, which will define whether to HTML escape the contents of the error message. Defaults to `true`.

Shows a validation error message, specified by `$text`, for the given field, in the event that a validation error has occurred. If `$text` is not provided then the default validation error message for that field will be used.

Uses the following template widgets:

    'error' => '<div class="error-message">{{content}}</div>'
    'errorList' => '<ul>{{content}}</ul>'
    'errorItem' => '<li>{{text}}</li>'

1  
2  
3  

The `'errorList'` and `'errorItem'` templates are used to format mutiple error messages per field.

Example:

    // If in TicketsTable you have a 'notEmpty' validation rule:
    public function validationDefault(Validator $validator)
    {
        $validator
            ->requirePresence('ticket', 'create')
            ->notEmpty('ticket');
    }
    
    // And inside Templates/Tickets/add.ctp you have:
    echo $this->Form->text('ticket');
    
    if ($this->Form->isFieldError('ticket')) {
        echo $this->Form->error('ticket', 'Completely custom error message!');
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

If you would click the _Submit_ button of your form without providing a value for the _Ticket_ field, your form would output:

    <input name="ticket" class="form-error" required="required" value="" type="text">
    <div class="error-message">Completely custom error message!</div>

1  
2  

NOTE

When using `Cake\View\Helper\FormHelper::control()`, errors are rendered by default, so you don't need to use `isFieldError()` or call `error()` manually.

TIP

If you use a certain model field to generate multiple form fields via `control()`, and you want the same validation error message displayed for each one, you will probably be better off defining a custom error message inside the respective [validator rules](https://book.cakephp.org/3.x/core-libraries/validation.html#creating-validators)
.

### Checking for Errors [​](https://book.cakephp.org/3.x/views/helpers/form.html#checking-for-errors)

`method` Cake\\View\\Helper\\FormHelper::**isFieldError**(string $fieldName)

*   `$fieldName` - A field name in the form `'Modelname.fieldname'`.

Returns `true` if the supplied `$fieldName` has an active validation error, otherwise returns `false`.

Example:

    if ($this->Form->isFieldError('gender')) {
        echo $this->Form->error('gender');
    }

1  
2  
3  

### Displaying validation messages in HTML5 validity messages [​](https://book.cakephp.org/3.x/views/helpers/form.html#displaying-validation-messages-in-html5-validity-messages)

Added in version 3.7.0

If the `autoSetCustomValidity` FormHelper option is set to `true`, error messages for the field's required and notBlank validation rules will be used instead of the default browser HTML5 required messages. Enabling the option will add the `onvalid` and `oninvalid` event attributes to your fields, for example:

    <input type="text" name="field" required onvalid="this.setCustomValidity('')" oninvalid="this.setCustomValidity('Custom notBlank message')" />

1  

If you want to manually set those events with custom JavaScript, you can set the `autoSetCustomValidity` option to `false` and use the special `customValidityMessage` template variable instead. This template variable is added when a field is required:

    // example template
    [\
        'input' => '<input type="{{type}}" name="{{name}}" data-error-message="{{customValidityMessage}}" {{attrs}}/>',\
    ]
    
    // would create an input like this
    <input type="text" name="field" required data-error-message="Custom notBlank message" />

1  
2  
3  
4  
5  
6  
7  

You could then use JavaScript to set the `onvalid` and `oninvalid` events as you like.

Creating Buttons and Submit Elements [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-buttons-and-submit-elements)

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

### Creating Submit Elements [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-submit-elements)

`method` Cake\\View\\Helper\\FormHelper::**submit**(string $caption, array $options)

*   `$caption` - An optional string providing the button's text caption or a path to an image. Defaults to `'Submit'`.
*   `$options` - An optional array including any of the [General Control Options](https://book.cakephp.org/3.x/views/helpers/form.html#general-control-options)
    , or of the specific submit options (see below) as well as any valid HTML attributes.

Creates an `input` element of `submit` type, with `$caption` as value. If the supplied `$caption` is a URL pointing to an image (i.e. if the string contains '😕/' or contains any of the extensions '.jpg, .jpe, .jpeg, .gif'), an image submit button will be generated, using the specified image if it exists. If the first character is '/' then the image path is relative to _webroot_, else if the first character is not '/' then the image path is relative to _webroot/img_.

By default it will use the following widget templates:

    'inputSubmit' => '<input type="{{type}}"{{attrs}}/>'
    'submitContainer' => '<div class="submit">{{content}}</div>'

1  
2  

**Options for Submit**

*   `'type'` - Set this option to `'reset'` in order to generate reset buttons. It defaults to `'submit'`.
*   `'templateVars'` - Set this array to provide additional template variables for the input element and its container.
*   Any other provided attributes will be assigned to the `input` element.

The following:

    echo $this->Form->submit('Click me');

1  

Will output:

    <div class="submit"><input value="Click me" type="submit"></div>

1  

You can pass a relative or absolute URL of an image to the caption parameter instead of the caption text:

    echo $this->Form->submit('ok.png');

1  

Will output:

    <div class="submit"><input type="image" src="/img/ok.png"></div>

1  

Submit inputs are useful when you only need basic text or images. If you need more complex button content you should use `button()`.

### Creating Button Elements [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-button-elements)

`method` Cake\\View\\Helper\\FormHelper::**button**(string $title, array $options = \[\])

*   `$title` - Mandatory string providing the button's text caption.
*   `$options` - An optional array including any of the [General Control Options](https://book.cakephp.org/3.x/views/helpers/form.html#general-control-options)
    , or of the specific button options (see below) as well as any valid HTML attributes.

Creates an HTML button with the specified title and a default type of `'button'`.

**Options for Button**

*   `$options['type']` - You can set this to one of the following three possible values:
    1.  `'submit'` - Similarly to the `$this->Form->submit()` method it will create a submit button. However this won't generate a wrapping `div` as `submit()` does. This is the default type.
    2.  `'reset'` - Creates a form reset button.
    3.  `'button'` - Creates a standard push button.
*   `$options['escape']` - Boolean. If set to `true` it will HTML encode the value provided inside `$title`. Defaults to `false`.

For example:

    echo $this->Form->button('A Button');
    echo $this->Form->button('Another Button', ['type' => 'button']);
    echo $this->Form->button('Reset the Form', ['type' => 'reset']);
    echo $this->Form->button('Submit Form', ['type' => 'submit']);

1  
2  
3  
4  

Will output:

    <button type="submit">A Button</button>
    <button type="button">Another Button</button>
    <button type="reset">Reset the Form</button>
    <button type="submit">Submit Form</button>

1  
2  
3  
4  

Example of use of the `'escape'` option:

    // Will render escaped HTML.
    echo $this->Form->button('<em>Submit Form</em>', [\
        'type' => 'submit',\
        'escape' => true\
    ]);

1  
2  
3  
4  
5  

Closing the Form [​](https://book.cakephp.org/3.x/views/helpers/form.html#closing-the-form)

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

`method` Cake\\View\\Helper\\FormHelper::**end**($secureAttributes = \[\])

*   `$secureAttributes` - Optional. Allows you to provide secure attributes which will be passed as HTML attributes into the hidden input elements generated for the SecurityComponent.

The `end()` method closes and completes a form. Often, `end()` will only output a closing form tag, but using `end()` is a good practice as it enables FormHelper to insert the hidden form elements that `Cake\Controller\Component\SecurityComponent` requires:

    <?= $this->Form->create(); ?>
    
    <!-- Form elements go here -->
    
    <?= $this->Form->end(); ?>

1  
2  
3  
4  
5  

If you need to add additional attributes to the generated hidden inputs you can use the `$secureAttributes` argument.

E.g. :

    echo $this->Form->end(['data-type' => 'hidden']);

1  

Will output:

    <div style="display:none;">
        <input type="hidden" name="_Token[fields]" data-type="hidden"
            value="2981c38990f3f6ba935e6561dc77277966fabd6d%3AAddresses.id">
        <input type="hidden" name="_Token[unlocked]" data-type="hidden"
            value="address%7Cfirst_name">
    </div>

1  
2  
3  
4  
5  
6  

NOTE

If you are using `Cake\Controller\Component\SecurityComponent` in your application you should always end your forms with `end()`.

Creating Standalone Buttons and POST Links [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-standalone-buttons-and-post-links)

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

### Creating POST Buttons [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-post-buttons)

`method` Cake\\View\\Helper\\FormHelper::**postButton**(string $title, mixed $url, array $options = \[\])

*   `$title` - Mandatory string providing the button's text caption. By default not HTML encoded.
*   `$url` - The URL of the form provided as a string or as array.
*   `$options` - An optional array including any of the [General Control Options](https://book.cakephp.org/3.x/views/helpers/form.html#general-control-options)
    , or of the specific options (see below) as well as any valid HTML attributes.

Creates a `<button>` tag with a surrounding `<form>` element that submits via POST, by default. Also, by default, it generates hidden input fields for the SecurityComponent.

**Options for POST Button**

*   `'data'` - Array with key/value to pass in hidden input.
*   `'method'` - Request method to use. E.g. set to `'delete'` to simulate a HTTP/1.1 DELETE request. Defaults to `'post'`.
*   `'form'` - Array with any option that `FormHelper::create()` can take.
*   Also, the `postButton()` method will accept the options which are valid for the `button()` method.

For example:

    // In Templates/Tickets/index.ctp
    <?= $this->Form->postButton('Delete Record', ['controller' => 'Tickets', 'action' => 'delete', 5]) ?>

1  
2  

Will output HTML similar to:

    <form method="post" accept-charset="utf-8" action="/Rtools/tickets/delete/5">
        <div style="display:none;">
            <input name="_method" value="POST" type="hidden">
        </div>
        <button type="submit">Delete Record</button>
        <div style="display:none;">
            <input name="_Token[fields]" value="186cfbfc6f519622e19d1e688633c4028229081f%3A" type="hidden">
            <input name="_Token[unlocked]" value="" type="hidden">
            <input name="_Token[debug]" value="%5B%22%5C%2FRtools%5C%2Ftickets%5C%2Fdelete%5C%2F1%22%2C%5B%5D%2C%5B%5D%5D" type="hidden">
        </div>
    </form>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

Since this method generates a `form` element, do not use this method in an already opened form. Instead use `Cake\View\Helper\FormHelper::submit()` or `Cake\View\Helper\FormHelper::button()` to create buttons inside opened forms.

### Creating POST Links [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-post-links)

`method` Cake\\View\\Helper\\FormHelper::**postLink**(string $title, mixed $url = null, array $options = \[\])

*   `$title` - Mandatory string providing the text to be wrapped in `<a>` tags.
*   `$url` - Optional. String or array which contains the URL of the form (Cake-relative or external URL starting with `http://`).
*   `$options` - An optional array including any of the [General Control Options](https://book.cakephp.org/3.x/views/helpers/form.html#general-control-options)
    , or of the specific options (see below) as well as any valid HTML attributes.

Creates an HTML link, but accesses the URL using the method you specify (defaults to POST). Requires JavaScript to be enabled in browser:

    // In your template, e.g. to delete an article
    <?= $this->Form->postLink(
        'Delete',
        ['action' => 'delete', $article->id],
        ['confirm' => 'Are you sure?'])
    ?>

1  
2  
3  
4  
5  
6  

**Options for POST Link**

*   `'data'` - Array with key/value to pass in hidden input.
*   `'method'` - Request method to use. E.g. set to `'delete'` to simulate a HTTP/1.1 DELETE request. Defaults to `'post'`.
*   `'confirm'` - The confirmation message to display on click. Defaults to `null`.
*   `'block'` - Set this option to `true` to append the form to view block `'postLink'` or provide a custom block name. Defaults to `null`.
*   Also, the `postLink` method will accept the options which are valid for the `link()` method.

This method creates a `<form>` element. If you want to use this method inside of an existing form, you must use the `block` option so that the new form is being set to a [view block](https://book.cakephp.org/3.x/views.html#view-blocks)
 that can be rendered outside of the main form.

If all you are looking for is a button to submit your form, then you should use `Cake\View\Helper\FormHelper::button()` or `Cake\View\Helper\FormHelper::submit()` instead.

NOTE

Be careful to not put a postLink inside an open form. Instead use the `block` option to buffer the form into a [view block](https://book.cakephp.org/3.x/views.html#view-blocks)

Customizing the Templates FormHelper Uses [​](https://book.cakephp.org/3.x/views/helpers/form.html#customizing-the-templates-formhelper-uses)

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

Like many helpers in CakePHP, FormHelper uses string templates to format the HTML it creates. While the default templates are intended to be a reasonable set of defaults, you may need to customize the templates to suit your application.

To change the templates when the helper is loaded you can set the `'templates'` option when including the helper in your controller:

    // In a View class
    $this->loadHelper('Form', [\
        'templates' => 'app_form',\
    ]);

1  
2  
3  
4  

This would load the tags found in **config/app\_form.php**. This file should contain an array of templates _indexed by name_:

    // in config/app_form.php
    return [\
        'inputContainer' => '<div class="form-control">{{content}}</div>',\
    ];

1  
2  
3  
4  

Any templates you define will replace the default ones included in the helper. Templates that are not replaced, will continue to use the default values.

You can also change the templates at runtime using the `setTemplates()` method:

    $myTemplates = [\
        'inputContainer' => '<div class="form-control">{{content}}</div>',\
    ];
    $this->Form->setTemplates($myTemplates);
    // Prior to 3.4
    $this->Form->templates($myTemplates);

1  
2  
3  
4  
5  
6  

WARNING

Template strings containing a percentage sign (`%`) need special attention; you should prefix this character with another percentage so it looks like `%%`. The reason is that internally templates are compiled to be used with `sprintf()`. Example: `'<div style="width:%%"></div>'`

### List of Templates [​](https://book.cakephp.org/3.x/views/helpers/form.html#list-of-templates)

The list of default templates, their default format and the variables they expect can be found in the [FormHelper API documentation](https://api.cakephp.org/3.x/class-Cake.View.Helper.FormHelper.html#%24_defaultConfig)
.

#### Using Distinct Custom Control Containers [​](https://book.cakephp.org/3.x/views/helpers/form.html#using-distinct-custom-control-containers)

In addition to these templates, the `control()` method will attempt to use distinct templates for each control container. For example, when creating a datetime control the `datetimeContainer` will be used if it is present. If that container is missing the `inputContainer` template will be used.

For example:

    // Add custom radio wrapping HTML
    $this->Form->setTemplates([\
        'radioContainer' => '<div class="form-radio">{{content}}</div>'\
    ]);
    
    // Create a radio set with our custom wrapping div.
    echo $this->Form->control('email_notifications', [\
        'options' => ['y', 'n'],\
        'type' => 'radio'\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

#### Using Distinct Custom Form Groups [​](https://book.cakephp.org/3.x/views/helpers/form.html#using-distinct-custom-form-groups)

Similar to controlling containers, the `control()` method will also attempt to use distinct templates for each form group. A form group is a combo of label and control. For example, when creating a radio control the `radioFormGroup` will be used if it is present. If that template is missing by default each set of `label` & `input` is rendered using the default `formGroup` template.

For example:

    // Add custom radio form group
    $this->Form->setTemplates([\
        'radioFormGroup' => '<div class="radio">{{label}}{{input}}</div>'\
    ]);

1  
2  
3  
4  

### Adding Additional Template Variables to Templates [​](https://book.cakephp.org/3.x/views/helpers/form.html#adding-additional-template-variables-to-templates)

You can add additional template placeholders in custom templates, and populate those placeholders when generating controls.

E.g. :

    // Add a template with the help placeholder.
    $this->Form->setTemplates([\
        'inputContainer' => '<div class="input {{type}}{{required}}">\
            {{content}} <span class="help">{{help}}</span></div>'\
    ]);
    
    // Generate an input and populate the help variable
    echo $this->Form->control('password', [\
        'templateVars' => ['help' => 'At least 8 characters long.']\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

Output:

    <div class="input password">
        <label for="password">
            Password
        </label>
        <input name="password" id="password" type="password">
        <span class="help">At least 8 characters long.</span>
    </div>

1  
2  
3  
4  
5  
6  
7  

Added in version 3.1

The templateVars option was added in 3.1.0

### Moving Checkboxes & Radios Outside of a Label [​](https://book.cakephp.org/3.x/views/helpers/form.html#moving-checkboxes-radios-outside-of-a-label)

By default CakePHP nests checkboxes created via `control()` and radio buttons created by both `control()` and `radio()` within label elements. This helps make it easier to integrate popular CSS frameworks. If you need to place checkbox/radio inputs outside of the label you can do so by modifying the templates:

    $this->Form->setTemplates([\
        'nestingLabel' => '{{hidden}}{{input}}<label{{attrs}}>{{text}}</label>',\
        'formGroup' => '{{input}}{{label}}',\
    ]);

1  
2  
3  
4  

This will make radio buttons and checkboxes render outside of their labels.

Generating Entire Forms [​](https://book.cakephp.org/3.x/views/helpers/form.html#generating-entire-forms)

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

### Creating Multiple Controls [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-multiple-controls)

`method` Cake\\View\\Helper\\FormHelper::**controls**(array $fields = \[\], $options = \[\])

*   `$fields` - An array of fields to generate. Allows setting custom types, labels and other options for each specified field.
*   `$options` - Optional. An array of options. Valid keys are:
    1.  `'fieldset'` - Set this to `false` to disable the fieldset. If empty, the fieldset will be enabled. Can also be an array of parameters to be applied as HTML attributes to the `fieldset` tag.
    2.  `legend` - String used to customize the `legend` text. Set this to `false` to disable the legend for the generated input set.

Generates a set of controls for the given context wrapped in a `fieldset`. You can specify the generated fields by including them:

    echo $this->Form->controls([\
        'name',\
        'email'\
    ]);

1  
2  
3  
4  

You can customize the legend text using an option:

    echo $this->Form->controls($fields, ['legend' => 'Update news post']);

1  

You can customize the generated controls by defining additional options in the `$fields` parameter:

    echo $this->Form->controls([\
        'name' => ['label' => 'custom label']\
    ]);

1  
2  
3  

When customizing, `$fields`, you can use the `$options` parameter to control the generated legend/fieldset.

For example:

    echo $this->Form->controls(
        [\
            'name' => ['label' => 'custom label']\
        ],
        ['legend' => 'Update your post']
    );

1  
2  
3  
4  
5  
6  

If you disable the `fieldset`, the `legend` will not print.

### Creating Controls for a Whole Entity [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-controls-for-a-whole-entity)

`method` Cake\\View\\Helper\\FormHelper::**allControls**(array $fields, $options = \[\])

*   `$fields` - Optional. An array of customizations for the fields that will be generated. Allows setting custom types, labels and other options.
*   `$options` - Optional. An array of options. Valid keys are:
    1.  `'fieldset'` - Set this to `false` to disable the fieldset. If empty, the fieldset will be enabled. Can also be an array of parameters to be applied as HTMl attributes to the `fieldset` tag.
    2.  `legend` - String used to customize the `legend` text. Set this to `false` to disable the legend for the generated control set.

This method is closely related to `controls()`, however the `$fields` argument is defaulted to _all_ fields in the current top-level entity. To exclude specific fields from the generated controls, set them to `false` in the `$fields` parameter:

    echo $this->Form->allControls(['password' => false]);
    // Or prior to 3.4.0:
    echo $this->Form->allInputs(['password' => false]);

1  
2  
3  

Creating Inputs for Associated Data [​](https://book.cakephp.org/3.x/views/helpers/form.html#creating-inputs-for-associated-data)

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

Creating forms for associated data is straightforward and is closely related to the paths in your entity's data. Assuming the following table relations:

*   Authors HasOne Profiles
*   Authors HasMany Articles
*   Articles HasMany Comments
*   Articles BelongsTo Authors
*   Articles BelongsToMany Tags

If we were editing an article with its associations loaded we could create the following controls:

    $this->Form->create($article);
    
    // Article controls.
    echo $this->Form->control('title');
    
    // Author controls (belongsTo)
    echo $this->Form->control('author.id');
    echo $this->Form->control('author.first_name');
    echo $this->Form->control('author.last_name');
    
    // Author profile (belongsTo + hasOne)
    echo $this->Form->control('author.profile.id');
    echo $this->Form->control('author.profile.username');
    
    // Tags controls (belongsToMany)
    // as separate inputs
    echo $this->Form->control('tags.0.id');
    echo $this->Form->control('tags.0.name');
    echo $this->Form->control('tags.1.id');
    echo $this->Form->control('tags.1.name');
    
    // Inputs for the joint table (articles_tags)
    echo $this->Form->control('tags.0._joinData.starred');
    echo $this->Form->control('tags.1._joinData.starred');
    
    // Comments controls (hasMany)
    echo $this->Form->control('comments.0.id');
    echo $this->Form->control('comments.0.comment');
    echo $this->Form->control('comments.1.id');
    echo $this->Form->control('comments.1.comment');
    
    // Multiple file control (hasMany) (requires $this->Form->create($article, ['type' => 'file']))
    echo $this->Form->control('files[].filename', ['type' => 'file', 'multiple' => 'true']);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  

The above controls could then be marshalled into a completed entity graph using the following code in your controller:

    $article = $this->Articles->patchEntity($article, $this->request->getData(), [\
        'associated' => [\
            'Authors',\
            'Authors.Profiles',\
            'Tags',\
            'Comments'\
        ]\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  

The above example shows an expanded example for belongs to many associations, with separate inputs for each entity and join data record. You can also create a multiple select input for belongs to many associations:

    // Multiple select element for belongsToMany
    // Does not support _joinData
    echo $this->Form->control('tags._ids', [\
        'type' => 'select',\
        'multiple' => true,\
        'options' => $tagList,\
    ]);

1  
2  
3  
4  
5  
6  
7  

Adding Custom Widgets [​](https://book.cakephp.org/3.x/views/helpers/form.html#adding-custom-widgets)

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

CakePHP makes it easy to add custom control widgets in your application, and use them like any other control type. All of the core control types are implemented as widgets, which means you can override any core widget with your own implementation as well.

### Building a Widget Class [​](https://book.cakephp.org/3.x/views/helpers/form.html#building-a-widget-class)

Widget classes have a very simple required interface. They must implement the `Cake\View\Widget\WidgetInterface`. This interface requires the `render(array $data)` and `secureFields(array $data)` methods to be implemented. The `render()` method expects an array of data to build the widget and is expected to return a string of HTML for the widget. The `secureFields()` method expects an array of data as well and is expected to return an array containing the list of fields to secure for this widget. If CakePHP is constructing your widget you can expect to get a `Cake\View\StringTemplate` instance as the first argument, followed by any dependencies you define. If we wanted to build an Autocomplete widget you could do the following:

    namespace App\View\Widget;
    
    use Cake\View\Form\ContextInterface;
    use Cake\View\Widget\WidgetInterface;
    
    class AutocompleteWidget implements WidgetInterface
    {
        protected $_templates;
    
        public function __construct($templates)
        {
            $this->_templates = $templates;
        }
    
        public function render(array $data, ContextInterface $context)
        {
            $data += [\
                'name' => '',\
            ];
            return $this->_templates->format('autocomplete', [\
                'name' => $data['name'],\
                'attrs' => $this->_templates->formatAttributes($data, ['name'])\
            ]);
        }
    
        public function secureFields(array $data)
        {
            return [$data['name']];
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  

Obviously, this is a very simple example, but it demonstrates how a custom widget could be built. This widget would render the "autocomplete" string template, such as:

    $this->Form->setTemplates([\
        'autocomplete' => '<input type="autocomplete" name="{{name}}" {{attrs}} />'\
    ]);

1  
2  
3  

For more information on string templates, see [Customizing Templates](https://book.cakephp.org/3.x/views/helpers/form.html#customizing-templates)
.

### Using Widgets [​](https://book.cakephp.org/3.x/views/helpers/form.html#using-widgets)

You can load custom widgets when loading FormHelper or by using the `addWidget()` method. When loading FormHelper, widgets are defined as a setting:

    // In View class
    $this->loadHelper('Form', [\
        'widgets' => [\
            'autocomplete' => ['Autocomplete']\
        ]\
    ]);

1  
2  
3  
4  
5  
6  

If your widget requires other widgets, you can have FormHelper populate those dependencies by declaring them:

    $this->loadHelper('Form', [\
        'widgets' => [\
            'autocomplete' => [\
                'App\View\Widget\AutocompleteWidget',\
                'text',\
                'label'\
            ]\
        ]\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  

In the above example, the `autocomplete` widget would depend on the `text` and `label` widgets. If your widget needs access to the View, you should use the `_view` 'widget'. When the `autocomplete` widget is created, it will be passed the widget objects that are related to the `text` and `label` names. To add widgets using the `addWidget()` method would look like:

    // Using a classname.
    $this->Form->addWidget(
        'autocomplete',
        ['Autocomplete', 'text', 'label']
    );
    
    // Using an instance - requires you to resolve dependencies.
    // Prior to 3.6.0 use widgetRegistry() to fetch widgets.
    $autocomplete = new AutocompleteWidget(
        $this->Form->getTemplater(),
        $this->Form->getWidgetLocator()->get('text'),
        $this->Form->getWidgetLocator()->get('label'),
    );
    $this->Form->addWidget('autocomplete', $autocomplete);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

Once added/replaced, widgets can be used as the control 'type':

    echo $this->Form->control('search', ['type' => 'autocomplete']);

1  

This will create the custom widget with a `label` and wrapping `div` just like `controls()` always does. Alternatively, you can create just the control widget using the magic method:

    echo $this->Form->autocomplete('search', $options);

1  

Working with SecurityComponent [​](https://book.cakephp.org/3.x/views/helpers/form.html#working-with-securitycomponent)

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

`Cake\Controller\Component\SecurityComponent` offers several features that make your forms safer and more secure. By simply including the `SecurityComponent` in your controller, you'll automatically benefit from form tampering-prevention features.

As mentioned previously when using SecurityComponent, you should always close your forms using `Cake\View\Helper\FormHelper::end()`. This will ensure that the special `_Token` inputs are generated.

`method` Cake\\View\\Helper\\FormHelper::**unlockField**($name)

*   `$name` - Optional. The dot-separated name for the field.

Unlocks a field making it exempt from the `SecurityComponent` field hashing. This also allows the fields to be manipulated by JavaScript. The `$name` parameter should be the entity property name for the field:

    $this->Form->unlockField('id');

1  

`method` Cake\\View\\Helper\\FormHelper::**secure**(array $fields = \[\], array $secureAttributes = \[\])

*   `$fields` - Optional. An array containing the list of fields to use when generating the hash. If not provided, then `$this->fields` will be used.
*   `$secureAttributes` - Optional. An array of HTML attributes to be passed into the generated hidden input elements.

Generates a hidden `input` field with a security hash based on the fields used in the form or an empty string when secured forms are not in use. If `$secureAttributes` is set, these HTML attributes will be merged into the hidden input tags generated for the SecurityComponent. This is especially useful to set HTML5 attributes like `'form'`.

---

# CakePHP 6 (dev) Documentation - Build Better Web Applications Faster | CakePHP

[Skip to content](https://book.cakephp.org/6.x/#VPContent)

Return to top

Build Better Web Applications, Faster [​](https://book.cakephp.org/6.x/#build-better-web-applications-faster)

==============================================================================================================

**CakePHP 6 (dev)** (currently 6.0.0) is a modern PHP framework running on PHP **8.5** (min. PHP _8.4_) that helps you write clean, maintainable code without the complexity. Whether you're building a simple blog or a complex enterprise application, CakePHP gives you the tools to get it done right.

Perfect for

✅ Developers who value **convention over configuration**  
✅ Teams building **secure, scalable applications**  
✅ Projects that need to **ship quickly** without sacrificing quality  
✅ Applications requiring **modern PHP standards** (PSR-7, PSR-15, PSR-17)

Why CakePHP? [​](https://book.cakephp.org/6.x/#why-cakephp)

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

🚀 **Rapid Development**  
Scaffold applications in minutes with powerful code generation tools.

🔒 **Security First**  
Built-in protection against SQL injection, XSS, CSRF, and more.

📦 **Batteries Included**  
ORM, validation, caching, authentication — everything you need out of the box.

🎯 **Convention over Configuration**  
Sensible defaults mean less setup, more coding.

Quick Start [​](https://book.cakephp.org/6.x/#quick-start)

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

Get a CakePHP application running in under 5 minutes:

ComposerDDEVDocker

bash

    # Create new project
    composer create-project --prefer-dist cakephp/app:~5.0 my_app
    
    # Start development server
    cd my_app
    bin/cake server
    
    # Open http://localhost:8765

1  
2  
3  
4  
5  
6  
7  
8  

bash

    # Setup with DDEV
    mkdir my-cakephp-app && cd my-cakephp-app
    ddev config --project-type=cakephp --docroot=webroot
    ddev composer create --prefer-dist cakephp/app:~5.0
    ddev launch

1  
2  
3  
4  
5  

bash

    # Using official PHP image
    docker run -it --rm -v $(pwd):/app composer create-project \
      --prefer-dist cakephp/app:~5.0 my_app
    
    cd my_app
    docker run -it --rm -p 8765:8765 -v $(pwd):/app \
      -w /app php:8.2-cli php bin/cake server -H 0.0.0.0

1  
2  
3  
4  
5  
6  
7  

TIP

You should see a welcome page with green checkmarks at **[http://localhost:8765](http://localhost:8765/)
**

System Requirements

Make sure your system meets these requirements before getting started:

| Component | Version |
| --- | --- |
| PHP | 8.2 - 8.5 |
| Database | MySQL 5.7+, PostgreSQL 9.6+, SQLite 3, SQL Server 2012+ |
| Extensions | `mbstring`, `intl`, `pdo`, `simplexml` |
| Composer | Latest |

Your First Application [​](https://book.cakephp.org/6.x/#your-first-application)

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

Let's build a simple blog in 10 minutes! Follow along with this hands-on tutorial.

NOTE

This tutorial assumes you already have a database created. Use your database management tool to create a database named `blog` before proceeding.

### Step 1: Configure Database Connection [​](https://book.cakephp.org/6.x/#step-1-configure-database-connection)

Update your database credentials in **config/app\_local.php**:

php

    <?php
    declare(strict_types=1);
    
    return [\
        'Datasources' => [\
            'default' => [\
                'host' => 'localhost',\
                'username' => 'my_user',\
                'password' => 'secret',\
                'database' => 'blog',\
                'encoding' => 'utf8mb4',\
            ],\
        ],\
    ];

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

Configuration Files

*   **config/app.php** - Default configuration (committed to git)
*   **config/app\_local.php** - Local overrides (gitignored)

### Step 2: Create Database Tables [​](https://book.cakephp.org/6.x/#step-2-create-database-tables)

Choose your preferred approach for creating the database schema:

NOTE

**Migrations** are recommended for team projects and production - they're version-controlled and database-agnostic. **Raw SQL** is fine for quick prototyping or if you prefer direct database control.

#### Option A: Using Migrations [​](https://book.cakephp.org/6.x/#option-a-using-migrations)

CommandsMigration FileSeed File

bash

    # Step 1: Generate a migration file
    bin/cake bake migration CreateArticles
    # This creates: config/Migrations/YYYYMMDDHHMMSS_CreateArticles.php
    
    # Step 2: Edit the generated file to define your table structure
    # See the "Migration File" tab for the complete example
    # Open: config/Migrations/YYYYMMDDHHMMSS_CreateArticles.php
    
    # Step 3: Run the migration to create the table
    bin/cake migrations migrate
    
    # Step 4: (Optional) Generate and run seed data
    bin/cake bake seed Articles
    bin/cake migrations seed

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

php

    <?php
    declare(strict_types=1);
    
    // config/Migrations/20240124000000_CreateArticles.php
    use Migrations\BaseMigration;
    
    class CreateArticles extends BaseMigration
    {
        public function change(): void
        {
            $table = $this->table('articles');
            $table->addColumn('title', 'string', ['limit' => 255])
                ->addColumn('slug', 'string', ['limit' => 191])
                ->addColumn('body', 'text', ['null' => true])
                ->addColumn('published', 'boolean', ['default' => false])
                ->addColumn('created', 'datetime')
                ->addColumn('modified', 'datetime')
                ->addIndex(['slug'], ['unique' => true])
                ->create();
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  

php

    <?php
    declare(strict_types=1);
    
    // config/Seeds/ArticlesSeed.php
    use Migrations\BaseSeed;
    
    class ArticlesSeed extends BaseSeed
    {
        public function run(): void
        {
            $data = [\
                [\
                    'title' => 'First Post',\
                    'slug' => 'first-post',\
                    'body' => 'This is my first blog post!',\
                    'published' => true,\
                    'created' => date('Y-m-d H:i:s'),\
                    'modified' => date('Y-m-d H:i:s'),\
                ],\
                [\
                    'title' => 'Second Post',\
                    'slug' => 'second-post',\
                    'body' => 'Another great article.',\
                    'published' => true,\
                    'created' => date('Y-m-d H:i:s'),\
                    'modified' => date('Y-m-d H:i:s'),\
                ],\
            ];
    
            $table = $this->table('articles');
            $table->insert($data)->save();
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  

#### Option B: Using Raw SQL [​](https://book.cakephp.org/6.x/#option-b-using-raw-sql)

MySQLPostgreSQLSQLite

sql

    USE blog;
    
    CREATE TABLE articles (
        id INT AUTO_INCREMENT PRIMARY KEY,
        title VARCHAR(255) NOT NULL,
        slug VARCHAR(191) UNIQUE,
        body TEXT,
        published BOOLEAN DEFAULT FALSE,
        created DATETIME,
        modified DATETIME
    ) ENGINE=InnoDB;
    
    INSERT INTO articles (title, slug, body, published, created, modified)
    VALUES ('First Post', 'first-post', 'This is my first blog post!', TRUE, NOW(), NOW());

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

sql

    \c blog
    
    CREATE TABLE articles (
        id SERIAL PRIMARY KEY,
        title VARCHAR(255) NOT NULL,
        slug VARCHAR(191) UNIQUE,
        body TEXT,
        published BOOLEAN DEFAULT FALSE,
        created TIMESTAMP,
        modified TIMESTAMP
    );
    
    INSERT INTO articles (title, slug, body, published, created, modified)
    VALUES ('First Post', 'first-post', 'This is my first blog post!', TRUE, NOW(), NOW());

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

sql

    CREATE TABLE articles (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        title VARCHAR(255) NOT NULL,
        slug VARCHAR(191) UNIQUE,
        body TEXT,
        published BOOLEAN DEFAULT 0,
        created DATETIME,
        modified DATETIME
    );
    
    INSERT INTO articles (title, slug, body, published, created, modified)
    VALUES ('First Post', 'first-post', 'This is my first blog post!', 1, datetime('now'), datetime('now'));

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

### Step 3: Generate Your First Model [​](https://book.cakephp.org/6.x/#step-3-generate-your-first-model)

Use CakePHP's code generation tool:

bash

    # Generate model classes
    bin/cake bake model Articles
    
    # Output:
    # ✓ Created: src/Model/Table/ArticlesTable.php
    # ✓ Created: src/Model/Entity/Article.php
    # ✓ Created: tests/TestCase/Model/Table/ArticlesTableTest.php

1  
2  
3  
4  
5  
6  
7  

This creates:

ArticlesTable.phpArticle.php

php

    <?php
    declare(strict_types=1);
    
    namespace App\Model\Table;
    
    use Cake\ORM\Table;
    
    class ArticlesTable extends Table
    {
        public function initialize(array $config): void
        {
            parent::initialize($config);
    
            $this->setTable('articles');
            $this->setDisplayField('title');
            $this->setPrimaryKey('id');
    
            $this->addBehavior('Timestamp');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  

php

    <?php
    declare(strict_types=1);
    
    namespace App\Model\Entity;
    
    use Cake\ORM\Entity;
    
    class Article extends Entity
    {
        protected array $_accessible = [\
            'title' => true,\
            'slug' => true,\
            'body' => true,\
            'published' => true,\
            'created' => true,\
            'modified' => true,\
        ];
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

### Step 4: Create Your Controller [​](https://book.cakephp.org/6.x/#step-4-create-your-controller)

Generate a controller with views:

bash

    bin/cake bake controller Articles

1  

php

    <?php
    declare(strict_types=1);
    
    namespace App\Controller;
    
    class ArticlesController extends AppController
    {
        public function index(): void
        {
            $articles = $this->Articles->find('all')
                ->where(['published' => true])
                ->orderBy(['created' => 'DESC']);
    
            $this->set(compact('articles'));
        }
    
        public function view(?string $slug = null): void
        {
            $article = $this->Articles
                ->findBySlug($slug)
                ->firstOrFail();
    
            $this->set(compact('article'));
        }
    
        public function add(): void
        {
            $article = $this->Articles->newEmptyEntity();
    
            if ($this->request->is('post')) {
                $article = $this->Articles->patchEntity(
                    $article,
                    $this->request->getData()
                );
    
                if ($this->Articles->save($article)) {
                    $this->Flash->success('Article saved!');
                    return $this->redirect(['action' => 'index']);
                }
    
                $this->Flash->error('Unable to save article.');
            }
    
            $this->set(compact('article'));
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40  
41  
42  
43  
44  
45  
46  

### Step 5: Create Your Views [​](https://book.cakephp.org/6.x/#step-5-create-your-views)

Create a simple list view in **templates/Articles/index.php**:

php

    <h1>Blog Articles</h1>
    
    <?php foreach ($articles as $article): ?>
        <article>
            <h2>
                <?= $this->Html->link(
                    h($article->title),
                    ['action' => 'view', $article->slug]
                ) ?>
            </h2>
            <p>
                <small>Published: <?= $article->created->format('F d, Y') ?></small>
            </p>
            <p><?= h($article->body) ?></p>
        </article>
    <?php endforeach; ?>
    
    <?= $this->Html->link('New Article', ['action' => 'add'], ['class' => 'button']) ?>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

TIP

Visit **[http://localhost:8765/articles](http://localhost:8765/articles)
** to see your blog in action!

Next Steps [​](https://book.cakephp.org/6.x/#next-steps)

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

Now that you've built your first CakePHP application, here are some great places to continue your journey:

**Learn the Fundamentals:**

*   [CakePHP Conventions](https://book.cakephp.org/6.x/intro/conventions.html)
     - Understanding the naming conventions that power CakePHP
*   [MVC Pattern](https://book.cakephp.org/6.x/intro.html)
     - How CakePHP structures applications
*   [Configuration](https://book.cakephp.org/6.x/development/configuration.html)
     - Customizing your application

**Build Real Applications:**

*   [Tutorials & Examples](https://book.cakephp.org/6.x/tutorials-and-examples.html)
     - Step-by-step guides
*   [CMS Tutorial](https://book.cakephp.org/6.x/tutorials-and-examples/cms/installation.html)
     - Build a complete content management system

**Master Core Features:**

*   [Database & ORM](https://book.cakephp.org/6.x/orm.html)
     - Advanced queries, associations, and data modeling
*   [Controllers](https://book.cakephp.org/6.x/controllers.html)
     - Request handling, components, and middleware
*   [Views](https://book.cakephp.org/6.x/views.html)
     - Templates, helpers, and rendering
*   [Security](https://book.cakephp.org/6.x/security.html)
     - Best practices for secure applications

Get Help [​](https://book.cakephp.org/6.x/#get-help)

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

Join our community and get the support you need:

[Join Discord](https://discord.com/invite/k4trEMPebj)
 [Join Slack](https://cakephp.slack.com/)
 [Discourse Forum](https://discourse.cakephp.org/)

**Additional Resources:**

*   [API Documentation](https://api.cakephp.org/5.0/)
     - Complete API reference
*   [Stack Overflow](https://stackoverflow.com/questions/tagged/cakephp)
     - Find answers to common questions

How CakePHP Works [​](https://book.cakephp.org/6.x/#how-cakephp-works)

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

Understanding the request flow helps you build better applications. Here's what happens when a user visits your CakePHP application:

![CakePHP request flow diagram](https://book.cakephp.org/6.x/typical-cake-request.png)

**A typical request follows these steps:**

1.  🌐 **Request arrives** → Webserver routes to `webroot/index.php`
2.  ⚙️ **Application boots** → Your app is loaded and middleware initializes
3.  🛣️ **Routing** → Request is matched to a controller and action
4.  🎮 **Controller** → Action is called, interacts with Models
5.  📊 **Model Layer** → Fetches and processes data from the database
6.  🎨 **View Layer** → Renders the response (HTML, JSON, XML, etc.)
7.  📤 **Response sent** → Back through middleware to the client

Understanding MVC

The **Model** handles your data and business logic, the **Controller** coordinates the request, and the **View** presents the data. This separation keeps your code organized and testable.

[Learn more about MVC in CakePHP →](https://book.cakephp.org/6.x/intro.html)

Everything You Need, Out of the Box [​](https://book.cakephp.org/6.x/#everything-you-need-out-of-the-box)

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

CakePHP comes with powerful features that save you time and help you build better applications:

🚀 Code Generation (Bake)

Generate complete CRUD applications in seconds:

bash

    bin/cake bake all Articles
    # Creates: Model, Controller, Views, Tests

1  
2  

Bake can scaffold entire features, saving hours of repetitive coding. Perfect for prototyping or generating boilerplate.

[Learn more about Bake →](https://book.cakephp.org/bake/2/en/)

💾 Caching Framework

Integrated caching with multiple backends:

php

    // Cache expensive operations
    $results = Cache::remember('expensive_query', function () {
        return $this->Articles->find('complex')->toArray();
    });

1  
2  
3  
4  

**Supported backends:** Redis, Memcached, APCu, File, Database

[Learn more about Caching →](https://book.cakephp.org/6.x/core-libraries/caching.html)

🧪 Built-in Testing

Write tests with confidence using the integrated testing framework:

php

    public function testAddArticle(): void
    {
        $this->post('/articles/add', ['title' => 'Test']);
        $this->assertResponseOk();
        $this->assertFlashMessage('Article saved!');
    }

1  
2  
3  
4  
5  
6  

Supports unit tests, integration tests, and browser tests out of the box.

[Learn more about Testing →](https://book.cakephp.org/6.x/development/testing.html)

🔐 Authentication & Authorization

Drop-in user management with flexible policies:

bash

    composer require cakephp/authentication cakephp/authorization

1  

Handle login, permissions, and access control with minimal configuration.

[Authentication Guide →](https://book.cakephp.org/authentication/)
 • [Authorization Guide →](https://book.cakephp.org/authorization/)

🌐 REST API Support

Build APIs with automatic content type negotiation:

php

    // Automatically serves JSON/XML based on Accept header
    public function index()
    {
        $articles = $this->Articles->find('all');
        $this->set('articles', $articles);
        $this->viewBuilder()->setOption('serialize', ['articles']);
    }

1  
2  
3  
4  
5  
6  
7  

Supports JSON, XML, and custom formats with minimal code.

[Learn more about REST →](https://book.cakephp.org/6.x/development/rest.html)

📦 Database Migrations

Version control your database schema:

bash

    bin/cake bake migration CreateArticles
    bin/cake migrations migrate

1  
2  

Keep your database changes in sync across development, staging, and production.

[Learn more about Migrations →](https://book.cakephp.org/migrations/)

What Makes CakePHP Special? [​](https://book.cakephp.org/6.x/#what-makes-cakephp-special)

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

Convention Over ConfigurationPowerful ORMBuilt-in SecurityCode Generation

php

    <?php
    declare(strict_types=1);
    
    // No configuration needed! CakePHP automatically knows:
    // - ArticlesController uses ArticlesTable
    // - ArticlesTable uses 'articles' database table
    // - Primary key is 'id'
    // - Foreign keys end in '_id'
    // - Templates are in templates/Articles/
    
    class ArticlesController extends AppController
    {
        // That's it! Table is auto-loaded
        public function index(): void
        {
            $articles = $this->Articles->find('all');
            $this->set(compact('articles'));
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  

php

    <?php
    declare(strict_types=1);
    
    // Elegant query building with relationships
    $popularArticles = $this->Articles->find()
        ->contain(['Users', 'Comments'])
        ->matching('Tags', function ($q) {
            return $q->where(['Tags.name IN' => ['PHP', 'CakePHP']]);
        })
        ->where(['Articles.published' => true])
        ->orderBy(['Articles.view_count' => 'DESC'])
        ->limit(10);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

php

    <?php
    declare(strict_types=1);
    
    // Automatic protection against common vulnerabilities:
    // ✓ SQL Injection (parameterized queries)
    // ✓ CSRF attacks (token validation)
    // ✓ XSS (auto-escaping in templates)
    // ✓ Mass assignment (protected fields)
    
    $article = $this->Articles->newEntity($data);
    // Only $_accessible fields can be set

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

bash

    # Generate complete CRUD in seconds
    bin/cake bake all Articles
    
    # Creates:
    # ✓ Model (Table + Entity)
    # ✓ Controller (with all actions)
    # ✓ Templates (index, view, add, edit)
    # ✓ Tests (full coverage)

1  
2  
3  
4  
5  
6  
7  
8  

![Ready to Build Something Amazing](https://cakephp.org/img/share_cake_bg_chiffon.svg)

Ready to Build Something Amazing?

**Start your CakePHP journey today and join thousands of developers building modern web applications.**

[Get Started →](https://book.cakephp.org/6.x/quickstart)
•[Join Community](https://discourse.cakephp.org/)
•[View Examples](https://book.cakephp.org/6.x/tutorials-and-examples)

---

# Welcome | CakePHP

[Skip to content](https://book.cakephp.org/2.x/#VPContent)

Return to top

Welcome [​](https://book.cakephp.org/2.x/#welcome)

===================================================

Unsupported Version

You are viewing documentation for an **unsupported version** of CakePHP. For the most recent stable version, please visit the [official documentation](https://book.cakephp.org/)
.

The CakePHP cookbook is an openly developed and community editable documentation project. We hope to maintain a high level of quality, validity and accuracy for the documentation. Notice the "Improve this Doc" button in the upper right-hand corner; it will direct you to the GitHub online editor of the active page, allowing you to easily contribute any additions, deletions, or corrections to the documentation.

**Read the Book Anywhere**

![image](https://book.cakephp.org/2.x/read-the-book.jpg)

Enjoy the CakePHP cookbook almost anywhere. Available as both a PDF and EPUB, you can now read it on more devices, as well as offline.

*   [PDF](https://book.cakephp.org/_downloads/en/CakePHPCookbook.pdf)
    
*   [EPUB](https://book.cakephp.org/_downloads/en/CakePHPCookbook.epub)
    
*   [Original Source](https://github.com/cakephp/docs)
    

Getting Started [​](https://book.cakephp.org/2.x/#getting-started)

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

### Build a Blog [​](https://book.cakephp.org/2.x/#build-a-blog)

Get started with the [blog tutorial](https://book.cakephp.org/2.x/tutorials-and-examples/blog/blog.html)
. You'll learn the basics of CakePHP, and build a basic blog in the process.

### Conventions [​](https://book.cakephp.org/2.x/#conventions)

Learn about a typical [CakePHP request](https://book.cakephp.org/2.x/getting-started/a-typical-cakephp-request.html)
 and the [conventions](https://book.cakephp.org/2.x/getting-started/cakephp-conventions.html)
 that power CakePHP.

### Controllers [​](https://book.cakephp.org/2.x/#controllers)

Controllers handle requests and help co-ordinate and prepare responses for the client. Read more about [Controllers](https://book.cakephp.org/2.x/controllers.html)
.

### Views [​](https://book.cakephp.org/2.x/#views)

Views are the presentation layer in CakePHP. They convert the data fetched from Models into the output format requested by the client. Read more about [Views](https://book.cakephp.org/2.x/views.html)
.

### Models [​](https://book.cakephp.org/2.x/#models)

Models are the heart of your application. They handle the validation, storage and retrieval of your data. Read more about [Models](https://book.cakephp.org/2.x/models.html)
.

Getting Help [​](https://book.cakephp.org/2.x/#getting-help)

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

If you're stuck, there are a number of places [you can get help](https://book.cakephp.org/2.x/cakephp-overview/where-to-get-help.html)
.

---

# Welcome | CakePHP

[Skip to content](https://book.cakephp.org/4.x/#VPContent)

Return to top

Welcome [​](https://book.cakephp.org/4.x/#welcome)

===================================================

Unsupported Version

You are viewing documentation for a **previous version** of CakePHP. For the most recent stable version, please visit the [official documentation](https://book.cakephp.org/)
.

CakePHP 4 is a web development framework running on PHP **8.2** (min. PHP _7.4_). Read [CakePHP at a Glance](https://book.cakephp.org/4.x/intro.html)
 to get an introduction to the fundamentals of CakePHP.

The CakePHP book is an openly developed and community editable documentation project. Notice the pencil icon button fixated against the right wall; it will direct you to the GitHub online editor of the active page, allowing you to contribute any additions, deletions, or corrections to the documentation.

**Read the Book Anywhere**

![image](https://book.cakephp.org/4.x/read-the-book.jpg)

Enjoy the CakePHP book almost anywhere. Available as both a PDF and EPUB, you can now read it on more devices, as well as offline.

*   [PDF](https://book.cakephp.org/_downloads/en/CakePHPBook.pdf)
    
*   [EPUB](https://book.cakephp.org/_downloads/en/CakePHP.epub)
    
*   [Original Source](https://github.com/cakephp/docs)
    

Getting Help [​](https://book.cakephp.org/4.x/#getting-help)

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

If you're stuck, there are a number of places [you can get help](https://book.cakephp.org/4.x/intro/where-to-get-help.html)
.

First Steps [​](https://book.cakephp.org/4.x/#first-steps)

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

Learning a new framework can be intimidating and exciting at the same time. To help you along, we have created a cookbook packed with examples and recipes to get the common tasks completed. If you are new, you should start off with the [Quick Start Guide](https://book.cakephp.org/4.x/quickstart.html)
 as it will give you a quick tour of what CakePHP has to offer and how it works.

After you've finished the Quickstart tutorial, you can brush up on the key elements in a CakePHP application:

*   The [CakePHP request cycle](https://book.cakephp.org/4.x/intro.html#request-cycle)
    
*   The [conventions](https://book.cakephp.org/4.x/intro/conventions.html)
     that CakePHP uses.
*   [Controllers](https://book.cakephp.org/4.x/controllers.html)
     handle requests and co-ordinate your models and the responses your application creates.
*   [Views](https://book.cakephp.org/4.x/views.html)
     are the presentation layer in your application. They give you powerful tools to create HTML, JSON and the other outputs your application needs.
*   [Models](https://book.cakephp.org/4.x/orm.html)
     are the key ingredient in any application. They handle validation, and domain logic within your application.

---

# Url | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/views/helpers/url.html#VPContent)

Return to top

Url [​](https://book.cakephp.org/3.x/ja/views/helpers/url.html#url)

====================================================================

`class` Cake\\View\\Helper\\**UrlHelper**(View $view, array $config = \[\])

UrlHelper は他のヘルパーから URL を生成することが容易になります。 アプリケーションのヘルパーでコアヘルパーをオーバーライドすることによって URL の生成方法を カスタマイズする単一の場所を提供します。このやり方は [Aliasing Helpers](https://book.cakephp.org/3.x/ja/views/helpers.html#aliasing-helpers)
 セクションをご覧ください。

URL の生成 [​](https://book.cakephp.org/3.x/ja/views/helpers/url.html#url-%E3%81%AE%E7%94%9F%E6%88%90)

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

`method` Cake\\View\\Helper\\UrlHelper::**build**(mixed $url = null, boolean|array $full = false)

コントローラーとアクションの組み合わせを指定することで URL を生成して返します。 `$url` が空の場合、 `REQUEST_URI` を返します。そうでない場合、 コントローラーとアクションの組み合わせで URL を生成します。 `full` が `true` の場合、結果がフルベース URL で返されます。 :

    echo $this->Url->build([\
        "controller" => "Posts",\
        "action" => "view",\
        "bar",\
    ]);
    
    // 出力結果
    /posts/view/bar

1  
2  
3  
4  
5  
6  
7  
8  

さらにいつかの使用例は、こちら:

拡張子つきの URL:

    echo $this->Url->build([\
        "controller" => "Posts",\
        "action" => "list",\
        "_ext" => "rss",\
    ]);
    
    // 出力結果
    /posts/list.rss

1  
2  
3  
4  
5  
6  
7  
8  

フルベース URL を前につけた ('/' から始まる) URL:

    echo $this->Url->build('/posts', true);
    
    // 出力結果
    http://somedomain.com/posts

1  
2  
3  
4  

GET パラメーターとフラグメントアンカーの URL:

    echo $this->Url->build([\
        "controller" => "Posts",\
        "action" => "search",\
        "?" => ["foo" => "bar"],\
        "#" => "first",\
    ]);
    
    // 出力結果
    /posts/search?foo=bar#first

1  
2  
3  
4  
5  
6  
7  
8  
9  

上記の例で使用している `?` キーは、あなたが使用しているクエリー文字列パラメーターを 明示したい場合やクエリー文字列パラメーターをあなたのルートプレースホルダーの一つと名前を 共有したい場合に便利です。

名前付きルートの URL:

    echo $this->Url->build(['_name' => 'product-page', 'slug' => 'i-m-slug']);
    
    // 以下のようにルートをセットアップすることを仮定:
    // $router->connect(
    //     '/products/:slug',
    //     [\
    //         'controller' => 'Products',\
    //         'action' => 'view',\
    //     ],
    //     [\
    //         '_name' => 'product-page',\
    //     ]
    // );
    /products/i-m-slug

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

第２パラメーターは、HTML エスケープやベースパスを追加するかどうかを制御するオプションを 定義できます。 :

    $this->Url->build('/posts', [\
        'escape' => false,\
        'fullBase' => true,\
    ]);

1  
2  
3  
4  

以下は、アセットタイムスタンプ付きの URL が `<link rel="preload"/>` で囲まれており、 フォントをプリロードしています。注意: ファイルは存在していなければならず、 `Configure::read('Asset.timestamp')` は、タイムスタンプを追加するために `true` または `'force'` を返さなければなりません。 :

    echo $this->Html->meta([\
        'rel' => 'preload',\
        'href' => $this->Url->assetUrl(\
            '/assets/fonts/yout-font-pack/your-font-name.woff2'\
        ),\
        'as' => 'font',\
    ]);

1  
2  
3  
4  
5  
6  
7  

Added in version 3.3.5

`build()` は、3.3.5 より第２引数として配列を受け取ります。

Added in version 3.6.0

`timestamp` オプションが `build()` に追加されました。

CSS や JavaScript、または画像ファイルの URL を生成する場合、 これらのアセットタイプのためのヘルパーメソッドがあります。 :

    // 出力結果 /img/icon.png
    $this->Url->image('icon.png');
    
    // 出力結果 /js/app.js
    $this->Url->script('app.js');
    
    // 出力結果 /css/app.css
    $this->Url->css('app.css');
    
    // メソッドの呼び出し時にタイムスタンプを強制
    $this->Url->css('app.css', ['timestamp' => 'force']);
    
    // または、メソッド呼び出し時にタイムスタンプを無効化
    $this->Url->css('app.css', ['timestamp' => false]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

Added in version 3.2.4

アセットヘルパーメソッドは 3.2.4 で追加されました。

Added in version 3.6.0

`timestamp` オプションが、アセットのヘルパーメソッドに追加されました。

詳細は API の [Router::url](https://api.cakephp.org/3.x/class-Cake.Routing.Router.html#_url)
 を確認してください。

---

# CakePHP の利用 | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/topics.html#VPContent)

Return to top

CakePHP の利用 [​](https://book.cakephp.org/3.x/ja/topics.html#cakephp-%E3%81%AE%E5%88%A9%E7%94%A8)

=================================================================================================

CakePHP のすべての重要な部分の紹介

*   [インストール](https://book.cakephp.org/3.x/ja/installation.html)
    
*   [構成設定](https://book.cakephp.org/3.x/ja/development/configuration.html)
    
*   [ルーティング](https://book.cakephp.org/3.x/ja/development/routing.html)
    
*   [リクエストとレスポンスオブジェクト](https://book.cakephp.org/3.x/ja/controllers/request-response.html)
    
*   [コントローラー](https://book.cakephp.org/3.x/ja/controllers.html)
    
*   [コンポーネント](https://book.cakephp.org/3.x/ja/controllers/components.html)
    
*   [ページコントローラー](https://book.cakephp.org/3.x/ja/controllers/pages-controller.html)
    
*   [ビュー](https://book.cakephp.org/3.x/ja/views.html)
    
*   [ビューセル](https://book.cakephp.org/3.x/ja/views/cells.html)
    
*   [ヘルパー](https://book.cakephp.org/3.x/ja/views/helpers.html)
    
*   [JSON と XML ビュー](https://book.cakephp.org/3.x/ja/views/json-and-xml-views.html)
    
*   [データベースアクセス & ORM](https://book.cakephp.org/3.x/ja/orm.html)
    
*   [テーブルオブジェクト](https://book.cakephp.org/3.x/ja/orm/table-objects.html)
    
*   [クエリービルダー](https://book.cakephp.org/3.x/ja/orm/query-builder.html)
    
*   [エンティティー](https://book.cakephp.org/3.x/ja/orm/entities.html)
    
*   [エラーと例外の処理](https://book.cakephp.org/3.x/ja/development/errors.html)
    
*   [キャッシュ](https://book.cakephp.org/3.x/ja/core-libraries/caching.html)
    
*   [ロギング](https://book.cakephp.org/3.x/ja/core-libraries/logging.html)
    
*   [モデルのないフォーム](https://book.cakephp.org/3.x/ja/core-libraries/form.html)
    
*   [セッション](https://book.cakephp.org/3.x/ja/development/sessions.html)
    
*   [REST](https://book.cakephp.org/3.x/ja/development/rest.html)
    
*   [AuthComponent](https://book.cakephp.org/3.x/ja/controllers/components/authentication.html)
    
*   [ページネーション](https://book.cakephp.org/3.x/ja/controllers/components/pagination.html)
    
*   [クロスサイトリクエストフォージェリ](https://book.cakephp.org/3.x/ja/controllers/components/csrf.html)
    
*   [Email](https://book.cakephp.org/3.x/ja/core-libraries/email.html)
    
*   [Form](https://book.cakephp.org/3.x/ja/views/helpers/form.html)
    
*   [Html](https://book.cakephp.org/3.x/ja/views/helpers/html.html)
    
*   [バリデーション](https://book.cakephp.org/3.x/ja/core-libraries/validation.html)
    
*   [テスト](https://book.cakephp.org/3.x/ja/development/testing.html)
    
*   [デプロイ](https://book.cakephp.org/3.x/ja/deployment.html)
    
*   [コンソールツール、シェルとタスク](https://book.cakephp.org/3.x/ja/console-and-shells.html)
    
*   [貢献](https://book.cakephp.org/3.x/ja/contributing.html)
    
*   [チュートリアルと例](https://book.cakephp.org/3.x/ja/tutorials-and-examples.html)

---

# ブックマークチュートリアル | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/intro.html#VPContent)

Return to top

ブックマークチュートリアル [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/intro.html#%E3%83%95%E3%82%99%E3%83%83%E3%82%AF%E3%83%9E%E3%83%BC%E3%82%AF%E3%83%81%E3%83%A5%E3%83%BC%E3%83%88%E3%83%AA%E3%82%A2%E3%83%AB)

==============================================================================================================================================================================================================================

このチュートリアルは簡単なブックマークのためのアプリケーション (bookmarker) を作ります。 はじめに CakePHP のインストールを行い、データベースの作成、 そしてアプリケーションを素早く仕上げるための CakePHP が提供するツールを使います。

必要なもの:

1.  データベースサーバー。このチュートリアルでは MySQL サーバーを使います。 データベースを作成するための SQL の知識が必要です。CakePHP は、それを前提としています。 MySQL を使用するとき、 PHP で `pdo_mysql` が有効になっていることを確認してください。
2.  基礎的な PHP の知識。

始める前に、最新の PHP バージョンであることを確認してください。

    php -v

1  

最低でも PHP _5.6_ (CLI) 以上をインストールしてください。 あなたのウェブサーバーの PHP バージョンもまた、_5.6_ 以上でなければなりません。そして、 コマンドラインインターフェイス (CLI) の PHP バージョンと同じバージョンがベストです。 完全なアプリケーションを確認したい場合、 [cakephp/bookmarker](https://github.com/cakephp/bookmarker-tutorial)
 をチェックアウトしてください。 さあ、はじめましょう!

CakePHP の取得 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/intro.html#cakephp-%E3%81%AE%E5%8F%96%E5%BE%97)

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

最も簡単な CakePHP のインストール方法は Composer を使う方法です。Composer は、 ターミナルやコマンドラインプロンプトから CakePHP をインストールするためのシンプルな方法です。 まだ準備ができていない場合、最初に Composer をダウンロードとインストールが必要です。 cURL がインストールされていたら、以下のように実行するのが簡単です。 :

    curl -s https://getcomposer.org/installer | php
    

もしくは [Composer のウェブサイト](https://getcomposer.org/download/)
 から `composer.phar` をダウンロードすることができます。

そして、CakePHP アプリケーションのスケルトンを **bookmarker** ディレクトリーにインストールするために、 インストールディレクトリーからターミナルに以下の行をシンプルにタイプしてください。 :

    php composer.phar create-project --prefer-dist cakephp/app:^3.8 bookmarker
    

[Composer Windows Installer](https://getcomposer.org/Composer-Setup.exe)
 をダウンロードして実行した場合、インストールディレクトリー (例えば、 C:\\wamp\\www\\dev\\cakephp3) からターミナルに以下の行をタイプしてください。 :

    composer self-update && composer create-project --prefer-dist cakephp/app:^3.8 bookmarker
    

Composer を使うメリットは、 正しいファイルパーミッションの設定や、 **config/app.php** ファイルの作成などのように、自動的に完全なセットアップをしてくれることです。

CakePHP をインストールする他の方法があります。 Composer を使いたくない場合、 [インストール](https://book.cakephp.org/3.x/ja/installation.html)
 セクションをご覧ください.

CakePHP のダウンロードやインストール方法にかかわらず、いったんセットアップが完了すると、 ディレクトリー構成は以下のようになります。 :

    /bookmarker
        /bin
        /config
        /logs
        /plugins
        /src
        /tests
        /tmp
        /vendor
        /webroot
        .editorconfig
        .gitignore
        .htaccess
        .travis.yml
        composer.json
        index.php
        phpunit.xml.dist
        README.md
    

CakePHP のディレクトリー構造がどのように働くかを学ぶのにいい機会かもしれません。 [CakePHP のフォルダー構成](https://book.cakephp.org/3.x/ja/intro/cakephp-folder-structure.html)
 セクションをご覧ください。

インストールの確認 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/intro.html#%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB%E3%81%AE%E7%A2%BA%E8%AA%8D)

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

デフォルトホームページを確認することで、インストールが正しいことをざっと確かめることができます。 その前に、開発用サーバーを起動する必要があります。 :

    bin/cake server
    

NOTE

Windows では、このコマンドは `bin\cake server` (バックスラッシュ) です。

これで、 8765 ポートで PHP のビルトインウェブサーバーが起動します。ウェルカムページを見るために **[http://localhost:8765](http://localhost:8765/)
** をウェブブラウザーで開いてください。CakePHP がデータベース接続が 可能かどうか以外は、すべての確認事項がチェック済みになるべきです。そうでなければ、PHP 拡張の 追加のインストールやディレクトリーのパーミッション設定が必要かもしれません。

データベースの作成 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/intro.html#%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%83%98%E3%82%99%E3%83%BC%E3%82%B9%E3%81%AE%E4%BD%9C%E6%88%90)

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

次に、ブックマークアプリケーションのデータベースをセットアップしましょう。 まだセットアップしていない場合、例えば `cake_bookmarks` のように、あなたの好きな名前で、 このチュートリアルで使用する空のデータベースを作成してください。必要なテーブルを作成するために、 以下の SQL を実行することができます。 :

    CREATE TABLE users (
        id INT AUTO_INCREMENT PRIMARY KEY,
        email VARCHAR(255) NOT NULL,
        password VARCHAR(255) NOT NULL,
        created DATETIME,
        modified DATETIME
    );
    
    CREATE TABLE bookmarks (
        id INT AUTO_INCREMENT PRIMARY KEY,
        user_id INT NOT NULL,
        title VARCHAR(50),
        description TEXT,
        url TEXT,
        created DATETIME,
        modified DATETIME,
        FOREIGN KEY user_key (user_id) REFERENCES users(id)
    );
    
    CREATE TABLE tags (
        id INT AUTO_INCREMENT PRIMARY KEY,
        title VARCHAR(255),
        created DATETIME,
        modified DATETIME,
        UNIQUE KEY (title)
    );
    
    CREATE TABLE bookmarks_tags (
        bookmark_id INT NOT NULL,
        tag_id INT NOT NULL,
        PRIMARY KEY (bookmark_id, tag_id),
        FOREIGN KEY tag_key(tag_id) REFERENCES tags(id),
        FOREIGN KEY bookmark_key(bookmark_id) REFERENCES bookmarks(id)
    );

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  

複合主キーを持つ `bookmarks_tags` テーブルにお気づきでしょうか。CakePHP は、 ほぼどこでも複合主キーをサポートします。それは、マルチテナントなアプリケーションの構築が しやすくなります。

私たちが使用するテーブルやカラムの名前は恣意的ではありませんでした。CakePHP の [命名規則](https://book.cakephp.org/3.x/ja/intro/conventions.html)
 を使用することによって、CakePHP がより効果的になり、 フレームワークの設定を避けられます。CakePHP はレガシーなデータベーススキーマに対応できるくらい 十分に柔軟ですが、規約に従うことで、時間を節約できます。

データベースの設定 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/intro.html#%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%83%98%E3%82%99%E3%83%BC%E3%82%B9%E3%81%AE%E8%A8%AD%E5%AE%9A)

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

次に、どこにデータベースあるか、そしてどうやってテータベースに接続するかを CakePHP に伝えましょう。おそらく、これが何らかの設定が必要となる最初で最後です。

この設定はとても単純です。あなたのセットアップを適用するために **config/app.php** ファイルの中の `Datasources.default` 配列の値を置き換えてください。 完全な設定配列の例は、以下のようになります。 :

    return [\
        // More configuration above.\
        'Datasources' => [\
            'default' => [\
                'className' => 'Cake\Database\Connection',\
                'driver' => 'Cake\Database\Driver\Mysql',\
                'persistent' => false,\
                'host' => 'localhost',\
                'username' => 'cakephp',\
                'password' => 'AngelF00dC4k3~',\
                'database' => 'cake_bookmarks',\
                'encoding' => 'utf8',\
                'timezone' => 'UTC',\
                'cacheMetadata' => true,\
            ],\
        ],\
        // More configuration below.\
    ];

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

１度 **config/app.php** ファイルを保存して、 'CakePHP is able to connect to the database' がチェック済みであることを確認してください。

NOTE

CakePHP のデフォルト設定ファイルは **config/app.default.php** にあります。

Scaffold コードの生成 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/intro.html#scaffold-%E3%82%B3%E3%83%BC%E3%83%88%E3%82%99%E3%81%AE%E7%94%9F%E6%88%90)

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

データベースが CakePHP の命名規則に従っているので、 基本的なアプリケーションを 素早く生成するために [bake コンソール](https://book.cakephp.org/3.x/ja/bake/usage.html)
 アプリケーションが使用できます。 コマンドライン上で、以下のコマンドを実行してください。 :

    // Windows 上では、代わりに bin\cake を使用する必要があります。
    bin/cake bake all users
    bin/cake bake all bookmarks
    bin/cake bake all tags

1  
2  
3  
4  

これは、 users、 bookmarks、 tags リソースのためのコントローラー、モデル、ビュー、 それらに対応するテストケース、フィクスチャーを生成します。あなたのサーバーが停止している場合、 再起動して **[http://localhost:8765/bookmarks](http://localhost:8765/bookmarks)
** に行ってください。

アプリケーションのデータベーステーブルへのデータアクセスを提供する基本的だが機能的な アプリケーションを見てください。１度、ブックマーク一覧を表示して、いくつかの ユーザー、ブックマーク、タグを追加してください。

パスワードハッシュを追加 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/intro.html#%E3%83%8F%E3%82%9A%E3%82%B9%E3%83%AF%E3%83%BC%E3%83%88%E3%82%99%E3%83%8F%E3%83%83%E3%82%B7%E3%83%A5%E3%82%92%E8%BF%BD%E5%8A%A0)

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

(**[http://localhost:8765/users](http://localhost:8765/users)
** にアクセスして) ユーザーを作成した時、パスワードが平文で保存されることにおそらく気づくでしょう。 これはセキュリティの観点から、とても良くありませんので修正しましょう。

これはまた、CakePHP のモデル層について説明する良い機会です。CakePHP では、 オブジェクトの集合と、異なるクラスの単一オブジェクトを操作する方法を分けてます。 エンティティーの集合は、 `Table` クラス内に格納され、１つのレコードに属する機能は、 `Entity` クラス内に格納されます。

例えば、パスワードのハッシュ化は、個々のレコードで行われ、エンティティーオブジェクトに この振る舞いを実装します。パスワードがセットされるたびにハッシュ化したいので、 ミューテーターメソッドやセッターメソッドを使います。CakePHP は規約に基づいて、 エンティティーの一つにプロパティーをセットするセッターメソッドを呼びます。 では、パスワードのためのセッターを追加してみましょう。 **src/Model/Entity/User.php** に 以下を追加してください。 :

    namespace App\Model\Entity;
    
    use Cake\Auth\DefaultPasswordHasher; // この行を追加してください
    use Cake\ORM\Entity;
    
    class User extends Entity
    {
    
        // bake で生成されたコード
    
        protected function _setPassword($value)
        {
            $hasher = new DefaultPasswordHasher();
            return $hasher->hash($value);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  

今から既存のユーザーのパスワードを更新してくだい。パスワードを変更した際、一覧もしくは詳細ページで、 入力した値の代わりにハッシュ化されたパスワードがあることを確認してください。CakePHP は、 デフォルトで [bcrypt](https://codahale.com/how-to-safely-store-a-password/)
 を使ってパスワードをハッシュ化します。既存のデータベースが動作している場合、 sha1 や md5 も 使用できます。

NOTE

パスワードがハッシュ化されない場合、セッター関数の命名について、 クラスのパスワードメンバーと大文字小文字が同じかを確認してください。

タグを指定してブックマークを取得 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/intro.html#%E3%82%BF%E3%82%AF%E3%82%99%E3%82%92%E6%8C%87%E5%AE%9A%E3%81%97%E3%81%A6%E3%83%95%E3%82%99%E3%83%83%E3%82%AF%E3%83%9E%E3%83%BC%E3%82%AF%E3%82%92%E5%8F%96%E5%BE%97)

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

これで、パスワードを安全に保存できますので、アプリケーションにもっと面白い機能を構築できます。 一度ブックマークのコレクションを蓄えて、タグでの検索ができるようになると便利です。 次は、タグでのブックマークを検索するため、ルート、コントローラーのアクション、finder メソッドを実装します。

理想的には、 **[http://localhost:8765/bookmarks/tagged/funny/cat/gifs](http://localhost:8765/bookmarks/tagged/funny/cat/gifs)
** のような URL にしたいと思います。この URL は、 'funny', 'cat', もしくは 'gifs' タグが付いたブックマークすべてを検索することを意図しています。これを実装する前に、 新しいルートを追加します。 **config/routes.php** を以下のようにしてください。 :

    <?php
    use Cake\Routing\Route\DashedRoute;
    use Cake\Routing\Router;
    
    Router::defaultRouteClass(DashedRoute::class);
    
    // 新しいルートを　tagged アクションのために追加します。
    // 末尾の `*` は、渡された引数を持っていることを
    // CakePHP に伝えます。
    Router::scope(
        '/bookmarks',
        ['controller' => 'Bookmarks'],
        function ($routes) {
            $routes->connect('/tagged/*', ['action' => 'tags']);
        }
    );
    
    Router::scope('/', function ($routes) {
        // デフォルトのホームと /pages/* ルートへの接続
        $routes->connect('/', [\
            'controller' => 'Pages',\
            'action' => 'display', 'home'\
        ]);
        $routes->connect('/pages/*', [\
            'controller' => 'Pages',\
            'action' => 'display'\
        ]);
    
        // デフォルトのルートへ接続
        $routes->fallbacks();
    });

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  

上記は、 **/bookmarks/tagged/** パスを `BookmarksController::tags()` に接続する 新しい「ルート」を定義します。ルートを定義することによて、 URL の見た目と、 それらどのように実装されたかを分離することができます。 **[http://localhost:8765/bookmarks/tagged](http://localhost:8765/bookmarks/tagged)
** にアクセスした場合、CakePHP から コントローラーのアクションがないことを伝える役に立つエラーページが表示されます。 今から存在しないメソッドを実装してみましょう。 **src/Controller/BookmarksController.php** に以下を追加してください。 :

    public function tags()
    {
        // CakePHP によって提供された 'pass' キーは全ての
        // リクエストにある渡された URL のパスセグメントです。
        $tags = $this->request->getParam('pass');
    
        // タグ付きのブックマークを探すために BookmarksTable を使用
        $bookmarks = $this->Bookmarks->find('tagged', [\
            'tags' => $tags\
        ]);
    
        // ビューテンプレートに変数を渡します
        $this->set([\
            'bookmarks' => $bookmarks,\
            'tags' => $tags\
        ]);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

リクエストデータの他の部分にアクセスするためには [Cake Request](https://book.cakephp.org/3.x/ja/controllers/request-response.html#cake-request)
 セクションを 参考にしてください。

### Finder メソッドの作成 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/intro.html#finder-%E3%83%A1%E3%82%BD%E3%83%83%E3%83%88%E3%82%99%E3%81%AE%E4%BD%9C%E6%88%90)

CakePHP では、コントローラーのアクションをスリムに保ち、アプリケーションの多くのロジックを モデルに置くことをお勧めします。 **/bookmarks/tagged** の URL にアクセスした場合、 `findTagged()` メソッドがまだ実装されていないエラーが表示されます。 **src/Model/Table/BookmarksTable.php** に以下を追加してください。 :

    // $query 引数は、クエリービルダーのインスタンスです。
    // $options 配列には、コントローラーのアクション中で find('tagged') に渡した
    // 'tag' オプションが含まれます。
    public function findTagged(Query $query, array $options)
    {
        $bookmarks = $this->find()
            ->select(['id', 'url', 'title', 'description']);
    
        if (empty($options['tags'])) {
            $bookmarks
                ->leftJoinWith('Tags')
                ->where(['Tags.title IS' => null]);
        } else {
            $bookmarks
                ->innerJoinWith('Tags')
                ->where(['Tags.title IN ' => $options['tags']]);
        }
    
        return $bookmarks->group(['Bookmarks.id']);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  

[カスタム Finder メソッド](https://book.cakephp.org/3.x/ja/orm/retrieving-data-and-resultsets.html#custom-find-methods)
 を実装しました。 これは、再利用可能なクエリーをまとめることを実現する CakePHP の非常に強力な概念です。 Finder メソッドは、常に [クエリービルダー](https://book.cakephp.org/3.x/ja/orm/query-builder.html)
 オブジェクトとオプション配列を パラメーターとして取得します。Finder メソッドは、クエリーを操作し、任意の必須条件や抽出条件を 追加することができます。完了時、Finder メソッドは更新されたクエリーオブジェクトを 返さなければなりません。finder の中で、一致するタグを持つ特定のブックマークを検索するために、 `innerJoinWith()` 、 `where()` そして `group` メソッドを使います。 タグの指定がない場合、タグなしでブックマークを検索するために `leftJoinWith()` を使用して、 'where' 条件を変更します。

### ビューの作成 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/intro.html#%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC%E3%81%AE%E4%BD%9C%E6%88%90)

**/bookmarks/tagged** の URL にアクセスすると、 CakePHP は、ビューファイルがないことを 知らせるエラーを表示します。次に、ビューファイルを `tags()` アクションのために作りましょう。 **src/Template/Bookmarks/tags.ctp** に以下の内容を追加します。 :

    <h1>
        Bookmarks tagged with
        <?= $this->Text->toList(h($tags)) ?>
    </h1>
    
    <section>
    <?php foreach ($bookmarks as $bookmark): ?>
        <article>
            <!-- リンクを作成するために HtmlHelper を使用 -->
            <h4><?= $this->Html->link($bookmark->title, $bookmark->url) ?></h4>
            <small><?= h($bookmark->url) ?></small>
    
            <!-- テキストを整形するために TextHelper を使用 -->
            <?= $this->Text->autoParagraph(h($bookmark->description)) ?>
        </article>
    <?php endforeach; ?>
    </section>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

上記のコードは [Html](https://book.cakephp.org/3.x/ja/views/helpers/html.html)
 と [Text](https://book.cakephp.org/3.x/ja/views/helpers/text.html)
 を ビューの出力生成を補助するために使いました。また、 HTML エンコード出力するために `h` ショートカット関数を使いました。HTML インジェクション問題を防ぐために ユーザーデータ出力時には、必ず `h()` を使用することを覚えておいて下さい。

ビューテンプレートファイルのための CakePHP の規約に従って **tags.ctp** ファイルを作りました。 この規約は、小文字を使い、コントローラーのアクション名をアンダースコアー化したテンプレート名にすることです。

ビューで `$tags` や `$bookmarks` 変数を使えることにお気づきでしょう。 コントローラーで `set()` メソッドを使って、指定した変数をビューに送るためにセットします。 ビューは、渡されたすべての変数をテンプレート内でローカル変数として利用可能にします。

**/bookmarks/tagged/funny** の URL にアクセスできるようにして、 全ての 'funny' でタグ付けされたブックマークを確認しましょう。

ここまで、ブックマーク、タグ、ユーザーを管理する基本的なアプリケーションを作成してきました。 しかしながら、全員のタグが全員に見えてしまいます。次の章では、認証を実装し、現在のユーザーに 属するブックマークのみを表示するよう制限します。

あなたのアプリケーションの構築を続けるために [ブックマークチュートリアル パート2](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/part-two.html)
 を読み続けるか、 CakePHP で出来ることをより詳しく学ぶために [ドキュメントの中に飛び込んで](https://book.cakephp.org/3.x/ja/topics.html)
 ください。

---

# ブックマークチュートリアル パート2 | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/part-two.html#VPContent)

Return to top

ブックマークチュートリアル パート2 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/part-two.html#%E3%83%95%E3%82%99%E3%83%83%E3%82%AF%E3%83%9E%E3%83%BC%E3%82%AF%E3%83%81%E3%83%A5%E3%83%BC%E3%83%88%E3%83%AA%E3%82%A2%E3%83%AB-%E3%83%8F%E3%82%9A%E3%83%BC%E3%83%882)

============================================================================================================================================================================================================================================================================

[チュートリアルの前編](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/intro.html)
 を終えると、 ごく基本的なブックマークアプリケーションができているでしょう。このチャプターでは認証機能と 各ユーザーが自分のブックマークだけを閲覧/編集できるように制限する機能を追加します。

ログインを追加 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/part-two.html#%E3%83%AD%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E3%82%92%E8%BF%BD%E5%8A%A0)

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

CakePHP では、認証は [コンポーネント](https://book.cakephp.org/3.x/ja/controllers/components.html)
 によって制御されます。 コンポーネントは再利用可能な特定の機能や概念を作成するための方法と考えることができます。 コンポーネントもまた、コントローラーのイベントのライフサイクルをフックすることでアプリケーションに 作用することができます。初めに、 [AuthComponent](https://book.cakephp.org/3.x/ja/controllers/components/authentication.html)
 をアプリケーションに追加しましょう。 すべてのメソッドに認証を必須にすることをおすすめします。では AuthComponent を AppController に追加しましょう。 :

    // src/Controller/AppController.php の中で
    namespace App\Controller;
    
    use Cake\Controller\Controller;
    
    class AppController extends Controller
    {
        public function initialize()
        {
            $this->loadComponent('Flash');
            $this->loadComponent('Auth', [\
                'authenticate' => [\
                    'Form' => [\
                        'fields' => [\
                            'username' => 'email',\
                            'password' => 'password'\
                        ]\
                    ]\
                ],\
                'loginAction' => [\
                    'controller' => 'Users',\
                    'action' => 'login'\
                ],\
                'unauthorizedRedirect' => $this->referer() // 未認証時、元のページを返します。\
            ]);
    
            // PagesController が動作し続けるように
            // display アクションを許可
            $this->Auth->allow(['display']);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  

これで、 `Flash` と `Auth` のコンポーネントを読み込むと CakePHP に示しました。 さらに users テーブルの `email` をユーザー名として使用するように AuthComponent の設定を カスタマイズしました。何かの URL にアクセスすると **/users/login** に遷移するようになりますが、 まだそのコードが存在しないというエラーページが表示されるでしょう。 それでは、ログインアクションを作成しましょう。 :

    // src/Controller/UsersController.php の中で
    public function login()
    {
        if ($this->request->is('post')) {
            $user = $this->Auth->identify();
            if ($user) {
                $this->Auth->setUser($user);
                return $this->redirect($this->Auth->redirectUrl());
            }
            $this->Flash->error('あなたのユーザー名またはパスワードが不正です。');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

さらに **src/Template/Users/login.ctp** に以下のように追記します。 :

    <h1>Login</h1>
    <?= $this->Form->create() ?>
    <?= $this->Form->control('email') ?>
    <?= $this->Form->control('password') ?>
    <?= $this->Form->button('Login') ?>
    <?= $this->Form->end() ?>

1  
2  
3  
4  
5  
6  

NOTE

`control()` は 3.4 以降で使用可能です。それより前のバージョンでは、代わりに `input()` を使用してください。

これでシンプルなログインフォームができました。ハッシュ化されたパスワードを持つユーザーで ログインすることができるはずです。

NOTE

もしハッシュ化されたパスワードを持つユーザーがいなければ、 `loadComponent('Auth')` の行をコメントアウトして、ユーザーを編集して新しいパスワードを保存して下さい。

ログアウトを追加 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/part-two.html#%E3%83%AD%E3%82%AF%E3%82%99%E3%82%A2%E3%82%A6%E3%83%88%E3%82%92%E8%BF%BD%E5%8A%A0)

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

これで人々はログインできますので、ログアウトする方法も同じように提供したいでしょう。 ここでも `UsersController` に以下のコードを追加します。 :

    public function initialize()
    {
        parent::initialize();
        $this->Auth->allow(['logout']);
    }
    
    public function logout()
    {
        $this->Flash->success('ログアウトしました。');
        return $this->redirect($this->Auth->logout());
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

このコードは、パブリックなアクションでログアウトのメソッドとして `logout` アクションを ホワイトリストに加えます。これで `/users/logout` にアクセスするとログアウトされて ログインページに遷移します。

新規登録を有効にする [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/part-two.html#%E6%96%B0%E8%A6%8F%E7%99%BB%E9%8C%B2%E3%82%92%E6%9C%89%E5%8A%B9%E3%81%AB%E3%81%99%E3%82%8B)

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

ログインしていない状態で **/users/add** にアクセスした場合、ログインページに遷移してしまうでしょう。 人々がアプリケーションにサインアップできるように修正しましょう。 `UsersController` に以下を 追記します。 :

    public function initialize()
    {
        parent::initialize();
        // 許可するアクション一覧に 'add' アクションを追加
        $this->Auth->allow(['logout', 'add']);
    }

1  
2  
3  
4  
5  
6  

上記では `add()` アクションは認証や許可が不要であることを `AuthComponent` に示しています。 **Users/add.ctp** をクリーンアップする時間を作り、誤解を招くようなリンクを削除しても、 このまま次のセクションに進んでもかまいません。このチュートリアルではユーザーの編集、 表示または一覧は構築しません。 それらのアクションは `AuthComponent` が拒否します。

ブックマークへのアクセスを制限する [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/part-two.html#%E3%83%95%E3%82%99%E3%83%83%E3%82%AF%E3%83%9E%E3%83%BC%E3%82%AF%E3%81%B8%E3%81%AE%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9%E3%82%92%E5%88%B6%E9%99%90%E3%81%99%E3%82%8B)

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

ユーザーがログインできるようになったので、ユーザーが自分が作成したブックマークだけを表示できるよう 制限しましょう。これは 'authorization' アダプタを使用して制限します。 要件は非常に単純です。 いくつかの簡単なコードを `BookmarksController` に書きます。 しかし、これをやる前にアプリケーションがどのようにアクションを許可するかを AuthComponent に示しましょう。 `AppController` に以下を追加します。 :

    public function isAuthorized($user)
    {
        return false;
    }

1  
2  
3  
4  

また、 `AppController` の `Auth` の設定を以下のように追加します。 :

    'authorize' => 'Controller',

1  

`initialize()` メソッドはこのようになります。 :

    public function initialize()
    {
        $this->loadComponent('Flash');
        $this->loadComponent('Auth', [\
            'authorize'=> 'Controller',//この行を追加\
            'authenticate' => [\
                'Form' => [\
                    'fields' => [\
                        'username' => 'email',\
                        'password' => 'password'\
                    ]\
                ]\
            ],\
            'loginAction' => [\
                'controller' => 'Users',\
                'action' => 'login'\
            ],\
            'unauthorizedRedirect' => $this->referer()\
        ]);
    
        // PagesController が動作し続けるように
        // display アクションを許可
        $this->Auth->allow(['display']);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  

デフォルトではアクセスを拒否し、必要に応じて一つづつアクセス権を付与しましょう。 はじめに、ブックマークに許可ロジックを追加します。 `BookmarksController` に以下を追加します。 :

    public function isAuthorized($user)
    {
        $action = $this->request->getParam('action');
    
        // add と index アクションは常に許可します。
        if (in_array($action, ['index', 'add', 'tags'])) {
            return true;
        }
        // その他のすべてのアクションは、id を必要とします。
        if (!$this->request->getParam('pass.0')) {
            return false;
        }
    
        // ブックマークが現在のユーザーに属するかどうかをチェック
        $id = $this->request->getParam('pass.0');
        $bookmark = $this->Bookmarks->get($id);
        if ($bookmark->user_id == $user['id']) {
            return true;
        }
        return parent::isAuthorized($user);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  

これで、自分のものではないブックマークを表示または編集、削除しようとすると、 元のページにリダイレクトされるはずです。もし、エラーメッセージが表示されないなら、 レイアウトに以下を追加してください。 :

    // src/Template/Layout/default.ctp の中で
    <?= $this->Flash->render() ?>

1  
2  

これで許可エラーメッセージが表示されるはずです。

一覧表示とフォームを修正する [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/part-two.html#%E4%B8%80%E8%A6%A7%E8%A1%A8%E7%A4%BA%E3%81%A8%E3%83%95%E3%82%A9%E3%83%BC%E3%83%A0%E3%82%92%E4%BF%AE%E6%AD%A3%E3%81%99%E3%82%8B)

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

詳細と削除が動作する一方で、追加と一覧表示には少し問題があります:

1.  ブックマークを追加するときにユーザーを選べる
2.  ブックマークを編集するときにユーザーを選べる
3.  一覧ページに他のユーザーのブックマークが表示される

まず追加のフォームから取り組みましょう。はじめに **src/Template/Bookmarks/add.ctp** から `control('user_id')` を削除します。 削除したら、 **src/Controller/BookmarksController.php** の `add()` アクションを以下のように修正します。 :

    public function add()
    {
        $bookmark = $this->Bookmarks->newEntity();
        if ($this->request->is('post')) {
            $bookmark = $this->Bookmarks->patchEntity($bookmark, $this->request->getData());
            $bookmark->user_id = $this->Auth->user('id');
            if ($this->Bookmarks->save($bookmark)) {
                $this->Flash->success('ブックマークを保存しました。');
                return $this->redirect(['action' => 'index']);
            }
            $this->Flash->error('ブックマークは保存できませんでした。もう一度お試しください。');
        }
        $tags = $this->Bookmarks->Tags->find('list');
        $this->set(compact('bookmark', 'tags'));
        $this->set('_serialize', ['bookmark']);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  

エンティティーのプロパティーにセッションデータを設定することで、ブックマークがほかのユーザーに変更される 可能性を排除しています。編集フォームとアクションも同様にします。 **src/Controller/BookmarksController.php** の `edit()` アクションを以下のようにします。 :

    public function edit($id = null)
    {
        $bookmark = $this->Bookmarks->get($id, [\
            'contain' => ['Tags']\
        ]);
        if ($this->request->is(['patch', 'post', 'put'])) {
            $bookmark = $this->Bookmarks->patchEntity($bookmark, $this->request->getData());
            $bookmark->user_id = $this->Auth->user('id');
            if ($this->Bookmarks->save($bookmark)) {
                $this->Flash->success('ブックマークを保存しました。');
                return $this->redirect(['action' => 'index']);
            }
            $this->Flash->error('ブックマークは保存できませんでした。もう一度お試しください。');
        }
        $tags = $this->Bookmarks->Tags->find('list');
        $this->set(compact('bookmark', 'tags'));
        $this->set('_serialize', ['bookmark']);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

### 一覧表示 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/part-two.html#%E4%B8%80%E8%A6%A7%E8%A1%A8%E7%A4%BA)

さて、現在ログインしているユーザーのブックマークだけを表示する必要があります。 `paginate()` の呼び出しを修正をすることでそのようにできます。 **src/Controller/BookmarksController.php** の `index()` アクションを以下のようにします。 :

    public function index()
    {
        $this->paginate = [\
            'conditions' => [\
                'Bookmarks.user_id' => $this->Auth->user('id'),\
            ]\
        ];
        $this->set('bookmarks', $this->paginate($this->Bookmarks));
        $this->set('_serialize', ['bookmarks']);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

同様に `tags()` アクションと関連する検索メソッドを修正しましょう。 これはあなた自身で完了できるように宿題として残しておきます。

タグ付け機能を改良する [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/part-two.html#%E3%82%BF%E3%82%AF%E3%82%99%E4%BB%98%E3%81%91%E6%A9%9F%E8%83%BD%E3%82%92%E6%94%B9%E8%89%AF%E3%81%99%E3%82%8B)

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

現在は、 `TagsController` ではすべてのアクセスが拒否されるため、新しいタグを追加することは困難です。 アクセスを許可する代わりに、カンマ区切りのテキストフィールドを使用してタグ選択 UI を改良できます。 これはユーザーに良い体験を与え、ORM の素晴らしい機能をさらに使うことができます。

### 計算済みフィールドを追加 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/part-two.html#%E8%A8%88%E7%AE%97%E6%B8%88%E3%81%BF%E3%83%95%E3%82%A3%E3%83%BC%E3%83%AB%E3%83%88%E3%82%99%E3%82%92%E8%BF%BD%E5%8A%A0)

エンティティーの整形済みのタグを取得する簡単な方法が必要なので、バーチャル/計算済みのフィールドを エンティティーに追加しましょう。 **src/Model/Entity/Bookmark.php** に以下を追加します。 :

    use Cake\Collection\Collection;
    
    protected function _getTagString()
    {
        if (isset($this->_properties['tag_string'])) {
            return $this->_properties['tag_string'];
        }
        if (empty($this->tags)) {
            return '';
        }
        $tags = new Collection($this->tags);
        $str = $tags->reduce(function ($string, $tag) {
            return $string . $tag->title . ', ';
        }, '');
        return trim($str, ', ');
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  

計算済みのプロパティー `$bookmark->tag_string` にアクセスできるようになります。 このプロパティーはあとで入力時に使用します。 あとで保存するので `tag_string` プロパティーを エンティティーの `_accessible` リストに追加することを忘れないでください。

**src/Model/Entity/Bookmark.php** で `$_accessible` に `tag_string` を このように追加してください。 :

    protected $_accessible = [\
        'user_id' => true,\
        'title' => true,\
        'description' => true,\
        'url' => true,\
        'user' => true,\
        'tags' => true,\
        'tag_string' => true,\
    ];

1  
2  
3  
4  
5  
6  
7  
8  
9  

### ビューを修正する [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/part-two.html#%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC%E3%82%92%E4%BF%AE%E6%AD%A3%E3%81%99%E3%82%8B)

エンティティーを修正するとタグ用の新しいインプットを追加することができます。 **src/Template/Bookmarks/add.ctp** と **src/Template/Bookmarks/edit.ctp** の すでにある `tags._ids` のインプットを以下と置き換えます。 :

    echo $this->Form->control('tag_string', ['type' => 'text']);

1  

### タグ文字列を保存する [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/part-two.html#%E3%82%BF%E3%82%AF%E3%82%99%E6%96%87%E5%AD%97%E5%88%97%E3%82%92%E4%BF%9D%E5%AD%98%E3%81%99%E3%82%8B)

これで存在するタグを文字列として表示できます。同様にデータを保存したいでしょう。 `tag_string` をアクセス可能に設定したので、ORM はリクエストからエンティティーにデータをコピーします。 `beforeSave()` フックメソッドを使用して、タグ文字列を解析し、関連するエンティティーを検索/構築します。 **src/Model/Table/BookmarksTable.php** に以下を追加します。 :

    public function beforeSave($event, $entity, $options)
    {
        if ($entity->tag_string) {
            $entity->tags = $this->_buildTags($entity->tag_string);
        }
    }
    
    protected function _buildTags($tagString)
    {
        // タグに trim 適用
        $newTags = array_map('trim', explode(',', $tagString));
        // すべての空のタグを削除
        $newTags = array_filter($newTags);
        // 重複するタグの削減
        $newTags = array_unique($newTags);
    
        $out = [];
        $query = $this->Tags->find()
            ->where(['Tags.title IN' => $newTags]);
    
        // 新しいタグの一覧から既存のタグを削除
        foreach ($query->extract('title') as $existing) {
            $index = array_search($existing, $newTags);
            if ($index !== false) {
                unset($newTags[$index]);
            }
        }
        // 既存のタグの追加
        foreach ($query as $tag) {
            $out[] = $tag;
        }
        // 新しいタグの追加
        foreach ($newTags as $tag) {
            $out[] = $this->Tags->newEntity(['title' => $tag]);
        }
        return $out;
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  

このコードはこれまでに行ったことよりも少し複雑ですが、これは CakePHP の ORM がいかに強力かを お見せするのに役立ちます。 [コレクション](https://book.cakephp.org/3.x/ja/core-libraries/collections.html)
 メソッドを使用してクエリー結果を 操作することができます。また、エンティティーをその場で容易に作成するシナリオを扱うことができます。

まとめ [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/bookmarks/part-two.html#%E3%81%BE%E3%81%A8%E3%82%81)

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

認証と基本的な許可/アクセス制御シナリオを処理できるようブックマークアプリケーションを拡張してきました。 また、FormHelper と ORM の機能を活用することで、いくつかの素晴らしい UX の改善を追加しました。

CakePHP を探求する時間を割いていただきありがとうございます。次は [ブログチュートリアル](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog/blog.html)
 を完了するか、 [データベースアクセス & ORM](https://book.cakephp.org/3.x/ja/orm.html)
 について更に学ぶか、もしくは [CakePHP の利用](https://book.cakephp.org/3.x/ja/topics.html)
 を熟読してください。

---

# Phinx マイグレーション | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/phinx.html#VPContent)

Return to top

Phinx マイグレーション [​](https://book.cakephp.org/3.x/ja/phinx.html#phinx-%E3%83%9E%E3%82%A4%E3%82%AF%E3%82%99%E3%83%AC%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3)

=======================================================================================================================================================

このページは [移動しました](https://book.cakephp.org/phinx/0/ja/)
 。

---

# CMS チュートリアル - タグとユーザー | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/tags-and-users.html#VPContent)

Return to top

CMS チュートリアル - タグとユーザー [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/tags-and-users.html#cms-%E3%83%81%E3%83%A5%E3%83%BC%E3%83%88%E3%83%AA%E3%82%A2%E3%83%AB-%E3%82%BF%E3%82%AF%E3%82%99%E3%81%A8%E3%83%A6%E3%83%BC%E3%82%B5%E3%82%99%E3%83%BC)

================================================================================================================================================================================================================================================================

基本的な記事の作成機能が作成されたので、複数の作成者が CMS で作業できるようにしましょう。 前回は、全てのモデル、ビュー、コントローラーを手作業で構築していました。今度は、 [Bake コンソール](https://book.cakephp.org/3.x/ja/bake.html)
 を使ってスケルトンコードを作成します。 Bake は、CakePHP が `CRUD (Create, Read, Update, Delete)` アプリケーションのスケルトンを とても効率的に作成するために、規約を活用した強力なコード生成 `CLI (Command Line Interface)` ツールです。ユーザーコードを構築するために `bake` を使ってみましょう。

    cd /path/to/our/app
    
    bin/cake bake model users
    bin/cake bake controller users
    bin/cake bake template users

1  
2  
3  
4  
5  

これらの3つのコマンドは次を生成します。

*   テーブル、エンティティー、フィクスチャーファイル
*   コントローラー
*   CRUD テンプレート
*   生成された各クラスのテストケース

Bake はまた、CakePHP の規約を使用して、モデルが持つ関連付けやバリデーションを推測します。

記事へのタグ付けの追加 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/tags-and-users.html#%E8%A8%98%E4%BA%8B%E3%81%B8%E3%81%AE%E3%82%BF%E3%82%AF%E3%82%99%E4%BB%98%E3%81%91%E3%81%AE%E8%BF%BD%E5%8A%A0)

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

複数のユーザーが私たちの小さな `CMS` にアクセスすることができれば、 私たちのコンテンツを分類することができればうれしいでしょう。 ユーザーがコンテンツに自由形式のカテゴリーやラベルを作成するためにタグを使用します。 ここでも、アプリケーション用のスケルトンコードを素早く生成するために `bake` を使います。

    # 一度にすべてのコードを生成します。
    bin/cake bake all tags

1  
2  

足場になるコードを作成したら、 **[http://localhost:8765/tags/add](http://localhost:8765/tags/add)
** に移動して サンプルタグをいくつか作成します。

Tags テーブルが作成されたので、Articles と Tags の関連付けを作成できます。 ArticlesTable の `initialize` メソッドに以下を追加することで、 これを行うことができます。 :

    public function initialize(array $config)
    {
        $this->addBehavior('Timestamp');
        $this->belongsToMany('Tags'); // この行を追加
    }

1  
2  
3  
4  
5  

テーブルの作成時に CakePHP の規約に従ったので、この関連付けは簡単な定義で動作します。 詳しくは、 [アソシエーション - モデル同士を繋ぐ](https://book.cakephp.org/3.x/ja/orm/associations.html)
 をご覧ください。

タグ付けを有効にする記事の更新 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/tags-and-users.html#%E3%82%BF%E3%82%AF%E3%82%99%E4%BB%98%E3%81%91%E3%82%92%E6%9C%89%E5%8A%B9%E3%81%AB%E3%81%99%E3%82%8B%E8%A8%98%E4%BA%8B%E3%81%AE%E6%9B%B4%E6%96%B0)

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

アプリケーションにタグが付いたので、ユーザーが記事にタグを付けるようにする必要があります。 まず `add` アクションを次のように更新してください。 :

    // src/Controller/ArticlesController.php の中で
    
    namespace App\Controller;
    
    use App\Controller\AppController;
    
    class ArticlesController extends AppController
    {
        public function add()
        {
            $article = $this->Articles->newEntity();
            if ($this->request->is('post')) {
                $article = $this->Articles->patchEntity($article, $this->request->getData());
    
        // user_id の決め打ちは一時的なもので、あとで認証を構築する際に削除されます。
                $article->user_id = 1;
    
                if ($this->Articles->save($article)) {
                    $this->Flash->success(__('Your article has been saved.'));
                    return $this->redirect(['action' => 'index']);
                }
                $this->Flash->error(__('Unable to add your article.'));
            }
            // タグのリストを取得
            $tags = $this->Articles->Tags->find('list');
    
            // ビューコンテキストに tags をセット
            $this->set('tags', $tags);
    
            $this->set('article', $article);
        }
    
        // 他のアクション
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  

追加された行は `id => title` の連想配列としてタグのリストを読み込みます。 この形式で、テンプレートに新しいタグ入力を作成できます。 **src/Template/Articles/add.ctp** のコントロールの PHP ブロックに以下を追加してください。 :

    echo $this->Form->control('tags._ids', ['options' => $tags]);

1  

これは、 `$tags` 変数を使用してセレクトボックスのオプションを生成する複数選択要素を描画します。 次のセクションでタグで記事を見つける機能を追加しますので、タグを持つ新しい記事を2つ作成してください。

また、 `edit` メソッドを更新して、タグの追加や編集を許可する必要があります。 edit メソッドは次のようになります。 :

    public function edit($slug)
    {
        $article = $this->Articles
            ->findBySlug($slug)
            ->contain('Tags') // 関連づけられた Tags を読み込む
            ->firstOrFail();
        if ($this->request->is(['post', 'put'])) {
            $this->Articles->patchEntity($article, $this->request->getData());
            if ($this->Articles->save($article)) {
                $this->Flash->success(__('Your article has been updated.'));
                return $this->redirect(['action' => 'index']);
            }
            $this->Flash->error(__('Unable to update your article.'));
        }
    
        // タグのリストを取得
        $tags = $this->Articles->Tags->find('list');
    
        // ビューコンテキストに tags をセット
        $this->set('tags', $tags);
    
        $this->set('article', $article);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  

**add.ctp** テンプレートに追加した新しいタグの複数選択コントロールを **src/Template/Articles/edit.ctp** テンプレートに追加することを忘れないでください。

タグによる記事の検索 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/tags-and-users.html#%E3%82%BF%E3%82%AF%E3%82%99%E3%81%AB%E3%82%88%E3%82%8B%E8%A8%98%E4%BA%8B%E3%81%AE%E6%A4%9C%E7%B4%A2)

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

ユーザーがコンテンツを分類すると、使用したタグでそのコンテンツを探したいと思うでしょう。 この機能のために、記事をタグで検索するためのルート、コントローラーのアクション、そして ファインダーメソッドを実装します。

理想的には、 **[http://localhost:8765/articles/tagged/funny/cat/gifs](http://localhost:8765/articles/tagged/funny/cat/gifs)
** のような URL になります。 これにより、「funny」、「cat」、または「gifs」タグを持つすべての記事を見つけることができます。 これを実装する前に、新しいルートを追加します。 **config/routes.php** は次のようになるはずです。 :

    <?php
    use Cake\Core\Plugin;
    use Cake\Routing\Route\DashedRoute;
    use Cake\Routing\Router;
    
    Router::defaultRouteClass(DashedRoute::class);
    
    // タグ付けられたアクションのために追加された新しいルート。
    // 末尾の `*` は、このアクションがパラメーターを渡されることを
    // CakePHP に伝えます。
    Router::scope(
        '/articles',
        ['controller' => 'Articles'],
        function ($routes) {
            $routes->connect('/tagged/*', ['action' => 'tags']);
        }
    );
    
    Router::scope('/', function ($routes) {
        // デフォルトの home と /pages/* ルートを接続。
        $routes->connect('/', [\
            'controller' => 'Pages',\
            'action' => 'display', 'home'\
        ]);
        $routes->connect('/pages/*', [\
            'controller' => 'Pages',\
            'action' => 'display'\
        ]);
    
        // 規約に基づいたデフォルトルートを接続。
        $routes->fallbacks();
    });
    
    Plugin::routes();

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  

上記は、 **/articles/tagged/** パスを `ArticlesController::tags()` に接続する、新しい 「ルート」を定義します。ルートを定義することにより、URL の外観とそれらの実装方法を分離することが できます。 **[http://localhost:8765/articles/tagged](http://localhost:8765/articles/tagged)
** にアクセスすると、コントローラーの アクションが存在しないことを知らせる CakePHP の役に立つエラーページが表示されます。 その足りないメソッドを今から実装しましょう。 **src/Controller/ArticlesController.php** の中で、次のように追加してください。 :

    public function tags()
    {
        // 'pass' キーは CakePHP によって提供され、リクエストに渡された
        // 全ての URL パスセグメントを含みます。
        $tags = $this->request->getParam('pass');
    
        // ArticlesTable を使用してタグ付きの記事を検索します。
        $articles = $this->Articles->find('tagged', [\
            'tags' => $tags\
        ]);
    
        // 変数をビューテンプレートのコンテキストに渡します。
        $this->set([\
            'articles' => $articles,\
            'tags' => $tags\
        ]);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

リクエストデータの他の部分にアクセスするには、 [Cake Request](https://book.cakephp.org/3.x/ja/controllers/request-response.html#cake-request)
 セクションを参照してください。

渡された引数はメソッドのパラメーターとして渡されるので、 PHP の可変引数を使ってアクションを記述することもできます。 :

    public function tags(...$tags)
    {
        // ArticlesTable を使用してタグ付きの記事を検索します。
        $articles = $this->Articles->find('tagged', [\
            'tags' => $tags\
        ]);
    
        // 変数をビューテンプレートのコンテキストに渡します。
        $this->set([\
            'articles' => $articles,\
            'tags' => $tags\
        ]);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

### ファインダーメソッドの追加 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/tags-and-users.html#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%B3%E3%82%BF%E3%82%99%E3%83%BC%E3%83%A1%E3%82%BD%E3%83%83%E3%83%88%E3%82%99%E3%81%AE%E8%BF%BD%E5%8A%A0)

CakePHP では、コントローラーのアクションをスリムに保ち、アプリケーションのロジックのほとんどを モデルレイヤーに入れたいと思っています。 **/articles/tagged** URL にアクセスすると、 `findTagged()` メソッドがまだ実装されていないというエラーが表示されます。 **src/Model/Table/ArticlesTable.php** の中で次を追加してください。 :

    // この use 文を名前空間宣言のすぐ下に追加して、
    // Query クラスをインポートします
    use Cake\ORM\Query;
    
    // $query 引数はクエリービルダーのインスタンスです。
    // $options 配列には、コントローラーのアクションで find('tagged') に渡した
    // "tags" オプションが含まれています。
    public function findTagged(Query $query, array $options)
    {
        $columns = [\
            'Articles.id', 'Articles.user_id', 'Articles.title',\
            'Articles.body', 'Articles.published', 'Articles.created',\
            'Articles.slug',\
        ];
    
        $query = $query
            ->select($columns)
            ->distinct($columns);
    
        if (empty($options['tags'])) {
            // タグが指定されていない場合は、タグのない記事を検索します。
            $query->leftJoinWith('Tags')
                ->where(['Tags.title IS' => null]);
        } else {
            // 提供されたタグが1つ以上ある記事を検索します。
            $query->innerJoinWith('Tags')
                ->where(['Tags.title IN' => $options['tags']]);
        }
    
        return $query->group(['Articles.id']);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  

私たちは [カスタムファインダーメソッド](https://book.cakephp.org/3.x/ja/orm/retrieving-data-and-resultsets.html#custom-find-methods)
 を実装しました。 これは CakePHP の非常に強力な概念で、再利用可能なクエリーをパッケージ化することができます。 ファインダーメソッドは常に [クエリービルダー](https://book.cakephp.org/3.x/ja/orm/query-builder.html)
 オブジェクトと options 配列を パラメーターとして取得します。ファインダーはクエリーを操作し、必須条件や抽出条件を追加できます。 完了したら、ファインダーメソッドは変更されたクエリーオブジェクトを返す必要があります。 上記のファインダーでは、 `distinct()` と `leftJoin()` メソッドを利用して、 '一致する' タグを持つ記事を見つけることができます。

### ビューの作成 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/tags-and-users.html#%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC%E3%81%AE%E4%BD%9C%E6%88%90)

**/articles/tagged** URL にもう一度アクセスすると、CakePHP は新しいエラーを表示して、 ビューファイルが作成されていないことを知らせます。 次は、 `tags()` アクションのビューファイルを作成しましょう。 **src/Template/Articles/tags.ctp** の中に次の内容を入れてください。 :

    <h1>
        Articles tagged with
        <?= $this->Text->toList(h($tags), 'or') ?>
    </h1>
    
    <section>
    <?php foreach ($articles as $article): ?>
        <article>
            <!-- リンクの作成に HtmlHelper を使用 -->
            <h4><?= $this->Html->link(
                $article->title,
                ['controller' => 'Articles', 'action' => 'view', $article->slug]
            ) ?></h4>
            <span><?= h($article->created) ?></span>
        </article>
    <?php endforeach; ?>
    </section>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

上記のコードの中で、 ビュー出力を支援するために [Html](https://book.cakephp.org/3.x/ja/views/helpers/html.html)
 ヘルパーと [Text](https://book.cakephp.org/3.x/ja/views/helpers/text.html)
 ヘルパーを使用します。また、HTML エンコード出力のために `h` ショートカット関数を使用します。HTML インジェクションの問題を防ぐために データを出力するときは、常に `h()` を使うことを忘れないでください。

先ほど作成した **tags.ctp** ファイルは、ビューテンプレートファイルの CakePHP 規約に従います。 コントローラーのアクション名を小文字とアンダースコアーに変えたものをテンプレートに使用することが 規約です。

ビューテンプレートに `$tags` と `$articles` 変数を使うことができることに気付くかもしれません。 コントローラーで `set()` メソッドを使う際、ビューに送る特定の変数を設定します。 ビューは、渡されたすべての変数をテンプレートスコープでローカル変数として使用可能にします。

以上で **/articles/tagged/funny** の URL にアクセスして、「funny」とタグ付けされたすべての記事を 見ることができます。

タグ付け体験の改善 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/tags-and-users.html#%E3%82%BF%E3%82%AF%E3%82%99%E4%BB%98%E3%81%91%E4%BD%93%E9%A8%93%E3%81%AE%E6%94%B9%E5%96%84)

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

現在、新しいタグを追加するのは面倒なプロセスです。作成者は、使用したいタグをすべて事前に作成する必要が あります。カンマ区切りのテキストフィールドを使用してタグ選択 UI を改善することができます。 これにより、ユーザーにとってより良い体験を提供し、ORM でさらに優れた機能を使用することができます。

### 計算フィールドの追加 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/tags-and-users.html#%E8%A8%88%E7%AE%97%E3%83%95%E3%82%A3%E3%83%BC%E3%83%AB%E3%83%88%E3%82%99%E3%81%AE%E8%BF%BD%E5%8A%A0)

エンティティーの書式設定されたタグに簡単にアクセスできるようにするため、仮想/計算フィールドを エンティティーに追加できます。 **src/Model/Entity/Article.php** の中で次を追加してください。 :

    // この use 文を名前空間宣言のすぐ下に追加して、
    // Collection クラスをインポートします
    use Cake\Collection\Collection;
    
    protected function _getTagString()
    {
        if (isset($this->_properties['tag_string'])) {
            return $this->_properties['tag_string'];
        }
        if (empty($this->tags)) {
            return '';
        }
        $tags = new Collection($this->tags);
        $str = $tags->reduce(function ($string, $tag) {
            return $string . $tag->title . ', ';
        }, '');
        return trim($str, ', ');
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

これにより `$article->tag_string` の計算されたプロパティにアクセスできます。 後でコントロールでこのプロパティーを使用します。

### ビューの更新 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/tags-and-users.html#%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC%E3%81%AE%E6%9B%B4%E6%96%B0)

エンティティーが更新されると、タグの新しいコントロールを追加できます。 **src/Template/Articles/add.ctp** と **src/Template/Articles/edit.ctp** の中で、 既存の `tags._ids` コントロールを次のものに置き換えてください。 :

    echo $this->Form->control('tag_string', ['type' => 'text']);

1  

### タグ文字列の永続化 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/tags-and-users.html#%E3%82%BF%E3%82%AF%E3%82%99%E6%96%87%E5%AD%97%E5%88%97%E3%81%AE%E6%B0%B8%E7%B6%9A%E5%8C%96)

既存のタグを文字列として表示できるようになったので、そのデータも保存したいと考えています。 `tag_string` をアクセス可能とマークしたので、ORM はそのデータをリクエストから エンティティーにコピーします。`beforeSave()` フックメソッドを使用してタグ文字列を解析し、 関連するエンティティーを検索/構築することができます。 **src/Model/Table/ArticlesTable.php** に次を追加してください。 :

    public function beforeSave($event, $entity, $options)
    {
        if ($entity->tag_string) {
            $entity->tags = $this->_buildTags($entity->tag_string);
        }
    
        // 他のコード
    }
    
    protected function _buildTags($tagString)
    {
        // タグをトリミング
        $newTags = array_map('trim', explode(',', $tagString));
        // 全てのからのタグを削除
        $newTags = array_filter($newTags);
        // 重複するタグの削減
        $newTags = array_unique($newTags);
    
        $out = [];
        $query = $this->Tags->find()
            ->where(['Tags.title IN' => $newTags]);
    
        // 新しいタグのリストから既存のタグを削除。
        foreach ($query->extract('title') as $existing) {
            $index = array_search($existing, $newTags);
            if ($index !== false) {
                unset($newTags[$index]);
            }
        }
        // 既存のタグを追加。
        foreach ($query as $tag) {
            $out[] = $tag;
        }
        // 新しいタグを追加。
        foreach ($newTags as $tag) {
            $out[] = $this->Tags->newEntity(['title' => $tag]);
        }
        return $out;
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  

記事を作成または編集する場合、タグをコンマ区切りのタグリストとして保存し、 タグとリンクレコードを自動的に作成できるようにする必要があります。

このコードはこれまでのやり方より少し複雑ですが、CakePHP の ORM がどれほど強力であるかを紹介するのに 役立ちます。 [コレクション](https://book.cakephp.org/3.x/ja/core-libraries/collections.html)
 のメソッドを使用してクエリー結果を操作したり、 エンティティーを簡単に作成したりするシナリオを扱うことができます。

次は [認証](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/authentication.html)
 を追加しましょう。

---

# シンプルな認証と認可のアプリケーション | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog-auth-example/auth.html#VPContent)

Return to top

シンプルな認証と認可のアプリケーション [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog-auth-example/auth.html#%E3%82%B7%E3%83%B3%E3%83%95%E3%82%9A%E3%83%AB%E3%81%AA%E8%AA%8D%E8%A8%BC%E3%81%A8%E8%AA%8D%E5%8F%AF%E3%81%AE%E3%82%A2%E3%83%95%E3%82%9A%E3%83%AA%E3%82%B1%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3)

==========================================================================================================================================================================================================================================================================================================

[ブログチュートリアル](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog/blog.html)
 の例で、ログインユーザーに基づく特定の URL に対してセキュアなアクセスをしたい、という状況を想像してください。 また、別の要求もあります。 複数の著者が自身の記事を作成、編集、削除できて、 一方で他の著者が自身のものではない記事に変更を加えるのを許可しないようなブログにすることができます。

ユーザーに関連するコードを作成する [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog-auth-example/auth.html#%E3%83%A6%E3%83%BC%E3%82%B5%E3%82%99%E3%83%BC%E3%81%AB%E9%96%A2%E9%80%A3%E3%81%99%E3%82%8B%E3%82%B3%E3%83%BC%E3%83%88%E3%82%99%E3%82%92%E4%BD%9C%E6%88%90%E3%81%99%E3%82%8B)

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

まずはじめに、ユーザーデータを保持するためのブログデータベースの中に新しいテーブルを作成しましょう。 :

    CREATE TABLE users (
        id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
        username VARCHAR(50),
        password VARCHAR(255),
        role VARCHAR(20),
        created DATETIME DEFAULT NULL,
        modified DATETIME DEFAULT NULL
    );

1  
2  
3  
4  
5  
6  
7  
8  

テーブルの命名には CakePHP の規則がありますが、別の規則も活用できます。 username と password のカラムをユーザーテーブルに使用すると、 CakePHP はユーザーログインの実装のときにほとんどのことを自動で定義します。

続いてのステップは、ユーザーデータを検索、保存、検証する UsersTable クラスを作成することです。 :

    // src/Model/Table/UsersTable.php
    namespace App\Model\Table;
    
    use Cake\ORM\Table;
    use Cake\Validation\Validator;
    
    class UsersTable extends Table
    {
    
        public function validationDefault(Validator $validator)
        {
            return $validator
                ->notEmpty('username', 'A username is required')
                ->notEmpty('password', 'A password is required')
                ->notEmpty('role', 'A role is required')
                ->add('role', 'inList', [\
                    'rule' => ['inList', ['admin', 'author']],\
                    'message' => 'Please enter a valid role'\
                ]);
        }
    
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  

では UsersController も作成しましょう。以下の内容は基本的に bake された UsersController の一部に対応するもので、 CakePHP にバンドルされているコード生成ユーティリティを利用しています。 :

    // src/Controller/UsersController.php
    
    namespace App\Controller;
    
    use App\Controller\AppController;
    use Cake\Event\Event;
    
    class UsersController extends AppController
    {
    
        public function beforeFilter(Event $event)
        {
            parent::beforeFilter($event);
            $this->Auth->allow('add');
        }
    
         public function index()
         {
            $this->set('users', $this->Users->find('all'));
        }
    
        public function view($id)
        {
            $user = $this->Users->get($id);
            $this->set(compact('user'));
        }
    
        public function add()
        {
            $user = $this->Users->newEntity();
            if ($this->request->is('post')) {
                // 3.4.0 より前は $this->request->data() が使われました。
                $user = $this->Users->patchEntity($user, $this->request->getData());
                if ($this->Users->save($user)) {
                    $this->Flash->success(__('The user has been saved.'));
                    return $this->redirect(['action' => 'add']);
                }
                $this->Flash->error(__('Unable to add the user.'));
            }
            $this->set('user', $user);
        }
    
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40  
41  
42  
43  

同じように、コード生成ツールで記事のビューを作り、ユーザーのビューを実装することができます。 このチュートリアルのために、 add.ctp をお見せしましょう。

    <!-- src/Template/Users/add.ctp -->
    
    <div class="users form">
    <?= $this->Form->create($user) ?>
        <fieldset>
            <legend><?= __('Add User') ?></legend>
            <?= $this->Form->control('username') ?>
            <?= $this->Form->control('password') ?>
            <?= $this->Form->control('role', [\
                'options' => ['admin' => 'Admin', 'author' => 'Author']\
            ]) ?>
       </fieldset>
    <?= $this->Form->button(__('Submit')); ?>
    <?= $this->Form->end() ?>
    </div>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

認証(ログインとログアウト) [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog-auth-example/auth.html#%E8%AA%8D%E8%A8%BC-%E3%83%AD%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E3%81%A8%E3%83%AD%E3%82%AF%E3%82%99%E3%82%A2%E3%82%A6%E3%83%88)

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

認証レイヤーを追加する準備が整いました。CakePHP において、これは `Cake\Controller\Component\AuthComponent` で扱われており、 このクラスはあるアクションのログインで必要となり、ユーザーのログインとログアウトを扱い、 そしてログインユーザーがアクセスできるアクションの認証を行います。

このコンポーネントをアプリケーションに追加するには、 **src/Controller/AppController.php** ファイルを開いて、以下の行を追加してください。 :

    // src/Controller/AppController.php
    
    namespace App\Controller;
    
    use Cake\Controller\Controller;
    use Cake\Event\Event;
    
    class AppController extends Controller
    {
        //...
    
        public function initialize()
        {
            $this->loadComponent('Flash');
            $this->loadComponent('Auth', [\
                'loginRedirect' => [\
                    'controller' => 'Articles',\
                    'action' => 'index'\
                ],\
                'logoutRedirect' => [\
                    'controller' => 'Pages',\
                    'action' => 'display',\
                    'home'\
                ]\
            ]);
        }
    
        public function beforeFilter(Event $event)
        {
            $this->Auth->allow(['index', 'view', 'display']);
        }
        //...
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  

設定する箇所はさほど多くはありません。ユーザーテーブルでは規約を利用しているからです。 ログインおよびログアウトアクションが実行された後に読み込まれるURLのセットアップをしました。 今回の場合では `/articles/` および `/` をそれぞれ設定しました。

`beforeFitler()` 関数でしたことは、 AuthComponent にそれぞれのコントローラーの `index()` と `view()` アクションではログインは不要であると伝えることです。 このサイトでは、登録なしでもエントリーを読んだり一覧したりさせたいのです。

それでは、新しいユーザーを登録できるようにする必要があります。ユーザーネームとパスワードを保存し、 そしてさらに重要なこととして、パスワードがデータベースないに平文で保存されないようにパスワードを ハッシュ化しましょう。 それでは、 AuthComponent に認証されていないユーザーにはユーザー追加機能にアクセスさせるように設定して、 ログインとログアウトのアクションを実装しましょう。 :

    // src/Controller/UsersController.php
    namespace App\Controller;
    
    use App\Controller\AppController;
    use Cake\Event\Event;
    
    class UsersController extends AppController
    {
        // その他のメソッド..
    
        public function beforeFilter(Event $event)
        {
            parent::beforeFilter($event);
            // ユーザーの登録とログアウトを許可します。
            // allow のリストに "login" アクションを追加しないでください。
            // そうすると AuthComponent の正常な機能に問題が発生します。
            $this->Auth->allow(['add', 'logout']);
        }
    
        public function login()
        {
            if ($this->request->is('post')) {
                $user = $this->Auth->identify();
                if ($user) {
                    $this->Auth->setUser($user);
                    return $this->redirect($this->Auth->redirectUrl());
                }
                $this->Flash->error(__('Invalid username or password, try again'));
            }
        }
    
        public function logout()
        {
            return $this->redirect($this->Auth->logout());
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  

パスワードのハッシュ化はまだ済んでいません。特別なロジックを扱うためには、User の Entity クラスが必要です。 **src/Model/Entity/User.php** にエンティティーファイルを作成し、以下を追加します。 :

    // src/Model/Entity/User.php
    namespace App\Model\Entity;
    
    use Cake\Auth\DefaultPasswordHasher;
    use Cake\ORM\Entity;
    
    class User extends Entity
    {
    
        // 主キーフィールド "id" を除く、すべてのフィールドを一括代入可能にします。
        protected $_accessible = [\
            '*' => true,\
            'id' => false\
        ];
    
        // ...
    
        protected function _setPassword($password)
        {
            if (strlen($password) > 0) {
                return (new DefaultPasswordHasher)->hash($password);
            }
        }
    
        // ...
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  

これで、パスワードのプロパティーがユーザーにアサインされるたびに、 `DefaultPasswordHasher` クラスを用いてパスワードがハッシュ化されます。ログイン機能のテンプレートビューファイルが足りていません。 **src/Template/Users/login.ctp** ファイルを開いて、以下を追加してください。

    <!-- File: src/Template/Users/login.ctp -->
    
    <div class="users form">
    <?= $this->Flash->render() ?>
    <?= $this->Form->create() ?>
        <fieldset>
            <legend><?= __('Please enter your username and password') ?></legend>
            <?= $this->Form->control('username') ?>
            <?= $this->Form->control('password') ?>
        </fieldset>
    <?= $this->Form->button(__('Login')); ?>
    <?= $this->Form->end() ?>
    </div>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

`/users/add` の URL にアクセスすると、新しいユーザーを登録でき、 `/users/login` URL で新しく作られた認証情報を用いてログインできます。また、 `/articles/add` のように、 明確に許可されていない他のURLにもアクセスしてみてください。アプリケーションがログインページに 自動的にリダイレクトするのがわかります。

そして、これで終わりです！ シンプルすぎるようですが、これで良いのです。 何が起こったのかを少し戻って説明しましょう。 AppController の `beforeFilter()` ですでに許可されている `index()` および `view()` アクションに加えて、 `add()` アクションもログインが不要であることを AuthComponent に `beforeFilter()` で伝えています。

`login()` アクションは AuthComponent 内の `$this->Auth->identify()` 関数で呼び、 特別な設定なしに動きます。 なぜなら先に言及した通り、規約に従っているからです。Users テーブルは username, password のカラムを持ち、ユーザーデータをコントローラーに送るフォームを利用します。 この関数はログインがうまくいったかどうかを返します、そしてうまくいった場合は、 アプリケーションの AuthComponent に追加したときに使用した、 設定されたリダイレクト URL にリダイレクトします。

ログアウトはただ `/users/logout` URL にアクセスするだけで動作します。 そして先に宣言し設定したログアウト URL にリダイレクトさせます。 この URL は、 `AuthComponent::logout()` 関数がうまくいった場合の結果です。

認可(誰が何にアクセスするのを許可するか) [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog-auth-example/auth.html#%E8%AA%8D%E5%8F%AF-%E8%AA%B0%E3%81%8B%E3%82%99%E4%BD%95%E3%81%AB%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9%E3%81%99%E3%82%8B%E3%81%AE%E3%82%92%E8%A8%B1%E5%8F%AF%E3%81%99%E3%82%8B%E3%81%8B)

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

始める前に、このブログをマルチユーザーが認可されるツールにし、 これをするために、記事テーブルを少し変更して、ユーザーテーブルへの参照を追加します。 :

    ALTER TABLE articles ADD COLUMN user_id INT(11);

1  

さらに、 ArticlesController に、記事を作成した現在のログインユーザーの参照を追加するように 少し変更する必要があります。 :

    // src/Controller/ArticlesController.php
    
    public function add()
    {
        $article = $this->Articles->newEntity();
        if ($this->request->is('post')) {
            // 3.4.0 より前は $this->request->data() が使われました。
            $article = $this->Articles->patchEntity($article, $this->request->getData());
            // この行を追加
            $article->user_id = $this->Auth->user('id');
            // また、次のようにすることもできます
            //$newData = ['user_id' => $this->Auth->user('id')];
            //$article = $this->Articles->patchEntity($article, $newData);
            if ($this->Articles->save($article)) {
                $this->Flash->success(__('Your article has been saved.'));
                return $this->redirect(['action' => 'index']);
            }
            $this->Flash->error(__('Unable to add your article.'));
        }
        $this->set('article', $article);
    
        // 記事のカテゴリーを1つ選択できるようにカテゴリーリストを追加しました
        $categories = $this->Articles->Categories->find('treeList');
        $this->set(compact('categories'));
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  

このコンポーネントで提供されている `user()` 関数は、現在ログインしているユーザーのカラムを返します。 保存されたリクエスト情報の中のデータを追加するためにこのメソッドを利用します。

それでは、ある著者が他の人の記事を編集したり削除したりするのから守りましょう。 アプリケーションの基本的なルールは、管理ユーザーはすべての URL にアクセスでき、 通常のユーザー(著者ロール)は許可されたアクションにしかアクセスできない、というものです。 もう一度 AppController クラスを開いて、 Auth の設定を少し追加してください。 :

    // src/Controller/AppController.php
    
    public function initialize()
    {
        $this->loadComponent('Flash');
        $this->loadComponent('Auth', [\
            'authorize' => ['Controller'], // この行を追加\
            'loginRedirect' => [\
                'controller' => 'Articles',\
                'action' => 'index'\
            ],\
            'logoutRedirect' => [\
                'controller' => 'Pages',\
                'action' => 'display',\
                'home'\
            ]\
        ]);
    }
    
    public function isAuthorized($user)
    {
        // 管理者はすべての操作にアクセスできます
        if (isset($user['role']) && $user['role'] === 'admin') {
            return true;
        }
    
        // デフォルトは拒否
        return false;
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  

シンプルな認可メカニズムを作成しました。 `admin` ロールのユーザーはログインしていれば サイト内のあらゆる URL にアクセスできます。 他のユーザー、 `author` ロールのユーザーは、ログインしていないユーザーと同じアクセス権を持ちます。

これは、求めているものではありません。 `isAuthorized()` メソッドで、 さらにルールを追加する必要があります。このことを AppConroller 内でやるかわりに、 各個別のコントローラーにさらなるルールを追加することにしましょう。 追加しようとしているルールというのは、 ArticlesController によって、著者は記事を作成できるが、 自分のものではない記事を編集できないようにする、というものです。 以下の内容を **ArticlesController.php** に追加してください。 :

    // src/Controller/ArticlesController.php
    
    public function isAuthorized($user)
    {
        // 登録ユーザー全員が記事を追加できます
        // 3.4.0 より前は $this->request->param('action') が使われました。
        if ($this->request->getParam('action') === 'add') {
            return true;
        }
    
        // 記事の所有者は編集して削除することができます
        // 3.4.0 より前は $this->request->param('action') が使われました。
        if (in_array($this->request->getParam('action'), ['edit', 'delete'])) {
            // 3.4.0 より前は $this->request->params('pass.0')
            $articleId = (int)$this->request->getParam('pass.0');
            if ($this->Articles->isOwnedBy($articleId, $user['id'])) {
                return true;
            }
        }
    
        return parent::isAuthorized($user);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  

AppController の `isAuthorized()` を上書きして、内部的に親クラスをチェックすることによって すでにユーザーを認可しています。そうでなければ、 add アクションへのアクセスだけを許可し、条件付きで edit や delete へアクセスできます。最後のひとつだけが実装されていません。 記事を編集するためのユーザーが認可されているかどうかを伝えるために、 ArticlesTable の `isOwnedBy()` 関数を呼んでいます。それでは、この関数を実装しましょう。 :

    // src/Model/Table/ArticlesTable.php
    
    public function isOwnedBy($articleId, $userId)
    {
        return $this->exists(['id' => $articleId, 'user_id' => $userId]);
    }

1  
2  
3  
4  
5  
6  

これでシンプルな認証と認可のチュートリアルが終わりです。 UseresController を守るためには、 ArticlesController でやったのと同じテクニックを利用できます。 もっとクリエイティブになって、あなた自身のルールに基づいて AppController の中で さらに一般的なものを実装することもできます。

もしより制御したいのなら、 [AuthComponent](https://book.cakephp.org/3.x/ja/controllers/components/authentication.html)
 セクションの Auth ガイドを通して読むことをお勧めします。 コンポーネントの設定や、カスタム認証クラスの作成、そしてその他のことをさらに見つけることができるでしょう。

### より詳しく知りたい方のための読みもの [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog-auth-example/auth.html#%E3%82%88%E3%82%8A%E8%A9%B3%E3%81%97%E3%81%8F%E7%9F%A5%E3%82%8A%E3%81%9F%E3%81%84%E6%96%B9%E3%81%AE%E3%81%9F%E3%82%81%E3%81%AE%E8%AA%AD%E3%81%BF%E3%82%82%E3%81%AE)

1.  [Bake でコード生成](https://book.cakephp.org/3.x/ja/bake/usage.html)
     基本的な CRUD コードの生成について
2.  [AuthComponent](https://book.cakephp.org/3.x/ja/controllers/components/authentication.html)
    : ユーザーの登録とログインについて

---

# ブログチュートリアル - パート2 | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog/part-two.html#VPContent)

Return to top

ブログチュートリアル - パート2 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog/part-two.html#%E3%83%95%E3%82%99%E3%83%AD%E3%82%AF%E3%82%99%E3%83%81%E3%83%A5%E3%83%BC%E3%83%88%E3%83%AA%E3%82%A2%E3%83%AB-%E3%83%8F%E3%82%9A%E3%83%BC%E3%83%882)

====================================================================================================================================================================================================================================================

Article モデルの作成 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog/part-two.html#article-%E3%83%A2%E3%83%86%E3%82%99%E3%83%AB%E3%81%AE%E4%BD%9C%E6%88%90)

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

モデルクラスは、CakePHP アプリケーションの基本中の基本 (_bread and butter_) です。 CakePHP のモデルを作成することで、データベースとやりとりできるようになり、表示 (_view_)、 追加 (_add_)、編集 (_edit_)、削除 (_delete_) といった操作に必要な土台を 手に入れることになります。

CakePHP のモデルクラスのファイルは、 `Table` オブジェクトと `Entity` オブジェクトに分離して 存在します。 `Table` オブジェクトは、特定のテーブルに格納されているエンティティーの集合にアクセスし、 `src/Model/Table` の中に行きます。 `src/Model/Table/ArticlesTable.php` というファイルを 作って保存します。完成したファイルは次のようになります。 :

    // src/Model/Table/ArticlesTable.php
    
    namespace App\Model\Table;
    
    use Cake\ORM\Table;
    
    class ArticlesTable extends Table
    {
        public function initialize(array $config)
        {
            $this->addBehavior('Timestamp');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

命名規約は、CakePHP では非常に大切です。 Table オブジェクトを `ArticlesTable` という名前にすることで、CakePHP は自動的に、 この Table オブジェクトは ArticlesController で使用されるのだろうと解釈します。 また、 `articles` という名前のデータベーステーブルと結びつけられます。

NOTE

もし一致するファイルが **src/Model/Table** に見つけられなければ、CakePHP は動的に モデルオブジェクトを生成します。これはまた、不意に間違ったファイル名 (例えば、 articlestable.php や ArticleTable.php) をつけると、CakePHP はどの設定も認識できず、 代わりに生成されたモデルを使うことになるということも意味します。

コールバック、バリデーションといったモデルの詳細については、 マニュアルの [データベースアクセス & ORM](https://book.cakephp.org/3.x/ja/orm.html)
 の章を参照してください。

NOTE

もし、すでに [ブログチュートリアルのパート1](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog/blog.html)
 を完了していて `articles` テーブルをブログ用のデータベースに作成してあれば、 CakePHP の bake コンソールを活用して `ArticlesTable` モデルを作成することができます。 :

    bin/cake bake model Articles

1  

bake とコード生成についての詳細は、 [Bake でコード生成](https://book.cakephp.org/3.x/ja/bake/usage.html)
 を参照してください。

Articles コントローラーの作成 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog/part-two.html#articles-%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%A9%E3%83%BC%E3%81%AE%E4%BD%9C%E6%88%90)

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

次に、投稿記事 (_articles_) に対するコントローラーを作成します。コントローラーとは、 投稿記事とのすべてのやりとりが発生するところです。 簡単に言うと、それはモデルとのビジネスロジックを含み、投稿記事に関連する作業を行う場所です。 この新しいコントローラーは `ArticlesController.php` という名前で、 `src/Controller` ディレクトリーの中に配置します。基本的なコントローラーは次のようになります。 :

    // src/Controller/ArticlesController.php
    
    namespace App\Controller;
    
    class ArticlesController extends AppController
    {
    }

1  
2  
3  
4  
5  
6  
7  

では、コントローラーにひとつのアクションを追加してみましょう。アクションは、 アプリケーションの中のひとつの関数か、インターフェイスをあらわしています。 例えば、ユーザーが www.example.com/articles/index (www.example.com/articles/ と同じです) をリクエストした場合、投稿記事の一覧が表示されると期待するでしょう。 このアクションのコードは次のようになります。 :

    // src/Controller/ArticlesController.php
    
    namespace App\Controller;
    
    class ArticlesController extends AppController
    {
    
        public function index()
        {
            $articles = $this->Articles->find('all');
            $this->set(compact('articles'));
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

`ArticlesController` の中に `index()` という関数を定義することによって、ユーザーは、 www.example.com/articles/index というリクエストで、そのロジックにアクセスできるようになります。 同様に、 `foobar()` という関数を定義すると、ユーザーは、www.example.com/articles/foobar でアクセスできるようになります。

WARNING

ある URL にさせたいために、コントローラー名とアクション名をそれに合わせて独自に 命名したくなるかもしれませんが、その誘惑に抵抗してください。[CakePHP の規約](https://book.cakephp.org/3.x/ja/intro/conventions.html)
 （大文字化、複数形の名前など）に従って、読みやすく、理解しやすいアクション名を 付けるようにしましょう。あとで、[ルーティング](https://book.cakephp.org/3.x/ja/development/routing.html)
 という機能を使って、URL とコードを 結びつけることができます。

アクションの中にあるひとつの命令が、 `set()` を使って、コントローラーからビュー (次に作成します) にデータを渡しています。この行は、`ArticlesTable` オブジェクトの `find('all')` メソッドから返ってきた値で、「articles」というビューの変数を設定します。

NOTE

もし、すでに[ブログチュートリアルのパート1](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog/blog.html)
 を完了していて `articles` テーブルをブログ用のデータベースに作成してあれば、 CakePHP の bake コンソールを活用して `ArticlesController` クラスを作成することができます。 :

    bin/cake bake controller Articles

1  

bake とコード生成についての詳細は、 [Bake でコード生成](https://book.cakephp.org/3.x/ja/bake/usage.html)
 を参照してください。

CakePHP のコントローラーに関する詳細は、 [コントローラー](https://book.cakephp.org/3.x/ja/controllers.html)
 の章をチェックしてください。

Article ビューの作成 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog/part-two.html#article-%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC%E3%81%AE%E4%BD%9C%E6%88%90)

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

現在、モデルにはデータが入り、コントローラーにはアプリケーションロジックと流れが定義されています。 今度は、作成した index アクション用のビューを作成しましょう。

CakePHP のビュー (_view_) は、アプリケーションのレイアウト (_layout_) の内側に はめこまれる、データ表示用の断片部品です。たいていのアプリケーションでは、PHP のコードが 含まれる HTML になりますが、XML、CSV、バイナリのデータにもなりえます。

レイアウト (_layout_) は、ビューを囲む表示用のコードで、独自に定義したり、 切り替えたりすることも可能ですが、今のところは、デフォルト (_default_) のものを 使用することにしましょう。

一つ前のセクションの `set()` メソッドによって、ビューから「articles」変数が使えるように 割り当てたのを覚えていますか。これはクエリーオブジェクトのコレクションを `foreach` イテレーションを呼び出した状態でビューに伝えます。

CakePHP のビューファイルは、 `src/Template` の中の、コントローラー名に対応するフォルダーの中に 保存されています (この場合は、「Articles」というフォルダーを作成します)。 この投稿記事データをテーブル表示するには、ビューのコードは次のようなものになります。

    <!-- File: src/Template/Articles/index.ctp -->
    
    <h1>Blog articles</h1>
    <table>
        <tr>
            <th>Id</th>
            <th>Title</th>
            <th>Created</th>
        </tr>
    
        <!-- ここから、$articles のクエリーオブジェクトをループして、投稿記事の情報を表示 -->
    
        <?php foreach ($articles as $article): ?>
        <tr>
            <td><?= $article->id ?></td>
            <td>
                <?= $this->Html->link($article->title, ['action' => 'view', $article->id]) ?>
            </td>
            <td>
                <?= $article->created->format(DATE_RFC850) ?>
            </td>
        </tr>
        <?php endforeach; ?>
    </table>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  

シンプルなものであることがお分かりいただけるかと思います。

`$this->Html` というオブジェクトを使っていることに気づいたかもしれません。 これは、CakePHP の `Cake\View\Helper\HtmlHelper` クラスのインスタンスです。 CakePHP には一連のビューヘルパーがあり、リンクの作成、フォームの出力などをすぐに使えます。 使い方の詳細については、 [ヘルパー](https://book.cakephp.org/3.x/ja/views/helpers.html)
 を参照してください。ここで重要なのは、 `link()` メソッドが、指定されたタイトル（最初のパラメーター）と URL (二つ目のパラメーター) で HTML リンクを生成する、ということです。

CakePHP 内で URL を指定する場合、配列フォーマットの使用が推奨されます。 これはルーティングの章で詳しく説明されます。URL に配列フォーマットを用いることによって、 CakePHP のリバースルーティング機能を活用することができます。また、 /コントローラー/アクション/パラメーター1/パラメーター2 という形のアプリケーションの基本パスに対する相対パスを単に書くこともできます。 [named routes](https://book.cakephp.org/3.x/ja/development/routing.html#named-routes)
 もご参照ください。

この時点で、ブラウザーから [http://www.example.com/articles/index](http://www.example.com/articles/index)
 を開いてみてください。 タイトルと投稿内容のテーブル一覧がまとめられているビューが表示されるはずです。

ビューの中のリンク (投稿記事のタイトルから `/articles/view/some\_id` という URL へのリンク) を クリックすると、CakePHP は、そのアクションはまだ定義されていません、という表示を出します。 もしそういう表示が出ない場合には、何かおかしくなってしまったか、もうすでにあなたが その定義作業をしてしまったから（仕事がハヤイ！）か、のどちらかです。 そうでないなら、これから `ArticlesController` の中に作ってみましょう。 :

    // src/Controller/ArticlesController.php
    
    namespace App\Controller;
    
    class ArticlesController extends AppController
    {
    
        public function index()
        {
             $this->set('articles', $this->Articles->find('all'));
        }
    
        public function view($id = null)
        {
            $article = $this->Articles->get($id);
            $this->set(compact('article'));
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

`set()` の呼び出しはもう知っていますね。 `find('all')` の代わりに、 `get()` を使っていることに注目してください。今回は、ひとつの投稿記事の情報しか 必要としないからです。

ビューのアクションが、ひとつのパラメーターを取っていることに注意してください。 それは、これから表示する投稿記事のID番号です。このパラメーターは、リクエストされた URL を通して渡されます。ユーザーが、 `/articles/view/3` とリクエストすると、 「3」という値が `$id` として渡されます。

ユーザーが実在するレコードにアクセスすることを保証するために少しだけエラーチェックを行います。 Articles テーブルに対して `get()` を用いるとき、存在するレコードにアクセスしています。 もしリクエスト記事がデータベースに存在しない場合、もしくは id が false の場合、 `get()` 関数は `NotFoundException` を送出します。

では、新しい「view」アクション用のビューを作って、 **src/Template/Articles/view.ctp** というファイルで保存しましょう。

    <!-- File: src/Template/Articles/view.ctp -->
    
    <h1><?= h($article->title) ?></h1>
    <p><?= h($article->body) ?></p>
    <p><small>Created: <?= $article->created->format(DATE_RFC850) ?></small></p>

1  
2  
3  
4  
5  

`/articles/index` の中にあるリンクをクリックしたり、手動で、 `/articles/view/1` にアクセスしたりして、動作することを確認してください。

記事の追加 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog/part-two.html#%E8%A8%98%E4%BA%8B%E3%81%AE%E8%BF%BD%E5%8A%A0)

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

データベースを読み、記事を表示できるようになりました。今度は、新しい投稿が できるようにしてみましょう。

まず、 `ArticlesController` の中に、 `add()` アクションを作ります。 :

    // src/Controller/ArticlesController.php
    
    namespace App\Controller;
    
    use App\Controller\AppController;
    
    class ArticlesController extends AppController
    {
    
        public function initialize()
        {
            parent::initialize();
    
            $this->loadComponent('Flash'); // Include the FlashComponent
        }
    
        public function index()
        {
            $this->set('articles', $this->Articles->find('all'));
        }
    
        public function view($id)
        {
            $article = $this->Articles->get($id);
            $this->set(compact('article'));
        }
    
        public function add()
        {
            $article = $this->Articles->newEntity();
            if ($this->request->is('post')) {
                // 3.4.0 より前は $this->request->data() が使われました。
                $article = $this->Articles->patchEntity($article, $this->request->getData());
                if ($this->Articles->save($article)) {
                    $this->Flash->success(__('Your article has been saved.'));
                    return $this->redirect(['action' => 'index']);
                }
                $this->Flash->error(__('Unable to add your article.'));
            }
            $this->set('article', $article);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40  
41  
42  

NOTE

[フラッシュ](https://book.cakephp.org/3.x/ja/controllers/components/flash.html)
 コンポーネントを使うコントローラーで読み込む必要があります。 必要不可欠なら、 `AppController` で読み込むようにしてください。

`add()` アクションの動作は次のとおりです: もし、リクエストの HTTP メソッドが POST なら、Articles モデルを使ってデータの保存を試みます。 何らかの理由で保存できなかった場合には、単にビューを表示します。 この時に、ユーザーバリデーションエラーやその他の警告が表示されることになります。

すべての CakePHP のリクエストは `ServerRequest` オブジェクトに格納されており、 `$this->request` でアクセスできます。リクエストオブジェクトには、受信したリクエストに 関するいろんな情報が含まれているので、アプリケーションのフローの制御に利用できます。今回は、 リクエストが HTTP POST かどうかの確認に `Cake\Http\ServerRequest::is()` メソッドを 使用しています。

ユーザーがフォームを使ってデータを POST した場合、その情報は、 `$this->request->getData()` (CakePHP v3.3 以前の場合、 `$this->request->data()` ) の中に入ってきます。 `pr()` や `debug()` を使うと、 内容を画面に表示させて、確認することができます。

FlashComponent の `success()` および `error()` メソッドを使って セッション変数にメッセージをセットします。これらのメソッドは PHP の [マジックメソッド](https://php.net/manual/en/language.oop5.overloading.php#object.call)
 を利用しています。 Flash メッセージはリダイレクト後のページに表示されます。 レイアウトでは `<?= $this->Flash->render() ?>` を用いてメッセージを表示し、 対応するセッション変数を削除します。コントローラーの `Cake\Controller\Controller::redirect` 関数は別の URL にリダイレクトを行います。 `['action' => 'index']` パラメーターは /articles、つまり articles コントローラーの index アクションを表す URL に解釈されます。 多くの CakePHP の関数で指定できるURLのフォーマットについては、 [API](https://api.cakephp.org/)
 の `Cake\Routing\Router::url()` 関数を参考にすることができます。

`save()` メソッドを呼ぶと、バリデーションエラーがチェックされ、もしエラーがある場合には 保存動作を中止します。これらのエラーがどのように扱われるのかは次のセクションで見てみましょう。

データのバリデーション [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog/part-two.html#%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%81%AE%E3%83%8F%E3%82%99%E3%83%AA%E3%83%86%E3%82%99%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3)

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

CakePHP はフォームの入力バリデーションの退屈さを取り除くのに大いに役立ちます。 みんな、延々と続くフォームとそのバリデーションルーチンのコーディングは好まないでしょう。 CakePHP を使うと、その作業を簡単、高速に片付けることができます。

バリデーションの機能を活用するためには、ビューの中で CakePHP の [Form](https://book.cakephp.org/3.x/ja/views/helpers/form.html)
 を 使う必要があります。 `Cake\View\Helper\FormHelper` はデフォルトで、 すべてのビューの中で `$this->Form` としてアクセスできるようになっています。

add のビューは次のようなものになります。

    <!-- File: src/Template/Articles/add.ctp -->
    
    <h1>Add Article</h1>
    <?php
        echo $this->Form->create($article);
        echo $this->Form->control('title');
        echo $this->Form->control('body', ['rows' => '3']);
        echo $this->Form->button(__('Save Article'));
        echo $this->Form->end();
    ?>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

ここで、FormHelper を使って、HTML フォームの開始タグを生成しています。 `$this->Form->create()` が生成した HTML は次のようになります。

    <form method="post" action="/articles/add">

1  

`create()` にパラメーターを渡さないで呼ぶと、現在のコントローラーの add() アクション (または `id` がフォームデータに含まれる場合 `edit()` アクション) に、 POST で送るフォームを構築している、と解釈されます。

`$this->Form->control()` メソッドは、同名のフォーム要素を作成するのに使われています。 最初のパラメーターは、どのフィールドに対応しているのかを CakePHP に教えます。 ２番目のパラメーターは、様々なオプションの配列を指定することができます。

*   この例では、textarea の列の数を指定しています。 ここではちょっとした内観的で自動的な手法が使われています。 `control()` は、指定されたモデルのフィールドに基づいて、異なるフォーム要素を出力します。

`$this->Form->end()` の呼び出しで、フォームの終了部分が出力されます。 hidden の input 要素の出力においては、CSRF/フォーム改ざん防止が有効です。

さて少し戻って、 `src/Template/Articles/index.ctp` のビューで「Add Article」というリンクを 新しく表示するように編集しましょう。 `<table>` の前に、以下の行を追加してください。 :

    <?= $this->Html->link('Add Article', ['action' => 'add']) ?>

1  

バリデーション要件について、どうやって CakePHP に指示するのだろう、と思ったかもしれません。 バリデーションのルールは、モデルの中で定義することができます。 Article モデルを見直して、幾つか修正してみましょう。 :

    // src/Model/Table/ArticlesTable.php
    
    namespace App\Model\Table;
    
    use Cake\ORM\Table;
    use Cake\Validation\Validator;
    
    class ArticlesTable extends Table
    {
        public function initialize(array $config)
        {
            $this->addBehavior('Timestamp');
        }
    
        public function validationDefault(Validator $validator)
        {
            $validator
                ->notEmpty('title')
                ->requirePresence('title')
                ->notEmpty('body')
                ->requirePresence('body');
    
            return $validator;
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  

`validationDefault()` メソッドを使って `save()` メソッドが呼ばれた時に、 どうやってバリデートするかを CakePHP に教えます。ここでは、本文とタイトルのフィールドが、 空ではいけない、そして作成及び編集の際にどちらも必要であるということを設定しています。 CakePHP のバリデーションエンジンは強力で、 組み込みのルールがいろいろあります (クレジットカード番号、メールアドレスなど）。 また柔軟に、独自ルールを作って設定することもできます。この設定に関する詳細は、 [バリデーション](https://book.cakephp.org/3.x/ja/core-libraries/validation.html)
 を参照してください。

バリデーションルールを書き込んだので、アプリケーションを動作させて、タイトルと本文を 空にしたまま、記事を投稿してみてください。 `Cake\View\Helper\FormHelper::control()` メソッドを使ってフォーム要素を作成したので、バリデーションエラーのメッセージが自動的に表示されます。

投稿記事の編集 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog/part-two.html#%E6%8A%95%E7%A8%BF%E8%A8%98%E4%BA%8B%E3%81%AE%E7%B7%A8%E9%9B%86)

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

それではさっそく投稿記事の編集ができるように作業をしましょう。 もう CakePHP プロのあなたは、パターンを見つけ出したでしょうか。 アクションをつくり、それからビューを作る、というパターンです。 `ArticlesController` の `edit()` アクションはこんな形になります。 :

    // src/Controller/ArticlesController.php
    
    public function edit($id = null)
    {
        $article = $this->Articles->get($id);
        if ($this->request->is(['post', 'put'])) {
            // 3.4.0 より前は $this->request->data() が使われました。
            $this->Articles->patchEntity($article, $this->request->getData());
            if ($this->Articles->save($article)) {
                $this->Flash->success(__('Your article has been updated.'));
                return $this->redirect(['action' => 'index']);
            }
            $this->Flash->error(__('Unable to update your article.'));
        }
    
        $this->set('article', $article);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

このアクションではまず、ユーザーが実在するレコードにアクセスしようとしていることを確認します。 もし `$id` パラメーターが渡されてないか、ポストが存在しない場合、 `NotFoundException` を送出して CakePHP の ErrorHandler に処理を委ねます。

次に、リクエストが POST か PUT であるかをチェックします。もしリクエストが POST か PUT なら、 `patchEntity()` メソッドを用いてPOST データを記事エンティティーに更新します。 最終的にテーブルオブジェクトを用いて、エンティティーを保存したり、退けてバリデーションエラーを表示したりします。

edit ビューは以下のようになるでしょう。

    <!-- File: src/Template/Articles/edit.ctp -->
    
    <h1>Edit Article</h1>
    <?php
        echo $this->Form->create($article);
        echo $this->Form->control('title');
        echo $this->Form->control('body', ['rows' => '3']);
        echo $this->Form->button(__('Save Article'));
        echo $this->Form->end();
    ?>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

（値が入力されている場合、）このビューは、編集フォームを出力します。 必要であれば、バリデーションのエラーメッセージも表示します。

`save()` が呼び出された時、エンティティーの内容によって CakePHP は挿入あるいは更新のどちらを生成するかを決定します。

これで、特定の記事をアップデートするためのリンクを index ビューに付けることができます。

    <!-- File: src/Template/Articles/index.ctp  (edit links added) -->
    
    <h1>Blog articles</h1>
    <p><?= $this->Html->link("Add Article", ['action' => 'add']) ?></p>
    <table>
        <tr>
            <th>Id</th>
            <th>Title</th>
            <th>Created</th>
            <th>Action</th>
        </tr>
    
    <!-- $articles クエリーオブジェクトをループして、投稿記事の情報を表示 -->
    
    <?php foreach ($articles as $article): ?>
        <tr>
            <td><?= $article->id ?></td>
            <td>
                <?= $this->Html->link($article->title, ['action' => 'view', $article->id]) ?>
            </td>
            <td>
                <?= $article->created->format(DATE_RFC850) ?>
            </td>
            <td>
                <?= $this->Html->link('Edit', ['action' => 'edit', $article->id]) ?>
            </td>
        </tr>
    <?php endforeach; ?>
    
    </table>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  

投稿記事の削除 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog/part-two.html#%E6%8A%95%E7%A8%BF%E8%A8%98%E4%BA%8B%E3%81%AE%E5%89%8A%E9%99%A4)

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

次に、ユーザーが投稿記事を削除できるようにする機能を作りましょう。 `ArticlesController` の `delete()` アクションを作るところから始めます。 :

    // src/Controller/ArticlesController.php
    
    public function delete($id)
    {
        $this->request->allowMethod(['post', 'delete']);
    
        $article = $this->Articles->get($id);
        if ($this->Articles->delete($article)) {
            $this->Flash->success(__('The article with id: {0} has been deleted.', h($id)));
            return $this->redirect(['action' => 'index']);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

このロジックは、 `$id` で指定された記事を削除し、 `$this->Flash->success()` を使って、ユーザーに確認メッセージを表示し、それから `/articles` にリダイレクトします。 ユーザーが GET リクエストを用いて削除を試みようとすると、 `allowMethod()` が例外を投げます。 捕捉されない例外は CakePHP の例外ハンドラーによって捕まえられ、気の利いたエラーページが 表示されます。多くの組み込み [Exceptions](https://book.cakephp.org/3.x/ja/development/errors.html)
 があり、アプリケーションが 生成することを必要とするであろう様々な HTTP エラーを指し示すのに使われます。

ロジックを実行してリダイレクトするので、このアクションにはビューがありません。 しかし、index ビューにリンクを付けて、投稿を削除するようにできるでしょう。

    <!-- File: src/Template/Articles/index.ctp (delete links added) -->
    
    <h1>Blog articles</h1>
    <p><?= $this->Html->link('Add Article', ['action' => 'add']) ?></p>
    <table>
        <tr>
            <th>Id</th>
            <th>Title</th>
            <th>Created</th>
            <th>Actions</th>
        </tr>
    
    <!-- ここで $articles クエリーオブジェクトをループして、投稿情報を表示 -->
    
        <?php foreach ($articles as $article): ?>
        <tr>
            <td><?= $article->id ?></td>
            <td>
                <?= $this->Html->link($article->title, ['action' => 'view', $article->id]) ?>
            </td>
            <td>
                <?= $article->created->format(DATE_RFC850) ?>
            </td>
            <td>
                <?= $this->Form->postLink(
                    'Delete',
                    ['action' => 'delete', $article->id],
                    ['confirm' => 'Are you sure?'])
                ?>
                <?= $this->Html->link('Edit', ['action' => 'edit', $article->id]) ?>
            </td>
        </tr>
        <?php endforeach; ?>
    
    </table>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  

`Cake\View\Helper\FormHelper::postLink()` を使うと、投稿記事の削除を行う POST リクエストをするための JavaScript を使うリンクが生成されます。

WARNING

ウェブクローラーが不意にコンテンツ全てを削除できてしまうので、 GETリクエストを用いたコンテンツの削除を許可することは危険です。

NOTE

このビューコードは `FormHelper` を使い、削除する前に、 JavaScript による確認ダイアログでユーザーに確認します。

ルーティング(_Routes_) [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog/part-two.html#%E3%83%AB%E3%83%BC%E3%83%86%E3%82%A3%E3%83%B3%E3%82%AF%E3%82%99-routes)

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

CakePHP のデフォルトのルーティングの動作で十分だという人もいます。しかし、ユーザーフレンドリーで 一般の検索エンジンに対応できるような操作に関心のある開発者であれば、CakePHP の中で、 URL がどのように特定の関数の呼び出しにマップされるのかを理解したいと思うはずです。 このチュートリアルでは、routes を簡単に変える方法について扱います。

ルーティングテクニックの応用に関する情報は、 [Routes Configuration](https://book.cakephp.org/3.x/ja/development/routing.html#routes-configuration)
 を見てください。

今のところ、ユーザーがサイト (たとえば、 [http://www.example.com](http://www.example.com/)
) を見に来ると、 CakePHP は `PagesController` に接続し、「home」というビューを表示するようになっています。 ではこれを、ルーティングルールを作成して ArticlesController に行くようにしてみましょう。

CakePHP のルーティングは、 **config/routes.php** の中にあります。 デフォルトのトップページのルートをコメントアウトするか、削除します。 この行です。

    $routes->connect('/', ['controller' => 'Pages', 'action' => 'display', 'home']);

1  

この行は、「/」という URL をデフォルトの CakePHP のホームページに接続します。 これを、自分のコントローラーに接続させるために、次のような行を追加してください。

    $routes->connect('/', ['controller' => 'Articles', 'action' => 'index']);

1  

これで、「/」でリクエストしてきたユーザーを、ArticlesController の index() アクションに 接続させることができます。

NOTE

CakePHP は「リバースルーティング」も利用します。 上記のルートが定義されている状態で、配列を期待する関数に `['controller' => 'Articles', 'action' => 'index']` を渡すと、結果のURLは「/」になります。 つまり、URL の指定に常に配列を使うということが良策となります。 これによりルートが URL の行き先を定義する意味を持ち、 リンクが確実に同じ場所を指し示すようになります。

まとめ [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog/part-two.html#%E3%81%BE%E3%81%A8%E3%82%81)

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

気をつけてほしいのは、 このチュートリアルは、非常に基本的な点しか扱っていない、ということです。 CakePHP には、もっともっと _多くの_ 機能があります。シンプルなチュートリアルにするために、 それらはここでは扱いませんでした。マニュアルの残りの部分をガイドとして使い、 もっと機能豊かなアプリケーションを作成してください。

基本的なアプリケーションの作成が終わったので [ブログチュートリアル - パート3](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog/part-three.html)
 に進むか、自分のプロジェクトを始めてください。CakePHP についてさらに学ぶために [CakePHP の利用](https://book.cakephp.org/3.x/ja/topics.html)
 や [API](https://api.cakephp.org/)
 を使いましょう。

もし困ったときは、いろんな方法で助けを得ることができます。 [情報の探し方](https://book.cakephp.org/3.x/ja/intro/where-to-get-help.html)
 を見てみてください。 CakePHP にようこそ！

### お勧めの参考文献 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog/part-two.html#%E3%81%8A%E5%8B%A7%E3%82%81%E3%81%AE%E5%8F%82%E8%80%83%E6%96%87%E7%8C%AE)

CakePHP を学習する人が次に学びたいと思う共通のタスクがいくつかあります。

1.  [View Layouts](https://book.cakephp.org/3.x/ja/views.html#view-layouts)
    : ウェブサイトのレイアウトをカスタマイズする
2.  [View Elements](https://book.cakephp.org/3.x/ja/views.html#view-elements)
    : ビューのスニペットを読み込んで再利用する
3.  [Bake でコード生成](https://book.cakephp.org/3.x/ja/bake/usage.html)
    : 基本的な CRUD コードの生成
4.  [シンプルな認証と認可のアプリケーション](https://book.cakephp.org/3.x/ja/tutorials-and-examples/blog-auth-example/auth.html)
    : ユーザーの認証と承認のチュートリアル

---

# CMS チュートリアル - データベース作成 | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/database.html#VPContent)

Return to top

CMS チュートリアル - データベース作成 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/database.html#cms-%E3%83%81%E3%83%A5%E3%83%BC%E3%83%88%E3%83%AA%E3%82%A2%E3%83%AB-%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%83%98%E3%82%99%E3%83%BC%E3%82%B9%E4%BD%9C%E6%88%90)

====================================================================================================================================================================================================================================================================

先ほどは CakePHP をインストールしましたので、 `CMS (Content Management System)` アプリケーションのためのデータベースをセットアップしましょう。まだセットアップしていない場合、 例えば `cake_cms` のように、あなたの好きな名前で、このチュートリアルで使用する空のデータベースを 作成してください。必要なテーブルを作成するために、以下の SQL を実行することができます。

    USE cake_cms;
    
    CREATE TABLE users (
        id INT AUTO_INCREMENT PRIMARY KEY,
        email VARCHAR(255) NOT NULL,
        password VARCHAR(255) NOT NULL,
        created DATETIME,
        modified DATETIME
    );
    
    CREATE TABLE articles (
        id INT AUTO_INCREMENT PRIMARY KEY,
        user_id INT NOT NULL,
        title VARCHAR(255) NOT NULL,
        slug VARCHAR(191) NOT NULL,
        body TEXT,
        published BOOLEAN DEFAULT FALSE,
        created DATETIME,
        modified DATETIME,
        UNIQUE KEY (slug),
        FOREIGN KEY user_key (user_id) REFERENCES users(id)
    ) CHARSET=utf8mb4;
    
    CREATE TABLE tags (
        id INT AUTO_INCREMENT PRIMARY KEY,
        title VARCHAR(191),
        created DATETIME,
        modified DATETIME,
        UNIQUE KEY (title)
    ) CHARSET=utf8mb4;
    
    CREATE TABLE articles_tags (
        article_id INT NOT NULL,
        tag_id INT NOT NULL,
        PRIMARY KEY (article_id, tag_id),
        FOREIGN KEY tag_key(tag_id) REFERENCES tags(id),
        FOREIGN KEY article_key(article_id) REFERENCES articles(id)
    );
    
    INSERT INTO users (email, password, created, modified)
    VALUES
    ('[email protected]', 'secret', NOW(), NOW());
    
    INSERT INTO articles (user_id, title, slug, body, published, created, modified)
    VALUES
    (1, 'First Post', 'first-post', 'This is the first post.', 1, now(), now());

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40  
41  
42  
43  
44  
45  
46  

複合主キーを持つ `articles_tags` テーブルにお気づきでしょうか。CakePHP は、 ほぼどこでも複合主キーをサポートしているので、追加の `id` カラムを必要としない 単純なスキーマを持つことができます。

私たちが使用するテーブルやカラムの名前は恣意的ではありませんでした。CakePHP の [命名規則](https://book.cakephp.org/3.x/ja/intro/conventions.html)
 を使用することによって、CakePHP がより効果的になり、 フレームワークの設定を避けられます。CakePHP は、ほぼ全てのデータベーススキーマに対応できるくらい 十分に柔軟ですが、CakePHP がデフォルトで提供する規約に従うことで、時間を節約できます。

データベースの設定 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/database.html#%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%83%98%E3%82%99%E3%83%BC%E3%82%B9%E3%81%AE%E8%A8%AD%E5%AE%9A)

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

次に、どこにデータベースあるか、そしてどうやってデータベースに接続するかを CakePHP に伝えましょう。あなたのセットアップを適用するために **config/app\_local.php** ファイルの中の `Datasources.default` 配列の値を置き換えてください。 完全な設定配列の例は、以下のようになります。 :

    <?php
    return [\
        // 上には他の設定があります\
        'Datasources' => [\
            'default' => [\
                'className' => 'Cake\Database\Connection',\
                'driver' => 'Cake\Database\Driver\Mysql',\
                'persistent' => false,\
                'host' => 'localhost',\
                'username' => 'cakephp',\
                'password' => 'AngelF00dC4k3~',\
                'database' => 'cake_cms',\
                'encoding' => 'utf8mb4',\
                'timezone' => 'UTC',\
                'cacheMetadata' => true,\
            ],\
        ],\
        // 下には他の設定があります\
    ];

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  

一度 **config/app\_local.php** ファイルを保存して、 'CakePHP is able to connect to the database' が緑色のコック帽であることを確認してください。

NOTE

CakePHP のデフォルト設定ファイルの複製は **config/app.default.php** にあります。

最初のモデルの作成 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/database.html#%E6%9C%80%E5%88%9D%E3%81%AE%E3%83%A2%E3%83%86%E3%82%99%E3%83%AB%E3%81%AE%E4%BD%9C%E6%88%90)

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

モデルは、CakePHP アプリケーションの心臓部です。データを読んだり変更することができます。 それらは、データ間のリレーションの構築、データの検証、アプリケーションルールの適用をすることができます。 モデルは、コントローラーアクションとテンプレートを構築するために必要な基礎を構築します。

CakePHP のモデルは `Table` と `Entity` オブジェクトで構成されています。 `Table` オブジェクトは、指定されたテーブルの中に保存されたエンティティーの集合へのアクセスを提供します。 それらは **src/Model/Table** の中に保存されます。私たちが今から作成するファイルは、 **src/Model/Table/ArticlesTable.php** に保存されます。完成したファイルは次のようになります。 :

    <?php
    // src/Model/Table/ArticlesTable.php
    namespace App\Model\Table;
    
    use Cake\ORM\Table;
    
    class ArticlesTable extends Table
    {
        public function initialize(array $config)
        {
            $this->addBehavior('Timestamp');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

このテーブルの `created` や `modified` カラムを自動的に更新する [Timestamp](https://book.cakephp.org/3.x/ja/orm/behaviors/timestamp.html)
 ビヘイビアーを追加しました。 Table オブジェクトを `ArticlesTable` と名付けることで、CakePHP は、命名規則により `articles` テーブルを使用するモデルであると解釈します。また、CakePHP は、 `id` カラムがテーブルの主キーであると解釈する規約を使用します。

NOTE

もし一致するファイルが **src/Model/Table** に見つけられなければ、CakePHP は動的に モデルオブジェクトを生成します。これはまた、不意に間違ったファイル名 (例えば、 articlestable.php や ArticleTable.php) をつけると、CakePHP はどの設定も認識できず、 代わりに生成されたモデルを使うことになるということも意味します。

また、Articles のための Entity クラスも作成します。エンティティーは、 データベースの１つのレコードを表し、データに対して行レベルの振る舞いを提供します。 このエンティティーは、 **src/Model/Entity/Article.php** に保存されます。 完成したファイルは、次のようになります。 :

    <?php
    // src/Model/Entity/Article.php
    namespace App\Model\Entity;
    
    use Cake\ORM\Entity;
    
    class Article extends Entity
    {
        protected $_accessible = [\
            '*' => true,\
            'id' => false,\
            'slug' => false,\
        ];
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

エンティティーは、今はとてもスリムです。そして、 [Entities Mass Assignment](https://book.cakephp.org/3.x/ja/orm/entities.html#entities-mass-assignment)
 によって どのようにプロパティーを変更できるかを制御するプロパティー `_accessible` をセットアップしました。

このモデルは、今は動きませんが、次は最初の [コントローラーとテンプレート](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/articles-controller.html)
 を作成し、このモデルとのやりとりができるようにします。

---

# <no title> - 2.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/bake/edit/2.x/docs/ja/contents.rst)

[](https://book.cakephp.org/bake/2/ja/contents.html#page-contents)

CakePHP Bake

*   [Bake コンソール](https://book.cakephp.org/bake/2/ja/index.html)
    *   [インストール手順](https://book.cakephp.org/bake/2/ja/index.html#id1)
        
*   [Bake でコード生成](https://book.cakephp.org/bake/2/ja/usage.html)
    *   [Bake テーマオプション](https://book.cakephp.org/bake/2/ja/usage.html#id1)
        
*   [Bake の拡張](https://book.cakephp.org/bake/2/ja/development.html)
    *   [Bake イベント](https://book.cakephp.org/bake/2/ja/development.html#id1)
        
    *   [Bake テンプレート構文](https://book.cakephp.org/bake/2/ja/development.html#id2)
        
    *   [Bake テーマの作成](https://book.cakephp.org/bake/2/ja/development.html#creating-a-bake-theme)
        
    *   [Bake テンプレートのカスタマイズ](https://book.cakephp.org/bake/2/ja/development.html#id4)
        
    *   [Bake コマンドオプションの新規作成](https://book.cakephp.org/bake/2/ja/development.html#id5)
        

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# CMS チュートリアル - Articles コントローラーの作成 | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/articles-controller.html#VPContent)

Return to top

CMS チュートリアル - Articles コントローラーの作成 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/articles-controller.html#cms-%E3%83%81%E3%83%A5%E3%83%BC%E3%83%88%E3%83%AA%E3%82%A2%E3%83%AB-articles-%E3%82%B3%E3%83%B3%E3%83%88%E3%83%AD%E3%83%BC%E3%83%A9%E3%83%BC%E3%81%AE%E4%BD%9C%E6%88%90)

===================================================================================================================================================================================================================================================================================================

モデルが作成できたので、記事のコントローラーが必要です。CakePHP のコントローラーは、 レスポンスを準備するために、HTTP リクエストを処理し、モデルのメソッドに含まれるビジネスロジックを 実行します。この新しいコントローラーは **src/Controller** ディレクトリーの中で **ArticlesController.php** と呼ばれるファイルに記述します。 基本的なコントローラーの外観は次の通りです。 :

    <?php
    // src/Controller/ArticlesController.php
    
    namespace App\Controller;
    
    class ArticlesController extends AppController
    {
    }

1  
2  
3  
4  
5  
6  
7  
8  

それでは、コントローラーにアクションを追加しましょう。アクションは、ルートに接続させる コントローラーのメソッドです。例えば、ユーザーが **www.example.com/articles/index** (**www.example.com/articles** と同じ) をリクエストした場合、CakePHP は、 `ArticlesController` の `index` メソッドを呼びます。このメソッドは、モデル層に問い合わせ、 ビューでテンプレートを描画してレスポンスの準備する必要があります。そのアクションのコードは、 次のようになります。 :

    <?php
    // src/Controller/ArticlesController.php
    
    namespace App\Controller;
    
    class ArticlesController extends AppController
    {
        public function index()
        {
            $this->loadComponent('Paginator');
            $articles = $this->Paginator->paginate($this->Articles->find());
            $this->set(compact('articles'));
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

`ArticlesController` の `index()` 関数を定義することで、ユーザーは、 **www.example.com/articles/index** をリクエストすることで、そこにあるロジックに アクセスできるようになります。同様に、 `foobar()` という関数を定義した場合、 ユーザーはそのメソッドに **www.example.com/articles/foobar** で、アクセスできます。 特定の URL を取得できるように、コントローラーとアクションの名前を付けたいという 誘惑に駆られるかもしれません。その誘惑に抗ってください。代わりに、 [CakePHP の規約](https://book.cakephp.org/3.x/ja/intro/conventions.html)
 にしたがって、読みやすく意味のあるアクション名を作成してください。そうすれば [ルーティング](https://book.cakephp.org/3.x/ja/development/routing.html)
 を使って、あなたが望む URL を、 あなたが作成したアクションに接続することができます。

このコントローラーのアクションはとてもシンプルです。 これは、命名規則によって自動的にロードされる Articles モデルを使用して、 データベースからページ分けされた記事を取得します。次に (これからすぐに作成する) テンプレートの中に記事を渡すために `set()` を使用します。CakePHP は、 コントローラーのアクションが完了した後、自動的にテンプレートを描画します。

記事一覧のテンプレート作成 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/articles-controller.html#%E8%A8%98%E4%BA%8B%E4%B8%80%E8%A6%A7%E3%81%AE%E3%83%86%E3%83%B3%E3%83%95%E3%82%9A%E3%83%AC%E3%83%BC%E3%83%88%E4%BD%9C%E6%88%90)

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

モデルからデータを取得し、ビューのコンテキストを準備するコントローラーを持っていますので、 index アクションのビューテンプレートを作成しましょう。

CakePHP のビューテンプレートは、アプリケーションのレイアウト内に挿入される表示用の PHP コードです。 ここで HTML が作成されますが、 View は JSON、CSV、または PDF などのバイナリファイルの生成もできます。

レイアウトは、ビューを囲む表示用のコードです。レイアウトファイルは、 ヘッダー・フッター・ナビゲーション要素のような一般的なサイトの要素が含まれます。 アプリケーションは、複数のレイアウトを持つことができ、それらを切り替えることができますが、 今回はデフォルトのレイアウトを使用しましょう。

CakePHP のテンプレートファイルは、 **src/Template** の中で 対応するコントローラーの名前をつけたフォルダーの中に保存されます。 今回の場合、 'Articles' という名前のフォルダーを作成する必要があります。 あなたのアプリケーションに以下のコードを追加してください。

    <!-- File: src/Template/Articles/index.ctp -->
    
    <h1>記事一覧</h1>
    <table>
        <tr>
            <th>タイトル</th>
            <th>作成日時</th>
        </tr>
    
        <!-- ここで、$articles クエリーオブジェクトを繰り返して、記事の情報を出力します -->
    
        <?php foreach ($articles as $article): ?>
        <tr>
            <td>
                <?= $this->Html->link($article->title, ['action' => 'view', $article->slug]) ?>
            </td>
            <td>
                <?= $article->created->format(DATE_RFC850) ?>
            </td>
        </tr>
        <?php endforeach; ?>
    </table>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  

前のセクションでは、 `set()` を使って 'articles' 変数をビューに割り当てました。 ビューに渡された変数は、上記のコードの中で使用したローカル変数として、 ビューテンプレートの中で利用できます。

`$this->Html` というオブジェクトを使っていることにお気づきでしょうか。 これは、 CakePHP の [HtmlHelper](https://book.cakephp.org/3.x/ja/views/helpers/html.html)
 のインスタンスです。 CakePHP には、リンク、フォーム、ページ制御ボタンの作成などのタスクを簡単に行うための 一連のビューヘルパーが付属しています。 [ヘルパー](https://book.cakephp.org/3.x/ja/views/helpers.html)
 について、 その章で詳しく学べますが、ここで重要なことは、 `link()` メソッドは、 与えられたリンクテキスト(第１パラメーター) と URL (第２パラメーター) を元に HTML リンクを生成することです。

CakePHP で URL を指定する際、配列や [名前付きルート](https://book.cakephp.org/3.x/ja/development/routing.html#named-routes)
 が 推奨されます。これらの構文で、CakePHP が提供するリバースルーティング機能を 活用することができます。

この時点で、ブラウザーで **[http://localhost:8765/articles/index](http://localhost:8765/articles/index)
** を 見ることができるはずです。記事のタイトルとテーブルのリストで正しくフォーマットされた リストビューが表示されます。

view アクションの作成 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/articles-controller.html#view-%E3%82%A2%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3%E3%81%AE%E4%BD%9C%E6%88%90)

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

記事一覧の 'view' リンクの一つをクリックした際、アクションが実装されてないという エラーページが表示されるはずです。今から、それを修正しましょう。 :

    // 既存の src/Controller/ArticlesController.php ファイルに追加
    
    public function view($slug = null)
    {
        $article = $this->Articles->findBySlug($slug)->firstOrFail();
        $this->set(compact('article'));
    }

1  
2  
3  
4  
5  
6  
7  

これはシンプルなアクションですが、いくつかの強力な CakePHP 機能を使用しています。 [動的なファインダー](https://book.cakephp.org/3.x/ja/orm/retrieving-data-and-resultsets.html#dynamic-finders)
 である `findBySlug()` を使用することにより アクションを開始します。このメソッドは、与えられたスラグによって記事を検索する基本的なクエリーを 作成することができます。その時、最初のレコードを取得するか `NotFoundException` を投げるか のいずれかをする `firstOrFail()` を使います。

このアクションは `$slug` パラメーターを持ちますが、そのパラメーターはどこから来るのでしょう？ ユーザーが `/articles/view/first-post` をリクエストした際、 値 'first-post' が CakePHP のルーティングとディスパッチレイヤーで `$slug` に渡されます。 新しいアクションを保存してブラウザーをリロードすると、別の CakePHP エラーページが表示され、 view テンプレートが見つからないことがわかります。それを修正しましょう。

view テンプレートの作成 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/articles-controller.html#view-%E3%83%86%E3%83%B3%E3%83%95%E3%82%9A%E3%83%AC%E3%83%BC%E3%83%88%E3%81%AE%E4%BD%9C%E6%88%90)

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

新しい 'view' アクションのビューを作成し、 **src/Template/Articles/view.ctp** に置きましょう。

    <!-- File: src/Template/Articles/view.ctp -->
    
    <h1><?= h($article->title) ?></h1>
    <p><?= h($article->body) ?></p>
    <p><small>作成日時: <?= $article->created->format(DATE_RFC850) ?></small></p>
    <p><?= $this->Html->link('Edit', ['action' => 'edit', $article->slug]) ?></p>

1  
2  
3  
4  
5  
6  

`/articles/index` のリンクを使うことによって、動作することを確認できますし、 `/articles/view/slug-name` のような URL にアクセスすることによって手動で記事を リクエストすることを確認できます。

記事の追加 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/articles-controller.html#%E8%A8%98%E4%BA%8B%E3%81%AE%E8%BF%BD%E5%8A%A0)

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

基本的な読み込みビューを作成できたので、新しい記事を作成できるようにする必要があります。 まず、 `ArticlesController` に `add()` アクションを作成してください。 コントローラーは次のようになります。 :

    // src/Controller/ArticlesController.php
    
    namespace App\Controller;
    
    use App\Controller\AppController;
    
    class ArticlesController extends AppController
    {
    
        public function initialize()
        {
            parent::initialize();
    
            $this->loadComponent('Paginator');
            $this->loadComponent('Flash'); // FlashComponent をインクルード
        }
    
        public function index()
        {
            $articles = $this->Paginator->paginate($this->Articles->find());
            $this->set(compact('articles'));
        }
    
        public function view($slug)
        {
            $article = $this->Articles->findBySlug($slug)->firstOrFail();
            $this->set(compact('article'));
        }
    
        public function add()
        {
            $article = $this->Articles->newEntity();
            if ($this->request->is('post')) {
                $article = $this->Articles->patchEntity($article, $this->request->getData());
    
                // user_id の決め打ちは一時的なもので、あとで認証を構築する際に削除されます。
                $article->user_id = 1;
    
                if ($this->Articles->save($article)) {
                    $this->Flash->success(__('Your article has been saved.'));
                    return $this->redirect(['action' => 'index']);
                }
                $this->Flash->error(__('Unable to add your article.'));
            }
            $this->set('article', $article);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40  
41  
42  
43  
44  
45  
46  
47  

NOTE

[フラッシュ](https://book.cakephp.org/3.x/ja/controllers/components/flash.html)
 コンポーネントを、使用するコントローラーに含める 必要があります。また、 `AppController` に含めてもよいでしょう。

こちらがこの `add()` アクションの行うことです。

*   リクエストの HTTP メソッドが POST だった場合、Articles モデルを使用してデータを保存しようとします。
*   なんらかの理由で保存しなかった場合、ただビューを描画します。これは、ユーザーバリデーションエラーや その他の警告を表示する機会を与えてくれます。

全ての CakePHP のリクエストは、 `$this->request` を使用してアクセス可能なリクエストオブジェクトを 含みます。リクエストオブジェクトは、今受信したリクエストに関する情報を含みます。リクエストが HTTP POST リクエストであることを確認するために `Cake\Http\ServerRequest::is()` メソッドを 使用します。

POST データは、 `$this->request->getData()` で利用可能です。それがどのような内容かを 知りたい場合に `pr()` 関数や `debug()` 関数を使って出力することができます。 データを保存するために、まず POST データを Article エンティティーに 「変換 (marshal)」します。 エンティティーは、以前作成した ArticlesTable を使用して永続化されます。

新しい記事を保存した後、セッションにメッセージをセットするために FlashComponent の `success()` メソッドを使用します。 `success` メソッドは PHP の [マジックメソッド機能](https://php.net/manual/ja/language.oop5.overloading.php#object.call)
 を使用して提供されます。フラッシュメッセージは、リダイレクトした後の次のページ上で表示されます。 レイアウトの中に、フラッシュメッセージを表示し、対応するセッション変数をクリアする `<?= $this->Flash->render() ?>` があります。最後に、保存が完了した後、 `Cake\Controller\Controller::redirect` を使ってユーザーを記事一覧に戻します。 パラメーター `['action' => 'index']` は、例えば `ArticlesController` の index アクションの場合、 URL `/articles` に変換します。 [API](https://api.cakephp.org/)
 の `Cake\Routing\Router::url()` 関数を参照すると、様々な CakePHP 関数の URL を 指定できる書式を見ることができます。

add テンプレートの作成 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/articles-controller.html#add-%E3%83%86%E3%83%B3%E3%83%95%E3%82%9A%E3%83%AC%E3%83%BC%E3%83%88%E3%81%AE%E4%BD%9C%E6%88%90)

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

こちらが add ビューテンプレートです。

    <!-- File: src/Template/Articles/add.ctp -->
    
    <h1>記事の追加</h1>
    <?php
        echo $this->Form->create($article);
        // 今はユーザーを直接記述
        echo $this->Form->control('user_id', ['type' => 'hidden', 'value' => 1]);
        echo $this->Form->control('title');
        echo $this->Form->control('body', ['rows' => '3']);
        echo $this->Form->button(__('Save Article'));
        echo $this->Form->end();
    ?>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

FormHelper を使うと、 HTML フォームの開始タグを生成できます。 こちらが `$this->Form->create()` が生成する HTML です。

    <form method="post" action="/articles/add">

1  

URL オプションなしで `create()` を呼び出したので、 `FormHelper` は、フォームを 現在のアクションに戻したいと仮定します。

`$this->Form->control()` メソッドは、同じ名前のフォーム要素を作成するために使われます。 １番目のパラメーターは、どのフィールドに対応するかを CakePHP に伝えます。そして、２番目の パラメーターは、さまざまなオプションを指定できます。上記の場合、テキストエリアの行数などです。 ここではちょっとした内部情報の確認 (introspection) と規約の使用があります。 `control()` は、指定されたモデルフィールドにもとづいて異なるフォーム要素を出力し、 語形変化 (inflection) を使ってラベルを生成します。オプションを使用して、 フォームコントロールのラベル、入力、または、その他の要素をカスタマイズすることができます。 `$this->Form->end()` の呼び出しでフォームを閉じます。

さて、 **src/Template/Articles/index.ctp** ビューを更新して、新しい 「記事の追加」リンクを追加しましょう。 `<table>` の前に以下の行を追加してください。 :

    <?= $this->Html->link('記事の追加', ['action' => 'add']) ?>

1  

シンプルなスラグ生成の追加 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/articles-controller.html#%E3%82%B7%E3%83%B3%E3%83%95%E3%82%9A%E3%83%AB%E3%81%AA%E3%82%B9%E3%83%A9%E3%82%AF%E3%82%99%E7%94%9F%E6%88%90%E3%81%AE%E8%BF%BD%E5%8A%A0)

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

記事を今保存すると、スラグ属性は、作成されておらず、カラムは `NOT NULL` なので保存に失敗します。 スラグの値は、通常、URL セーフなバージョンの記事タイトルです。スラグを作成するために ORM の [beforeSave() コールバック](https://book.cakephp.org/3.x/ja/orm/table-objects.html#table-callbacks)
 が使用できます。 :

    // src/Model/Table/ArticlesTable.php の中で
    namespace App\Model\Table;
    
    use Cake\ORM\Table;
    // Text クラス
    use Cake\Utility\Text;
    
    // 次のメソッドを追加してください。
    
    public function beforeSave($event, $entity, $options)
    {
        if ($entity->isNew() && !$entity->slug) {
            $sluggedTitle = Text::slug($entity->title);
            // スラグをスキーマで定義されている最大長に調整
            $entity->slug = substr($sluggedTitle, 0, 191);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

このコードはシンプルで、重複したスラグを考慮していません。しかし、後でそれを修正します。

edit アクションの追加 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/articles-controller.html#edit-%E3%82%A2%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3%E3%81%AE%E8%BF%BD%E5%8A%A0)

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

今のアプリケーションは、記事を保存できますが編集はできません。今から修正しましょう。 `ArticlesController` に次のアクションを追加してください。 :

    // src/Controller/ArticlesController.php の中で
    
    // 次のメソッドを追加してください。
    
    public function edit($slug)
    {
        $article = $this->Articles->findBySlug($slug)->firstOrFail();
        if ($this->request->is(['post', 'put'])) {
            $this->Articles->patchEntity($article, $this->request->getData());
            if ($this->Articles->save($article)) {
                $this->Flash->success(__('Your article has been updated.'));
                return $this->redirect(['action' => 'index']);
            }
            $this->Flash->error(__('Unable to update your article.'));
        }
    
        $this->set('article', $article);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

このアクションは、まずユーザーが既存のレコードにアクセスすることを確保します。 `$slug` パラメーターの中に渡されなかったり、記事が存在しなかった場合、 `NotFoundException` が投げられ、 CakePHP の ErrorHandler が、適切なエラーページを 描画します。

次に、このアクションはリクエストが POST または PUT いずれかのリクエストかどうかをチェックします。 そうであれば、POST/PUT データを元に、 `patchEntity()` メソッドを使って article エンティティーを更新します。最後に、 `save()` を呼び出して、 適切なフラッシュメッセージを設定し、リダイレクトするか検証エラーを表示します。

edit テンプレートの作成 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/articles-controller.html#edit-%E3%83%86%E3%83%B3%E3%83%95%E3%82%9A%E3%83%AC%E3%83%BC%E3%83%88%E3%81%AE%E4%BD%9C%E6%88%90)

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

edit テンプレートは次のようになります。

    <!-- File: src/Template/Articles/edit.ctp -->
    
    <h1>記事の編集</h1>
    <?php
        echo $this->Form->create($article);
        echo $this->Form->control('user_id', ['type' => 'hidden']);
        echo $this->Form->control('title');
        echo $this->Form->control('body', ['rows' => '3']);
        echo $this->Form->button(__('Save Article'));
        echo $this->Form->end();
    ?>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

このテンプレートは、編集フォーム（値が入力された状態）に加えて、 必要な検証エラーメッセージを出力します。

特定の記事を編集するためのリンクで index ビューを更新できるようになりました。

    <!-- File: src/Template/Articles/index.ctp  (編集リンク付き) -->
    
    <h1>記事一覧</h1>
    <p><?= $this->Html->link("記事の追加", ['action' => 'add']) ?></p>
    <table>
        <tr>
            <th>タイトル</th>
            <th>作成日時</th>
            <th>操作</th>
        </tr>
    
    <!-- ここで、$articles クエリーオブジェクトを繰り返して、記事情報を出力します -->
    
    <?php foreach ($articles as $article): ?>
        <tr>
            <td>
                <?= $this->Html->link($article->title, ['action' => 'view', $article->slug]) ?>
            </td>
            <td>
                <?= $article->created->format(DATE_RFC850) ?>
            </td>
            <td>
                <?= $this->Html->link('編集', ['action' => 'edit', $article->slug]) ?>
            </td>
        </tr>
    <?php endforeach; ?>
    
    </table>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  

Articles の検証ルールの更新 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/articles-controller.html#articles-%E3%81%AE%E6%A4%9C%E8%A8%BC%E3%83%AB%E3%83%BC%E3%83%AB%E3%81%AE%E6%9B%B4%E6%96%B0)

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

この時点まで、記事は入力検証が行われていませんでした。 [バリデーター](https://book.cakephp.org/3.x/ja/orm/validation.html#validating-request-data)
 を使って修正しましょう。 :

    // src/Model/Table/ArticlesTable.php
    
    // この use 文を名前空間宣言のすぐ下に追加して、
    // Validator クラスをインポートします。
    use Cake\Validation\Validator;
    
    // 次のメソッドを追加してください。
    public function validationDefault(Validator $validator)
    {
        $validator
            ->allowEmptyString('title', false)
            ->minLength('title', 10)
            ->maxLength('title', 255)
    
            ->allowEmptyString('body', false)
            ->minLength('body', 10);
    
        return $validator;
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  

`validationDefault()` メソッドは、 `save()` メソッドが呼ばれる際のデータの検証方法を CakePHP に伝えます。ここでは、title フィールドと body フィールドの両方が空であってはならず、 長さに制約があることを指定しました。

CakePHP の検証エンジンは強力で柔軟性があります。メールアドレス、IP アドレスなどのようにタスクに 頻繁に使用されるルール一式を提供し、独自の検証ルールを追加する柔軟性を提供します。 その設定の詳細については、 [バリデーション](https://book.cakephp.org/3.x/ja/core-libraries/validation.html)
 のドキュメントを確認してください。

さて、検証ルールが整いましたので、 それがどのように動くかを見るためにアプリを使って空のタイトルや本文で記事を追加してみてください。 FormHelper の `Cake\View\Helper\FormHelper::control()` メソッドを使用して、 フォーム要素を作成しているので、検証エラーメッセージが自動的に表示されます。

delete アクションの追加 [​](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/articles-controller.html#delete-%E3%82%A2%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3%E3%81%AE%E8%BF%BD%E5%8A%A0)

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

次に、ユーザーが記事を削除する方法を作ってみましょう。 `ArticlesController` の中の `delete()` アクションから始めましょう。 :

    // src/Controller/ArticlesController.php
    
    public function delete($slug)
    {
        $this->request->allowMethod(['post', 'delete']);
    
        $article = $this->Articles->findBySlug($slug)->firstOrFail();
        if ($this->Articles->delete($article)) {
            $this->Flash->success(__('The {0} article has been deleted.', $article->title));
            return $this->redirect(['action' => 'index']);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

このロジックは `$slug` で指定された記事を削除し、 `$this->Flash->success()` を使って `/articles` にリダイレクトした後に確認メッセージを表示します。 ユーザーが GET リクエストを使って記事を削除しようとすると、 `allowMethod()` は例外をスローします。 キャッチされない例外は CakePHP の例外ハンドラによって捕捉され、素晴らしいエラーページが表示されます。 アプリケーションで生成する必要のあるさまざまな HTTP エラーを示すために使用できる組み込みの [例外](https://book.cakephp.org/3.x/ja/development/errors.html)
 が多数あります。

WARNING

ウェブクローラーが誤ってすべてのコンテンツを削除する可能性があるため、 GET リクエストを使用してコンテンツを削除することは _とても_ 危険です。 それでコントローラーの中で `allowMethod()` を使ったのです。

私たちはロジックを実行して、別のアクションにリダイレクトしているだけなので、 このアクションにはテンプレートはありません。ユーザーが記事を削除できるリンク付きに index テンプレートを更新するといいでしょう。

    <!-- File: src/Template/Articles/index.ctp  (削除リンク付き) -->
    
    <h1>記事一覧</h1>
    <p><?= $this->Html->link("記事の追加", ['action' => 'add']) ?></p>
    <table>
        <tr>
            <th>タイトル</th>
            <th>作成日時</th>
            <th>操作</th>
        </tr>
    
    <!-- ここで、$articles クエリーオブジェクトを繰り返して、記事情報を出力します -->
    
    <?php foreach ($articles as $article): ?>
        <tr>
            <td>
                <?= $this->Html->link($article->title, ['action' => 'view', $article->slug]) ?>
            </td>
            <td>
                <?= $article->created->format(DATE_RFC850) ?>
            </td>
            <td>
                <?= $this->Html->link('編集', ['action' => 'edit', $article->slug]) ?>
                <?= $this->Form->postLink(
                    '削除',
                    ['action' => 'delete', $article->slug],
                    ['confirm' => 'よろしいですか?'])
                ?>
            </td>
        </tr>
    <?php endforeach; ?>
    
    </table>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  

`Cake\View\Helper\FormHelper::postLink()` を使用すると、 JavaScript を使用して記事を削除する POST リクエストを行うリンクが作成されます。

NOTE

また、このビューコードは `FormHelper` を使って記事を削除しようとする前に JavaScript の確認ダイアログを表示します。

基本的な記事管理のセットアップの後は、 [タグとユーザーテーブルの基本的な操作](https://book.cakephp.org/3.x/ja/tutorials-and-examples/cms/tags-and-users.html)
 を作成します。

---

# Bake の拡張 - 2.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/bake/edit/2.x/docs/ja/development.rst)

[](https://book.cakephp.org/bake/2/ja/development.html#page-contents)

### Page Contents

*   [Bake の拡張](https://book.cakephp.org/bake/2/ja/development.html#)
    *   [Bake イベント](https://book.cakephp.org/bake/2/ja/development.html#id1)
        
    *   [Bake テンプレート構文](https://book.cakephp.org/bake/2/ja/development.html#id2)
        
    *   [Bake テーマの作成](https://book.cakephp.org/bake/2/ja/development.html#creating-a-bake-theme)
        
    *   [Bake テンプレートのカスタマイズ](https://book.cakephp.org/bake/2/ja/development.html#id4)
        
    *   [Bake コマンドオプションの新規作成](https://book.cakephp.org/bake/2/ja/development.html#id5)
        

Bake の拡張[¶](https://book.cakephp.org/bake/2/ja/development.html#bake "この見出しへのパーマリンク")

======================================================================================

Bake は、アプリケーションやプラグインが基本機能に対して変更または追加を可能にする 拡張可能なアーキテクチャーを備えています。Bake は、 [Twig](https://twig.symfony.com/)
 テンプレートエンジンを使用したビュークラスを利用します。

Bake イベント[¶](https://book.cakephp.org/bake/2/ja/development.html#id1 "この見出しへのパーマリンク")

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

`BakeView` は、ビュークラスとして、他のビュークラスと同様のイベントに加え、 1つの特別な初期化 (initialize) イベントを発します。しかし、一方で標準ビュークラスは、 イベントのプレフィックス "View." を使用しますが、 `BakeView` は、 イベントのプレフィックス "Bake." を使用しています。

初期化イベントは、すべての bake の出力に対して変更を加えるために使用できます。 例えば、bake ビュークラスに他のヘルパーを追加するためにこのイベントは使用されます。

<?php
// config/bootstrap\_cli.php

use Cake\\Event\\Event;
use Cake\\Event\\EventManager;

EventManager::instance()\->on('Bake.initialize', function (Event $event) {
    $view \= $event\->getSubject();

    // bake テンプレートの中で MySpecial ヘルパーの使用を可能にします
    $view\->loadHelper('MySpecial', \['some' \=> 'config'\]);

    // そして、$author 変数を利用可能にするために追加
    $view\->set('author', 'Andy');

});

別のプラグインの中から bake を変更したい場合は、プラグインの `config/bootstrap.php` ファイルでプラグインの Bake イベントを置くことは良いアイデアです。

Bake イベントは、既存のテンプレートに小さな変更を行うための便利なことができます。 例えば、コントローラーやテンプレートファイルを bake する際に使用される変数名を 変更するために、bake テンプレートで使用される変数を変更するために `Bake.beforeRender` で呼び出される関数を使用することができます。

<?php
// config/bootstrap\_cli.php

use Cake\\Event\\Event;
use Cake\\Event\\EventManager;

EventManager::instance()\->on('Bake.beforeRender', function (Event $event) {
    $view \= $event\->getSubject();

    // indexes の中のメインデータ変数に $rows を使用
    if ($view\->get('pluralName')) {
        $view\->set('pluralName', 'rows');
    }
    if ($view\->get('pluralVar')) {
        $view\->set('pluralVar', 'rows');
    }

    // view と edit の中のメインデータ変数に $theOne を使用
    if ($view\->get('singularName')) {
        $view\->set('singularName', 'theOne');
    }
    if ($view\->get('singularVar')) {
        $view\->set('singularVar', 'theOne');
    }

});

特定の生成されたファイルへの `Bake.beforeRender` と `Bake.afterRender` イベントを指定することもあるでしょう。例えば、 **Controller/controller.twig** ファイルから生成する際、 UsersController に特定のアクションを追加したい場合、以下のイベントを使用することができます。

<?php
// config/bootstrap\_cli.php

use Cake\\Event\\Event;
use Cake\\Event\\EventManager;
use Cake\\Utility\\Hash;

EventManager::instance()\->on(
    'Bake.beforeRender.Controller.controller',
    function (Event $event) {
        $view \= $event\->getSubject();
        if ($view\->viewVars\['name'\] \== 'Users') {
            // Users コントローラーに login と logout を追加
            $view\->viewVars\['actions'\] \= \[\
                'login',\
                'logout',\
                'index',\
                'view',\
                'add',\
                'edit',\
                'delete'\
            \];
        }
    }
);

特定の bake テンプレートのためのイベントリスナーを指定することによって、 bake 関連のイベント・ロジックを簡素化し、テストするのが容易であるコールバックを 提供することができます。

Bake テンプレート構文[¶](https://book.cakephp.org/bake/2/ja/development.html#id2 "この見出しへのパーマリンク")

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

Bake テンプレートファイルは、 [Twig](https://twig.symfony.com/doc/2.x/)
 テンプレート構文を使用します。

だから、例えば、以下のようにシェルを bake した場合:

bin/cake bake shell Foo

(**vendor/cakephp/bake/src/Template/Bake/Shell/shell.twig**) を使用した テンプレートは、以下のようになります。

<?php
namespace {{ namespace }}\\Shell;

use Cake\\Console\\Shell;

/\*\*
 \* {{ name }} shell command.
 \*/
class {{ name }}Shell extends Shell
{
    /\*\*
     \* main() method.
     \*
     \* @return bool|int Success or error code.
     \*/
    public function main()
    {
    }

}

そして、 bake で得られたクラス (**src/Shell/FooShell.php**) は、 このようになります。

<?php
namespace App\\Shell;

use Cake\\Console\\Shell;

/\*\*
 \* Foo shell command.
 \*/
class FooShell extends Shell
{
    /\*\*
     \* main() method.
     \*
     \* @return bool|int Success or error code.
     \*/
    public function main()
    {
    }

}

注釈

バージョン 1.5.0 より前の bake は、 .ctp テンプレートファイルでカスタム erb スタイルのタグを 使用していました。

*   `<%` Bake テンプレートの PHP 開始タグ
    
*   `%>` Bake テンプレートの PHP 終了タグ
    
*   `<%=` Bake テンプレートの PHP ショートエコータグ
    
*   `<%-` Bake テンプレートの PHP 開始タグ、タグの前に、先頭の空白を除去
    
*   `-%>` Bake テンプレートの PHP 終了タグ、タグの後に末尾の空白を除去
    

Bake テーマの作成[¶](https://book.cakephp.org/bake/2/ja/development.html#creating-a-bake-theme "この見出しへのパーマリンク")

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

"bake" コマンドによって生成された出力を変更したい場合、bake が使用するテンプレートの 一部または全部を置き換えることができる、独自の bake の「テーマ」を作成することができます。 これを行うための最善の方法は、次のとおりです。

1.  新しいプラグインを bake します。プラグインの名前は bake の「テーマ」名になります。
    
2.  新しいディレクトリー **plugins/\[name\]/src/Template/Bake/Template/** を作成します。
    
3.  **vendor/cakephp/bake/src/Template/Bake/Template** から上書きしたい テンプレートをあなたのプラグインの中の適切なファイルにコピーしてください。
    
4.  bake を実行するときに、必要であれば、 bake のテーマを指定するための `--theme` オプションを使用してください。各呼び出しでこのオプションを指定しなくても済むように、 カスタムテーマをデフォルトテーマとして使用するように設定することもできます。
    
    <?php
    // config/bootstrap.php または config/bootstrap\_cli.php の中で
    Configure::write('Bake.theme', 'MyTheme');
    

Bake テンプレートのカスタマイズ[¶](https://book.cakephp.org/bake/2/ja/development.html#id4 "この見出しへのパーマリンク")

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

"bake" コマンドによって生成されるデフォルトの出力を変更したい場合、アプリケーションで独自の bake テンプレートを作成することができます。この方法では、bake する際、コマンドラインで `--theme` オプションを使用していません。これを行うための最善の方法は、次のとおりです。

1.  新しいディレクトリー **/templates/plugin/Bake/** を作成します。
    
2.  **vendor/cakephp/bake/templates/bake/** から上書きしたいテンプレートを あなたのアプリケーションの中の適切なファイルにコピーします。
    

Bake コマンドオプションの新規作成[¶](https://book.cakephp.org/bake/2/ja/development.html#id5 "この見出しへのパーマリンク")

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

あなたのアプリケーションやプラグインでタスクを作成することによって、新しい bake コマンドの オプションを追加したり、CakePHP が提供するオプションを上書きすることが可能です。 `Bake\Shell\Task\BakeTask` を継承することで、bake は、あなたの新しいタスクを見つけて bake の一部としてそれを含めます。

例として、任意の foo クラスを作成するタスクを作ります。 まず、 **src/Shell/Task/FooTask.php** タスクファイルを作成します。 私たちのシェルタスクが単純になるように、 `SimpleBakeTask` を継承します。 `SimpleBakeTask` は抽象クラスで、どのタスクが呼ばれるか、どこにファイルを生成するか、 どのテンプレートを使用するかを bake に伝える３つのメソッドを定義することが必要です。 FooTask.php ファイルは次のようになります。

<?php
namespace App\\Shell\\Task;

use Bake\\Shell\\Task\\SimpleBakeTask;

class FooTask extends SimpleBakeTask
{
    public $pathFragment \= 'Foo/';

    public function name()
    {
        return 'foo';
    }

    public function fileName($name)
    {
        return $name . 'Foo.php';
    }

    public function template()
    {
        return 'foo';
    }

}

このファイルが作成されたら、コードを生成する際に bake 使用することができるテンプレートを 作成する必要があります。 **src/Template/Bake/foo.twig** を作成してください。 このファイルに、以下の内容を追加します。

<?php
namespace {{ namespace }}\\Foo;

/\*\*
 \* {{ name }} foo
 \*/
class {{ name }}Foo
{
    // コードを追加。
}

これで、`bin/cake bake` の出力に新しいタスクが表示されるはずです。 `bin/cake bake foo Example` を実行して、新しいタスクを実行することができます。 これは、使用するアプリケーションの **src/Foo/ExampleFoo.php** で 新しい `ExampleFoo` クラスを生成します。

また、 `ExampleFoo` クラスのテストファイルを作成するために `bake` を呼びたい場合は、 カスタムコマンド名のクラスサフィックスと名前空間を登録するために `FooTask` クラスの `bakeTest()` メソッドをオーバーライドする必要があります。

public function bakeTest($className)
{
    if (!isset($this\->Test\->classSuffixes\[$this\->name()\])) {
      $this\->Test\->classSuffixes\[$this\->name()\] \= 'Foo';
    }

    $name \= ucfirst($this\->name());
    if (!isset($this\->Test\->classTypes\[$name\])) {
      $this\->Test\->classTypes\[$name\] \= 'Foo';
    }

    return parent::bakeTest($className);
}

*   **class suffix** は `bake` 呼び出しで与えられた名前に追加します。前の例では、 `ExampleFooTest.php` ファイルを作成します。
    
*   **class type** は、（あなたが bake するアプリやプラグインに関連する） あなたのファイルを導くために使用されるサブ名前空間です。 前の例では、名前空間 `App\Test\TestCase\Foo` でテストを作成します。
    

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# <no title> - 2.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/chronos/edit/2.x/docs/ja/contents.rst)

[](https://book.cakephp.org/chronos/2/ja/contents.html#page-contents)

CakePHP Chronos

*   [Chronos](https://book.cakephp.org/chronos/2/ja/index.html)
    *   [インストール](https://book.cakephp.org/chronos/2/ja/index.html#id1)
        
    *   [概要](https://book.cakephp.org/chronos/2/ja/index.html#id2)
        
    *   [インスタンスの作成](https://book.cakephp.org/chronos/2/ja/index.html#id3)
        
    *   [イミュータブルオブジェクトの動作](https://book.cakephp.org/chronos/2/ja/index.html#id4)
        
    *   [日付オブジェクト](https://book.cakephp.org/chronos/2/ja/index.html#id5)
        
    *   [変更メソッド](https://book.cakephp.org/chronos/2/ja/index.html#id6)
        
    *   [比較メソッド](https://book.cakephp.org/chronos/2/ja/index.html#id7)
        
    *   [差の生成](https://book.cakephp.org/chronos/2/ja/index.html#id8)
        
    *   [フォーマットの設定](https://book.cakephp.org/chronos/2/ja/index.html#id9)
        
    *   [日付要素の抽出](https://book.cakephp.org/chronos/2/ja/index.html#id10)
        
    *   [テストの支援](https://book.cakephp.org/chronos/2/ja/index.html#id11)
        
*   [API](https://api.cakephp.org/chronos)
    

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# Contents - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/elastic-search/edit/3.x/docs/ja/contents.rst)

[](https://book.cakephp.org/elasticsearch/3/ja/contents.html#page-contents)

Contents[¶](https://book.cakephp.org/elasticsearch/3/ja/contents.html#contents "この見出しへのパーマリンク")

================================================================================================

CakePHP ElasticSearch

*   [ElasticSearch](https://book.cakephp.org/elasticsearch/3/ja/index.html)
    *   [インストール](https://book.cakephp.org/elasticsearch/3/ja/index.html#id2)
        
    *   [概要](https://book.cakephp.org/elasticsearch/3/ja/index.html#id3)
        
    *   [Document オブジェクト](https://book.cakephp.org/elasticsearch/3/ja/index.html#document)
        
    *   [インデックス付きドキュメントの検索](https://book.cakephp.org/elasticsearch/3/ja/index.html#id4)
        
    *   [データのバリデーションとアプリケーションルールの使用](https://book.cakephp.org/elasticsearch/3/ja/index.html#id5)
        
    *   [新しいドキュメントの保存](https://book.cakephp.org/elasticsearch/3/ja/index.html#id6)
        
    *   [既存ドキュメントの更新](https://book.cakephp.org/elasticsearch/3/ja/index.html#id7)
        
    *   [ドキュメントの削除](https://book.cakephp.org/elasticsearch/3/ja/index.html#id8)
        
    *   [埋め込みドキュメント](https://book.cakephp.org/elasticsearch/3/ja/index.html#id9)
        
    *   [Type インスタンスの取得](https://book.cakephp.org/elasticsearch/3/ja/index.html#type)
        
    *   [テストフィクスチャー](https://book.cakephp.org/elasticsearch/3/ja/index.html#id11)
        

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# <no title> - 1.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/bake/edit/1.x/docs/ja/contents.rst)

[](https://book.cakephp.org/bake/1/ja/contents.html#page-contents)

CakePHP Bake

*   [Bake コンソール](https://book.cakephp.org/bake/1/ja/index.html)
    *   [インストール手順](https://book.cakephp.org/bake/1/ja/index.html#id1)
        
*   [Bake でコード生成](https://book.cakephp.org/bake/1/ja/usage.html)
    *   [Bake テーマオプション](https://book.cakephp.org/bake/1/ja/usage.html#id1)
        
*   [Bake の拡張](https://book.cakephp.org/bake/1/ja/development.html)
    *   [Bake イベント](https://book.cakephp.org/bake/1/ja/development.html#id1)
        
    *   [Bake テンプレート構文](https://book.cakephp.org/bake/1/ja/development.html#id2)
        
    *   [Bake テーマの作成](https://book.cakephp.org/bake/1/ja/development.html#creating-a-bake-theme)
        
    *   [Bake テンプレートのカスタマイズ](https://book.cakephp.org/bake/1/ja/development.html#id4)
        
    *   [Bake コマンドオプションの新規作成](https://book.cakephp.org/bake/1/ja/development.html#id5)
        

[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://cakesf.herokuapp.com/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")
[#IRC](https://webchat.freenode.net/?channels=cakephp "IRC")

---

# <no title> - 1.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/chronos/edit/1.x/docs/ja/contents.rst)

[](https://book.cakephp.org/chronos/1/ja/contents.html#page-contents)

CakePHP Chronos

*   [Chronos](https://book.cakephp.org/chronos/1/ja/index.html)
    *   [インストール](https://book.cakephp.org/chronos/1/ja/index.html#id1)
        
    *   [概要](https://book.cakephp.org/chronos/1/ja/index.html#id2)
        
    *   [インスタンスの作成](https://book.cakephp.org/chronos/1/ja/index.html#id3)
        
    *   [イミュータブルオブジェクトの動作](https://book.cakephp.org/chronos/1/ja/index.html#id4)
        
    *   [日付オブジェクト](https://book.cakephp.org/chronos/1/ja/index.html#id5)
        
    *   [変更メソッド](https://book.cakephp.org/chronos/1/ja/index.html#id6)
        
    *   [比較メソッド](https://book.cakephp.org/chronos/1/ja/index.html#id7)
        
    *   [差の生成](https://book.cakephp.org/chronos/1/ja/index.html#id8)
        
    *   [フォーマットの設定](https://book.cakephp.org/chronos/1/ja/index.html#id9)
        
    *   [日付要素の抽出](https://book.cakephp.org/chronos/1/ja/index.html#id10)
        
    *   [テストの支援](https://book.cakephp.org/chronos/1/ja/index.html#id11)
        
*   [API](https://api.cakephp.org/chronos)
    

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# <no title> - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/debug_kit/edit/3.x/docs/ja/contents.rst)

[](https://book.cakephp.org/debugkit/3/ja/contents.html#page-contents)

CakePHP DebugKit

*   [Debug Kit](https://book.cakephp.org/debugkit/3/ja/index.html)
    *   [インストール](https://book.cakephp.org/debugkit/3/ja/index.html#id1)
        
    *   [設定](https://book.cakephp.org/debugkit/3/ja/index.html#id2)
        
    *   [ツールバーの使い方](https://book.cakephp.org/debugkit/3/ja/index.html#id4)
        
    *   [履歴パネルを使用する](https://book.cakephp.org/debugkit/3/ja/index.html#id5)
        
    *   [メールパネルを使用](https://book.cakephp.org/debugkit/3/ja/index.html#id6)
        
    *   [独自のパネルを開発する](https://book.cakephp.org/debugkit/3/ja/index.html#id8)
        
    *   [ヘルパー関数](https://book.cakephp.org/debugkit/3/ja/index.html#id15)
        

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# Contents - 2.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/elastic-search/edit/master/docs/ja/contents.rst)

[](https://book.cakephp.org/elasticsearch/2/ja/contents.html#page-contents)

Contents[¶](https://book.cakephp.org/elasticsearch/2/ja/contents.html#contents "このヘッドラインへのパーマリンク")

===================================================================================================

CakePHP ElasticSearch

*   [ElasticSearch](https://book.cakephp.org/elasticsearch/2/ja/index.html)
    *   [インストール](https://book.cakephp.org/elasticsearch/2/ja/index.html#id2)
        
    *   [概要](https://book.cakephp.org/elasticsearch/2/ja/index.html#id3)
        
    *   [Document オブジェクト](https://book.cakephp.org/elasticsearch/2/ja/index.html#document)
        
    *   [インデックス付きドキュメントの検索](https://book.cakephp.org/elasticsearch/2/ja/index.html#id4)
        
    *   [データのバリデーションとアプリケーションルールの使用](https://book.cakephp.org/elasticsearch/2/ja/index.html#id5)
        
    *   [新しいドキュメントの保存](https://book.cakephp.org/elasticsearch/2/ja/index.html#id6)
        
    *   [既存ドキュメントの更新](https://book.cakephp.org/elasticsearch/2/ja/index.html#id7)
        
    *   [ドキュメントの削除](https://book.cakephp.org/elasticsearch/2/ja/index.html#id8)
        
    *   [埋め込みドキュメント](https://book.cakephp.org/elasticsearch/2/ja/index.html#id9)
        
    *   [Type インスタンスの取得](https://book.cakephp.org/elasticsearch/2/ja/index.html#type)
        
    *   [テストフィクスチャー](https://book.cakephp.org/elasticsearch/2/ja/index.html#id11)
        

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# <no title> - 2.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/migrations/edit/2.x/docs/ja/contents.rst)

[](https://book.cakephp.org/migrations/2/ja/contents.html#page-contents)

CakePHP Migrations

*   [Migrations](https://book.cakephp.org/migrations/2/ja/index.html)
    *   [インストール](https://book.cakephp.org/migrations/2/ja/index.html#id1)
        
    *   [概要](https://book.cakephp.org/migrations/2/ja/index.html#id2)
        
    *   [マイグレーションファイルの作成](https://book.cakephp.org/migrations/2/ja/index.html#id3)
        
    *   [２つのデータベース間の状態の差分を生成する](https://book.cakephp.org/migrations/2/ja/index.html#id16)
        
    *   [コマンド](https://book.cakephp.org/migrations/2/ja/index.html#id17)
        
    *   [プラグイン内のマイグレーションファイルを使う](https://book.cakephp.org/migrations/2/ja/index.html#id19)
        
    *   [非シェルの環境でマイグレーションを実行する](https://book.cakephp.org/migrations/2/ja/index.html#id20)
        
    *   [小技と裏技](https://book.cakephp.org/migrations/2/ja/index.html#id21)
        

[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://cakesf.herokuapp.com/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")
[#IRC](https://webchat.freenode.net/?channels=cakephp "IRC")

---

# Bake でコード生成 - 1.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/bake/edit/1.x/docs/ja/usage.rst)

[](https://book.cakephp.org/bake/1/ja/usage.html#page-contents)

### Page Contents

*   [Bake でコード生成](https://book.cakephp.org/bake/1/ja/usage.html#)
    *   [Bake テーマオプション](https://book.cakephp.org/bake/1/ja/usage.html#id1)
        

Bake でコード生成[¶](https://book.cakephp.org/bake/1/ja/usage.html#bake "このヘッドラインへのパーマリンク")

======================================================================================

cake コンソールは、 PHP CLI (command line interface) で実行します。 もしスクリプトの実行に問題があるなら、以下を満たしてください。

1.  PHP CLI がインストールされているか適切なモジュールが有効か確認してください (例：MySQL, intl)。
    
2.  データベースのホストが 'localhost' で問題があるなら、代わりに '127.0.0.1' を使って下さい。 PHP CLI でこの問題がおこる可能性があります。
    
3.  使っているコンピューターの設定に応じて、 `bin/cake bake` で使用する cake bash スクリプトの 実行権限を設定する必要があります。
    

bake を実行する前にデータベースとの接続を確認しましょう。

`bin/cake bake` を引数無しで実行すると可能なタスクを表示できます。

Windows システムの場合、 `bin\cake bake` を試してみてください。

それは以下のように表示されます。

$ bin/cake bake

Welcome to CakePHP v3.1.6 Console
\---------------------------------------------------------------
App : src
Path: /var/www/cakephp.dev/src/
PHP: 5.5.8
\---------------------------------------------------------------
The following commands can be used to generate skeleton code for your application.

Available bake commands:

\- all
\- behavior
\- cell
\- component
\- controller
\- fixture
\- form
\- helper
\- mailer
\- migration
\- migration\_snapshot
\- model
\- plugin
\- shell
\- shell\-helper
\- template
\- test

By using \`cake bake \[name\]\` you can invoke a specific bake task.

より詳しい各コマンドの情報を得るには、 `--help` オプションをつけ実行してください。

$ bin/cake bake controller \--help

Welcome to CakePHP v3.1.6 Console
\---------------------------------------------------------------
App : src
Path: /var/www/cakephp.dev/src/
\---------------------------------------------------------------
Bake a controller skeleton.

Usage:
cake bake controller \[subcommand\] \[options\] \[<name\>\]

Subcommands:

all  Bake all controllers with CRUD methods.

To see help on a subcommand use \`cake bake controller \[subcommand\] --help\`

Options:

\--help, \-h        Display this help.
\--verbose, \-v     Enable verbose output.
\--quiet, \-q       Enable quiet output.
\--plugin, \-p      Plugin to bake into.
\--force, \-f       Force overwriting existing files without prompting.
\--connection, \-c  The datasource connection to get data from.
                  (default: default)
\--theme, \-t       The theme to use when baking code.
\--components      The comma separated list of components to use.
\--helpers         The comma separated list of helpers to use.
\--prefix          The namespace/routing prefix to use.
\--no\-test         Do not generate a test skeleton.
\--no\-actions      Do not generate basic CRUD action methods.

Arguments:

name  Name of the controller to bake. Can use Plugin.name to bake
    controllers into plugins. (optional)

Bake テーマオプション[¶](https://book.cakephp.org/bake/1/ja/usage.html#id1 "このヘッドラインへのパーマリンク")

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

テーマオプションは全 bake コマンドで一般的です。また、bake テンプレートファイルを変更することができます。 テーマを作るには、 [Bake テーマ作成ドキュメント](https://book.cakephp.org/bake/1/ja/development.html#creating-a-bake-theme)
 をご覧ください。

[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://cakesf.herokuapp.com/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")
[#IRC](https://webchat.freenode.net/?channels=cakephp "IRC")

---

# Contents - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/authorization/edit/3.x/docs/ja/contents.rst)

[](https://book.cakephp.org/authorization/3/ja/contents.html#page-contents)

Contents[¶](https://book.cakephp.org/authorization/3/ja/contents.html#contents "この見出しへのパーマリンク")

================================================================================================

CakePHP Authorization

*   [クイック スタート](https://book.cakephp.org/authorization/3/ja/index.html)
    *   [インストール](https://book.cakephp.org/authorization/3/ja/index.html#id2)
        
    *   [はじめに](https://book.cakephp.org/authorization/3/ja/index.html#id3)
        
    *   [より詳しく](https://book.cakephp.org/authorization/3/ja/index.html#id4)
        
*   [Policies](https://book.cakephp.org/authorization/3/ja/policies.html)
    *   [Policies を作成する](https://book.cakephp.org/authorization/3/ja/policies.html#id1)
        
    *   [ポリシーメソッドの書き方](https://book.cakephp.org/authorization/3/ja/policies.html#id2)
        
    *   [ポリシーのResultオブジェクト](https://book.cakephp.org/authorization/3/ja/policies.html#result)
        
*   [ポリシーリゾルバー](https://book.cakephp.org/authorization/3/ja/policy-resolvers.html)
    *   [MapResolver を使う](https://book.cakephp.org/authorization/3/ja/policy-resolvers.html#mapresolver)
        
    *   [OrmResolverを使う](https://book.cakephp.org/authorization/3/ja/policy-resolvers.html#ormresolver)
        
    *   [ResolverCollectionを使う](https://book.cakephp.org/authorization/3/ja/policy-resolvers.html#resolvercollection)
        
    *   [Resolver を作成する](https://book.cakephp.org/authorization/3/ja/policy-resolvers.html#resolver)
        
*   [認可ミドルウェア](https://book.cakephp.org/authorization/3/ja/middleware.html)
    *   [Identity Decorator](https://book.cakephp.org/authorization/3/ja/middleware.html#identity-decorator)
        
*   [認可の確認](https://book.cakephp.org/authorization/3/ja/checking-authorization.html)
    *   [単一リソースの認可チェック](https://book.cakephp.org/authorization/3/ja/checking-authorization.html#id2)
        
    *   [条件適用の範囲](https://book.cakephp.org/authorization/3/ja/checking-authorization.html#id3)
        
*   [AuthorizationComponent](https://book.cakephp.org/authorization/3/ja/component.html)
    *   [自動認可の確認](https://book.cakephp.org/authorization/3/ja/component.html#id1)
        
    *   [Authorization を確認する](https://book.cakephp.org/authorization/3/ja/component.html#authorization)
        
    *   [匿名のユーザー](https://book.cakephp.org/authorization/3/ja/component.html#id2)
        
    *   [ポリシースコープを適用する](https://book.cakephp.org/authorization/3/ja/component.html#id3)
        
*   [リクエスト認証ミドルウェア](https://book.cakephp.org/authorization/3/ja/request-authorization-middleware.html)
    *   [使用方法](https://book.cakephp.org/authorization/3/ja/request-authorization-middleware.html#id2)
        
*   [2.0 Migration Guide](https://book.cakephp.org/authorization/3/ja/2-0-migration-guide.html)
    *   [破壊的変更](https://book.cakephp.org/authorization/3/ja/2-0-migration-guide.html#id1)
        

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# <no title> - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/migrations/edit/3.x/docs/ja/contents.rst)

[](https://book.cakephp.org/migrations/3/ja/contents.html#page-contents)

CakePHP Migrations

*   [Migrations](https://book.cakephp.org/migrations/3/ja/index.html)
    *   [インストール](https://book.cakephp.org/migrations/3/ja/index.html#id1)
        
    *   [概要](https://book.cakephp.org/migrations/3/ja/index.html#id2)
        
    *   [マイグレーションファイルの作成](https://book.cakephp.org/migrations/3/ja/index.html#id3)
        
    *   [２つのデータベース間の状態の差分を生成する](https://book.cakephp.org/migrations/3/ja/index.html#id16)
        
    *   [コマンド](https://book.cakephp.org/migrations/3/ja/index.html#id17)
        
    *   [プラグイン内のマイグレーションファイルを使う](https://book.cakephp.org/migrations/3/ja/index.html#id19)
        
    *   [非シェルの環境でマイグレーションを実行する](https://book.cakephp.org/migrations/3/ja/index.html#id20)
        
    *   [小技と裏技](https://book.cakephp.org/migrations/3/ja/index.html#id21)
        

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# Contents - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/authentication/edit/3.x/docs/ja/contents.rst)

[](https://book.cakephp.org/authentication/3/ja/contents.html#page-contents)

Contents[¶](https://book.cakephp.org/authentication/3/ja/contents.html#contents "このヘッドラインへのパーマリンク")

====================================================================================================

CakePHP Authentication

*   [Quick Start](https://book.cakephp.org/authentication/3/ja/index.html)
    *   [はじめに](https://book.cakephp.org/authentication/3/ja/index.html#id1)
        
    *   [ログインアクションの構成](https://book.cakephp.org/authentication/3/ja/index.html#id3)
        
    *   [Further Reading](https://book.cakephp.org/authentication/3/ja/index.html#further-reading)
        
*   [認証機能](https://book.cakephp.org/authentication/3/ja/authenticators.html)
    *   [Session](https://book.cakephp.org/authentication/3/ja/authenticators.html#session)
        
    *   [Form](https://book.cakephp.org/authentication/3/ja/authenticators.html#form)
        
    *   [トークン](https://book.cakephp.org/authentication/3/ja/authenticators.html#id2)
        
    *   [JWT](https://book.cakephp.org/authentication/3/ja/authenticators.html#jwt)
        
    *   [Http基本](https://book.cakephp.org/authentication/3/ja/authenticators.html#http)
        
    *   [Httpダイジェスト](https://book.cakephp.org/authentication/3/ja/authenticators.html#id3)
        
    *   [クッキー認証機能 別名 "Remember Me"](https://book.cakephp.org/authentication/3/ja/authenticators.html#remember-me)
        
    *   [OAuth](https://book.cakephp.org/authentication/3/ja/authenticators.html#oauth)
        
    *   [イベント](https://book.cakephp.org/authentication/3/ja/authenticators.html#id4)
        
    *   [URL チェッカー](https://book.cakephp.org/authentication/3/ja/authenticators.html#url)
        
    *   [成功した Authenticator または Identifier の取得](https://book.cakephp.org/authentication/3/ja/authenticators.html#authenticator-identifier)
        
    *   [ステートフル認証でステートレス認証を使用する](https://book.cakephp.org/authentication/3/ja/authenticators.html#id5)
        
    *   [認証されていないエラーの処理](https://book.cakephp.org/authentication/3/ja/authenticators.html#id6)
        
*   [Identifiers](https://book.cakephp.org/authentication/3/ja/identifiers.html)
    *   [Password](https://book.cakephp.org/authentication/3/ja/identifiers.html#password)
        
    *   [トークン](https://book.cakephp.org/authentication/3/ja/identifiers.html#id1)
        
    *   [JWT サブジェクト](https://book.cakephp.org/authentication/3/ja/identifiers.html#jwt)
        
    *   [LDAP](https://book.cakephp.org/authentication/3/ja/identifiers.html#ldap)
        
    *   [コールバック](https://book.cakephp.org/authentication/3/ja/identifiers.html#id2)
        
    *   [Identity resolvers](https://book.cakephp.org/authentication/3/ja/identifiers.html#identity-resolvers)
        
*   [Password Hashers](https://book.cakephp.org/authentication/3/ja/password-hashers.html)
    *   [Default](https://book.cakephp.org/authentication/3/ja/password-hashers.html#default)
        
    *   [レガシー](https://book.cakephp.org/authentication/3/ja/password-hashers.html#id1)
        
    *   [フォールバック](https://book.cakephp.org/authentication/3/ja/password-hashers.html#id2)
        
    *   [ハッシュアルゴリズムのアップグレード](https://book.cakephp.org/authentication/3/ja/password-hashers.html#id3)
        
*   [Identity Objects](https://book.cakephp.org/authentication/3/ja/identity-object.html)
    *   [独自のIdentityオブジェクトの作成](https://book.cakephp.org/authentication/3/ja/identity-object.html#identity)
        
    *   [User クラスへの IdentityInterface の実装](https://book.cakephp.org/authentication/3/ja/identity-object.html#user-identityinterface)
        
    *   [カスタムIdentityデコレータを使用する](https://book.cakephp.org/authentication/3/ja/identity-object.html#id1)
        
*   [Middleware](https://book.cakephp.org/authentication/3/ja/middleware.html)
    *   [設定](https://book.cakephp.org/authentication/3/ja/middleware.html#id1)
        
    *   [複数の認証設定の設定](https://book.cakephp.org/authentication/3/ja/middleware.html#id2)
        
*   [認証 Component](https://book.cakephp.org/authentication/3/ja/authentication-component.html)
    *   [ログインしているユーザーへのアクセス](https://book.cakephp.org/authentication/3/ja/authentication-component.html#id1)
        
    *   [ログイン状態を確認する](https://book.cakephp.org/authentication/3/ja/authentication-component.html#id2)
        
    *   [identity のログアウト](https://book.cakephp.org/authentication/3/ja/authentication-component.html#identity)
        
    *   [自動Identityチェックを構成する](https://book.cakephp.org/authentication/3/ja/authentication-component.html#id3)
        
*   [認証コンポーネントから移行](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html)
    *   [違い](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id2)
        
    *   [類似](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id3)
        
    *   [認証装置と認証者](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id4)
        
    *   [認証設定の移行](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id5)
        
    *   [認証されていないリダイレクトの移行](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id9)
        
    *   [ハッシングアップグレードロジックの移行](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id10)
        
*   [認証によるテスト](https://book.cakephp.org/authentication/3/ja/testing.html)
    *   [セッションベースの認証](https://book.cakephp.org/authentication/3/ja/testing.html#id2)
        
    *   [トークンベースの認証](https://book.cakephp.org/authentication/3/ja/testing.html#id3)
        
*   [URL チェッカー](https://book.cakephp.org/authentication/3/ja/url-checkers.html)
    *   [付属のチェッカー](https://book.cakephp.org/authentication/3/ja/url-checkers.html#id1)
        
*   [View Helper](https://book.cakephp.org/authentication/3/ja/view-helper.html)
    

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# JSON と XML ビュー | CakePHP

[Skip to content](https://book.cakephp.org/3.x/ja/views/json-and-xml-views.html#VPContent)

Return to top

JSON と XML ビュー [​](https://book.cakephp.org/3.x/ja/views/json-and-xml-views.html#json-%E3%81%A8-xml-%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC)

==========================================================================================================================================

`JsonView` と `XmlView` を使用することで JSON と XML レスポンスを作成できるようになり、 それらは `Cake\Controller\Component\RequestHandlerComponent` と統合されます。

あなたのアプリケーションで `RequestHandlerComponent` を有効にして、 `json` と `xml` またはいずれかの拡張子のサポートを有効にすることで、 自動的に新しいビュークラスを使用することが出来るようになります。 以降、このページでは `JsonView` と `XmlView` をデータビューと呼びます。

データビューを生成する方法は2つあります。 一つ目は `_serialize` キーを使用する方法、二つ目は通常のテンプレートファイルを使用する方法です。

あなたのアプリケーションでデータビューを有効化する [​](https://book.cakephp.org/3.x/ja/views/json-and-xml-views.html#%E3%81%82%E3%81%AA%E3%81%9F%E3%81%AE%E3%82%A2%E3%83%95%E3%82%9A%E3%83%AA%E3%82%B1%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%81%A6%E3%82%99%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC%E3%82%92%E6%9C%89%E5%8A%B9%E5%8C%96%E3%81%99%E3%82%8B)

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

データビュークラスを使用する前に、 まず `Cake\Controller\Component\RequestHandlerComponent` をコントローラーでロードする必要があります。 :

    public function initialize()
    {
        ...
        $this->loadComponent('RequestHandler');
    }

1  
2  
3  
4  
5  

`AppController` で上記のようにすることで、コンテンツタイプによる自動切り替えが有効化されます。 `viewClassMap` 設定でコンポーネットを設定することで、カスタムクラスをマップしたり 他のデータ型をマップするも出来ます。

任意で [File Extensions](https://book.cakephp.org/3.x/ja/development/routing.html#file-extensions)
 で json と xml 、もしくはどちらかの拡張子を有効化することが出来ます。 `http://example.com/articles.json` の様に、URL の末尾でファイルの拡張子として レスポンスタイプの名前を指定することで、 `JSON` 、 `XML` もしくはそれ以外の特定の フォーマットビューにアクセスすることが出来ます。

デフォルトでは [File Extensions](https://book.cakephp.org/3.x/ja/development/routing.html#file-extensions)
 が無効の場合、リクエストの `Accept` ヘッダーにより、 ユーザーにどのフォーマットをレンダリングするべきかが判断されます。例として、 `JSON` レスポンスを レンダリングするために使用される `Accept` の設定値は `application/json` です。

シリアライズキーをデータビューで使用する [​](https://book.cakephp.org/3.x/ja/views/json-and-xml-views.html#%E3%82%B7%E3%83%AA%E3%82%A2%E3%83%A9%E3%82%A4%E3%82%B9%E3%82%99%E3%82%AD%E3%83%BC%E3%82%92%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC%E3%81%A6%E3%82%99%E4%BD%BF%E7%94%A8%E3%81%99%E3%82%8B)

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

`_serialize` キーは、データビューを使用する時に、どのビュー変数がシリアライズされるべきかを示す 特別なビュー変数です。json/xml に変換する前に独自のフォーマット処理が不要な場合、 これはコントローラーのアクションでテンプレートファイルを定義する手間を省いてくれます。

レスポンスを生成する前にビュー変数へ独自のフォーマット処理や操作が必要な場合は、 テンプレートファイルを使用する必要があります。 `_serialize` の値は、文字列かシリアライズしたいビュー変数の配列のどちらかになります。 :

    namespace App\Controller;
    
    class ArticlesController extends AppController
    {
        public function initialize()
        {
            parent::initialize();
            $this->loadComponent('RequestHandler');
        }
    
        public function index()
        {
            // シリアライズする必要があるビュー変数をセットする
            $this->set('articles', $this->paginate());
            // JsonView がシリアライズするべきビュー変数を指定する
            $this->set('_serialize', 'articles');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

`_serialize` をビュー変数の配列として定義し結合することも出来ます。 :

    namespace App\Controller;
    
    class ArticlesController extends AppController
    {
        public function initialize()
        {
            parent::initialize();
            $this->loadComponent('RequestHandler');
        }
    
        public function index()
        {
            // $articles と $comments を生成する何某かのコード
    
            // シリアライズする必要があるビュー変数をセットする
            $this->set(compact('articles', 'comments'));
    
            // JsonView がシリアライズするべきビュー変数を指定する
            $this->set('_serialize', ['articles', 'comments']);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  

`XmlView` を使用するケースでは、配列として `_serialize` を定義することには最上位に `<response>` 要素が自動的に付与されるという利点があります。 `_serialize` と XmlView に 文字列を使用する時は、ビュー変数が最上位要素を一つ持つことに確認してください。 一つも最上位要素を持たない場合、XML の生成に失敗するでしょう。

テンプレートファイルをデータビューで使用する [​](https://book.cakephp.org/3.x/ja/views/json-and-xml-views.html#%E3%83%86%E3%83%B3%E3%83%95%E3%82%9A%E3%83%AC%E3%83%BC%E3%83%88%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%82%92%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC%E3%81%A6%E3%82%99%E4%BD%BF%E7%94%A8%E3%81%99%E3%82%8B)

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

最終的な出力の前にビュー変数に何かの処理を施したいケースでは、テンプレートファイルを 使用する必要があります。例えば、生成された HTML を要素として持つ記事があり、 JSON レスポンスからそれを取り除きたいとします。こういった状況ではビューファイルが役に立ちます。 :

    // コントローラーのコード
    class ArticlesController extends AppController
    {
        public function index()
        {
            $articles = $this->paginate('Articles');
            $this->set(compact('articles'));
        }
    }
    
    // ビューのコード - src/Template/Articles/json/index.ctp
    foreach ($articles as &$article) {
        unset($article->generated_html);
    }
    echo json_encode(compact('articles'));

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

より複雑な操作を行ったり、ヘルパーを整形に使用することも出来ます。データビュークラスは、 ビューファイルはシリアライズされたコンテンツを出力することを前提としているため、 レイアウトをサポートしません。

NOTE

3.1.0 から 3.5.0 まで、 アプリケーションスケルトンの AppController は、 全ての XML/JSON リクエストに対して、自動的に `'_serialize' => true` を追加していました。 そのためビューファイルを使用したい場合は、このコードを beforeRender コールバックから 取り除くか、 `'_serialize' => false` をセットする必要があります。

XML ビューの作成 [​](https://book.cakephp.org/3.x/ja/views/json-and-xml-views.html#xml-%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC%E3%81%AE%E4%BD%9C%E6%88%90)

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

`class` **XmlView**

デフォルトでは `_serialize` を使用する時、XmlView は `<response>` ノードでシリアル化されるビュー変数をラップします。 `_rootNode` ビュー変数を使用することで、このノードに別の名前を設定することが出来ます。

XmlView クラスは、XML の生成に使用するオプション（例: `tags` vs `attributes` ）を 変更するための `_xmlOptions` 変数をサポートしています。

`XmlView` の使用例は [sitemap.xml](https://www.sitemaps.org/protocol.html)
 を生成することです。 このドキュメントタイプでは `_rootNode` を変更し属性を設定する必要があります。 属性は `@` プレフィックスを使用して定義されます。 :

    public function sitemap()
    {
        $pages = $this->Pages->find();
        $urls = [];
        foreach ($pages as $page) {
            $urls[] = [\
                'loc' => Router::url(['controller' => 'Pages', 'action' => 'view', $page->slug, '_full' => true]),\
                'lastmod' => $page->modified->format('Y-m-d'),\
                'changefreq' => 'daily',\
                'priority' => '0.5'\
            ];
        }
    
        // 生成されたドキュメントにカスタムルートノードを定義します。
        $this->set('_rootNode', 'urlset');
        $this->set([\
            // ルートノードで属性を定義します。\
            '@xmlns' => 'http://www.sitemaps.org/schemas/sitemap/0.9',\
            'url' => $urls\
        ]);
        $this->set('_serialize', ['@xmlns', 'url']);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  

JSON ビューの作成 [​](https://book.cakephp.org/3.x/ja/views/json-and-xml-views.html#json-%E3%83%92%E3%82%99%E3%83%A5%E3%83%BC%E3%81%AE%E4%BD%9C%E6%88%90)

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

`class` **JsonView**

JsonView クラスは、JSON の生成に使用するビットマスクを変更するためための `_jsonOptions` 変数をサポートします。このオプションの有効な値は [json\_encode](https://php.net/json_encode)
 を参照してください。

例えば、一貫した JSON 形式で CakePHP エンティティーの検証エラーをシリアライズするには:

    // コントローラーのアクションの中で、保存に失敗した時
    $this->set('errors', $articles->errors());
    $this->set('_jsonOptions', JSON_FORCE_OBJECT);
    $this->set('_serialize', ['errors']);

1  
2  
3  
4  

### JSONP レスポンス [​](https://book.cakephp.org/3.x/ja/views/json-and-xml-views.html#jsonp-%E3%83%AC%E3%82%B9%E3%83%9B%E3%82%9A%E3%83%B3%E3%82%B9)

`JsonView` を使用する時は、特別なビュー変数 `_jsonp` を使用することで JSONP レスポンスの返すことが出来ます。これに `true` を設定することで、ビュークラスに "callback" という名前のクエリー文字列パラメーターがセットされているかをチェックさせ、 それ同時に提供された関数名で JSON レスポンスをラップさせることが出来ます。 "callback" の代わりにカスタムクエリー文字列パラメーターを使用したい場合は、 `_jsonp` に `true` の代わりの名前を指定してください。

使用例 [​](https://book.cakephp.org/3.x/ja/views/json-and-xml-views.html#%E4%BD%BF%E7%94%A8%E4%BE%8B)

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

リクエストのコンテンツタイプまたは拡張子によって、 [RequestHandlerComponent](https://book.cakephp.org/3.x/ja/controllers/components/request-handling.html)
 が自動的にビューをセットするのに対して、あなたも同様にコントローラーのなかでビューマッピングを 操作することが出来ます。 :

    // src/Controller/VideosController.php
    namespace App\Controller;
    
    use App\Controller\AppController;
    // 3.6 より前は Cake\Network\Exception\NotFoundException を使用
    use Cake\Http\Exception\NotFoundException;
    
    class VideosController extends AppController
    {
        public function export($format = '')
        {
            $format = strtolower($format);
    
            // ビューマッピングの形式
            $formats = [\
              'xml' => 'Xml',\
              'json' => 'Json',\
            ];
    
            // 未知の形式の時はエラー
            if (!isset($formats[$format])) {
                throw new NotFoundException(__('Unknown format.'));
            }
    
            // ビューに出力形式をセット
            $this->viewBuilder()->className($formats[$format]);
    
            // データを取得
            $videos = $this->Videos->find('latest');
    
            // ビューにデータをセット
            $this->set(compact('videos'));
            $this->set('_serialize', ['videos']);
    
            // ダウンロードを指定
            // 3.4.0 より前は
            // $this->response->download('report-' . date('YmdHis') . '.' . $format);
            return $this->response->withDownload('report-' . date('YmdHis') . '.' . $format);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40

---

# Debug Kit - 4.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/debug_kit/edit/4.x/docs/ja/index.rst)

[](https://book.cakephp.org/debugkit/4/ja/#page-contents)

### Page Contents

*   [Debug Kit](https://book.cakephp.org/debugkit/4/ja/#)
    *   [インストール](https://book.cakephp.org/debugkit/4/ja/#id1)
        
    *   [設定](https://book.cakephp.org/debugkit/4/ja/#id2)
        *   [データベース設定](https://book.cakephp.org/debugkit/4/ja/#id3)
            
    *   [ツールバーの使い方](https://book.cakephp.org/debugkit/4/ja/#id4)
        
    *   [履歴パネルを使用する](https://book.cakephp.org/debugkit/4/ja/#id5)
        
    *   [メールパネルを使用](https://book.cakephp.org/debugkit/4/ja/#id6)
        *   [プレビュークラスの作成](https://book.cakephp.org/debugkit/4/ja/#id7)
            
    *   [独自のパネルを開発する](https://book.cakephp.org/debugkit/4/ja/#id8)
        *   [パネルクラスを作成する](https://book.cakephp.org/debugkit/4/ja/#id9)
            
        *   [コールバック](https://book.cakephp.org/debugkit/4/ja/#id10)
            
        *   [パネルの構成要素](https://book.cakephp.org/debugkit/4/ja/#id11)
            
        *   [カスタムのタイトルとエレメント](https://book.cakephp.org/debugkit/4/ja/#id12)
            
        *   [パネルフックメソッド](https://book.cakephp.org/debugkit/4/ja/#id13)
            
        *   [他のプラグインのパネル](https://book.cakephp.org/debugkit/4/ja/#id14)
            
    *   [ヘルパー関数](https://book.cakephp.org/debugkit/4/ja/#id15)
        

Debug Kit[¶](https://book.cakephp.org/debugkit/4/ja/#debug-kit "この見出しへのパーマリンク")

================================================================================

DebugKit は、CakePHP アプリケーション用のデバッグツールバーと拡張デバッグツールを提供します。 アプリケーションの設定データ、ログメッセージ、SQL クエリー、およびタイミングデータをすばやく 確認できます。

警告

DebugKit は、シングルユーザーのローカル開発環境での使用を目的としています。 共有開発環境、ステージング環境、または設定データと環境変数を隠しておく必要がある環境では、 DebugKit を使用しないでください。

インストール[¶](https://book.cakephp.org/debugkit/4/ja/#id1 "この見出しへのパーマリンク")

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

デフォルトで、DebugKit はデフォルトのアプリケーションスケルトンにインストールされています。 もし削除してしまって再インストールしたい場合は、以下のコマンドをアプリケーションの ルートディレクトリー (composer.json ファイルのある場所) で実行してください。

php composer.phar require \--dev cakephp/debug\_kit "~4.0"

そして以下のコマンドでプラグインを有効化する必要があります。

bin/cake plugin load DebugKit

設定[¶](https://book.cakephp.org/debugkit/4/ja/#id2 "この見出しへのパーマリンク")

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

*   `DebugKit.panels` - DebugKit のパネルを有効化または無効化します。 次のようにして、任意の標準パネルを無効にすることができます。
    
    // DebugKit をロードする前に
    Configure::write('DebugKit.panels', \['DebugKit.Packages' \=> false\]);
    
*   `DebugKit.includeSchemaReflection` - スキーマリフレクションクエリーの ロギングを有効にするには、true に設定します。デフォルトは無効になっています。
    
*   `DebugKit.safeTld` - ローカル開発用のトップレベルドメインのホワイトリストを設定します。 これにより安全でないと判断したホスト上で DebugKit を表示できるようになります。
    
    // 例: http://foo.bar.dev または http://my-shop.local のドメインはローカルとして許可する
    Configure::write('DebugKit.safeTld', \['dev', 'local', 'example'\]);
    
*   `DebugKit.forceEnable` - DebugKit を強制的に表示します。これを使うときは注意してください。 通常は単純にローカルのトップレベルドメインをホワイトリストに追加したほうが安全です。 使用例:
    
    // DebugKit をロードする前に
    Configure::write('DebugKit.forceEnable', true);
    

### データベース設定[¶](https://book.cakephp.org/debugkit/4/ja/#id3 "この見出しへのパーマリンク")

デフォルトでは DebugKit はアプリケーションの `/tmp` 内の SQLite データベースに パネルデータを保持します。もし pdo\_sqlite をインストールできない場合は、 **config/app.php** ファイル に `debug_kit` コネクションを定義すると DebugKit が異なるデータベースを使用するように設定できます。例:

/\*\*
 \* debug\_kit コネクションは DebugKit のメタデータを格納します。
 \*/
'debug\_kit' \=> \[\
    'className' \=> 'Cake\\Database\\Connection',\
    'driver' \=> 'Cake\\Database\\Driver\\Mysql',\
    'persistent' \=> false,\
    'host' \=> 'localhost',\
    //'port' => 'nonstandard\_port\_number',\
    'username' \=> 'dbusername',    // Your DB username here\
    'password' \=> 'dbpassword',    // Your DB password here\
    'database' \=> 'debug\_kit',\
    'encoding' \=> 'utf8',\
    'timezone' \=> 'UTC',\
    'cacheMetadata' \=> true,\
    'quoteIdentifiers' \=> false,\
    //'init' => \['SET GLOBAL innodb\_stats\_on\_metadata = 0'\],\
\],

**tmp/debug\_kit.sqlite** ファイルは、いつでも削除することができます。 DebugKit は、必要に応じて、それを再生成します。

ツールバーの使い方[¶](https://book.cakephp.org/debugkit/4/ja/#id4 "この見出しへのパーマリンク")

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

DebugKit ツールバーは、いくつかのパネルで構成されています。これらのパネルは、 DebugKit をインストールしてロードした後、ブラウザーの右下隅にある CakePHP アイコンをクリックすると表示されます。各パネルは、パネルクラスとビューエレメントで構成されています。 一般的に、パネルは単一の種類の情報のコレクションの処理やログやリクエスト情報の表示を行います。 ツールバーからパネルを表示したり、独自のカスタムパネルを追加することを選択できます。

各パネルはアプリケーションの様々な側面を見せてくれます。

*   **Cache** リクエスト中のキャッシュの使用状況の確認とキャッシュのクリアー。
    
*   **Environment** PHP 及び CakePHP に関連する環境変数の表示。
    
*   **History** 以前のリクエストの一覧の表示と、以前のリクエストのツールバーデータの読み込みと表示。
    
*   **Include** タイプごとにグループ化されたインクルードファイルを表示。
    
*   **Log** このリクエスト中にログファイルに加えられたすべてのエントリーを表示。
    
*   **Packages** 現在のバージョンのパッケージの依存関係の一覧を表示し、 古いパッケージをチェックすることができます。
    
*   **Mail** このリクエスト中の全てのメール送信を表示し、 送信せずに開発中のメールのプレビューができます。
    
*   **Request** 現在のリクエスト、GET、POST、Cake パラメーター、現在のルート情報、クッキー情報の表示。
    
*   **Session** 現在のセッション情報の表示。
    
*   **Sql Logs** 各データベースコネクションの SQL ログの表示。
    
*   **Timer** リクエスト中に `DebugKit\DebugTimer` で設定されたすべてのタイマーと、 `DebugKit\DebugMemory` で収集されたメモリー使用状況の表示。
    
*   **Variables** コントローラーでセットされたビュー変数の表示。
    

履歴パネルを使用する[¶](https://book.cakephp.org/debugkit/4/ja/#id5 "この見出しへのパーマリンク")

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

履歴パネルは DebugKit で最も勘違いされやすい機能の一つです。 エラーやリダイレクトを含む以前のリクエストのツールバーのデータを表示することができます。

![Screenshot of the history panel in debug kit.](https://book.cakephp.org/debugkit/4/_static/history-panel.png)

ご覧のようにパネルにはリクエストの一覧が含まれます。左側にドットがついているのがアクティブな リクエストです。どれかのリクエストをクリックするとそのリクエストのデータが読み込まれます。 履歴データがロードされると代替のデータが読み込まれたことを示すようにパネルのタイトルが遷移します。

Video of history panel in action.

メールパネルを使用[¶](https://book.cakephp.org/debugkit/4/ja/#id6 "この見出しへのパーマリンク")

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

メールパネルは、リクエストの間に送信された全てのメールを追跡することができます。

Video of mail panel in action

メーラープレビューは、開発中のメールを簡単にプレビューすることができます。

Video of mail panel in action

### プレビュークラスの作成[¶](https://book.cakephp.org/debugkit/4/ja/#id7 "この見出しへのパーマリンク")

メールを送信する前にプレビューするには、受信者と mailer メソッドに必要なテンプレート変数を 定義するプレビュークラスを作成する必要があります。

// src/Mailer/MailPreview/WelcomePreview.php の中で
namespace App\\Mailer\\Preview;

use DebugKit\\Mailer\\MailPreview;

class WelcomePreview extends MailPreview
{
    public function welcome()
    {
        $mailer \= $this\->getMailer('Welcome');
        // メーラーのテンプレート変数受信者を設定します。

        return $mailer;
    }
}

MailPreview クラスは、 アプリケーションまたはプラグインの `Mailer\Preview` 名前空間に存在し、 `Preview` を使用する必要があります。

独自のパネルを開発する[¶](https://book.cakephp.org/debugkit/4/ja/#id8 "この見出しへのパーマリンク")

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

アプリケーションのデバッグを補助するための DebugKit の独自のカスタムパネルを 作成することができます。

### パネルクラスを作成する[¶](https://book.cakephp.org/debugkit/4/ja/#id9 "この見出しへのパーマリンク")

パネルクラスは単に **src/Panel** ディレクトリーに設置してください。ファイル名はクラス名と 一致する必要があります。 つまり `MyCustomPanel` クラスは **src/Panel/MyCustomPanel.php** というファイル名であることを想定しています。

namespace App\\Panel;

use DebugKit\\DebugPanel;

/\*\*
 \* My Custom Panel
 \*/
class MyCustomPanel extends DebugPanel
{
    ...
}

カスタムパネルは `DebugPanel` クラスを拡張する必要があることに注意してください。

### コールバック[¶](https://book.cakephp.org/debugkit/4/ja/#id10 "この見出しへのパーマリンク")

デフォルトではパネルオブジェクトには、現在のリクエストをフックすることができる 2つのコールバックがあります。パネルは `Controller.initialize` と `Controller.shutdown` のイベントを取得します。もしパネルが追加のイベントを 取得したい場合は、 `implementedEvents()` メソッドを使用し、 パネルが必要とするすべてのイベントを定義できます。

どのようにパネルを構築するかについてのいくつかの例として、ビルトインのパネルを参照してください。

### パネルの構成要素[¶](https://book.cakephp.org/debugkit/4/ja/#id11 "この見出しへのパーマリンク")

各パネルはパネルのコンテンツを描画するためのビューエレメントがあることを想定しています。 エレメント名はアンダースコアー区切りのクラス名である必要があります。 たとえば、 `SessionPanel` は **session\_panel.ctp** という名前のエレメントを持ちます。 また、SqllogPanelは **sqllog\_panel.ctp** という名前のエレメントを持ちます。 これらのエレメントは **src/Template/Element** ディレクトリーのルートに設置する必要があります。

### カスタムのタイトルとエレメント[¶](https://book.cakephp.org/debugkit/4/ja/#id12 "この見出しへのパーマリンク")

パネルは慣例を元にそのタイトルとエレメント名を補足します。もしカスタムのタイトルやエレメント名を 付けたい場合は、パネルの振る舞いをカスタムするメソッドを定義することができます。

*   `title()` - ツールバー上に表示されるタイトルを設定します
    
*   `elementName()` - 与えられたパネルがどのエレメントを使用するかを設定します
    

### パネルフックメソッド[¶](https://book.cakephp.org/debugkit/4/ja/#id13 "この見出しへのパーマリンク")

また、パネルの動作や表示方法をカスタムするために以下のフックメソッドを実装することができます。

*   `shutdown(Event $event)` このメソッドは通常はパネルのデータの収集と準備を行います。
    
*   `summary()` パネルが折りたたまれている時に表示されるサマリーデータの文字列を 返すことができます。多くの場合、これは件数や短いサマリー情報です。
    
*   `data()` エレメントのコンテキストで使用されるパネルのデータを返します。 このフックメソッドは `shutdown()` で収集されるデータを更に操作することができます。 このメソッドはシリアライズ化可能なデータを **必ず** 返す必要があります。
    

### 他のプラグインのパネル[¶](https://book.cakephp.org/debugkit/4/ja/#id14 "この見出しへのパーマリンク")

パネルはひとつの小さな違いを除き、[plugins](https://book.cakephp.org/3.0/ja/plugins.html)
 とほぼ同じ動作を提供します。レンダリング時にパネルのエレメントを配置できるように、 `public $plugin` にプラグインディレクトリーの名前を必ずセットする必要があります。

namespace MyPlugin\\Panel;

use DebugKit\\DebugPanel;

class MyCustomPanel extends DebugPanel
{
    public $plugin \= 'MyPlugin';
        ...
}

プラグインやアプリケーションパネルを使用するには、アプリケーションの DebugKit の設定を 更新します。

// src/Application.php の bootstrap() メソッドの中に追加
Configure::write('DebugKit.panels', \['App', 'MyPlugin.MyCustom'\]);
$this\->addPlugin('DebugKit', \['bootstrap' \=> true\]);

上記は、すべてのデフォルトのパネルと同じように `AppPanel` と `MyPlugin` の `MyCustomPanel` パネルを読みこみます。

ヘルパー関数[¶](https://book.cakephp.org/debugkit/4/ja/#id15 "この見出しへのパーマリンク")

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

*   `sql()` ORM クエリーから SQL をダンプします。
    
*   `sqld()` ORM クエリーから SQL をダンプして終了します。
    

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# Bake の拡張 - 1.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/bake/edit/1.x/docs/ja/development.rst)

[](https://book.cakephp.org/bake/1/ja/development.html#page-contents)

### Page Contents

*   [Bake の拡張](https://book.cakephp.org/bake/1/ja/development.html#)
    *   [Bake イベント](https://book.cakephp.org/bake/1/ja/development.html#id1)
        
    *   [Bake テンプレート構文](https://book.cakephp.org/bake/1/ja/development.html#id2)
        
    *   [Bake テーマの作成](https://book.cakephp.org/bake/1/ja/development.html#creating-a-bake-theme)
        
    *   [Bake テンプレートのカスタマイズ](https://book.cakephp.org/bake/1/ja/development.html#id4)
        
    *   [Bake コマンドオプションの新規作成](https://book.cakephp.org/bake/1/ja/development.html#id5)
        

Bake の拡張[¶](https://book.cakephp.org/bake/1/ja/development.html#bake "このヘッドラインへのパーマリンク")

=========================================================================================

Bake は、アプリケーションやプラグインが基本機能に対して変更または追加を可能にする 拡張可能なアーキテクチャーを備えています。Bake は、 [Twig](https://twig.symfony.com/)
 テンプレートエンジンを使用したビュークラスを利用します。

Bake イベント[¶](https://book.cakephp.org/bake/1/ja/development.html#id1 "このヘッドラインへのパーマリンク")

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

`BakeView` は、ビュークラスとして、他のビュークラスと同様のイベントに加え、 1つの特別な初期化 (initialize) イベントを発します。しかし、一方で標準ビュークラスは、 イベントのプレフィックス "View." を使用しますが、 `BakeView` は、 イベントのプレフィックス "Bake." を使用しています。

初期化イベントは、すべての bake の出力に対して変更を加えるために使用できます。 例えば、bake ビュークラスに他のヘルパーを追加するためにこのイベントは使用されます。

<?php
// config/bootstrap\_cli.php

use Cake\\Event\\Event;
use Cake\\Event\\EventManager;

EventManager::instance()\->on('Bake.initialize', function (Event $event) {
    $view \= $event\->getSubject();

    // bake テンプレートの中で MySpecial ヘルパーの使用を可能にします
    $view\->loadHelper('MySpecial', \['some' \=> 'config'\]);

    // そして、$author 変数を利用可能にするために追加
    $view\->set('author', 'Andy');

});

別のプラグインの中から bake を変更したい場合は、プラグインの `config/bootstrap.php` ファイルでプラグインの Bake イベントを置くことは良いアイデアです。

Bake イベントは、既存のテンプレートに小さな変更を行うための便利なことができます。 例えば、コントローラーやテンプレートファイルを bake する際に使用される変数名を 変更するために、bake テンプレートで使用される変数を変更するために `Bake.beforeRender` で呼び出される関数を使用することができます。

<?php
// config/bootstrap\_cli.php

use Cake\\Event\\Event;
use Cake\\Event\\EventManager;

EventManager::instance()\->on('Bake.beforeRender', function (Event $event) {
    $view \= $event\->getSubject();

    // indexes の中のメインデータ変数に $rows を使用
    if ($view\->get('pluralName')) {
        $view\->set('pluralName', 'rows');
    }
    if ($view\->get('pluralVar')) {
        $view\->set('pluralVar', 'rows');
    }

    // view と edit の中のメインデータ変数に $theOne を使用
    if ($view\->get('singularName')) {
        $view\->set('singularName', 'theOne');
    }
    if ($view\->get('singularVar')) {
        $view\->set('singularVar', 'theOne');
    }

});

特定の生成されたファイルへの `Bake.beforeRender` と `Bake.afterRender` イベントを指定することもあるでしょう。例えば、 **Controller/controller.twig** ファイルから生成する際、 UsersController に特定のアクションを追加したい場合、以下のイベントを使用することができます。

<?php
// config/bootstrap\_cli.php

use Cake\\Event\\Event;
use Cake\\Event\\EventManager;
use Cake\\Utility\\Hash;

EventManager::instance()\->on(
    'Bake.beforeRender.Controller.controller',
    function (Event $event) {
        $view \= $event\->getSubject();
        if ($view\->viewVars\['name'\] \== 'Users') {
            // Users コントローラーに login と logout を追加
            $view\->viewVars\['actions'\] \= \[\
                'login',\
                'logout',\
                'index',\
                'view',\
                'add',\
                'edit',\
                'delete'\
            \];
        }
    }
);

特定の bake テンプレートのためのイベントリスナーを指定することによって、 bake 関連のイベント・ロジックを簡素化し、テストするのが容易であるコールバックを 提供することができます。

Bake テンプレート構文[¶](https://book.cakephp.org/bake/1/ja/development.html#id2 "このヘッドラインへのパーマリンク")

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

Bake テンプレートファイルは、 [Twig](https://twig.symfony.com/doc/2.x/)
 テンプレート構文を使用します。

bake テンプレートがどのように動作するかを確認/理解する一つの方法は、 bake テンプレートファイルを変更しようとする場合は特に、クラスを bake して、 アプリケーションの **tmp/bake** フォルダー内に残っている前処理されたテンプレートファイルを 使ったテンプレートと比較することです。

だから、例えば、以下のようにシェルを bake した場合:

bin/cake bake shell Foo

(**vendor/cakephp/bake/src/Template/Bake/Shell/shell.twig**) を使用した テンプレートは、以下のようになります。

<?php
namespace {{ namespace }}\\Shell;

use Cake\\Console\\Shell;

/\*\*
 \* {{ name }} shell command.
 \*/
class {{ name }}Shell extends Shell
{
    /\*\*
     \* main() method.
     \*
     \* @return bool|int Success or error code.
     \*/
    public function main()
    {
    }

}

そして、 bake で得られたクラス (**src/Shell/FooShell.php**) は、 このようになります。

<?php
namespace App\\Shell;

use Cake\\Console\\Shell;

/\*\*
 \* Foo shell command.
 \*/
class FooShell extends Shell
{
    /\*\*
     \* main() method.
     \*
     \* @return bool|int Success or error code.
     \*/
    public function main()
    {
    }

}

注釈

バージョン 1.5.0 より前の bake は、 .ctp テンプレートファイルでカスタム erb スタイルのタグを 使用していました。

*   `<%` Bake テンプレートの PHP 開始タグ
    
*   `%>` Bake テンプレートの PHP 終了タグ
    
*   `<%=` Bake テンプレートの PHP ショートエコータグ
    
*   `<%-` Bake テンプレートの PHP 開始タグ、タグの前に、先頭の空白を除去
    
*   `-%>` Bake テンプレートの PHP 終了タグ、タグの後に末尾の空白を除去
    

Bake テーマの作成[¶](https://book.cakephp.org/bake/1/ja/development.html#creating-a-bake-theme "このヘッドラインへのパーマリンク")

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

"bake" コマンドによって生成された出力を変更したい場合、bake が使用するテンプレートの 一部または全部を置き換えることができる、独自の bake の「テーマ」を作成することができます。 これを行うための最善の方法は、次のとおりです。

1.  新しいプラグインを bake します。プラグインの名前は bake の「テーマ」名になります。
    
2.  新しいディレクトリー **plugins/\[name\]/src/Template/Bake/Template/** を作成します。
    
3.  **vendor/cakephp/bake/src/Template/Bake/Template** から上書きしたい テンプレートをあなたのプラグインの中の適切なファイルにコピーしてください。
    
4.  bake を実行するときに、必要であれば、 bake のテーマを指定するための `--theme` オプションを使用してください。各呼び出しでこのオプションを指定しなくても済むように、 カスタムテーマをデフォルトテーマとして使用するように設定することもできます。
    
    <?php
    // config/bootstrap.php または config/bootstrap\_cli.php の中で
    Configure::write('Bake.theme', 'MyTheme');
    

Bake テンプレートのカスタマイズ[¶](https://book.cakephp.org/bake/1/ja/development.html#id4 "このヘッドラインへのパーマリンク")

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

"bake" コマンドによって生成されるデフォルトの出力を変更したい場合、アプリケーションで独自の bake テンプレートを作成することができます。この方法では、bake する際、コマンドラインで `--theme` オプションを使用していません。これを行うための最善の方法は、次のとおりです。

1.  新しいディレクトリー **/src/Template/Bake/** を作成します。
    
2.  **vendor/cakephp/bake/src/Template/Bake/** から上書きしたいテンプレートを あなたのアプリケーションの中の適切なファイルにコピーします。
    

Bake コマンドオプションの新規作成[¶](https://book.cakephp.org/bake/1/ja/development.html#id5 "このヘッドラインへのパーマリンク")

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

あなたのアプリケーションやプラグインでタスクを作成することによって、新しい bake コマンドの オプションを追加したり、CakePHP が提供するオプションを上書きすることが可能です。 `Bake\Shell\Task\BakeTask` を継承することで、bake は、あなたの新しいタスクを見つけて bake の一部としてそれを含めます。

例として、任意の foo クラスを作成するタスクを作ります。 まず、 **src/Shell/Task/FooTask.php** タスクファイルを作成します。 私たちのシェルタスクが単純になるように、 `SimpleBakeTask` を継承します。 `SimpleBakeTask` は抽象クラスで、どのタスクが呼ばれるか、どこにファイルを生成するか、 どのテンプレートを使用するかを bake に伝える３つのメソッドを定義することが必要です。 FooTask.php ファイルは次のようになります。

<?php
namespace App\\Shell\\Task;

use Bake\\Shell\\Task\\SimpleBakeTask;

class FooTask extends SimpleBakeTask
{
    public $pathFragment \= 'Foo/';

    public function name()
    {
        return 'foo';
    }

    public function fileName($name)
    {
        return $name . 'Foo.php';
    }

    public function template()
    {
        return 'foo';
    }

}

このファイルが作成されたら、コードを生成する際に bake 使用することができるテンプレートを 作成する必要があります。 **src/Template/Bake/foo.twig** を作成してください。 このファイルに、以下の内容を追加します。

<?php
namespace {{ namespace }}\\Foo;

/\*\*
 \* {{ name }} foo
 \*/
class {{ name }}Foo
{
    // コードを追加。
}

これで、`bin/cake bake` の出力に新しいタスクが表示されるはずです。 `bin/cake bake foo Example` を実行して、新しいタスクを実行することができます。 これは、使用するアプリケーションの **src/Foo/ExampleFoo.php** で 新しい `ExampleFoo` クラスを生成します。

また、 `ExampleFoo` クラスのテストファイルを作成するために `bake` を呼びたい場合は、 カスタムコマンド名のクラスサフィックスと名前空間を登録するために `FooTask` クラスの `bakeTest()` メソッドをオーバーライドする必要があります。

public function bakeTest($className)
{
    if (!isset($this\->Test\->classSuffixes\[$this\->name()\])) {
      $this\->Test\->classSuffixes\[$this\->name()\] \= 'Foo';
    }

    $name \= ucfirst($this\->name());
    if (!isset($this\->Test\->classTypes\[$name\])) {
      $this\->Test\->classTypes\[$name\] \= 'Foo';
    }

    return parent::bakeTest($className);
}

*   **class suffix** は `bake` 呼び出しで与えられた名前に追加します。前の例では、 `ExampleFooTest.php` ファイルを作成します。
    
*   **class type** は、（あなたが bake するアプリやプラグインに関連する） あなたのファイルを導くために使用されるサブ名前空間です。 前の例では、名前空間 `App\Test\TestCase\Foo` でテストを作成します。
    

[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://cakesf.herokuapp.com/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")
[#IRC](https://webchat.freenode.net/?channels=cakephp "IRC")

---

# ポリシーリゾルバー - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/authorization/edit/3.x/docs/ja/policy-resolvers.rst)

[](https://book.cakephp.org/authorization/3/ja/policy-resolvers.html#page-contents)

### Page Contents

*   [ポリシーリゾルバー](https://book.cakephp.org/authorization/3/ja/policy-resolvers.html#)
    *   [MapResolver を使う](https://book.cakephp.org/authorization/3/ja/policy-resolvers.html#mapresolver)
        
    *   [OrmResolverを使う](https://book.cakephp.org/authorization/3/ja/policy-resolvers.html#ormresolver)
        
    *   [ResolverCollectionを使う](https://book.cakephp.org/authorization/3/ja/policy-resolvers.html#resolvercollection)
        
    *   [Resolver を作成する](https://book.cakephp.org/authorization/3/ja/policy-resolvers.html#resolver)
        

ポリシーリゾルバー[¶](https://book.cakephp.org/authorization/3/ja/policy-resolvers.html#id1 "この見出しへのパーマリンク")

====================================================================================================

リソースオブジェクトをそれぞれのポリシークラスにマッピングすることは、ポリシーリゾルバによって処理される動作である。 いくつかのリゾルバを用意していますが、 `AuthorizationPolicyResolverInterface` を実装することで、独自のリゾルバを作成することができます。 内部のリゾルバ:

*   `MapResolver` では、リソース名をそのポリシークラス名、またはオブジェクトやcallableにマッピングすることができます。
    
*   `OrmResolver` は、一般的なORMオブジェクトに対して、規約に基づいたポリシー解決を適用します。
    
*   `ResolverCollection` では、複数のリゾルバを集約して、順番に検索することができます。
    

MapResolver を使う[¶](https://book.cakephp.org/authorization/3/ja/policy-resolvers.html#mapresolver "この見出しへのパーマリンク")

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

`MapResolver` では、リソースクラス名をポリシークラス名、ポリシーオブジェクト、 またはファクトリーコーラブルにマッピングすることができます。:

use Authorization\\Policy\\MapResolver;

$mapResolver \= new MapResolver();

// ポリシークラス名とリソースクラスの対応付け
$mapResolver\->map(Article::class, ArticlePolicy::class);

// policyインスタンスとリソースクラスの対応付け
$mapResolver\->map(Article::class, new ArticlePolicy());

// ファクトリークラスとリソースクラスの対応付け
$mapResolver\->map(Article::class, function ($resource, $mapResolver) {
    // Return a policy object.
});

OrmResolverを使う[¶](https://book.cakephp.org/authorization/3/ja/policy-resolvers.html#ormresolver "この見出しへのパーマリンク")

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

`OrmResolver` は、CakePHP の ORM 用の規約ベースのポリシーリゾルバである。OrmResolver は以下の規約を適用する。:

1.  ポリシーは `App\Policy` に保存されます。
    
2.  ポリシークラスは末尾が `Policy` で終わります。
    

OrmResolverは、以下のオブジェクトタイプのポリシーを解決することができます。:

*   Entities - エンティティクラス名の使用
    
*   Tables - テーブルクラスの使用
    
*   Queries - クエリの `repository()` の戻り値を使用して、クラス名を取得する。
    

すべての場合において、以下のルールが適用されます。:

1.  リソースクラス名は、ポリシークラス名を生成するために使用されます。例えば、 `AppModelEntity Filter` は `AppPolicy Filter` にマップされます。
    
2.  プラグインリソースは、まずアプリケーションポリシーを確認する。 例えば `App\Policy\Bookmarks\BookmarkPolicy` は [\`\`](https://book.cakephp.org/authorization/3/ja/policy-resolvers.html#id2)
    BookmarksModelEntityBookmark\`\`に向けて。
    
3.  アプリケーションオーバーライドポリシーが見つからない場合、プラグインポリシーがチェックされます。例えば `Bookmarks\Policy\BookmarkPolicy`
    

テーブルオブジェクトの場合、クラス名の変換で `AppModelTableTable` が `AppPolicyArticlesTablePolicy` にマッピングされることになります。 クエリーオブジェクトは `repository()` メソッドを呼び出され、その結果得られるテーブルクラスに基づいてポリシーが生成されます。

OrmResolver は、そのコンストラクタでカスタマイズをサポートします。:

use Authorization\\Policy\\OrmResolver;

// カスタムアプリケーションの名前空間を使用する場合の変更。
$appNamespace \= 'App';

// Map policies in one namespace to another.
// Here we have mapped policies for classes in the \`\`Blog\`\` namespace to be
// found in the \`\`Cms\`\` namespace.
$overrides \= \[\
    'Blog' \=> 'Cms',\
\];
$resolver \= new OrmResolver($appNamespace, $overrides)

ResolverCollectionを使う[¶](https://book.cakephp.org/authorization/3/ja/policy-resolvers.html#resolvercollection "この見出しへのパーマリンク")

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

`ResolverCollection` では、複数のリゾルバをまとめることができます。:

use Authorization\\Policy\\ResolverCollection;
use Authorization\\Policy\\MapResolver;
use Authorization\\Policy\\OrmResolver;

$ormResolver \= new OrmResolver();
$mapResolver \= new MapResolver();

// マップリゾルバをチェックし、リソースが明示的にマップされていない場合は、オームリゾルバにフォールバックする。
$resolver \= new ResolverCollection(\[$mapResolver, $ormResolver\]);

Resolver を作成する[¶](https://book.cakephp.org/authorization/3/ja/policy-resolvers.html#resolver "この見出しへのパーマリンク")

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

独自のリゾルバを実装するには、 `AuthorizationPolicyResolverInterface` を実装し、 `getPolicy($resource)` メソッドを定義する必要があります。

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# Policies - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/authorization/edit/3.x/docs/ja/policies.rst)

[](https://book.cakephp.org/authorization/3/ja/policies.html#page-contents)

### Page Contents

*   [Policies](https://book.cakephp.org/authorization/3/ja/policies.html#)
    *   [Policies を作成する](https://book.cakephp.org/authorization/3/ja/policies.html#id1)
        
    *   [ポリシーメソッドの書き方](https://book.cakephp.org/authorization/3/ja/policies.html#id2)
        
    *   [ポリシーのResultオブジェクト](https://book.cakephp.org/authorization/3/ja/policies.html#result)
        *   [ポリシーのスコープ](https://book.cakephp.org/authorization/3/ja/policies.html#id3)
            
        *   [ポリシーの前提条件](https://book.cakephp.org/authorization/3/ja/policies.html#id4)
            

Policies[¶](https://book.cakephp.org/authorization/3/ja/policies.html#policies "この見出しへのパーマリンク")

================================================================================================

Policiesは与えられたオブジェクトの権限を解決するクラスです。 アプリケーション内の任意のクラスに対して、権限の確認を適用するPoliciesを作成することができます。

Policies を作成する[¶](https://book.cakephp.org/authorization/3/ja/policies.html#id1 "この見出しへのパーマリンク")

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

`src/Policy` ディレクトリにPoliciesを作成します。 クラスが用意されていないため、自分で作成する必要があります。 アプリケーションのクラスはポリシークラスによって、'resolved'(解決)されます。 ポリシーの解決については [ポリシーリゾルバー](https://book.cakephp.org/authorization/3/ja/policy-resolvers.html)
 セクションをご覧ください。

ポリシーは **src/Policy** において、クラスの末尾に `Policy` をつけます。 一旦例として、 Article エンティティのためのポリシーを作成します。 **src/Policy/ArticlePolicy.php** に以下を追加します。

<?php
namespace App\\Policy;

use App\\Model\\Entity\\Article;
use Authorization\\IdentityInterface;

class ArticlePolicy
{
}

エンティティだけでなく、テーブルやクエリ自体が解決されることもあります。 Queryオブジェクトの `repository()` メソッドが呼び出され、テーブル名に基づいてポリシークラスが生成されます。 `App\Model\Table\ArticlesTable` なら、 `App\Policy\ArticlesTablePolicy` になります。

ORMオブジェクトのポリシーを作成するには `bake` コマンドを使用します。(便利ですね):

\# Create an entity policy
bin/cake bake policy \--type entity Article

\# Create a table policy
bin/cake bake policy \--type table Articles

ポリシーメソッドの書き方[¶](https://book.cakephp.org/authorization/3/ja/policies.html#id2 "この見出しへのパーマリンク")

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

さっき作成したばかりのポリシークラスはまだ何もしてくれません。 ユーザーが記事を更新できるかのチェックをするメソッドを定義してみましょう。:

public function canUpdate(IdentityInterface $user, Article $article)
{
    return $user\->id \== $article\->user\_id;
}

ポリシーメソッドは `true` か `Result(真偽の結果)` を返す必要があります。 それ以外は失敗と解釈します。

認証していない場合、 `$user` は `null` が代入されます。 匿名ユーザーに対するポリシーメソッドを失敗させたい場合、 `IdentityInterface` のType Hintingを使用することができます。.

ポリシーのResultオブジェクト[¶](https://book.cakephp.org/authorization/3/ja/policies.html#result "この見出しへのパーマリンク")

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

ポリシーメソッドの返り値はBool以外にも `Result` オブジェクトを返すことができます。 `Result` オブジェクトはポリシーの成功・失敗について、より多くの情報を提供することができます。:

use Authorization\\Policy\\Result;

public function canUpdate(IdentityInterface $user, Article $article)
{
    if ($user\->id \== $article\->user\_id) {
        return new Result(true);
    }
    // 失敗の理由を定義できる。
    return new Result(false, 'not-owner');
}

戻り値が `true` か `ResultInterface` 以外は失敗と解釈されます。

### ポリシーのスコープ[¶](https://book.cakephp.org/authorization/3/ja/policies.html#id3 "この見出しへのパーマリンク")

ポリシーは認可の可否だけでなく、「スコープ」を定義することもできます。 スコープメソッドは認可の条件を適用して他のオブジェクトを変更することができます。 リストの取得を現在のユーザーに限定するときに最適です。:

namespace App\\Policy;

class ArticlesTablePolicy
{
    public function scopeIndex($user, $query)
    {
        return $query\->where(\['Articles.user\_id' \=> $user\->getIdentifier()\]);
    }
}

### ポリシーの前提条件[¶](https://book.cakephp.org/authorization/3/ja/policies.html#id4 "この見出しへのパーマリンク")

ポリシーによっては、ポリシー内のすべての操作に共通のチェックを適用したい場合があります。 全てのアクションを拒否する必要があるときに便利です。 前提条件として `BeforePolicyInterface` をポリシーに追加する必要があります。:

namespace App\\Policy;

use Authorization\\IdentityInterface;
use Authorization\\Policy\\BeforePolicyInterface;
use Authorization\\Policy\\ResultInterface;

class ArticlesPolicy implements BeforePolicyInterface
{
    public function before(?IdentityInterface $identity, mixed $resource, string $action): ResultInterface|bool|null
    {
        if ($identity\->getOriginalData()\->is\_admin) {
            return true;
        }
        // fall through
    }
}

3つの値を返却するbeforeが必要です。:

*   `true` 実行を許可します。
    
*   `false` 実行を拒否します。
    
*   `null` 判断できないので、authorizationメソッドが呼び出されます。
    

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# AuthorizationComponent - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/authorization/edit/3.x/docs/ja/component.rst)

[](https://book.cakephp.org/authorization/3/ja/component.html#page-contents)

### Page Contents

*   [AuthorizationComponent](https://book.cakephp.org/authorization/3/ja/component.html#)
    *   [自動認可の確認](https://book.cakephp.org/authorization/3/ja/component.html#id1)
        
    *   [Authorization を確認する](https://book.cakephp.org/authorization/3/ja/component.html#authorization)
        
    *   [匿名のユーザー](https://book.cakephp.org/authorization/3/ja/component.html#id2)
        
    *   [ポリシースコープを適用する](https://book.cakephp.org/authorization/3/ja/component.html#id3)
        

AuthorizationComponent[¶](https://book.cakephp.org/authorization/3/ja/component.html#authorizationcomponent "この見出しへのパーマリンク")

=============================================================================================================================

`AuthorizationComponent` は、コントローラのパーミッションをチェックするための、 いくつかの規約に基づいたヘルパーメソッドを公開しています。 ユーザーの取得や、 `can` や `applyScope` メソッドの呼び出しが抽象化されています。 AuthorizationComponent を使用するには、ミドルウェアを使用する必要があるので、ミドルウェアが適用されていることを確認してください。コンポーネントを使用するには、まず、次のようにコンポーネントをロードします。:

// In your AppController
public function initialize()
{
    parent::initialize();
    $this\->loadComponent('Authorization.Authorization');
}

自動認可の確認[¶](https://book.cakephp.org/authorization/3/ja/component.html#id1 "この見出しへのパーマリンク")

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

`AuthorizationComponent` は、コントローラのデフォルトのモデルクラスと現在のアクション名に基づいて、自動的に認可を適用するように設定することができます。 次の例では、 `index` と `add` のアクションが許可されます。:

$this\->Authorization\->authorizeModel('index', 'add');

また、認証をスキップするアクションを設定することも可能です。 これにより、すべてのユーザーがアクセスできる、**public** なアクションが作成されます。デフォルトでは、すべてのアクションは認証が必要で、認証チェックが有効な場合は `AuthorizationRequiredException` がスローされます。 Authorizationは個々のアクションをスキップできます。:

$this\->loadComponent('Authorization.Authorization', \[\
    'skipAuthorization' \=> \[\
        'login',\
    \]\
\]);

Authorization を確認する[¶](https://book.cakephp.org/authorization/3/ja/component.html#authorization "この見出しへのパーマリンク")

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

コントローラのアクションやコールバックメソッドで、 認証をチェックするにはコンポーネント:

// ArticlesControllerの中
public function edit($id)
{
    $article \= $this\->Articles\->get($id);
    $this\->Authorization\->authorize($article);
    // 残りの編集についての処理
}

上では、現在のユーザーに対して記事が認証されていることがわかります。 チェックするアクションを指定していないので、リクエストの `action` が使われます。 第2パラメータでポリシーアクションを指定することができます。:

// 現在のコントローラアクションに一致しないポリシーメソッドを使用します。
$this\->Authorization\->authorize($article, 'update');

`authorize()` は、拒否されると `Authorization\Exception\ForbiddenException` を投げます。 もし、Bool値を取得したいなら `can()` を使用してください

if ($this\->Authorization\->can($article, 'update')) {
    // 記事に関する処理
}

匿名のユーザー[¶](https://book.cakephp.org/authorization/3/ja/component.html#id2 "この見出しへのパーマリンク")

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

アプリケーション内の一部のリソースは、ログインしていないユーザーもアクセスできる場合があります。 未認証のユーザーがリソースにアクセスできるかどうかは、ポリシーの領域である。 このコンポーネントを通して、匿名ユーザーの認可を確認することができます。 `can()` と `authorize()` の両方が匿名ユーザーをサポートします。ユーザーがログインしていない場合、ポリシーは 'user' パラメータに `null` を期待することができます。

ポリシースコープを適用する[¶](https://book.cakephp.org/authorization/3/ja/component.html#id3 "この見出しへのパーマリンク")

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

また、ポリシースコープを適用するには、コンポーネント:

$query \= $this\->Authorization\->applyScope($this\->Articles\->find());

現在のアクションにログインしているユーザがいない場合、 `MissingIdentityException` が発生します。

アクションを異なる認証方式にマッピングしたい場合は、 `actionMap` オプションを使用します:

// In your controller initialize() method:
$this\->Authorization\->mapActions(\[\
    'index' \=> 'list',\
    'delete' \=> 'remove',\
    'add' \=> 'insert',\
\]);

// or map actions individually.
$this\->Authorization
    \->mapAction('index','list')
    \->mapAction('delete', 'remove')
    \->mapAction('add', 'insert');

例:

   //ArticlesController.php

   public function index()
   {
       $query \= $this\->Articles\->find();

       // これは \`index\` コントローラアクションで呼び出される際に \`list\` スコープを適用します。
       $this\->Authorization\->applyScope($query);
       ...
   }

   public function delete($id)
   {
       $article \= $this\->Articles\->get($id);

       // これは、 \`delete\` コントローラアクションで呼び出される \`remove\` エンティティアクションに対して認可を行うものです。
       $this\->Authorization\->authorize($article);
       ...
   }

   public function add()
   {
       // これは \`add\` コントローラアクションで呼び出される \`insert\` モデルアクションに対して認可を行います。
       $this\->Authorization\->authorizeModel();
       ...
   }

認可をスキップする

* * *

アクションの内部で認証を省略することもできます。:

//ArticlesController.php

public function view($id)
{
    $this\->Authorization\->skipAuthorization();
    ...
}

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# 認可の確認 - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/authorization/edit/3.x/docs/ja/checking-authorization.rst)

[](https://book.cakephp.org/authorization/3/ja/checking-authorization.html#page-contents)

### Page Contents

*   [認可の確認](https://book.cakephp.org/authorization/3/ja/checking-authorization.html#)
    *   [単一リソースの認可チェック](https://book.cakephp.org/authorization/3/ja/checking-authorization.html#id2)
        
    *   [条件適用の範囲](https://book.cakephp.org/authorization/3/ja/checking-authorization.html#id3)
        

認可の確認[¶](https://book.cakephp.org/authorization/3/ja/checking-authorization.html#id1 "この見出しへのパーマリンク")

======================================================================================================

アプリケーションに [認可ミドルウェア](https://book.cakephp.org/authorization/3/ja/middleware.html)
 を適用して、リクエストに `identity` を追加したら、認可のチェックを開始できます。 ミドルウェアは各リクエストの `identity` を `IdentityDecorator` でラップし、認可に関連するメソッドを追加します。

モデル、サービス、テンプレートに `identity` を渡すことで、 アプリケーションの任意の場所で簡単に認可を確認することができます。 デフォルトのデコレーターをカスタマイズしたり置き換えたりする方法については、 [Identity Decorator](https://book.cakephp.org/authorization/3/ja/middleware.html#identity-decorator)
 のセクションを参照してください。

単一リソースの認可チェック[¶](https://book.cakephp.org/authorization/3/ja/checking-authorization.html#id2 "この見出しへのパーマリンク")

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

`can` メソッドを使用すると、1つのリソースの認可を確認することができます。 通常、これはORMエンティティ、またはアプリケーションドメインオブジェクトである。 あなたの [Policies](https://book.cakephp.org/authorization/3/ja/policies.html)
 は認可を決定するためのロジックを提供します。:

// リクエストからIDを取得する
$user \= $this\->request\->getAttribute('identity');

// $article の権限をチェック
if ($user\->can('delete', $article)) {
    // 削除の操作...
}

ポリシーが [ポリシーのResultオブジェクト](https://book.cakephp.org/authorization/3/ja/policies.html#policy-result-objects)
 を返す場合、 `canResult()` が結果インスタンスを返すので、そのステータスを必ずチェックしてください。:

// ポリシーが結果を返すと仮定して
$result \= $user\->canResult('delete', $article);
if ($result\->getStatus()) {
    // 削除する
}

条件適用の範囲[¶](https://book.cakephp.org/authorization/3/ja/checking-authorization.html#id3 "この見出しへのパーマリンク")

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

ページ分割されたクエリのようなオブジェクトのコレクションに権限チェックを適用する必要がある場合、 現在のユーザがアクセスできるレコードのみを取得したいことがよくあるでしょう。 このプラグインは、この概念を 'scope' として実装しています。 スコープ・ポリシーでは、クエリや結果セットを 'scope' し、 更新されたリストやクエリ・オブジェクトを返すことができます:

// リクエストから 'identity' を取得する
$user \= $this\->request\->getAttribute('identity');

// クエリに許可条件を適用し、
// 現在のユーザーがアクセスできるレコードのみを返すようにします。
$query \= $user\->applyScope('index', $query);

[AuthorizationComponent](https://book.cakephp.org/authorization/3/ja/component.html)
 をコントローラのアクションで使用することで、失敗時に例外が発生する認証チェックを効率化することができます。

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# 認証機能 - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/authentication/edit/3.x/docs/ja/authenticators.rst)

[](https://book.cakephp.org/authentication/3/ja/authenticators.html#page-contents)

### Page Contents

*   [認証機能](https://book.cakephp.org/authentication/3/ja/authenticators.html#)
    *   [Session](https://book.cakephp.org/authentication/3/ja/authenticators.html#session)
        
    *   [Form](https://book.cakephp.org/authentication/3/ja/authenticators.html#form)
        
    *   [トークン](https://book.cakephp.org/authentication/3/ja/authenticators.html#id2)
        
    *   [JWT](https://book.cakephp.org/authentication/3/ja/authenticators.html#jwt)
        
    *   [Http基本](https://book.cakephp.org/authentication/3/ja/authenticators.html#http)
        
    *   [Httpダイジェスト](https://book.cakephp.org/authentication/3/ja/authenticators.html#id3)
        
    *   [クッキー認証機能 別名 "Remember Me"](https://book.cakephp.org/authentication/3/ja/authenticators.html#remember-me)
        
    *   [OAuth](https://book.cakephp.org/authentication/3/ja/authenticators.html#oauth)
        
    *   [イベント](https://book.cakephp.org/authentication/3/ja/authenticators.html#id4)
        
    *   [URL チェッカー](https://book.cakephp.org/authentication/3/ja/authenticators.html#url)
        
    *   [成功した Authenticator または Identifier の取得](https://book.cakephp.org/authentication/3/ja/authenticators.html#authenticator-identifier)
        
    *   [ステートフル認証でステートレス認証を使用する](https://book.cakephp.org/authentication/3/ja/authenticators.html#id5)
        
    *   [認証されていないエラーの処理](https://book.cakephp.org/authentication/3/ja/authenticators.html#id6)
        

認証機能[¶](https://book.cakephp.org/authentication/3/ja/authenticators.html#id1 "このヘッドラインへのパーマリンク")

=================================================================================================

Authenticatorは、リクエストを認証操作に変換する処理を行います。 それらは、 [Identifiers](https://book.cakephp.org/authentication/3/ja/identifiers.html)
 を利用して、既知の [Identity Objects](https://book.cakephp.org/authentication/3/ja/identity-object.html)
 を見つけます。

Session[¶](https://book.cakephp.org/authentication/3/ja/authenticators.html#session "このヘッドラインへのパーマリンク")

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

この認証機能は、セッションにユーザー情報や資格情報が含まれているかどうかをチェックします。 以下に挙げた `Form` のようなステートフルな認証機能を使う場合、 ユーザーが一度ログインしたら、それ以降でセッションからデータを取得されるように、 最初に `Session` の認証機能をロードするようにしてください。 設定オプション:

*   **sessionKey**: ユーザーのセッションキー, デフォルトは `Auth`
    
*   **identify**: bool `true` の値を指定してこのキーを設定すると、 セッションの認証情報を識別子と照合できるようになります。 `true` の場合、設定された [Identifiers](https://book.cakephp.org/authentication/3/ja/identifiers.html)
     はリクエストのたびにセッションに 保存されたデータを使ってユーザを識別するために使われます。デフォルト値は `false`.
    
*   **fields**: `username` フィールドをユーザストレージ内の一意の識別しに写像することができます。 デフォルトは `username` です。 このオプションは `identify` オプションが true に設定されている場合に使用されます.
    

Form[¶](https://book.cakephp.org/authentication/3/ja/authenticators.html#form "このヘッドラインへのパーマリンク")

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

リクエストボディのデータを調べます。通常、フォームの送信が POST / PUT 経由で行われる場合が多いです。

設定オプション:

*   **loginUrl**: ログインURL、文字列またはURLの配列。デフォルトは\`\`null\`\` で、すべてのページがチェックされます。
    
*   **fields**: `username` と `password` を指定したPOSTフィールドに描画する配列です。
    
*   **urlChecker**: URLチェッカーのクラスまたはオブジェクト。デフォルトは `DefaultUrlChecker`。
    
*   **useRegex**: URLのマッチングに正規表現を使うかどうか。 デフォルトは `false`.
    
*   **checkFullUrl**: クエリ文字を含むURLをチェックするかどうか。 ログインフォームが別のサブドメインにある場合に便利です。 デフォルトは、`false`。
    

警告

URLに配列構文を使用した場合、URLはCakePHPルータによって生成されます。 結果は、ルート処理によってはリクエストURIに実際にあるものと **異なる** かもしれない。 大文字小文字を区別するために、これを考慮してください

トークン[¶](https://book.cakephp.org/authentication/3/ja/authenticators.html#id2 "このヘッドラインへのパーマリンク")

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

トークン認証機能は、ヘッダーやリクエストパラメータの中にある リクエストと一緒に来るトークンに基づいてリクエストを認証することができます。

設定オプション:

*   **queryParam**: クエリパラメータの名前. クエリパラメータからトークンを取得したい場合に設定します。
    
*   **header**: ヘッダーの名前. ヘッダーからトークンを取得したい場合に設定します。
    
*   **tokenPrefix**: オプションのトークンプレフィックス。
    

ヘッダやクエリ文字列からトークンを取得する例は次のようになります:

$service\->loadAuthenticator('Authentication.Token', \[\
    'queryParam' \=> 'token',\
    'header' \=> 'Authorization',\
    'tokenPrefix' \=> 'Token'\
\]);

上記の場合、 `Token` の前にトークンとスペースがある限り、 `token` のGETパラメータまたは `Authorization` ヘッダが読み込まれます。

トークンは常に次のように設定された識別子に渡されます:

\[\
    'token' \=> '{token-value}',\
\]

JWT[¶](https://book.cakephp.org/authentication/3/ja/authenticators.html#jwt "このヘッドラインへのパーマリンク")

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

JWT 認証機能は、ヘッダーまたはクエリパラメータから [JWT token](https://jwt.io/)
 を取得し、 ペイロードを直接返すか、識別子に渡して別のデータソースなどと照合して検証します。

*   **header**: トークンを確認するためのヘッダー行です。デフォルトは `Authorization` です。
    
*   **queryParam**: トークンをチェックするクエリパラメータ。デフォルトは `token` です。
    
*   **tokenPrefix**: prefixトークン. デフォルトは `bearer` です。
    
*   **algorithm**: Firebase JWT のハッシュアルゴリズム。デフォルトは `'HS256'` です。
    
*   **returnPayload**: 識別子を経由せずに、トークンのペイロードを直接返すか返さないか。デフォルトは `true` です。
    
*   **secretKey**: デフォルトは `null` ですが、秘密鍵を `Security::salt()` 提供しているCakePHPアプリケーションのコンテキストではない場合は **必須** です。
    

デフォルトでは、 `JwtAuthenticator` は対称鍵アルゴリズム `HS256` を使用し、暗号化鍵として、 `Cake\Utility\Security::salt()` の値を使用します。:

\# 秘密鍵生成
openssl genrsa \-out config/jwt.key 1024
\# 公開鍵生成
openssl rsa \-in config/jwt.key \-outform PEM \-pubout \-out config/jwt.pem

`jwt.key` ファイルは秘密鍵であり、安全に保管する必要があります。 `jwt.pem` ファイルは公開鍵です。 このファイルは、モバイルアプリなどの外部アプリケーションによって作成されたトークンを 検証する必要がある場合に使用する必要があります。

以下の例では、 `JwtSubject` 識別しを用いてトークンの `sub` (subject) に基づいてユーザーを識別し、 トークンの検証に公開鍵を使用するように、 `Authenticator` を設定しています。

`Application` クラスに以下を追加してください:

public function getAuthenticationService(ServerRequestInterface $request): AuthenticationServiceInterface
{
    $service \= new AuthenticationService();
    // ...
    $service\->loadIdentifier('Authentication.JwtSubject');
    $service\->loadAuthenticator('Authentication.Jwt', \[\
        'secretKey' \=> file\_get\_contents(CONFIG . '/jwt.pem'),\
        'algorithm' \=> 'RS256',\
        'returnPayload' \=> false\
    \]);
}

`UsersController` に追加:

public function login()
{
    $result \= $this\->Authentication\->getResult();
    if ($result\->isValid()) {
        $privateKey \= file\_get\_contents(CONFIG . '/jwt.key');
        $user \= $result\->getData();
        $payload \= \[\
            'iss' \=> 'myapp',\
            'sub' \=> $user\->id,\
            'exp' \=> time() + 60,\
        \];
        $json \= \[\
            'token' \=> JWT::encode($payload, $privateKey, 'RS256'),\
        \];
    } else {
        $this\->response \= $this\->response\->withStatus(401);
        $json \= \[\];
    }
    $this\->set(compact('json'));
    $this\->viewBuilder()\->setOption('serialize', 'json');
}

公開鍵ファイルを外部アプリに共有する以外にも、 以下のようにアプリを設定することで、 JWKSのエンドポイントを経由して公開鍵ファイルを配布することができます。:

// config/routes.php
$builder\->setExtensions('json');
$builder\->connect('/.well-known/:controller/\*', \[\
    'action' \=> 'index',\
\], \[\
    'controller' \=> '(jwks)',\
\]); // connect /.well-known/jwks.json to JwksController

// controller/JwksController.php
public function index()
{
    $pubKey \= file\_get\_contents(CONFIG . './jwt.pem');
    $res \= openssl\_pkey\_get\_public($pubKey);
    $detail \= openssl\_pkey\_get\_details($res);
    $key \= \[\
        'kty' \=> 'RSA',\
        'alg' \=> 'RS256',\
        'use' \=> 'sig',\
        'e' \=> JWT::urlsafeB64Encode($detail\['rsa'\]\['e'\]),\
        'n' \=> JWT::urlsafeB64Encode($detail\['rsa'\]\['n'\]),\
    \];
    $keys\['keys'\]\[\] \= $key;

    $this\->viewBuilder()\->setClassName('Json');
    $this\->set(compact('keys'));
    $this\->viewBuilder()\->setOption('serialize', 'keys');
}

JWKSの詳細情報は [https://datatracker.ietf.org/doc/html/rfc7517](https://datatracker.ietf.org/doc/html/rfc7517)
 または [https://auth0.com/docs/tokens/json-web-tokens/json-web-key-sets](https://auth0.com/docs/tokens/json-web-tokens/json-web-key-sets)
 を参照してください。

Http基本[¶](https://book.cakephp.org/authentication/3/ja/authenticators.html#http "このヘッドラインへのパーマリンク")

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

[https://en.wikipedia.org/wiki/Basic\_access\_authentication](https://en.wikipedia.org/wiki/Basic_access_authentication)
 を確認してください。

設定オプション:

*   **realm**: デフォルトは `$_SERVER['SERVER_NAME']` で、必要に応じて上書きしてください。
    

Httpダイジェスト[¶](https://book.cakephp.org/authentication/3/ja/authenticators.html#id3 "このヘッドラインへのパーマリンク")

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

[https://en.wikipedia.org/wiki/Digest\_access\_authentication](https://en.wikipedia.org/wiki/Digest_access_authentication)
 を確認してください。

設定オプション:

*   **realm**: デフォルトは `null` です。
    
*   **qop**: デフォルトは `auth` です。
    
*   **nonce**: デフォルトは `uniqid(''),` です。
    
*   **opaque**: デフォルトは `null` です。
    

クッキー認証機能 別名 "Remember Me"[¶](https://book.cakephp.org/authentication/3/ja/authenticators.html#remember-me "このヘッドラインへのパーマリンク")

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

クッキー認証機能を使用すると、ログインフォームに "remember me" 機能を実装することができます。

ログインフォームに、この認証機能で設定されているフィールド名と一致するフィールドがあることを確認してください。

クッキーを暗号化して複合化するには、AuthenticationMiddlewareの **前に** EncryptedCookieMiddlewareをアプリに追加したことを確認してください。

設定オプション:

*   **rememberMeField**: デフォルトは `remember_me` です。
    
*   **cookie**: クッキーオプションの配列:
    
    *   **name**: クッキー名, デフォルトは `CookieAuth`
        
    *   **expire**: 有効期限, デフォルトは `null` です。
        
    *   **path**: パス, デフォルトは `/` です。
        
    *   **domain**: ドメイン, デフォルトは空の文字列です \`\`
        
    *   **secure**: Bool, デフォルトは `false` です。
        
    *   **httpOnly**: Bool, デフォルトは `false` です。
        
    *   **value**: Value, デフォルトは空の文字列です。 \`\`
        
*   **fields**: `username` と `password` を指定されたIDフィールドにマップする配列
    
*   **urlChecker**: URLチェッカーのクラスまたはオブジェクト。デフォルトは `DefaultUrlChecker`
    
*   **loginUrl**: ログイン URL, 文字列または URL の配列。 デフォルトは `null` で、すべてのページがチェックされます。
    
*   **passwordHasher**: トークンハッシュに使うパスワードハッシャー。デフォルトは `DefaultPasswordHasher::class`.
    

OAuth[¶](https://book.cakephp.org/authentication/3/ja/authenticators.html#oauth "このヘッドラインへのパーマリンク")

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

現在のところ、OAuth認証機能の実装予定はありません。 その主な理由は、OAuth 2.0が認証プロトコルではないからです。

このトピックについて知りたい場合は、 [ここ](https://oauth.net/articles/authentication/)
.

将来的にはOpenID Connect認証機能を追加するかもしれません。

イベント[¶](https://book.cakephp.org/authentication/3/ja/authenticators.html#id4 "このヘッドラインへのパーマリンク")

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

認証によって発生するイベントは1つだけです。: `Authentication.afterIdentify`.

イベントとは何か、イベントの使い方がわからない場合は [ここをクリックしてください！](https://book.cakephp.org/3.0/en/core-libraries/events.html)
.

身元の特定に成功した後に `Authentication.afterIdentify` イベントが `AuthenticationComponent` によって発行されます。

イベントには以下のデータが含まれています。:

*   **provider**: `\Authentication\Authenticator\AuthenticatorInterface` を実装したオブジェクトです。
    
*   **identity**: `\ArrayAccess` を実装したオブジェクトです。
    
*   **service**: `\Authentication\AuthenticationServiceInterface` を実装したオブジェクトです。
    

イベントのサブジェクトは、AuthenticationComponent がアタッチされている 現在のコントローラのインスタンスになります。

しかし、このイベントが発生するのは、IDを識別するために使用された authenticator が永続的ではなく、ステートレスではない場合に限られます。 これは、例えばセッション認証やトークンがリクエストのたびに毎回イベントを発生させてしまうからです。

含まれている認証子からは、FormAuthenticatorのみがイベントを発生させます。 その後、セッション認証機能がIDを提供します。

URL チェッカー[¶](https://book.cakephp.org/authentication/3/ja/authenticators.html#url "このヘッドラインへのパーマリンク")

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

`Form` や `Cookie` のような認証証は、 `/login` ページのような 特定のページでのみ実行されるべきものがあります。 これは、URLチェッカーを使用することで実現できます。

デフォルトは `DefaultUrlChecker` を使います。 これは、正規表現チェックをサポートした文字列URLを比較に使用します。

設定オプション:

*   **useRegex**: URLのマッチングに正規表現を使用するかどうか。デフォルトは `false` です。
    
*   **checkFullUrl**: フルURLをチェックするかどうか。 ログインフォームが別のサブドメインにある場合に便利です。 デフォルトは `false` です。
    

フレームワーク固有の URL のサポートが必要な場合など、カスタム URL チェッカーを実装することができます。 この場合は `Authentication\UrlChecker\UrlCheckerInterface` を実装してください。

もっと詳しくURLチェッカーについて知るには [このページを見てください](https://book.cakephp.org/authentication/3/ja/url-checkers.html)
.

成功した Authenticator または Identifier の取得[¶](https://book.cakephp.org/authentication/3/ja/authenticators.html#authenticator-identifier "このヘッドラインへのパーマリンク")

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

ユーザーの認証が完了した後、ユーザーの認証に成功した Authenticator を確認したり、 次のような操作を行うことができます。:

// コントローラー、アクションの中
$service \= $this\->request\->getAttribute('authentication');

// 認証に失敗した場合、または認証機能がある場合は null になります。
$authenticator \= $service\->getAuthenticationProvider();

ユーザーを特定した識別子も取得できます。:

// コントローラー、アクションの中
$service \= $this\->request\->getAttribute('authentication');

//  認証に失敗した場合は null になります。
$identifier \= $service\->getIdentificationProvider();

ステートフル認証でステートレス認証を使用する[¶](https://book.cakephp.org/authentication/3/ja/authenticators.html#id5 "このヘッドラインへのパーマリンク")

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

`Token` や `HttpBasic` を使用している場合は、他の認証しと一緒に `HttpDigest` を使用します。 これらの認証子は、認証証明書が見つからないか無効な場合にリクエストを停止することを覚えておくべきです。 これは、これらの認証子がレスポンスの中で特定のチャレンジヘッダを送信しなければならないために必要です:

use Authentication\\AuthenticationService;

// サービスのインスタンス化
$service \= new AuthenticationService();

// 識別子の読み込み
$service\->loadIdentifier('Authentication.Password', \[\
    'fields' \=> \[\
        'username' \=> 'email',\
        'password' \=> 'password'\
    \]\
\]);
$service\->loadIdentifier('Authentication.Token');

// Basicを最後にして、認証子をロードします。
$service\->loadAuthenticator('Authentication.Session');
$service\->loadAuthenticator('Authentication.Form');
$service\->loadAuthenticator('Authentication.HttpBasic');

もし `HttpBasic` や `HttpDigest` と他の認証子を組み合わせたい場合は、 これらの認証子はリクエストを中止してブラウザのダイアログを強制的に表示するので注意してください。

認証されていないエラーの処理[¶](https://book.cakephp.org/authentication/3/ja/authenticators.html#id6 "このヘッドラインへのパーマリンク")

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

認証されていないユーザがいた場合、 `AuthenticationComponent` は例外を発生させます。 この例外をリダイレクトに変換するには `AuthenticationService` を設定する際に `unauthenticatedRedirect` を使ってください。

また、 `queryParam` オプションを使って現在のリクエストのターゲットURIを クエリパラメータとして渡すこともできます:

// src/Application.phpのgetAuthenticationService() メソッドの中

$service \= new AuthenticationService();

// 認証されていないときにリダイレクトする
$service\->setConfig(\[\
    'unauthenticatedRedirect' \=> '/users/login',\
    'queryParam' \=> 'redirect',\
\]);

そして、コントローラのログインメソッドの中で\`\`getLoginRedirect()\`\` を使うことで、クエリ文字列パラメータ:からリダイレクト先を安全に取得することができます。:

public function login()
{
    $result \= $this\->Authentication\->getResult();

    // Regardless of POST or GET, redirect if user is logged in
    if ($result\->isValid()) {
        // Use the redirect parameter if present.
        $target \= $this\->Authentication\->getLoginRedirect();
        if (!$target) {
            $target \= \['controller' \=> 'Pages', 'action' \=> 'display', 'home'\];
        }
        return $this\->redirect($target);
    }
}

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# リクエスト認証ミドルウェア - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/authorization/edit/3.x/docs/ja/request-authorization-middleware.rst)

[](https://book.cakephp.org/authorization/3/ja/request-authorization-middleware.html#page-contents)

### Page Contents

*   [リクエスト認証ミドルウェア](https://book.cakephp.org/authorization/3/ja/request-authorization-middleware.html#)
    *   [使用方法](https://book.cakephp.org/authorization/3/ja/request-authorization-middleware.html#id2)
        

リクエスト認証ミドルウェア[¶](https://book.cakephp.org/authorization/3/ja/request-authorization-middleware.html#id1 "この見出しへのパーマリンク")

========================================================================================================================

このミドルウェアは、例えば各コントローラーやアクションなどのリクエストを、 ロールベースアクセスシステムや、 特定のアクションへのアクセスを制御する他の種類の認可プロセスに対して認可したい場合に便利です。 Authorization や RoutingMiddleware の **後に** 追加する必要があります

リクエスト認可を処理するロジックは、リクエストポリシーに実装される。 そこですべてのロジックを追加することもできるし、リクエストからの情報をACLやRBACの実装に渡すだけでいい。

使用方法[¶](https://book.cakephp.org/authorization/3/ja/request-authorization-middleware.html#id2 "この見出しへのパーマリンク")

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

リクエストオブジェクトを処理するためのポリシーを作成します。プラグインは実装可能なインターフェイスを同梱しています。 まず、 **src/Policy/RequestPolicy.php** を作成し、以下を追加します。:

namespace App\\Policy;

use Authorization\\Policy\\RequestPolicyInterface;
use Cake\\Http\\ServerRequest;

class RequestPolicy implements RequestPolicyInterface
{
    /\*\*
     \* Method to check if the request can be accessed
     \*
     \* @param \\Authorization\\IdentityInterface|null $identity Identity
     \* @param \\Cake\\Http\\ServerRequest $request Server Request
     \* @return bool
     \*/
    public function canAccess($identity, ServerRequest $request)
    {
        if ($request\->getParam('controller') \=== 'Articles'
            && $request\->getParam('action') \=== 'index'
        ) {
            return true;
        }

        return false;
    }
}

次に、 **src/Application.php** の `Application::getAuthorizationService()` 内で、リクエストクラスをポリシーにマッピングします。:

use App\\Policy\\RequestPolicy;
use Authorization\\AuthorizationService;
use Authorization\\AuthorizationServiceInterface;
use Authorization\\AuthorizationServiceProviderInterface;
use Authorization\\Middleware\\AuthorizationMiddleware;
use Authorization\\Middleware\\RequestAuthorizationMiddleware;
use Authorization\\Policy\\MapResolver;
use Authorization\\Policy\\OrmResolver;
use Psr\\Http\\Message\\ResponseInterface;
use Cake\\Http\\ServerRequest;

public function getAuthorizationService(ServerRequestInterface $request): AuthorizationServiceInterface {
    $mapResolver \= new MapResolver();
    $mapResolver\->map(ServerRequest::class, RequestPolicy::class);
    return new AuthorizationService($mapResolver);
}

RequestAuthorizationMiddlewareの読み込みが、AuthorizationMiddlewareの **後** であることを確認する。:

public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue {
    // other middleware...
    // $middlewareQueue->add(new AuthenticationMiddleware($this));

    // authorizationを加える (authenticationの後にね).
    $middlewareQueue\->add(new AuthorizationMiddleware($this));
    $middlewareQueue\->add(new RequestAuthorizationMiddleware());
}

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# 2.0 Migration Guide - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/authorization/edit/3.x/docs/ja/2-0-migration-guide.rst)

[](https://book.cakephp.org/authorization/3/ja/2-0-migration-guide.html#page-contents)

### Page Contents

*   [2.0 Migration Guide](https://book.cakephp.org/authorization/3/ja/2-0-migration-guide.html#)
    *   [破壊的変更](https://book.cakephp.org/authorization/3/ja/2-0-migration-guide.html#id1)
        

2.0 Migration Guide[¶](https://book.cakephp.org/authorization/3/ja/2-0-migration-guide.html#migration-guide "この見出しへのパーマリンク")

=============================================================================================================================

Authorization 2.0 には新しい機能と、少しの破壊的変更が含まれています。

破壊的変更[¶](https://book.cakephp.org/authorization/3/ja/2-0-migration-guide.html#id1 "この見出しへのパーマリンク")

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

`IdentityInterface` にタイプヒントが追加されました。 もし `IdentityInterface` を実装している場合は、新しい typehints を反映させるためにアプリケーションの実装を更新する必要があります。

タイプヒントを加えて、 `IdentityInterface` に `canResult()` メソッドが追加されました。 このメソッドは常に `ResultInterface` オブジェクトを返し `can()` は常にboolを返します。 1.xバージョンの時は `can()` は `bool` と `ResultInterface` が返却されていました。 このため、 `can()` の戻り値を知ることは非常に困難でした。 新しいメソッドと追加の型付けにより、 `IdentityInterface` はよりシンプルに、より信頼性の高いものとして使用できるようになりました。

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# 認可ミドルウェア - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/authorization/edit/3.x/docs/ja/middleware.rst)

[](https://book.cakephp.org/authorization/3/ja/middleware.html#page-contents)

### Page Contents

*   [認可ミドルウェア](https://book.cakephp.org/authorization/3/ja/middleware.html#)
    *   [Identity Decorator](https://book.cakephp.org/authorization/3/ja/middleware.html#identity-decorator)
        *   [Userクラスを識別子として使用する](https://book.cakephp.org/authorization/3/ja/middleware.html#user)
            
        *   [認可を確実に適用する](https://book.cakephp.org/authorization/3/ja/middleware.html#id3)
            
        *   [不正なリクエストへの対処](https://book.cakephp.org/authorization/3/ja/middleware.html#id4)
            
        *   [不正なリクエストでリダイレクトされた後のフラッシュメッセージの追加](https://book.cakephp.org/authorization/3/ja/middleware.html#id5)
            
        *   [どうやってカスタムUnauthorizedHandlerを作成するか](https://book.cakephp.org/authorization/3/ja/middleware.html#unauthorizedhandler)
            

認可ミドルウェア[¶](https://book.cakephp.org/authorization/3/ja/middleware.html#id1 "この見出しへのパーマリンク")

=============================================================================================

認可はミドルウェアとしてアプリケーションに適用されます。 `AuthorizationMiddleware` は次のような役割があります。:

*   リクエストの '識別要素' を必要に応じて `can`, `canResult`, `applyScope` メソッドで装飾します。
    
*   リクエストの確認/回避を確実にする
    

アプリケーションにミドルウェアを反映させるにはApplicationクラスに `AuthorizationServiceProviderInterface` を追加します。 ミドルウェアをキューに追加するのもお忘れなく。 基本的な例:

namespace App;
use Authorization\\AuthorizationService;
use Authorization\\AuthorizationServiceProviderInterface;
use Authorization\\Middleware\\AuthorizationMiddleware;
use Authorization\\Policy\\OrmResolver;
use Cake\\Http\\BaseApplication;
class Application extends BaseApplication implements AuthorizationServiceProviderInterface
{
    public function getAuthorizationService(ServerRequestInterface $request, ResponseInterface $response)
    {
        $resolver \= new OrmResolver();
        return new AuthorizationService($resolver);
    }
    public function middleware($middlewareQueue)
    {
        // other middleware
        $middlewareQueue\->add(new AuthorizationMiddleware($this));
        return $middlewareQueue;
    }
}

認可Serviceにはポリシーリゾルバが必要です。 詳しくは [Policies](https://book.cakephp.org/authorization/3/ja/policies.html)
 をご覧ください。

Identity Decorator[¶](https://book.cakephp.org/authorization/3/ja/middleware.html#identity-decorator "この見出しへのパーマリンク")

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

デフォルトの `identity` (リクエスト) は `Authorization\IdentityDecorator` でデコレートされます。 デコレータクラスは、メソッド呼び出し、配列アクセス、プロパティアクセスをデコレートされたIDオブジェクトにプロキシします。 アクセスするのに基礎となる `getOriginalData()` を直接使う:

$originalUser \= $user\->getOriginalData();

もしあなたのアプリケーションで、 [cakephp/authentication](https://github.com/cakephp/authentication)
 プラグインが使われていたら、 `Authorization\Identity` クラスを使用しています。 このクラスは `Authorization\IdentityInterface` に `Authentication\IdentityInterface``を加えて実装します。 これにより、 ``Authentication` のコンポーネントとヘルパーを使用して、デコレートされたIDが取得できます。

### Userクラスを識別子として使用する[¶](https://book.cakephp.org/authorization/3/ja/middleware.html#user "この見出しへのパーマリンク")

`User` クラスか識別子クラスがある場合、 `Authorization\IdentityInterface` を実装して、 `identityDecorator` ミドルウェアオプションを使用していた場合、デコレータを省略することができます。 最初に `User` クラスを変更します:

namespace App\\Model\\Entity;
use Authorization\\AuthorizationServiceInterface;
use Authorization\\IdentityInterface;
use Authorization\\Policy\\ResultInterface;
use Cake\\ORM\\Entity;
class User extends Entity implements IdentityInterface
{
    /\*\*
     \* @inheritDoc
     \*/
    public function can(string $action, mixed $resource): bool
    {
        return $this\->authorization\->can($this, $action, $resource);
    }

    /\*\*
     \* @inheritDoc
     \*/
    public function canResult(string $action, mixed $resource): ResultInterface
    {
        return $this\->authorization\->canResult($this, $action, $resource);
    }

    /\*\*
     \* @inheritDoc
     \*/
    public function applyScope(string $action, mixed $resource, mixed ...$optionalArgs): mixed
    {
        return $this\->authorization\->applyScope($this, $action, $resource, ...$optionalArgs);
    }

    /\*\*
     \* @inheritDoc
     \*/
    public function getOriginalData(): \\ArrayAccess|array
    {
        return $this;
    }

    /\*\*
     \* Setter to be used by the middleware.
     \*/
    public function setAuthorization(AuthorizationServiceInterface $service)
    {
        $this\->authorization \= $service;
        return $this;
    }
    // Other methods
}

必要なインターフェースは実装したので、ミドルウェアの設定を更新しましょう:

// Application::middleware() メソッド内で
// Authorization
$middlewareQueue\->add(new AuthorizationMiddleware($this, \[\
    'identityDecorator' \=> function ($auth, $user) {\
        return $user\->setAuthorization($auth);\
    }\
\]));

既存のタイプヒントを変更する必要がなくなり、ユーザーへのアクセスが可能な場所であれば、どこでも認可ポリシーを使い始めることができます。 Authentication(認証)プラグインを使っているなら、両方のインターフェイスを実装します。:

use Authorization\\IdentityInterface as AuthorizationIdentity;
use Authentication\\IdentityInterface as AuthenticationIdentity;
class User extends Entity implements AuthorizationIdentity, AuthenticationIdentity
{
    ...

    /\*\*
     \* Authentication\\IdentityInterface method
     \*
     \* @return string
     \*/
    public function getIdentifier()
    {
        return $this\->id;
    }
    ...
}

### 認可を確実に適用する[¶](https://book.cakephp.org/authorization/3/ja/middleware.html#id3 "この見出しへのパーマリンク")

デフォルトでは、 `AuthorizationMiddleware` は `identity` を含む各リクエストに対して、認可のチェックと回避を行います。 認可が確認できなかった場合 `AuthorizationRequiredException` を投げます。 この例外はミドルウェア/コントローラーが動作した **後に** 発生するため、不正アクセスの防止に使えません。 しかし、開発やテストの時は補助として使うことができます。 この動作は、オプションで無効にすることができます:

$middlewareQueue\->add(new AuthorizationMiddleware($this, \[\
    'requireAuthorizationCheck' \=> false\
\]));

### 不正なリクエストへの対処[¶](https://book.cakephp.org/authorization/3/ja/middleware.html#id4 "この見出しへのパーマリンク")

デフォルトでは、アプリケーションがスローする認証例外は、ミドルウェアによって再スローされます。 不正なリクエストへの対処を設定し、ユーザーをログインページにリダイレクトさせるなど、 カスタムアクションを実行することができます。:

*   `Exception` - このハンドラーは例外を再スローします。これはミドルウェアのデフォルトの動作です。
    
*   `Redirect` - このハンドラーは、指定されたURLにリクエストをリダイレクトします。
    
*   `CakeRedirect` - CakePHPルーターをサポートするハンドラーをリダイレクトします。 両方のリダイレクトハンドラーは同じ構成オプションを共有します:
    
*   `url` - リダイレクトするURL (`CakeRedirect` はCakePHPルーター構文をサポートします。).
    
*   `exceptions` - リダイレクトする必要がある例外クラスのリスト。デフォルトでは `MissingIdentityException` のみがリダイレクトされます。
    
*   `queryParam` - アクセスされたリクエストURLは、リダイレクトURLクエリパラメータにアタッチされます。 (デフォルトは `redirect`)
    
*   `statusCode` - リダイレクトのHTTPステータスコードで、デフォルトは `302` です。
    

例:

use Authorization\\Exception\\MissingIdentityException;

$middlewareQueue\->add(new AuthorizationMiddleware($this, \[\
    'unauthorizedHandler' \=> \[\
        'className' \=> 'Authorization.Redirect',\
        'url' \=> '/pages/unauthorized',\
        'queryParam' \=> 'redirectUrl',\
        'exceptions' \=> \[\
            MissingIdentityException::class,\
            OtherException::class,\
        \],\
    \],\
\]));

すべてのハンドラは、パラメータとして与えられたスローされた例外オブジェクトを取得します。 この例外はいつも `Authorization\Exception\Exception` のインスタンスです。 この例では、 `Authorization.Redirect` ハンドラで、どの例外をリスニングするかを指定するオプションが提供されているだけです。 この例では `Authorization.Redirect` ハンドラを使用していますが、 他の `AuthorizationException` ベースの例外を優雅に処理したい場合は、 `execeptions` 配列に追加することができます。:

'exceptions' \=> \[\
    MissingIdentityException::class,\
    ForbiddenException::class\
\],

[RedirectHandler source](https://github.com/cakephp/authorization/blob/2.next/src/Middleware/UnauthorizedHandler/RedirectHandler.php)
 を見てください。 設定オプションはハンドラの `handle()` メソッドに最後のパラメータとして渡されます。

### 不正なリクエストでリダイレクトされた後のフラッシュメッセージの追加[¶](https://book.cakephp.org/authorization/3/ja/middleware.html#id5 "この見出しへのパーマリンク")

現在、不正なリダイレクトにフラッシュメッセージを追加するストレートな方法はありません。 したがって、フラッシュメッセージ (またはリダイレクト時に発生させたいその他のロジック) を 追加する独自のハンドラを作成する必要があります。

### どうやってカスタムUnauthorizedHandlerを作成するか[¶](https://book.cakephp.org/authorization/3/ja/middleware.html#unauthorizedhandler "この見出しへのパーマリンク")

1.  `src/Middleware/UnauthorizedHandler/CustomRedirectHandler.php` ファイルを作成:
    
    <?php
    declare( strict\_types \= 1 );
    namespace App\\Middleware\\UnauthorizedHandler;
    use Authorization\\Exception\\Exception;
    use Authorization\\Middleware\\UnauthorizedHandler\\RedirectHandler;
    use Psr\\Http\\Message\\ResponseInterface;
    use Psr\\Http\\Message\\ServerRequestInterface;
    class CustomRedirectHandler extends RedirectHandler {
        public function handle( Exception $exception, ServerRequestInterface $request, array $options \= \[\] ): ResponseInterface {
            $response \= parent::handle( $exception, $request, $options );
            $request\->getFlash()\->error( 'You are not authorized to access that location' );
            return $response;
        }
    }
    
2.  AuthorizationMiddlewareに、新しいカスタムハンドラを使用するように指示します。:
    
    // src/Application.php内で
    
    use AuthorizationExceptionMissingIdentityException; use AuthorizationExceptionForbiddenException;
    
    $middlewareQueue->add(new AuthorizationMiddleware($this, \[\
    \
    'unauthorizedHandler' => \[\
    \
    'className' => 'CustomRedirect', // <--- see here 'url' => '/users/login', 'queryParam' => 'redirectUrl', 'exceptions' => \[\
    \
    > MissingIdentityException::class, ForbiddenException::class\
    \
    \], 'custom\_param' => true,\
    \
    \],\
    \
    \]));
    

クラス名として `Authorization.Redirect` を使用した場合と同じ設定パラメータがあることがおわかりいただけると思います。 これは、プラグインに存在する RedirectHandler をベースに私たちのハンドラを拡張しているからです。したがって、すべての機能は `handle()` 関数内に存在し、私たち自身の機能は `handle()` 内に存在します。

カスタムパラメータを追加したい場合は、 `CustomRedirectHandler` 内の `handle()` 関数で指定した `$options` 配列に `custom_param` が含まれます。 こちらもご覧ください [CakeRedirectHandler](https://github.com/cakephp/authorization/blob/2.next/src/Middleware/UnauthorizedHandler/CakeRedirectHandler.php)
 or [RedirectHandler](https://github.com/cakephp/authorization/blob/2.next/src/Middleware/UnauthorizedHandler/RedirectHandler.php)

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# Identifiers - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/authentication/edit/3.x/docs/ja/identifiers.rst)

[](https://book.cakephp.org/authentication/3/ja/identifiers.html#page-contents)

### Page Contents

*   [Identifiers](https://book.cakephp.org/authentication/3/ja/identifiers.html#)
    *   [Password](https://book.cakephp.org/authentication/3/ja/identifiers.html#password)
        
    *   [トークン](https://book.cakephp.org/authentication/3/ja/identifiers.html#id1)
        
    *   [JWT サブジェクト](https://book.cakephp.org/authentication/3/ja/identifiers.html#jwt)
        
    *   [LDAP](https://book.cakephp.org/authentication/3/ja/identifiers.html#ldap)
        
    *   [コールバック](https://book.cakephp.org/authentication/3/ja/identifiers.html#id2)
        
    *   [Identity resolvers](https://book.cakephp.org/authentication/3/ja/identifiers.html#identity-resolvers)
        *   [ORM Resolver](https://book.cakephp.org/authentication/3/ja/identifiers.html#orm-resolver)
            
        *   [独自のリゾルバを書く](https://book.cakephp.org/authentication/3/ja/identifiers.html#id3)
            

Identifiers[¶](https://book.cakephp.org/authentication/3/ja/identifiers.html#identifiers "このヘッドラインへのパーマリンク")

=============================================================================================================

Identifiersは認証者がリクエストから抽出した情報に基づいてユーザやサービスを識別します。 Identifiersは `loadIdentifier` メソッドでオプション指定することができます。 パスワード識別子を使用した全体的な例は次のようになります。:

$service\->loadIdentifier('Authentication.Password', \[\
    'fields' \=> \[\
        'username' \=> 'email',\
        'password' \=> 'passwd',\
    \],\
    'resolver' \=> \[\
        'className' \=> 'Authentication.Orm',\
        'finder' \=> 'active'\
    \],\
    'passwordHasher' \=> \[\
        'className' \=> 'Authentication.Fallback',\
        'hashers' \=> \[\
            'Authentication.Default',\
            \[\
                'className' \=> 'Authentication.Legacy',\
                'hashType' \=> 'md5'\
            \],\
        \]\
    \]\
\]);

Password[¶](https://book.cakephp.org/authentication/3/ja/identifiers.html#password "このヘッドラインへのパーマリンク")

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

パスワード識別子は、渡された資格情報をデータソースに対してチェックします。

設定オプション:

*   **fields**: 調べるためのフィールドです。デフォルトは `['username' => 'username', 'password' => 'password']`。 `ユーザー名` を配列にすることができます。 例えば、 `['username' => ['username', 'email'], 'password' => 'password']` を使うと、 ユーザ名とemailのどちらかのカラムの値をマッチさせることができます。
    
*   **resolver**: 同一性を決意します. デフォルトは `Authentication.Orm` で、CakePHPのORMを使用しています。
    
*   **passwordHasher**: パスワードハッシャー. デフォルトは、 `DefaultPasswordHasher::class` 。
    

トークン[¶](https://book.cakephp.org/authentication/3/ja/identifiers.html#id1 "このヘッドラインへのパーマリンク")

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

渡されたトークンをデータソースと照合します。

設定オプション:

*   **tokenField**: データベース内のフィールドをチェックします。 デフォルトは `token` です。
    
*   **dataField**: 認証器から渡されたデータの中のフィールド。デフォルトは `token` です。
    
*   **resolver**: 同一性を決意します。デフォルトは `Authentication.Orm` で、CakePHPのORMを使用しています。
    

JWT サブジェクト[¶](https://book.cakephp.org/authentication/3/ja/identifiers.html#jwt "このヘッドラインへのパーマリンク")

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

渡された JWT トークンをデータソースと照合します。

*   **tokenField**: データベース内のフィールドをチェックします。デフォルトは `id` です。
    
*   **dataField**: ユーザ識別子を取得するためのペイロードキー。デフォルトは、 `sub` です。
    
*   **resolver**: 同一性を決意します。デフォルトは `Authentication.Orm` で、CakePHPのORMを使用しています。
    

LDAP[¶](https://book.cakephp.org/authentication/3/ja/identifiers.html#ldap "このヘッドラインへのパーマリンク")

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

LDAP サーバーに対して渡された資格情報をチェックします。 この識別子には PHP LDAP 拡張モジュールが必要です。

*   **fields**: 調べるためのフィールドです。 デフォルトは `['username' => 'username', 'password' => 'password']` です。
    
*   **host**: LDAPサーバーのFQDN。
    
*   **port**: LDAPサバーのポート。デフォルトは `389` 。
    
*   **bindDN**: 認証するユーザーの識別名。呼び出し可能である必要があります。匿名バインドはサポートされていません。
    
*   **ldap**: 延長アダプターです。 デフォルトは `\Authentication\Identifier\Ldap\ExtensionAdapter`。 もしそれが `AdapterInterface` を実装しているならば、そのobject/classnameをここに渡すことができます。
    
*   **options**: 付加的な LDAP オプション, like `LDAP_OPT_PROTOCOL_VERSION` または `LDAP_OPT_NETWORK_TIMEOUT` のようなものです。 [php.net](https://php.net/manual/en/function.ldap-set-option.php)
     をみてより多くのオプションを参照してください。
    

コールバック[¶](https://book.cakephp.org/authentication/3/ja/identifiers.html#id2 "このヘッドラインへのパーマリンク")

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

識別のためにコールバックを使用できるようにします。 シンプルな識別子やクイックプロトタイピングに便利です。

設定オプション:

*   **callback**: デフォルトは `null` で例外が発生します。 認証機能を使用するには、このオプションに有効なコールバックを渡す必要があります。
    

コールバックの識別子は、単純な結果を得るために `null|ArrayAccess` を返すこともできます。, または、エラーメッセージを転送したい場合、 `Authentication\Authenticator\Result` を使用します。:

// シンプルなコールバック識別子
$authenticationService\->loadIdentifier('Authentication.Callback', \[\
    'callback' \=> function($data) {\
        // 識別子のロジック\
\
        // 識別されたユーザの配列を返すか、失敗した場合はnullを返します。\
        if ($result) {\
            return $result;\
        }\
\
        return null;\
    }\
\]);

// エラーメッセージを返すために結果オブジェクトを使用します。
$authenticationService\->loadIdentifier('Authentication.Callback', \[\
    'callback' \=> function($data) {\
        // 識別子のロジック\
\
        if ($result) {\
            return new Result($result, Result::SUCCESS);\
        }\
\
        return new Result(\
            null,\
            Result::FAILURE\_OTHER,\
            \['message' \=> 'Removed user.'\]\
        );\
    }\
\]);

Identity resolvers[¶](https://book.cakephp.org/authentication/3/ja/identifiers.html#identity-resolvers "このヘッドラインへのパーマリンク")

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

Identity resolvers は、異なるデータソース用のアダプタを提供する。 これにより、どのソースのアイデンティティを検索するかを制御することができます。 これらは識別子とは別個のものであり、 識別子の方法(form, jwt, basic auth)とは独立してスワップアウトできるようになっています。

### ORM Resolver[¶](https://book.cakephp.org/authentication/3/ja/identifiers.html#orm-resolver "このヘッドラインへのパーマリンク")

CakePHP ORM の Identity resolvers。

設定オプション:

*   **userModel**: ユーザーモデルのアイデンティティが配置されています。 デフォルトは `Users` 。
    
*   **finder**: モデルと一緒に使うファインダー. デフォルトは `all` 。
    

ORM resolverを使用するには `composer.json` ファイルの中に `cakephp/orm` が必要です。

### 独自のリゾルバを書く[¶](https://book.cakephp.org/authentication/3/ja/identifiers.html#id3 "このヘッドラインへのパーマリンク")

どんなORMやデータソースでも、リゾルバを作成することで認証に対応できるようにすることができます。 リゾルバは、`App\Identifier\Resolver` の名前空間の下に、 `Authentication\Identifier\Resolver\ResolverInterface` を実装しなければなりません。

リゾルバの設定は\`\`resolver\`\` のconfigオプションを使って行えます。:

$service\->loadIdentifier('Authentication.Password', \[\
    'resolver' \=> \[\
         // name: \\Some\\Other\\Custom\\Resolver::class フルのクラス名です。\
        'className' \=> 'MyResolver',\
        // リゾルバのコンストラクタに追加のオプションを渡します。\
        'option' \=> 'value'\
    \]\
\]);

またはセッターを使用して注入してください。:

$resolver \= new \\App\\Identifier\\Resolver\\CustomResolver();
$identifier \= $service\->loadIdentifier('Authentication.Password');
$identifier\->setResolver($resolver);

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# Identity Objects - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/authentication/edit/3.x/docs/ja/identity-object.rst)

[](https://book.cakephp.org/authentication/3/ja/identity-object.html#page-contents)

### Page Contents

*   [Identity Objects](https://book.cakephp.org/authentication/3/ja/identity-object.html#)
    *   [独自のIdentityオブジェクトの作成](https://book.cakephp.org/authentication/3/ja/identity-object.html#identity)
        
    *   [User クラスへの IdentityInterface の実装](https://book.cakephp.org/authentication/3/ja/identity-object.html#user-identityinterface)
        
    *   [カスタムIdentityデコレータを使用する](https://book.cakephp.org/authentication/3/ja/identity-object.html#id1)
        

Identity Objects[¶](https://book.cakephp.org/authentication/3/ja/identity-object.html#identity-objects "このヘッドラインへのパーマリンク")

===========================================================================================================================

Identity オブジェクトは、認証サービスによって返され、リクエストで利用可能になる。 Identitiesは現在のログインIDのプライマリIDの値を取得するためのメソッド `getIdentifier()` を提供しています。

このオブジェクトが存在する理由は、それを実装/ソースにするインターフェースを提供するためです:

// Service
$authenticationService
    \->getIdentity()
    \->getIdentifier()

// Component
$this\->Authentication
    \->getIdentity()
    \->getIdentifier();

// Request
$this\->request
    \->getAttribute('identity')
    \->getIdentifier();

identityオブジェクトはArrayAccessを提供していますが、 データにアクセスするための `get()` メソッドも提供しています。 getメソッドはフィールドマッピングを認識しているので、 配列へのアクセスよりも `get()` メソッドを使うことを強く推奨します。:

$identity\->get('email');
$identity\->get('username');

また、 `get` メソッドはIDEのメタファイルを介してタイプヒントを与えることもできます。 例えば、 [IdeHelper](https://github.com/dereuromark/cakephp-ide-helper)
 。

もしあなたが望むならば、プロパティアクセスを使用することができます。:

$identity\->email;
$identity\->username;

デフォルトの Identity オブジェクトクラスは、フィールドをマップするように構成できます。 これは、ID の識別子が型にはまらない `id` フィールドである場合や、 他のフィールドをより一般的で一般的な名前にマップしたい場合に非常に便利です。:

$identity \= new Identity($data, \[\
    'fieldMap' \=> \[\
        'id' \=> 'uid',\
        'username' \=> 'first\_name'\
    \]\
\]);

独自のIdentityオブジェクトの作成[¶](https://book.cakephp.org/authentication/3/ja/identity-object.html#identity "このヘッドラインへのパーマリンク")

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

デフォルトでは、Authentication プラグインは メソッドとプロパティアクセスをプロキシする `IdentityDecorator` で返されたユーザーデータをラップします。 自分の ID オブジェクトを作りたい場合は `IdentityInterface` を実装しなければなりません。

User クラスへの IdentityInterface の実装[¶](https://book.cakephp.org/authentication/3/ja/identity-object.html#user-identityinterface "このヘッドラインへのパーマリンク")

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

このプラグインで既存のUserクラスを使い続けたい場合は、 `Authentication\IdentityInterface` を実装してください:

namespace App\\Model\\Entity;

use Authentication\\IdentityInterface;
use Cake\\ORM\\Entity;

class User extends Entity implements IdentityInterface
{
    /\*\*
     \* Authentication\\IdentityInterface method
     \*/
    public function getIdentifier()
    {
        return $this\->id;
    }

    /\*\*
     \* Authentication\\IdentityInterface method
     \*/
    public function getOriginalData()
    {
        return $this;
    }

    // Other methods
}

カスタムIdentityデコレータを使用する[¶](https://book.cakephp.org/authentication/3/ja/identity-object.html#id1 "このヘッドラインへのパーマリンク")

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

もしあなたの識別子が `IdentityInterface` を実装したオブジェクトに変更を加えることができない場合は、 必要なインターフェイスを実装したカスタムデコレータを実装することができます。:

// 呼び出し可能な...
$identityResolver \= function ($data) {
    return new MyCustomIdentity($data);
};

//...またはクラス名を指定して ID ラッパーを設定することができます。
$identityResolver \= MyCustomIdentity::class;

// そしてそれをサービスの設定に渡します。
$service \= new AuthenticationService(\[\
    'identityClass' \=> $identityResolver,\
    'identifiers' \=> \[\
        'Authentication.Password'\
    \],\
    'authenticators' \=> \[\
        'Authentication.Form'\
    \]\
\]);

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# 認証 Component - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/authentication/edit/3.x/docs/ja/authentication-component.rst)

[](https://book.cakephp.org/authentication/3/ja/authentication-component.html#page-contents)

### Page Contents

*   [認証 Component](https://book.cakephp.org/authentication/3/ja/authentication-component.html#)
    *   [ログインしているユーザーへのアクセス](https://book.cakephp.org/authentication/3/ja/authentication-component.html#id1)
        
    *   [ログイン状態を確認する](https://book.cakephp.org/authentication/3/ja/authentication-component.html#id2)
        
    *   [identity のログアウト](https://book.cakephp.org/authentication/3/ja/authentication-component.html#identity)
        
    *   [自動Identityチェックを構成する](https://book.cakephp.org/authentication/3/ja/authentication-component.html#id3)
        

認証 Component[¶](https://book.cakephp.org/authentication/3/ja/authentication-component.html#component "このヘッドラインへのパーマリンク")

=========================================================================================================================

認証結果にアクセスするために `AuthenticationComponent` にアクセスすることができます。 ユーザーの身元とログアウトユーザーを取得できます。 他のコンポーネントと同じように `AppController::initialize()` でコンポーネントをロードします

$this\->loadComponent('Authentication.Authentication', \[\
    'logoutRedirect' \=> '/users/login'  // デフォルトはfalse\
\]);

一旦ロードされると、全てのアクションが認証済みユーザーでしか入れなくなります。 しかし、他のアクセス制御チェックは行わないでください。 このチェックを無効にするには `allowUnauthenticated()` を使います:

// beforeFilter メソッドの中に記述してください。
$this\->Authentication\->allowUnauthenticated(\['view'\]);

ログインしているユーザーへのアクセス[¶](https://book.cakephp.org/authentication/3/ja/authentication-component.html#id1 "このヘッドラインへのパーマリンク")

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

認証されたユーザーデータを取得するには認証コンポーネントのこちらを使用します

$user \= $this\->Authentication\->getIdentity();

リクエストインスタンスから直接ユーザーデータ を取得することもできます。:

$user \= $request\->getAttribute('identity');

ログイン状態を確認する[¶](https://book.cakephp.org/authentication/3/ja/authentication-component.html#id2 "このヘッドラインへのパーマリンク")

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

認証処理が成功したかどうかは、結果オブジェクトにアクセスすることで確認できます。:

// 認証コンポーネントを使います。
$result \= $this\->Authentication\->getResult();

// リクエストオブジェクトを使います。
$result \= $request\->getAttribute('authentication')\->getResult();

if ($result\->isValid()) {
    $user \= $request\->getAttribute('identity');
} else {
    $this\->log($result\->getStatus());
    $this\->log($result\->getErrors());
}

結果セットは `getStatus()` から返されたオブジェクトの状態が、結果オブジェクトの中のこれらの定数のいずれかと一致します。:

*   `ResultInterface::SUCCESS`, うまくいった場合。
    
*   `ResultInterface::FAILURE_IDENTITY_NOT_FOUND`, 身元が不明の場合。
    
*   `ResultInterface::FAILURE_CREDENTIALS_INVALID`, クレデンシャルが無効な場合。
    
*   `ResultInterface::FAILURE_CREDENTIALS_MISSING`, クレデンシャルがリクエストに含まれていない場合。
    
*   `ResultInterface::FAILURE_OTHER`, その他の種類の障害が発生した場合。
    

`getErrors()` が返すエラー配列には、 認証を試みた特定のシステムから得られる **追加の** 情報が含まれています。 例えば、LDAPやOAuthなどは、その実装に特有のエラーをここに書き込むことで、 原因のロギングやデバッグを容易にすることができます。 しかし、同梱されている認証子のほとんどはここには何も入れていません。

identity のログアウト[¶](https://book.cakephp.org/authentication/3/ja/authentication-component.html#identity "このヘッドラインへのパーマリンク")

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

ログアウトするには:

$this\->Authentication\->logout();

もし、 `logoutRedirect` を設定しているならば、 `Authentication::logout()` はその値を返します。 それ以外の場合は、 `false` を返します。 どちらの場合も実際のリダイレクトは行われません。

あるいは、 コンポーネントの代わりに、サービスを使ってログアウトすることもできます

$return \= $request\->getAttribute('authentication')\->clearIdentity($request, $response);

返される結果には、次のような配列が含まれます。:

\[\
    'response' \=> object(Cake\\Http\\Response) { ... },\
    'request' \=> object(Cake\\Http\\ServerRequest) { ... },\
\]

注釈

これはリクエストオブジェクトとレスポンスオブジェクトを含む配列を返します。 両方とも不変なので、新しいオブジェクトを取り戻すことができます。 変更されたレスポンスやリクエストオブジェクトを使い続けたい場合は、 作業しているコンテキストに応じて、今後はこれらのインスタンスを使用しなければならないでしょう。

自動Identityチェックを構成する[¶](https://book.cakephp.org/authentication/3/ja/authentication-component.html#id3 "このヘッドラインへのパーマリンク")

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

デフォルトでは `認証コンポーネント` は、 `Controller.startup` イベントの間に存在するIDを自動的に強制します。 このチェックは `Controller.initialize` イベント中に適用することもできます:

// コントローラの initialize() メソッドの中です。
$this\->loadComponent('Authentication.Authentication', \[\
    'identityCheckEvent' \=> 'Controller.initialize',\
\]);

また、 `requireIdentity` オプションを使って ID チェックを完全に無効にすることもできます。

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# Password Hashers - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/authentication/edit/3.x/docs/ja/password-hashers.rst)

[](https://book.cakephp.org/authentication/3/ja/password-hashers.html#page-contents)

### Page Contents

*   [Password Hashers](https://book.cakephp.org/authentication/3/ja/password-hashers.html#)
    *   [Default](https://book.cakephp.org/authentication/3/ja/password-hashers.html#default)
        
    *   [レガシー](https://book.cakephp.org/authentication/3/ja/password-hashers.html#id1)
        
    *   [フォールバック](https://book.cakephp.org/authentication/3/ja/password-hashers.html#id2)
        
    *   [ハッシュアルゴリズムのアップグレード](https://book.cakephp.org/authentication/3/ja/password-hashers.html#id3)
        

Password Hashers[¶](https://book.cakephp.org/authentication/3/ja/password-hashers.html#password-hashers "このヘッドラインへのパーマリンク")

============================================================================================================================

Default[¶](https://book.cakephp.org/authentication/3/ja/password-hashers.html#default "このヘッドラインへのパーマリンク")

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

暗号化方法にPHPの定数 `PASSWORD_DEFAULT` を使用しています。 デフォルトのハッシュ型は `bcrypt` です。

こちらをご覧ください [PHPのドキュメント](https://php.net/manual/en/function.password-hash.php)
 bcryptとPHPのパスワードハッシュについての詳細情報が書かれています。

このアダプタの設定オプションは次のとおりです:

*   **hashType**: 使用するハッシュ化アルゴリズム。 有効な値は `password_hash()` の引数 `$algo` でサポートされている値です。 デフォルトは、 `PASSWORD_DEFAULT` です。
    
*   **hashOptions**: オプションの連想配列。 各ハッシュ型でサポートしているオプションについてはPHPマニュアルを参照してください。 デフォルトは空の配列です。
    

レガシー[¶](https://book.cakephp.org/authentication/3/ja/password-hashers.html#id1 "このヘッドラインへのパーマリンク")

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

cakePHP2から移行したアプリケーションのためのパスワードハッシャーです。

フォールバック[¶](https://book.cakephp.org/authentication/3/ja/password-hashers.html#id2 "このヘッドラインへのパーマリンク")

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

フォールバックパスワードハッシャーでは、 複数のハッシャーを設定することができ、それらを順次チェックしていきます。 これにより、パスワードがリセットされて新しいハッシュにアップグレードされるまで、 古いハッシュタイプでログインすることができます。

ハッシュアルゴリズムのアップグレード[¶](https://book.cakephp.org/authentication/3/ja/password-hashers.html#id3 "このヘッドラインへのパーマリンク")

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

CakePHPは、ユーザーのパスワードをあるアルゴリズムから別のアルゴリズムに移行するためのクリーンな方法を提供します。 これは `FallbackPasswordHasher` クラスによって実現されます。 レガシーパスワードからデフォルトのbcryptハッシャーに移行したい場合を想定しています。 以下のようにフォールバックハッシュアーを想定することができます。:

$service\->loadIdentifier('Authentication.Password', \[\
    // その他の設定オプション\
    'passwordHasher' \=> \[\
        'className' \=> 'Authentication.Fallback',\
        'hashers' \=> \[\
            'Authentication.Default',\
            \[\
                'className' \=> 'Authentication.Legacy',\
                'hashType' \=> 'md5',\
                'salt' \=> false // saltのデフォルトをoffにする\
            \],\
        \]\
    \]\
\]);

ログインアクションの中で認証サービスを使って `Password` 識別子にアクセスし、 現在のユーザーのパスワードをアップグレードする必要があるかどうかをチェックすることができます。:

public function login()
{
    $authentication \= $this\->request\->getAttribute('authentication');
    $result \= $authentication\->getResult();

    // POST  GETに関係なくログインする時にリダイレクトする
    if ($result\->isValid()) {
        // 識別子に \`Password\` を使用していると仮定します。
        if ($authentication\->identifiers()\->get('Password')\->needsPasswordRehash()) {
            // セーブ時にリハッシュが発生します。
            $user \= $this\->Users\->get($this\->Auth\->user('id'));
            $user\->password \= $this\->request\->getData('password');
            $this\->Users\->save($user);
        }

        // テンプレートをリダイレクトしたり、表示したりします。
    }
}

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# URL チェッカー - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/authentication/edit/3.x/docs/ja/url-checkers.rst)

[](https://book.cakephp.org/authentication/3/ja/url-checkers.html#page-contents)

### Page Contents

*   [URL チェッカー](https://book.cakephp.org/authentication/3/ja/url-checkers.html#)
    *   [付属のチェッカー](https://book.cakephp.org/authentication/3/ja/url-checkers.html#id1)
        *   [DefaultUrlChecker](https://book.cakephp.org/authentication/3/ja/url-checkers.html#defaulturlchecker)
            
        *   [CakeRouterUrlChecker](https://book.cakephp.org/authentication/3/ja/url-checkers.html#cakerouterurlchecker)
            
        *   [独自のチェッカーの実装](https://book.cakephp.org/authentication/3/ja/url-checkers.html#id2)
            

URL チェッカー[¶](https://book.cakephp.org/authentication/3/ja/url-checkers.html#url "このヘッドラインへのパーマリンク")

====================================================================================================

抽象的でフレームワークに依存しないソリューションを提供するために、 必要に応じて現在のURLの比較をカスタマイズできるURLチェッカーが実装されています。 例えば、別のフレームワークのルーティングなど。

付属のチェッカー[¶](https://book.cakephp.org/authentication/3/ja/url-checkers.html#id1 "このヘッドラインへのパーマリンク")

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

### DefaultUrlChecker[¶](https://book.cakephp.org/authentication/3/ja/url-checkers.html#defaulturlchecker "このヘッドラインへのパーマリンク")

デフォルトのチェッカーでは、正規表現や文字列のURLでURLを比較することができます。

オプション:

*   **checkFullUrl**: フルURLを比較するには, プロトコルを含みます。 ホストとポートの有無を指定します。 デフォルトは `false` です。
    
*   **useRegex**: チェッカーの引数 `$loginUrls` で指定された正規表現でURLを比較します。
    

### CakeRouterUrlChecker[¶](https://book.cakephp.org/authentication/3/ja/url-checkers.html#cakerouterurlchecker "このヘッドラインへのパーマリンク")

オプション:

CakePHPsのルーティングシステムの配列表記を使用したい場合は、このチェッカーを使用します。 チェッカーは名前付きルートでも動作します。

*   **checkFullUrl**: プロトコル、ホスト、ポートを含む完全なURLを比較するかどうか。デフォルトは `false`
    

### 独自のチェッカーの実装[¶](https://book.cakephp.org/authentication/3/ja/url-checkers.html#id2 "このヘッドラインへのパーマリンク")

URLチェッカーは `UrlCheckterInterface` を実装 _していなければなりません_ 。

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# 認証コンポーネントから移行 - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/authentication/edit/3.x/docs/ja/migration-from-the-authcomponent.rst)

[](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#page-contents)

### Page Contents

*   [認証コンポーネントから移行](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#)
    *   [違い](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id2)
        
    *   [類似](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id3)
        
    *   [認証装置と認証者](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id4)
        
    *   [認証設定の移行](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id5)
        *   [AuthComponent の設定の移行](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#authcomponent)
            
        *   [ロジックアクション](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id6)
            
        *   [認証者の確認](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id7)
            
        *   [許可/拒否ロジックの移行](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id8)
            
    *   [認証されていないリダイレクトの移行](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id9)
        
    *   [ハッシングアップグレードロジックの移行](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id10)
        

認証コンポーネントから移行[¶](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id1 "このヘッドラインへのパーマリンク")

============================================================================================================================

違い[¶](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id2 "このヘッドラインへのパーマリンク")

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

*   このプラグインは意図的に認可を処理しません。 [懸念事項](https://en.wikipedia.org/wiki/Separation_of_concerns)
     を明確に分離するために、 わざと認可から [切り離され](https://en.wikipedia.org/wiki/Coupling_(computer_programming))
     ました。 [\`コンピュータアクセス制御<https://en.wikipedia.org/wiki/Computer\_access\_control>\`\_\_](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id11)
     もご覧ください。 このプラグインは、 _本人確認_ と _認証のみ_ を行います。 認可のための別のプラグインがあるかもしれません。
    
*   セッションの自動チェックはありません。 セッションから実際のユーザーデータを取得するには、 `SessionAuthenticator` を使用する必要があります。 設定したセッションキーにデータがあるかどうかをチェックして、それをIDオブジェクトに入れてくれます。
    
*   ユーザーのデータは古いAuthComponentでは利用できなくなりましたが、 request属性を使ってアクセスでき、 identityオブジェクトにカプセル化されています: `$request->getAttribute('authentication')->getIdentity();` 。 さらに, `AuthenticationComponent` の `getIdentity()` と `getIdentityData()` が使えます。
    
*   認証処理のロジックは、認証と本人確認に分かれています。 認証機能はリクエストから認証情報を抽出し、識別子は認証情報を検証して一致するユーザーを見つけます。
    
*   DigestAuthenticateの名前がHttpDigestAuthenticatorに変更しました。
    
*   BasicAuthenticateの名前がHttpBasicAuthenticatorに変更しました。
    

類似[¶](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id3 "このヘッドラインへのパーマリンク")

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

*   既存の認証アダプタ、Form、Basic、Digestはすべて残っていますが、認証アダプタにリファクタリングされています。
    

認証装置と認証者[¶](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id4 "このヘッドラインへのパーマリンク")

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

関係分離の原則に従って、従来の認証オブジェクトは、 認証装置と認証者という別々のオブジェクトに分割されました。

*   **認証装置** 受信したリクエストを受け取り、そこから識別情報を抽出しようとします。 資格情報が見つかった場合、その資格情報はユーザーの位置を示す識別子のコレクションに渡されます。 このため、認証子はIdentifierCollectionをコンストラクタの最初の引数として取ります。
    
*   **認証者** ストレージシステムに対する識別資格情報を検証します。 例: (ORMテーブル, LDAP など) と識別されたユーザーデータを返します。
    

これにより、必要に応じて識別ロジックを変更したり、 複数のユーザーデータソースを使用したりすることが容易になります。

独自の識別子を実装したい場合は `IdentifierInterface` を実装しなければなりません。

認証設定の移行[¶](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id5 "このヘッドラインへのパーマリンク")

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

アプリケーションを移行する最初のステップは、 アプリケーションのブートストラップメソッドで認証プラグインをロードすることです。:

public function bootstrap(): void
{
    parent::bootstrap();
    $this\->addPlugin('Authentication');
}

その後、アプリケーションを更新して、認証プロバイダのインターフェースを実装してください。 これにより、AuthenticationMiddleware はアプリケーションから認証サービスを取得する方法を知ることができます。:

// src/Application.php の中

// 以下を追加してください
use Authentication\\AuthenticationService;
use Authentication\\AuthenticationServiceInterface;
use Authentication\\AuthenticationServiceProviderInterface;
use Authentication\\Middleware\\AuthenticationMiddleware;
use Psr\\Http\\Message\\ResponseInterface;
use Psr\\Http\\Message\\ServerRequestInterface;

// 認証インターフェースを追加します。
class Application extends BaseApplication implements AuthenticationServiceProviderInterface
{
    /\*\*
     \* サービスプロバイダのインスタンスを返します。
     \*
     \* @param \\Psr\\Http\\Message\\ServerRequestInterface $request Request
     \* @param \\Psr\\Http\\Message\\ResponseInterface $response Response
     \* @return \\Authentication\\AuthenticationServiceInterface
     \*/
    public function getAuthenticationService(ServerRequestInterface $request) : AuthenticationServiceInterface
    {
        $service \= new AuthenticationService();
        // サービス設定 (詳細は以下をご覧ください)
        return $service;
    }
}

次に `AuthenticationMiddleware` を追加します。:

// src/Application.php のなか
public function middleware($middlewareQueue)
{
    // その他、エラー処理やルーティングなどの各種ミドルウェアを追加しました。

    // ミドルウェアキューにミドルウェアを追加する
    $middlewareQueue\->add(new AuthenticationMiddleware($this));

    return $middlewareQueue;
}

### AuthComponent の設定の移行[¶](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#authcomponent "このヘッドラインへのパーマリンク")

サービスを設定する際には `AuthComponent` の設定配列を識別子と認証子に分割する必要があります。 また、このように `AuthComponent` を設定していたときは:

$this\->loadComponent('Auth', \[\
    'authentication' \=> \[\
        'Form' \=> \[\
            'fields' \=> \[\
                'username' \=> 'email',\
                'password' \=> 'password',\
            \]\
        \]\
    \]\
\]);

このように設定する必要があります。:

// サービスのインスタンス化
$service \= new AuthenticationService();

// 識別者の読み込み
$service\->loadIdentifier('Authentication.Password', \[\
    'fields' \=> \[\
        'username' \=> 'email',\
        'password' \=> 'password',\
    \]\
\]);

// 認証機能の読み込み
$service\->loadAuthenticator('Authentication.Session');
$service\->loadAuthenticator('Authentication.Form');

もし `userModel` をカスタマイズしているならば、以下の設定を使うことができます。:

// サービスのインスタンス化
$service \= new AuthenticationService();

// 識別者の読み込み
$service\->loadIdentifier('Authentication.Password', \[\
    'resolver' \=> \[\
        'className' \=> 'Authentication.Orm',\
        'userModel' \=> 'Employees',\
    \],\
    'fields' \=> \[\
        'username' \=> 'email',\
        'password' \=> 'password',\
    \]\
\]);

以前よりも少しコードが増えていますが、認証の処理方法に柔軟性が出てきています。

### ロジックアクション[¶](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id6 "このヘッドラインへのパーマリンク")

この\`\`AuthenticationMiddleware\`\`はあなたの認証子に基づいたアイデンティティのチェックと設定を行います。 通常、ログイン後に `AuthComponent` は設定した場所にリダイレクトします。 ログインが成功したときにリダイレクトするには、ログインアクションを変更して新しいIDの結果を確認してください。:

public function login()
{
    $result \= $this\->Authentication\->getResult();

    // POSTかGETにかかわらず、ユーザーがログインしている場合はリダイレクト
    if ($result\->isValid()) {
        $target \= $this\->Authentication\->getLoginRedirect();
        return $this\->redirect($target);
    }

    // ユーザーの送信と認証に失敗した場合にエラーを表示する
    if ($this\->request\->is(\['post'\])) {
        $this\->Flash\->error('ユーザー名またはパスワードが無効です');
    }
}

### 認証者の確認[¶](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id7 "このヘッドラインへのパーマリンク")

ミドルウェアを適用した後、`identity``リクエスト属性を使ってIDデータを利用することができます。 これは今使っている ``$this->Auth->user()` の呼び出しを置き換えるものです。 現在のユーザーが認証されていないか、提供された資格情報が無効な場合は、 `identity` が `null` になります。:

$user \= $request\->getAttribute('identity');

認証処理の結果の詳細については、リクエストに添付されている結果オブジェクトにアクセスすることができ、 `authentication` 属性にアクセスすることはできません。:

$result \= $request\->getAttribute('authentication')\->getResult();
// 結果が有効な場合のブール値
$isValid \= $result\->isValid();
// ステータスコード
$statusCode \= $result\->getStatus();
// 識別子が何かを提供した場合のエラーメッセージまたはデータの配列
$errors \= $result\->getErrors();

これまで `AuthComponent::setUser()` を呼んでいた場所は、 `setIdentity()` を使うようにしてください。:

// アクセストークンでユーザーを読み取る必要があるとします。
$user \= $this\->Users\->find('byToken', \['token' \=> $token\])\->first();

// ユーザーを構成された認証子に持続させます。
$this\->Authentication\->setIdentity($user);

### 許可/拒否ロジックの移行[¶](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id8 "このヘッドラインへのパーマリンク")

`AuthComponent` と同様に、 `AuthenticationComponent` は特定の動作を簡単に '公開' し、 有効なIDを必要としないようにします。:

// In your controller's beforeFilter method.
$this\->Authentication\->allowUnauthenticated(\['view'\]);

Each call to `allowUnauthenticated()` will overwrite the current action list.

認証されていないリダイレクトの移行[¶](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id9 "このヘッドラインへのパーマリンク")

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

By default `AuthComponent` redirects users back to the login page when authentication is required. In contrast, the `AuthenticationComponent` in this plugin will raise an exception in this scenario. You can convert this exception into a redirect using the `unauthenticatedRedirect` when configuring the `AuthenticationService`.

You can also pass the current request target URI as a query parameter using the `queryParam` option. Note that the redirect parameter is only appended for GET requests to prevent redirecting to non-GET actions after login:

// In the getAuthenticationService() method of your src/Application.php

$service \= new AuthenticationService();

// Configure unauthenticated redirect
$service\->setConfig(\[\
    'unauthenticatedRedirect' \=> '/users/login',\
    'queryParam' \=> 'redirect',\
\]);

そして、コントローラのログインメソッドで `getLoginRedirect()` を使用して、 クエリ文字列パラメータからリダイレクト先を安全に取得することができます。:

public function login()
{
    $result \= $this\->Authentication\->getResult();

    // POSTかGETに関わらず、 ユーザーがログインしている場合はリダイレクト
    if ($result\->isValid()) {
        // redirect パラメータがある場合は、それを使用します。
        $target \= $this\->Authentication\->getLoginRedirect();
        if (!$target) {
            $target \= \['controller' \=> 'Pages', 'action' \=> 'display', 'home'\];
        }
        return $this\->redirect($target);
    }
}

ハッシングアップグレードロジックの移行[¶](https://book.cakephp.org/authentication/3/ja/migration-from-the-authcomponent.html#id10 "このヘッドラインへのパーマリンク")

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

アプリケーションが `AuthComponent` のハッシュアップグレード機能を使用している場合。 このプラグインでは `AuthenticationService` を利用することで、そのロジックを複製することができます。:

public function login()
{
    $result \= $this\->Authentication\->getResult();

    // POSTかGETに関わらず、 ユーザーがログインしている場合はリダイレクト
    if ($result\->isValid()) {
        $authService \= $this\->Authentication\->getAuthenticationService();

        // 認証に使用された識別子を取得します。
        $identifier \= $authService\->getIdentificationProvider();
        if ($identifier !== null && $identifier\->needsPasswordRehash()) {
            // セーブ時にリハッシュが発生します。
            $user \= $this\->Users\->get($this\->Authentication\->getIdentityData('id'));
            $user\->password \= $this\->request\->getData('password');
            $this\->Users\->save($user);
        }

        // ログインしたページにリダイレクトする
        return $this\->redirect(\[\
            'controller' \=> 'Pages',\
            'action' \=> 'display',\
            'home'\
        \]);
    }
}

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# View Helper - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/authentication/edit/3.x/docs/ja/view-helper.rst)

[](https://book.cakephp.org/authentication/3/ja/view-helper.html#page-contents)

### Page Contents

*   [View Helper](https://book.cakephp.org/authentication/3/ja/view-helper.html#)
    

View Helper[¶](https://book.cakephp.org/authentication/3/ja/view-helper.html#view-helper "このヘッドラインへのパーマリンク")

=============================================================================================================

AppViewでヘルパーを次のようにロードします。:

$this\->loadHelper('Authentication.Identity');

ユーザーがログインしているかどうかを非常に簡単に確認するには:

if ($this\->Identity\->isLoggedIn()) {
    ...
}

ユーザーデータの取得は:

$username \= $this\->Identity\->get('username');

次のチェックは、あるユーザーに属するレコードが現在ログインしているユーザーであるかどうかを判断し、 他のフィールドを比較するために使用することができます。:

$isCurrentUser \= $this\->Identity\->is($user\->id);
$isCurrentRole \= $this\->Identity\->is($user\->role\_id, 'role\_id');

このメソッドは主に単純なケースのための便利なメソッドであり、いかなる種類の適切な認可実装を置き換えることを意図したものではありません。

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# 認証によるテスト - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/authentication/edit/3.x/docs/ja/testing.rst)

[](https://book.cakephp.org/authentication/3/ja/testing.html#page-contents)

### Page Contents

*   [認証によるテスト](https://book.cakephp.org/authentication/3/ja/testing.html#)
    *   [セッションベースの認証](https://book.cakephp.org/authentication/3/ja/testing.html#id2)
        
    *   [トークンベースの認証](https://book.cakephp.org/authentication/3/ja/testing.html#id3)
        

認証によるテスト[¶](https://book.cakephp.org/authentication/3/ja/testing.html#id1 "このヘッドラインへのパーマリンク")

==============================================================================================

アプリケーションで `authentication` ミドルウェアがアクティブな状態であれば、 統合テストで認証情報をシミュレートする必要があります。 使用している認証の種類に応じて、クレデンシャルを異なる方法でシミュレートする必要があります。 認証の一般的なタイプをいくつか確認してみましょう。

セッションベースの認証[¶](https://book.cakephp.org/authentication/3/ja/testing.html#id2 "このヘッドラインへのパーマリンク")

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

セッションベースの認証では、通常セッションで見つかるであろうユーザデータをシミュレートする必要があります。 テストケースでは、「ログイン」するためのヘルパーメソッドを定義することができます。:

protected function login($userId \= 1)
{
    $users \= TableRegistry::getTableLocator()\->get('Users');
    $user \= $users\->get($userId);
    $this\->session(\['Auth' \=> $user\]);
}

統合テストでは `login()` を使ってユーザがログインしたときのシミュレーションをすることができます。:

public function testGet()
{
    $this\->login();
    $this\->get('/bookmarks/1');
    $this\->assertResponseOk();
}

トークンベースの認証[¶](https://book.cakephp.org/authentication/3/ja/testing.html#id3 "このヘッドラインへのパーマリンク")

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

トークンベースの認証では `Authorization` ヘッダーをシミュレートする必要があります。 有効なトークンを取得した後、リクエスト:

public function testGet()
{
    $token \= $this\->getToken();
    $this\->configRequest(\[\
        'headers' \=> \['Authorization' \=> 'Bearer ' . $token\]\
    \]);
    $this\->get('/api/bookmarks');
    $this\->assertResponseOk();
}

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# クイック スタート - 2.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/authorization/edit/2.x/docs/ja/index.rst)

[](https://book.cakephp.org/authorization/2/ja/#page-contents)

### Page Contents

*   [クイック スタート](https://book.cakephp.org/authorization/2/ja/#)
    *   [インストール](https://book.cakephp.org/authorization/2/ja/#id2)
        
    *   [はじめに](https://book.cakephp.org/authorization/2/ja/#id3)
        
    *   [より詳しく](https://book.cakephp.org/authorization/2/ja/#id4)
        

クイック スタート[¶](https://book.cakephp.org/authorization/2/ja/#id1 "この見出しへのパーマリンク")

===============================================================================

インストール[¶](https://book.cakephp.org/authorization/2/ja/#id2 "この見出しへのパーマリンク")

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

プラグインをインストールするには、CakePHPから [composer](https://getcomposer.org/)
 を プロジェクトのルートディレクトリ (**composer.json** がある場所) で使用します。

php composer.phar require "cakephp/authorization:^2.0"

Authorization Plugin(認可プラグイン)のバージョン2はCakePHP4に対応しています。

プラグインを読み込むにはApplication.phpに下記の一業を追加します。 `src/Application.php`

$this\->addPlugin('Authorization');

はじめに[¶](https://book.cakephp.org/authorization/2/ja/#id3 "この見出しへのパーマリンク")

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

Authorization pluginは、ミドルウェア層としてアプリケーションに組み込まれ、 オプションのコンポーネントで認可の確認を容易に行え行えます。 はじめに **src/Application.php** に以下のクラス使用を明示してください。:

use Authorization\\AuthorizationService;
use Authorization\\AuthorizationServiceInterface;
use Authorization\\AuthorizationServiceProviderInterface;
use Authorization\\Middleware\\AuthorizationMiddleware;
use Authorization\\Policy\\OrmResolver;
use Psr\\Http\\Message\\ResponseInterface;
use Psr\\Http\\Message\\ServerRequestInterface;

Applicationに `AuthorizationServiceProviderInterface` を追加してください:

class Application extends BaseApplication implements AuthorizationServiceProviderInterface

そして、Applicationの `middleware()` を以下のようにします(AuthorizationMiddlewareを加える):

public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue
{
    // Middleware provided by CakePHP
    $middlewareQueue\->add(new ErrorHandlerMiddleware(Configure::read('Error')))
        \->add(new AssetMiddleware())
        \->add(new RoutingMiddleware($this))
        \->add(new BodyParserMiddleware())

        // If you are using Authentication it should be \*before\* Authorization.
        \->add(new AuthenticationMiddleware($this));

        // Add the AuthorizationMiddleware \*after\* routing, body parser
        // and authentication middleware.
        \->add(new AuthorizationMiddleware($this));

    return $middlewareQueue();
}

`AuthorizationMiddleware` は `AuthenticationMiddleware` の **後** に置く必要があります。 これにより、認可の確認で使用する `identity` が使用できるようになります。

`AuthorizationMiddleware` はリクエスト処理が開始した際に、フックメソッドを呼び出します。 このフックメソッドで、使用したい `AuthorizationService` を定義できます。 以下のメソッドを **src/Application.php** に追加してください。:

public function getAuthorizationService(ServerRequestInterface $request): AuthorizationServiceInterface
{
    $resolver \= new OrmResolver();

    return new AuthorizationService($resolver);
}

これは、ORMエンティティとPolicyクラスをマッチングする、基本的な [ポリシーリゾルバー](https://book.cakephp.org/authorization/2/ja/policy-resolvers.html)
 を設定するものです。

次に、　`AppController` に `AuthorizationComponent` を加えます。 **src/Controller/AppController.php** の `initialize()` に下記を追加してください。:

$this\->loadComponent('Authorization.Authorization');

[AuthorizationComponent](https://book.cakephp.org/authorization/2/ja/component.html)
 を読み込むことで、以下のような認可チェックを行うことができます。

> public function edit($id = null) {
> 
> > $article = $this->Article->get($id); $this->Authorization->authorize($article, 'update');
> > 
> > // Rest of action
> 
> }

`authorize` を呼び出すことで、 [Policies](https://book.cakephp.org/authorization/2/ja/policies.html)
 を使用して、アクセス制御ルールを強制することができます。 [identity stored in the request](https://book.cakephp.org/authorization/2/ja/checking-authorization.html)
 を使えばどこでも権限を確認することができます。

より詳しく[¶](https://book.cakephp.org/authorization/2/ja/#id4 "この見出しへのパーマリンク")

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

*   [Policies](https://book.cakephp.org/authorization/2/ja/policies.html)
    
*   [ポリシーリゾルバー](https://book.cakephp.org/authorization/2/ja/policy-resolvers.html)
    
*   [認可ミドルウェア](https://book.cakephp.org/authorization/2/ja/middleware.html)
    
*   [AuthorizationComponent](https://book.cakephp.org/authorization/2/ja/component.html)
    
*   [認可の確認](https://book.cakephp.org/authorization/2/ja/checking-authorization.html)
    
*   [リクエスト認証ミドルウェア](https://book.cakephp.org/authorization/2/ja/request-authorization-middleware.html)
    

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# Middleware - 3.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/authentication/edit/3.x/docs/ja/middleware.rst)

[](https://book.cakephp.org/authentication/3/ja/middleware.html#page-contents)

### Page Contents

*   [Middleware](https://book.cakephp.org/authentication/3/ja/middleware.html#)
    *   [設定](https://book.cakephp.org/authentication/3/ja/middleware.html#id1)
        
    *   [複数の認証設定の設定](https://book.cakephp.org/authentication/3/ja/middleware.html#id2)
        

Middleware[¶](https://book.cakephp.org/authentication/3/ja/middleware.html#middleware "このヘッドラインへのパーマリンク")

==========================================================================================================

`AuthenticationMiddleware` は認証プラグインの中で成形しています。 これは、アプリケーションへの各リクエストを捕らえ、いずれかの認証証明証でユーザーの認証を試みます。 各認証機能は、ユーザが認証されるまで、あるいはユーザが見つからないまで順番に試行されます。 認証された場合の ID と認証結果オブジェクトを含むリクエストには `authentication` 、`identity` 、 `authenticationResult` 属性が設定され、認証子によって提供された追加のエラーを含むことができます。

各リクエストの最後に `identity` は `Session` のようなステートフルな認証機能に保持されます。

設定[¶](https://book.cakephp.org/authentication/3/ja/middleware.html#id1 "このヘッドラインへのパーマリンク")

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

ミドルウェアの設定は全て `AuthenticationService` で行います。 サービスでは、次の構成オプションを使用できます:

*   `identityClass` - IDのクラス名、または呼び出し可能なIDビルダー。
    
*   `identityAttribute` - ID を格納するために使用されるリクエスト属性。デフォルトは `identity`。
    
*   `unauthenticatedRedirect` - 認証されていない場合リダイレクトするURL。
    
*   `queryParam` - 文字列を設定すると、認証されていないリダイレクトに `redirect` クエリ文字列パラメータに以前にブロックされたURLが含まれるようになります。
    

複数の認証設定の設定[¶](https://book.cakephp.org/authentication/3/ja/middleware.html#id2 "このヘッドラインへのパーマリンク")

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

アプリケーションがAPIやWeb UIなど、アプリケーションのさまざまな部分で異なる認証設定を必要とする場合。 これはアプリケーションの `getAuthenticationService()` フックメソッドで条件付きロジックを使用することで可能です。 リクエストオブジェクトを検査することで、認証を適切に設定することができます:

public function getAuthenticationService(ServerRequestInterface $request): AuthenticationServiceInterface
{
    $path \= $request\->getPath();

    $service \= new AuthenticationService();
    if (strpos($path, '/api') \=== 0) {
        // Accept API tokens only
        $service\->loadAuthenticator('Authentication.Token');
        $service\->loadIdentifier('Authentication.Token');

        return $service;
    }

    // Web 認証
    // サポートセッションとフォームログイン
    $service\->loadAuthenticator('Authentication.Session');
    $service\->loadAuthenticator('Authentication.Form');

    $service\->loadIdentifier('Authentication.Password');

    return $service;
}

上記の例ではパスプレフィックスを使用していますが、同様のロジックをサブドメインやドメイン、 リクエストに存在するその他のヘッダや属性にも適用することができます。

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# Quick Start - 2.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/authentication/edit/2.x/docs/ja/index.rst)

[](https://book.cakephp.org/authentication/2/ja/#page-contents)

### Page Contents

*   [Quick Start](https://book.cakephp.org/authentication/2/ja/#)
    *   [はじめに](https://book.cakephp.org/authentication/2/ja/#id1)
        
    *   [ログインアクションの構成](https://book.cakephp.org/authentication/2/ja/#id3)
        
    *   [Further Reading](https://book.cakephp.org/authentication/2/ja/#further-reading)
        

Quick Start[¶](https://book.cakephp.org/authentication/2/ja/#quick-start "このヘッドラインへのパーマリンク")

=============================================================================================

CakePHPから [composer](https://getcomposer.org/)
 でプラグインをインストールします。 プロジェクトのルートディレクトリ( **composer.json** ファイルが置かれている場所です)

php composer.phar require "cakephp/authentication:^2.0"

プロジェクトの `src/Application.php` に以下の文を追加してプラグインをロードしてください。

public function bootstrap(): void
{
    parent::bootstrap();

    $this\->addPlugin('Authentication');
}

はじめに[¶](https://book.cakephp.org/authentication/2/ja/#id1 "このヘッドラインへのパーマリンク")

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

認証プラグインは、ミドルウェアとしてアプリケーションと統合します。 [middleware](https://book.cakephp.org/4/en/controllers/middleware.html)
 また、認証されていないアクセスをより簡単にするためのコンポーネントとして使用することもできます。 まずはミドルウェアを適用してみましょう。

**src/Application.php** に以下のクラスを追加します。

インポート:

use Authentication\\AuthenticationService;
use Authentication\\AuthenticationServiceInterface;
use Authentication\\AuthenticationServiceProviderInterface;
use Authentication\\Identifier\\IdentifierInterface;
use Authentication\\Middleware\\AuthenticationMiddleware;
use Cake\\Http\\MiddlewareQueue;
use Psr\\Http\\Message\\ServerRequestInterface;

次に、アプリケーションに実装されたインターフェースに `AuthenticationProviderInterface` を追加します。:

class Application extends BaseApplication implements AuthenticationServiceProviderInterface

次に、 `middleware()` メソッドに以下の AuthenticationMiddleware を追加します。:

$middleware\->add(new AuthenticationMiddleware($this));

注釈

両方ある場合は `AuthenticationMiddleware` の前に `AuthorizationMiddleware` を追加するようにしてください。

リクエストの処理を開始すると、 `AuthenticationMiddleware` はフックメソッドを呼び出します。 このフックメソッドにより、アプリケーションが使用したい `AuthenticationService` を定義することができます。 以下のメソッドを **src/Application.php** に記述します。:

/\*\*
 \* サービスプロバイダのインスタンスを返します。
 \*
 \* @param \\Psr\\Http\\Message\\ServerRequestInterface $request Request
 \* @return \\Authentication\\AuthenticationServiceInterface
 \*/
public function getAuthenticationService(ServerRequestInterface $request): AuthenticationServiceInterface
{
    $service \= new AuthenticationService();

    // 認証されていない場合にユーザーがどこにリダイレクトするかを定義します。
    $service\->setConfig(\[\
        'unauthenticatedRedirect' \=> '/users/login',\
        'queryParam' \=> 'redirect',\
    \]);

    $fields \= \[\
        IdentifierInterface::CREDENTIAL\_USERNAME \=> 'email',\
        IdentifierInterface::CREDENTIAL\_PASSWORD \=> 'password'\
    \];

    // 認証者を読み込みます。セッションを優先してください。
    $service\->loadAuthenticator('Authentication.Session');
    $service\->loadAuthenticator('Authentication.Form', \[\
        'fields' \=> $fields,\
        'loginUrl' \=> '/users/login'\
    \]);

    // 識別子を読み込みます。
    $service\->loadIdentifier('Authentication.Password', compact('fields'));

    return $service;
}

まず、ユーザーが認証されていない場合にどうするかを設定します。 次に、アプリケーションがユーザーを認証するための仕組みを定義する `Session` と `Form` [認証機能](https://book.cakephp.org/authentication/2/ja/authenticators.html)
 をアタッチします。 `Session` はセッション内のデータに基づいてユーザを識別し、 `Form` はログインフォームを `loginUrl` で扱うことを可能にします。

最後に、ログインしたユーザーを表す [identifier](https://book.cakephp.org/authentication/2/ja/identifiers.html)
 に変換するための [identity](https://book.cakephp.org/authentication/2/ja/identity-object.html)
 をアタッチします。

認証が確認できた場合、ミドルウェアは認証サービスを [属性](https://www.php-fig.org/psr/psr-7/)
. としてリクエストオブジェクトに追加します。

次に、 `AppController` に [認証 Component](https://book.cakephp.org/authentication/2/ja/authentication-component.html)
 を呼び出します。:

// in src/Controller/AppController.php
public function initialize()
{
    parent::initialize();

    $this\->loadComponent('Authentication.Authentication');
}

デフォルトでコンポーネントは、 **全て** のアクションに認証済みのユーザーを必要とします。 特定のコントローラでこの動作を無効にするには、 `allowUnauthenticated()` を使用してください。:

// コントローラの beforeFilter か initialize で、
// ログインしている必要のないview()とindex()を作成します。
$this\->Authentication\->allowUnauthenticated(\['view', 'index'\]);

ログインアクションの構成[¶](https://book.cakephp.org/authentication/2/ja/#id3 "このヘッドラインへのパーマリンク")

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

アプリケーションにミドルウェアを適用したら、ユーザーがログインするための方法が必要になります。 基本的に次のように `UsersController` にloginアクションと追加します。:

public function login()
{
    $result \= $this\->Authentication\->getResult();
    // ユーザーがログインしている場合は、そのユーザーを送り出してください。
    if ($result\->isValid()) {
        $target \= $this\->Authentication\->getLoginRedirect() ?? '/home';
        return $this\->redirect($target);
    }
    if ($this\->request\->is('post')) {
        $this\->Flash\->error('ユーザー名とパスワードが無効です');
    }
}

前のセクションで述べたように、コントローラの `beforeFilter()` コールバックで `login` アクションにアクセスできるようにして、 認証されていないユーザがアクセスできるようにしてください。:

public function beforeFilter(\\Cake\\Event\\EventInterface $event)
{
    parent::beforeFilter($event);

    $this\->Authentication\->allowUnauthenticated(\['login'\]);
}

シンプルなlogoutアクションの追加:

public function logout()
{
    $this\->Authentication\->logout();
    return $this\->redirect(\['controller' \=> 'Users', 'action' \=> 'login'\]);
}

ログインするためには、ユーザーはハッシュ化されたパスワードを持つ必要があります。以下のようなことができます。 ユーザーがエンティティを使用してパスワードを更新すると、自動的にパスワードをハッシュ化します。:

// in src/Model/Entity/User.php
use Authentication\\PasswordHasher\\DefaultPasswordHasher;

class User extends Entity
{
    // ... other methods

    // Automatically hash passwords when they are changed.
    protected function \_setPassword(string $password)
    {
        $hasher \= new DefaultPasswordHasher();
        return $hasher\->hash($password);
    }
}

Further Reading[¶](https://book.cakephp.org/authentication/2/ja/#further-reading "このヘッドラインへのパーマリンク")

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

*   [認証機能](https://book.cakephp.org/authentication/2/ja/authenticators.html)
    
*   [Identifiers](https://book.cakephp.org/authentication/2/ja/identifiers.html)
    
*   [Password Hashers](https://book.cakephp.org/authentication/2/ja/password-hashers.html)
    
*   [Identity Objects](https://book.cakephp.org/authentication/2/ja/identity-object.html)
    
*   [認証 Component](https://book.cakephp.org/authentication/2/ja/authentication-component.html)
    
*   [認証コンポーネントから移行](https://book.cakephp.org/authentication/2/ja/migration-from-the-authcomponent.html)
    
*   [URL チェッカー](https://book.cakephp.org/authentication/2/ja/url-checkers.html)
    
*   [認証によるテスト](https://book.cakephp.org/authentication/2/ja/testing.html)
    
*   [View Helper](https://book.cakephp.org/authentication/2/ja/view-helper.html)
    

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# <no title> - 4.x

**Nav**

**Table of Contents**

[###### Improve This Doc](https://github.com/cakephp/debug_kit/edit/4.x/docs/ja/contents.rst)

[](https://book.cakephp.org/debugkit/4/ja/contents.html#page-contents)

CakePHP DebugKit

*   [Debug Kit](https://book.cakephp.org/debugkit/4/ja/index.html)
    *   [インストール](https://book.cakephp.org/debugkit/4/ja/index.html#id1)
        
    *   [設定](https://book.cakephp.org/debugkit/4/ja/index.html#id2)
        
    *   [ツールバーの使い方](https://book.cakephp.org/debugkit/4/ja/index.html#id4)
        
    *   [履歴パネルを使用する](https://book.cakephp.org/debugkit/4/ja/index.html#id5)
        
    *   [メールパネルを使用](https://book.cakephp.org/debugkit/4/ja/index.html#id6)
        
    *   [独自のパネルを開発する](https://book.cakephp.org/debugkit/4/ja/index.html#id8)
        
    *   [ヘルパー関数](https://book.cakephp.org/debugkit/4/ja/index.html#id15)
        

[](https://phpc.social/@cakephp "Mastodon")
[](https://twitter.com/cakephp "Twitter")
[](https://www.facebook.com/groups/cake.community "Facebook")
[](https://www.youtube.com/user/CakePHP "Youtube")
[](https://www.linkedin.com/groups/4623165/profile "Linkedin")
[](https://github.com/cakephp "Github")
[](https://slack-invite.cakephp.org/ "Slack")
[](https://stackoverflow.com/tags/cakephp "Stack Overflow")

---

# Form Protection Component | CakePHP

[Skip to content](https://book.cakephp.org/6.x/controllers/components/form-protection.html#VPContent)

Return to top

Form Protection Component [​](https://book.cakephp.org/6.x/controllers/components/form-protection.html#form-protection-component)

==================================================================================================================================

`class` **FormProtection**(ComponentCollection $collection, array $config = \[\])

The FormProtection Component provides protection against form data tampering.

Like all components it is configured through several configurable parameters. All of these properties can be set directly or through setter methods of the same name in your controller's `initialize()` or `beforeFilter()` methods.

If you are using other components that process form data in their `startup()` callbacks, be sure to place FormProtection Component before those components in your `initialize()` method.

NOTE

When using the FormProtection Component you **must** use the FormHelper to create your forms. In addition, you must **not** override any of the fields' "name" attributes. The FormProtection Component looks for certain indicators that are created and managed by the FormHelper (especially those created in `Cake\View\Helper\FormHelper::create()` and `Cake\View\Helper\FormHelper::end()`). Dynamically altering the fields that are submitted in a POST request, such as disabling, deleting or creating new fields via JavaScript, is likely to cause the form token validation to fail.

Form tampering prevention [​](https://book.cakephp.org/6.x/controllers/components/form-protection.html#form-tampering-prevention)

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

By default the `FormProtectionComponent` prevents users from tampering with forms in specific ways. It will prevent the following things:

*   Form's action (URL) cannot be modified.
*   Unknown fields cannot be added to the form.
*   Fields cannot be removed from the form.
*   Values in hidden inputs cannot be modified.

Preventing these types of tampering is accomplished by working with the `FormHelper` and tracking which fields are in a form. The values for hidden fields are tracked as well. All of this data is combined and turned into a hash and hidden token fields are automatically be inserted into forms. When a form is submitted, the `FormProtectionComponent` will use the POST data to build the same structure and compare the hash.

NOTE

The FormProtectionComponent will **not** prevent select options from being added/changed. Nor will it prevent radio options from being added/changed.

Usage [​](https://book.cakephp.org/6.x/controllers/components/form-protection.html#usage)

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

Configuring the form protection component is generally done in the controller's `initialize()` or `beforeFilter()` callbacks

Available options are:

validate  
Set to `false` to completely skip the validation of POST requests, essentially turning off form validation.

unlockedFields  
Set to a list of form fields to exclude from POST validation. Fields can be unlocked either in the Component, or with `FormHelper::unlockField()`. Fields that have been unlocked are not required to be part of the POST and hidden unlocked fields do not have their values checked.

unlockedActions  
Actions to exclude from POST validation checks.

validationFailureCallback  
Callback to call in case of validation failure. Must be a valid Closure. Unset by default in which case exception is thrown on validation failure.

Disabling form tampering checks [​](https://book.cakephp.org/6.x/controllers/components/form-protection.html#disabling-form-tampering-checks)

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

    namespace App\Controller;
    
    use App\Controller\AppController;
    use Cake\Event\EventInterface;
    
    class WidgetsController extends AppController
    {
        public function initialize(): void
        {
            parent::initialize();
    
            $this->loadComponent('FormProtection');
        }
    
        public function beforeFilter(EventInterface $event): void
        {
            parent::beforeFilter($event);
    
            if ($this->request->getParam('prefix') === 'Admin') {
                $this->FormProtection->setConfig('validate', false);
            }
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  

The above example would disable form tampering prevention for admin prefixed routes.

Disabling form tampering for specific actions [​](https://book.cakephp.org/6.x/controllers/components/form-protection.html#disabling-form-tampering-for-specific-actions)

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

There may be cases where you want to disable form tampering prevention for an action (ex. AJAX requests). You may "unlock" these actions by listing them in `$this->FormProtection->setConfig('unlockedActions', ['edit']);` in your `beforeFilter()`:

    namespace App\Controller;
    
    use App\Controller\AppController;
    use Cake\Event\EventInterface;
    
    class WidgetController extends AppController
    {
        public function initialize(): void
        {
            parent::initialize();
            $this->loadComponent('FormProtection');
        }
    
        public function beforeFilter(EventInterface $event): void
        {
            parent::beforeFilter($event);
    
            $this->FormProtection->setConfig('unlockedActions', ['edit']);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  

This example would disable all security checks for the edit action.

Handling validation failure through callbacks [​](https://book.cakephp.org/6.x/controllers/components/form-protection.html#handling-validation-failure-through-callbacks)

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

If form protection validation fails it will result in a 400 error by default. You can configure this behavior by setting the `validationFailureCallback` configuration option to a callback function in the controller.

By configuring a callback method you can customize how the failure handling process works:

    use Cake\Controller\Exception\FormProtectionException;
    
    public function beforeFilter(EventInterface $event): void
    {
        parent::beforeFilter($event);
    
        $this->FormProtection->setConfig(
            'validationFailureCallback',
            // Prior to 5.2 use Cake\Http\Exception\BadRequestException.
            function (FormProtectionException $exception) {
                // You can either return a response instance or throw the exception
                // received as argument.
            }
        );
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15

---

# Timestamp | CakePHP

[Skip to content](https://book.cakephp.org/6.x/orm/behaviors/timestamp.html#VPContent)

Return to top

Timestamp [​](https://book.cakephp.org/6.x/orm/behaviors/timestamp.html#timestamp)

===================================================================================

`class` Cake\\ORM\\Behavior\\**TimestampBehavior**

The timestamp behavior allows your table objects to update one or more timestamps on each model event. This is primarily used to populate data into `created` and `modified` fields. However, with some additional configuration, you can update any timestamp/datetime column on any event a table publishes.

Basic Usage [​](https://book.cakephp.org/6.x/orm/behaviors/timestamp.html#basic-usage)

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

You enable the timestamp behavior like any other behavior:

    class ArticlesTable extends Table
    {
        public function initialize(array $config): void
        {
            $this->addBehavior('Timestamp');
        }
    }

1  
2  
3  
4  
5  
6  
7  

The default configuration will do the following:

*   When a new entity is saved the `created` and `modified` fields will be set to the current time.
*   When an entity is updated, the `modified` field is set to the current time.

Using and Configuring the Behavior [​](https://book.cakephp.org/6.x/orm/behaviors/timestamp.html#using-and-configuring-the-behavior)

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

If you need to modify fields with different names, or want to update additional timestamp fields on custom events you can use some additional configuration:

    class OrdersTable extends Table
    {
        public function initialize(array $config): void
        {
            $this->addBehavior('Timestamp', [\
                'events' => [\
                    'Model.beforeSave' => [\
                        'created_at' => 'new',\
                        'updated_at' => 'always',\
                    ],\
                    'Orders.completed' => [\
                        'completed_at' => 'always'\
                    ]\
                ]\
            ]);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

As you can see above, in addition to the standard `Model.beforeSave` event, we are also updating the `completed_at` column when orders are completed.

Updating Timestamps on Entities [​](https://book.cakephp.org/6.x/orm/behaviors/timestamp.html#updating-timestamps-on-entities)

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

Sometimes you'll want to update just the timestamps on an entity without changing any other properties. This is sometimes referred to as 'touching' a record. In CakePHP you can use the `touch()` method to do exactly this:

    // Touch based on the Model.beforeSave event.
    $articles->getBehavior('Timestamp')->touch($article);
    
    // Touch based on a specific event.
    $orders->getBehavior('Timestamp')->touch($order, 'Orders.completed');

1  
2  
3  
4  
5  

After you have saved the entity, the field is updated.

Touching records can be useful when you want to signal that a parent resource has changed when a child resource is created/updated. For example: updating an article when a new comment is added.

Saving Updates Without Modifying Timestamps [​](https://book.cakephp.org/6.x/orm/behaviors/timestamp.html#saving-updates-without-modifying-timestamps)

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

To disable the automatic modification of the `updated` timestamp column when saving an entity you can mark the attribute as 'dirty':

    // Mark the modified column as dirty making
    // the current value be set on update.
    $order->setDirty('modified', true);

1  
2  
3

---

# CounterCache | CakePHP

[Skip to content](https://book.cakephp.org/6.x/orm/behaviors/counter-cache.html#VPContent)

Return to top

CounterCache [​](https://book.cakephp.org/6.x/orm/behaviors/counter-cache.html#countercache)

=============================================================================================

`class` Cake\\ORM\\Behavior\\**CounterCacheBehavior**

Often times web applications need to display counts of related objects. For example, when showing a list of articles you may want to display how many comments it has. Or when showing a user you might want to show how many friends/followers she has. The CounterCache behavior is intended for these situations. CounterCache will update a field in the associated models assigned in the options when it is invoked. The fields should exist in the database and be of the type INT.

Basic Usage [​](https://book.cakephp.org/6.x/orm/behaviors/counter-cache.html#basic-usage)

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

You enable the CounterCache behavior like any other behavior, but it won't do anything until you configure some relations and the field counts that should be stored on each of them. Using our example below, we could cache the comment count for each article with the following:

    class CommentsTable extends Table
    {
        public function initialize(array $config): void
        {
            $this->addBehavior('CounterCache', [\
                'Articles' => ['comment_count']\
            ]);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  

NOTE

The column `comment_count` should exist in the `articles` table.

The CounterCache configuration should be a map of relation names and the specific configuration for that relation.

As you see you need to add the behavior on the "other side" of the association where you actually want the field to be updated. In this example the behavior is added to the `CommentsTable` even though it updates the `comment_count` field in the `ArticlesTable`.

The counter's value will be updated each time an entity is saved or deleted. The counter **will not** be updated when you

*   save the entity without changing data or
*   use `updateAll()` or
*   use `deleteAll()` or
*   execute SQL you have written

Advanced Usage [​](https://book.cakephp.org/6.x/orm/behaviors/counter-cache.html#advanced-usage)

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

If you need to keep a cached counter for less than all of the related records, you can supply additional conditions or finder methods to generate a counter value:

    // Use a specific find method.
    // In this case find(published)
    $this->addBehavior('CounterCache', [\
        'Articles' => [\
            'comment_count' => [\
                'finder' => 'published',\
            ],\
        ],\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  

If you don't have a custom finder method you can provide an array of conditions to find records instead:

    $this->addBehavior('CounterCache', [\
        'Articles' => [\
            'comment_count' => [\
                'conditions' => ['Comments.spam' => false],\
            ],\
        ],\
    ]);

1  
2  
3  
4  
5  
6  
7  

If you want CounterCache to update multiple fields, for example both showing a conditional count and a basic count you can add these fields in the array:

    $this->addBehavior('CounterCache', [\
        'Articles' => ['comment_count',\
            'published_comment_count' => [\
                'finder' => 'published',\
            ],\
        ],\
    ]);

1  
2  
3  
4  
5  
6  
7  

If you want to calculate the CounterCache field value on your own, you can set the `ignoreDirty` option to `true`. This will prevent the field from being recalculated if you've set it dirty before:

    $this->addBehavior('CounterCache', [\
        'Articles' => [\
            'comment_count' => [\
                'ignoreDirty' => true,\
            ],\
        ],\
    ]);

1  
2  
3  
4  
5  
6  
7  

Lastly, if a custom finder and conditions are not suitable you can provide a callback function. Your function must return the count value to be stored:

    $this->addBehavior('CounterCache', [\
        'Articles' => [\
            'rating_avg' => function ($event, $entity, $table, $original) {\
                return 4.5;\
            }\
        ],\
    ]);

1  
2  
3  
4  
5  
6  
7  

Your function can return `false` to skip updating the counter column, or a `SelectQuery` object that produced the count value. If you return a `SelectQuery` object, your query will be used as a subquery in the update statement. The `$table` parameter refers to the table object holding the behavior (not the target relation) for convenience. The callback is invoked at least once with `$original` set to `false`. If the entity-update changes the association then the callback is invoked a _second_ time with `true`, the return value then updates the counter of the _previously_ associated item.

NOTE

The CounterCache behavior works for `belongsTo` associations only. For example for "Comments belongsTo Articles", you need to add the CounterCache behavior to the `CommentsTable` in order to generate `comment_count` for Articles table.

Changed in version 5.1.2

As of CakePHP 5.1.2, the counter cache values are updated using a single query using sub-queries, instead of separate queries, to fetch the count and update a record. If required you can disable the use of sub-queries by setting useSubQuery key to false in the config \['Articles' => \['comment\_count' => \['useSubQuery' => false\]\]\
\
Belongs to many Usage [​](https://book.cakephp.org/6.x/orm/behaviors/counter-cache.html#belongs-to-many-usage)\
\
---------------------------------------------------------------------------------------------------------------\
\
It is possible to use the CounterCache behavior in a `belongsToMany` association. First, you need to add the `through` and `cascadeCallbacks` options to the `belongsToMany` association:\
\
    'through'          => 'CommentsArticles',\
    'cascadeCallbacks' => true\
\
1  \
2  \
\
Also see [Using The Through Option](https://book.cakephp.org/6.x/orm/associations.html#using-the-through-option)\
 how to configure a custom join table.\
\
The `CommentsArticles` is the name of the junction table classname. If you don't have it you should create it with the bake CLI tool.\
\
In this `src/Model/Table/CommentsArticlesTable.php` you then need to add the behavior with the same code as described above.:\
\
    $this->addBehavior('CounterCache', [\
        'Articles' => ['comments_count'],\
    ]);\
\
1  \
2  \
3  \
\
Finally clear all caches with `bin/cake cache clear_all` and try it out.\
\
Manually updating counter caches [​](https://book.cakephp.org/6.x/orm/behaviors/counter-cache.html#manually-updating-counter-caches)\
\
-------------------------------------------------------------------------------------------------------------------------------------\
\
`method` Cake\\ORM\\Behavior\\CounterCacheBehavior::**updateCounterCache(?string $assocName = null, int $limit = 100, ?int $page = null): void**()\
\
The `updateCounterCache()` method allows you to update the counter cache values for all records of one or all configured associations in batches. This can be useful, for example, to update the counter cache after importing data directly into the database.:\
\
    // Update the counter cache for all configured associations\
    $table->getBehavior('CounterCache')->updateCounterCache();\
    \
    // Update the counter cache for a specific association, 200 records per batch\
    $table->getBehavior('CounterCache')->updateCounterCache('Articles', 200);\
    \
    // Update only the first page of records\
    $table->getBehavior('CounterCache')->updateCounterCache('Articles', page: 1);\
\
1  \
2  \
3  \
4  \
5  \
6  \
7  \
8  \
\
Added in version 5.2.0\
\
NOTE\
\
This methods won't update the counter cache values for fields which are configured to use a closure to get the count value.

---

# App Class | CakePHP

[Skip to content](https://book.cakephp.org/6.x/core-libraries/app.html#VPContent)

Return to top

App Class [​](https://book.cakephp.org/6.x/core-libraries/app.html#app-class)

==============================================================================

`class` Cake\\Core\\**App**

The App class is responsible for resource location and path management.

Finding Classes [​](https://book.cakephp.org/6.x/core-libraries/app.html#finding-classes)

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

### App::className() [​](https://book.cakephp.org/6.x/core-libraries/app.html#app-classname)

`static` Cake\\Core\\App::**className**($name, $type = '', $suffix = ''): string|null

This method is used to resolve class names throughout CakePHP. It resolves the short form names CakePHP uses and returns the fully resolved class name:

    // Resolve a short class name with the namespace + suffix.
    App::className('Flash', 'Controller/Component', 'Component');
    // Returns Cake\Controller\Component\FlashComponent
    
    // Resolve a plugin name.
    App::className('DebugKit.Toolbar', 'Controller/Component', 'Component');
    // Returns DebugKit\Controller\Component\ToolbarComponent
    
    // Names with \ in them will be returned unaltered.
    App::className('App\Cache\ComboCache');
    // Returns App\Cache\ComboCache

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

When resolving classes, the `App` namespace will be tried, and if the class does not exist the `Cake` namespace will be attempted. If both class names do not exist, `false` will be returned.

Finding Paths to Resources [​](https://book.cakephp.org/6.x/core-libraries/app.html#finding-paths-to-resources)

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

### App::path() [​](https://book.cakephp.org/6.x/core-libraries/app.html#app-path)

`static` Cake\\Core\\App::**path**(string $package, ?string $plugin = null): array

The method returns paths set using `App.paths` app config:

    // Get the templates path set using ``App.paths.templates`` app config.
    App::path('templates');

1  
2  

The same way you can retrieve paths for `locales` and `plugins`.

Finding Paths to Namespaces [​](https://book.cakephp.org/6.x/core-libraries/app.html#finding-paths-to-namespaces)

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

### App::classPath() [​](https://book.cakephp.org/6.x/core-libraries/app.html#app-classpath)

`static` Cake\\Core\\App::**classPath**(string $package, ?string $plugin = null): array

Used to get locations for paths based on conventions:

    // Get the path to Controller/ in your application
    App::classPath('Controller');

1  
2  

This can be done for all namespaces that are part of your application.

`App::classPath()` will only return the default path, and will not be able to provide any information about additional paths the autoloader is configured for.

### App::core() [​](https://book.cakephp.org/6.x/core-libraries/app.html#app-core)

`static` Cake\\Core\\App::**core**(string $package): array

Used for finding the path to a package inside CakePHP:

    // Get the path to Cache engines.
    App::core('Cache/Engine');

1  
2  

Locating Themes [​](https://book.cakephp.org/6.x/core-libraries/app.html#locating-themes)

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

Since themes are plugins, you can use the methods above to get the path to a theme.

Loading Vendor Files [​](https://book.cakephp.org/6.x/core-libraries/app.html#loading-vendor-files)

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

Ideally vendor files should be autoloaded with `Composer`, if you have vendor files that cannot be autoloaded or installed with Composer you will need to use `require` to load them.

If you cannot install a library with Composer, it is best to install each library in a directory following Composer's convention of `vendor/$author/$package`. If you had a library called AcmeLib, you could install it into `vendor/Acme/AcmeLib`. Assuming it did not use PSR-0 compatible classnames you could autoload the classes within it using `classmap` in your application's `composer.json`:

    "autoload": {
        "psr-4": {
            "App\\": "src/",
            "App\\Test\\": "tests/"
        },
        "classmap": [\
            "vendor/Acme/AcmeLib"\
        ]
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  

If your vendor library does not use classes, and instead provides functions, you can configure Composer to load these files at the beginning of each request using the `files` autoloading strategy:

    "autoload": {
        "psr-4": {
            "App\\": "src/",
            "App\\Test\\": "tests/"
        },
        "files": [\
            "vendor/Acme/AcmeLib/functions.php"\
        ]
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  

After configuring the vendor libraries you will need to regenerate your application's autoloader using:

    $ php composer.phar dump-autoload

1  

If you happen to not be using Composer in your application, you will need to manually load all vendor libraries yourself.

---

# Registry Objects | CakePHP

[Skip to content](https://book.cakephp.org/6.x/core-libraries/registry-objects.html#VPContent)

Return to top

Registry Objects [​](https://book.cakephp.org/6.x/core-libraries/registry-objects.html#registry-objects)

=========================================================================================================

The registry classes provide a simple way to create and retrieve loaded instances of a given object type. There are registry classes for Components, Helpers, Tasks, and Behaviors.

While the examples below will use Components, the same behavior can be expected for Helpers, Behaviors, and Tasks in addition to Components.

Loading Objects [​](https://book.cakephp.org/6.x/core-libraries/registry-objects.html#loading-objects)

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

Objects can be loaded on-the-fly using add<registry-object>() Example:

    $this->loadComponent('Acl.Acl');
    $this->addHelper('Flash')

1  
2  

This will result in the `Acl` property and `Flash` helper being loaded. Configuration can also be set on-the-fly. Example:

    $this->loadComponent('Cookie', ['name' => 'sweet']);

1  

Any keys and values provided will be passed to the Component's constructor. The one exception to this rule is `className`. Classname is a special key that is used to alias objects in a registry. This allows you to have component names that do not reflect the classnames, which can be helpful when extending core components:

    $this->Flash = $this->loadComponent('Flash', ['className' => 'MyCustomFlash']);
    $this->Flash->error(); // Actually using MyCustomFlash::error();

1  
2  

Triggering Callbacks [​](https://book.cakephp.org/6.x/core-libraries/registry-objects.html#triggering-callbacks)

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

Callbacks are not provided by registry objects. You should use the [events system](https://book.cakephp.org/6.x/core-libraries/events.html)
 to dispatch any events/callbacks for your application.

Disabling Callbacks [​](https://book.cakephp.org/6.x/core-libraries/registry-objects.html#disabling-callbacks)

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

In previous versions, collection objects provided a `disable()` method to disable objects from receiving callbacks. You should use the features in the events system to accomplish this now. For example, you could disable component callbacks in the following way:

    // Remove MyComponent from callbacks.
    $this->getEventManager()->off($this->MyComponent);
    
    // Re-enable MyComponent for callbacks.
    $this->getEventManager()->on($this->MyComponent);

1  
2  
3  
4  
5

---

# Security Utility | CakePHP

[Skip to content](https://book.cakephp.org/6.x/core-libraries/security.html#VPContent)

Return to top

Security Utility [​](https://book.cakephp.org/6.x/core-libraries/security.html#security-utility)

=================================================================================================

`class` Cake\\Utility\\**Security**

The [security library](https://api.cakephp.org/5.x/class-Cake.Utility.Security.html)
 handles basic security measures such as providing methods for hashing and encrypting data.

Encrypting and Decrypting Data [​](https://book.cakephp.org/6.x/core-libraries/security.html#encrypting-and-decrypting-data)

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

### Security::encrypt() [​](https://book.cakephp.org/6.x/core-libraries/security.html#security-encrypt)

`static` Cake\\Utility\\Security::**encrypt**(string $plain, string $key, ?string $hmacSalt = null): string

### Security::decrypt() [​](https://book.cakephp.org/6.x/core-libraries/security.html#security-decrypt)

`static` Cake\\Utility\\Security::**decrypt**(string $cipher, string $key, ?string $hmacSalt = null): ?string

Encrypt `$text` using AES-256. The `$key` should be a value with a lots of variance in the data much like a good password. The returned result will be the encrypted value with an HMAC checksum.

The [openssl](https://php.net/openssl)
 extension is required for encrypting/decrypting.

An example use would be:

    // Assuming key is stored somewhere it can be re-used for
    // decryption later.
    $key = 'wt1U5MACWJFTXGenFoZoiLwQGrLgdbHA';
    $result = Security::encrypt($value, $key);

1  
2  
3  
4  

If you do not supply an HMAC salt, the value of `Security::getSalt()` will be used. Encrypted values can be decrypted using `Cake\Utility\Security::decrypt()`.

This method should **never** be used to store passwords.

Decrypt a previously encrypted value. The `$key` and `$hmacSalt` parameters must match the values used to encrypt or decryption will fail. An example use would be:

    // Assuming the key is stored somewhere it can be re-used for
    // Decryption later.
    $key = 'wt1U5MACWJFTXGenFoZoiLwQGrLgdbHA';
    
    $cipher = $user->secrets;
    $result = Security::decrypt($cipher, $key);

1  
2  
3  
4  
5  
6  

If the value cannot be decrypted due to changes in the key or HMAC salt `false` will be returned.

Hashing Data [​](https://book.cakephp.org/6.x/core-libraries/security.html#hashing-data)

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

### Security::hash() [​](https://book.cakephp.org/6.x/core-libraries/security.html#security-hash)

`static` Cake\\Utility\\Security::**hash**(string $string, ?string $algorithm = null, string|bool $salt = false): string

Create a hash from string using given method. Fallback on next available method. If `$salt` is set to `true`, the application's salt value will be used:

    // Using the application's salt value
    $sha1 = Security::hash('CakePHP Framework', 'sha1', true);
    
    // Using a custom salt value
    $sha1 = Security::hash('CakePHP Framework', 'sha1', 'my-salt');
    
    // Using the default hash algorithm
    $hash = Security::hash('CakePHP Framework');

1  
2  
3  
4  
5  
6  
7  
8  

The `hash()` method supports the following hashing strategies:

*   md5
*   sha1
*   sha256

And any other hash algorithm that PHP's `hash()` function supports.

WARNING

You should not be using `hash()` for passwords in new applications. Instead you should use the `DefaultPasswordHasher` class which uses bcrypt by default.

Getting Secure Random Data [​](https://book.cakephp.org/6.x/core-libraries/security.html#getting-secure-random-data)

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

### Security::randomBytes() [​](https://book.cakephp.org/6.x/core-libraries/security.html#security-randombytes)

`static` Cake\\Utility\\Security::**randomBytes**(int $length): string

Get `$length` number of bytes from a secure random source. This function draws data from one of the following sources:

*   PHP's `random_bytes` function.
*   `openssl_random_pseudo_bytes` from the SSL extension.

If neither source is available a warning will be emitted and an unsafe value will be used for backwards compatibility reasons.

### Security::randomString() [​](https://book.cakephp.org/6.x/core-libraries/security.html#security-randomstring)

`static` Cake\\Utility\\Security::**randomString**(int $length = 64): string

Get a random string `$length` long from a secure random source. This method draws from the same random source as `randomBytes()` and will encode the data as a hexadecimal string.

---

# Plugin Class | CakePHP

[Skip to content](https://book.cakephp.org/6.x/core-libraries/plugin.html#VPContent)

Return to top

Plugin Class [​](https://book.cakephp.org/6.x/core-libraries/plugin.html#plugin-class)

=======================================================================================

`class` Cake\\Core\\**Plugin**

The Plugin class is responsible for resource location and path management of plugins.

Locating Plugins [​](https://book.cakephp.org/6.x/core-libraries/plugin.html#locating-plugins)

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

### Plugin::path() [​](https://book.cakephp.org/6.x/core-libraries/plugin.html#plugin-path)

`static` Cake\\Core\\Plugin::**path**(string $plugin): string

Plugins can be located with Plugin. Using `Plugin::path('DebugKit');` for example, will give you the full path to the DebugKit plugin:

    $path = Plugin::path('DebugKit');

1  

Check if a Plugin is Loaded [​](https://book.cakephp.org/6.x/core-libraries/plugin.html#check-if-a-plugin-is-loaded)

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

You can check dynamically inside your code if a specific plugin has been loaded:

    $isLoaded = Plugin::isLoaded('DebugKit');

1  

Use `Plugin::loaded()` if you want to get a list of all currently loaded plugins.

Finding Paths to Namespaces [​](https://book.cakephp.org/6.x/core-libraries/plugin.html#finding-paths-to-namespaces)

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

### Plugin::classPath() [​](https://book.cakephp.org/6.x/core-libraries/plugin.html#plugin-classpath)

`static` Cake\\Core\\Plugin::**classPath**(string $plugin): string

Used to get the location of the plugin's class files:

    $path = App::classPath('DebugKit');

1  

Finding Paths to Resources [​](https://book.cakephp.org/6.x/core-libraries/plugin.html#finding-paths-to-resources)

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

### Plugin::templatePath() [​](https://book.cakephp.org/6.x/core-libraries/plugin.html#plugin-templatepath)

`static` Cake\\Core\\Plugin::**templatePath**(string $plugin): string

The method returns the path to the plugins' templates:

    $path = Plugin::templatePath('DebugKit');

1  

The same goes for the config path:

    $path = Plugin::configPath('DebugKit');

1

---

# Constants & Functions | CakePHP

[Skip to content](https://book.cakephp.org/6.x/core-libraries/global-constants-and-functions.html#VPContent)

Return to top

Constants & Functions [​](https://book.cakephp.org/6.x/core-libraries/global-constants-and-functions.html#constants-functions)

===============================================================================================================================

While most of your day-to-day work in CakePHP will be utilizing core classes and methods, CakePHP features a number of global convenience functions that may come in handy. Many of these functions are for use with CakePHP classes (loading model or component classes), but many others make working with arrays or strings a little easier.

We'll also cover some of the constants available in CakePHP applications. Using these constants will help make upgrades more smooth, but are also convenient ways to point to certain files or directories in your CakePHP application.

Global Functions [​](https://book.cakephp.org/6.x/core-libraries/global-constants-and-functions.html#global-functions)

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

Here are CakePHP's globally available functions. Most of them are just convenience wrappers for other CakePHP functionality, such as debugging and translating content. By default only namespaced functions are autoloaded, however you can optionally load global aliases by adding:

    require CAKE . 'functions.php';

1  

To your application's `config/bootstrap.php`. Doing this will load global aliases for _all_ functions listed below.

### \_\_() [​](https://book.cakephp.org/6.x/core-libraries/global-constants-and-functions.html#)

`function` **\_\_(string $string\_id, \[$formatArgs\])**

This function handles localization in CakePHP applications. The `$string_id` identifies the ID for a translation. You can supply additional arguments to replace placeholders in your string:

    __('You have {0} unread messages', $number);

1  

You can also provide a name-indexed array of replacements:

    __('You have {unread} unread messages', ['unread' => $number]);

1  

NOTE

Check out the [Internationalization & Localization](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html)
 section for more information.

### \_\_d() [​](https://book.cakephp.org/6.x/core-libraries/global-constants-and-functions.html#d)

`function` **\_\_d(string $domain, string $msg, mixed $args = null)**

Allows you to override the current domain for a single message lookup.

Useful when internationalizing a plugin: `echo __d('plugin_name', 'This is my plugin');`

NOTE

Make sure to use the underscored version of the plugin name here as domain.

### \_\_dn() [​](https://book.cakephp.org/6.x/core-libraries/global-constants-and-functions.html#dn)

`function` **\_\_dn(string $domain, string $singular, string $plural, integer $count, mixed $args = null)**

Allows you to override the current domain for a single plural message lookup. Returns correct plural form of message identified by `$singular` and `$plural` for count `$count` from domain `$domain`.

### \_\_dx() [​](https://book.cakephp.org/6.x/core-libraries/global-constants-and-functions.html#dx)

`function` **\_\_dx(string $domain, string $context, string $msg, mixed $args = null)**

Allows you to override the current domain for a single message lookup. It also allows you to specify a context.

The context is a unique identifier for the translations string that makes it unique within the same domain.

### \_\_dxn() [​](https://book.cakephp.org/6.x/core-libraries/global-constants-and-functions.html#dxn)

`function` **\_\_dxn(string $domain, string $context, string $singular, string $plural, integer $count, mixed $args = null)**

Allows you to override the current domain for a single plural message lookup. It also allows you to specify a context. Returns correct plural form of message identified by `$singular` and `$plural` for count `$count` from domain `$domain`. Some languages have more than one form for plural messages dependent on the count.

The context is a unique identifier for the translations string that makes it unique within the same domain.

### \_\_n() [​](https://book.cakephp.org/6.x/core-libraries/global-constants-and-functions.html#n)

`function` **\_\_n(string $singular, string $plural, integer $count, mixed $args = null)**

Returns correct plural form of message identified by `$singular` and `$plural` for count `$count`. Some languages have more than one form for plural messages dependent on the count.

### \_\_x() [​](https://book.cakephp.org/6.x/core-libraries/global-constants-and-functions.html#x)

`function` **\_\_x(string $context, string $msg, mixed $args = null)**

The context is a unique identifier for the translations string that makes it unique within the same domain.

### \_\_xn() [​](https://book.cakephp.org/6.x/core-libraries/global-constants-and-functions.html#xn)

`function` **\_\_xn(string $context, string $singular, string $plural, integer $count, mixed $args = null)**

Returns correct plural form of message identified by `$singular` and `$plural` for count `$count` from domain `$domain`. It also allows you to specify a context. Some languages have more than one form for plural messages dependent on the count.

The context is a unique identifier for the translations string that makes it unique within the same domain.

### collection() [​](https://book.cakephp.org/6.x/core-libraries/global-constants-and-functions.html#collection)

`function` **collection(mixed $items)**

Convenience wrapper for instantiating a new `Cake\Collection\Collection` object, wrapping the passed argument. The `$items` parameter takes either a `Traversable` object or an array.

### debug() [​](https://book.cakephp.org/6.x/core-libraries/global-constants-and-functions.html#debug)

`function` **debug(mixed $var, boolean $showHtml = null, $showFrom = true)**

If the core `$debug` variable is `true`, `$var` is printed out. If `$showHTML` is `true` or left as `null`, the data is rendered to be browser-friendly. If `$showFrom` is not set to `false`, the debug output will start with the line from which it was called. Also see [Debugging](https://book.cakephp.org/6.x/development/debugging.html)

### dd() [​](https://book.cakephp.org/6.x/core-libraries/global-constants-and-functions.html#dd)

`function` **dd(mixed $var, boolean $showHtml = null)**

It behaves like `debug()`, but execution is also halted. If the core `$debug` variable is `true`, `$var` is printed. If `$showHTML` is `true` or left as `null`, the data is rendered to be browser-friendly. Also see [Debugging](https://book.cakephp.org/6.x/development/debugging.html)

### pr() [​](https://book.cakephp.org/6.x/core-libraries/global-constants-and-functions.html#pr)

`function` **pr(mixed $var)**

Convenience wrapper for `print_r()`, with the addition of wrapping `<pre>` tags around the output.

### pj() [​](https://book.cakephp.org/6.x/core-libraries/global-constants-and-functions.html#pj)

`function` **pj(mixed $var)**

JSON pretty print convenience function, with the addition of wrapping `<pre>` tags around the output.

It is meant for debugging the JSON representation of objects and arrays.

### env() [​](https://book.cakephp.org/6.x/core-libraries/global-constants-and-functions.html#env)

`function` **env(string $key, string $default = null)**

Gets an environment variable from available sources. Used as a backup if `$_SERVER` or `$_ENV` are disabled.

This function also emulates `PHP_SELF` and `DOCUMENT_ROOT` on unsupporting servers. In fact, it's a good idea to always use `env()` instead of `$_SERVER` or `getenv()` (especially if you plan to distribute the code), since it's a full emulation wrapper.

### h() [​](https://book.cakephp.org/6.x/core-libraries/global-constants-and-functions.html#h)

`function` **h(string $text, boolean $double = true, string $charset = null)**

Convenience wrapper for `htmlspecialchars()`.

### pluginSplit() [​](https://book.cakephp.org/6.x/core-libraries/global-constants-and-functions.html#pluginsplit)

`function` **pluginSplit(string $name, boolean $dotAppend = false, string $plugin = null)**

Splits a dot syntax plugin name into its plugin and class name. If `$name` does not have a dot, then index 0 will be `null`.

Commonly used like `list($plugin, $name) = pluginSplit('Users.User');`

### namespaceSplit() [​](https://book.cakephp.org/6.x/core-libraries/global-constants-and-functions.html#namespacesplit)

`function` **namespaceSplit(string $class)**

Split the namespace from the classname.

Commonly used like `list($namespace, $className) = namespaceSplit('Cake\Core\App');`

Core Definition Constants [​](https://book.cakephp.org/6.x/core-libraries/global-constants-and-functions.html#core-definition-constants)

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

Most of the following constants refer to paths in your application.

`constant` Cake\\Core\\**APP**

Absolute path to your application directory, including a trailing slash.

`constant` Cake\\Core\\**APP\_DIR**

Equals `app` or the name of your application directory.

`constant` Cake\\Core\\**CACHE**

Path to the cache files directory. It can be shared between hosts in a multi-server setup.

`constant` Cake\\Core\\**CAKE**

Path to the cake directory.

`constant` Cake\\Core\\**CAKE\_CORE\_INCLUDE\_PATH**

Path to the root lib directory.

`constant` Cake\\Core\\**CONFIG**

Path to the config directory.

`constant` Cake\\Core\\**CORE\_PATH**

Path to the CakePHP directory with ending directory slash.

`constant` Cake\\Core\\**DS**

Short for PHP's `DIRECTORY_SEPARATOR`, which is `/` on Linux and `\` on Windows.

`constant` Cake\\Core\\**LOGS**

Path to the logs directory.

`constant` Cake\\Core\\**RESOURCES**

Path to the resources directory.

`constant` Cake\\Core\\**ROOT**

Path to the root directory.

`constant` Cake\\Core\\**TESTS**

Path to the tests directory.

`constant` Cake\\Core\\**TMP**

Path to the temporary files directory.

`constant` Cake\\Core\\**WWW\_ROOT**

Full path to the webroot.

Timing Definition Constants [​](https://book.cakephp.org/6.x/core-libraries/global-constants-and-functions.html#timing-definition-constants)

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

`constant` Cake\\Core\\**TIME\_START**

Unix timestamp in microseconds as a float from when the application started.

---

# Flash | CakePHP

[Skip to content](https://book.cakephp.org/2.x/core-libraries/components/flash.html#VPContent)

Return to top

Flash [​](https://book.cakephp.org/2.x/core-libraries/components/flash.html#flash)

===================================================================================

`class` **FlashComponent**(ComponentCollection $collection, array $config = array())

FlashComponent provides a way to set one-time notification messages to be displayed after processing a form or acknowledging data. CakePHP refers to these messages as "flash messages". FlashComponent writes flash messages to `$_SESSION`, to be rendered in a View using [FlashHelper](https://book.cakephp.org/2.x/core-libraries/helpers/flash.html)
.

The FlashComponent replaces the `setFlash()` method on `SessionComponent` and should be used instead of that method.

Setting Flash Messages [​](https://book.cakephp.org/2.x/core-libraries/components/flash.html#setting-flash-messages)

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

FlashComponent provides two ways to set flash messages: its `__call` magic method and its `set()` method.

To use the default flash message handler, you can use the `set()` method:

    $this->Flash->set('This is a message');

1  

Added in version 2.10.0

Flash messages now stack. Successive calls to `set()` or `__call()` with the same key will append the messages in the `$_SESSION`. If you want to keep the old behavior (one message even after consecutive calls), set the `clear` option to true when setting messages.

To create custom Flash elements, FlashComponent's `__call` magic method allows you use a method name that maps to an element located under the `app/View/Elements/Flash` directory. By convention, camelcased methods will map to the lowercased and underscored element name:

    // Uses app/View/Elements/Flash/success.ctp
    $this->Flash->success('This was successful');
    
    // Uses app/View/Elements/Flash/great_success.ctp
    $this->Flash->greatSuccess('This was greatly successful');

1  
2  
3  
4  
5  

FlashComponent's `__call` and `set()` methods optionally take a second parameter, an array of options:

*   `key` Defaults to 'flash'. The array key found under the 'Flash' key in the session.
*   `element` Defaults to null, but will automatically be set when using the `__call()` magic method. The element name to use for rendering.
*   `params` An optional array of keys/values to make available as variables within an element.
*   `clear` Set to `true` to remove any existing flash messages of the given key/element. (Added in 2.10.0).

An example of using these options:

    // In your Controller
    $this->Flash->success('The user has been saved', array(
        'key' => 'positive',
        'params' => array(
            'name' => $user['User']['name'],
            'email' => $user['User']['email']
        )
    ));
    
    // In your View
    <?php echo $this->Flash->render('positive') ?>
    
    <!-- In app/View/Elements/Flash/success.ctp -->
    <div id="flash-<?php echo h($key) ?>" class="message-info success">
        <?php echo h($message) ?>: <?php echo h($params['name']) ?>, <?php echo h($params['email']) ?>.
    </div>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  

If you are using the `__call()` magic method, the `element` option will always be replaced. In order to retrieve a specific element from a plugin, you should set the `plugin` parameter. For example:

    // In your Controller
    $this->Flash->warning('My message', array('plugin' => 'PluginName'));

1  
2  

The code above will use the warning.ctp element under `plugins/PluginName/View/Elements/Flash` for rendering the flash message.

NOTE

By default, CakePHP does not escape the HTML in flash messages. If you are using any request or user data in your flash messages, you should escape it with `h` when formatting your messages.

For more information about rendering your flash messages, please refer to the [FlashHelper](https://book.cakephp.org/2.x/core-libraries/helpers/flash.html)
 section.

---

# Inflector | CakePHP

[Skip to content](https://book.cakephp.org/6.x/core-libraries/inflector.html#VPContent)

Return to top

Inflector [​](https://book.cakephp.org/6.x/core-libraries/inflector.html#inflector)

====================================================================================

`class` Cake\\Utility\\**Inflector**

The Inflector class takes a string and can manipulate it to handle word variations such as pluralization or camelizing and is normally accessed statically. Example: `Inflector::pluralize('example')` returns "examples".

You can try out the inflections online at [inflector.cakephp.org](https://inflector.cakephp.org/)
 or [sandbox.dereuromark.de](https://sandbox.dereuromark.de/sandbox/inflector)
.

Summary of Inflector Methods and Their Output [​](https://book.cakephp.org/6.x/core-libraries/inflector.html#summary-of-inflector-methods-and-their-output)

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

Quick summary of the Inflector built-in methods and the results they output when provided a multi-word argument:

| Method | Argument | Output |
| --- | --- | --- |
| `pluralize()` | BigApple | BigApples |
| big\_apple | big\_apples |
| `singularize()` | BigApples | BigApple |
| big\_apples | big\_apple |
| `camelize()` | big\_apples | BigApples |
| big apple | BigApple |
| `underscore()` | BigApples | big\_apples |
| Big Apples | big apples |
| `humanize()` | big\_apples | Big Apples |
| bigApple | BigApple |
| `classify()` | big\_apples | BigApple |
| big apple | BigApple |
| `dasherize()` | BigApples | big-apples |
| big apple | big apple |
| `tableize()` | BigApple | big\_apples |
| Big Apple | big apples |
| `variable()` | big\_apple | bigApple |
| big apples | bigApples |

Creating Plural & Singular Forms [​](https://book.cakephp.org/6.x/core-libraries/inflector.html#creating-plural-singular-forms)

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

### Inflector::singularize() [​](https://book.cakephp.org/6.x/core-libraries/inflector.html#inflector-singularize)

`static` Cake\\Utility\\Inflector::**singularize**($singular): string

### Inflector::pluralize() [​](https://book.cakephp.org/6.x/core-libraries/inflector.html#inflector-pluralize)

`static` Cake\\Utility\\Inflector::**pluralize**($singular): string

Both `pluralize` and `singularize()` work on most English nouns. If you need to support other languages, you can use [Inflection Configuration](https://book.cakephp.org/6.x/core-libraries/inflector.html#inflection-configuration)
 to customize the rules used:

    // Apples
    echo Inflector::pluralize('Apple');

1  
2  

NOTE

`pluralize()` should not be used on a noun that is already in its plural form.

    // Person
    echo Inflector::singularize('People');

1  
2  

NOTE

`singularize()` should not be used on a noun that is already in its singular form.

Creating CamelCase and under\_scored Forms [​](https://book.cakephp.org/6.x/core-libraries/inflector.html#creating-camelcase-and-under-scored-forms)

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

### Inflector::camelize() [​](https://book.cakephp.org/6.x/core-libraries/inflector.html#inflector-camelize)

`static` Cake\\Utility\\Inflector::**camelize**($underscored): string

### Inflector::underscore() [​](https://book.cakephp.org/6.x/core-libraries/inflector.html#inflector-underscore)

`static` Cake\\Utility\\Inflector::**underscore**($camelCase): string

These methods are useful when creating class names, or property names:

    // ApplePie
    Inflector::camelize('Apple_pie')
    
    // apple_pie
    Inflector::underscore('ApplePie');

1  
2  
3  
4  
5  

It should be noted that underscore will only convert camelCase formatted words. Words that contains spaces will be lower-cased, but will not contain an underscore.

Creating Human Readable Forms [​](https://book.cakephp.org/6.x/core-libraries/inflector.html#creating-human-readable-forms)

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

### Inflector::humanize() [​](https://book.cakephp.org/6.x/core-libraries/inflector.html#inflector-humanize)

`static` Cake\\Utility\\Inflector::**humanize**($underscored): string

This method is useful when converting underscored forms into "Title Case" forms for human readable values:

    // Apple Pie
    Inflector::humanize('apple_pie');

1  
2  

Creating Table and Class Name Forms [​](https://book.cakephp.org/6.x/core-libraries/inflector.html#creating-table-and-class-name-forms)

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

### Inflector::classify() [​](https://book.cakephp.org/6.x/core-libraries/inflector.html#inflector-classify)

`static` Cake\\Utility\\Inflector::**classify**($underscored): string

### Inflector::dasherize() [​](https://book.cakephp.org/6.x/core-libraries/inflector.html#inflector-dasherize)

`static` Cake\\Utility\\Inflector::**dasherize**($dashed): string

### Inflector::tableize() [​](https://book.cakephp.org/6.x/core-libraries/inflector.html#inflector-tableize)

`static` Cake\\Utility\\Inflector::**tableize**($camelCase): string

When generating code, or using CakePHP's conventions you may need to inflect table names or class names:

    // UserProfileSetting
    Inflector::classify('user_profile_settings');
    
    // user-profile-setting
    Inflector::dasherize('UserProfileSetting');
    
    // user_profile_settings
    Inflector::tableize('UserProfileSetting');

1  
2  
3  
4  
5  
6  
7  
8  

Creating Variable Names [​](https://book.cakephp.org/6.x/core-libraries/inflector.html#creating-variable-names)

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

### Inflector::variable() [​](https://book.cakephp.org/6.x/core-libraries/inflector.html#inflector-variable)

`static` Cake\\Utility\\Inflector::**variable**($underscored): string

Variable names are often useful when doing meta-programming tasks that involve generating code or doing work based on conventions:

    // applePie
    Inflector::variable('apple_pie');

1  
2  

Inflection Configuration [​](https://book.cakephp.org/6.x/core-libraries/inflector.html#inflection-configuration)

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

CakePHP's naming conventions can be really nice - you can name your database table `big_boxes`, your model `BigBoxes`, your controller `BigBoxesController`, and everything just works together automatically. The way CakePHP knows how to tie things together is by _inflecting_ the words between their singular and plural forms.

There are occasions (especially for our non-English speaking friends) where you may run into situations where CakePHP's inflector (the class that pluralizes, singularizes, camelCases, and under\_scores) might not work as you'd like. If CakePHP won't recognize your Foci or Fish, you can tell CakePHP about your special cases.

### Loading Custom Inflections [​](https://book.cakephp.org/6.x/core-libraries/inflector.html#loading-custom-inflections)

### Inflector::rules() [​](https://book.cakephp.org/6.x/core-libraries/inflector.html#inflector-rules)

`static` Cake\\Utility\\Inflector::**rules**($type, $rules, $reset = false): void

Define new inflection and transliteration rules for Inflector to use. Often, this method is used in your **config/bootstrap.php**:

    Inflector::rules('singular', ['/^(bil)er$/i' => '\1', '/^(inflec|contribu)tors$/i' => '\1ta']);
    Inflector::rules('uninflected', ['singulars']);
    Inflector::rules('irregular', ['phylum' => 'phyla']); // The key is singular form, value is plural form

1  
2  
3  

The supplied rules will be merged into the respective inflection sets defined in `Cake/Utility/Inflector`, with the added rules taking precedence over the core rules. You can use `Inflector::reset()` to clear rules and restore the original Inflector state.

---

# Cache Tool | CakePHP

[Skip to content](https://book.cakephp.org/6.x/console-commands/cache.html#VPContent)

Return to top

Cache Tool [​](https://book.cakephp.org/6.x/console-commands/cache.html#cache-tool)

====================================================================================

To help you better manage cached data from a CLI environment, a console command is available for clearing cached data your application has:

    // Clear one cache config
    bin/cake cache clear <configname>
    
    // Clear all cache configs
    bin/cake cache clear_all
    
    // Clear one cache group
    bin/cake cache clear_group <groupname>

1  
2  
3  
4  
5  
6  
7  
8

---

# Request Handling | CakePHP

[Skip to content](https://book.cakephp.org/2.x/core-libraries/components/request-handling.html#VPContent)

Return to top

Request Handling [​](https://book.cakephp.org/2.x/core-libraries/components/request-handling.html#request-handling)

====================================================================================================================

`class` **RequestHandlerComponent**(ComponentCollection $collection, array $settings = array())

The Request Handler component is used in CakePHP to obtain additional information about the HTTP requests that are made to your applications. You can use it to inform your controllers about AJAX as well as gain additional insight into content types that the client accepts and automatically changes to the appropriate layout when file extensions are enabled.

By default RequestHandler will automatically detect AJAX requests based on the HTTP-X-Requested-With header that many javascript libraries use. When used in conjunction with `Router::parseExtensions()` RequestHandler will automatically switch the layout and view files to those that match the requested type. Furthermore, if a helper with the same name as the requested extension exists, it will be added to the Controllers Helper array. Lastly, if XML/JSON data is POST'ed to your Controllers, it will be parsed into an array which is assigned to `$this->request->data`, and can then be saved as model data. In order to make use of RequestHandler it must be included in your $components array:

    class WidgetController extends AppController {
    
        public $components = array('RequestHandler');
    
        // Rest of controller
    }

1  
2  
3  
4  
5  
6  

Obtaining Request Information [​](https://book.cakephp.org/2.x/core-libraries/components/request-handling.html#obtaining-request-information)

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

Request Handler has several methods that provide information about the client and its request.

`method` RequestHandlerComponent::**accepts**($type = null)

Other request 'type' detection methods include:

`method` RequestHandlerComponent::**isXml**()

`method` RequestHandlerComponent::**isRss**()

`method` RequestHandlerComponent::**isAtom**()

`method` RequestHandlerComponent::**isMobile**()

`method` RequestHandlerComponent::**isWap**()

All of the above request detection methods can be used in a similar fashion to filter functionality intended for specific content types. For example when responding to AJAX requests, you often will want to disable browser caching, and change the debug level. However, you want to allow caching for non-AJAX requests. The following would accomplish that:

    if ($this->request->is('ajax')) {
        $this->disableCache();
    }
    // Continue Controller action

1  
2  
3  
4  

Obtaining Additional Client Information [​](https://book.cakephp.org/2.x/core-libraries/components/request-handling.html#obtaining-additional-client-information)

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

`method` RequestHandlerComponent::**getAjaxVersion**()

Automatically decoding request data [​](https://book.cakephp.org/2.x/core-libraries/components/request-handling.html#automatically-decoding-request-data)

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

`method` RequestHandlerComponent::**addInputType**($type, $handler)

Responding To Requests [​](https://book.cakephp.org/2.x/core-libraries/components/request-handling.html#responding-to-requests)

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

In addition to request detection RequestHandler also provides easy access to altering the output and content type mappings for your application.

`method` RequestHandlerComponent::**setContent**($name, $type = null)

`method` RequestHandlerComponent::**prefers**($type = null)

`method` RequestHandlerComponent::**renderAs**($controller, $type)

`method` RequestHandlerComponent::**respondAs**($type, $options)

`method` RequestHandlerComponent::**responseType**()

Taking advantage of HTTP cache validation [​](https://book.cakephp.org/2.x/core-libraries/components/request-handling.html#taking-advantage-of-http-cache-validation)

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

Added in version 2.1

The HTTP cache validation model is one of the processes used for cache gateways, also known as reverse proxies, to determine if they can serve a stored copy of a response to the client. Under this model, you mostly save bandwidth, but when used correctly you can also save some CPU processing, reducing this way response times.

Enabling the RequestHandlerComponent in your controller automatically activates a check done before rendering the view. This check compares the response object against the original request to determine whether the response was not modified since the last time the client asked for it.

If response is evaluated as not modified, then the view rendering process is stopped, saving processing time, saving bandwidth and no content is returned to the client. The response status code is then set to 304 Not Modified.

You can opt-out this automatic checking by setting the `checkHttpCache` setting to false:

    public $components = array(
        'RequestHandler' => array(
            'checkHttpCache' => false
    ));

1  
2  
3  
4  

Using custom ViewClasses [​](https://book.cakephp.org/2.x/core-libraries/components/request-handling.html#using-custom-viewclasses)

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

Added in version 2.3

When using JsonView/XmlView you might want to override the default serialization with a custom View class, or add View classes for other types.

You can map existing and new types to your custom classes.

`method` RequestHandlerComponent::**viewClassMap**($type, $viewClass)

You can also set this automatically by using the `viewClassMap` setting:

    public $components = array(
        'RequestHandler' => array(
            'viewClassMap' => array(
                'json' => 'ApiKit.MyJson',
                'xml' => 'ApiKit.MyXml',
                'csv' => 'ApiKit.Csv'
            )
    ));

1  
2  
3  
4  
5  
6  
7  
8

---

# FlashHelper | CakePHP

[Skip to content](https://book.cakephp.org/2.x/core-libraries/helpers/flash.html#VPContent)

Return to top

FlashHelper [​](https://book.cakephp.org/2.x/core-libraries/helpers/flash.html#flashhelper)

============================================================================================

`class` **FlashHelper**(View $view, array $config = array())

Added in version 2.7.0

in replacement of `SessionHelper::flash()`

FlashHelper provides a way to render flash messages that were set in `$_SESSION` by [FlashComponent](https://book.cakephp.org/2.x/core-libraries/components/flash.html)
. [FlashComponent](https://book.cakephp.org/2.x/core-libraries/components/flash.html)
 and FlashHelper primarily use elements to render flash messages. Flash elements are found under the `app/View/Elements/Flash` directory. You'll notice that CakePHP's App template comes with two flash elements: `success.ctp` and `error.ctp`.

The FlashHelper replaces the `flash()` method on `SessionHelper` and should be used instead of that method.

Rendering Flash Messages [​](https://book.cakephp.org/2.x/core-libraries/helpers/flash.html#rendering-flash-messages)

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

To render a flash message, you can simply use FlashHelper's `render()` method:

    <?php echo $this->Flash->render() ?>

1  

By default, CakePHP uses a "flash" key for flash messages in a session. But, if you've specified a key when setting the flash message in [FlashComponent](https://book.cakephp.org/2.x/core-libraries/components/flash.html)
, you can specify which flash key to render:

    <?php echo $this->Flash->render('other') ?>

1  

You can also override any of the options that were set in FlashComponent:

    // In your Controller
    $this->Flash->set('The user has been saved.', array(
        'element' => 'success'
    ));
    
    // In your View: Will use great_success.ctp instead of success.ctp
    <?php echo $this->Flash->render('flash', array(
        'element' => 'great_success'
    ));

1  
2  
3  
4  
5  
6  
7  
8  
9  

NOTE

By default, CakePHP does not escape the HTML in flash messages. If you are using any request or user data in your flash messages, you should escape it with `h` when formatting your messages.

Added in version 2.10.0

[Flash](https://book.cakephp.org/2.x/core-libraries/components/flash.html)
 stacks messages as of 2.10.0. If you set multiple flash messages, when you call `render()`, each message will be rendered in its own element, in the order the messages were set.

For more information about the available array options, please refer to the [FlashComponent](https://book.cakephp.org/2.x/core-libraries/components/flash.html)
 section.

---

# TextHelper | CakePHP

[Skip to content](https://book.cakephp.org/2.x/core-libraries/helpers/text.html#VPContent)

Return to top

TextHelper [​](https://book.cakephp.org/2.x/core-libraries/helpers/text.html#texthelper)

=========================================================================================

`class` **TextHelper**(View $view, array $settings = array())

The TextHelper contains methods to make text more usable and friendly in your views. It aids in enabling links, formatting URLs, creating excerpts of text around chosen words or phrases, highlighting key words in blocks of text, and gracefully truncating long stretches of text.

Changed in version 2.1

Several `TextHelper` methods have been moved into the `String` class to allow easier use outside of the `View` layer. Within a view, these methods are accessible via the TextHelper class. You can call one as you would call a normal helper method: `$this->Text->method($args);`.

`method` TextHelper::**autoLinkEmails**(string $text, array $options=array())

`method` TextHelper::**autoLinkUrls**(string $text, array $options=array())

`method` TextHelper::**autoLink**(string $text, array $options=array())

`method` TextHelper::**autoParagraph**(string $text)

`method` CakeText::**highlight**(string $haystack, string $needle, array $options = array() )

`method` CakeText::**stripLinks**($text)

`method` CakeText::**truncate**(string $text, int $length=100, array $options)

Changed in version 2.3

`ending` has been replaced by `ellipsis`. `ending` is still used in 2.2.1

`method` CakeText::**tail**(string $text, int $length=100, array $options)

`method` CakeText::**excerpt**(string $haystack, string $needle, integer $radius=100, string $ellipsis="...")

`method` CakeText::**toList**(array $list, $and='and')

---

# HtmlHelper | CakePHP

[Skip to content](https://book.cakephp.org/2.x/core-libraries/helpers/html.html#VPContent)

Return to top

HtmlHelper [​](https://book.cakephp.org/2.x/core-libraries/helpers/html.html#htmlhelper)

=========================================================================================

`class` **HtmlHelper**(View $view, array $settings = array())

The role of the HtmlHelper in CakePHP is to make HTML-related options easier, faster, and more resilient to change. Using this helper will enable your application to be more light on its feet, and more flexible on where it is placed in relation to the root of a domain.

Many HtmlHelper methods include a `$options` parameter, that allow you to tack on any extra attributes on your tags. Here are a few examples of how to use the $options parameter:

    Desired attributes: <tag class="someClass" />
    Array parameter: array('class' => 'someClass')
    
    Desired attributes: <tag name="foo" value="bar" />
    Array parameter:  array('name' => 'foo', 'value' => 'bar')

1  
2  
3  
4  
5  

NOTE

The HtmlHelper is available in all views by default. If you're getting an error informing you that it isn't there, it's usually due to its name being missing from a manually configured $helpers controller variable.

Inserting Well-Formatted elements [​](https://book.cakephp.org/2.x/core-libraries/helpers/html.html#inserting-well-formatted-elements)

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

The most important task the HtmlHelper accomplishes is creating well formed markup. Don't be afraid to use it often - you can cache views in CakePHP in order to save some CPU cycles when views are being rendered and delivered. This section will cover some of the methods of the HtmlHelper and how to use them.

`method` HtmlHelper::**charset**($charset=null)

`method` HtmlHelper::**css**(mixed $path, array $options = array())

`method` HtmlHelper::**meta**(string $type, string $url = null, array $options = array())

`method` HtmlHelper::**docType**(string $type = 'xhtml-strict')

`method` HtmlHelper::**style**(array $data, boolean $oneline = true)

`method` HtmlHelper::**image**(string $path, array $options = array())

`method` HtmlHelper::**link**(string $title, mixed $url = null, array $options = array())

`method` HtmlHelper::**media**(string|array $path, array $options)

`method` HtmlHelper::**tag**(string $tag, string $text, array $options)

`method` HtmlHelper::**div**(string $class, string $text, array $options)

`method` HtmlHelper:😗\* para(string $class, string $text, array $options)\*\*()

`method` HtmlHelper::**script**(mixed $url, mixed $options)

`method` HtmlHelper:😗\* scriptBlock($code, $options = array())\*\*()

`method` HtmlHelper::**scriptStart**($options = array())

`method` HtmlHelper::**scriptEnd**()

`method` HtmlHelper::**nestedList**(array $list, array $options = array(), array $itemOptions = array(), string $tag = 'ul')

`method` HtmlHelper::**tableHeaders**(array $names, array $trOptions = null, array $thOptions = null)

`method` HtmlHelper::**tableCells**(array $data, array $oddTrOptions = null, array $evenTrOptions = null, $useCount = false, $continueOddEven = true)

`method` HtmlHelper::**url**(mixed $url = NULL, boolean $full = false)

`method` HtmlHelper::**useTag**(string $tag)

Changing the tags output by HtmlHelper [​](https://book.cakephp.org/2.x/core-libraries/helpers/html.html#changing-the-tags-output-by-htmlhelper)

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

`method` HtmlHelper::**loadConfig**(mixed $configFile, string $path = null)

Creating breadcrumb trails with HtmlHelper [​](https://book.cakephp.org/2.x/core-libraries/helpers/html.html#creating-breadcrumb-trails-with-htmlhelper)

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

`method` HtmlHelper::**getCrumbs**(string $separator = '»', string|array|bool $startText = false)

`method` HtmlHelper::**addCrumb**(string $name, string $link = null, mixed $options = null)

`method` HtmlHelper::**getCrumbList**(array $options = array(), mixed $startText)

---

# Sessions | CakePHP

[Skip to content](https://book.cakephp.org/2.x/core-libraries/components/sessions.html#VPContent)

Return to top

Sessions [​](https://book.cakephp.org/2.x/core-libraries/components/sessions.html#sessions)

============================================================================================

`class` **SessionComponent**(ComponentCollection $collection, array $settings = array())

The CakePHP SessionComponent provides a way to persist client data between page requests. It acts as a wrapper for `$_SESSION` as well as providing convenience methods for several `$_SESSION` related functions.

Sessions can be configured in a number of ways in CakePHP. For more information, you should see the [Session configuration](https://book.cakephp.org/2.x/development/sessions.html)
 documentation.

Interacting with Session data [​](https://book.cakephp.org/2.x/core-libraries/components/sessions.html#interacting-with-session-data)

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

The Session component is used to interact with session information. It includes basic CRUD functions as well as features for creating feedback messages to users.

It should be noted that Array structures can be created in the Session by using `dot notation`. So `User.username` would reference the following:

    array('User' => array(
        'username' => '[email protected]'
    ));

1  
2  
3  

Dots are used to indicate nested arrays. This notation is used for all Session component methods wherever a name/key is used.

`method` SessionComponent::**write**($name, $value)

`method` SessionComponent::**read**($name)

`method` SessionComponent::**consume**($name)

`method` SessionComponent::**check**($name)

`method` SessionComponent::**delete**($name)

`method` SessionComponent::**destroy**()

Creating notification messages [​](https://book.cakephp.org/2.x/core-libraries/components/sessions.html#creating-notification-messages)

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

`method` SessionComponent::**setFlash**(string $message, string $element = 'default', array $params = array(), string $key = 'flash')

---

# SessionHelper | CakePHP

[Skip to content](https://book.cakephp.org/2.x/core-libraries/helpers/session.html#VPContent)

Return to top

SessionHelper [​](https://book.cakephp.org/2.x/core-libraries/helpers/session.html#sessionhelper)

==================================================================================================

`class` **SessionHelper**(View $view, array $settings = array())

As a natural counterpart to the Session Component, the Session Helper replicates most of the component's functionality and makes it available in your view.

The major difference between the Session Helper and the Session Component is that the helper does _not_ have the ability to write to the session.

As with the Session Component, data is read by using `dot notation` array structures:

    array('User' => array(
        'username' => '[email protected]'
    ));

1  
2  
3  

Given the previous array structure, the node would be accessed by `User.username`, with the dot indicating the nested array. This notation is used for all Session helper methods wherever a `$key` is used.

`method` SessionHelper::**read**(string $key)

`method` SessionHelper::**consume**($name)

`method` SessionHelper::**check**(string $key)

`method` SessionHelper::**error**()

`method` SessionHelper::**valid**()

Displaying notifications or flash messages [​](https://book.cakephp.org/2.x/core-libraries/helpers/session.html#displaying-notifications-or-flash-messages)

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

`method` SessionHelper::**flash**(string $key = 'flash', array $params = array())

---

# Filesystem | CakePHP

[Skip to content](https://book.cakephp.org/6.x/core-libraries/filesystem.html#VPContent)

Return to top

Filesystem [​](https://book.cakephp.org/6.x/core-libraries/filesystem.html#filesystem)

=======================================================================================

CakePHP provides filesystem utilities for working with files and directories efficiently. These utilities are split into two main classes:

*   **Finder** - A fluent, iterator-based API for discovering files and directories
*   **Path** - Static utilities for path manipulation

Finder [​](https://book.cakephp.org/6.x/core-libraries/filesystem.html#finder)

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

`class` Cake\\Utility\\Fs\\**Finder**

The `Finder` class provides a lazy, iterator-based approach to discovering files and directories with a fluent interface for building complex queries. It's memory-efficient and works consistently across different operating systems.

### Available Methods [​](https://book.cakephp.org/6.x/core-libraries/filesystem.html#available-methods)

#### Location & Type [​](https://book.cakephp.org/6.x/core-libraries/filesystem.html#location-type)

`method` Cake\\Utility\\Fs\\Finder::**in**(string $directory)

`method` Cake\\Utility\\Fs\\Finder::**files**()

`method` Cake\\Utility\\Fs\\Finder::**directories**()

`method` Cake\\Utility\\Fs\\Finder::**all**()

`method` Cake\\Utility\\Fs\\Finder::**recursive**(bool $recursive = true)

#### Filtering by Name [​](https://book.cakephp.org/6.x/core-libraries/filesystem.html#filtering-by-name)

`method` Cake\\Utility\\Fs\\Finder::**name**(string $pattern)

`method` Cake\\Utility\\Fs\\Finder::**notName**(string $pattern)

#### Filtering by Path [​](https://book.cakephp.org/6.x/core-libraries/filesystem.html#filtering-by-path)

`method` Cake\\Utility\\Fs\\Finder::**path**(string $pattern)

`method` Cake\\Utility\\Fs\\Finder::**notPath**(string $pattern)

`method` Cake\\Utility\\Fs\\Finder::**pattern**(string $globPattern)

`method` Cake\\Utility\\Fs\\Finder::**exclude**(string $directory)

#### Depth Control [​](https://book.cakephp.org/6.x/core-libraries/filesystem.html#depth-control)

`method` Cake\\Utility\\Fs\\Finder::**depth**(int $depth, DepthOperator $operator = DepthOperator::EQUAL)

#### Custom Filtering [​](https://book.cakephp.org/6.x/core-libraries/filesystem.html#custom-filtering)

`method` Cake\\Utility\\Fs\\Finder::**filter**(callable $callback)

`method` Cake\\Utility\\Fs\\Finder::**ignoreHiddenFiles**()

### Basic Usage [​](https://book.cakephp.org/6.x/core-libraries/filesystem.html#basic-usage)

#### Finding Files and Directories [​](https://book.cakephp.org/6.x/core-libraries/filesystem.html#finding-files-and-directories)

Find all PHP files in a directory:

    use Cake\Utility\Fs\Finder;
    
    $finder = (new Finder())
        ->in('src')
        ->name('*.php')
        ->files();
    
    foreach ($files as $file) {
        echo $file->getPathname();
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

Find directories while excluding certain ones:

    $directories = (new Finder())
        ->in('src')
        ->exclude('vendor')
        ->exclude('tmp')
        ->directories();

1  
2  
3  
4  
5  

By default, the Finder searches recursively. Use `recursive(false)` for top-level only:

    $finder = (new Finder())
        ->in('src')
        ->recursive(false)
        ->files();

1  
2  
3  
4  

### Filtering Examples [​](https://book.cakephp.org/6.x/core-libraries/filesystem.html#filtering-examples)

#### By Filename Pattern [​](https://book.cakephp.org/6.x/core-libraries/filesystem.html#by-filename-pattern)

Include and exclude specific filename patterns:

    $finder = (new Finder())
        ->in('src')
        ->name('*.php')              // Include all PHP files
        ->notName('*Test.php')       // Exclude test files
        ->notName('*Fixture.php')    // Exclude fixtures
        ->files();

1  
2  
3  
4  
5  
6  

#### By Path Pattern [​](https://book.cakephp.org/6.x/core-libraries/filesystem.html#by-path-pattern)

Filter by path containing specific strings or regex patterns:

    $finder = (new Finder())
        ->in('src')
        ->path('Controller')                    // Include paths containing "Controller"
        ->notPath('Test')                       // Exclude paths containing "Test"
        ->path('/Controller\.php$/')            // Or use regex patterns
        ->files();

1  
2  
3  
4  
5  
6  

#### By Depth [​](https://book.cakephp.org/6.x/core-libraries/filesystem.html#by-depth)

Control traversal depth using type-safe operators:

    use Cake\Utility\Fs\Enum\DepthOperator;
    
    // Maximum depth of 3
    $finder = (new Finder())
        ->in('src')
        ->depth(3, DepthOperator::LESS_THAN)
        ->files();
    
    // Depth range (1, 2, or 3)
    $finder = (new Finder())
        ->in('src')
        ->depth(0, DepthOperator::GREATER_THAN)
        ->depth(4, DepthOperator::LESS_THAN)
        ->files();

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

Available depth operators: `EQUAL`, `NOT_EQUAL`, `LESS_THAN`, `GREATER_THAN`, `LESS_THAN_OR_EQUAL`, `GREATER_THAN_OR_EQUAL`.

#### Using Glob Patterns [​](https://book.cakephp.org/6.x/core-libraries/filesystem.html#using-glob-patterns)

Use glob patterns with `**` for recursive matching:

    $finder = (new Finder())
        ->in('.')
        ->pattern('src/**/*Controller.php')
        ->pattern('tests/**/*Test.php')
        ->files();

1  
2  
3  
4  
5  

Glob syntax: `*` matches any characters except `/`, `**` matches including `/`, `?` matches single character, `[abc]` matches any character in set.

#### Custom Filters [​](https://book.cakephp.org/6.x/core-libraries/filesystem.html#custom-filters)

For complex filtering, use custom callbacks:

    use SplFileInfo;
    
    $finder = (new Finder())
        ->in('src')
        ->filter(fn(SplFileInfo $file) => $file->getSize() > 1024)
        ->filter(fn(SplFileInfo $file) => $file->getMTime() > strtotime('-1 week'))
        ->files();

1  
2  
3  
4  
5  
6  
7  

The callback receives `SplFileInfo` and the relative path:

    $finder = (new Finder())
        ->in('.')
        ->filter(function (SplFileInfo $file, string $relativePath) {
            return str_starts_with($relativePath, 'src/Controller')
                || str_starts_with($relativePath, 'src/Model');
        })
        ->files();

1  
2  
3  
4  
5  
6  
7  

### Complete Example [​](https://book.cakephp.org/6.x/core-libraries/filesystem.html#complete-example)

Combining multiple filters:

    use Cake\Utility\Fs\Finder;
    use Cake\Utility\Fs\Enum\DepthOperator;
    
    $finder = (new Finder())
        ->in('src')
        ->in('plugins')
        ->name('*.php')
        ->notName('*Test.php')
        ->exclude('vendor')
        ->exclude('tmp')
        ->path('Controller')
        ->depth(5, DepthOperator::LESS_THAN)
        ->ignoreHiddenFiles()
        ->files();
    
    foreach ($finder as $file) {
        echo $file->getRealPath() . PHP_EOL;
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

Path [​](https://book.cakephp.org/6.x/core-libraries/filesystem.html#path)

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

`class` Cake\\Utility\\Fs\\**Path**

The `Path` class provides static utilities for path manipulation.

### Available Methods [​](https://book.cakephp.org/6.x/core-libraries/filesystem.html#available-methods-1)

`static` Cake\\Utility\\Fs\\Path::**normalize**(string $path)

Convert paths to use forward slashes.

`static` Cake\\Utility\\Fs\\Path::**makeRelative**(string $path, string $base)

Convert an absolute path to a relative path based on a base directory.

`static` Cake\\Utility\\Fs\\Path::**join**(string ...$segments)

Join multiple path segments into a single path.

`static` Cake\\Utility\\Fs\\Path::**matches**(string $pattern, string $path)

Test if a path matches a glob pattern. Supports `*`, `**`, `?`, and `[abc]` syntax.

### Examples [​](https://book.cakephp.org/6.x/core-libraries/filesystem.html#examples)

    use Cake\Utility\Fs\Path;
    
    // Normalize path separators
    Path::normalize('path\\to\\file.php');
    // Returns: 'path/to/file.php'
    
    // Make relative paths
    Path::makeRelative('/var/www/app/src/Controller/UsersController.php', '/var/www/app');
    // Returns: 'src/Controller/UsersController.php'
    
    // Join path segments
    Path::join('src', 'Controller', 'UsersController.php');
    // Returns: 'src/Controller/UsersController.php'
    
    // Match glob patterns
    Path::matches('*.php', 'test.php');                                      // true
    Path::matches('src/**/*.php', 'src/Controller/UsersController.php');    // true
    Path::matches('src/**/Test/*.php', 'src/Controller/UsersController.php'); // false

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18

---

# Tree | CakePHP

[Skip to content](https://book.cakephp.org/6.x/orm/behaviors/tree.html#VPContent)

Return to top

Tree [​](https://book.cakephp.org/6.x/orm/behaviors/tree.html#tree)

====================================================================

`class` Cake\\ORM\\Behavior\\**TreeBehavior**

It's fairly common to want to store hierarchical data in a database table. Examples of such data might be categories with unlimited subcategories, data related to a multilevel menu system or a literal representation of hierarchy such as departments in a company.

Relational databases are usually not well suited for storing and retrieving this type of data, but there are a few known techniques that can make them effective for working with multi-level information.

The TreeBehavior helps you maintain a hierarchical data structure in the database that can be queried without much overhead and helps reconstruct the tree data for finding and displaying processes.

Requirements [​](https://book.cakephp.org/6.x/orm/behaviors/tree.html#requirements)

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

This behavior requires the following columns in your table:

*   `parent_id` (nullable) The column holding the ID of the parent row. This column should be indexed.
*   `lft` (integer, signed) Used to maintain the tree structure. This column should be indexed.
*   `rght` (integer, signed) Used to maintain the tree structure.

You can configure the name of those fields should you need to customize them. More information on the meaning of the fields and how they are used can be found in this article describing the [MPTT logic](https://www.sitepoint.com/hierarchical-data-database-2/)

WARNING

The TreeBehavior is not safe for concurrent write operations. Simultaneous requests that modify tree-structured data (e.g., insertions, deletions, or moves) can lead to corruption of the `lft` and `rght` values.

To prevent this, a locking mechanism like a [Semaphore](https://www.php.net/manual/en/book.sem.php)
 should be used.

WARNING

The TreeBehavior does not support composite primary keys at this point in time.

A Quick Tour [​](https://book.cakephp.org/6.x/orm/behaviors/tree.html#a-quick-tour)

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

You enable the Tree behavior by adding it to the Table you want to store hierarchical data in:

    class CategoriesTable extends Table
    {
        public function initialize(array $config): void
        {
            $this->addBehavior('Tree');
        }
    }

1  
2  
3  
4  
5  
6  
7  

Once added, you can let CakePHP build the internal structure if the table is already holding some rows:

    // In a controller
    $categories = $this->getTableLocator()->get('Categories');
    $categories->recover();

1  
2  
3  

You can verify it works by getting any row from the table and asking for the count of descendants it has:

    $node = $categories->get(1);
    echo $categories->getBehavior('Tree')->childCount($node);

1  
2  

### Getting direct descendents [​](https://book.cakephp.org/6.x/orm/behaviors/tree.html#getting-direct-descendents)

Getting a flat list of the descendants for a node can be done with:

    $descendants = $categories->find('children', for: 1);
    
    foreach ($descendants as $category) {
        echo $category->name . "\n";
    }

1  
2  
3  
4  
5  

If you need to pass conditions you do so as per normal:

    $descendants = $categories
        ->find('children', for: 1)
        ->where(['name LIKE' => '%Foo%'])
        ->all();
    
    foreach ($descendants as $category) {
        echo $category->name . "\n";
    }

1  
2  
3  
4  
5  
6  
7  
8  

If you instead need a threaded list, where children for each node are nested in a hierarchy, you can stack the 'threaded' finder:

    $children = $categories
        ->find('children', for: 1)
        ->find('threaded')
        ->toArray();
    
    foreach ($children as $child) {
        echo "{$child->name} has " . count($child->children) . " direct children";
    }

1  
2  
3  
4  
5  
6  
7  
8  

While, if you're using custom `parent_id` you need to pass it in the 'threaded' finder option (i.e. `parentField`) .

NOTE

For more information on 'threaded' finder options see [Finding Threaded Data logic](https://book.cakephp.org/6.x/orm/retrieving-data-and-resultsets.html#finding-threaded-data)

### Getting formatted tree lists [​](https://book.cakephp.org/6.x/orm/behaviors/tree.html#getting-formatted-tree-lists)

Traversing threaded results usually requires recursive functions in, but if you only require a result set containing a single field from each level so you can display a list, in an HTML select for example, it is better to use the `treeList` finder:

    $list = $categories->find('treeList')->toArray();
    
    // In a CakePHP template file:
    echo $this->Form->control('categories', ['options' => $list]);
    
    // Or you can output it in plain text, for example in a CLI script
    foreach ($list as $categoryName) {
        echo $categoryName . "\n";
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  

The output will be similar to:

    My Categories
    _Fun
    __Sport
    ___Surfing
    ___Skating
    _Trips
    __National
    __International
    

The `treeList` finder takes a number of options:

*   `keyPath`: A dot separated path to fetch the field to use for the array key, or a closure to return the key out of the provided row.
*   `valuePath`: A dot separated path to fetch the field to use for the array value, or a closure to return the value out of the provided row.
*   `spacer`: A string to be used as prefix for denoting the depth in the tree for each item

An example of all options in use is:

    $query = $categories->find('treeList',
        keyPath: 'url',
        valuePath: 'id',
        spacer: ' '
    );

1  
2  
3  
4  
5  

An example using closure:

    $query = $categories->find('treeList',
        valuePath: function($entity){
            return $entity->url . ' ' . $entity->id
        }
    );

1  
2  
3  
4  
5  

### Finding a path or branch in the tree [​](https://book.cakephp.org/6.x/orm/behaviors/tree.html#finding-a-path-or-branch-in-the-tree)

One very common task is to find the tree path from a particular node to the root of the tree. This is useful, for example, for adding the breadcrumbs list for a menu structure:

    $nodeId = 5;
    $crumbs = $categories->find('path', for: $nodeId)->all();
    
    foreach ($crumbs as $crumb) {
        echo $crumb->name . ' > ';
    }

1  
2  
3  
4  
5  
6  

Trees constructed with the TreeBehavior cannot be sorted by any column other than `lft`, this is because the internal representation of the tree depends on this sorting. Luckily, you can reorder the nodes inside the same level without having to change their parent:

    $node = $categories->get(5);
    
    // Move the node so it shows up one position up when listing children.
    $categories->getBehavior('Tree')->moveUp($node);
    
    // Move the node to the top of the list inside the same level.
    $categories->getBehavior('Tree')->moveUp($node, true);
    
    // Move the node to the bottom.
    $categories->getBehavior('Tree')->moveDown($node, true);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

Configuration [​](https://book.cakephp.org/6.x/orm/behaviors/tree.html#configuration)

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

If the default column names that are used by this behavior don't match your own schema, you can provide aliases for them:

    public function initialize(array $config): void
    {
        $this->addBehavior('Tree', [\
            'parent' => 'ancestor_id', // Use this instead of parent_id\
            'left' => 'tree_left', // Use this instead of lft\
            'right' => 'tree_right' // Use this instead of rght\
        ]);
    }

1  
2  
3  
4  
5  
6  
7  
8  

### Node Level (Depth) [​](https://book.cakephp.org/6.x/orm/behaviors/tree.html#node-level-depth)

Knowing the depth of tree nodes can be useful when you want to retrieve nodes only up to a certain level, for example, when generating menus. You can use the `level` option to specify the field that will save level of each node:

    $this->addBehavior('Tree', [\
        'level' => 'level', // Defaults to null, i.e. no level saving\
    ]);

1  
2  
3  

If you don't want to cache the level using a db field you can use `TreeBehavior::getLevel()` method to get level of a node.

### Scoping and Multi Trees [​](https://book.cakephp.org/6.x/orm/behaviors/tree.html#scoping-and-multi-trees)

Sometimes you want to persist more than one tree structure inside the same table, you can achieve that by using the 'scope' configuration. For example, in a locations table you may want to create one tree per country:

    class LocationsTable extends Table
    {
        public function initialize(array $config): void
        {
            $this->addBehavior('Tree', [\
                'scope' => ['country_name' => 'Brazil']\
            ]);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  

In the previous example, all tree operations will be scoped to only the rows having the column `country_name` set to 'Brazil'. You can change the scoping on the fly by using the 'config' function:

    $this->getBehavior('Tree')->setConfig('scope', ['country_name' => 'France']);

1  

Optionally, you can have a finer grain control of the scope by passing a closure as the scope:

    $this->getBehavior('Tree')->setConfig('scope', function ($query) {
        $country = $this->getConfigureContry(); // A made-up function
        return $query->where(['country_name' => $country]);
    });

1  
2  
3  
4  

### Deletion Behavior [​](https://book.cakephp.org/6.x/orm/behaviors/tree.html#deletion-behavior)

By enabling the `cascadeCallbacks` option, `TreeBehavior` will load all of the entities that are going to be deleted. Once loaded, these entities will be deleted individually using `Table::delete()`. This enables ORM callbacks to be fired when tree nodes are deleted:

    $this->addBehavior('Tree', [\
        'cascadeCallbacks' => true,\
    ]);

1  
2  
3  

Recovering with custom sort field [​](https://book.cakephp.org/6.x/orm/behaviors/tree.html#recovering-with-custom-sort-field)

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

By default, `recover()` sorts the items using the primary key. This works great if this is a numeric (auto increment) column, but can lead to weird results if you use UUIDs.

If you need custom sorting for the recovery, you can set a custom order clause in your config:

    $this->addBehavior('Tree', [\
        'recoverOrder' => ['country_name' => 'DESC'],\
    ]);

1  
2  
3  

Saving Hierarchical Data [​](https://book.cakephp.org/6.x/orm/behaviors/tree.html#saving-hierarchical-data)

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

When using the Tree behavior, you usually don't need to worry about the internal representation of the hierarchical structure. The positions where nodes are placed in the tree are deduced from the `parent_id` column in each of your entities:

    $aCategory = $categoriesTable->get(10);
    $aCategory->parent_id = 5;
    $categoriesTable->save($aCategory);

1  
2  
3  

Providing inexistent parent ids when saving or attempting to create a loop in the tree (making a node child of itself) will throw an exception.

You can make a node into a root in the tree by setting the `parent_id` column to null:

    $aCategory = $categoriesTable->get(10);
    $aCategory->parent_id = null;
    $categoriesTable->save($aCategory);

1  
2  
3  

Children for the new root node will be preserved.

Deleting Nodes [​](https://book.cakephp.org/6.x/orm/behaviors/tree.html#deleting-nodes)

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

Deleting a node and all its sub-tree (any children it may have at any depth in the tree) is trivial:

    $aCategory = $categoriesTable->get(10);
    $categoriesTable->delete($aCategory);

1  
2  

The TreeBehavior will take care of all internal deleting operations for you. It is also possible to only delete one node and re-assign all children to the immediately superior parent node in the tree:

    $aCategory = $categoriesTable->get(10);
    $categoriesTable->getBehavior('Tree')->removeFromTree($aCategory);
    $categoriesTable->delete($aCategory);

1  
2  
3  

All children nodes will be kept and a new parent will be assigned to them.

The deletion of a node is based off of the `lft` and `rght` values of the entity. This is important to note when looping through the various children of a node for conditional deletes:

    $descendants = $teams->find('children', for: 1)->all();
    
    foreach ($descendants as $descendant) {
        $team = $teams->get($descendant->id); // search for the up-to-date entity object
        if ($team->expired) {
            $teams->delete($team); // deletion reorders the lft and rght of database entries
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  

TreeBehavior will reorder the `lft` and `rght` values of records in the table when a node is deleted.

In our example above, the `lft` and `rght` values of the entities inside `$descendants` will be inaccurate. You will need to reload existing entity objects if you need an accurate shape of the tree.

---

# Xml | CakePHP

[Skip to content](https://book.cakephp.org/6.x/core-libraries/xml.html#VPContent)

Return to top

Xml [​](https://book.cakephp.org/6.x/core-libraries/xml.html#xml)

==================================================================

`class` Cake\\Utility\\**Xml**

The Xml class allows you to transform arrays into SimpleXMLElement or DOMDocument objects, and back into arrays again.

Loading XML documents [​](https://book.cakephp.org/6.x/core-libraries/xml.html#loading-xml-documents)

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

### Xml::build() [​](https://book.cakephp.org/6.x/core-libraries/xml.html#xml-build)

`static` Cake\\Utility\\Xml::**build**($input, array $options = \[\]): SimpleXMLElement|DOMDocument

You can load XML-ish data using `Xml::build()`. Depending on your `$options` parameter, this method will return a SimpleXMLElement (default) or DOMDocument object. You can use `Xml::build()` to build XML objects from a variety of sources. For example, you can load XML from strings:

    $text = '<?xml version="1.0" encoding="utf-8"?>
    <post>
        <id>1</id>
        <title>Best post</title>
        <body> ... </body>
    </post>';
    $xml = Xml::build($text);

1  
2  
3  
4  
5  
6  
7  

You can also build Xml objects from local files by overriding the default option:

    // Local file
    $xml = Xml::build('/home/awesome/unicorns.xml', ['readFile' => true]);

1  
2  

You can also build Xml objects using an array:

    $data = [\
        'post' => [\
            'id' => 1,\
            'title' => 'Best post',\
            'body' => ' ... ',\
        ]\
    ];
    $xml = Xml::build($data);

1  
2  
3  
4  
5  
6  
7  
8  

If your input is invalid, the Xml class will throw an exception:

    $xmlString = 'What is XML?';
    try {
        $xmlObject = Xml::build($xmlString); // Here will throw an exception
    } catch (\Cake\Utility\Exception\XmlException $e) {
        throw new InternalErrorException();
    }

1  
2  
3  
4  
5  
6  

NOTE

[DOMDocument](https://php.net/domdocument)
 and [SimpleXML](https://php.net/simplexml)
 implement different APIs. Be sure to use the correct methods on the object you request from Xml.

Loading HTML documents [​](https://book.cakephp.org/6.x/core-libraries/xml.html#loading-html-documents)

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

HTML documents can be parsed into `SimpleXmlElement` or `DOMDocument` objects with `loadHtml()`:

    $html = Xml::loadHtml($htmlString, ['return' => 'domdocument']);

1  

By default entity loading and huge document parsing are disabled. These modes can be enabled with the `loadEntities` and `parseHuge` options respectively.

Transforming a XML String in Array [​](https://book.cakephp.org/6.x/core-libraries/xml.html#transforming-a-xml-string-in-array)

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

### Xml::toArray() [​](https://book.cakephp.org/6.x/core-libraries/xml.html#xml-toarray)

`static` Cake\\Utility\\Xml::**toArray**($obj): array

Converting XML strings into arrays is simple with the Xml class as well. By default you'll get a SimpleXml object back:

    $xmlString = '<?xml version="1.0"?><root><child>value</child></root>';
    $xmlArray = Xml::toArray(Xml::build($xmlString));

1  
2  

If your XML is invalid a `Cake\Utility\Exception\XmlException` will be raised.

Transforming an Array into a String of XML [​](https://book.cakephp.org/6.x/core-libraries/xml.html#transforming-an-array-into-a-string-of-xml)

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

    $xmlArray = ['root' => ['child' => 'value']];
    // You can use Xml::build() too.
    $xmlObject = Xml::fromArray($xmlArray, ['format' => 'tags']);
    $xmlString = $xmlObject->asXML();

1  
2  
3  
4  

Your array must have only one element in the "top level" and it can not be numeric. If the array is not in this format, Xml will throw an exception. Examples of invalid arrays:

    // Top level with numeric key
    [\
        ['key' => 'value']\
    ];
    
    // Multiple keys in top level
    [\
        'key1' => 'first value',\
        'key2' => 'other value'\
    ];

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

By default array values will be output as XML tags. If you want to define attributes or text values you can prefix the keys that are supposed to be attributes with `@`. For value text, use `@` as the key:

    $xmlArray = [\
        'project' => [\
            '@id' => 1,\
            'name' => 'Name of project, as tag',\
            '@' => 'Value of project',\
        ],\
    ];
    $xmlObject = Xml::fromArray($xmlArray);
    $xmlString = $xmlObject->asXML();

1  
2  
3  
4  
5  
6  
7  
8  
9  

The content of `$xmlString` will be:

    <?xml version="1.0"?>
    <project id="1">Value of project<name>Name of project, as tag</name></project>

1  
2  

### Using Namespaces [​](https://book.cakephp.org/6.x/core-libraries/xml.html#using-namespaces)

To use XML Namespaces, create a key in your array with the name `xmlns:` in a generic namespace or input the prefix `xmlns:` in a custom namespace. See the samples:

    $xmlArray = [\
        'root' => [\
            'xmlns:' => 'https://cakephp.org',\
            'child' => 'value',\
        ]\
    ];
    $xml1 = Xml::fromArray($xmlArray);
    
    $xmlArray(
        'root' => [\
            'tag' => [\
                'xmlns:pref' => 'https://cakephp.org',\
                'pref:item' => [\
                    'item 1',\
                    'item 2'\
                ]\
            ]\
        ]
    );
    $xml2 = Xml::fromArray($xmlArray);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  

The value of `$xml1` and `$xml2` will be, respectively:

    <?xml version="1.0"?>
    <root xmlns="https://cakephp.org"><child>value</child>
    
    <?xml version="1.0"?>
    <root><tag xmlns:pref="https://cakephp.org"><pref:item>item 1</pref:item><pref:item>item 2</pref:item></tag></root>

1  
2  
3  
4  
5  

### Creating a Child [​](https://book.cakephp.org/6.x/core-libraries/xml.html#creating-a-child)

After you have created your XML document, you just use the native interfaces for your document type to add, remove, or manipulate child nodes:

    // Using SimpleXML
    $myXmlOriginal = '<?xml version="1.0"?><root><child>value</child></root>';
    $xml = Xml::build($myXmlOriginal);
    $xml->root->addChild('young', 'new value');
    
    // Using DOMDocument
    $myXmlOriginal = '<?xml version="1.0"?><root><child>value</child></root>';
    $xml = Xml::build($myXmlOriginal, ['return' => 'domdocument']);
    $child = $xml->createElement('young', 'new value');
    $xml->firstChild->appendChild($child);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

TIP

After manipulating your XML using SimpleXMLElement or DomDocument you can use `Xml::toArray()` without a problem.

---

# Running Shells as Cron Jobs | CakePHP

[Skip to content](https://book.cakephp.org/6.x/console-commands/cron-jobs.html#VPContent)

Return to top

Running Shells as Cron Jobs [​](https://book.cakephp.org/6.x/console-commands/cron-jobs.html#running-shells-as-cron-jobs)

==========================================================================================================================

A common thing to do with a shell is making it run as a cronjob to clean up the database once in a while or send newsletters. This is trivial to setup, for example:

    */5  *    *    *    *  cd /full/path/to/root && bin/cake myshell myparam
    # *    *    *    *    *  command to execute
    # │    │    │    │    │
    # │    │    │    │    │
    # │    │    │    │    \───── day of week (0 - 6) (0 to 6 are Sunday to Saturday,
    # |    |    |    |           or use names)
    # │    │    │    \────────── month (1 - 12)
    # │    │    \─────────────── day of month (1 - 31)
    # │    \──────────────────── hour (0 - 23)
    # \───────────────────────── min (0 - 59)

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

You can see more info here: [https://en.wikipedia.org/wiki/Cron](https://en.wikipedia.org/wiki/Cron)

TIP

Use `-q` (or \--quiet) to silence any output for cronjobs.

Cron Jobs on Shared Hosting [​](https://book.cakephp.org/6.x/console-commands/cron-jobs.html#cron-jobs-on-shared-hosting)

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

On some shared hostings `cd /full/path/to/root && bin/cake mycommand myparam` might not work. Instead you can use `php /full/path/to/root/bin/cake.php mycommand myparam`.

NOTE

register\_argc\_argv has to be turned on by including `register_argc_argv = 1` in your php.ini. If you cannot change register\_argc\_argv globally, you can tell the cron job to use your own configuration by specifying it with `-d register_argc_argv=1` parameter. Example: `php -d register_argc_argv=1 /full/path/to/root/bin/cake.php myshell myparam`

---

# Security | CakePHP

[Skip to content](https://book.cakephp.org/2.x/core-libraries/components/security-component.html#VPContent)

Return to top

Security [​](https://book.cakephp.org/2.x/core-libraries/components/security-component.html#security)

======================================================================================================

`class` **SecurityComponent**(ComponentCollection $collection, array $settings = array())

The Security Component creates an easy way to integrate tighter security in your application. It provides methods for various tasks like:

*   Restricting which HTTP methods your application accepts.
*   CSRF protection.
*   Form tampering protection
*   Requiring that SSL be used.
*   Limiting cross controller communication.

Like all components it is configured through several configurable parameters. All of these properties can be set directly or through setter methods of the same name in your controller's beforeFilter.

By using the Security Component you automatically get [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery)
 and form tampering protection. Hidden token fields will automatically be inserted into forms and checked by the Security component. Among other things, a form submission will not be accepted after a certain period of inactivity, which is controlled by the `csrfExpires` time.

If you are using Security component's form protection features and other components that process form data in their `startup()` callbacks, be sure to place Security Component before those components in your `$components` array.

NOTE

When using the Security Component you **must** use the FormHelper to create your forms. In addition, you must **not** override any of the fields' "name" attributes. The Security Component looks for certain indicators that are created and managed by the FormHelper (especially those created in `~FormHelper::create()` and `~FormHelper::end()`). Dynamically altering the fields that are submitted in a POST request (e.g. disabling, deleting or creating new fields via JavaScript) is likely to trigger a black-holing of the request. See the `$validatePost` or `$disabledFields` configuration parameters.

Handling blackhole callbacks [​](https://book.cakephp.org/2.x/core-libraries/components/security-component.html#handling-blackhole-callbacks)

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

If an action is restricted by the Security Component it is black-holed as an invalid request which will result in a 400 error by default. You can configure this behavior by setting the `$this->Security->blackHoleCallback` property to a callback function in the controller.

`method` SecurityComponent::**blackHole**(object $controller, string $error)

Restricting HTTP methods [​](https://book.cakephp.org/2.x/core-libraries/components/security-component.html#restricting-http-methods)

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

`method` SecurityComponent::**requirePost**()

`method` SecurityComponent::**requireGet**()

`method` SecurityComponent::**requirePut**()

`method` SecurityComponent::**requireDelete**()

Restrict actions to SSL [​](https://book.cakephp.org/2.x/core-libraries/components/security-component.html#restrict-actions-to-ssl)

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

`method` SecurityComponent::**requireSecure**()

`method` SecurityComponent::**requireAuth**()

Restricting cross controller communication [​](https://book.cakephp.org/2.x/core-libraries/components/security-component.html#restricting-cross-controller-communication)

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

> A list of controllers which can send requests to this controller. This can be used to control cross controller requests.
> 
> A list of actions which are allowed to send requests to this controller's actions. This can be used to control cross controller requests.

Form tampering prevention [​](https://book.cakephp.org/2.x/core-libraries/components/security-component.html#form-tampering-prevention)

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

By default the `SecurityComponent` prevents users from tampering with forms in specific ways. The `SecurityComponent` will prevent the following things:

*   Unknown fields cannot be added to the form.
*   Fields cannot be removed from the form.
*   Values in hidden inputs cannot be modified.

Preventing these types of tampering is accomplished by working with the FormHelper and tracking which fields are in a form. The values for hidden fields are tracked as well. All of this data is combined and turned into a hash. When a form is submitted, the `SecurityComponent` will use the POST data to build the same structure and compare the hash.

NOTE

The SecurityComponent will **not** prevent select options from being added/changed. Nor will it prevent radio options from being added/changed.

Set to a list of form fields to exclude from POST validation. Fields can be unlocked either in the Component, or with `FormHelper::unlockField()`. Fields that have been unlocked are not required to be part of the POST and hidden unlocked fields do not have their values checked.

Set to `false` to completely skip the validation of POST requests, essentially turning off form validation.

CSRF configuration [​](https://book.cakephp.org/2.x/core-libraries/components/security-component.html#csrf-configuration)

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

> Whether to use CSRF protected forms. Set to `false` to disable CSRF protection on forms.
> 
> The duration from when a CSRF token is created that it will expire on. Each form/page request will generate a new token that can only be submitted once unless it expires. Can be any value compatible with `strtotime()`. The default is +30 minutes.
> 
> Controls whether or not CSRF tokens are single use. Set to `false` to not generate new tokens on each request. One token will be reused until it expires. This reduces the chances of users getting invalid requests because of token consumption. It has the side effect of making CSRF less secure, as tokens are reusable.

Usage [​](https://book.cakephp.org/2.x/core-libraries/components/security-component.html#usage)

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

Using the security component is generally done in the controllers `beforeFilter()`. You would specify the security restrictions you want and the Security Component will enforce them on its startup:

    class WidgetController extends AppController {
    
        public $components = array('Security');
    
        public function beforeFilter() {
            $this->Security->requirePost('delete');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  

In this example the delete action can only be successfully triggered if it receives a POST request:

    class WidgetController extends AppController {
    
        public $components = array('Security');
    
        public function beforeFilter() {
            if (isset($this->request->params['admin'])) {
                $this->Security->requireSecure();
            }
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

This example would force all actions that had admin routing to require secure SSL requests:

    class WidgetController extends AppController {
    
        public $components = array('Security');
    
        public function beforeFilter() {
            if (isset($this->params['admin'])) {
                $this->Security->blackHoleCallback = 'forceSSL';
                $this->Security->requireSecure();
            }
        }
    
        public function forceSSL() {
            return $this->redirect('https://' . env('SERVER_NAME') . $this->here);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

This example would force all actions that had admin routing to require SSL requests. When the request is black holed, it will call the nominated `forceSSL()` callback which will redirect non-secure requests to secure requests automatically.

CSRF protection [​](https://book.cakephp.org/2.x/core-libraries/components/security-component.html#csrf-protection)

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

CSRF or Cross Site Request Forgery is a common vulnerability in web applications. It allows an attacker to capture and replay a previous request, and sometimes submit data requests using image tags or resources on other domains.

Double submission and replay attacks are handled by the `SecurityComponent` CSRF features. They work by adding a special token to each form request. This token, once used, cannot be used again. If an attempt is made to re-use an expired token the request will be blackholed.

### Using CSRF protection [​](https://book.cakephp.org/2.x/core-libraries/components/security-component.html#using-csrf-protection)

Simply by adding the `SecurityComponent` to your components array, you can benefit from the CSRF protection it provides. By default CSRF tokens are valid for 30 minutes and expire on use. You can control how long tokens last by setting csrfExpires on the component. :

    public $components = array(
        'Security' => array(
            'csrfExpires' => '+1 hour'
        )
    );

1  
2  
3  
4  
5  

You can also set this property in your controller's `beforeFilter`:

    public function beforeFilter() {
        $this->Security->csrfExpires = '+1 hour';
        // ...
    }

1  
2  
3  
4  

The csrfExpires property can be any value that is compatible with [strtotime()](https://www.php.net/manual/en/function.strtotime.php)
. By default the `FormHelper` will add a `data[_Token][key]` containing the CSRF token to every form when the component is enabled.

### Handling missing or expired tokens [​](https://book.cakephp.org/2.x/core-libraries/components/security-component.html#handling-missing-or-expired-tokens)

Missing or expired tokens are handled similar to other security violations. The `SecurityComponent` `blackHoleCallback` will be called with a 'csrf' parameter. This helps you filter out CSRF token failures, from other warnings.

### Using per-session tokens instead of one-time use tokens [​](https://book.cakephp.org/2.x/core-libraries/components/security-component.html#using-per-session-tokens-instead-of-one-time-use-tokens)

By default a new CSRF token is generated for each request, and each token can only be used once. If a token is used twice, the request will be blackholed. Sometimes, this behaviour is not desirable, as it can create issues with single page applications. You can toggle on longer, multi-use tokens by setting `csrfUseOnce` to `false`. This can be done in the components array, or in the `beforeFilter` of your controller:

    public $components = array(
        'Security' => array(
            'csrfUseOnce' => false
        )
    );

1  
2  
3  
4  
5  

This will tell the component that you want to re-use a CSRF token until it expires - which is controlled by the `csrfExpires` value. If you are having issues with expired tokens, this is a good balance between security and ease of use.

### Disabling the CSRF protection [​](https://book.cakephp.org/2.x/core-libraries/components/security-component.html#disabling-the-csrf-protection)

There may be cases where you want to disable CSRF protection on your forms for some reason. If you do want to disable this feature, you can set `$this->Security->csrfCheck = false;` in your `beforeFilter` or use the components array. By default CSRF protection is enabled, and configured to use one-use tokens.

Disabling CSRF and Post Data Validation For Specific Actions [​](https://book.cakephp.org/2.x/core-libraries/components/security-component.html#disabling-csrf-and-post-data-validation-for-specific-actions)

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

There may be cases where you want to disable all security checks for an action (ex. AJAX requests). You may "unlock" these actions by listing them in `$this->Security->unlockedActions` in your `beforeFilter`. The `unlockedActions` property will **not** effect other features of `SecurityComponent`.

Added in version 2.3

---

# TimeHelper | CakePHP

[Skip to content](https://book.cakephp.org/2.x/core-libraries/helpers/time.html#VPContent)

Return to top

TimeHelper [​](https://book.cakephp.org/2.x/core-libraries/helpers/time.html#timehelper)

=========================================================================================

`class` **TimeHelper**(View $view, array $settings = array())

The Time Helper does what it says on the tin: saves you time. It allows for the quick processing of time related information. The Time Helper has two main tasks that it can perform:

1.  It can format time strings.
2.  It can test time (but cannot bend time, sorry).

Changed in version 2.1

`TimeHelper` has been refactored into the `CakeTime` class to allow easier use outside of the `View` layer. Within a view, these methods are accessible via the TimeHelper class and you can call it as you would call a normal helper method: `$this->Time->method($args);`.

Using the Helper [​](https://book.cakephp.org/2.x/core-libraries/helpers/time.html#using-the-helper)

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

A common use of the Time Helper is to offset the date and time to match a user's time zone. Lets use a forum as an example. Your forum has many users who may post messages at any time from any part of the world. An easy way to manage the time is to save all dates and times as GMT+0 or UTC. Uncomment the line `date_default_timezone_set('UTC');` in `app/Config/core.php` to ensure your application's time zone is set to GMT+0.

Next add a time zone field to your users table and make the necessary modifications to allow your users to set their time zone. Now that we know the time zone of the logged in user we can correct the date and time on our posts using the Time Helper:

    echo $this->Time->format(
      'F jS, Y h:i A',
      $post['Post']['created'],
      null,
      $user['User']['time_zone']
    );
    // Will display August 22nd, 2011 11:53 PM for a user in GMT+0
    // August 22nd, 2011 03:53 PM for a user in GMT-8
    // and August 23rd, 2011 09:53 AM GMT+10

1  
2  
3  
4  
5  
6  
7  
8  
9  

Most of the Time Helper methods have a $timezone parameter. The $timezone parameter accepts a valid timezone identifier string or an instance of DateTimeZone class.

Formatting [​](https://book.cakephp.org/2.x/core-libraries/helpers/time.html#formatting)

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

`method` CakeTime::**convert**($serverTime, $timezone = NULL)

`method` CakeTime::**convertSpecifiers**($format, $time = NULL)

`method` CakeTime::**dayAsSql**($dateString, $field\_name, $timezone = NULL)

`method` CakeTime::**daysAsSql**($begin, $end, $fieldName, $timezone = NULL)

`method` CakeTime::**format**($date, $format = NULL, $default = false, $timezone = NULL)

`method` CakeTime::**fromString**($dateString, $timezone = NULL)

`method` CakeTime::**gmt**($dateString = NULL)

`method` CakeTime::**i18nFormat**($date, $format = NULL, $invalid = false, $timezone = NULL)

`method` CakeTime::**nice**($dateString = NULL, $timezone = NULL, $format = null)

`method` CakeTime::**niceShort**($dateString = NULL, $timezone = NULL)

`method` CakeTime::**serverOffset**()

`method` CakeTime::**timeAgoInWords**($dateString, $options = array())

`method` CakeTime::**toAtom**($dateString, $timezone = NULL)

`method` CakeTime::**toQuarter**($dateString, $range = false)

`method` CakeTime::**toRSS**($dateString, $timezone = NULL)

`method` CakeTime::**toUnix**($dateString, $timezone = NULL)

`method` CakeTime::**toServer**($dateString, $timezone = NULL, $format = 'Y-m-d H:i:s')

`method` CakeTime::**timezone**($timezone = NULL)

`method` CakeTime::**listTimezones**($filter = null, $country = null, $options = array())

Testing Time [​](https://book.cakephp.org/2.x/core-libraries/helpers/time.html#testing-time)

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

`method` CakeTime::**isToday**($dateString, $timezone = NULL)

`method` CakeTime::**isThisWeek**($dateString, $timezone = NULL)

`method` CakeTime::**isThisMonth**($dateString, $timezone = NULL)

`method` CakeTime::**isThisYear**($dateString, $timezone = NULL)

`method` CakeTime::**wasYesterday**($dateString, $timezone = NULL)

`method` CakeTime::**isTomorrow**($dateString, $timezone = NULL)

`method` CakeTime::**isFuture**($dateString, $timezone = NULL)

`method` CakeTime::**isPast**($dateString, $timezone = NULL)

`method` CakeTime::**wasWithinLast**($timeInterval, $dateString, $timezone = NULL)

---

# Console Commands | CakePHP

[Skip to content](https://book.cakephp.org/6.x/console-commands.html#VPContent)

Return to top

Console Commands [​](https://book.cakephp.org/6.x/console-commands.html#console-commands)

==========================================================================================

In addition to a web framework, CakePHP also provides a console framework for creating command line tools & applications. Console applications are ideal for handling a variety of background & maintenance tasks that leverage your existing application configuration, models, plugins and domain logic.

CakePHP provides several console tools for interacting with CakePHP features like i18n and routing that enable you to introspect your application and generate related files.

The CakePHP Console [​](https://book.cakephp.org/6.x/console-commands.html#the-cakephp-console)

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

The CakePHP Console uses a dispatcher-type system to load commands, parse their arguments and invoke the correct command. While the examples below use bash the CakePHP console is compatible with any \*nix shell and windows.

A CakePHP application contains **src/Command** directory that contain its commands. It also comes with an executable in the **bin** directory:

    $ cd /path/to/app
    $ bin/cake

1  
2  

NOTE

For Windows, the command needs to be `bin\cake` (note the backslash).

Running the Console with no arguments will list out available commands. You could then run the any of the listed commands by using its name:

    # run server command
    bin/cake server
    
    # run migrations command
    bin/cake migrations -h
    
    # run bake (with plugin prefix)
    bin/cake bake.bake -h

1  
2  
3  
4  
5  
6  
7  
8  

Plugin commands can be invoked without a plugin prefix if the commands's name does not overlap with an application or framework command. In the case that two plugins provide a command with the same name, the first loaded plugin will get the short alias. You can always use the `plugin.command` format to unambiguously reference a command.

Console Applications [​](https://book.cakephp.org/6.x/console-commands.html#console-applications)

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

By default CakePHP will automatically discover all the commands in your application and its plugins. You may want to reduce the number of exposed commands, when building standalone console applications. You can use your `Application`'s `console()` hook to limit which commands are exposed and rename commands that are exposed:

    // in src/Application.php
    namespace App;
    
    use App\Command\UserCommand;
    use App\Command\VersionCommand;
    use Cake\Console\CommandCollection;
    use Cake\Http\BaseApplication;
    
    class Application extends BaseApplication
    {
        public function console(CommandCollection $commands): CommandCollection
        {
            // Add by classname
            $commands->add('user', UserCommand::class);
    
            // Add instance
            $commands->add('version', new VersionCommand());
    
            return $commands;
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  

In the above example, the only commands available would be `help`, `version` and `user`. See the [Plugin Commands](https://book.cakephp.org/6.x/plugins.html#plugin-commands)
 section for how to add commands in your plugins.

NOTE

When adding multiple commands that use the same Command class, the `help` command will display the shortest option.

Renaming Commands [​](https://book.cakephp.org/6.x/console-commands.html#renaming-commands)

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

There are cases where you will want to rename commands, to create nested commands or subcommands. While the default auto-discovery of commands will not do this, you can register your commands to create any desired naming.

You can customize the command names by defining each command in your plugin:

    public function console(CommandCollection $commands): CommandCollection
    {
        // Add commands with nested naming
        $commands->add('user dump', UserDumpCommand::class);
        $commands->add('user:show', UserShowCommand::class);
    
        // Rename a command entirely
        $commands->add('lazer', UserDeleteCommand::class);
    
        return $commands;
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

When overriding the `console()` hook in your application, remember to call `$commands->autoDiscover()` to add commands from CakePHP, your application, and plugins.

If you need to rename/remove any attached commands, you can use the `Console.buildCommands` event on your application event manager to modify the available commands.

Commands [​](https://book.cakephp.org/6.x/console-commands.html#commands)

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

See the [Command Objects](https://book.cakephp.org/6.x/console-commands/commands.html)
 chapter on how to create your first command. Then learn more about commands:

*   [Command Objects](https://book.cakephp.org/6.x/console-commands/commands.html)
    
*   [Command Input/Output](https://book.cakephp.org/6.x/console-commands/input-output.html)
    
*   [Option Parsers](https://book.cakephp.org/6.x/console-commands/option-parsers.html)
    
*   [Running Shells as Cron Jobs](https://book.cakephp.org/6.x/console-commands/cron-jobs.html)
    

CakePHP Provided Commands [​](https://book.cakephp.org/6.x/console-commands.html#cakephp-provided-commands)

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

*   [Cache Tool](https://book.cakephp.org/6.x/console-commands/cache.html)
    
*   [Completion Tool](https://book.cakephp.org/6.x/console-commands/completion.html)
    
*   [CounterCache Tool](https://book.cakephp.org/6.x/console-commands/counter-cache.html)
    
*   [I18N Tool](https://book.cakephp.org/6.x/console-commands/i18n.html)
    
*   [Plugin Tool](https://book.cakephp.org/6.x/console-commands/plugin.html)
    
*   [Schema Cache Tool](https://book.cakephp.org/6.x/console-commands/schema-cache.html)
    
*   [Routes Tool](https://book.cakephp.org/6.x/console-commands/routes.html)
    
*   [Server Tool](https://book.cakephp.org/6.x/console-commands/server.html)
    
*   [Interactive Console (REPL)](https://book.cakephp.org/6.x/console-commands/repl.html)
    

Routing in the Console Environment [​](https://book.cakephp.org/6.x/console-commands.html#routing-in-the-console-environment)

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

In command-line interface (CLI), specifically your console commands, `env('HTTP_HOST')` and other webbrowser specific environment variables are not set.

If you generate reports or send emails that make use of `Router::url()` those will contain the default host `http://localhost/` and thus resulting in invalid URLs. In this case you need to specify the domain manually. You can do that using the Configure value `App.fullBaseUrl` from your bootstrap or config, for example.

For sending emails, you should provide Email class with the host you want to send the email with:

    use Cake\Mailer\Email;
    
    $email = new Email();
    $email->setDomain('www.example.org');

1  
2  
3  
4  

This asserts that the generated message IDs are valid and fit to the domain the emails are sent from.

---

# I18N Tool | CakePHP

[Skip to content](https://book.cakephp.org/6.x/console-commands/i18n.html#VPContent)

Return to top

I18N Tool [​](https://book.cakephp.org/6.x/console-commands/i18n.html#i18n-tool)

=================================================================================

The i18n features of CakePHP use [po files](https://en.wikipedia.org/wiki/GNU_gettext)
 as their translation source. PO files integrate with commonly used translation tools like [Poedit](https://www.poedit.net/)
.

The i18n commands provides a quick way to generate po template files. These templates files can then be given to translators so they can translate the strings in your application. Once you have translations done, pot files can be merged with existing translations to help update your translations.

Generating POT Files [​](https://book.cakephp.org/6.x/console-commands/i18n.html#generating-pot-files)

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

POT files can be generated for an existing application using the `extract` command. This command will scan your entire application for `__()` style function calls, and extract the message string. Each unique string in your application will be combined into a single POT file:

    bin/cake i18n extract

1  

The above will run the extraction command. The result of this command will be the file **resources/locales/default.pot**. You use the pot file as a template for creating po files. If you are manually creating po files from the pot file, be sure to correctly set the `Plural-Forms` header line.

### Generating POT Files for Plugins [​](https://book.cakephp.org/6.x/console-commands/i18n.html#generating-pot-files-for-plugins)

You can generate a POT file for a specific plugin using:

    bin/cake i18n extract --plugin <Plugin>

1  

This will generate the required POT files used in the plugins.

### Extracting from multiple folders at once [​](https://book.cakephp.org/6.x/console-commands/i18n.html#extracting-from-multiple-folders-at-once)

Sometimes, you might need to extract strings from more than one directory of your application. For instance, if you are defining some strings in the `config/` directory of your application, you probably want to extract strings from this directory as well as from the `src/` directory. You can do it by using the `--paths` option. It takes a comma-separated list of absolute paths to extract:

    bin/cake i18n extract --paths /var/www/app/config,/var/www/app/src

1  

### Excluding Folders [​](https://book.cakephp.org/6.x/console-commands/i18n.html#excluding-folders)

You can pass a comma separated list of folders that you wish to be excluded. Any path containing a path segment with the provided values will be ignored:

    bin/cake i18n extract --exclude vendor,tests

1  

### Skipping Overwrite Warnings for Existing POT Files [​](https://book.cakephp.org/6.x/console-commands/i18n.html#skipping-overwrite-warnings-for-existing-pot-files)

By adding `--overwrite`, the shell script will no longer warn you if a POT file already exists and will overwrite by default:

    bin/cake i18n extract --overwrite

1  

### Extracting Messages from the CakePHP Core Libraries [​](https://book.cakephp.org/6.x/console-commands/i18n.html#extracting-messages-from-the-cakephp-core-libraries)

By default, the extract shell script will ask you if you like to extract the messages used in the CakePHP core libraries. Set `--extract-core` to yes or no to set the default behavior:

    bin/cake i18n extract --extract-core yes
    
    // or
    
    bin/cake i18n extract --extract-core no

1  
2  
3  
4  
5

---

# Server Tool | CakePHP

[Skip to content](https://book.cakephp.org/6.x/console-commands/server.html#VPContent)

Return to top

Server Tool [​](https://book.cakephp.org/6.x/console-commands/server.html#server-tool)

=======================================================================================

The `ServerCommand` lets you stand up a simple webserver using the built in PHP webserver. While this server is _not_ intended for production use it can be handy in development when you want to quickly try an idea out and don't want to spend time configuring Apache or Nginx. You can start the server command with:

    bin/cake server

1  

You should see the server boot up and attach to port 8765. You can visit the CLI server by visiting `http://localhost:8765` in your web-browser. You can close the server by pressing `CTRL-C` in your terminal.

NOTE

Try `bin/cake server -H 0.0.0.0` if the server is unreachable from other hosts.

Changing the Port and Document Root [​](https://book.cakephp.org/6.x/console-commands/server.html#changing-the-port-and-document-root)

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

You can customize the port and document root using options:

    bin/cake server --port 8080 --document_root path/to/app

1

---

# Schema Cache Tool | CakePHP

[Skip to content](https://book.cakephp.org/6.x/console-commands/schema-cache.html#VPContent)

Return to top

Schema Cache Tool [​](https://book.cakephp.org/6.x/console-commands/schema-cache.html#schema-cache-tool)

=========================================================================================================

The SchemaCacheCommand provides a simple CLI tool for managing your application's metadata caches. In deployment situations it is helpful to rebuild the metadata cache in-place without clearing the existing cache data. You can do this by running:

    bin/cake schema_cache build --connection default

1  

This will rebuild the metadata cache for all tables on the `default` connection. If you only need to rebuild a single table you can do that by providing its name:

    bin/cake schema_cache build --connection default articles

1  

In addition to building cached data, you can use the SchemaCacheShell to remove cached metadata as well:

    # Clear all metadata
    bin/cake schema_cache clear
    
    # Clear a single table
    bin/cake schema_cache clear articles

1  
2  
3  
4  
5

---

# Data Sanitization | CakePHP

[Skip to content](https://book.cakephp.org/2.x/core-utility-libraries/sanitize.html#VPContent)

Return to top

Data Sanitization [​](https://book.cakephp.org/2.x/core-utility-libraries/sanitize.html#data-sanitization)

===========================================================================================================

The `Sanitize` class is deprecated as of 2.4, and will be removed in CakePHP 3.0. Instead of using the Sanitize class you can accomplish the same tasks using other parts of CakePHP, native PHP functions, or other libraries.

Input filtering [​](https://book.cakephp.org/2.x/core-utility-libraries/sanitize.html#input-filtering)

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

Instead of using the destructive input filtering features of Sanitize class you should instead apply more thorough [Data Validation](https://book.cakephp.org/2.x/models/data-validation.html)
 to the user data your application accepts. By rejecting invalid input you can often remove the need to destructively modify user data. You might also want to look at [PHP's filter extension](https://www.php.net/filter)
 in situations you need to modify user input.

Accepting user submitted HTML [​](https://book.cakephp.org/2.x/core-utility-libraries/sanitize.html#accepting-user-submitted-html)

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

Often input filtering is used when accepting user-submitted HTML. In these situations it is best to use a dedicated library like [HTML Purifier](https://htmlpurifier.org/)
.

SQL Escaping [​](https://book.cakephp.org/2.x/core-utility-libraries/sanitize.html#sql-escaping)

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

CakePHP handles SQL escaping on associated array values provided to `Model::find()` and `Model::save()`. In the rare case you need to construct SQL by hand using user input you should use [Prepared Statements](https://book.cakephp.org/2.x/models/retrieving-your-data.html#prepared-statements)
.

---

# CakeNumber | CakePHP

[Skip to content](https://book.cakephp.org/2.x/core-utility-libraries/number.html#VPContent)

Return to top

CakeNumber [​](https://book.cakephp.org/2.x/core-utility-libraries/number.html#cakenumber)

===========================================================================================

`class` **CakeNumber**

If you need `NumberHelper` functionalities outside of a `View`, use the `CakeNumber` class:

    class UsersController extends AppController {
    
        public $components = array('Auth');
    
        public function afterLogin() {
            App::uses('CakeNumber', 'Utility');
            $storageUsed = $this->Auth->user('storage_used');
            if ($storageUsed > 5000000) {
                // notify users of quota
                $this->Session->setFlash(__('You are using %s storage', CakeNumber::toReadableSize($storageUsed)));
            }
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

Added in version 2.1

`CakeNumber` has been factored out from `NumberHelper`.

All of these functions return the formatted number; They do not automatically echo the output into the view.

`method` CakeNumber::**currency**(float $number, string $currency = 'USD', array $options = array())

`method` CakeNumber::**defaultCurrency**(string $currency)

`method` CakeNumber::**addFormat**(string $formatName, array $options)

`method` CakeNumber::**precision**(mixed $number, int $precision = 3)

`method` CakeNumber::**toPercentage**(mixed $number, int $precision = 2, array $options = array())

`method` CakeNumber::**fromReadableSize**(string $size, $default)

`method` CakeNumber::**toReadableSize**(string $dataSize)

`method` CakeNumber::**format**(mixed $number, mixed $options=false)

`method` CakeNumber::**formatDelta**(mixed $number, mixed $options=array())

---

# Inflector | CakePHP

[Skip to content](https://book.cakephp.org/2.x/core-utility-libraries/inflector.html#VPContent)

Return to top

Inflector [​](https://book.cakephp.org/2.x/core-utility-libraries/inflector.html#inflector)

============================================================================================

`class` **Inflector**

The Inflector class takes a string and can manipulate it to handle word variations such as pluralizations or camelizing and is normally accessed statically. Example: `Inflector::pluralize('example')` returns "examples".

You can try out the inflections online at [inflector.cakephp.org](https://inflector.cakephp.org/)
.

`static` Inflector::**pluralize**($singular)

*   **Input:** Apple, Orange, Person, Man
*   **Output:** Apples, Oranges, People, Men

NOTE

`pluralize()` may not always correctly convert a noun that is already in it's plural form.

`static` Inflector::**singularize**($plural)

*   **Input:** Apples, Oranges, People, Men
*   **Output:** Apple, Orange, Person, Man

NOTE

`singularize()` may not always correctly convert a noun that is already in it's singular form.

`static` Inflector::**camelize**($underscored)

*   **Input:** Apple\_pie, some\_thing, people\_person
*   **Output:** ApplePie, SomeThing, PeoplePerson

`static` Inflector::**underscore**($camelCase)

It should be noted that underscore will only convert camelCase formatted words. Words that contains spaces will be lower-cased, but will not contain an underscore.

*   **Input:** applePie, someThing
*   **Output:** apple\_pie, some\_thing

`static` Inflector::**humanize**($underscored)

*   **Input:** apple\_pie, some\_thing, people\_person
*   **Output:** Apple Pie, Some Thing, People Person

`static` Inflector::**tableize**($camelCase)

*   **Input:** Apple, UserProfileSetting, Person
*   **Output:** apples, user\_profile\_settings, people

`static` Inflector::**classify**($underscored)

*   **Input:** apples, user\_profile\_settings, people
*   **Output:** Apple, UserProfileSetting, Person

`static` Inflector::**variable**($underscored)

*   **Input:** apples, user\_result, people\_people
*   **Output:** apples, userResult, peoplePeople

`static` Inflector::**slug**($word, $replacement = '\_')

Slug converts special characters into latin versions and converting unmatched characters and spaces to underscores. The slug method expects UTF-8 encoding.

*   **Input:** apple purée
*   **Output:** apple\_puree

`static` Inflector::**reset**()

Resets Inflector back to its initial state, useful in testing.

`static` Inflector::**rules**($type, $rules, $reset = false)

Define new inflection and transliteration rules for Inflector to use. See [Inflection Configuration](https://book.cakephp.org/2.x/development/configuration.html#inflection-configuration)
 for more information.

---

# Deleting Data | CakePHP

[Skip to content](https://book.cakephp.org/4.x/orm/deleting-data.html#VPContent)

Return to top

Deleting Data [​](https://book.cakephp.org/4.x/orm/deleting-data.html#deleting-data)

=====================================================================================

`class` Cake\\ORM\\**Table**

`method` Cake\\ORM\\Table::**delete**(Entity $entity, $options = \[\])

Once you've loaded an entity you can delete it by calling the originating table's delete method:

    // In a controller.
    $entity = $this->Articles->get(2);
    $result = $this->Articles->delete($entity);

1  
2  
3  

When deleting entities a few things happen:

1.  The [delete rules](https://book.cakephp.org/4.x/orm/validation.html#application-rules)
     will be applied. If the rules fail, deletion will be prevented.
2.  The `Model.beforeDelete` event is triggered. If this event is stopped, the delete will be aborted and the event's result will be returned.
3.  The entity will be deleted.
4.  All dependent associations will be deleted. If associations are being deleted as entities, additional events will be dispatched.
5.  Any junction table records for BelongsToMany associations will be removed.
6.  The `Model.afterDelete` event will be triggered.

By default all deletes happen within a transaction. You can disable the transaction with the atomic option:

    $result = $this->Articles->delete($entity, ['atomic' => false]);

1  

The `$options` parameter supports the following options:

*   `atomic` Defaults to true. When true the deletion happens within a transaction.
*   `checkRules` Defaults to true. Check deletion rules before deleting records.

Cascading Deletes [​](https://book.cakephp.org/4.x/orm/deleting-data.html#cascading-deletes)

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

When deleting entities, associated data can also be deleted. If your HasOne and HasMany associations are configured as `dependent`, delete operations will 'cascade' to those entities as well. By default entities in associated tables are removed using `Cake\ORM\Table::deleteAll()`. You can elect to have the ORM load related entities, and delete them individually by setting the `cascadeCallbacks` option to `true`. A sample HasMany association with both these options enabled would be:

    // In a Table's initialize method.
    $this->hasMany('Comments', [\
        'dependent' => true,\
        'cascadeCallbacks' => true,\
    ]);

1  
2  
3  
4  
5  

NOTE

Setting `cascadeCallbacks` to `true`, results in considerably slower deletes when compared to bulk deletes. The cascadeCallbacks option should only be enabled when your application has important work handled by event listeners.

Bulk Deletes [​](https://book.cakephp.org/4.x/orm/deleting-data.html#bulk-deletes)

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

`method` Cake\\ORM\\Table::**deleteMany**($entities, $options = \[\])

If you have an array of entities you want to delete you can use `deleteMany()` to delete them in a single transaction:

    // Get a boolean indicating success
    $success = $this->Articles->deleteMany($entities);
    
    // Will throw a PersistenceFailedException if any entity cannot be deleted.
    $this->Articles->deleteManyOrFail($entities);

1  
2  
3  
4  
5  

The `$options` for these methods are the same as `delete()`. Deleting records with these method **will** trigger events.

`method` Cake\\ORM\\Table::**deleteAll**($conditions)

There may be times when deleting rows one by one is not efficient or useful. In these cases it is more performant to use a bulk-delete to remove many rows at once:

    // Delete all the spam
    function destroySpam()
    {
        return $this->deleteAll(['is_spam' => true]);
    }

1  
2  
3  
4  
5  

A bulk-delete will be considered successful if 1 or more rows are deleted. The function returns the number of deleted records as an integer.

WARNING

deleteAll will _not_ trigger beforeDelete/afterDelete events. If you need callbacks triggered, first load the entities with `find()` and delete them in a loop.

Strict Deletes [​](https://book.cakephp.org/4.x/orm/deleting-data.html#strict-deletes)

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

`method` Cake\\ORM\\Table::**deleteOrFail**($entity, $options = \[\])

Using this method will throw an `Cake\ORM\Exception\PersistenceFailedException` if:

*   the entity is new
*   the entity has no primary key value
*   application rules checks failed
*   the delete was aborted by a callback.

If you want to track down the entity that failed to delete, you can use the `Cake\ORM\Exception\PersistenceFailedException::getEntity()` method:

    try {
        $table->deleteOrFail($entity);
    } catch (\Cake\ORM\Exception\PersistenceFailedException $e) {
        echo $e->getEntity();
    }

1  
2  
3  
4  
5  

As this internally performs a `Cake\ORM\Table::delete()` call, all corresponding delete events will be triggered.

---

# Timestamp | CakePHP

[Skip to content](https://book.cakephp.org/4.x/orm/behaviors/timestamp.html#VPContent)

Return to top

Timestamp [​](https://book.cakephp.org/4.x/orm/behaviors/timestamp.html#timestamp)

===================================================================================

`class` Cake\\ORM\\Behavior\\**TimestampBehavior**

The timestamp behavior allows your table objects to update one or more timestamps on each model event. This is primarily used to populate data into `created` and `modified` fields. However, with some additional configuration, you can update any timestamp/datetime column on any event a table publishes.

Basic Usage [​](https://book.cakephp.org/4.x/orm/behaviors/timestamp.html#basic-usage)

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

You enable the timestamp behavior like any other behavior:

    class ArticlesTable extends Table
    {
        public function initialize(array $config): void
        {
            $this->addBehavior('Timestamp');
        }
    }

1  
2  
3  
4  
5  
6  
7  

The default configuration will do the following:

*   When a new entity is saved the `created` and `modified` fields will be set to the current time.
*   When an entity is updated, the `modified` field is set to the current time.

Using and Configuring the Behavior [​](https://book.cakephp.org/4.x/orm/behaviors/timestamp.html#using-and-configuring-the-behavior)

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

If you need to modify fields with different names, or want to update additional timestamp fields on custom events you can use some additional configuration:

    class OrdersTable extends Table
    {
        public function initialize(array $config): void
        {
            $this->addBehavior('Timestamp', [\
                'events' => [\
                    'Model.beforeSave' => [\
                        'created_at' => 'new',\
                        'updated_at' => 'always',\
                    ],\
                    'Orders.completed' => [\
                        'completed_at' => 'always'\
                    ]\
                ]\
            ]);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

As you can see above, in addition to the standard `Model.beforeSave` event, we are also updating the `completed_at` column when orders are completed.

Updating Timestamps on Entities [​](https://book.cakephp.org/4.x/orm/behaviors/timestamp.html#updating-timestamps-on-entities)

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

Sometimes you'll want to update just the timestamps on an entity without changing any other properties. This is sometimes referred to as 'touching' a record. In CakePHP you can use the `touch()` method to do exactly this:

    // Touch based on the Model.beforeSave event.
    $articles->touch($article);
    
    // Touch based on a specific event.
    $orders->touch($order, 'Orders.completed');

1  
2  
3  
4  
5  

After you have saved the entity, the field is updated.

Touching records can be useful when you want to signal that a parent resource has changed when a child resource is created/updated. For example: updating an article when a new comment is added.

Saving Updates Without Modifying Timestamps [​](https://book.cakephp.org/4.x/orm/behaviors/timestamp.html#saving-updates-without-modifying-timestamps)

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

To disable the automatic modification of the `updated` timestamp column when saving an entity you can mark the attribute as 'dirty':

    // Mark the modified column as dirty making
    // the current value be set on update.
    $order->setDirty('modified', true);

1  
2  
3

---

# Logging | CakePHP

[Skip to content](https://book.cakephp.org/6.x/core-libraries/logging.html#VPContent)

Return to top

Logging [​](https://book.cakephp.org/6.x/core-libraries/logging.html#logging)

==============================================================================

While CakePHP core Configure Class settings can really help you see what's happening under the hood, there are certain times that you'll need to log data to the disk in order to find out what's going on. With technologies like SOAP, AJAX, and REST APIs, debugging can be rather difficult.

Logging can also be a way to find out what's been going on in your application over time. What search terms are being used? What sorts of errors are my users being shown? How often is a particular query being executed?

Logging data in CakePHP is done with the `log()` function. It is provided by the `LogTrait`, which is the common ancestor for many CakePHP classes. If the context is a CakePHP class (Controller, Component, View,...), you can log your data. You can also use `Log::write()` directly. See [Writing To Logs](https://book.cakephp.org/6.x/core-libraries/logging.html#writing-to-logs)
.

Logging Configuration [​](https://book.cakephp.org/6.x/core-libraries/logging.html#logging-configuration)

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

Configuring `Log` should be done during your application's bootstrap phase. The **config/app.php** file is intended for just this. You can define as many or as few loggers as your application needs. Loggers should be configured using `Cake\Log\Log`. An example would be:

    use Cake\Log\Engine\FileLog;
    use Cake\Log\Log;
    
    // Classname using logger 'class' constant
    Log::setConfig('info', [\
        'className' => FileLog::class,\
        'path' => LOGS,\
        'levels' => ['info'],\
        'file' => 'info',\
    ]);
    
    // Short classname
    Log::setConfig('debug', [\
        'className' => 'File',\
        'path' => LOGS,\
        'levels' => ['notice', 'debug'],\
        'file' => 'debug',\
    ]);
    
    // Fully namespaced name.
    Log::setConfig('error', [\
        'className' => 'Cake\Log\Engine\FileLog',\
        'path' => LOGS,\
        'levels' => ['warning', 'error', 'critical', 'alert', 'emergency'],\
        'file' => 'error',\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  

The above creates three loggers, named `info`, `debug` and `error`. Each is configured to handle different levels of messages. They also store their log messages in separate files, so we can separate debug/notice/info logs from more serious errors. See the section on [Logging Levels](https://book.cakephp.org/6.x/core-libraries/logging.html#logging-levels)
 for more information on the different levels and what they mean.

Once a configuration is created you cannot change it. Instead you should drop the configuration and re-create it using `Cake\Log\Log::drop()` and `Cake\Log\Log::setConfig()`.

It is also possible to create loggers by providing a closure. This is useful when you need full control over how the logger object is built. The closure has to return the constructed logger instance. For example:

    Log::setConfig('special', function () {
        return new \Cake\Log\Engine\FileLog(['path' => LOGS, 'file' => 'log']);
    });

1  
2  
3  

Configuration options can also be provided as a `DSN` string. This is useful when working with environment variables or `PaaS` providers:

    Log::setConfig('error', [\
        'url' => 'file:///full/path/to/logs/?levels[]=warning&levels[]=error&file=error',\
    ]);

1  
2  
3  

WARNING

If you do not configure logging engines, log messages will not be stored.

Error and Exception Logging [​](https://book.cakephp.org/6.x/core-libraries/logging.html#error-and-exception-logging)

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

Errors and Exceptions can also be logged. By configuring the corresponding values in your **config/app.php** file. Errors will be displayed when debug is `true` and logged when debug is `false`. To log uncaught exceptions, set the `log` option to `true`. See [Configuration](https://book.cakephp.org/6.x/development/configuration.html)
 for more information.

Writing to Logs [​](https://book.cakephp.org/6.x/core-libraries/logging.html#writing-to-logs)

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

Writing to the log files can be done in two different ways. The first is to use the static `Cake\Log\Log::write()` method:

    Log::write('debug', 'Something did not work');

1  

The second is to use the `log()` shortcut function available on any class using the `LogTrait`. Calling `log()` will internally call `Log::write()`:

    // Executing this inside a class using LogTrait
    $this->log('Something did not work!', 'debug');

1  
2  

All configured log streams are written to sequentially each time `Cake\Log\Log::write()` is called. If you have not configured any logging engines `log()` will return `false` and no log messages will be written.

### Using Placeholders in Messages [​](https://book.cakephp.org/6.x/core-libraries/logging.html#using-placeholders-in-messages)

If you need to log dynamically defined data, you can use placeholders in your log messages and provide an array of key/value pairs in the `$context` parameter:

    // Will log `Could not process for userid=1`
    Log::write('error', 'Could not process for userid={user}', ['user' => $user->id]);

1  
2  

Placeholders that do not have keys defined will not be replaced. If you need to use a literal braced word, you must escape the placeholder:

    // Will log `No {replace}`
    Log::write('error', 'No \\{replace}', ['replace' => 'no']);

1  
2  

If you include objects in your logging placeholders those objects must implement one of the following methods:

*   `__toString()`
*   `toArray()`
*   `__debugInfo()`

### Using Levels [​](https://book.cakephp.org/6.x/core-libraries/logging.html#using-levels)

CakePHP supports the standard POSIX set of logging levels. Each level represents an increasing level of severity:

*   Emergency: system is unusable
*   Alert: action must be taken immediately
*   Critical: critical conditions
*   Error: error conditions
*   Warning: warning conditions
*   Notice: normal but significant condition
*   Info: informational messages
*   Debug: debug-level messages

You can refer to these levels by name when configuring loggers, and when writing log messages. Alternatively, you can use convenience methods like `Cake\Log\Log::error()` to clearly indicate the logging level. Using a level that is not in the above levels will result in an exception.

NOTE

When `levels` is set to an empty value in a logger's configuration, it will take messages of any level.

### Logging Scopes [​](https://book.cakephp.org/6.x/core-libraries/logging.html#logging-scopes)

Often times you'll want to configure different logging behavior for different subsystems or parts of your application. Take for example an e-commerce shop. You'll probably want to handle logging for orders and payments differently than you do other less critical logs.

CakePHP exposes this concept as logging scopes. When log messages are written you can include a scope name. If there is a configured logger for that scope, the log messages will be directed to those loggers. For example:

    use Cake\Log\Engine\FileLog;
    
    // Configure logs/shops.log to receive all levels, but only
    // those with `orders` and `payments` scope.
    Log::setConfig('shops', [\
        'className' => FileLog::class,\
        'path' => LOGS,\
        'levels' => [],\
        'scopes' => ['orders', 'payments'],\
        'file' => 'shops.log',\
    ]);
    
    // Configure logs/payments.log to receive all levels, but only
    // those with `payments` scope.
    Log::setConfig('payments', [\
        'className' => FileLog::class,\
        'path' => LOGS,\
        'levels' => [],\
        'scopes' => ['payments'],\
        'file' => 'payments.log',\
    ]);
    
    Log::warning('this gets written only to shops.log', ['scope' => ['orders']]);
    Log::warning('this gets written to both shops.log and payments.log', ['scope' => ['payments']]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  

Scopes can also be passed as a single string or a numerically indexed array. Note that using this form will limit the ability to pass more data as context:

    Log::warning('This is a warning', ['orders']);
    Log::warning('This is a warning', 'payments');

1  
2  

NOTE

When `scopes` is set to an empty array or `null` in a logger's configuration, it will take messages of any scope. Setting it to `false` will only match messages without scope.

Logging to Files [​](https://book.cakephp.org/6.x/core-libraries/logging.html#logging-to-files)

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

As its name implies `FileLog` writes log messages to files. The level of log message being written determines the name of the file the message is stored in. If a level is not supplied, `LOG_ERR` is used which writes to the error log. The default log location is **logs/$level.log**:

    // Executing this inside a CakePHP class
    $this->log("Something didn't work!");
    
    // Results in this being appended to logs/error.log
    // 2007-11-02 10:22:02 Error: Something didn't work!

1  
2  
3  
4  
5  

The configured directory must be writable by the web server user in order for logging to work correctly.

You can configure additional/alternate FileLog locations when configuring a logger. FileLog accepts a `path` which allows for custom paths to be used:

    Log::setConfig('custom_path', [\
        'className' => 'File',\
        'path' => '/path/to/custom/place/'\
    ]);

1  
2  
3  
4  

`FileLog` engine takes the following options:

*   `size` Used to implement basic log file rotation. If log file size reaches specified size the existing file is renamed by appending timestamp to filename and new log file is created. Can be integer bytes value or human readable string values like '10MB', '100KB' etc. Defaults to 10MB.
*   `rotate` Log files are rotated specified times before being removed. If value is 0, old versions are removed rather then rotated. Defaults to 10.
*   `mask` Set the file permissions for created files. If left empty the default permissions are used.

NOTE

Missing directories will be automatically created to avoid unnecessary errors thrown when using the FileEngine.

Logging to Syslog [​](https://book.cakephp.org/6.x/core-libraries/logging.html#logging-to-syslog)

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

In production environments it is highly recommended that you setup your system to use syslog instead of the file logger. This will perform much better as any writes will be done in a (almost) non-blocking fashion and your operating system logger can be configured separately to rotate files, pre-process writes or use a completely different storage for your logs.

Using syslog is pretty much like using the default FileLog engine, you just need to specify `Syslog` as the engine to be used for logging. The following configuration snippet will replace the default logger with syslog, this should be done in the **config/bootstrap.php** file:

    Log::setConfig('default', [\
        'engine' => 'Syslog'\
    ]);

1  
2  
3  

The configuration array accepted for the Syslog logging engine understands the following keys:

*   `format`: An sprintf template string with two placeholders, the first one for the error level, and the second for the message itself. This key is useful to add additional information about the server or process in the logged message. For example: `%s - Web Server 1 - %s` will look like `error - Web Server 1 - An error occurred in this request` after replacing the placeholders. This option is deprecated. You should use [Logging Formatters](https://book.cakephp.org/6.x/core-libraries/logging.html#logging-formatters)
     instead.
*   `prefix`: An string that will be prefixed to every logged message.
*   `flag`: An integer flag to be used for opening the connection to the logger, by default `LOG_ODELAY` will be used. See `openlog` documentation for more options
*   `facility`: The logging slot to use in syslog. By default `LOG_USER` is used. See `syslog` documentation for more options

Creating Log Engines [​](https://book.cakephp.org/6.x/core-libraries/logging.html#creating-log-engines)

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

Log engines can be part of your application, or part of plugins. If for example you had a database logger called `DatabaseLog`. As part of your application it would be placed in **src/Log/Engine/DatabaseLog.php**. As part of a plugin it would be placed in **plugins/LoggingPack/src/Log/Engine/DatabaseLog.php**. To configure log engine you should use `Cake\Log\Log::setConfig()`. For example configuring our DatabaseLog would look like:

    // For src/Log
    Log::setConfig('otherFile', [\
        'className' => 'Database',\
        'model' => 'LogEntry',\
        // ...\
    ]);
    
    // For plugin called LoggingPack
    Log::setConfig('otherFile', [\
        'className' => 'LoggingPack.Database',\
        'model' => 'LogEntry',\
        // ...\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

When configuring a log engine the `className` parameter is used to locate and load the log handler. All of the other configuration properties are passed to the log engine's constructor as an array. :

    namespace App\Log\Engine;
    use Cake\Log\Engine\BaseLog;
    
    class DatabaseLog extends BaseLog
    {
        public function __construct(array $config = [])
        {
            parent::__construct($config);
            // ...
        }
    
        public function log($level, string $message, array $context = [])
        {
            // Write to the database.
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  

CakePHP requires that all logging engine implement `Psr\Log\LoggerInterface`. The class `Cake\Log\Engine\BaseLog` is an easy way to satisfy the interface as it only requires you to implement the `log()` method.

Logging Formatters [​](https://book.cakephp.org/6.x/core-libraries/logging.html#logging-formatters)

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

Logging formatters allow you to control how log messages are formatted independent of the storage engine. Each core provided logging engine comes with a formatter configured to maintain backwards compatible output. However, you can adjust the formatters to fit your requirements. Formatters are configured alongside the logging engine:

    use Cake\Log\Engine\SyslogLog;
    use App\Log\Formatter\CustomFormatter;
    
    // Simple formatting configuration with no options.
    Log::setConfig('error', [\
        'className' => SyslogLog::class,\
        'formatter' => CustomFormatter::class,\
    ]);
    
    // Configure a formatter with additional options.
    Log::setConfig('error', [\
        'className' => SyslogLog::class,\
        'formatter' => [\
            'className' => CustomFormatter::class,\
            'key' => 'value',\
        ],\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

To implement your own logging formatter you need to extend `Cake\Log\Format\AbstractFormatter` or one of its subclasses. The primary method you need to implement is `format($level, $message, $context)` which is responsible for formatting log messages.

Testing Logs [​](https://book.cakephp.org/6.x/core-libraries/logging.html#testing-logs)

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

To test logging, add `Cake\TestSuite\LogTestTrait` to your test case. The `LogTestTrait` uses PHPUnit hooks to attach log engines that intercept the log messages your application is making. Once you have captured logs you can perform assertions on log messages your application is emitting. For example:

    namespace App\Test\TestCase\Controller;
    
    use Cake\TestSuite\LogTestTrait;
    use Cake\TestSuite\TestCase;
    
    class UsersControllerTest extends TestCase
    {
        use LogTestTrait;
    
        public function setUp(): void
        {
            parent::setUp();
            $this->setupLog([\
                'error' => ['scopes' => ['app.security']]\
            ]);
        }
    
        public function testResetPassword()
        {
            $this->post('/users/resetpassword', ['email' => '[email protected]']);
            $this->assertLogMessageContains('info', '[email protected] reset password', 'app.security');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  

You use `setupLog()` to define the log messages you wish to capture and perform assertions on. After logs have been emitted you can make assertions on the contents of logs, or the absence of them:

*   `assertLogMessage(string $level, string $expectedMessage, ?string $scope = null, string $failMsg = '')` Assert that a log message was found.
*   `assertLogMessageContains(string $level, string $expectedMessage, ?string $scope = null, string $failMsg = '')` Assert that a log message contains the substring.
*   `assertLogAbsent(string $level, ?string $failMsg = '')` Assert that no log messages of the given level were captured.

The `LogTestTrait` will automatically clean up any loggers that were configured.

Log API [​](https://book.cakephp.org/6.x/core-libraries/logging.html#log-api)

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

`class` Cake\\Log\\**Log**

### Log::setConfig() [​](https://book.cakephp.org/6.x/core-libraries/logging.html#log-setconfig)

`static` Cake\\Log\\Log::**setConfig**(array|string $key, $config = null): void

param string $name Name for the logger being connected, used to drop a logger later on.

param array $config Array of configuration information and constructor arguments for the logger.

Get or set the configuration for a Logger. See [Log Configuration](https://book.cakephp.org/6.x/core-libraries/logging.html#log-configuration)
 for more information.

### Log::configured() [​](https://book.cakephp.org/6.x/core-libraries/logging.html#log-configured)

`static` Cake\\Log\\Log::**configured**(): array

returns An array of configured loggers.

Get the names of the configured loggers.

### Log::drop() [​](https://book.cakephp.org/6.x/core-libraries/logging.html#log-drop)

`static` Cake\\Log\\Log::**drop**(string $name): bool

param string $name Name of the logger you wish to no longer receive messages.

### Log::write() [​](https://book.cakephp.org/6.x/core-libraries/logging.html#log-write)

`static` Cake\\Log\\Log::**write**(string|int $level, Stringable|string $message, array|string $context = \[\]): bool

Write a message into all the configured loggers. `$level` indicates the level of log message being created. `$message` is the message of the log entry being written to. `$context` is the scope(s) a log message is being created in.

### Log::levels() [​](https://book.cakephp.org/6.x/core-libraries/logging.html#log-levels)

`static` Cake\\Log\\Log::**levels**(): array

Call this method without arguments, eg: Log::levels() to obtain current level configuration.

### Convenience Methods [​](https://book.cakephp.org/6.x/core-libraries/logging.html#convenience-methods)

The following convenience methods were added to log $message with the appropriate log level.

#### Log::emergency() [​](https://book.cakephp.org/6.x/core-libraries/logging.html#log-emergency)

`static` Cake\\Log\\Log::**emergency**(Stringable|string $message, array|string $context = \[\]): bool

#### Log::alert() [​](https://book.cakephp.org/6.x/core-libraries/logging.html#log-alert)

`static` Cake\\Log\\Log::**alert**(Stringable|string $message, array|string $context = \[\]): bool

#### Log::critical() [​](https://book.cakephp.org/6.x/core-libraries/logging.html#log-critical)

`static` Cake\\Log\\Log::**critical**(Stringable|string $message, array|string $context = \[\]): bool

#### Log::error() [​](https://book.cakephp.org/6.x/core-libraries/logging.html#log-error)

`static` Cake\\Log\\Log::**error**(Stringable|string $message, array|string $context = \[\]): bool

#### Log::warning() [​](https://book.cakephp.org/6.x/core-libraries/logging.html#log-warning)

`static` Cake\\Log\\Log::**warning**(Stringable|string $message, array|string $context = \[\]): bool

#### Log::notice() [​](https://book.cakephp.org/6.x/core-libraries/logging.html#log-notice)

`static` Cake\\Log\\Log::**notice**(Stringable|string $message, array|string $context = \[\]): bool

#### Log::info() [​](https://book.cakephp.org/6.x/core-libraries/logging.html#log-info)

`static` Cake\\Log\\Log::**info**(Stringable|string $message, array|string $context = \[\]): bool

#### Log::debug() [​](https://book.cakephp.org/6.x/core-libraries/logging.html#log-debug)

`static` Cake\\Log\\Log::**debug**(Stringable|string $message, array|string $context = \[\]): bool

Logging Trait [​](https://book.cakephp.org/6.x/core-libraries/logging.html#logging-trait)

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

> A trait that provides shortcut methods for logging

### Log::log() [​](https://book.cakephp.org/6.x/core-libraries/logging.html#log-log)

`method` Cake\\Log\\Log::**log**($msg, $level = LOG\_ERR): bool

Using Monolog [​](https://book.cakephp.org/6.x/core-libraries/logging.html#using-monolog)

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

Monolog is a popular logger for PHP. Since it implements the same interfaces as the CakePHP loggers, you can use them in your application as the default logger.

After installing Monolog using composer, configure the logger using the `Log::setConfig()` method:

    // config/bootstrap.php
    
    use Monolog\Logger;
    use Monolog\Handler\StreamHandler;
    
    Log::setConfig('default', function () {
        $log = new Logger('app');
        $log->pushHandler(new StreamHandler('path/to/your/combined.log'));
    
        return $log;
    });
    
    // Optionally stop using the now redundant default loggers
    Log::drop('debug');
    Log::drop('error');

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

Use similar methods if you want to configure a different logger for your console:

    // config/bootstrap_cli.php
    
    use Monolog\Logger;
    use Monolog\Handler\StreamHandler;
    
    Log::setConfig('default', function () {
        $log = new Logger('cli');
        $log->pushHandler(new StreamHandler('path/to/your/combined-cli.log'));
    
        return $log;
    });
    
    // Optionally stop using the now redundant default CLI loggers
    Configure::delete('Log.debug');
    Configure::delete('Log.error');

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

NOTE

When using a console specific logger, make sure to conditionally configure your application logger. This will prevent duplicate log entries.

---

# Text | CakePHP

[Skip to content](https://book.cakephp.org/6.x/core-libraries/text.html#VPContent)

Return to top

Text [​](https://book.cakephp.org/6.x/core-libraries/text.html#text)

=====================================================================

`class` Cake\\Utility\\**Text**

The Text class includes convenience methods for creating and manipulating strings and is normally accessed statically. Example: `Text::uuid()`.

If you need `Cake\View\Helper\TextHelper` functionalities outside of a `View`, use the `Text` class:

    namespace App\Controller;
    
    use Cake\Utility\Text;
    
    class UsersController extends AppController
    {
        public function initialize(): void
        {
            parent::initialize();
            $this->loadComponent('Auth')
        };
    
        public function afterLogin()
        {
            $message = $this->Users->find('new_message')->first();
            if (!empty($message)) {
                // Notify user of new message
                $this->Flash->success(__(
                    'You have a new message: {0}',
                    Text::truncate($message['Message']['body'], 255, ['html' => true])
                ));
            }
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  

Convert Strings into ASCII [​](https://book.cakephp.org/6.x/core-libraries/text.html#convert-strings-into-ascii)

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

### Text::transliterate() [​](https://book.cakephp.org/6.x/core-libraries/text.html#text-transliterate)

`static` Cake\\Utility\\Text::**transliterate**($string, $transliteratorId = null): string

Transliterate by default converts all characters in provided string into equivalent ASCII characters. The method expects UTF-8 encoding. The character conversion can be controlled using transliteration identifiers which you can pass using the `$transliteratorId` argument or change the default identifier string using `Text::setTransliteratorId()`. ICU transliteration identifiers are basically of form `<source script>:<target script>` and you can specify multiple conversion pairs separated by `;`. You can find more info about transliterator identifiers [here](https://unicode-org.github.io/icu/userguide/transforms/general/#transliterator-identifiers)
:

    // apple puree
    Text::transliterate('apple purée');
    
    // Ubermensch (only latin characters are transliterated)
    Text::transliterate('Übérmensch', 'Latin-ASCII;');

1  
2  
3  
4  
5  

Creating URL Safe Strings [​](https://book.cakephp.org/6.x/core-libraries/text.html#creating-url-safe-strings)

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

### Text::slug() [​](https://book.cakephp.org/6.x/core-libraries/text.html#text-slug)

`static` Cake\\Utility\\Text::**slug**(string $string, array|string $options = \[\]): string

Slug transliterates all characters into ASCII versions and converting unmatched characters and spaces to dashes. The slug method expects UTF-8 encoding.

You can provide an array of options that controls slug. `$options` can also be a string in which case it will be used as replacement string. The supported options are:

*   `replacement` Replacement string, defaults to '-'.
    
*   `transliteratorId` A valid tranliterator id string. If default `null``Text::$_defaultTransliteratorId` to be used. If `false` no transliteration will be done, only non words will be removed.
    
*   `preserve` Specific non-word character to preserve. Defaults to `null`. For example, this option can be set to '.' to generate clean file names:
    
        // apple-puree
        Text::slug('apple purée');
        
        // apple_puree
        Text::slug('apple purée', '_');
        
        // foo-bar.tar.gz
        Text::slug('foo bar.tar.gz', ['preserve' => '.']);
    
    1  
    2  
    3  
    4  
    5  
    6  
    7  
    8  
    

Generating UUIDs [​](https://book.cakephp.org/6.x/core-libraries/text.html#generating-uuids)

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

### Text::uuid() [​](https://book.cakephp.org/6.x/core-libraries/text.html#text-uuid)

`static` Cake\\Utility\\Text::**uuid**(): string

The UUID method is used to generate unique identifiers as per `4122`. The UUID is a 128-bit string in the format of `485fc381-e790-47a3-9794-1337c0a8fe68`. :

    Text::uuid(); // 485fc381-e790-47a3-9794-1337c0a8fe68

1  

Added in version 5.3.0

You can now configure a custom UUID generator using dependency injection.

Starting from CakePHP 5.3.0, you can configure a custom UUID generator by setting a closure in your configuration:

    // In your config/app.php or config/bootstrap.php
    use Cake\Core\Configure;
    
    Configure::write('Text.uuidGenerator', function () {
        // Return your custom UUID string
        return \MyUuidLibrary::generate();
    });

1  
2  
3  
4  
5  
6  
7  

This allows you to integrate your own UUID generation strategy or use third-party UUID libraries. When a custom generator is configured, it will be used instead of the default UUID generation method.

Simple String Parsing [​](https://book.cakephp.org/6.x/core-libraries/text.html#simple-string-parsing)

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

### Text::tokenize() [​](https://book.cakephp.org/6.x/core-libraries/text.html#text-tokenize)

`static` Cake\\Utility\\Text::**tokenize**(string $data, string $separator = ',', string $leftBound = '(', string $rightBound = ')'): array

Tokenizes a string using `$separator`, ignoring any instance of `$separator` that appears between `$leftBound` and `$rightBound`.

This method can be useful when splitting up data that has regular formatting such as tag lists:

    $data = "cakephp 'great framework' php";
    $result = Text::tokenize($data, ' ', "'", "'");
    // Result contains
    ['cakephp', "'great framework'", 'php'];

1  
2  
3  
4  

### Text::parseFileSize() [​](https://book.cakephp.org/6.x/core-libraries/text.html#text-parsefilesize)

`method` Cake\\Utility\\Text::**parseFileSize**(string $size, mixed $default = false): mixed

This method unformats a number from a human-readable byte size to an integer number of bytes:

    $int = Text::parseFileSize('2GB');

1  

Formatting Strings [​](https://book.cakephp.org/6.x/core-libraries/text.html#formatting-strings)

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

### Text::insert() [​](https://book.cakephp.org/6.x/core-libraries/text.html#text-insert)

`static` Cake\\Utility\\Text::**insert**(string $str, array $data, array $options = \[\]): string

The insert method is used to create string templates and to allow for key/value replacements:

    Text::insert(
        'My name is :name and I am :age years old.',
        ['name' => 'Bob', 'age' => '65']
    );
    // Returns: "My name is Bob and I am 65 years old."

1  
2  
3  
4  
5  

### Text::cleanInsert() [​](https://book.cakephp.org/6.x/core-libraries/text.html#text-cleaninsert)

`static` Cake\\Utility\\Text::**cleanInsert**(string $str, array $options): string

Cleans up a `Text::insert` formatted string with given `$options` depending on the 'clean' key in `$options`. The default method used is text but html is also available. The goal of this function is to replace all whitespace and unneeded markup around placeholders that did not get replaced by `Text::insert`.

You can use the following options in the options array:

    $options = [\
        'clean' => [\
            'method' => 'text', // or html\
        ],\
        'before' => '',\
        'after' => ''\
    ];

1  
2  
3  
4  
5  
6  
7  

Wrapping Text [​](https://book.cakephp.org/6.x/core-libraries/text.html#wrapping-text)

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

### Text::wrap() [​](https://book.cakephp.org/6.x/core-libraries/text.html#text-wrap)

`static` Cake\\Utility\\Text::**wrap**(string $text, array|int $options = \[\]): string

Wraps a block of text to a set width and indents blocks as well. Can intelligently wrap text so words are not sliced across lines:

    $text = 'This is the song that never ends.';
    $result = Text::wrap($text, 22);
    
    // Returns
    This is the song that
    never ends.

1  
2  
3  
4  
5  
6  

You can provide an array of options that control how wrapping is done. The supported options are:

*   `width` The width to wrap to. Defaults to 72.
*   `wordWrap` Whether or not to wrap whole words. Defaults to `true`.
*   `indent` The character to indent lines with. Defaults to ''.
*   `indentAt` The line number to start indenting text. Defaults to 0.

### Text::wrapBlock() [​](https://book.cakephp.org/6.x/core-libraries/text.html#text-wrapblock)

`static` Cake\\Utility\\Text::**wrapBlock**(string $text, array|int $options = \[\]): string

If you need to ensure that the total width of the generated block won't exceed a certain length even with internal indentation, you need to use `wrapBlock()` instead of `wrap()`. This is particularly useful to generate text for the console for example. It accepts the same options as `wrap()`:

    $text = 'This is the song that never ends. This is the song that never ends.';
    $result = Text::wrapBlock($text, [\
        'width' => 22,\
        'indent' => ' → ',\
        'indentAt' => 1\
    ]);
    
    // Returns
    This is the song that
     → never ends. This
     → is the song that
     → never ends.

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

Highlighting Substrings [​](https://book.cakephp.org/6.x/core-libraries/text.html#highlighting-substrings)

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

### Text::highlight() [​](https://book.cakephp.org/6.x/core-libraries/text.html#text-highlight)

`method` Cake\\Utility\\Text::**highlight**(string $text, array|string $phrase, array $options = \[\]): string

Highlights `$phrase` in `$text` using the `$options['format']` string specified or a default string.

Options:

*   `format` string - The piece of HTML with the phrase that will be highlighted
*   `html` bool - If `true`, will ignore any HTML tags, ensuring that only the correct text is highlighted

Example:

    // Called as TextHelper
    echo $this->Text->highlight(
        $lastSentence,
        'using',
        ['format' => '<span class="highlight">\1</span>']
    );
    
    // Called as Text
    use Cake\Utility\Text;
    
    echo Text::highlight(
        $lastSentence,
        'using',
        ['format' => '<span class="highlight">\1</span>']
    );

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

Output:

> Highlights $phrase in $text <span class="highlight">using</span> the $options\['format'\] string specified or a default string.

Truncating Text [​](https://book.cakephp.org/6.x/core-libraries/text.html#truncating-text)

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

### Text::truncate() [​](https://book.cakephp.org/6.x/core-libraries/text.html#text-truncate)

`method` Cake\\Utility\\Text::**truncate**(string $text, int $length = 100, array $options = \[\]): string

If `$text` is longer than `$length`, this method truncates it at `$length` and adds a suffix consisting of `'ellipsis'`, if defined. If `'exact'` is passed as `false`, the truncation will occur at the first whitespace after the point at which `$length` is exceeded. If `'html'` is passed as `true`, HTML tags will be respected and will not be cut off.

`$options` is used to pass all extra parameters, and has the following possible keys by default, all of which are optional:

    [\
        'ellipsis' => '...',\
        'exact' => true,\
        'html' => false\
    ]

1  
2  
3  
4  
5  

Example:

    // Called as TextHelper
    echo $this->Text->truncate(
        'The killer crept forward and tripped on the rug.',
        22,
        [\
            'ellipsis' => '...',\
            'exact' => false\
        ]
    );
    
    // Called as Text
    use Cake\Utility\Text;
    
    echo Text::truncate(
        'The killer crept forward and tripped on the rug.',
        22,
        [\
            'ellipsis' => '...',\
            'exact' => false\
        ]
    );

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  

Output:

    The killer crept...
    

Truncating the Tail of a String [​](https://book.cakephp.org/6.x/core-libraries/text.html#truncating-the-tail-of-a-string)

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

### Text::tail() [​](https://book.cakephp.org/6.x/core-libraries/text.html#text-tail)

`method` Cake\\Utility\\Text::**tail**(string $text, int $length = 100, array $options = \[\]): string

If `$text` is longer than `$length`, this method removes an initial substring with length consisting of the difference and prepends a prefix consisting of `'ellipsis'`, if defined. If `'exact'` is passed as `false`, the truncation will occur at the first whitespace prior to the point at which truncation would otherwise take place.

`$options` is used to pass all extra parameters, and has the following possible keys by default, all of which are optional:

    [\
        'ellipsis' => '...',\
        'exact' => true\
    ]

1  
2  
3  
4  

Example:

    $sampleText = 'I packed my bag and in it I put a PSP, a PS3, a TV, ' .
        'a C# program that can divide by zero, death metal t-shirts'
    
    // Called as TextHelper
    echo $this->Text->tail(
        $sampleText,
        70,
        [\
            'ellipsis' => '...',\
            'exact' => false\
        ]
    );
    
    // Called as Text
    use Cake\Utility\Text;
    
    echo Text::tail(
        $sampleText,
        70,
        [\
            'ellipsis' => '...',\
            'exact' => false\
        ]
    );

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  

Output:

    ...a TV, a C# program that can divide by zero, death metal t-shirts
    

Extracting an Excerpt [​](https://book.cakephp.org/6.x/core-libraries/text.html#extracting-an-excerpt)

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

### Text::excerpt() [​](https://book.cakephp.org/6.x/core-libraries/text.html#text-excerpt)

`method` Cake\\Utility\\Text::**excerpt**(string $text, string $phrase, int $radius = 100, string $ellipsis = '…'): string

Extracts an excerpt from `$text` surrounding the `$phrase` with a number of characters on each side determined by `$radius`, and prefix/suffix with `$ellipsis`. This method is especially handy for search results. The query string or keywords can be shown within the resulting document. :

    // Called as TextHelper
    echo $this->Text->excerpt($lastParagraph, 'method', 50, '...');
    
    // Called as Text
    use Cake\Utility\Text;
    
    echo Text::excerpt($lastParagraph, 'method', 50, '...');

1  
2  
3  
4  
5  
6  
7  

Output:

    ... by $radius, and prefix/suffix with $ellipsis. This method is especially
    handy for search results. The query...
    

Converting an Array to Sentence Form [​](https://book.cakephp.org/6.x/core-libraries/text.html#converting-an-array-to-sentence-form)

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

### Text::toList() [​](https://book.cakephp.org/6.x/core-libraries/text.html#text-tolist)

`method` Cake\\Utility\\Text::**toList**(array $list, ?string $and = null, $separator = ', '): string

Creates a comma-separated list where the last two items are joined with 'and':

    $colors = ['red', 'orange', 'yellow', 'green', 'blue', 'indigo', 'violet'];
    
    // Called as TextHelper
    echo $this->Text->toList($colors);
    
    // Called as Text
    use Cake\Utility\Text;
    
    echo Text::toList($colors);

1  
2  
3  
4  
5  
6  
7  
8  
9  

Output:

    red, orange, yellow, green, blue, indigo and violet

---

# Translate | CakePHP

[Skip to content](https://book.cakephp.org/6.x/orm/behaviors/translate.html#VPContent)

Return to top

Translate [​](https://book.cakephp.org/6.x/orm/behaviors/translate.html#translate)

===================================================================================

`class` Cake\\ORM\\Behavior\\**TranslateBehavior**

The Translate behavior allows you to create and retrieve translated copies of your entities in multiple languages.

WARNING

The TranslateBehavior does not support composite primary keys at this point in time.

Translation Strategies [​](https://book.cakephp.org/6.x/orm/behaviors/translate.html#translation-strategies)

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

The behavior offers two strategies for how the translations are stored.

1.  Shadow table Strategy: This strategy uses a separate "shadow table" for each Table object to store translation of all translated fields of that table. This is the default strategy.
2.  Eav Strategy: This strategy uses a `i18n` table where it stores the translation for each of the fields of any given Table object that it's bound to.

Shadow Table Strategy [​](https://book.cakephp.org/6.x/orm/behaviors/translate.html#shadow-table-strategy)

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

Let's assume we have an `articles` table and we want it's `title` and `body` fields to be translated. For that we create a shadow table `articles_translations`:

    CREATE TABLE `articles_translations` (
        `id` int(11) NOT NULL,
        `locale` varchar(5) NOT NULL,
        `title` varchar(255),
        `body` text,
        PRIMARY KEY (`id`,`locale`)
    );

1  
2  
3  
4  
5  
6  
7  

The shadow table needs `id` and `locale` columns which together form the primary key and other columns with same name as primary table which need to be translated.

A note on language abbreviations: The Translate Behavior doesn't impose any restrictions on the language identifier, the possible values are only restricted by the `locale` column type/size. `locale` is defined as `varchar(6)` in case you want to use abbreviations like `es-419` (Spanish for Latin America, language abbreviation with area code [UN M.49](https://en.wikipedia.org/wiki/UN_M.49)
).

TIP

It's wise to use the same language abbreviations as required for [Internationalization and Localization](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html)
. Thus you are consistent and switching the language works identical for both, the `Translate` behavior and `Internationalization and Localization`.

So it's recommended to use either the two letter ISO code of the language like `en`, `fr`, `de` or the full locale name such as `fr_FR`, `es_AR`, `da_DK` which contains both the language and the country where it is spoken.

Eav Strategy [​](https://book.cakephp.org/6.x/orm/behaviors/translate.html#eav-strategy)

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

In order to use the Eav strategy, you need to create a `i18n` table with the correct schema. Currently the only way of loading the `i18n` table is by manually running the following SQL script in your database:

    CREATE TABLE i18n (
        id int NOT NULL auto_increment,
        locale varchar(6) NOT NULL,
        model varchar(255) NOT NULL,
        foreign_key int(10) NOT NULL,
        field varchar(255) NOT NULL,
        content text,
        PRIMARY KEY (id),
        UNIQUE INDEX I18N_LOCALE_FIELD(locale, model, foreign_key, field),
        INDEX I18N_FIELD(model, foreign_key, field)
    );

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

The schema is also available as sql file in **/config/schema/i18n.sql**.

Attaching the Translate Behavior to Your Tables [​](https://book.cakephp.org/6.x/orm/behaviors/translate.html#attaching-the-translate-behavior-to-your-tables)

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

Attaching the behavior can be done in the `initialize()` method in your Table class:

    class ArticlesTable extends Table
    {
        public function initialize(array $config): void
        {
            // By default ShadowTable will be used.
            $this->addBehavior('Translate', ['fields' => ['title', 'body']]);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  

For shadow table strategy specifying the `fields` key is optional as the behavior can infer the fields from the shadow table columns.

If you want to use the `EavStrategy` then you can configure the behavior as:

    class ArticlesTable extends Table
    {
        public function initialize(array $config): void
        {
            $this->addBehavior('Translate', [\
                'strategyClass' => \Cake\ORM\Behavior\Translate\EavStrategy::class,\
                'fields' => ['title', 'body'],\
            ]);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

For `EavStrategy` you are required to pass the `fields` key in the configuration array. This list of fields is needed to tell the behavior what columns will be able to store translations.

By default the locale specified in `App.defaultLocale` config is used as default locale for the `TranslateBehavior`. You can override that by setting `defaultLocale` config of the behavior:

    class ArticlesTable extends Table
    {
        public function initialize(array $config): void
        {
            $this->addBehavior('Translate', [\
                'defaultLocale' => 'en_GB',\
            ]);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  

Quick tour [​](https://book.cakephp.org/6.x/orm/behaviors/translate.html#quick-tour)

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

Regardless of the datastructure strategy you choose the behavior provides the same API to manage translations.

Now, select a language to be used for retrieving entities by changing the application language, which will affect all translations:

    // In the Articles controller. Change the locale to Spanish, for example
    I18n::setLocale('es');

1  
2  

Then, get an existing entity:

    $article = $this->Articles->get(12);
    echo $article->title; // Echoes 'A title', not translated yet

1  
2  

Next, translate your entity:

    $article->title = 'Un Artículo';
    $this->Articles->save($article);

1  
2  

You can try now getting your entity again:

    $article = $this->Articles->get(12);
    echo $article->title; // Echoes 'Un Artículo', yay piece of cake!

1  
2  

Working with multiple translations can be done by using a special trait in your Entity class:

    use Cake\ORM\Behavior\Translate\TranslateTrait;
    use Cake\ORM\Entity;
    
    class Article extends Entity
    {
        use TranslateTrait;
    }

1  
2  
3  
4  
5  
6  
7  

Now you can find all translations for a single entity:

    $article = $this->Articles->find('translations')->first();
    echo $article->translation('es')->title; // 'Un Artículo'
    
    echo $article->translation('en')->title; // 'An Article';

1  
2  
3  
4  

And save multiple translations at once:

    $article->translation('es')->title = 'Otro Título';
    $article->translation('fr')->title = 'Un autre Titre';
    $this->Articles->save($article);

1  
2  
3  

If you want to go deeper on how it works or how to tune the behavior for your needs, keep on reading the rest of this chapter.

### Using a Separate Translations Table for Eav strategy [​](https://book.cakephp.org/6.x/orm/behaviors/translate.html#using-a-separate-translations-table-for-eav-strategy)

If you wish to use a table other than `i18n` for translating a particular repository, you can specify the name of the table class name for your custom table in the behavior's configuration. This is common when you have multiple tables to translate and you want a cleaner separation of the data that is stored for each different table:

    class ArticlesTable extends Table
    {
        public function initialize(array $config): void
        {
            $this->addBehavior('Translate', [\
                'fields' => ['title', 'body'],\
                'translationTable' => 'ArticlesI18n',\
            ]);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

You need to make sure that any custom table you use has the columns `field`, `foreign_key`, `locale` and `model`.

Reading Translated Content [​](https://book.cakephp.org/6.x/orm/behaviors/translate.html#reading-translated-content)

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

As shown above you can use the `setLocale()` method to choose the active translation for entities that are loaded:

    // Load I18n core functions at the beginning of your Articles Controller:
    use Cake\I18n\I18n;
    
    // Then you can change the language in your action:
    I18n::setLocale('es');
    
    // All entities in results will contain spanish translation
    $results = $this->Articles->find()->all();

1  
2  
3  
4  
5  
6  
7  
8  

This method works with any finder in your tables. For example, you can use TranslateBehavior with `find('list')`:

    I18n::setLocale('es');
    $data = $this->Articles->find('list')->toArray();
    
    // Data will contain
    [1 => 'Mi primer artículo', 2 => 'El segundo artículo', 15 => 'Otro articulo' ...]
    
    // Change the locale to french for a single find call
    $data = $this->Articles->find('list', locale: 'fr')->toArray();

1  
2  
3  
4  
5  
6  
7  
8  

### Retrieve All Translations For An Entity [​](https://book.cakephp.org/6.x/orm/behaviors/translate.html#retrieve-all-translations-for-an-entity)

When building interfaces for updating translated content, it is often helpful to show one or more translation(s) at the same time. You can use the `translations` finder for this:

    // Find the first article with all corresponding translations
    $article = $this->Articles->find('translations')->first();

1  
2  

In the example above you will get a list of entities back that have a `_translations` property set. This property will contain a list of translation data entities. For example the following properties would be accessible:

    // Outputs 'en'
    echo $article->_translations['en']->locale;
    
    // Outputs 'title'
    echo $article->_translations['en']->field;
    
    // Outputs 'My awesome post!'
    echo $article->_translations['en']->body;

1  
2  
3  
4  
5  
6  
7  
8  

A more elegant way for dealing with this data is by adding a trait to the entity class that is used for your table:

    use Cake\ORM\Behavior\Translate\TranslateTrait;
    use Cake\ORM\Entity;
    
    class Article extends Entity
    {
        use TranslateTrait;
    }

1  
2  
3  
4  
5  
6  
7  

This trait contains a single method called `translation`, which lets you access or create new translation entities on the fly:

    // Outputs 'title'
    echo $article->translation('en')->title;
    
    // Adds a new translation data entity to the article
    $article->translation('de')->title = 'Wunderbar';

1  
2  
3  
4  
5  

### Limiting the Translations to be Retrieved [​](https://book.cakephp.org/6.x/orm/behaviors/translate.html#limiting-the-translations-to-be-retrieved)

You can limit the languages that are fetched from the database for a particular set of records:

    $results = $this->Articles->find('translations', locales: ['en', 'es']);
    $article = $results->first();
    $spanishTranslation = $article->translation('es');
    $englishTranslation = $article->translation('en');

1  
2  
3  
4  

### Preventing Retrieval of Empty Translations [​](https://book.cakephp.org/6.x/orm/behaviors/translate.html#preventing-retrieval-of-empty-translations)

Translation records can contain any string, if a record has been translated and stored as an empty string ('') the translate behavior will take and use this to overwrite the original field value.

If this is undesired, you can ignore translations which are empty using the `allowEmptyTranslations` config key:

    class ArticlesTable extends Table
    {
        public function initialize(array $config): void
        {
            $this->addBehavior('Translate', [\
                'fields' => ['title', 'body'],\
                'allowEmptyTranslations' => false\
            ]);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

The above would only load translated data that had content.

### Retrieving All Translations For Associations [​](https://book.cakephp.org/6.x/orm/behaviors/translate.html#retrieving-all-translations-for-associations)

It is also possible to find translations for any association in a single find operation:

    $article = $this->Articles->find('translations')->contain([\
        'Categories' => function ($query) {\
            return $query->find('translations');\
        }\
    ])->first();
    
    // Outputs 'Programación'
    echo $article->categories[0]->translation('es')->name;

1  
2  
3  
4  
5  
6  
7  
8  

This assumes that `Categories` has the TranslateBehavior attached to it. It simply uses the query builder function for the `contain` clause to use the `translations` custom finder in the association.

### Retrieving one language without using I18n::setLocale [​](https://book.cakephp.org/6.x/orm/behaviors/translate.html#retrieving-one-language-without-using-i18n-setlocale)

calling `I18n::setLocale('es');` changes the default locale for all translated finds, there may be times you wish to retrieve translated content without modifying the application's state. For these scenarios use the behavior's `setLocale()` method:

    I18n::setLocale('en'); // reset for illustration
    
    // specific locale.
    $this->Articles->getBehavior('Translate')->setLocale('es');
    
    $article = $this->Articles->get(12);
    echo $article->title; // Echoes 'Un Artículo', yay piece of cake!
    

Note that this only changes the locale of the Articles table, it would not affect the language of associated data. To affect associated data it's necessary to call the method on each table, for example:

    I18n::setLocale('en'); // reset for illustration
    
    $this->Articles->getBehavior('Translate')->setLocale('es');
    $this->Articles->Categories->getBehavior('Translate')->setLocale('es');
    
    $data = $this->Articles->find('all', contain: ['Categories']);

1  
2  
3  
4  
5  
6  

This example also assumes that `Categories` has the TranslateBehavior attached to it.

### Querying Translated Fields [​](https://book.cakephp.org/6.x/orm/behaviors/translate.html#querying-translated-fields)

TranslateBehavior does not substitute find conditions by default. You need to use `translationField()` method to compose find conditions on translated fields:

    $this->Articles->getBehavior('Translate')->setLocale('es');
    $query = $this->Articles->find()->where([\
        $this->Articles->getBehavior('Translate')->translationField('title') => 'Otro Título'\
    ]);

1  
2  
3  
4  

Saving in Another Language [​](https://book.cakephp.org/6.x/orm/behaviors/translate.html#saving-in-another-language)

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

The philosophy behind the TranslateBehavior is that you have an entity representing the default language, and multiple translations that can override certain fields in such entity. Keeping this in mind, you can intuitively save translations for any given entity. For example, given the following setup:

    // in src/Model/Table/ArticlesTable.php
    class ArticlesTable extends Table
    {
        public function initialize(array $config): void
        {
            $this->addBehavior('Translate', ['fields' => ['title', 'body']]);
        }
    }
    
    // in src/Model/Entity/Article.php
    class Article extends Entity
    {
        use TranslateTrait;
    }
    
    // In the Articles Controller
    $article = new Article([\
        'title' => 'My First Article',\
        'body' => 'This is the content',\
        'footnote' => 'Some afterwords'\
    ]);
    
    $this->Articles->save($article);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  

So, after you save your first article, you can now save a translation for it, there are a couple ways to do it. The first one is setting the language directly into the entity:

    $article->_locale = 'es';
    $article->title = 'Mi primer Artículo';
    
    $this->Articles->save($article);

1  
2  
3  
4  

After the entity has been saved, the translated field will be persisted as well, one thing to note is that values from the default language that were not overridden will be preserved:

    // Outputs 'This is the content'
    echo $article->body;
    
    // Outputs 'Mi primer Artículo'
    echo $article->title;

1  
2  
3  
4  
5  

Once you override the value, the translation for that field will be saved and can be retrieved as usual:

    $article->body = 'El contendio';
    $this->Articles->save($article);

1  
2  

The second way to use for saving entities in another language is to set the default language directly to the table:

    $article->title = 'Mi Primer Artículo';
    
    $this->Articles->getBehavior('Translate')->setLocale('es');
    $this->Articles->save($article);

1  
2  
3  
4  

Setting the language directly in the table is useful when you need to both retrieve and save entities for the same language or when you need to save multiple entities at once.

Saving Multiple Translations [​](https://book.cakephp.org/6.x/orm/behaviors/translate.html#saving-multiple-translations)

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

It is a common requirement to be able to add or edit multiple translations to any database record at the same time. This can be done using the `TranslateTrait`:

    use Cake\ORM\Behavior\Translate\TranslateTrait;
    use Cake\ORM\Entity;
    
    class Article extends Entity
    {
        use TranslateTrait;
    }

1  
2  
3  
4  
5  
6  
7  

Now, You can populate translations before saving them:

    $translations = [\
        'fr' => ['title' => "Un article"],\
        'es' => ['title' => 'Un artículo'],\
    ];
    
    foreach ($translations as $lang => $data) {
        $article->translation($lang)->set($data, ['guard' => false]);
    }
    
    $this->Articles->save($article);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

And create form controls for your translated fields:

    // In a view template.
    <?= $this->Form->create($article); ?>
    <fieldset>
        <legend>French</legend>
        <?= $this->Form->control('_translations.fr.title'); ?>
        <?= $this->Form->control('_translations.fr.body'); ?>
    </fieldset>
    <fieldset>
        <legend>Spanish</legend>
        <?= $this->Form->control('_translations.es.title'); ?>
        <?= $this->Form->control('_translations.es.body'); ?>
    </fieldset>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

In your controller, you can marshal the data as normal:

    $article = $this->Articles->newEntity($this->request->getData());
    $this->Articles->save($article);

1  
2  

This will result in your article, the french and spanish translations all being persisted. You'll need to remember to add `_translations` into the `$_accessible` fields of your entity as well.

### Validating Translated Entities [​](https://book.cakephp.org/6.x/orm/behaviors/translate.html#validating-translated-entities)

When attaching `TranslateBehavior` to a model, you can define the validator that should be used when translation records are created/modified by the behavior during `newEntity()` or `patchEntity()`:

    class ArticlesTable extends Table
    {
        public function initialize(array $config): void
        {
            $this->addBehavior('Translate', [\
                'fields' => ['title'],\
                'validator' => 'translated',\
            ]);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

The above will use the validator created by `validationTranslated` to validated translated entities.

---

# Checking HTTP Cache | CakePHP

[Skip to content](https://book.cakephp.org/6.x/controllers/components/check-http-cache.html#VPContent)

Return to top

Checking HTTP Cache [​](https://book.cakephp.org/6.x/controllers/components/check-http-cache.html#checking-http-cache)

=======================================================================================================================

`class` **CheckHttpCacheComponent**(ComponentCollection $collection, array $config = \[\])

The HTTP cache validation model is one of the processes used for cache gateways, also known as reverse proxies, to determine if they can serve a stored copy of a response to the client. Under this model, you mostly save bandwidth, but when used correctly you can also save some CPU processing, reducing response times:

    // in a Controller
    public function initialize(): void
    {
        parent::initialize();
    
        $this->addComponent('CheckHttpCache');
    }

1  
2  
3  
4  
5  
6  
7  

Enabling the `CheckHttpCacheComponent` in your controller automatically activates a `beforeRender` check. This check compares caching headers set in the response object to the caching headers sent in the request to determine whether the response was not modified since the last time the client asked for it. The following request headers are used:

*   `If-None-Match` is compared with the response's `Etag` header.
*   `If-Modified-Since` is compared with the response's `Last-Modified` header.

If response headers match the request header criteria, then view rendering is skipped. This saves your application generating a view, saving bandwidth and time. When response headers match, an empty response is returned with a `304 Not Modified` status code.

---

# Command Input/Output | CakePHP

[Skip to content](https://book.cakephp.org/6.x/console-commands/input-output.html#VPContent)

Return to top

Command Input/Output [​](https://book.cakephp.org/6.x/console-commands/input-output.html#command-input-output)

===============================================================================================================

`class` Cake\\Console\\**ConsoleIo**

CakePHP provides the `ConsoleIo` object to commands so that they can interactively read user input and output information to the user.

Command Helpers [​](https://book.cakephp.org/6.x/console-commands/input-output.html#command-helpers)

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

Formatting console output can be tedious and lead to maintenance issues. To enable better re-use and testability of console formatting code, CakePHP command helpers provide 'macros' for console formatting logic. Command Helpers can be accessed and used from any command:

    // Output some data as a table.
    $io->helper('Table')->output($data);
    
    // Get a helper from a plugin.
    $io->helper('Plugin.HelperName')->output($data);

1  
2  
3  
4  
5  

You can also get instances of helpers and call any public methods, to manipulate state and generate updated output:

    // Get and use the Progress Helper.
    $progress = $io->helper('Progress');
    $progress->increment(10);
    $progress->draw();

1  
2  
3  
4  

Creating Helpers [​](https://book.cakephp.org/6.x/console-commands/input-output.html#creating-helpers)

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

While CakePHP comes with a few command helpers you can create more in your application or plugins. As an example, we'll create a simple helper to generate fancy headings. First create the **src/Command/Helper/HeadingHelper.php** and put the following in it:

    <?php
    namespace App\Command\Helper;
    
    use Cake\Console\Helper;
    
    class HeadingHelper extends Helper
    {
        public function output($args)
        {
            $args += ['', '#', 3];
            $marker = str_repeat($args[1], $args[2]);
            $this->_io->out($marker . ' ' . $args[0] . ' ' . $marker);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

We can then use this new helper in one of our shell commands by calling it:

    // With ### on either side
    $this->helper('Heading')->output(['It works!']);
    
    // With ~~~~ on either side
    $this->helper('Heading')->output(['It works!', '~', 4]);

1  
2  
3  
4  
5  

Helpers generally implement the `output()` method which takes an array of parameters. However, because Console Helpers are vanilla classes they can implement additional methods that take any form of arguments.

NOTE

Helpers can also live in `src/Shell/Helper` for backwards compatibility.

Built-In Helpers [​](https://book.cakephp.org/6.x/console-commands/input-output.html#built-in-helpers)

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

### Table Helper [​](https://book.cakephp.org/6.x/console-commands/input-output.html#table-helper)

The TableHelper assists in making well formatted ASCII art tables. Using it is pretty simple:

    $data = [\
        ['Header 1', 'Header', 'Long Header'],\
        ['short', 'Longish thing', 'short'],\
        ['Longer thing', 'short', 'Longest Value'],\
    ];
    $io->helper('Table')->output($data);
    
    // Outputs
    +--------------+---------------+---------------+
    | Header 1     | Header        | Long Header   |
    +--------------+---------------+---------------+
    | short        | Longish thing | short         |
    | Longer thing | short         | Longest Value |
    +--------------+---------------+---------------+

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

You can use the `<text-right>` formatting tag in tables to right align content:

    $data = [\
        ['Name', 'Total Price'],\
        ['Cake Mix', '<text-right>1.50</text-right>'],\
    ];
    $io->helper('Table')->output($data);
    
    // Outputs
    +----------+-------------+
    | Name 1   | Total Price |
    +----------+-------------+
    | Cake Mix |        1.50 |
    +----------+-------------+

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

### Progress Helper [​](https://book.cakephp.org/6.x/console-commands/input-output.html#progress-helper)

The ProgressHelper can be used in two different ways. The simple mode lets you provide a callback that is invoked until the progress is complete:

    $io->helper('Progress')->output(['callback' => function ($progress) {\
        // Do work here.\
        $progress->increment(20);\
        $progress->draw();\
    }]);

1  
2  
3  
4  
5  

You can control the progress bar more by providing additional options:

*   `total` The total number of items in the progress bar. Defaults to 100.
*   `width` The width of the progress bar. Defaults to 80.
*   `callback` The callback that will be called in a loop to advance the progress bar.

An example of all the options in use would be:

    $io->helper('Progress')->output([\
        'total' => 10,\
        'width' => 20,\
        'callback' => function ($progress) {\
            $progress->increment(2);\
            $progress->draw();\
        }\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  

The progress helper can also be used manually to increment and re-render the progress bar as necessary:

    $progress = $io->helper('Progress');
    $progress->init([\
        'total' => 10,\
        'width' => 20,\
    ]);
    
    $progress->increment(4);
    $progress->draw();

1  
2  
3  
4  
5  
6  
7  
8  

### Banner Helper [​](https://book.cakephp.org/6.x/console-commands/input-output.html#banner-helper)

The `BannerHelper` can be used to format one or more lines of text into a banner with a background and horizontal padding:

    $io->helper('Banner')
        ->withPadding(5)
        ->withStyle('success.bg')
        ->output(['Work complete']);

1  
2  
3  
4  

Added in version 5.1.0

The `BannerHelper` was added in 5.1

Getting User Input [​](https://book.cakephp.org/6.x/console-commands/input-output.html#getting-user-input)

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

`method` Cake\\Console\\ConsoleIo::**ask**($question, $choices = null, $default = null): string

When building interactive console applications you'll need to get user input. CakePHP provides a way to do this:

    // Get arbitrary text from the user.
    $color = $io->ask('What color do you like?');
    
    // Get a choice from the user.
    $selection = $io->askChoice('Red or Green?', ['R', 'G'], 'R');

1  
2  
3  
4  
5  

Selection validation is case-insensitive.

Creating Files [​](https://book.cakephp.org/6.x/console-commands/input-output.html#creating-files)

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

`method` Cake\\Console\\ConsoleIo::**createFile**($path, $contents): bool

Creating files is often important part of many console commands that help automate development and deployment. The `createFile()` method gives you a simple interface for creating files with interactive confirmation:

    // Create a file with confirmation on overwrite
    $io->createFile('bower.json', $stuff);
    
    // Force overwriting without asking
    $io->createFile('bower.json', $stuff, true);

1  
2  
3  
4  
5  

Creating Output [​](https://book.cakephp.org/6.x/console-commands/input-output.html#creating-output)

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

### ConsoleIo::out() [​](https://book.cakephp.org/6.x/console-commands/input-output.html#consoleio-out)

Writing to `stdout` is done using the `out()` method:

    // Write to stdout
    $io->out('Normal message');

1  
2  

### ConsoleIo::err() [​](https://book.cakephp.org/6.x/console-commands/input-output.html#consoleio-err)

Writing to `stderr` is done using the `err()` method:

    // Write to stderr
    $io->err('Error message');

1  
2  

In addition to vanilla output methods, CakePHP provides wrapper methods that style output with appropriate ANSI colors:

    // Green text on stdout
    $io->success('Success message');
    
    // Cyan text on stdout
    $io->info('Informational text');
    
    // Blue text on stdout
    $io->comment('Additional context');
    
    // Red text on stderr
    $io->error('Error text');
    
    // Yellow text on stderr
    $io->warning('Warning text');

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

Color formatting will automatically be disabled if `posix_isatty` returns true, or if the `NO_COLOR` environment variable is set.

`ConsoleIo` provides two convenience methods regarding the output level:

    // Would only appear when verbose output is enabled (-v)
    $io->verbose('Verbose message');
    
    // Would appear at all levels.
    $io->quiet('Quiet message');

1  
2  
3  
4  
5  

You can also create blank lines or draw lines of dashes:

    // Output 2 newlines
    $io->out($io->nl(2));
    
    // Draw a horizontal line
    $io->hr();

1  
2  
3  
4  
5  

Lastly, you can update the current line of text on the screen:

    $io->out('Counting down');
    $io->out('10', 0);
    for ($i = 9; $i > 0; $i--) {
        sleep(1);
        $io->overwrite($i, 0, 2);
    }

1  
2  
3  
4  
5  
6  

NOTE

It is important to remember, that you cannot overwrite text once a new line has been output.

Output Levels [​](https://book.cakephp.org/6.x/console-commands/input-output.html#output-levels)

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

Console applications often need different levels of verbosity. For example, when running as a cron job, most output is un-necessary. You can use output levels to flag output appropriately. The user of the shell, can then decide what level of detail they are interested in by setting the correct flag when calling the command. There are 3 levels:

*   `QUIET` - Only absolutely important information should be marked for quiet output.
*   `NORMAL` - The default level, and normal usage.
*   `VERBOSE` - Mark messages that may be too noisy for everyday use, but helpful for debugging as `VERBOSE`.

You can mark output as follows:

    // Would appear at all levels.
    $io->out('Quiet message', 1, ConsoleIo::QUIET);
    $io->quiet('Quiet message');
    
    // Would not appear when quiet output is toggled.
    $io->out('normal message', 1, ConsoleIo::NORMAL);
    $io->out('loud message', 1, ConsoleIo::VERBOSE);
    $io->verbose('Verbose output');
    
    // Would only appear when verbose output is enabled.
    $io->out('extra message', 1, ConsoleIo::VERBOSE);
    $io->verbose('Verbose output');

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

You can control the output level of commands, by using the `--quiet` and `--verbose` options. These options are added by default, and allow you to consistently control output levels inside your CakePHP comands.

The `--quiet` and `--verbose` options also control how logging data is output to stdout/stderr. Normally info and higher log messages are output to stdout/stderr. When `--verbose` is used, debug logs will be output to stdout. When `--quiet` is used, only warning and higher log messages will be output to stderr.

Styling Output [​](https://book.cakephp.org/6.x/console-commands/input-output.html#styling-output)

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

Styling output is done by including tags - just like HTML - in your output. These tags will be replaced with the correct ansi code sequence, or stripped if you are on a console that doesn't support ansi codes. There are several built-in styles, and you can create more. The built-in ones are

*   `success` Success messages. Green text.
*   `error` Error messages. Red text.
*   `warning` Warning messages. Yellow text.
*   `info` Informational messages. Cyan text.
*   `comment` Additional text. Blue text.
*   `question` Text that is a question, added automatically by shell.
*   `info.bg` White background with cyan text.
*   `warning.bg` Yellow background with black text.
*   `error.bg` Red background with black text.
*   `success.bg` Green background with black text.

You can create additional styles using `$io->setStyle()`. To declare a new output style you could do:

    $io->setStyle('flashy', ['text' => 'magenta', 'blink' => true]);

1  

This would then allow you to use a `<flashy>` tag in your shell output, and if ansi colors are enabled, the following would be rendered as blinking magenta text `$this->out('<flashy>Whoooa</flashy> Something went wrong');`. When defining styles you can use the following colors for the `text` and `background` attributes:

*   black
*   blue
*   cyan
*   green
*   magenta
*   red
*   white
*   yellow

You can also use the following options as boolean switches, setting them to a truthy value enables them.

*   blink
*   bold
*   reverse
*   underline

Adding a style makes it available on all instances of ConsoleOutput as well, so you don't have to redeclare styles for both stdout and stderr objects.

Changed in version 5.1.0

The `info.bg`, `warning.bg`, `error.bg`, and `success.bg` were added.

Turning Off Coloring [​](https://book.cakephp.org/6.x/console-commands/input-output.html#turning-off-coloring)

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

Although coloring is pretty, there may be times when you want to turn it off, or force it on:

    $io->outputAs(ConsoleOutput::RAW);

1  

The above will put the output object into raw output mode. In raw output mode, no styling is done at all. There are three modes you can use.

*   `ConsoleOutput::COLOR` - Output with color escape codes in place.
*   `ConsoleOutput::PLAIN` - Plain text output, known style tags will be stripped from the output.
*   `ConsoleOutput::RAW` - Raw output, no styling or formatting will be done. This is a good mode to use if you are outputting XML or, want to debug why your styling isn't working.

By default on \*nix systems ConsoleOutput objects default to color output. On Windows systems, plain output is the default unless the `ANSICON` environment variable is present.

---

# Pagination | CakePHP

[Skip to content](https://book.cakephp.org/2.x/core-libraries/components/pagination.html#VPContent)

Return to top

Pagination [​](https://book.cakephp.org/2.x/core-libraries/components/pagination.html#pagination)

==================================================================================================

`class` **PaginatorComponent**(ComponentCollection $collection, array $settings = array())

One of the main obstacles of creating flexible and user-friendly web applications is designing an intuitive user interface. Many applications tend to grow in size and complexity quickly, and designers and programmers alike find they are unable to cope with displaying hundreds or thousands of records. Refactoring takes time, and performance and user satisfaction can suffer.

Displaying a reasonable number of records per page has always been a critical part of every application and used to cause many headaches for developers. CakePHP eases the burden on the developer by providing a quick, easy way to paginate data.

Pagination in CakePHP is offered by a component in the controller, to make building paginated queries easier. In the View `PaginatorHelper` is used to make the generation of pagination links & buttons simple.

Query Setup [​](https://book.cakephp.org/2.x/core-libraries/components/pagination.html#query-setup)

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

In the controller, we start by defining the query conditions pagination will use by default in the `$paginate` controller variable. These conditions, serve as the basis of your pagination queries. They are augmented by the `sort`, `direction`, `limit`, and `page` parameters passed in from the URL. It is important to note here that the `order` key must be defined in an array structure like below:

    class PostsController extends AppController {
    
        public $components = array('Paginator');
    
        public $paginate = array(
            'limit' => 25,
            'order' => array(
                'Post.title' => 'asc'
            )
        );
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

You can also include other `~Model::find()` options, such as `fields`:

    class PostsController extends AppController {
    
        public $components = array('Paginator');
    
        public $paginate = array(
            'fields' => array('Post.id', 'Post.created'),
            'limit' => 25,
            'order' => array(
                'Post.title' => 'asc'
            )
        );
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

Other keys that can be included in the `$paginate` array are similar to the parameters of the `Model->find('all')` method, that is: `conditions`, `fields`, `order`, `limit`, `page`, `contain`, `joins`, and `recursive`. In addition to the aforementioned keys, any additional keys will also be passed directly to the model find methods. This makes it very simple to use behaviors like `ContainableBehavior` with pagination:

    class RecipesController extends AppController {
    
        public $components = array('Paginator');
    
        public $paginate = array(
            'limit' => 25,
            'contain' => array('Article')
        );
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  

In addition to defining general pagination values, you can define more than one set of pagination defaults in the controller, you just name the keys of the array after the model you wish to configure:

    class PostsController extends AppController {
    
        public $paginate = array(
            'Post' => array (...),
            'Author' => array (...)
        );
    }

1  
2  
3  
4  
5  
6  
7  

The values of the `Post` and `Author` keys could contain all the properties that a model/key less `$paginate` array could.

Once the `$paginate` variable has been defined, we can use the `PaginatorComponent`'s `paginate()` method from our controller action. This will return `find()` results from the model. It also sets some additional paging parameters, which are added to the request object. The additional information is set to `$this->request->params['paging']`, and is used by `PaginatorHelper` for creating links. `PaginatorComponent::paginate()` also adds `PaginatorHelper` to the list of helpers in your controller, if it has not been added already:

    public function list_recipes() {
        $this->Paginator->settings = $this->paginate;
    
        // similar to findAll(), but fetches paged results
        $data = $this->Paginator->paginate('Recipe');
        $this->set('data', $data);
    }

1  
2  
3  
4  
5  
6  
7  

You can filter the records by passing conditions as second parameter to the `paginate()` function:

    $data = $this->Paginator->paginate(
        'Recipe',
        array('Recipe.title LIKE' => 'a%')
    );

1  
2  
3  
4  

Or you can also set `conditions` and other pagination settings array inside your action:

    public function list_recipes() {
        $this->Paginator->settings = array(
            'conditions' => array('Recipe.title LIKE' => 'a%'),
            'limit' => 10
        );
        $data = $this->Paginator->paginate('Recipe');
        $this->set(compact('data'));
    }

1  
2  
3  
4  
5  
6  
7  
8  

Custom Query Pagination [​](https://book.cakephp.org/2.x/core-libraries/components/pagination.html#custom-query-pagination)

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

If you're not able to use the standard find options to create the query you need to display your data, there are a few options. You can use a [custom find type](https://book.cakephp.org/2.x/models/retrieving-your-data.html#model-custom-find)
. You can also implement the `paginate()` and `paginateCount()` methods on your model, or include them in a behavior attached to your model. Behaviors implementing `paginate` and/or `paginateCount` should implement the method signatures defined below with the normal additional first parameter of `$model`:

    // paginate and paginateCount implemented on a behavior.
    public function paginate(Model $model, $conditions, $fields, $order, $limit,
        $page = 1, $recursive = null, $extra = array()) {
        // method content
    }
    
    public function paginateCount(Model $model, $conditions = null, $recursive = 0,
        $extra = array()) {
        // method body
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

It's seldom you'll need to implement paginate() and paginateCount(). You should make sure you can't achieve your goal with the core model methods, or a custom finder. To paginate with a custom find type, you should set the `0`'th element, or the `findType` key as of 2.3:

    public $paginate = array(
        'popular'
    );

1  
2  
3  

Since the 0th index is difficult to manage, in 2.3 the `findType` option was added:

    public $paginate = array(
        'findType' => 'popular'
    );

1  
2  
3  

The `paginate()` method should implement the following method signature. To use your own method/logic override it in the model you wish to get the data from:

    /**
     * Overridden paginate method - group by week, away_team_id and home_team_id
     */
    public function paginate($conditions, $fields, $order, $limit, $page = 1,
        $recursive = null, $extra = array()) {
    
        $recursive = -1;
        $group = $fields = array('week', 'away_team_id', 'home_team_id');
        return $this->find(
            'all',
            compact('conditions', 'fields', 'order', 'limit', 'page', 'recursive', 'group')
        );
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

You also need to override the core `paginateCount()`, this method expects the same arguments as `Model::find('count')`. The example below uses some PostgresSQL-specifc features, so please adjust accordingly depending on what database you are using:

    /**
     * Overridden paginateCount method
     */
    public function paginateCount($conditions = null, $recursive = 0,
                                    $extra = array()) {
        $sql = "SELECT
            DISTINCT ON(
                week, home_team_id, away_team_id
            )
                week, home_team_id, away_team_id
            FROM
                games";
        $this->recursive = $recursive;
        $results = $this->query($sql);
        return count($results);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  

The observant reader will have noticed that the paginate method we've defined wasn't actually necessary - All you have to do is add the keyword in controller's `$paginate` class variable:

    /**
     * Add GROUP BY clause
     */
    public $paginate = array(
        'MyModel' => array(
            'limit' => 20,
            'order' => array('week' => 'desc'),
            'group' => array('week', 'home_team_id', 'away_team_id')
        )
    );
    /**
     * Or on-the-fly from within the action
     */
    public function index() {
        $this->Paginator->settings = array(
            'MyModel' => array(
                'limit' => 20,
                'order' => array('week' => 'desc'),
                'group' => array('week', 'home_team_id', 'away_team_id')
            )
        );
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  

In CakePHP 2.0, you no longer need to implement `paginateCount()` when using group clauses. The core `find('count')` will correctly count the total number of rows.

Control which fields used for ordering [​](https://book.cakephp.org/2.x/core-libraries/components/pagination.html#control-which-fields-used-for-ordering)

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

By default sorting can be done with any column on a model. This is sometimes undesirable as it can allow users to sort on un-indexed columns, or virtual fields that can be expensive to calculate. You can use the 3rd parameter of `PaginatorComponent::paginate()` to restrict the columns that sorting will be done on:

    $this->Paginator->paginate('Post', array(), array('title', 'slug'));

1  

This would allow sorting on the title and slug columns only. A user that sets sort to any other value will be ignored.

Limit the maximum number of rows per page [​](https://book.cakephp.org/2.x/core-libraries/components/pagination.html#limit-the-maximum-number-of-rows-per-page)

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

The number of results that are fetched per page is exposed to the user as the `limit` parameter. It is generally undesirable to allow users to fetch all rows in a paginated set. The `maxLimit` option asserts that no one can set this limit too high from the outside. By default CakePHP limits the maximum number of rows that can be fetched to 100. If this default is not appropriate for your application, you can adjust it as part of the pagination options, for example reducing it to `10`:

    public $paginate = array(
        // other keys here.
        'maxLimit' => 10
    );

1  
2  
3  
4  

If the request's limit param is greater than this value, it will be reduced to the `maxLimit` value.

Pagination with GET parameters [​](https://book.cakephp.org/2.x/core-libraries/components/pagination.html#pagination-with-get-parameters)

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

In previous versions of CakePHP you could only generate pagination links using named parameters. But if pages were requested with GET parameters they would still work. For 2.0, we decided to make how you generate pagination parameters more controlled and consistent. You can choose to use either querystring or named parameters in the component. Incoming requests will accept only the chosen type, and the `PaginatorHelper` will generate links with the chosen type of parameter:

    public $paginate = array(
        'paramType' => 'querystring'
    );

1  
2  
3  

The above would enable querystring parameter parsing and generation. You can also modify the `$settings` property on the PaginatorComponent:

    $this->Paginator->settings['paramType'] = 'querystring';

1  

By default all of the typical paging parameters will be converted into GET arguments.

NOTE

You can run into a situation where assigning a value to a nonexistent property will throw errors:

    $this->paginate['limit'] = 10;

1  

will throw the error "Notice: Indirect modification of overloaded property $paginate has no effect." Assigning an initial value to the property solves the issue:

    $this->paginate = array();
    $this->paginate['limit'] = 10;
    //or
    $this->paginate = array('limit' => 10);

1  
2  
3  
4  

Or just declare the property in the controller class:

    class PostsController {
        public $paginate = array();
    }

1  
2  
3  

Or use `$this->Paginator->settings = array('limit' => 10);`

Make sure you have added the Paginator component to your $components array if you want to modify the `$settings` property of the PaginatorComponent.

Either of these approaches will solve the notice errors.

Out of range page requests [​](https://book.cakephp.org/2.x/core-libraries/components/pagination.html#out-of-range-page-requests)

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

As of 2.3 the PaginatorComponent will throw a NotFoundException when trying to access a non-existent page, i.e. page number requested is greater than total page count.

So you could either let the normal error page be rendered or use a try catch block and take appropriate action when a NotFoundException is caught:

    public function index() {
        try {
            $this->Paginator->paginate();
        } catch (NotFoundException $e) {
            //Do something here like redirecting to first or last page.
            //$this->request->params['paging'] will give you required info.
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  

AJAX Pagination [​](https://book.cakephp.org/2.x/core-libraries/components/pagination.html#ajax-pagination)

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

It's very easy to incorporate AJAX functionality into pagination. Using the `JsHelper` and `RequestHandlerComponent` you can easily add AJAX pagination to your application. See [Ajax Pagination](https://book.cakephp.org/2.x/core-libraries/helpers/js.html#ajax-pagination)
 for more information.

Pagination in the view [​](https://book.cakephp.org/2.x/core-libraries/components/pagination.html#pagination-in-the-view)

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

Check the `PaginatorHelper` documentation for how to create links for pagination navigation.

---

# Folder & File | CakePHP

[Skip to content](https://book.cakephp.org/2.x/core-utility-libraries/file-folder.html#VPContent)

Return to top

Folder & File [​](https://book.cakephp.org/2.x/core-utility-libraries/file-folder.html#folder-file)

====================================================================================================

The Folder and File utilities are convenience classes to help you read from and write/append to files; list files within a folder and other common directory related tasks.

Basic usage [​](https://book.cakephp.org/2.x/core-utility-libraries/file-folder.html#basic-usage)

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

Ensure the classes are loaded using `App::uses()`:

    <?php
    App::uses('Folder', 'Utility');
    App::uses('File', 'Utility');

1  
2  
3  

Then we can setup a new folder instance:

    <?php
    $dir = new Folder('/path/to/folder');

1  
2  

and search for all _.ctp_ files within that folder using regex:

    <?php
    $files = $dir->find('.*\.ctp');

1  
2  

Now we can loop through the files and read from or write/append to the contents or simply delete the file:

    <?php
    foreach ($files as $file) {
        $file = new File($dir->pwd() . DS . $file);
        $contents = $file->read();
        // $file->write('I am overwriting the contents of this file');
        // $file->append('I am adding to the bottom of this file.');
        // $file->delete(); // I am deleting this file
        $file->close(); // Be sure to close the file when you're done
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  

Folder API [​](https://book.cakephp.org/2.x/core-utility-libraries/file-folder.html#folder-api)

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

`class` **Folder**(string $path = false, boolean $create = false, string|boolean $mode = false)

    <?php
    // Create a new folder with 0755 permissions
    $dir = new Folder('/path/to/folder', true, 0755);
    
    
    Path of the current folder. :php:meth:`Folder::pwd()` will return the same
    information.
    
    
    Whether or not the list results should be sorted by name.
    
    
    Mode to be used when creating folders. Defaults to ``0755``. Does nothing on
    Windows machines.

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

`static` Folder::**addPathElement**(string $path, string $element)

rtype  
string

Returns $path with $element added, with correct slash in-between:

    $path = Folder::addPathElement('/a/path/for', 'testing');
    // $path equals /a/path/for/testing

1  
2  

$element can also be an array:

    $path = Folder::addPathElement('/a/path/for', array('testing', 'another'));
    // $path equals /a/path/for/testing/another

1  
2  

Added in version 2.5

$element parameter accepts an array as of 2.5

`method` Folder::**cd**(string $path)

`method` Folder::**chmod**(string $path, integer $mode = false, boolean $recursive = true, array $exceptions = array())

`method` Folder::**copy**(array|string $options = array())

`static` Folder::**correctSlashFor**(string $path)

rtype  
string

Returns a correct set of slashes for given $path ('\\ for Windows paths and '/' for other paths).

`method` Folder::**create**(string $pathname, integer $mode = false)

`method` Folder::**delete**(string $path = null)

`method` Folder::**dirsize**()

`method` Folder::**errors**()

`method` Folder::**find**(string $regexpPattern = '.\*', boolean $sort = false)

NOTE

The folder find and findRecursive methods will only find files. If you would like to get folders and files see `Folder::read()` or `Folder::tree()`

`method` Folder::**findRecursive**(string $pattern = '.\*', boolean $sort = false)

`method` Folder::**inCakePath**(string $path = '')

`method` Folder::**inPath**(string $path = '', boolean $reverse = false)

`static` Folder::**isAbsolute**(string $path)

rtype  
boolean

Returns true if the given $path is an absolute path.

`static` Folder::**isSlashTerm**(string $path)

rtype  
boolean

Returns true if given $path ends in a slash (i.e. is slash-terminated):

    <?php
    $result = Folder::isSlashTerm('/my/test/path');
    // $result = false
    $result = Folder::isSlashTerm('/my/test/path/');
    // $result = true

1  
2  
3  
4  
5  

`static` Folder::**isWindowsPath**(string $path)

rtype  
boolean

Returns true if the given $path is a Windows path.

`method` Folder::**messages**()

`method` Folder::**move**(array $options)

`static` Folder::**normalizePath**(string $path)

rtype  
string

Returns a correct set of slashes for given $path ('\\ for Windows paths and '/' for other paths).

`method` Folder::**pwd**()

`method` Folder::**read**(boolean $sort = true, array|boolean $exceptions = false, boolean $fullPath = false)

`method` Folder::**realpath**(string $path)

`static` Folder::**slashTerm**(string $path)

rtype  
string

Returns $path with added terminating slash (corrected for Windows or other OS).

`method` Folder::**tree**(null|string $path = null, array|boolean $exceptions = true, null|string $type = null)

File API [​](https://book.cakephp.org/2.x/core-utility-libraries/file-folder.html#file-api)

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

`class` **File**(string $path, boolean $create = false, integer $mode = 755)

    <?php
    // Create a new file with 0644 permissions
    $file = new File('/path/to/file.php', true, 0644);
    
    
    The Folder object of the file.
    
    
    The name of the file with the extension. Differs from
    :php:meth:`File::name()` which returns the name without the extension.
    
    
    An array of file info. Use :php:meth:`File::info()` instead.
    
    
    Holds the file handler resource if the file is opened.
    
    
    Enable locking for file reading and writing.
    
    
    The current file's absolute path.

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  

`method` File::**append**(string $data, boolean $force = false)

`method` File::**close**()

`method` File::**copy**(string $dest, boolean $overwrite = true)

`method` File::**create**()

`method` File::**delete**()

`method` File::**executable**()

`method` File::**exists**()

`method` File::**ext**()

`method` File::**Folder**()

`method` File::**group**()

`method` File::**info**()

`method` File::**lastAccess**()

`method` File::**lastChange**()

`method` File::**md5**(integer|boolean $maxsize = 5)

`method` File::**name**()

`method` File::**offset**(integer|boolean $offset = false, integer $seek = 0)

`method` File::**open**(string $mode = 'r', boolean $force = false)

`method` File::**owner**()

`method` File::**perms**()

<File::prepare(string> $data, boolean $forceWindows = false)

rtype  
string

Prepares a ascii string for writing. Converts line endings to the correct terminator for the current platform. For Windows "rn" will be used, "n" for all other platforms.

`method` File::**pwd**()

`method` File::**read**(string $bytes = false, string $mode = 'rb', boolean $force = false)

`method` File::**readable**()

`method` File::**safe**(string $name = null, string $ext = null)

`method` File::**size**()

`method` File::**writable**()

`method` File::**write**(string $data, string $mode = 'w', boolean$force = false)

Added in version 2.1

`File::mime()`

`method` File::**mime**()

`method` File::**replaceText**( $search, $replace )

Better explain how to use each method with both classes.

---

# App Class | CakePHP

[Skip to content](https://book.cakephp.org/4.x/core-libraries/app.html#VPContent)

Return to top

App Class [​](https://book.cakephp.org/4.x/core-libraries/app.html#app-class)

==============================================================================

`class` Cake\\Core\\**App**

The App class is responsible for resource location and path management.

Finding Classes [​](https://book.cakephp.org/4.x/core-libraries/app.html#finding-classes)

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

`static` Cake\\Core\\App::**className**($name, $type = '', $suffix = '')

This method is used to resolve class names throughout CakePHP. It resolves the short form names CakePHP uses and returns the fully resolved class name:

    // Resolve a short class name with the namespace + suffix.
    App::className('Auth', 'Controller/Component', 'Component');
    // Returns Cake\Controller\Component\AuthComponent
    
    // Resolve a plugin name.
    App::className('DebugKit.Toolbar', 'Controller/Component', 'Component');
    // Returns DebugKit\Controller\Component\ToolbarComponent
    
    // Names with \ in them will be returned unaltered.
    App::className('App\Cache\ComboCache');
    // Returns App\Cache\ComboCache

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

When resolving classes, the `App` namespace will be tried, and if the class does not exist the `Cake` namespace will be attempted. If both class names do not exist, `false` will be returned.

Finding Paths to Resources [​](https://book.cakephp.org/4.x/core-libraries/app.html#finding-paths-to-resources)

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

`static` Cake\\Core\\App::**path**(string $package, ?string $plugin = null)

The method returns paths set using `App.paths` app config:

    // Get the templates path set using ``App.paths.templates`` app config.
    App::path('templates');

1  
2  

The same way you can retrieve paths for `locales`, `plugins`.

Finding Paths to Namespaces [​](https://book.cakephp.org/4.x/core-libraries/app.html#finding-paths-to-namespaces)

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

`static` Cake\\Core\\App::**classPath**(string $package, ?string $plugin = null)

Used to get locations for paths based on conventions:

    // Get the path to Controller/ in your application
    App::classPath('Controller');

1  
2  

This can be done for all namespaces that are part of your application.

`App::classPath()` will only return the default path, and will not be able to provide any information about additional paths the autoloader is configured for.

`static` Cake\\Core\\App::**core**(string $package)

Used for finding the path to a package inside CakePHP:

    // Get the path to Cache engines.
    App::core('Cache/Engine');

1  
2  

Locating Themes [​](https://book.cakephp.org/4.x/core-libraries/app.html#locating-themes)

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

Since themes are plugins, you can use the methods above to get the path to a theme.

Loading Vendor Files [​](https://book.cakephp.org/4.x/core-libraries/app.html#loading-vendor-files)

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

Ideally vendor files should be autoloaded with `Composer`, if you have vendor files that cannot be autoloaded or installed with Composer you will need to use `require` to load them.

If you cannot install a library with Composer, it is best to install each library in a directory following Composer's convention of `vendor/$author/$package`. If you had a library called AcmeLib, you could install it into `vendor/Acme/AcmeLib`. Assuming it did not use PSR-0 compatible classnames you could autoload the classes within it using `classmap` in your application's `composer.json`:

    "autoload": {
        "psr-4": {
            "App\\": "src/",
            "App\\Test\\": "tests/"
        },
        "classmap": [\
            "vendor/Acme/AcmeLib"\
        ]
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  

If your vendor library does not use classes, and instead provides functions, you can configure Composer to load these files at the beginning of each request using the `files` autoloading strategy:

    "autoload": {
        "psr-4": {
            "App\\": "src/",
            "App\\Test\\": "tests/"
        },
        "files": [\
            "vendor/Acme/AcmeLib/functions.php"\
        ]
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  

After configuring the vendor libraries you will need to regenerate your application's autoloader using:

    $ php composer.phar dump-autoload

1  

If you happen to not be using Composer in your application, you will need to manually load all vendor libraries yourself.

---

# CounterCache | CakePHP

[Skip to content](https://book.cakephp.org/4.x/orm/behaviors/counter-cache.html#VPContent)

Return to top

CounterCache [​](https://book.cakephp.org/4.x/orm/behaviors/counter-cache.html#countercache)

=============================================================================================

`class` Cake\\ORM\\Behavior\\**CounterCacheBehavior**

Often times web applications need to display counts of related objects. For example, when showing a list of articles you may want to display how many comments it has. Or when showing a user you might want to show how many friends/followers she has. The CounterCache behavior is intended for these situations. CounterCache will update a field in the associated models assigned in the options when it is invoked. The fields should exist in the database and be of the type INT.

Basic Usage [​](https://book.cakephp.org/4.x/orm/behaviors/counter-cache.html#basic-usage)

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

You enable the CounterCache behavior like any other behavior, but it won't do anything until you configure some relations and the field counts that should be stored on each of them. Using our example below, we could cache the comment count for each article with the following:

    class CommentsTable extends Table
    {
        public function initialize(array $config): void
        {
            $this->addBehavior('CounterCache', [\
                'Articles' => ['comment_count']\
            ]);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  

NOTE

The column `comment_count` should exist in the `articles` table.

The CounterCache configuration should be a map of relation names and the specific configuration for that relation.

As you see you need to add the behavior on the "other side" of the association where you actually want the field to be updated. In this example the behavior is added to the `CommentsTable` even though it updates the `comment_count` field in the `ArticlesTable`.

The counter's value will be updated each time an entity is saved or deleted. The counter **will not** be updated when you

*   save the entity without changing data or
*   use `updateAll()` or
*   use `deleteAll()` or
*   execute SQL you have written

Advanced Usage [​](https://book.cakephp.org/4.x/orm/behaviors/counter-cache.html#advanced-usage)

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

If you need to keep a cached counter for less than all of the related records, you can supply additional conditions or finder methods to generate a counter value:

    // Use a specific find method.
    // In this case find(published)
    $this->addBehavior('CounterCache', [\
        'Articles' => [\
            'comment_count' => [\
                'finder' => 'published'\
            ]\
        ]\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  

If you don't have a custom finder method you can provide an array of conditions to find records instead:

    $this->addBehavior('CounterCache', [\
        'Articles' => [\
            'comment_count' => [\
                'conditions' => ['Comments.spam' => false]\
            ]\
        ]\
    ]);

1  
2  
3  
4  
5  
6  
7  

If you want CounterCache to update multiple fields, for example both showing a conditional count and a basic count you can add these fields in the array:

    $this->addBehavior('CounterCache', [\
        'Articles' => ['comment_count',\
            'published_comment_count' => [\
                'finder' => 'published'\
            ]\
        ]\
    ]);

1  
2  
3  
4  
5  
6  
7  

If you want to calculate the CounterCache field value on your own, you can set the `ignoreDirty` option to `true`. This will prevent the field from being recalculated if you've set it dirty before:

    $this->addBehavior('CounterCache', [\
        'Articles' => [\
            'comment_count' => [\
                'ignoreDirty' => true\
            ]\
        ]\
    ]);

1  
2  
3  
4  
5  
6  
7  

Lastly, if a custom finder and conditions are not suitable you can provide a callback function. Your function must return the count value to be stored:

    $this->addBehavior('CounterCache', [\
        'Articles' => [\
            'rating_avg' => function ($event, $entity, $table, $original) {\
                return 4.5;\
            }\
        ]\
    ]);

1  
2  
3  
4  
5  
6  
7  

Your function can return `false` to skip updating the counter column, or a `Query` object that produced the count value. If you return a `Query` object, your query will be used as a subquery in the update statement. The `$table` parameter refers to the table object holding the behavior (not the target relation) for convenience. The callback is invoked at least once with `$original` set to `false`. If the entity-update changes the association then the callback is invoked a _second_ time with `true`, the return value then updates the counter of the _previously_ associated item.

NOTE

The CounterCache behavior works for `belongsTo` associations only. For example for "Comments belongsTo Articles", you need to add the CounterCache behavior to the `CommentsTable` in order to generate `comment_count` for Articles table.

Belongs to many Usage [​](https://book.cakephp.org/4.x/orm/behaviors/counter-cache.html#belongs-to-many-usage)

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

It is possible to use the CounterCache behavior in a `belongsToMany` association. First, you need to add the `through` and `cascadeCallbacks` options to the `belongsToMany` association:

    'through'          => 'CommentsArticles',
    'cascadeCallbacks' => true

1  
2  

Also see [Using The Through Option](https://book.cakephp.org/4.x/orm/associations.html#using-the-through-option)
 how to configure a custom join table.

The `CommentsArticles` is the name of the junction table classname. If you don't have it you should create it with the bake CLI tool.

In this `src/Model/Table/CommentsArticlesTable.php` you then need to add the behavior with the same code as described above.:

    $this->addBehavior('CounterCache', [\
        'Articles' => ['comments_count'],\
    ]);

1  
2  
3  

Finally clear all caches with `bin/cake cache clear_all` and try it out.

---

# Schema System | CakePHP

[Skip to content](https://book.cakephp.org/4.x/orm/schema-system.html#VPContent)

Return to top

Schema System [​](https://book.cakephp.org/4.x/orm/schema-system.html#schema-system)

=====================================================================================

CakePHP features a schema system that is capable of reflecting and generating schema information for tables in SQL datastores. The schema system can generate/reflect a schema for any SQL platform that CakePHP supports.

The main pieces of the schema system are `Cake\Database\Schema\Collection` and `Cake\Database\Schema\TableSchema`. These classes give you access to database-wide and individual Table object features respectively.

The primary use of the schema system is for [Test Fixtures](https://book.cakephp.org/4.x/development/testing.html#test-fixtures)
. However, it can also be used in your application if required.

Schema\\TableSchema Objects [​](https://book.cakephp.org/4.x/orm/schema-system.html#schema-tableschema-objects)

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

`class` Cake\\Database\\Schema\\**TableSchema**

The schema subsystem provides a simple TableSchema object to hold data about a table in a database. This object is returned by the schema reflection features:

    use Cake\Database\Schema\TableSchema;
    
    // Create a table one column at a time.
    $schema = new TableSchema('posts');
    $schema->addColumn('id', [\
      'type' => 'integer',\
      'length' => 11,\
      'null' => false,\
      'default' => null,\
    ])->addColumn('title', [\
      'type' => 'string',\
      'length' => 255,\
      // Create a fixed length (char field)\
      'fixed' => true\
    ])->addConstraint('primary', [\
      'type' => 'primary',\
      'columns' => ['id']\
    ]);
    
    // Schema\TableSchema classes could also be created with array data
    $schema = new TableSchema('posts', $columns);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  

`Schema\TableSchema` objects allow you to build up information about a table's schema. It helps to normalize and validate the data used to describe a table. For example, the following two forms are equivalent:

    $schema->addColumn('title', 'string');
    // and
    $schema->addColumn('title', [\
      'type' => 'string'\
    ]);

1  
2  
3  
4  
5  

While equivalent, the 2nd form allows more detail and control. This emulates the existing features available in Schema files + the fixture schema in 2.x.

### Accessing Column Data [​](https://book.cakephp.org/4.x/orm/schema-system.html#accessing-column-data)

Columns are either added as constructor arguments, or via addColumn(). Once fields are added information can be fetched using column() or \`columns()\`:

    // Get the array of data about a column
    $c = $schema->column('title');
    
    // Get the list of all columns.
    $cols = $schema->columns();

1  
2  
3  
4  
5  

### Indexes and Constraints [​](https://book.cakephp.org/4.x/orm/schema-system.html#indexes-and-constraints)

Indexes are added using the `addIndex()`. Constraints are added using `addConstraint()`. Indexes and constraints cannot be added for columns that do not exist, as it would result in an invalid state. Indexes are different from constraints, and exceptions will be raised if you try to mix types between the methods. An example of both methods is:

    $schema = new TableSchema('posts');
    $schema->addColumn('id', 'integer')
      ->addColumn('author_id', 'integer')
      ->addColumn('title', 'string')
      ->addColumn('slug', 'string');
    
    // Add a primary key.
    $schema->addConstraint('primary', [\
      'type' => 'primary',\
      'columns' => ['id']\
    ]);
    // Add a unique key
    $schema->addConstraint('slug_idx', [\
      'columns' => ['slug'],\
      'type' => 'unique',\
    ]);
    // Add index
    $schema->addIndex('slug_title', [\
      'columns' => ['slug', 'title'],\
      'type' => 'index'\
    ]);
    // Add a foreign key
    $schema->addConstraint('author_id_idx', [\
      'columns' => ['author_id'],\
      'type' => 'foreign',\
      'references' => ['authors', 'id'],\
      'update' => 'cascade',\
      'delete' => 'cascade'\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  

If you add a primary key constraint to a single integer column it will automatically be converted into a auto-increment/serial column depending on the database platform:

    $schema = new TableSchema('posts');
    $schema->addColumn('id', 'integer')
    ->addConstraint('primary', [\
        'type' => 'primary',\
        'columns' => ['id']\
    ]);

1  
2  
3  
4  
5  
6  

In the above example the `id` column would generate the following SQL in MySQL:

    CREATE TABLE `posts` (
        `id` INTEGER AUTO_INCREMENT,
        PRIMARY KEY (`id`)
    )

1  
2  
3  
4  

If your primary key contains more than one column, none of them will automatically be converted to an auto-increment value. Instead you will need to tell the table object which column in the composite key you want to auto-increment:

    $schema = new TableSchema('posts');
    $schema->addColumn('id', [\
        'type' => 'integer',\
        'autoIncrement' => true,\
    ])
    ->addColumn('account_id', 'integer')
    ->addConstraint('primary', [\
        'type' => 'primary',\
        'columns' => ['id', 'account_id']\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

The `autoIncrement` option only works with `integer` and `biginteger` columns.

### Reading Indexes and Constraints [​](https://book.cakephp.org/4.x/orm/schema-system.html#reading-indexes-and-constraints)

Indexes and constraints can be read out of a table object using accessor methods. Assuming that `$schema` is a populated TableSchema instance you could do the following:

    // Get constraints. Will return the
    // names of all constraints.
    $constraints = $schema->constraints()
    
    // Get data about a single constraint.
    $constraint = $schema->constraint('author_id_idx')
    
    // Get indexes. Will return the
    // names of all indexes.
    $indexes = $schema->indexes()
    
    // Get data about a single index.
    $index = $schema->index('author_id_idx')

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

### Adding Table Options [​](https://book.cakephp.org/4.x/orm/schema-system.html#adding-table-options)

Some drivers (primarily MySQL) support and require additional table metadata. In the case of MySQL the `CHARSET`, `COLLATE` and `ENGINE` properties are required for maintaining a table's structure in MySQL. The following could be used to add table options:

    $schema->options([\
      'engine' => 'InnoDB',\
      'collate' => 'utf8_unicode_ci',\
    ]);

1  
2  
3  
4  

Platform dialects only handle the keys they are interested in and ignore the rest. Not all options are supported on all platforms.

### Converting Tables into SQL [​](https://book.cakephp.org/4.x/orm/schema-system.html#converting-tables-into-sql)

Using the `createSql()` or `dropSql()` you can get platform specific SQL for creating or dropping a specific table:

    $db = ConnectionManager::get('default');
    $schema = new TableSchema('posts', $fields, $indexes);
    
    // Create a table
    $queries = $schema->createSql($db);
    foreach ($queries as $sql) {
      $db->execute($sql);
    }
    
    // Drop a table
    $sql = $schema->dropSql($db);
    $db->execute($sql);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

By using a connection's driver the schema data can be converted into platform specific SQL. The return of `createSql` and `dropSql` is a list of SQL queries required to create a table and the required indexes. Some platforms may require multiple statements to create tables with comments and/or indexes. An array of queries is always returned.

Schema Collections [​](https://book.cakephp.org/4.x/orm/schema-system.html#schema-collections)

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

`class` Cake\\Database\\Schema\\**Collection**

`Collection` provides access to the various tables available on a connection. You can use it to get the list of tables or reflect tables into `TableSchema` objects. Basic usage of the class looks like:

    $db = ConnectionManager::get('default');
    
    // Create a schema collection.
    $collection = $db->getSchemaCollection();
    
    // Get the table names
    $tables = $collection->listTables();
    
    // Get a single table (instance of Schema\TableSchema)
    $tableSchema = $collection->describe('posts');

1  
2  
3  
4  
5  
6  
7  
8  
9  
10

---

# Flash | CakePHP

[Skip to content](https://book.cakephp.org/6.x/controllers/components/flash.html#VPContent)

Return to top

Flash [​](https://book.cakephp.org/6.x/controllers/components/flash.html#flash)

================================================================================

`class` Cake\\Controller\\Component\\**FlashComponent**(ComponentCollection $collection, array $config = \[\])

FlashComponent provides a way to set one-time notification messages to be displayed after processing a form or acknowledging data. CakePHP refers to these messages as "flash messages". FlashComponent writes flash messages to `$_SESSION`, to be rendered in a View using [FlashHelper](https://book.cakephp.org/6.x/views/helpers/flash.html)
.

Setting Flash Messages [​](https://book.cakephp.org/6.x/controllers/components/flash.html#setting-flash-messages)

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

FlashComponent provides two ways to set flash messages: its `__call()` magic method and its `set()` method. To furnish your application with verbosity, FlashComponent's `__call()` magic method allows you use a method name that maps to an element located under the **templates/element/flash** directory. By convention, camelcased methods will map to the lowercased and underscored element name:

    // Uses templates/element/flash/success.php
    $this->Flash->success('This was successful');
    
    // Uses templates/element/flash/great_success.php
    $this->Flash->greatSuccess('This was greatly successful');

1  
2  
3  
4  
5  

Alternatively, to set a plain-text message without rendering an element, you can use the `set()` method:

    $this->Flash->set('This is a message');

1  

Flash messages are appended to an array internally. Successive calls to `set()` or `__call()` with the same key will append the messages in the `$_SESSION`. If you want to overwrite existing messages when setting a flash message, set the `clear` option to `true` when configuring the Component.

FlashComponent's `__call()` and `set()` methods optionally take a second parameter, an array of options:

*   `key` Defaults to 'flash'. The array key found under the `Flash` key in the session.
*   `element` Defaults to `null`, but will automatically be set when using the `__call()` magic method. The element name to use for rendering.
*   `params` An optional array of keys/values to make available as variables within an element.
*   `clear` expects a `bool` and allows you to delete all messages in the current stack and start a new one.

An example of using these options:

    // In your Controller
    $this->Flash->success('The user has been saved', [\
        'key' => 'positive',\
        'clear' => true,\
        'params' => [\
            'name' => $user->name,\
            'email' => $user->email,\
        ],\
    ]);
    
    // In your View
    <?= $this->Flash->render('positive') ?>
    
    <!-- In templates/element/flash/success.php -->
    <div id="flash-<?= h($key) ?>" class="message-info success">
        <?= h($message) ?>: <?= h($params['name']) ?>, <?= h($params['email']) ?>.
    </div>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

Note that the parameter `element` will be always overridden while using `__call()`. In order to retrieve a specific element from a plugin, you should set the `plugin` parameter. For example:

    // In your Controller
    $this->Flash->warning('My message', ['plugin' => 'PluginName']);

1  
2  

The code above will use the **warning.php** element under **plugins/PluginName/templates/element/flash** for rendering the flash message.

NOTE

By default, CakePHP escapes the content in flash messages to prevent cross site scripting. User data in your flash messages will be HTML encoded and safe to be printed. If you want to include HTML in your flash messages, you need to pass the `escape` option and adjust your flash message templates to allow disabling escaping when the escape option is passed.

HTML in Flash Messages [​](https://book.cakephp.org/6.x/controllers/components/flash.html#html-in-flash-messages)

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

It is possible to output HTML in flash messages by using the `'escape'` option key:

    $this->Flash->info(sprintf('<b>%s</b> %s', h($highlight), h($message)), ['escape' => false]);

1  

Make sure that you escape the input manually, then. In the above example `$highlight` and `$message` are non-HTML input and therefore escaped.

For more information about rendering your flash messages, please refer to the [FlashHelper](https://book.cakephp.org/6.x/views/helpers/flash.html)
 section.

---

# Security | CakePHP

[Skip to content](https://book.cakephp.org/6.x/security.html#VPContent)

Return to top

Security [​](https://book.cakephp.org/6.x/security.html#security)

==================================================================

CakePHP provides you some tools to secure your application. In addition to the [Form Protection Component](https://book.cakephp.org/6.x/controllers/components/form-protection.html)
, the following sections cover additional security features:

*   [Security Utility](https://book.cakephp.org/6.x/core-libraries/security.html)
    
*   [CSRF Protection](https://book.cakephp.org/6.x/security/csrf.html)
    
*   [Content Security Policy](https://book.cakephp.org/6.x/security/content-security-policy.html)
    
*   [Security Headers](https://book.cakephp.org/6.x/security/security-headers.html)
    
*   [HTTPS Enforcer](https://book.cakephp.org/6.x/security/https-enforcer.html)

---

# Date & Time | CakePHP

[Skip to content](https://book.cakephp.org/6.x/core-libraries/time.html#VPContent)

Return to top

Date & Time [​](https://book.cakephp.org/6.x/core-libraries/time.html#date-time)

=================================================================================

`class` Cake\\I18n\\**DateTime**

If you need `TimeHelper` functionalities outside of a `View`, use the `DateTime` class:

    use Cake\I18n\DateTime;
    
    class UsersController extends AppController
    {
        public function initialize(): void
        {
            parent::initialize();
            $this->loadComponent('Authentication.Authentication');
        }
    
        public function afterLogin()
        {
            $identity = $this->Authentication->getIdentity();
            $time = new DateTime($identity->date_of_birth);
            if ($time->isToday()) {
                // Greet user with a happy birthday message
                $this->Flash->success(__('Happy birthday to you...'));
            }
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  

Under the hood, CakePHP uses [Chronos](https://github.com/cakephp/chronos)
 to power its `DateTime` utility. Anything you can do with `Chronos` and PHP's `DateTimeImmutable`, you can do with `DateTime`.

For more details on Chronos please see [the API documentation](https://api.cakephp.org/chronos/)
.

Creating DateTime Instances [​](https://book.cakephp.org/6.x/core-libraries/time.html#creating-datetime-instances)

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

`DateTime` are immutable objects as immutability prevents accidental changes to data, and avoids order based dependency issues.

There are a few ways to create `DateTime` instances:

    use Cake\I18n\DateTime;
    
    // Create from a string datetime.
    $time = DateTime::createFromFormat(
        'Y-m-d H:i:s',
        '2021-01-31 22:11:30',
        'America/New_York'
    );
    
    // Create from a timestamp and set timezone
    $time = DateTime::createFromTimestamp(1612149090, 'America/New_York');
    
    // Get the current time.
    $time = DateTime::now();
    
    // Or just use 'new'
    $time = new DateTime('2021-01-31 22:11:30', 'America/New_York');
    
    $time = new DateTime('2 hours ago');

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  

The `DateTime` class constructor can take any parameter that the internal `DateTimeImmutable` PHP class can. When passing a number or numeric string, it will be interpreted as a UNIX timestamp.

In test cases, you can mock out `now()` using `setTestNow()`:

    // Fixate time.
    $time = new DateTime('2021-01-31 22:11:30');
    DateTime::setTestNow($time);
    
    // Outputs '2021-01-31 22:11:30'
    $now = DateTime::now();
    echo $now->i18nFormat('yyyy-MM-dd HH:mm:ss');
    
    // Outputs '2021-01-31 22:11:30'
    $now = DateTime::parse('now');
    echo $now->i18nFormat('yyyy-MM-dd HH:mm:ss');

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

Manipulation [​](https://book.cakephp.org/6.x/core-libraries/time.html#manipulation)

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

Remember, `DateTime` instance always return a new instance from setters instead of modifying itself:

    $time = DateTime::now();
    
    // Create and reassign a new instance
    $newTime = $time->year(2013)
        ->month(10)
        ->day(31);
    // Outputs '2013-10-31 22:11:30'
    echo $newTime->i18nFormat('yyyy-MM-dd HH:mm:ss');

1  
2  
3  
4  
5  
6  
7  
8  

You can also use the methods provided by PHP's built-in `DateTime` class:

    $time = $time->setDate(2013, 10, 31);

1  

Failing to reassign the new `DateTime` instances will result in the original, unmodified instance being used:

    $time->year(2013)
        ->month(10)
        ->day(31);
    // Outputs '2021-01-31 22:11:30'
    echo $time->i18nFormat('yyyy-MM-dd HH:mm:ss');

1  
2  
3  
4  
5  

You can create another instance with modified dates, through subtraction and addition of their components:

    $time = DateTime::create(2021, 1, 31, 22, 11, 30);
    $newTime = $time->subDays(5)
        ->addHours(-2)
        ->addMonths(1);
    // Outputs '2/26/21, 8:11 PM'
    echo $newTime;
    
    // Using strtotime strings.
    $newTime = $time->modify('+1 month -5 days -2 hours');
    // Outputs '2/26/21, 8:11 PM'
    echo $newTime;

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

You can get the internal components of a date by accessing its properties:

    $time = DateTime::create(2021, 1, 31, 22, 11, 30);
    echo $time->year; // 2021
    echo $time->month; // 1
    echo $time->day; // 31
    echo $time->timezoneName; // America/New_York

1  
2  
3  
4  
5  

Formatting [​](https://book.cakephp.org/6.x/core-libraries/time.html#formatting)

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

### DateTime::setJsonEncodeFormat() [​](https://book.cakephp.org/6.x/core-libraries/time.html#datetime-setjsonencodeformat)

`static` Cake\\I18n\\DateTime::**setJsonEncodeFormat**($format): void

This method sets the default format used when converting an object to json:

    DateTime::setJsonEncodeFormat('yyyy-MM-dd HH:mm:ss');  // For any immutable DateTime
    Date::setJsonEncodeFormat('yyyy-MM-dd HH:mm:ss');  // For any mutable Date
    
    $time = DateTime::parse('2021-01-31 22:11:30');
    echo json_encode($time);   // Outputs '2021-01-31 22:11:30'
    
    Date::setJsonEncodeFormat(static function($time) {
        return $time->format(DATE_ATOM);
    });

1  
2  
3  
4  
5  
6  
7  
8  
9  

NOTE

This method must be called statically.

NOTE

Be aware that this is not a PHP Datetime string format! You need to use a ICU date formatting string as specified in the following resource: [https://unicode-org.github.io/icu/userguide/format\_parse/datetime/#datetime-format-syntax](https://unicode-org.github.io/icu/userguide/format_parse/datetime/#datetime-format-syntax)
.

Changed in version 4.1.0

The `callable` parameter type was added.

### DateTime::i18nFormat() [​](https://book.cakephp.org/6.x/core-libraries/time.html#datetime-i18nformat)

`method` Cake\\I18n\\DateTime::**i18nFormat**($format = null, $timezone = null, $locale = null): string|int

A very common thing to do with `Time` instances is to print out formatted dates. CakePHP makes this a snap:

    $time = DateTime::parse('2021-01-31 22:11:30');
    
    // Prints a localized datetime stamp. Outputs '1/31/21, 10:11 PM'
    echo $time;
    
    // Outputs '1/31/21, 10:11 PM' for the en-US locale
    echo $time->i18nFormat();
    
    // Use the full date and time format. Outputs 'Sunday, January 31, 2021 at 10:11:30 PM Eastern Standard Time'
    echo $time->i18nFormat(\IntlDateFormatter::FULL);
    
    // Use full date but short time format. Outputs 'Sunday, January 31, 2021 at 10:11 PM'
    echo $time->i18nFormat([\IntlDateFormatter::FULL, \IntlDateFormatter::SHORT]);
    
    // Outputs '2021-Jan-31 22:11:30'
    echo $time->i18nFormat('yyyy-MMM-dd HH:mm:ss');

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  

It is possible to specify the desired format for the string to be displayed. You can either pass [IntlDateFormatter constants](https://www.php.net/manual/en/class.intldateformatter.php)
 as the first argument of this function, or pass a full ICU date formatting string as specified in the following resource: [https://unicode-org.github.io/icu/userguide/format\_parse/datetime/#datetime-format-syntax](https://unicode-org.github.io/icu/userguide/format_parse/datetime/#datetime-format-syntax)
.

You can also format dates with non-gregorian calendars:

    // On ICU version 66.1
    $time = DateTime::create(2021, 1, 31, 22, 11, 30);
    
    // Outputs 'Sunday, Bahman 12, 1399 AP at 10:11:30 PM Eastern Standard Time'
    echo $time->i18nFormat(\IntlDateFormatter::FULL, null, 'en-IR@calendar=persian');
    
    // Outputs 'Sunday, January 31, 3 Reiwa at 10:11:30 PM Eastern Standard Time'
    echo $time->i18nFormat(\IntlDateFormatter::FULL, null, 'en-JP@calendar=japanese');
    
    // Outputs 'Sunday, Twelfth Month 19, 2020(geng-zi) at 10:11:30 PM Eastern Standard Time'
    echo $time->i18nFormat(\IntlDateFormatter::FULL, null, 'en-CN@calendar=chinese');
    
    // Outputs 'Sunday, Jumada II 18, 1442 AH at 10:11:30 PM Eastern Standard Time'
    echo $time->i18nFormat(\IntlDateFormatter::FULL, null, 'en-SA@calendar=islamic');

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

The following calendar types are supported:

*   japanese
*   buddhist
*   chinese
*   persian
*   indian
*   islamic
*   hebrew
*   coptic
*   ethiopic

NOTE

For constant strings i.e. IntlDateFormatter::FULL Intl uses ICU library that feeds its data from CLDR ([https://cldr.unicode.org/](https://cldr.unicode.org/)
) which version may vary depending on PHP installation and give different results.

### DateTime::nice() [​](https://book.cakephp.org/6.x/core-libraries/time.html#datetime-nice)

`method` Cake\\I18n\\DateTime::**nice**(): string

Print out a predefined 'nice' format:

    $time = DateTime::parse('2021-01-31 22:11:30', new \DateTimeZone('America/New_York'));
    
    // Outputs 'Jan 31, 2021, 10:11 PM' in en-US
    echo $time->nice();

1  
2  
3  
4  

You can alter the timezone in which the date is displayed without altering the `DateTime` object itself. This is useful when you store dates in one timezone, but want to display them in a user's own timezone:

    // Outputs 'Monday, February 1, 2021 at 4:11:30 AM Central European Standard Time'
    echo $time->i18nFormat(\IntlDateFormatter::FULL, 'Europe/Paris');
    
    // Outputs 'Monday, February 1, 2021 at 12:11:30 PM Japan Standard Time'
    echo $time->i18nFormat(\IntlDateFormatter::FULL, 'Asia/Tokyo');
    
    // Timezone is unchanged. Outputs 'America/New_York'
    echo $time->timezoneName;

1  
2  
3  
4  
5  
6  
7  
8  

Leaving the first parameter as `null` will use the default formatting string:

    // Outputs '2/1/21, 4:11 AM'
    echo $time->i18nFormat(null, 'Europe/Paris');

1  
2  

Finally, it is possible to use a different locale for displaying a date:

    // Outputs 'lundi 1 février 2021 à 04:11:30 heure normale d’Europe centrale'
    echo $time->i18nFormat(\IntlDateFormatter::FULL, 'Europe/Paris', 'fr-FR');
    
    // Outputs '1 févr. 2021 à 04:11'
    echo $time->nice('Europe/Paris', 'fr-FR');

1  
2  
3  
4  
5  

### Setting the Default Locale and Format String [​](https://book.cakephp.org/6.x/core-libraries/time.html#setting-the-default-locale-and-format-string)

The default locale in which dates are displayed when using `nice``i18nFormat` is taken from the directive [intl.default\_locale](https://www.php.net/manual/en/intl.configuration.php#ini.intl.default-locale)
. You can, however, modify this default at runtime:

    DateTime::setDefaultLocale('es-ES');
    Date::setDefaultLocale('es-ES');
    
    // Outputs '31 ene. 2021 22:11'
    echo $time->nice();

1  
2  
3  
4  
5  

From now on, datetimes will be displayed in the Spanish preferred format unless a different locale is specified directly in the formatting method.

Likewise, it is possible to alter the default formatting string to be used for `i18nFormat`:

    DateTime::setToStringFormat(\IntlDateFormatter::SHORT); // For any DateTime
    Date::setToStringFormat(\IntlDateFormatter::SHORT); // For any Date
    
    // The same method exists on Date, and DateTime
    DateTime::setToStringFormat([\
        \IntlDateFormatter::FULL,\
        \IntlDateFormatter::SHORT\
    ]);
    // Outputs 'Sunday, January 31, 2021 at 10:11 PM'
    echo $time;
    
    // The same method exists on Date and DateTime
    DateTime::setToStringFormat("EEEE, MMMM dd, yyyy 'at' KK:mm:ss a");
    // Outputs 'Sunday, January 31, 2021 at 10:11:30 PM'
    echo $time;

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

It is recommended to always use the constants instead of directly passing a date format string.

NOTE

Be aware that this is not a PHP Datetime string format! You need to use a ICU date formatting string as specified in the following resource: [https://unicode-org.github.io/icu/userguide/format\_parse/datetime/#datetime-format-syntax](https://unicode-org.github.io/icu/userguide/format_parse/datetime/#datetime-format-syntax)
.

### Formatting Relative Times [​](https://book.cakephp.org/6.x/core-libraries/time.html#formatting-relative-times)

### DateTime::timeAgoInWords() [​](https://book.cakephp.org/6.x/core-libraries/time.html#datetime-timeagoinwords)

`method` Cake\\I18n\\DateTime::**timeAgoInWords**(array $options = \[\]): string

Often it is useful to print times relative to the present:

    $time = new DateTime('Jan 31, 2021');
    // On June 12, 2021, this would output '4 months, 1 week, 6 days ago'
    echo $time->timeAgoInWords(
        ['format' => 'MMM d, YYY', 'end' => '+1 year']
    );

1  
2  
3  
4  
5  

The `end` option lets you define at which point after which relative times should be formatted using the `format` option. The `accuracy` option lets us control what level of detail should be used for each interval range:

    // Outputs '4 months ago'
    echo $time->timeAgoInWords([\
        'accuracy' => ['month' => 'month'],\
        'end' => '1 year'\
    ]);

1  
2  
3  
4  
5  

By setting `accuracy` to a string, you can specify what is the maximum level of detail you want output:

    $time = new DateTime('+23 hours');
    // Outputs 'in about a day'
    echo $time->timeAgoInWords([\
        'accuracy' => 'day'\
    ]);

1  
2  
3  
4  
5  

Conversion [​](https://book.cakephp.org/6.x/core-libraries/time.html#conversion)

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

### DateTime::toQuarter() [​](https://book.cakephp.org/6.x/core-libraries/time.html#datetime-toquarter)

`method` Cake\\I18n\\DateTime::**toQuarter**(): int|array

### DateTime::toQuarterRange() [​](https://book.cakephp.org/6.x/core-libraries/time.html#datetime-toquarterrange)

`method` Cake\\I18n\\DateTime::**toQuarterRange**(): array

Once created, you can convert `DateTime` instances into timestamps or quarter values:

    $time = new DateTime('2021-01-31');
    echo $time->toQuarter();  // Outputs '1'
    echo $time->toUnixString();  // Outputs '1612069200'

1  
2  
3  

Added in version 5.3.0

The `toQuarterRange()` method was added.

You can also get the date range for a quarter:

    $time = new DateTime('2021-01-31');
    $range = $time->toQuarterRange();
    // Outputs ['2021-01-01', '2021-03-31']
    
    $time = new DateTime('2021-12-25');
    $range = $time->toQuarterRange();
    // Outputs ['2021-10-01', '2021-12-31']

1  
2  
3  
4  
5  
6  
7  

Comparing With the Present [​](https://book.cakephp.org/6.x/core-libraries/time.html#comparing-with-the-present)

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

### DateTime::isYesterday() [​](https://book.cakephp.org/6.x/core-libraries/time.html#datetime-isyesterday)

`method` Cake\\I18n\\DateTime::**isYesterday**()

### DateTime::isThisWeek() [​](https://book.cakephp.org/6.x/core-libraries/time.html#datetime-isthisweek)

`method` Cake\\I18n\\DateTime::**isThisWeek**()

### DateTime::isThisMonth() [​](https://book.cakephp.org/6.x/core-libraries/time.html#datetime-isthismonth)

`method` Cake\\I18n\\DateTime::**isThisMonth**()

### DateTime::isThisYear() [​](https://book.cakephp.org/6.x/core-libraries/time.html#datetime-isthisyear)

`method` Cake\\I18n\\DateTime::**isThisYear**()

You can compare a `DateTime` instance with the present in a variety of ways:

    $time = new DateTime('+3 days');
    
    debug($time->isYesterday());
    debug($time->isThisWeek());
    debug($time->isThisMonth());
    debug($time->isThisYear());

1  
2  
3  
4  
5  
6  

Each of the above methods will return `true`/`false` based on whether or not the `DateTime` instance matches the present.

Comparing With Intervals [​](https://book.cakephp.org/6.x/core-libraries/time.html#comparing-with-intervals)

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

### DateTime::isWithinNext() [​](https://book.cakephp.org/6.x/core-libraries/time.html#datetime-iswithinnext)

`method` Cake\\I18n\\DateTime::**isWithinNext**($interval)

You can see if a `DateTime` instance falls within a given range using `wasWithinLast()` and `isWithinNext()`:

    $time = new DateTime('+3 days');
    
    // Within 2 days. Outputs 'false'
    debug($time->isWithinNext('2 days'));
    
    // Within 2 next weeks. Outputs 'true'
    debug($time->isWithinNext('2 weeks'));

1  
2  
3  
4  
5  
6  
7  

### DateTime::wasWithinLast() [​](https://book.cakephp.org/6.x/core-libraries/time.html#datetime-waswithinlast)

`method` Cake\\I18n\\DateTime::**wasWithinLast**($interval)

You can also compare a `DateTime` instance within a range in the past:

    $time = new DateTime('-72 hours');
    
    // Within past 2 days. Outputs 'false'
    debug($time->wasWithinLast('2 days'));
    
    // Within past 3 days. Outputs 'true'
    debug($time->wasWithinLast('3 days'));
    
    // Within past 2 weeks. Outputs 'true'
    debug($time->wasWithinLast('2 weeks'));

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

Date [​](https://book.cakephp.org/6.x/core-libraries/time.html#date)

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

`class` Cake\\I18n\\**Date**

The immutable `Date` class in CakePHP represents calendar dates unaffected by time and timezones. The `Date` class wraps the `Cake\Chronos\ChronosDate` class.

NOTE

Unlike the `DateTime` class, `Date` does not extends the `DateTimeInterface`. So you cannot cannot directly compare a `Date` instance with a `DateTime` instance. But you can do comparisons like `$dateTime->toNative() > $date->toNative()`.

Time [​](https://book.cakephp.org/6.x/core-libraries/time.html#time)

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

`class` Cake\\I18n\\**Time**

The `Time` class represents clock times independent of date or time zones Similar to the `DateTime` and `` `Date `` classes, the `Time` class is also immutable. It wraps the `Cake\Chronos\ChronosTime` class.

Accepting Localized Request Data [​](https://book.cakephp.org/6.x/core-libraries/time.html#accepting-localized-request-data)

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

When creating text inputs that manipulate dates, you'll probably want to accept and parse localized datetime strings. See the [Parsing Localized Dates](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html#parsing-localized-dates)
.

Supported Timezones [​](https://book.cakephp.org/6.x/core-libraries/time.html#supported-timezones)

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

CakePHP supports all valid PHP timezones. For a list of supported timezones, [see this page](https://php.net/manual/en/timezones.php)
.

---

# Http Client | CakePHP

[Skip to content](https://book.cakephp.org/6.x/core-libraries/httpclient.html#VPContent)

Return to top

Http Client [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#http-client)

=========================================================================================

`class` Cake\\Http\\**Client**(mixed $config = \[\])

CakePHP includes a PSR-18 compliant HTTP client which can be used for making requests. It is a great way to communicate with webservices, and remote APIs.

Doing Requests [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#doing-requests)

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

Doing requests is simple and straight forward. Doing a GET request looks like:

    use Cake\Http\Client;
    
    $http = new Client();
    
    // Simple get
    $response = $http->get('http://example.com/test.html');
    
    // Simple get with querystring
    $response = $http->get('http://example.com/search', ['q' => 'widget']);
    
    // Simple get with querystring & additional headers
    $response = $http->get('http://example.com/search', ['q' => 'widget'], [\
      'headers' => ['X-Requested-With' => 'XMLHttpRequest'],\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

Doing POST and PUT requests is equally simple:

    // Send a POST request with application/x-www-form-urlencoded encoded data
    $http = new Client();
    $response = $http->post('http://example.com/posts/add', [\
      'title' => 'testing',\
      'body' => 'content in the post',\
    ]);
    
    // Send a PUT request with application/x-www-form-urlencoded encoded data
    $response = $http->put('http://example.com/posts/add', [\
      'title' => 'testing',\
      'body' => 'content in the post',\
    ]);
    
    // Other methods as well.
    $http->delete(/* ... */);
    $http->head(/* ... */);
    $http->patch(/* ... */);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

If you have created a PSR-7 request object you can send it using `sendRequest()`:

    use Cake\Http\Client;
    use Cake\Http\Client\Request as ClientRequest;
    
    $request = new ClientRequest(
        'http://example.com/search',
        ClientRequest::METHOD_GET
    );
    $http = new Client();
    $response = $http->sendRequest($request);

1  
2  
3  
4  
5  
6  
7  
8  
9  

Creating Multipart Requests with Files [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#creating-multipart-requests-with-files)

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

You can include files in request bodies by including a filehandle in the array:

    $http = new Client();
    $response = $http->post('http://example.com/api', [\
      'image' => fopen('/path/to/a/file', 'r'),\
    ]);

1  
2  
3  
4  

The filehandle will be read until its end; it will not be rewound before being read.

### Building Multipart Request Bodies [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#building-multipart-request-bodies)

There may be times when you need to build a request body in a very specific way. In these situations you can often use `Cake\Http\Client\FormData` to craft the specific multipart HTTP request you want:

    use Cake\Http\Client\FormData;
    
    $data = new FormData();
    
    // Create an XML part
    $xml = $data->newPart('xml', $xmlString);
    // Set the content type.
    $xml->type('application/xml');
    $data->add($xml);
    
    // Create a file upload with addFile()
    // This will append the file to the form data as well.
    $file = $data->addFile('upload', fopen('/some/file.txt', 'r'));
    $file->contentId('abc123');
    $file->disposition('attachment');
    
    // Send the request.
    $response = $http->post(
        'http://example.com/api',
        (string)$data,
        ['headers' => ['Content-Type' => $data->contentType()]]
    );

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  

Sending Request Bodies [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#sending-request-bodies)

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

When dealing with REST APIs you often need to send request bodies that are not form encoded. Http\\Client exposes this through the type option:

    // Send a JSON request body.
    $http = new Client();
    $response = $http->post(
      'http://example.com/tasks',
      json_encode($data),
      ['type' => 'json']
    );

1  
2  
3  
4  
5  
6  
7  

The `type` key can either be a one of 'json', 'xml' or a full mime type. When using the `type` option, you should provide the data as a string. If you're doing a GET request that needs both querystring parameters and a request body you can do the following:

    // Send a JSON body in a GET request with query string parameters.
    $http = new Client();
    $response = $http->get(
      'http://example.com/tasks',
      ['q' => 'test', '_content' => json_encode($data)],
      ['type' => 'json']
    );

1  
2  
3  
4  
5  
6  
7  

Request Method Options [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#request-method-options)

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

Each HTTP method takes an `$options` parameter which is used to provide addition request information. The following keys can be used in `$options`:

*   `headers` - Array of additional headers
*   `cookie` - Array of cookies to use.
*   `proxy` - Array of proxy information.
*   `auth` - Array of authentication data, the `type` key is used to delegate to an authentication strategy. By default Basic auth is used.
*   `ssl_verify_peer` - defaults to `true`. Set to `false` to disable SSL certification verification (not recommended).
*   `ssl_verify_peer_name` - defaults to `true`. Set to `false` to disable host name verification when verifying SSL certificates (not recommended).
*   `ssl_verify_depth` - defaults to 5. Depth to traverse in the CA chain.
*   `ssl_verify_host` - defaults to `true`. Validate the SSL certificate against the host name.
*   `ssl_cafile` - defaults to built in cafile. Overwrite to use custom CA bundles.
*   `timeout` - Duration to wait before timing out in seconds.
*   `type` - Send a request body in a custom content type. Requires `$data` to either be a string, or the `_content` option to be set when doing GET requests.
*   `redirect` - Number of redirects to follow. Defaults to `false`.
*   `curl` - An array of additional curl options (if the curl adapter is used), for example, `[CURLOPT_SSLKEY => 'key.pem']`.

The options parameter is always the 3rd parameter in each of the HTTP methods. They can also be used when constructing `Client` to create [scoped clients](https://book.cakephp.org/6.x/core-libraries/httpclient.html#http-client-scoped-client)
.

Authentication [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#authentication)

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

`Cake\Http\Client` supports a few different authentication systems. Different authentication strategies can be added by developers. Auth strategies are called before the request is sent, and allow headers to be added to the request context.

### Using Basic Authentication [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#using-basic-authentication)

An example of basic authentication:

    $http = new Client();
    $response = $http->get('http://example.com/profile/1', [], [\
      'auth' => ['username' => 'mark', 'password' => 'secret'],\
    ]);

1  
2  
3  
4  

By default `Cake\Http\Client` will use basic authentication if there is no `'type'` key in the auth option.

### Using Digest Authentication [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#using-digest-authentication)

An example of basic authentication:

    $http = new Client();
    $response = $http->get('http://example.com/profile/1', [], [\
        'auth' => [\
            'type' => 'digest',\
            'username' => 'mark',\
            'password' => 'secret',\
            'realm' => 'myrealm',\
            'nonce' => 'onetimevalue',\
            'qop' => 1,\
            'opaque' => 'someval',\
        ],\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

By setting the 'type' key to 'digest', you tell the authentication subsystem to use digest authentication. Digest authentication supports the following algorithms:

*   MD5
*   SHA-256
*   SHA-512-256
*   MD5-sess
*   SHA-256-sess
*   SHA-512-256-sess

The algorithm will be automatically chosen based on the server challenge.

### OAuth 1 Authentication [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#oauth-1-authentication)

Many modern web-services require OAuth authentication to access their APIs. The included OAuth authentication assumes that you already have your consumer key and consumer secret:

    $http = new Client();
    $response = $http->get('http://example.com/profile/1', [], [\
        'auth' => [\
            'type' => 'oauth',\
            'consumerKey' => 'bigkey',\
            'consumerSecret' => 'secret',\
            'token' => '...',\
            'tokenSecret' => '...',\
            'realm' => 'tickets',\
        ],\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

### OAuth 2 Authentication [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#oauth-2-authentication)

Because OAuth2 is often a single header, there is not a specialized authentication adapter. Instead you can create a client with the access token:

    $http = new Client([\
        'headers' => ['Authorization' => 'Bearer ' . $accessToken],\
    ]);
    $response = $http->get('https://example.com/api/profile/1');

1  
2  
3  
4  

### Proxy Authentication [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#proxy-authentication)

Some proxies require authentication to use them. Generally this authentication is Basic, but it can be implemented by any authentication adapter. By default Http\\Client will assume Basic authentication, unless the type key is set:

    $http = new Client();
    $response = $http->get('http://example.com/test.php', [], [\
        'proxy' => [\
            'username' => 'mark',\
            'password' => 'testing',\
            'proxy' => '127.0.0.1:8080',\
        ],\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  

The second proxy parameter must be a string with an IP or a domain without protocol. The username and password information will be passed through the request headers, while the proxy string will be passed through [stream\_context\_create()](https://php.net/manual/en/function.stream-context-create.php)
.

Creating Scoped Clients [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#creating-scoped-clients)

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

Having to re-type the domain name, authentication and proxy settings can become tedious & error prone. To reduce the chance for mistake and relieve some of the tedium, you can create scoped clients:

    // Create a scoped client.
    $http = new Client([\
        'host' => 'api.example.com',\
        'scheme' => 'https',\
        'auth' => ['username' => 'mark', 'password' => 'testing'],\
    ]);
    
    // Do a request to api.example.com
    $response = $http->get('/test.php');

1  
2  
3  
4  
5  
6  
7  
8  
9  

If your scoped client only needs information from the URL you can use `createFromUrl()`:

    $http = Client::createFromUrl('https://api.example.com/v1/test');

1  

The above would create a client instance with the `protocol`, `host`, and `basePath` options set.

The following information can be used when creating a scoped client:

*   host
*   basePath
*   scheme
*   proxy
*   auth
*   port
*   cookies
*   timeout
*   ssl\_verify\_peer
*   ssl\_verify\_depth
*   ssl\_verify\_host

Any of these options can be overridden by specifying them when doing requests. host, scheme, proxy, port are overridden in the request URL:

    // Using the scoped client we created earlier.
    $response = $http->get('http://foo.com/test.php');

1  
2  

The above will replace the domain, scheme, and port. However, this request will continue using all the other options defined when the scoped client was created. See [Http Client Request Options](https://book.cakephp.org/6.x/core-libraries/httpclient.html#http-client-request-options)
 for more information on the options supported.

Setting and Managing Cookies [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#setting-and-managing-cookies)

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

Http\\Client can also accept cookies when making requests. In addition to accepting cookies, it will also automatically store valid cookies set in responses. Any response with cookies, will have them stored in the originating instance of Http\\Client. The cookies stored in a Client instance are automatically included in future requests to domain + path combinations that match:

    $http = new Client([\
        'host' => 'cakephp.org'\
    ]);
    
    // Do a request that sets some cookies
    $response = $http->get('/');
    
    // Cookies from the first request will be included
    // by default.
    $response2 = $http->get('/changelogs');

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

You can always override the auto-included cookies by setting them in the request's `$options` parameters:

    // Replace a stored cookie with a custom value.
    $response = $http->get('/changelogs', [], [\
        'cookies' => ['sessionid' => '123abc'],\
    ]);

1  
2  
3  
4  

You can add cookie objects to the client after creating it using the `addCookie()` method:

    use Cake\Http\Cookie\Cookie;
    
    $http = new Client([\
        'host' => 'cakephp.org'\
    ]);
    $http->addCookie(new Cookie('session', 'abc123'));

1  
2  
3  
4  
5  
6  

Client Events [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#client-events)

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

`Client` will emit events when requests are sent. The `HttpClient.beforeSend` event is fired before a request is sent, and `HttpClient.afterSend` is fired after a request is sent. You can modify the request, or set a response in a `beforeSend` listener. The `afterSend` event is triggered for all requests, even those that have their responses set by a `beforeSend` event.

Response Objects [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#response-objects)

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

`class` Cake\\Http\\Client\\**Response**

Response objects have a number of methods for inspecting the response data.

### Reading Response Bodies [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#reading-response-bodies)

You read the entire response body as a string:

    // Read the entire response as a string.
    $response->getStringBody();

1  
2  

You can also access the stream object for the response and use its methods:

    // Get a Psr\Http\Message\StreamInterface containing the response body
    $stream = $response->getBody();
    
    // Read a stream 100 bytes at a time.
    while (!$stream->eof()) {
        echo $stream->read(100);
    }

1  
2  
3  
4  
5  
6  
7  

### Reading JSON and XML Response Bodies [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#reading-json-and-xml-response-bodies)

Since JSON and XML responses are commonly used, response objects provide a way to use accessors to read decoded data. JSON data is decoded into an array, while XML data is decoded into a `SimpleXMLElement` tree:

    // Get some XML
    $http = new Client();
    $response = $http->get('http://example.com/test.xml');
    $xml = $response->getXml();
    
    // Get some JSON
    $http = new Client();
    $response = $http->get('http://example.com/test.json');
    $json = $response->getJson();

1  
2  
3  
4  
5  
6  
7  
8  
9  

The decoded response data is stored in the response object, so accessing it multiple times has no additional cost.

### Accessing Response Headers [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#accessing-response-headers)

You can access headers through a few different methods. Header names are always treated as case-insensitive values when accessing them through methods:

    // Get all the headers as an associative array.
    $response->getHeaders();
    
    // Get a single header as an array.
    $response->getHeader('content-type');
    
    // Get a header as a string
    $response->getHeaderLine('content-type');
    
    // Get the response encoding
    $response->getEncoding();

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

### Accessing Cookie Data [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#accessing-cookie-data)

You can read cookies with a few different methods depending on how much data you need about the cookies:

    // Get all cookies (full data)
    $response->getCookies();
    
    // Get a single cookie's value.
    $response->getCookie('session_id');
    
    // Get a the complete data for a single cookie
    // includes value, expires, path, httponly, secure keys.
    $response->getCookieData('session_id');

1  
2  
3  
4  
5  
6  
7  
8  
9  

### Checking the Status Code [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#checking-the-status-code)

Response objects provide a few methods for checking status codes:

    // Was the response a 20x
    $response->isOk();
    
    // Was the response a 30x
    $response->isRedirect();
    
    // Get the status code
    $response->getStatusCode();

1  
2  
3  
4  
5  
6  
7  
8  

Changing Transport Adapters [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#changing-transport-adapters)

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

By default `Http\Client` will prefer using a `curl` based transport adapter. If the curl extension is not available a stream based adapter will be used instead. You can force select a transport adapter using a constructor option:

    use Cake\Http\Client\Adapter\Stream;
    
    $http = new Client(['adapter' => Stream::class]);

1  
2  
3  

Events [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#events)

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

The HTTP client triggers couple of events before and after sending a request which allows you to modify either the request or response or do other tasks like caching, logging etc.

### HttpClient.beforeSend [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#httpclient-beforesend)

    // Somewhere before calling one of the HTTP client's methods which makes a request
    $http->getEventManager()->on(
        'HttpClient.beforeSend',
        function (
            \Cake\Http\Client\ClientEvent $event,
            \Cake\Http\Client\Request $request,
            array $adapterOptions,
            int $redirects
        ) {
            // Modify the request
            $event->setRequest(....);
            // Modify the adapter options
            $event->setAdapterOptions(....);
    
            // Skip making the actual request by returning a response.
            // You can use $event->setResult($response) to achieve the same.
            return new \Cake\Http\Client\Response(body: 'something');
        }
    );

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  

### HttpClient.afterSend [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#httpclient-aftersend)

    // Somewhere before calling one of the HTTP client's methods which makes a request
    $http->getEventManager()->on(
        'HttpClient.afterSend',
        function (
            \Cake\Http\Client\ClientEvent $event,
            \Cake\Http\Client\Request $request,
            array $adapterOptions,
            int $redirects,
            bool $requestSent // Indicates whether the request was actually sent
                              // or response returned from ``beforeSend`` event
        ) {
            // Get the response
            $response = $event->getResponse();
    
            // Return a new/modified response.
            // You can use $event->setResult($response) to achieve the same.
            return new \Cake\Http\Client\Response(body: 'something');
        }
    );

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  

Testing [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#testing)

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

In tests you will often want to create mock responses to external APIs. You can use the `HttpClientTrait` to define responses to the requests your application is making:

    use Cake\Http\TestSuite\HttpClientTrait;
    use Cake\TestSuite\TestCase;
    
    class CartControllerTests extends TestCase
    {
        use HttpClientTrait;
    
        public function testCheckout()
        {
            // Mock a POST request that will be made.
            $this->mockClientPost(
                'https://example.com/process-payment',
                $this->newClientResponse(200, [], json_encode(['ok' => true]))
            );
            $this->post("/cart/checkout");
            // Do assertions.
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

There are methods to mock the most commonly used HTTP methods:

    $this->mockClientGet(/* ... */);
    $this->mockClientPatch(/* ... */);
    $this->mockClientPost(/* ... */);
    $this->mockClientPut(/* ... */);
    $this->mockClientDelete(/* ... */);

1  
2  
3  
4  
5  

### Response::newClientResponse() [​](https://book.cakephp.org/6.x/core-libraries/httpclient.html#response-newclientresponse)

`method` Cake\\Http\\TestSuite\\Response::**newClientResponse**(int $code = 200, array $headers = \[\], string $body = '')

As seen above you can use the `newClientResponse()` method to create responses for the requests your application will make. The headers need to be a list of strings:

    $headers = [\
        'Content-Type: application/json',\
        'Connection: close',\
    ];
    $response = $this->newClientResponse(200, $headers, $body)

1  
2  
3  
4  
5

---

# RssHelper | CakePHP

[Skip to content](https://book.cakephp.org/2.x/core-libraries/helpers/rss.html#VPContent)

Return to top

RssHelper [​](https://book.cakephp.org/2.x/core-libraries/helpers/rss.html#rsshelper)

======================================================================================

`class` **RssHelper**(View $view, array $settings = array())

The RSS helper makes generating XML for RSS feeds easy.

Creating an RSS feed with the RssHelper [​](https://book.cakephp.org/2.x/core-libraries/helpers/rss.html#creating-an-rss-feed-with-the-rsshelper)

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

This example assumes you have a Posts Controller and Post Model already created and want to make an alternative view for RSS.

Creating an xml/rss version of posts/index is a snap with CakePHP. After a few simple steps you can simply append the desired extension .rss to `posts/index` making your URL `posts/index.rss`. Before we jump too far ahead trying to get our webservice up and running we need to do a few things. First parseExtensions needs to be activated, this is done in `app/Config/routes.php`:

    Router::parseExtensions('rss');

1  

In the call above we've activated the .rss extension. When using `Router::parseExtensions()` you can pass as many arguments or extensions as you want. This will activate each extension/content-type for use in your application. Now when the address `posts/index.rss` is requested you will get an xml version of your `posts/index`. However, first we need to edit the controller to add in the rss-specific code.

### Controller Code [​](https://book.cakephp.org/2.x/core-libraries/helpers/rss.html#controller-code)

It is a good idea to add RequestHandler to your PostsController's $components array. This will allow a lot of automagic to occur:

    public $components = array('RequestHandler');

1  

Our view will also use the `TextHelper` for formatting, so that should be added to the controller as well:

    public $helpers = array('Text');

1  

Before we can make an RSS version of our posts/index we need to get a few things in order. It may be tempting to put the channel metadata in the controller action and pass it to your view using the `Controller::set()` method but this is inappropriate. That information can also go in the view. That will come later though, for now if you have a different set of logic for the data used to make the RSS feed and the data for the HTML view you can use the `RequestHandler::isRss()` method, otherwise your controller can stay the same:

    // Modify the Posts Controller action that corresponds to
    // the action which deliver the rss feed, which is the
    // index action in our example
    
    public function index() {
        if ($this->RequestHandler->isRss() ) {
            $posts = $this->Post->find(
                'all',
                array('limit' => 20, 'order' => 'Post.created DESC')
            );
            return $this->set(compact('posts'));
        }
    
        // this is not an Rss request, so deliver
        // data used by website's interface
        $this->paginate['Post'] = array(
            'order' => 'Post.created DESC',
            'limit' => 10
        );
    
        $posts = $this->paginate();
        $this->set(compact('posts'));
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  

With all the View variables set we need to create an rss layout.

### Layout [​](https://book.cakephp.org/2.x/core-libraries/helpers/rss.html#layout)

An Rss layout is very simple, put the following contents in `app/View/Layouts/rss/default.ctp`:

    if (!isset($documentData)) {
        $documentData = array();
    }
    if (!isset($channelData)) {
        $channelData = array();
    }
    if (!isset($channelData['title'])) {
        $channelData['title'] = $this->fetch('title');
    }
    $channel = $this->Rss->channel(array(), $channelData, $this->fetch('content'));
    echo $this->Rss->document($documentData, $channel);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

It doesn't look like much but thanks to the power in the `RssHelper` it's doing a lot of lifting for us. We haven't set `$documentData` or `$channelData` in the controller, however in CakePHP your views can pass variables back to the layout. Which is where our `$channelData` array will come from setting all of the meta data for our feed.

Next up is view file for my posts/index. Much like the layout file we created, we need to create a `View/Posts/rss/` directory and create a new `index.ctp` inside that folder. The contents of the file are below.

### View [​](https://book.cakephp.org/2.x/core-libraries/helpers/rss.html#view)

Our view, located at `app/View/Posts/rss/index.ctp`, begins by setting the `$documentData` and `$channelData` variables for the layout, these contain all the metadata for our RSS feed. This is done by using the `View::set()` method which is analogous to the `Controller::set()` method. Here though we are passing the channel's metadata back to the layout:

    $this->set('channelData', array(
        'title' => __("Most Recent Posts"),
        'link' => $this->Html->url('/', true),
        'description' => __("Most recent posts."),
        'language' => 'en-us'
    ));

1  
2  
3  
4  
5  
6  

The second part of the view generates the elements for the actual records of the feed. This is accomplished by looping through the data that has been passed to the view ($items) and using the `RssHelper::item()` method. The other method you can use, `RssHelper::items()` which takes a callback and an array of items for the feed. (The method I have seen used for the callback has always been called `transformRss()`. There is one downfall to this method, which is that you cannot use any of the other helper classes to prepare your data inside the callback method because the scope inside the method does not include anything that is not passed inside, thus not giving access to the TimeHelper or any other helper that you may need. The `RssHelper::item()` transforms the associative array into an element for each key value pair.

NOTE

You will need to modify the $postLink variable as appropriate to your application.

    foreach ($posts as $post) {
        $postTime = strtotime($post['Post']['created']);
    
        $postLink = array(
            'controller' => 'posts',
            'action' => 'view',
            'year' => date('Y', $postTime),
            'month' => date('m', $postTime),
            'day' => date('d', $postTime),
            $post['Post']['slug']
        );
    
        // Remove & escape any HTML to make sure the feed content will validate.
        $bodyText = h(strip_tags($post['Post']['body']));
        $bodyText = $this->Text->truncate($bodyText, 400, array(
            'ending' => '...',
            'exact'  => true,
            'html'   => true,
        ));
    
        echo  $this->Rss->item(array(), array(
            'title' => $post['Post']['title'],
            'link' => $postLink,
            'guid' => array('url' => $postLink, 'isPermaLink' => 'true'),
            'description' => $bodyText,
            'pubDate' => $post['Post']['created']
        ));
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  

You can see above that we can use the loop to prepare the data to be transformed into XML elements. It is important to filter out any non-plain text characters out of the description, especially if you are using a rich text editor for the body of your blog. In the code above we used `strip_tags()` and `h()` to remove/escape any XML special characters from the content, as they could cause validation errors. Once we have set up the data for the feed, we can then use the `RssHelper::item()` method to create the XML in RSS format. Once you have all this setup, you can test your RSS feed by going to your site `/posts/index.rss` and you will see your new feed. It is always important that you validate your RSS feed before making it live. This can be done by visiting sites that validate the XML such as Feed Validator or the w3c site at [https://validator.w3.org/feed/](https://validator.w3.org/feed/)
.

NOTE

You may need to set the value of 'debug' in your core configuration to 1 or to 0 to get a valid feed, because of the various debug information added automagically under higher debug settings that break XML syntax or feed validation rules.

Rss Helper API [​](https://book.cakephp.org/2.x/core-libraries/helpers/rss.html#rss-helper-api)

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

> Current action
> 
> Base URL
> 
> POSTed model data
> 
> Name of the current field
> 
> Helpers used by the RSS Helper
> 
> URL to current action
> 
> Name of current model
> 
> Parameter array
> 
> Default spec version of generated RSS.

`method` RssHelper::**channel**(array $attrib = array (), array $elements = array (), mixed $content = null)

`method` RssHelper::**document**(array $attrib = array (), string $content = null)

`method` RssHelper::**elem**(string $name, array $attrib = array (), mixed $content = null, boolean $endTag = true)

`method` RssHelper::**item**(array $att = array (), array $elements = array ())

`method` RssHelper::**items**(array $items, mixed $callback = null)

`method` RssHelper::**time**(mixed $time)

---

# CakeTime | CakePHP

[Skip to content](https://book.cakephp.org/2.x/core-utility-libraries/time.html#VPContent)

Return to top

CakeTime [​](https://book.cakephp.org/2.x/core-utility-libraries/time.html#caketime)

=====================================================================================

`class` **CakeTime**

If you need `TimeHelper` functionalities outside of a `View`, use the `CakeTime` class:

    class UsersController extends AppController {
    
        public $components = array('Auth');
    
        public function afterLogin() {
            App::uses('CakeTime', 'Utility');
            if (CakeTime::isToday($this->Auth->user('date_of_birth']))) {
                // greet user with a happy birthday message
                $this->Session->setFlash(__('Happy birthday you...'));
            }
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

Added in version 2.1

`CakeTime` has been factored out from `TimeHelper`.

Formatting [​](https://book.cakephp.org/2.x/core-utility-libraries/time.html#formatting)

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

`method` CakeTime::**convert**($serverTime, $timezone = NULL)

`method` CakeTime::**convertSpecifiers**($format, $time = NULL)

`method` CakeTime::**dayAsSql**($dateString, $field\_name, $timezone = NULL)

`method` CakeTime::**daysAsSql**($begin, $end, $fieldName, $timezone = NULL)

`method` CakeTime::**format**($date, $format = NULL, $default = false, $timezone = NULL)

`method` CakeTime::**fromString**($dateString, $timezone = NULL)

`method` CakeTime::**gmt**($dateString = NULL)

`method` CakeTime::**i18nFormat**($date, $format = NULL, $invalid = false, $timezone = NULL)

`method` CakeTime::**nice**($dateString = NULL, $timezone = NULL, $format = null)

`method` CakeTime::**niceShort**($dateString = NULL, $timezone = NULL)

`method` CakeTime::**serverOffset**()

`method` CakeTime::**timeAgoInWords**($dateString, $options = array())

`method` CakeTime::**toAtom**($dateString, $timezone = NULL)

`method` CakeTime::**toQuarter**($dateString, $range = false)

`method` CakeTime::**toRSS**($dateString, $timezone = NULL)

`method` CakeTime::**toUnix**($dateString, $timezone = NULL)

`method` CakeTime::**toServer**($dateString, $timezone = NULL, $format = 'Y-m-d H:i:s')

`method` CakeTime::**timezone**($timezone = NULL)

`method` CakeTime::**listTimezones**($filter = null, $country = null, $options = array())

Testing Time [​](https://book.cakephp.org/2.x/core-utility-libraries/time.html#testing-time)

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

`method` CakeTime::**isToday**($dateString, $timezone = NULL)

`method` CakeTime::**isThisWeek**($dateString, $timezone = NULL)

`method` CakeTime::**isThisMonth**($dateString, $timezone = NULL)

`method` CakeTime::**isThisYear**($dateString, $timezone = NULL)

`method` CakeTime::**wasYesterday**($dateString, $timezone = NULL)

`method` CakeTime::**isTomorrow**($dateString, $timezone = NULL)

`method` CakeTime::**isFuture**($dateString, $timezone = NULL)

`method` CakeTime::**isPast**($dateString, $timezone = NULL)

`method` CakeTime::**wasWithinLast**($timeInterval, $dateString, $timezone = NULL)

---

# Code Generation with Bake | CakePHP

[Skip to content](https://book.cakephp.org/2.x/console-and-shells/code-generation-with-bake.html#VPContent)

Return to top

Code Generation with Bake [​](https://book.cakephp.org/2.x/console-and-shells/code-generation-with-bake.html#code-generation-with-bake)

========================================================================================================================================

CakePHP's Bake console is another effort to get you up and running in CakePHP – fast. The Bake console can create any of CakePHP's basic ingredients: models, views and controllers. And we aren't just talking skeleton classes: Bake can create a fully functional application in just a few minutes. In fact, Bake is a natural step to take once an application has been scaffolded.

See [The Cakephp Console](https://book.cakephp.org/2.x/console-and-shells.html#the-cakephp-console)
 section for instructions on how to use the CakePHP console in general. Depending on the configuration of your setup, you may have to set execute rights on the cake bash script or call it using `./Console/cake bake`. The cake console is run using the PHP CLI (command line interface). If you have problems running the script, ensure that you have the PHP CLI installed and that it has the proper modules enabled (eg: MySQL) Users also might have issues if the database host is 'localhost' and should try '127.0.0.1' instead. This could cause issues with PHP CLI.

When running Bake for the first time, you'll be prompted to create a Database Configuration file, if you haven't created one already.

After you've created a Database Configuration file, running Bake will present you with the following options:

    ---------------------------------------------------------------
    App : app
    Path: /path-to/project/app
    ---------------------------------------------------------------
    Interactive Bake Shell
    ---------------------------------------------------------------
    [D]atabase Configuration
    [M]odel
    [V]iew
    [C]ontroller
    [P]roject
    [F]ixture
    [T]est case
    [Q]uit
    What would you like to Bake? (D/M/V/C/P/F/T/Q)
    >

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  

Alternatively, you can run any of these commands directly from the command line:

    $ cake bake db_config
    $ cake bake model
    $ cake bake view
    $ cake bake controller
    $ cake bake project
    $ cake bake fixture
    $ cake bake test
    $ cake bake plugin plugin_name
    $ cake bake all

1  
2  
3  
4  
5  
6  
7  
8  
9  

Changed in version 2.5

Test files produced by `bake test` include calls to [PHPunit's markTestIncomplete()](https://phpunit.de/manual/3.7/en/incomplete-and-skipped-tests.html)
 to draw attention to empty test methods. Before 2.5, empty tests pass silently.

Modify default HTML produced by "baked" templates [​](https://book.cakephp.org/2.x/console-and-shells/code-generation-with-bake.html#modify-default-html-produced-by-baked-templates)

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

If you wish to modify the default HTML output produced by the "bake" command, follow these simple steps:

### For baking custom views [​](https://book.cakephp.org/2.x/console-and-shells/code-generation-with-bake.html#for-baking-custom-views)

1.  Go into: lib/Cake/Console/Templates/default/views
2.  Notice the 4 files there
3.  Copy them to your: app/Console/Templates/\[themename\]/views
4.  Make changes to the HTML output to control the way "bake" builds your views

The `[themename]` path segment should be the name of the bake theme that you are creating. Bake theme names need to be unique, so don't use 'default'.

### For baking custom projects [​](https://book.cakephp.org/2.x/console-and-shells/code-generation-with-bake.html#for-baking-custom-projects)

1.  Go into: lib/Cake/Console/Templates/skel
2.  Notice the base application files there
3.  Copy them to your: app/Console/Templates/skel
4.  Make changes to the HTML output to control the way "bake" builds your views
5.  Pass the skeleton path parameter to the project task

    cake bake project --skel Console/Templates/skel
    

Note

*   You must run the specific project task `cake bake project` so that the path parameter can be passed.
*   The template path is relative to the current path of the Command Line Interface.
*   Since the full path to the skeleton needs to be manually entered, you can specify any directory holding your template build you want, including using multiple templates. (Unless CakePHP starts supporting overriding the skel folder like it does for views)

---

# Test shell | CakePHP

[Skip to content](https://book.cakephp.org/2.x/console-and-shells/testsuite-shell.html#VPContent)

Return to top

Test shell [​](https://book.cakephp.org/2.x/console-and-shells/testsuite-shell.html#test-shell)

================================================================================================

Once you've started writing [Tests](https://book.cakephp.org/2.x/development/testing.html)
 you can run them using the test shell.

For more information on basic usage of the test shell see [Run Tests From Command Line](https://book.cakephp.org/2.x/development/testing.html#run-tests-from-command-line)
.

Changed in version 2.1

The `test` shell was added in 2.1. The 2.0 `testsuite` shell is still available but the new syntax is preferred.

---

# Development | CakePHP

[Skip to content](https://book.cakephp.org/2.x/development.html#VPContent)

Return to top

Development [​](https://book.cakephp.org/2.x/development.html#development)

===========================================================================

In this section we'll cover the various aspects of developing a CakePHP application. Topics like Configuration, handling errors & exceptions, debugging, and testing will be covered.

*   [Configuration](https://book.cakephp.org/2.x/development/configuration.html)
    
*   [Routing](https://book.cakephp.org/2.x/development/routing.html)
    
*   [Sessions](https://book.cakephp.org/2.x/development/sessions.html)
    
*   [Exceptions](https://book.cakephp.org/2.x/development/exceptions.html)
    
*   [Error Handling](https://book.cakephp.org/2.x/development/errors.html)
    
*   [Debugging](https://book.cakephp.org/2.x/development/debugging.html)
    
*   [Testing](https://book.cakephp.org/2.x/development/testing.html)
    
*   [REST](https://book.cakephp.org/2.x/development/rest.html)
    
*   [Dispatcher Filters](https://book.cakephp.org/2.x/development/dispatch-filters.html)

---

# PaginatorHelper | CakePHP

[Skip to content](https://book.cakephp.org/2.x/core-libraries/helpers/paginator.html#VPContent)

Return to top

PaginatorHelper [​](https://book.cakephp.org/2.x/core-libraries/helpers/paginator.html#paginatorhelper)

========================================================================================================

`class` **PaginatorHelper**(View $view, array $settings = array())

The Pagination helper is used to output pagination controls such as page numbers and next/previous links. It works in tandem with `PaginatorComponent`.

See also [Pagination](https://book.cakephp.org/2.x/core-libraries/components/pagination.html)
 for information on how to create paginated datasets and do paginated queries.

Creating sort links [​](https://book.cakephp.org/2.x/core-libraries/helpers/paginator.html#creating-sort-links)

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

`method` PaginatorHelper::**sort**($key, $title = null, $options = array())

Generates a sorting link. Sets named or querystring parameters for the sort and direction. Links will default to sorting by asc. After the first click, links generated with `sort()` will handle direction switching automatically. Link sorting default by 'asc'. If the resultset is sorted 'asc' by the specified key the returned link will sort by 'desc'.

Accepted keys for `$options`:

*   `escape` Whether you want the contents HTML entity encoded, defaults to true.
    
*   `model` The model to use, defaults to `PaginatorHelper::defaultModel()`.
    
*   `direction` The default direction to use when this link isn't active.
    
*   `lock` Lock direction. Will only use the default direction then, defaults to false.
    
    Added in version 2.5
    
    You can now set the lock option to true in order to lock the sorting direction into the specified direction.
    

Assuming you are paginating some posts, and are on page one:

    echo $this->Paginator->sort('user_id');

1  

Output:

    <a href="/posts/index/page:1/sort:user_id/direction:asc/">User Id</a>

1  

You can use the title parameter to create custom text for your link:

    echo $this->Paginator->sort('user_id', 'User account');

1  

Output:

    <a href="/posts/index/page:1/sort:user_id/direction:asc/">User account</a>

1  

If you are using HTML like images in your links remember to set escaping off:

    echo $this->Paginator->sort(
      'user_id',
      '<em>User account</em>',
      array('escape' => false)
    );

1  
2  
3  
4  
5  

Output:

    <a href="/posts/index/page:1/sort:user_id/direction:asc/">
      <em>User account</em>
    </a>

1  
2  
3  

The direction option can be used to set the default direction for a link. Once a link is active, it will automatically switch directions like normal:

    echo $this->Paginator->sort('user_id', null, array('direction' => 'desc'));

1  

Output:

    <a href="/posts/index/page:1/sort:user_id/direction:desc/">User Id</a>

1  

The lock option can be used to lock sorting into the specified direction:

    echo $this->Paginator->sort('user_id', null, array('direction' => 'asc', 'lock' => true));

1  

`method` PaginatorHelper::**sortDir**(string $model = null, mixed $options = array())

`method` PaginatorHelper::**sortKey**(string $model = null, mixed $options = array())

Creating page number links [​](https://book.cakephp.org/2.x/core-libraries/helpers/paginator.html#creating-page-number-links)

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

`method` PaginatorHelper::**numbers**($options = array())

Returns a set of numbers for the paged result set. Uses a modulus to decide how many numbers to show on each side of the current page By default 8 links on either side of the current page will be created if those pages exist. Links will not be generated for pages that do not exist. The current page is also not a link.

Supported options are:

*   `before` Content to be inserted before the numbers.
    
*   `after` Content to be inserted after the numbers.
    
*   `model` Model to create numbers for, defaults to `PaginatorHelper::defaultModel()`.
    
*   `modulus` how many numbers to include on either side of the current page, defaults to 8.
    
*   `separator` Separator content defaults to `|`
    
*   `tag` The tag to wrap links in, defaults to 'span'.
    
*   `first` Whether you want first links generated, set to an integer to define the number of 'first' links to generate. Defaults to false. If a string is set a link to the first page will be generated with the value as the title:
    
        echo $this->Paginator->numbers(array('first' => 'First page'));
    
    1  
    
*   `last` Whether you want last links generated, set to an integer to define the number of 'last' links to generate. Defaults to false. Follows the same logic as the `first` option. There is a `~PaginatorHelper::last()`\` method to be used separately as well if you wish.
    
*   `ellipsis` Ellipsis content, defaults to '...'
    
*   `class` The class name used on the wrapping tag.
    
*   `currentClass` The class name to use on the current/active link. Defaults to _current_.
    
*   `currentTag` Tag to use for current page number, defaults to null. This allows you to generate for example Twitter Bootstrap like links with the current page number wrapped in extra 'a' or 'span' tag.
    

While this method allows a lot of customization for its output. It is also ok to just call the method without any params. :

    echo $this->Paginator->numbers();

1  

Using the first and last options you can create links to the beginning and end of the page set. The following would create a set of page links that include links to the first 2 and last 2 pages in the paged results:

    echo $this->Paginator->numbers(array('first' => 2, 'last' => 2));

1  

Added in version 2.1

The `currentClass` option was added in 2.1.

Added in version 2.3

The `currentTag` option was added in 2.3.

Creating jump links [​](https://book.cakephp.org/2.x/core-libraries/helpers/paginator.html#creating-jump-links)

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

In addition to generating links that go directly to specific page numbers, you'll often want links that go to the previous and next links, first and last pages in the paged data set.

`method` PaginatorHelper::**prev**($title = '<< Previous', $options = array(), $disabledTitle = null, $disabledOptions = array())

Changed in version 2.3

For methods: `PaginatorHelper::prev()` and `PaginatorHelper::next()` it is now possible to set the `tag` option to `false` to disable the wrapper. New options `disabledTag` has been added.If you leave the `$disabledOptions` empty the `$options` parameter will be used. This can save some additional typing if both sets of options are the same.

`method` PaginatorHelper::**next**($title = 'Next >>', $options = array(), $disabledTitle = null, $disabledOptions = array())

`method` PaginatorHelper::**first**($first = '<< first', $options = array())

`method` PaginatorHelper::**last**($last = 'last >>', $options = array())

`method` PaginatorHelper::**current**(string $model = null)

`method` PaginatorHelper::**hasNext**(string $model = null)

`method` PaginatorHelper::**hasPrev**(string $model = null)

`method` PaginatorHelper::**hasPage**(string $model = null, integer $page = 1)

Creating a page counter [​](https://book.cakephp.org/2.x/core-libraries/helpers/paginator.html#creating-a-page-counter)

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

`method` PaginatorHelper::**counter**($options = array())

Returns a counter string for the paged result set. Using a provided format string and a number of options you can create localized and application specific indicators of where a user is in the paged data set.

There are a number of options for `counter()`. The supported ones are:

*   `format` Format of the counter. Supported formats are 'range', 'pages' and custom. Defaults to pages which would output like '1 of 10'. In the custom mode the supplied string is parsed and tokens are replaced with actual values. The available tokens are:
    
    *   `{:page}` - the current page displayed.
    *   `{:pages}` - total number of pages.
    *   `{:current}` - current number of records being shown.
    *   `{:count}` - the total number of records in the result set.
    *   `{:start}` - number of the first record being displayed.
    *   `{:end}` - number of the last record being displayed.
    *   `{:model}` - The pluralized human form of the model name. If your model was 'RecipePage', `{:model}` would be 'recipe pages'. This option was added in 2.0.
    
    You could also supply only a string to the counter method using the tokens available. For example:
    
        echo $this->Paginator->counter(
            'Page {:page} of {:pages}, showing {:current} records out of
             {:count} total, starting on record {:start}, ending on {:end}'
        );
    
    1  
    2  
    3  
    4  
    
    Setting 'format' to range would output like '1 - 3 of 13':
    
        echo $this->Paginator->counter(array(
            'format' => 'range'
        ));
    
    1  
    2  
    3  
    
*   `separator` The separator between the actual page and the number of pages. Defaults to ' of '. This is used in conjunction with 'format' = 'pages' which is 'format' default value:
    
        echo $this->Paginator->counter(array(
            'separator' => ' of a total of '
        ));
    
    1  
    2  
    3  
    
*   `model` The name of the model being paginated, defaults to `PaginatorHelper::defaultModel()`. This is used in conjunction with the custom string on 'format' option.
    

Modifying the options PaginatorHelper uses [​](https://book.cakephp.org/2.x/core-libraries/helpers/paginator.html#modifying-the-options-paginatorhelper-uses)

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

`method` PaginatorHelper::**options**($options = array())

Sets all the options for the Paginator Helper. Supported options are:

*   `url` The URL of the paginating action. 'url' has a few sub options as well:
    
    *   `sort` The key that the records are sorted by.
    *   `direction` The direction of the sorting. Defaults to 'ASC'.
    *   `page` The page number to display.
    
    The above mentioned options can be used to force particular pages/directions. You can also append additional URL content into all URLs generated in the helper:
    
        $this->Paginator->options(array(
            'url' => array(
                'sort' => 'email', 'direction' => 'desc', 'page' => 6,
                'lang' => 'en'
            )
        ));
    
    1  
    2  
    3  
    4  
    5  
    6  
    
    The above adds the `en` route parameter to all links the helper will generate. It will also create links with specific sort, direction and page values. By default PaginatorHelper will merge in all of the current pass and named parameters. So you don't have to do that in each view file.
    
*   `escape` Defines if the title field for links should be HTML escaped. Defaults to true.
    
*   `update` The CSS selector of the element to update with the results of AJAX pagination calls. If not specified, regular links will be created:
    
        $this->Paginator->options(array('update' => '#content'));
    
    1  
    
    This is useful when doing [Ajax Pagination](https://book.cakephp.org/2.x/core-libraries/helpers/js.html#ajax-pagination)
    . Keep in mind that the value of update can be any valid CSS selector, but most often is simpler to use an id selector.
    
*   `model` The name of the model being paginated, defaults to `PaginatorHelper::defaultModel()`.
    

### Using GET parameters for pagination [​](https://book.cakephp.org/2.x/core-libraries/helpers/paginator.html#using-get-parameters-for-pagination)

Normally Pagination in CakePHP uses [Named Parameters](https://book.cakephp.org/2.x/development/routing.html#named-parameters)
. There are times you want to use GET parameters instead. While the main configuration option for this feature is in `PaginatorComponent`, you have some additional control in the view. You can use `options()` to indicate that you want other named parameters to be converted:

    $this->Paginator->options(array(
      'convertKeys' => array('your', 'keys', 'here')
    ));

1  
2  
3  

### Configuring the PaginatorHelper to use a JavaScript helper [​](https://book.cakephp.org/2.x/core-libraries/helpers/paginator.html#configuring-the-paginatorhelper-to-use-a-javascript-helper)

By default the `PaginatorHelper` uses `JsHelper` to do AJAX features. However, if you don't want that and want to use a custom helper for AJAX links, you can do so by changing the `$helpers` array in your controller. After running `paginate()` do the following:

    // In your controller action.
    $this->set('posts', $this->paginate());
    $this->helpers['Paginator'] = array('ajax' => 'CustomJs');

1  
2  
3  

Will change the `PaginatorHelper` to use the `CustomJs` for AJAX operations. You could also set the 'ajax' key to be any helper, as long as that class implements a `link()` method that behaves like `HtmlHelper::link()`

Pagination in Views [​](https://book.cakephp.org/2.x/core-libraries/helpers/paginator.html#pagination-in-views)

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

It's up to you to decide how to show records to the user, but most often this will be done inside HTML tables. The examples below assume a tabular layout, but the PaginatorHelper available in views doesn't always need to be restricted as such.

See the details on [PaginatorHelper](https://api.cakephp.org/2.x/class-PaginatorHelper.html)
 in the API. As mentioned, the PaginatorHelper also offers sorting features which can be easily integrated into your table column headers:

    // app/View/Posts/index.ctp
    <table>
        <tr>
            <th><?php echo $this->Paginator->sort('id', 'ID'); ?></th>
            <th><?php echo $this->Paginator->sort('title', 'Title'); ?></th>
        </tr>
           <?php foreach ($data as $recipe): ?>
        <tr>
            <td><?php echo $recipe['Recipe']['id']; ?> </td>
            <td><?php echo h($recipe['Recipe']['title']); ?> </td>
        </tr>
        <?php endforeach; ?>
    </table>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

The links output from the `sort()` method of the `PaginatorHelper` allow users to click on table headers to toggle the sorting of the data by a given field.

It is also possible to sort a column based on associations:

    <table>
        <tr>
            <th><?php echo $this->Paginator->sort('title', 'Title'); ?></th>
            <th><?php echo $this->Paginator->sort('Author.name', 'Author'); ?></th>
        </tr>
           <?php foreach ($data as $recipe): ?>
        <tr>
            <td><?php echo h($recipe['Recipe']['title']); ?> </td>
            <td><?php echo h($recipe['Author']['name']); ?> </td>
        </tr>
        <?php endforeach; ?>
    </table>

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

The final ingredient to pagination display in views is the addition of page navigation, also supplied by the PaginationHelper:

    // Shows the page numbers
    echo $this->Paginator->numbers();
    
    // Shows the next and previous links
    echo $this->Paginator->prev(
      '« Previous',
      null,
      null,
      array('class' => 'disabled')
    );
    echo $this->Paginator->next(
      'Next »',
      null,
      null,
      array('class' => 'disabled')
    );
    
    // prints X of Y, where X is current page and Y is number of pages
    echo $this->Paginator->counter();

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  

The wording output by the counter() method can also be customized using special markers:

    echo $this->Paginator->counter(array(
        'format' => 'Page {:page} of {:pages}, showing {:current} records out of
                 {:count} total, starting on record {:start}, ending on {:end}'
    ));

1  
2  
3  
4  

Other Methods [​](https://book.cakephp.org/2.x/core-libraries/helpers/paginator.html#other-methods)

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

`method` PaginatorHelper::**link**($title, $url = array(), $options = array())

`method` PaginatorHelper::**url**($options = array(), $asArray = false, $model = null)

`method` PaginatorHelper::**defaultModel**()

`method` PaginatorHelper::**params**(string $model = null)

`method` PaginatorHelper::**param**(string $key, string $model = null)

Added in version 2.4

The `param()` method was added in 2.4.

`method` PaginatorHelper::**meta**(array $options = array())

Added in version 2.6

The `meta()` method was added in 2.6.

---

# Events System | CakePHP

[Skip to content](https://book.cakephp.org/6.x/core-libraries/events.html#VPContent)

Return to top

Events System [​](https://book.cakephp.org/6.x/core-libraries/events.html#events-system)

=========================================================================================

Creating maintainable applications is both a science and an art. It is well-known that a key for having good quality code is making your objects loosely coupled and strongly cohesive at the same time. Cohesion means that all methods and properties for a class are strongly related to the class itself and it is not trying to do the job other objects should be doing, while loosely coupling is the measure of how little a class is "wired" to external objects, and how much that class is depending on them.

There are certain cases where you need to cleanly communicate with other parts of an application, without having to hard code dependencies, thus losing cohesion and increasing class coupling. Using the Observer pattern, which allows objects to notify other objects and anonymous listeners about changes is a useful pattern to achieve this goal.

Listeners in the observer pattern can subscribe to events and choose to act upon them if they are relevant. If you have used JavaScript, there is a good chance that you are already familiar with event driven programming.

CakePHP emulates several aspects of how events are triggered and managed in popular JavaScript libraries such as jQuery. In the CakePHP implementation, an event object is dispatched to all listeners. The event object holds information about the event, and provides the ability to stop event propagation at any point. Listeners can register themselves or can delegate this task to other objects and have the chance to alter the state and the event itself for the rest of the callbacks.

The event subsystem is at the heart of Model, Behavior, Controller, View and Helper callbacks. If you've ever used any of them, you are already somewhat familiar with events in CakePHP.

Example Event Usage [​](https://book.cakephp.org/6.x/core-libraries/events.html#example-event-usage)

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

Let's suppose you are building a Cart plugin, and you'd like to focus on just handling order logic. You don't really want to include shipping logic, emailing the user or decrementing the item from the stock, but these are important tasks to the people using your plugin. If you were not using events, you may try to implement this by attaching behaviors to models, or adding components to your controllers. Doing so represents a challenge most of the time, since you would have to come up with the code for externally loading those behaviors or attaching hooks to your plugin controllers.

Instead, you can use events to allow you to cleanly separate the concerns of your code and allow additional concerns to hook into your plugin using events. For example, in your Cart plugin you have an Orders model that deals with creating orders. You'd like to notify the rest of the application that an order has been created. To keep your Orders model clean you could use events:

    // Cart/Model/Table/OrdersTable.php
    namespace Cart\Model\Table;
    
    use Cake\Event\Event;
    use Cake\ORM\Table;
    
    class OrdersTable extends Table
    {
        public function place($order)
        {
            if ($this->save($order)) {
                $this->Cart->remove($order);
                $event = new Event('Order.afterPlace', $this, [\
                    'order' => $order\
                ]);
                $this->getEventManager()->dispatch($event);
    
                return true;
            }
    
            return false;
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  

The above code allows you to notify the other parts of the application that an order has been created. You can then do tasks like send email notifications, update stock, log relevant statistics and other tasks in separate objects that focus on those concerns.

Accessing Event Managers [​](https://book.cakephp.org/6.x/core-libraries/events.html#accessing-event-managers)

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

In CakePHP events are triggered against event managers. Event managers are available in every Table, View and Controller using `getEventManager()`:

    $events = $this->getEventManager();

1  

Each model has a separate event manager, while the View and Controller share one. This allows model events to be self contained, and allow components or controllers to act upon events created in the view if necessary.

### Global Event Manager [​](https://book.cakephp.org/6.x/core-libraries/events.html#global-event-manager)

In addition to instance level event managers, CakePHP provides a global event manager that allows you to listen to any event fired in an application. This is useful when attaching listeners to a specific instance might be cumbersome or difficult. The global manager is a singleton instance of `Cake\Event\EventManager`. Listeners attached to the global dispatcher will be fired before instance listeners at the same priority. You can access the global manager using a static method:

    // In any configuration file or piece of code that executes before the event
    use Cake\Event\EventManager;
    
    EventManager::instance()->on(
        'Order.afterPlace',
        $aCallback
    );

1  
2  
3  
4  
5  
6  
7  

One important thing you should consider is that there are events that will be triggered having the same name but different subjects, so checking it in the event object is usually required in any function that gets attached globally in order to prevent some bugs. Remember that with the flexibility of using the global manager, some additional complexity is incurred.

`Cake\Event\EventManager::dispatch()` method accepts the event object as an argument and notifies all listener and callbacks passing this object along. The listeners will handle all the extra logic around the `afterPlace` event, you can log the time, send emails, update user statistics possibly in separate objects and even delegating it to offline tasks if you have the need.

### Tracking Events [​](https://book.cakephp.org/6.x/core-libraries/events.html#tracking-events)

To keep a list of events that are fired on a particular `EventManager`, you can enable event tracking. To do so, simply attach an `Cake\Event\EventList` to the manager:

    EventManager::instance()->setEventList(new EventList());

1  

After firing an event on the manager, you can retrieve it from the event list:

    $eventsFired = EventManager::instance()->getEventList();
    $firstEvent = $eventsFired[0];

1  
2  

Tracking can be disabled by removing the event list or calling `Cake\Event\EventManager::trackEvents(false)`.

Core Events [​](https://book.cakephp.org/6.x/core-libraries/events.html#core-events)

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

There are a number of core events within the framework which your application can listen to. Each layer of CakePHP emits events that you can use in your application.

*   [ORM/Model events](https://book.cakephp.org/6.x/orm/table-objects.html#table-callbacks)
    
*   [Controller events](https://book.cakephp.org/6.x/controllers.html#controller-life-cycle)
    
*   [View events](https://book.cakephp.org/6.x/views.html#view-events)
    

### `Server.terminate` [​](https://book.cakephp.org/6.x/core-libraries/events.html#server-terminate)

The `Server.terminate` event is triggered after the response has been sent to the client. This event is useful for performing tasks that should be done after the response has been sent, such as logging or sending emails.

You can listen to this event using an event manager instance:

    use Cake\Event\EventManager;
    
    EventManager::instance()->on('Server.terminate', function ($event) {
        // Perform tasks that should be done after the response has been
        // sent to the client.
    });

1  
2  
3  
4  
5  
6  

Or using the `events` hook in your Application/Plugin class:

    use Cake\Event\EventManagerInterface;
    
    public function events(EventManagerInterface $eventManager): EventManagerInterface
    {
        $eventManager->on('Server.terminate', function ($event) {
            // Perform tasks that should be done after the response has been
            // sent to the client.
        });
    
        return $eventManager;
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

TIP

This is called even if an exception is thrown during the request, e.g. on 404 pages.

NOTE

The `Server.terminate` event only works for PHP-FPM implementations which support the `fastcgi_finish_request` function.

### `Command.beforeExecute` & `Command.afterExecute` [​](https://book.cakephp.org/6.x/core-libraries/events.html#command-beforeexecute-command-afterexecute)

Added in version 5.0.0

The `Command.beforeExecute` & `Command.afterExecute` events were added in 5.0

The `Command.beforeExecute` & `Command.afterExecute` events are triggered before and after a command has been executed. Both events contain the `args` which are passed to the command and the `afterExecute` event also contains the `exitCode` which is returned by the command.

You can listen to this event using an event manager instance:

    use Cake\Event\EventManager;
    
    EventManager::instance()->on('Command.beforeExecute', function ($event, $args) {
        $command = $event->getSubject();
        // Do stuff here
    });
    
    EventManager::instance()->on('Command.afterExecute', function ($event, $args, $result) {
        $command = $event->getSubject();
        // Do stuff here
    });

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

Or using the `events` hook in your Application/Plugin class:

    use Cake\Event\EventManagerInterface;
    
    public function events(EventManagerInterface $eventManager): EventManagerInterface
    {
        $eventManager->on('Command.beforeExecute', function ($event, $args) {
            $command = $event->getSubject();
            // Do stuff here
        });
    
        $eventManager->on('Command.afterExecute', function ($event, $args, $result) {
            $command = $event->getSubject();
            // Do stuff here
        });
    
        return $eventManager;
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  

Registering Listeners [​](https://book.cakephp.org/6.x/core-libraries/events.html#registering-listeners)

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

Listeners are the preferred way to register callbacks for an event. This is done by implementing the `Cake\Event\EventListenerInterface` interface in any class you wish to register some callbacks. Classes implementing it need to provide the `implementedEvents()` method. This method must return an associative array with all event names that the class will handle.

To continue our previous example, let's imagine we have a UserStatistic class responsible for calculating a user's purchasing history, and compiling into global site statistics. This is a great place to use a listener class. Doing so allows you to concentrate the statistics logic in one place and react to events as necessary. Our `UserStatistics` listener might start out like:

    namespace App\Event;
    
    use Cake\Event\EventListenerInterface;
    
    class UserStatistic implements EventListenerInterface
    {
        public function implementedEvents(): array
        {
            return [\
                // Custom event names let you design your application events\
                // as required.\
                'Order.afterPlace' => 'updateBuyStatistic',\
            ];
        }
    
        public function updateBuyStatistic($event)
        {
            // Code to update statistics
        }
    }
    
    // From your controller, attach the UserStatistic object to the Order's event manager
    $statistics = new UserStatistic();
    $this->Orders->getEventManager()->on($statistics);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  

As you can see in the above code, the `on()` function will accept instances of the `EventListener` interface. Internally, the event manager will use `implementedEvents()` to attach the correct callbacks.

Added in version 5.1.0

The `events` hook was added to the `BaseApplication` as well as the `BasePlugin` class

As of CakePHP 5.1 it is recommended to register event listeners by adding them via the `events` hook in your application or plugin class:

    namespace App;
    
    use App\Event\UserStatistic;
    use Cake\Event\EventManagerInterface;
    use Cake\Http\BaseApplication;
    
    class Application extends BaseApplication
    {
        // The rest of your Application class
    
        public function events(EventManagerInterface $eventManager): EventManagerInterface
        {
            $statistics = new UserStatistic();
            $eventManager->on($statistics);
    
            return $eventManager;
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

### Registering Anonymous Listeners [​](https://book.cakephp.org/6.x/core-libraries/events.html#registering-anonymous-listeners)

While event listener objects are generally a better way to implement listeners, you can also bind any `callable` as an event listener. For example if we wanted to put any orders into the log files, we could use a simple anonymous function to do so:

    use Cake\Log\Log;
    
    // From within a controller, or during application bootstrap.
    $this->Orders->getEventManager()->on('Order.afterPlace', function ($event) {
        Log::write(
            'info',
            'A new order was placed with id: ' . $event->getSubject()->id
        );
    });

1  
2  
3  
4  
5  
6  
7  
8  
9  

In addition to anonymous functions you can use any other callable type that PHP supports:

    $events = [\
        'email-sending' => 'EmailSender::sendBuyEmail',\
        'inventory' => [$this->InventoryManager, 'decrement'],\
    ];
    foreach ($events as $callable) {
        $eventManager->on('Order.afterPlace', $callable);
    }

1  
2  
3  
4  
5  
6  
7  

When working with plugins that don't trigger specific events, you can leverage event listeners on the default events. Lets take an example 'UserFeedback' plugin which handles feedback forms from users. From your application you would like to know when a Feedback record has been saved and ultimately act on it. You can listen to the global `Model.afterSave` event. However, you can take a more direct approach and only listen to the event you really need:

    // You can create the following before the
    // save operation, ie. config/bootstrap.php
    use Cake\Datasource\FactoryLocator;
    // If sending emails
    use Cake\Mailer\Email;
    
    FactoryLocator::get('Table')->get('ThirdPartyPlugin.Feedbacks')
        ->getEventManager()
        ->on('Model.afterSave', function($event, $entity)
        {
            // For example we can send an email to the admin
            $email = new Email('default');
            $email->setFrom(['[email protected]' => 'Your Site'])
                ->setTo('[email protected]')
                ->setSubject('New Feedback - Your Site')
                ->send('Body of message');
        });

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

You can use this same approach to bind listener objects.

### Interacting with Existing Listeners [​](https://book.cakephp.org/6.x/core-libraries/events.html#interacting-with-existing-listeners)

Assuming several event listeners have been registered the presence or absence of a particular event pattern can be used as the basis of some action.:

    // Attach listeners to EventManager.
    $this->getEventManager()->on('User.Registration', [$this, 'userRegistration']);
    $this->getEventManager()->on('User.Verification', [$this, 'userVerification']);
    $this->getEventManager()->on('User.Authorization', [$this, 'userAuthorization']);
    
    // Somewhere else in your application.
    $events = $this->getEventManager()->matchingListeners('Verification');
    if (!empty($events)) {
        // Perform logic related to presence of 'Verification' event listener.
        // For example removing the listener if present.
        $this->getEventManager()->off('User.Verification');
    } else {
        // Perform logic related to absence of 'Verification' event listener
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

NOTE

The pattern passed to the `matchingListeners` method is case sensitive.

### Establishing Priorities [​](https://book.cakephp.org/6.x/core-libraries/events.html#establishing-priorities)

In some cases you might want to control the order that listeners are invoked. For instance, if we go back to our user statistics example. It would be ideal if this listener was called at the end of the stack. By calling it at the end of the listener stack, we can ensure that the event was not cancelled, and that no other listeners raised exceptions. We can also get the final state of the objects in the case that other listeners have modified the subject or event object.

Priorities are defined as an integer when adding a listener. The higher the number, the later the method will be fired. The default priority for all listeners is `10`. If you need your method to be run earlier, using any value below this default will work. On the other hand if you desire to run the callback after the others, using a number above `10` will do.

If two callbacks happen to have the same priority value, they will be executed with a the order they were attached. You set priorities using the `on()` method for callbacks, and declaring it in the `implementedEvents()` function for event listeners:

    // Setting priority for a callback
    $callback = [$this, 'doSomething'];
    $this->getEventManager()->on(
        'Order.afterPlace',
        ['priority' => 2],
        $callback
    );
    
    // Setting priority for a listener
    class UserStatistic implements EventListenerInterface
    {
        public function implementedEvents(): array
        {
            return [\
                'Order.afterPlace' => [\
                    'callable' => 'updateBuyStatistic',\
                    'priority' => 100\
                ],\
            ];
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  

As you see, the main difference for `EventListener` objects is that you need to use an array for specifying the callable method and the priority preference. The `callable` key is a special array entry that the manager will read to know what function in the class it should be calling.

### Getting Event Data as Function Parameters [​](https://book.cakephp.org/6.x/core-libraries/events.html#getting-event-data-as-function-parameters)

When events have data provided in their constructor, the provided data is converted into arguments for the listeners. An example from the View layer is the afterRender callback:

    $this->getEventManager()
        ->dispatch(new Event('View.afterRender', $this, ['view' => $viewFileName]));

1  
2  

The listeners of the `View.afterRender` callback should have the following signature:

    function (EventInterface $event, $viewFileName)

1  

Each value provided to the Event constructor will be converted into function parameters in the order they appear in the data array. If you use an associative array, the result of `array_values` will determine the function argument order.

NOTE

Unlike in 2.x, converting event data to listener arguments is the default behavior and cannot be disabled.

Dispatching Events [​](https://book.cakephp.org/6.x/core-libraries/events.html#dispatching-events)

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

Once you have obtained an instance of an event manager you can dispatch events using `Cake\Event\EventManager::dispatch()`. This method takes an instance of the `Cake\Event\Event` class. Let's look at dispatching an event:

    // An event listener has to be instantiated before dispatching an event.
    // Create a new event and dispatch it.
    $event = new Event('Order.afterPlace', $this, [\
        'order' => $order\
    ]);
    $this->getEventManager()->dispatch($event);

1  
2  
3  
4  
5  
6  

`Cake\Event\Event` accepts 3 arguments in its constructor. The first one is the event name, you should try to keep this name as unique as possible, while making it readable. We suggest a convention as follows: `Layer.eventName` for general events happening at a layer level (for example, `Controller.startup`, `View.beforeRender`) and `Layer.Class.eventName` for events happening in specific classes on a layer, for example `Model.User.afterRegister` or `Controller.Courses.invalidAccess`.

The second argument is the `subject`, meaning the object associated to the event, usually when it is the same class triggering events about itself, using `$this` will be the most common case. Although a Component could trigger controller events too. The subject class is important because listeners will get immediate access to the object properties and have the chance to inspect or change them on the fly.

Finally, the third argument is any additional event data. This can be any data you consider useful to pass around so listeners can act upon it. While this can be an argument of any type, we recommend passing an associative array.

The `Cake\Event\EventManager::dispatch()` method accepts an event object as an argument and notifies all subscribed listeners.

### Stopping Events [​](https://book.cakephp.org/6.x/core-libraries/events.html#stopping-events)

Much like DOM events, you may want to stop an event to prevent additional listeners from being notified. You can see this in action during model callbacks (for example, beforeSave) in which it is possible to stop the saving operation if the code detects it cannot proceed any further.

In order to stop events you can either return `false` in your callbacks or call the `stopPropagation()` method on the event object:

    public function doSomething($event)
    {
        // ...
        return false; // Stops the event
    }
    
    public function updateBuyStatistic($event)
    {
        // ...
        $event->stopPropagation();
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

Stopping an event will prevent any additional callbacks from being called. Additionally the code triggering the event may behave differently based on the event being stopped or not. Generally it does not make sense to stop 'after' events, but stopping 'before' events is often used to prevent the entire operation from occurring.

To check if an event was stopped, you call the `isStopped()` method in the event object:

    public function place($order)
    {
        $event = new Event('Order.beforePlace', $this, ['order' => $order]);
        $this->getEventManager()->dispatch($event);
        if ($event->isStopped()) {
            return false;
        }
        if ($this->Orders->save($order)) {
            // ...
        }
        // ...
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

In the previous example the order would not get saved if the event is stopped during the `beforePlace` process.

### Getting Event Results [​](https://book.cakephp.org/6.x/core-libraries/events.html#getting-event-results)

Every time a callback returns a non-null non-false value, it gets stored in the `$result` property of the event object. This is useful when you want to allow callbacks to modify the event execution. Let's take again our `beforePlace` example and let callbacks modify the `$order` data.

Event results can be altered either using the event object result property directly or returning the value in the callback itself:

    // A listener callback
    public function doSomething($event)
    {
        // ...
        $alteredData = $event->getData('order') + $moreData;
    
        return $alteredData;
    }
    
    // Another listener callback
    public function doSomethingElse($event)
    {
        // ...
        $event->setResult(['order' => $alteredData] + $this->result());
    }
    
    // Using the event result
    public function place($order)
    {
        $event = new Event('Order.beforePlace', $this, ['order' => $order]);
        $this->getEventManager()->dispatch($event);
        if (!empty($event->getResult()['order'])) {
            $order = $event->getResult()['order'];
        }
        if ($this->Orders->save($order)) {
            // ...
        }
        // ...
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  

It is possible to alter any event object property and have the new data passed to the next callback. In most of the cases, providing objects as event data or result and directly altering the object is the best solution as the reference is kept the same and modifications are shared across all callback calls.

### Removing Callbacks and Listeners [​](https://book.cakephp.org/6.x/core-libraries/events.html#removing-callbacks-and-listeners)

If for any reason you want to remove any callback from the event manager just call the `Cake\Event\EventManager::off()` method using as arguments the first two parameters you used for attaching it:

    // Attaching a function
    $this->getEventManager()->on('My.event', [$this, 'doSomething']);
    
    // Detaching the function
    $this->getEventManager()->off('My.event', [$this, 'doSomething']);
    
    // Attaching an anonymous function.
    $myFunction = function ($event) { ... };
    $this->getEventManager()->on('My.event', $myFunction);
    
    // Detaching the anonymous function
    $this->getEventManager()->off('My.event', $myFunction);
    
    // Adding a EventListener
    $listener = new MyEventLister();
    $this->getEventManager()->on($listener);
    
    // Detaching a single event key from a listener
    $this->getEventManager()->off('My.event', $listener);
    
    // Detaching all callbacks implemented by a listener
    $this->getEventManager()->off($listener);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  

Events are a great way of separating concerns in your application and make classes both cohesive and decoupled from each other. Events can be utilized to de-couple application code and make extensible plugins.

Keep in mind that with great power comes great responsibility. Using too many events can make debugging harder and require additional integration testing.

Additional Reading [​](https://book.cakephp.org/6.x/core-libraries/events.html#additional-reading)

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

*   [Behaviors](https://book.cakephp.org/6.x/orm/behaviors.html)
    
*   [Command Objects](https://book.cakephp.org/6.x/console-commands/commands.html)
    
*   [Components](https://book.cakephp.org/6.x/controllers/components.html)
    
*   [Helpers](https://book.cakephp.org/6.x/views/helpers.html)
    
*   [Testing Events](https://book.cakephp.org/6.x/development/testing.html#testing-events)

---

# Mailer | CakePHP

[Skip to content](https://book.cakephp.org/6.x/core-libraries/email.html#VPContent)

Return to top

Mailer [​](https://book.cakephp.org/6.x/core-libraries/email.html#mailer)

==========================================================================

`class` Cake\\Mailer\\**Mailer**(string|array|null $profile = null)

`Mailer` is a convenience class for sending email. With this class you can send email from any place inside of your application.

Basic Usage [​](https://book.cakephp.org/6.x/core-libraries/email.html#basic-usage)

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

First of all, you should ensure the class is loaded:

    use Cake\Mailer\Mailer;

1  

After you've loaded `Mailer`, you can send an email with the following:

    $mailer = new Mailer('default');
    $mailer->setFrom(['[email protected]' => 'My Site'])
        ->setTo('[email protected]')
        ->setSubject('About')
        ->deliver('My message');

1  
2  
3  
4  
5  

Since `Mailer`'s setter methods return the instance of the class, you are able to set its properties with method chaining.

`Mailer` has several methods for defining recipients - `setTo()`, `setCc()`, `setBcc()`, `addTo()`, `addCc()` and `addBcc()`. The main difference being that the first three will overwrite what was already set and the latter will just add more recipients to their respective field:

    $mailer = new Mailer();
    $mailer->setTo('[email protected]', 'To Example');
    $mailer->addTo('[email protected]', 'To2 Example');
    // The email's To recipients are: [email protected] and [email protected]
    $mailer->setTo('[email protected]', 'ToTest Example');
    // The email's To recipient is: [email protected]

1  
2  
3  
4  
5  
6  

### Choosing the Sender [​](https://book.cakephp.org/6.x/core-libraries/email.html#choosing-the-sender)

When sending email on behalf of other people, it's often a good idea to define the original sender using the Sender header. You can do so using `setSender()`:

    $mailer = new Mailer();
    $mailer->setSender('[email protected]', 'MyApp emailer');

1  
2  

NOTE

It's also a good idea to set the envelope sender when sending mail on another person's behalf. This prevents them from getting any messages about deliverability.

Configuration [​](https://book.cakephp.org/6.x/core-libraries/email.html#configuration)

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

Mailer profiles and email transport settings are defined in your application's configuration files. The `Email` and `EmailTransport` keys define mailer profiles and email transport configurations respectively. During application bootstrap configuration settings are passed from `Configure` into the `Mailer` and `TransportFactory` classes using `setConfig()`. By defining profiles and transports, you can keep your application code free of configuration data, and avoid duplication that makes maintenance and deployment more difficult.

To load a predefined configuration, you can use the `setProfile()` method or pass it to the constructor of `Mailer`:

    $mailer = new Mailer();
    $mailer->setProfile('default');
    
    // Or in constructor
    $mailer = new Mailer('default');

1  
2  
3  
4  
5  

Instead of passing a string which matches a preset configuration name, you can also just load an array of options:

    $mailer = new Mailer();
    $mailer->setProfile(['from' => '[email protected]', 'transport' => 'my_custom']);
    
    // Or in constructor
    $mailer = new Mailer(['from' => '[email protected]', 'transport' => 'my_custom']);

1  
2  
3  
4  
5  

### Configuration Profiles [​](https://book.cakephp.org/6.x/core-libraries/email.html#configuration-profiles)

Defining delivery profiles allows you to consolidate common email settings into re-usable profiles. Your application can have as many profiles as necessary. The following configuration keys are used:

*   `'from'`: Mailer or array of sender. See `Mailer::setFrom()`.
*   `'sender'`: Mailer or array of real sender. See `Mailer::setSender()`.
*   `'to'`: Mailer or array of destination. See `Mailer::setTo()`.
*   `'cc'`: Mailer or array of carbon copy. See `Mailer::setCc()`.
*   `'bcc'`: Mailer or array of blind carbon copy. See `Mailer::setBcc()`.
*   `'replyTo'`: Mailer or array to reply the e-mail. See `Mailer::setReplyTo()`.
*   `'readReceipt'`: Mailer address or an array of addresses to receive the receipt of read. See `Mailer::setReadReceipt()`.
*   `'returnPath'`: Mailer address or an array of addresses to return if have some error. See `Mailer::setReturnPath()`.
*   `'messageId'`: Message ID of e-mail. See `Mailer::setMessageId()`.
*   `'subject'`: Subject of the message. See `Mailer::setSubject()`.
*   `'message'`: Content of message. Do not set this field if you are using rendered content.
*   `'priority'`: Priority of the email as numeric value (usually from 1 to 5 with 1 being the highest).
*   `'headers'`: Headers to be included. See `Mailer::setHeaders()`.
*   `'viewRenderer'`: If you are using rendered content, set the view classname. See `ViewBuilder::setClassName()`.
*   `'template'`: If you are using rendered content, set the template name. See `ViewBuilder::setTemplate()`.
*   `'theme'`: Theme used when rendering template. See `ViewBuilder::setTheme()`.
*   `'layout'`: If you are using rendered content, set the layout to render. See `ViewBuilder::setTemplate()`.
*   `'autoLayout'`: If you want to render a template without layout, set this field to `false`. See `ViewBuilder::disableAutoLayout()`.
*   `'viewVars'`: If you are using rendered content, set the array with variables to be used in the view. See `Mailer::setViewVars()`.
*   `'attachments'`: List of files to attach. See `Mailer::setAttachments()`.
*   `'emailFormat'`: Format of email (html, text or both). See `Mailer::setEmailFormat()`.
*   `'transport'`: Transport configuration name. See [Email Transport](https://book.cakephp.org/6.x/core-libraries/email.html#email-transport)
    .
*   `'log'`: Log level to log the email headers and message. `true` will use LOG\_DEBUG. See [Logging Levels](https://book.cakephp.org/6.x/core-libraries/logging.html#logging-levels)
    . Note that logs will be emitted under the scope named `email`. See also [Logging Scopes](https://book.cakephp.org/6.x/core-libraries/logging.html#logging-scopes)
    .
*   `'helpers'`: Array of helpers used in the email template. `ViewBuilder::setHelpers()`/`ViewBuilder::addHelpers()`.

NOTE

The values of above keys using Mailer or array, like from, to, cc, etc will be passed as first parameter of corresponding methods. The equivalent for: `$mailer->setFrom('[[email protected]](https://book.cakephp.org/cdn-cgi/l/email-protection) ', 'My Site')` would be defined as `'from' => ['[[email protected]](https://book.cakephp.org/cdn-cgi/l/email-protection) ' => 'My Site']` in your config

Setting Headers [​](https://book.cakephp.org/6.x/core-libraries/email.html#setting-headers)

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

In `Mailer` you are free to set whatever headers you want. Do not forget to put the `X-` prefix for your custom headers.

See `Mailer::setHeaders()` and `Mailer::addHeaders()`

Sending Templated Emails [​](https://book.cakephp.org/6.x/core-libraries/email.html#sending-templated-emails)

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

Emails are often much more than just a simple text message. In order to facilitate that, CakePHP provides a way to send emails using CakePHP's [view layer](https://book.cakephp.org/6.x/views.html)
.

The templates for emails reside in a special folder `templates/email/` of your application. Mailer views can also use layouts and elements just like normal views:

    $mailer = new Mailer();
    $mailer
                ->setEmailFormat('html')
                ->setTo('[email protected]')
                ->setFrom('[email protected]')
                ->viewBuilder()
                    ->setTemplate('welcome')
                    ->setLayout('fancy');
    
    $mailer->deliver();

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

The above would use **templates/email/html/welcome.php** for the view and **templates/layout/email/html/fancy.php** for the layout. You can send multipart templated email messages as well:

    $mailer = new Mailer();
    $mailer
                ->setEmailFormat('both')
                ->setTo('[email protected]')
                ->setFrom('[email protected]')
                ->viewBuilder()
                    ->setTemplate('welcome')
                    ->setLayout('fancy');
    
    $mailer->deliver();

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

This would use the following template files:

*   **templates/email/text/welcome.php**
*   **templates/layout/email/text/fancy.php**
*   **templates/email/html/welcome.php**
*   **templates/layout/email/html/fancy.php**

When sending templated emails you have the option of sending either `text`, `html` or `both`.

You can set all view related config using the view builder instance got by `Mailer::viewBuilder()` similar to how you do the same in controller.

You can set view variables with `Mailer::setViewVars()`:

    $mailer = new Mailer('templated');
    $mailer->setViewVars(['value' => 12345]);

1  
2  

Or you can use the view builder methods `ViewBuilder::setVar()` and `ViewBuilder::setVars()`.

In your email templates you can use these with:

    <p>Here is your value: <b><?= $value ?></b></p>

1  

You can use helpers in emails as well, much like you can in normal template files. By default only the `HtmlHelper` is loaded. You can load additional helpers using the `ViewBuilder::addHelpers()` method:

    $mailer->viewBuilder()->addHelpers(['Html', 'Custom', 'Text']);

1  

When adding helpers be sure to include 'Html' or it will be removed from the helpers loaded in your email template.

NOTE

In versions prior to 4.3.0, you will need to use `setHelpers()` instead.

If you want to send email using templates in a plugin you can use the familiar `plugin syntax` to do so:

    $mailer = new Mailer();
    $mailer->viewBuilder()->setTemplate('Blog.new_comment');

1  
2  

The above would use template and layout from the Blog plugin as an example.

In some cases, you might need to override the default template provided by plugins. You can do this using themes:

    $mailer->viewBuilder()
        ->setTemplate('Blog.new_comment')
        ->setLayout('Blog.auto_message')
        ->setTheme('TestTheme');

1  
2  
3  
4  

This allows you to override the `new_comment` template in your theme without modifying the Blog plugin. The template file needs to be created in the following path: **templates/plugin/TestTheme/plugin/Blog/email/text/new\_comment.php**.

Sending Attachments [​](https://book.cakephp.org/6.x/core-libraries/email.html#sending-attachments)

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

### Mailer::setAttachments() [​](https://book.cakephp.org/6.x/core-libraries/email.html#mailer-setattachments)

`method` Cake\\Mailer\\Mailer::**setAttachments**($attachments)

You can attach files to email messages as well. There are a few different formats depending on what kind of files you have, and how you want the filenames to appear in the recipient's mail client:

1.  Array: `$mailer->setAttachments(['/full/file/path/file.png'])` will attach this file with the name file.png..
    
2.  Array with key: `$mailer->setAttachments(['photo.png' => '/full/some_hash.png'])` will attach some\_hash.png with the name photo.png. The recipient will see photo.png, not some\_hash.png.
    
3.  Nested arrays:
    
        $mailer->setAttachments([\
            'photo.png' => [\
                'file' => '/full/some_hash.png',\
                'mimetype' => 'image/png',\
                'contentId' => 'my-unique-id',\
            ],\
        ]);
    
    1  
    2  
    3  
    4  
    5  
    6  
    7  
    
    The above will attach the file with different mimetype and with custom Content ID (when set the content ID the attachment is transformed to inline). The mimetype and contentId are optional in this form.
    
    3.1. When you are using the `contentId`, you can use the file in the HTML body like `<img src="cid:my-content-id">`.
    
    3.2. You can use the `contentDisposition` option to disable the `Content-Disposition` header for an attachment. This is useful when sending ical invites to clients using outlook.
    
    3.3 Instead of the `file` option you can provide the file contents as a string using the `data` option. This allows you to attach files without needing file paths to them.
    

### Mailer::addAttachment() [​](https://book.cakephp.org/6.x/core-libraries/email.html#mailer-addattachment)

`method` Cake\\Mailer\\Mailer::**addAttachment**(\\Psr\\Http\\Message\\UploadedFileInterface|string $path, ?string $name, ?string $mimetype, ?string $contentId, ?bool $contentDisposition)

You can also add attachments using the `addAttachment()` method.

> $mailer->addAttachment('/full/file/path/file.png');

### Relaxing Address Validation Rules [​](https://book.cakephp.org/6.x/core-libraries/email.html#relaxing-address-validation-rules)

### Mailer::setEmailPattern() [​](https://book.cakephp.org/6.x/core-libraries/email.html#mailer-setemailpattern)

`method` Cake\\Mailer\\Mailer::**setEmailPattern**($pattern)

If you are having validation issues when sending to non-compliant addresses, you can relax the pattern used to validate email addresses. This is sometimes necessary when dealing with some ISPs:

    $mailer = new Mailer('default');
    
    // Relax the email pattern, so you can send
    // to non-conformant addresses.
    $mailer->setEmailPattern($newPattern);

1  
2  
3  
4  
5  

Sending Emails from CLI [​](https://book.cakephp.org/6.x/core-libraries/email.html#sending-emails-from-cli)

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

When sending emails within a CLI script (Shells, Tasks, ...) you should manually set the domain name for Mailer to use. It will serve as the host name for the message id (since there is no host name in a CLI environment):

    $mailer->setDomain('www.example.org');
    // Results in message ids like ``<[email protected]>`` (valid)
    // Instead of `<UUID@>`` (invalid)

1  
2  
3  

A valid message id can help to prevent emails ending up in spam folders.

Creating Reusable Emails [​](https://book.cakephp.org/6.x/core-libraries/email.html#creating-reusable-emails)

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

Until now we have seen how to directly use the the `Mailer` class to create and send one emails. But main feature of mailer is to allow creating reusable emails throughout your application. They can also be used to contain multiple email configurations in one location. This helps keep your code DRYer and keeps email configuration noise out of other areas in your application.

In this example we will be creating a `Mailer` that contains user-related emails. To create our `UserMailer`, create the file **src/Mailer/UserMailer.php**. The contents of the file should look like the following:

    namespace App\Mailer;
    
    use Cake\Mailer\Mailer;
    
    class UserMailer extends Mailer
    {
        public function welcome($user)
        {
            $this
                ->setTo($user->email)
                ->setSubject(sprintf('Welcome %s', $user->name))
                ->viewBuilder()
                    ->setTemplate('welcome_mail'); // By default template with same name as method name is used.
        }
    
        public function resetPassword($user)
        {
            $this
                ->setTo($user->email)
                ->setSubject('Reset password')
                ->setViewVars(['token' => $user->token]);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  

In our example we have created two methods, one for sending a welcome email, and another for sending a password reset email. Each of these methods expect a user `Entity` and utilizes its properties for configuring each email.

We are now able to use our `UserMailer` to send out our user-related emails from anywhere in our application. For example, if we wanted to send our welcome email we could do the following:

    namespace App\Controller;
    
    use Cake\Mailer\MailerAwareTrait;
    
    class UsersController extends AppController
    {
        use MailerAwareTrait;
    
        public function register()
        {
            $user = $this->Users->newEmptyEntity();
            if ($this->request->is('post')) {
                $user = $this->Users->patchEntity($user, $this->request->getData())
                if ($this->Users->save($user)) {
                    $this->getMailer('User')->send('welcome', [$user]);
                }
            }
            $this->set('user', $user);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  

If we wanted to completely separate sending a user their welcome email from our application's code, we can have our `UserMailer` subscribe to the `Model.afterSave` event. By subscribing to an event, we can keep our application's user-related classes completely free of email-related logic and instructions. For example, we could add the following to our `UserMailer`:

    public function implementedEvents(): array
    {
        return [\
            'Model.afterSave' => 'onRegistration',\
        ];
    }
    
    public function onRegistration(EventInterface $event, EntityInterface $entity, ArrayObject $options): void
    {
        if ($entity->isNew()) {
            $this->send('welcome', [$entity]);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

You can now register the mailer as an event listener and the `onRegistration()` method will be invoked every time the `Model.afterSave` event is fired:

    // attach to Users event manager
    $this->Users->getEventManager()->on($this->getMailer('User'));

1  
2  

NOTE

For information on how to register event listener objects, please refer to the [Registering Event Listeners](https://book.cakephp.org/6.x/core-libraries/events.html#registering-event-listeners)
 documentation.

Configuring Transports [​](https://book.cakephp.org/6.x/core-libraries/email.html#configuring-transports)

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

Email messages are delivered by transports. Different transports allow you to send messages via PHP's `mail()` function, SMTP servers, or not at all which is useful for debugging. Configuring transports allows you to keep configuration data out of your application code and makes deployment simpler as you can simply change the configuration data. An example transport configuration looks like:

    // In config/app.php
    'EmailTransport' => [\
        // Sample Mail configuration\
        'default' => [\
            'className' => 'Mail',\
        ],\
        // Sample SMTP configuration\
        'gmail' => [\
            'host' => 'smtp.gmail.com',\
            'port' => 587,\
            'username' => '[email protected]',\
            'password' => 'secret',\
            'className' => 'Smtp',\
            'tls' => true,\
        ],\
    ],

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  

Transports can also be configured at runtime using `TransportFactory::setConfig()`:

    use Cake\Mailer\TransportFactory;
    
    // Define an SMTP transport
    TransportFactory::setConfig('gmail', [\
        'host' => 'ssl://smtp.gmail.com',\
        'port' => 465,\
        'username' => '[email protected]',\
        'password' => 'secret',\
        'className' => 'Smtp'\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

You can configure SSL SMTP servers, like Gmail. To do so, put the `ssl://` prefix in the host and configure the port value accordingly. You can also enable TLS SMTP using the `tls` option:

    use Cake\Mailer\TransportFactory;
    
    TransportFactory::setConfig('gmail', [\
        'host' => 'smtp.gmail.com',\
        'port' => 587,\
        'username' => '[email protected]',\
        'password' => 'secret',\
        'className' => 'Smtp',\
        'tls' => true\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

The above configuration would enable TLS communication for email messages.

To configure your mailer to use a specific transport you can use `Cake\Mailer\Mailer::setTransport()` method or have the transport in your configuration:

    // Use a named transport already configured using TransportFactory::setConfig()
    $mailer->setTransport('gmail');
    
    // Use a constructed object.
    $mailer->setTransport(new \Cake\Mailer\Transport\DebugTransport());

1  
2  
3  
4  
5  

WARNING

You will need to have access for less secure apps enabled in your Google account for this to work: [Allowing less secure apps to access your account](https://support.google.com/accounts/answer/6010255)
.

NOTE

[Gmail SMTP settings](https://support.google.com/a/answer/176600?hl=en)
.

NOTE

To use SSL + SMTP, you will need to have the SSL configured in your PHP install.

Configuration options can also be provided as a `DSN` string. This is useful when working with environment variables or `PaaS` providers:

    TransportFactory::setConfig('default', [\
        'url' => 'smtp://[email protected]:[email protected]:587?tls=true',\
    ]);

1  
2  
3  

When using a DSN string you can define any additional parameters/options as query string arguments.

### Mailer::drop() [​](https://book.cakephp.org/6.x/core-libraries/email.html#mailer-drop)

`static` Cake\\Mailer\\Mailer::**drop**($key)

Once configured, transports cannot be modified. In order to modify a transport you must first drop it and then reconfigure it.

### Creating Custom Transports [​](https://book.cakephp.org/6.x/core-libraries/email.html#creating-custom-transports)

You are able to create your custom transports for situations such as send email using services like SendGrid, MailGun or Postmark. To create your transport, first create the file **src/Mailer/Transport/ExampleTransport.php** (where Example is the name of your transport). To start, your file should look like:

    namespace App\Mailer\Transport;
    
    use Cake\Mailer\AbstractTransport;
    use Cake\Mailer\Message;
    
    class ExampleTransport extends AbstractTransport
    {
        public function send(Message $message): array
        {
            // Do something.
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

You must implement the method `send(Message $message)` with your custom logic.

Sending emails without using Mailer [​](https://book.cakephp.org/6.x/core-libraries/email.html#sending-emails-without-using-mailer)

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

The `Mailer` is a higher level abstraction class which acts as a bridge between the `Cake\Mailer\Message`, `Cake\Mailer\Renderer` and `Cake\Mailer\AbstractTransport` classes to configure emails with a fluent interface.

If you want you can use these classes directly with the `Mailer` too.

For example:

    $render = new \Cake\Mailer\Renderer();
    $render->viewBuilder()
        ->setTemplate('custom')
        ->setLayout('sparkly');
    
    $message = new \Cake\Mailer\Message();
    $message
        ->setFrom('[email protected]')
        ->setTo('[email protected]')
        ->setBody($render->render());
    
    $transport = new \Cake\Mailer\Transport\MailTransport();
    $result = $transport->send($message);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

You can even skip using the `Renderer` and set the message body directly using `Message::setBodyText()` and `Message::setBodyHtml()` methods.

Testing Mailers [​](https://book.cakephp.org/6.x/core-libraries/email.html#testing-mailers)

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

To test mailers, add `Cake\TestSuite\EmailTrait` to your test case. The `EmailTrait` uses PHPUnit hooks to replace your application's email transports with a proxy that intercepts email messages and allows you to do assertions on the mail that would be delivered.

Add the trait to your test case to start testing emails, and load routes if your emails need to generate URLs:

    namespace App\Test\TestCase\Mailer;
    
    use App\Mailer\WelcomeMailer;
    use App\Model\Entity\User;
    
    use Cake\TestSuite\EmailTrait;
    use Cake\TestSuite\TestCase;
    
    class WelcomeMailerTestCase extends TestCase
    {
        use EmailTrait;
    
        public function setUp(): void
        {
            parent::setUp();
            $this->loadRoutes();
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

Let's assume we have a mailer that delivers welcome emails when a new user registers. We want to check that the subject and body contain the user's name:

    // in our WelcomeMailerTestCase class.
    public function testName()
    {
        $user = new User([\
            'name' => 'Alice Alittea',\
            'email' => '[email protected]',\
        ]);
        $mailer = new WelcomeMailer();
        $mailer->send('welcome', [$user]);
    
        $this->assertMailSentTo($user->email);
        $this->assertMailContainsText('Hi ' . $user->name);
        $this->assertMailContainsText('Welcome to CakePHP!');
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

### Assertion methods [​](https://book.cakephp.org/6.x/core-libraries/email.html#assertion-methods)

The `Cake\TestSuite\EmailTrait` trait provides the following assertions:

    // Asserts an expected number of emails were sent
    $this->assertMailCount($count);
    
    // Asserts that no emails were sent
    $this->assertNoMailSent();
    
    // Asserts an email was sent to an address
    $this->assertMailSentTo($address);
    
    // Asserts an email was sent from an address
    $this->assertMailSentFrom($emailAddress);
    $this->assertMailSentFrom([$emailAddress => $displayName]);
    
    // Asserts an email contains expected contents
    $this->assertMailContains($contents);
    
    // Asserts an email contains expected html contents
    $this->assertMailContainsHtml($contents);
    
    // Asserts an email contains expected text contents
    $this->assertMailContainsText($contents);
    
    // Asserts an email contains the expected value within an Message getter (for example, "subject")
    $this->assertMailSentWith($expected, $parameter);
    
    // Asserts an email at a specific index was sent to an address
    $this->assertMailSentToAt($at, $address);
    
    // Asserts an email at a specific index was sent from an address
    $this->assertMailSentFromAt($at, $address);
    
    // Asserts an email at a specific index contains expected contents
    $this->assertMailContainsAt($at, $contents);
    
    // Asserts an email at a specific index contains expected html contents
    $this->assertMailContainsHtmlAt($at, $contents);
    
    // Asserts an email at a specific index contains expected text contents
    $this->assertMailContainsTextAt($at, $contents);
    
    // Asserts an email contains an attachment
    $this->assertMailContainsAttachment('test.png');
    
    // Asserts an email at a specific index contains the expected value within an Message getter (for example, "cc")
    $this->assertMailSentWithAt($at, $expected, $parameter);
    
    // Asserts an email contains a substring in the subject.
    $this->assertMailSubjectContains('Free Offer');
    
    // Asserts an email at the specific index contains a substring in the subject.
    $this->assertMailSubjectContainsAt(1, 'Free Offer');

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40  
41  
42  
43  
44  
45  
46  
47  
48  
49  
50  
51

---

# Security | CakePHP

[Skip to content](https://book.cakephp.org/2.x/core-utility-libraries/security.html#VPContent)

Return to top

Security [​](https://book.cakephp.org/2.x/core-utility-libraries/security.html#security)

=========================================================================================

`class` **Security**

The [security library](https://api.cakephp.org/2.x/class-Security.html)
 handles basic security measures such as providing methods for hashing and encrypting data.

NOTE

By default the encryption features offered by Security rely on the deprecated `mcrypt` extension. This behaviour can be changed by setting `Security.useOpenSsl`. If you are using the default behaviour using PHP>=7.1 you will need to install `mcrypt` via PECL.

Security API [​](https://book.cakephp.org/2.x/core-utility-libraries/security.html#security-api)

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

`static` Security::**cipher**( $text, $key )

rtype  
string

Encrypts/Decrypts text using the given key:

    // Encrypt your text with my_key
    $secret = Security::cipher('hello world', 'my_key');
    
    // Later decrypt your text
    $nosecret = Security::cipher($secret, 'my_key');

1  
2  
3  
4  
5  

WARNING

`cipher()` uses a **weak** XOR cipher and should **not** be used. It is only included for backwards compatibility.

`static` Security::**rijndael**($text, $key, $mode)

param string $text  
The text to encrypt

param string $key  
The key to use for encryption. This must be longer than 32 bytes.

param string $mode  
The mode to use, either 'encrypt' or 'decrypt'

Encrypts/Decrypts text using the rijndael-256 cipher. This requires the [mcrypt extension](https://www.php.net/mcrypt)
 to be installed:

    // Encrypt some data.
    $encrypted = Security::rijndael('a secret', Configure::read('Security.key'), 'encrypt');
    
    // Later decrypt it.
    $decrypted = Security::rijndael($encrypted, Configure::read('Security.key'), 'decrypt');

1  
2  
3  
4  
5  

`rijndael()` can be used to store data you need to decrypt later, like the contents of cookies. It should **never** be used to store passwords. Instead you should use the one way hashing methods provided by `~Security::hash()`

Added in version 2.2

`Security::rijndael()` was added in 2.2.

`static` Security::**encrypt**($text, $key, $hmacSalt = null)

param string $plain  
The value to encrypt.

param string $key  
The 256 bit/32 byte key to use as a cipher key.

param string $hmacSalt  
The salt to use for the HMAC process. Leave null to use Security.salt.

Encrypt `$text` using AES-256. The `$key` should be a value with a lots of variance in the data, much like a good password. The returned result will be the encrypted value with an HMAC checksum.

This method should **never** be used to store passwords. Instead you should use the one way hashing methods provided by `~Security::hash()`. An example use would be:

    // Assuming key is stored somewhere it can be re-used for
    // decryption later.
    $key = 'wt1U5MACWJFTXGenFoZoiLwQGrLgdbHA';
    $result = Security::encrypt($value, $key);

1  
2  
3  
4  

Encrypted values can be decrypted using `Security::decrypt()`.

Added in version 2.5

Added in version 2.10.8

Set `Security.useOpenSsl` to use OpenSSL instead of the deprecated `mcrypt` extension.

`static` Security::**decrypt**($cipher, $key, $hmacSalt = null)

param string $cipher  
The ciphertext to decrypt.

param string $key  
The 256 bit/32 byte key to use as a cipher key.

param string $hmacSalt  
The salt to use for the HMAC process. Leave null to use Security.salt.

Decrypt a previously encrypted value. The `$key` and `$hmacSalt` parameters must match the values used to encrypt or decryption will fail. An example use would be:

    // Assuming key is stored somewhere it can be re-used for
    // decryption later.
    $key = 'wt1U5MACWJFTXGenFoZoiLwQGrLgdbHA';
    
    $cipher = $user['User']['secrets'];
    $result = Security::decrypt($cipher, $key);

1  
2  
3  
4  
5  
6  

If the value cannot be decrypted due to changes in the key or HMAC salt `false` will be returned.

Added in version 2.5

Added in version 2.10.8

Set `Security.useOpenSsl` to use OpenSSL instead of the deprecated `mcrypt` extension.

`static` Security::**hash**( $string, $type = NULL, $salt = false )

rtype  
string

Create a hash from a string using given method or fallback to next available method. If `$salt` is set to true, the applications salt value will be used:

    // Using the application's salt value
    $sha1 = Security::hash('CakePHP Framework', 'sha1', true);
    
    // Using a custom salt value
    $md5 = Security::hash('CakePHP Framework', 'md5', 'my-salt');
    
    // Using the default hash algorithm
    $hash = Security::hash('CakePHP Framework');

1  
2  
3  
4  
5  
6  
7  
8  

`hash()` also supports other secure hashing algorithms like bcrypt. When using bcrypt, you should be mindful of the slightly different usage. Creating an initial hash works the same as other algorithms:

    // Create a hash using bcrypt
    Security::setHash('blowfish');
    $hash = Security::hash('CakePHP Framework');

1  
2  
3  

Unlike other hash types comparing plain text values to hashed values should be done as follows:

    // $storedPassword, is a previously generated bcrypt hash.
    $newHash = Security::hash($newPassword, 'blowfish', $storedPassword);

1  
2  

When comparing values hashed with bcrypt, the original hash should be provided as the `$salt` parameter. This allows bcrypt to reuse the same cost and salt values, allowing the generated hash to return the same resulting hash, given the same input value.

Changed in version 2.3

Support for bcrypt was added in 2.3

`static` Security::**setHash**( $hash )

rtype  
void

Sets the default hash method for the Security object. This affects all objects using Security::hash().

---

# ACL Shell | CakePHP

[Skip to content](https://book.cakephp.org/2.x/console-and-shells/acl-shell.html#VPContent)

Return to top

ACL Shell [​](https://book.cakephp.org/2.x/console-and-shells/acl-shell.html#acl-shell)

========================================================================================

The AclShell is useful for managing and inspecting your Acl databases records. It's often more convenient than adding one time modifications to your controllers.

Most acl shell subcommands involve referencing aco/aro nodes. As there are two 'forms' of these nodes, there is two notations in the shell:

    # A Model + foreign_key reference
    ./Console/cake acl view aro Model.1
    
    # An alias path reference
    ./Console/cake acl view aco root/controllers

1  
2  
3  
4  
5  

Using a `.` indicates that you are going to use a bound record style reference while using a `/` indicates an alias path.

Installing the database tables [​](https://book.cakephp.org/2.x/console-and-shells/acl-shell.html#installing-the-database-tables)

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

Before using the database ACL you'll need to setup the tables. You can do that using:

    ./Console/cake acl initdb
    

Create and delete nodes [​](https://book.cakephp.org/2.x/console-and-shells/acl-shell.html#create-and-delete-nodes)

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

You can use the create and delete subcommands to create and delete nodes:

    ./Console/cake acl create aco controllers Posts
    ./Console/cake acl create aco Posts index
    

Would create an aco record using an alias path. You could do the following as well:

    ./Console/cake acl create aro Group.1
    

To create an aro node for the Group id = 1.

Grant and deny access [​](https://book.cakephp.org/2.x/console-and-shells/acl-shell.html#grant-and-deny-access)

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

Use the grant command to grant ACL permissions. Once executed, the ARO specified (and its children, if any) will have ALLOW access to the specified ACO action (and the ACO's children, if any):

    ./Console/cake acl grant Group.1 controllers/Posts
    

The above would grant all privileges. You could grant only the read privilege using the following:

    ./Console/cake acl grant Group.1 controllers/Posts read
    

Denying permission works in the exact same way. The only difference is you switch 'deny' in for 'grant'.

Check permissions [​](https://book.cakephp.org/2.x/console-and-shells/acl-shell.html#check-permissions)

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

Use this command to check ACL permissions. :

    ./Console/cake acl check Group.1 controllers/Posts read
    

The output will either be `allowed` or `not allowed`.

View the node trees [​](https://book.cakephp.org/2.x/console-and-shells/acl-shell.html#view-the-node-trees)

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

The view command will return the ARO or ACO tree. The optional node parameter allows you to return only a portion of the requested tree:

    ./Console/cake acl view

---

# Upgrade shell | CakePHP

[Skip to content](https://book.cakephp.org/2.x/console-and-shells/upgrade-shell.html#VPContent)

Return to top

Upgrade shell [​](https://book.cakephp.org/2.x/console-and-shells/upgrade-shell.html#upgrade-shell)

====================================================================================================

The upgrade shell will do most of the work to upgrade your CakePHP application from 1.3 to 2.0.

To run all upgrade steps:

    ./Console/cake upgrade all
    

If you would like to see what the shell will do without modifying files perform a dry run first with --dry-run:

    ./Console/cake upgrade all --dry-run
    

To upgrade your plugin run the command:

    ./Console/cake upgrade all --plugin YourPluginName
    

You are able to run each upgrade step individually. To see all the steps available run the command:

    ./Console/cake upgrade --help
    

Or visit the [API docs](https://api.cakephp.org/2.x/class-UpgradeShell.html)
 for more info.

Upgrade Your App [​](https://book.cakephp.org/2.x/console-and-shells/upgrade-shell.html#upgrade-your-app)

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

Here is a guide to help you upgrade your CakePHP 1.3 app to 2.x using the upgrade shell. Your 1.3 app structure will likely look like this:

    mywebsite/
        app/             <- Your App
        cake/            <- 1.3 Version of CakePHP
        plugins/
        vendors/
        .htaccess
        index.php
    

The first step is to download or `git clone` the new version of CakePHP into another folder outside of your `mywebsite` folder, we'll call it `cakephp`. We don't want the downloaded `app` folder to overwrite your app folder. Now is a good time to make a backup of your app folder, eg.: `cp -R app app-backup`.

Copy the `cakephp/lib` folder to your `mywebsite/lib` to setup the new CakePHP version in your app, eg.: `cp -R ../cakephp/lib .`. Symlinking is a good alternative to copy as well, eg.: `ln -s /var/www/cakephp/lib`.

Before we can run the upgrade shell we need the new console scripts as well. Copy the `cakephp/app/Console` folder into your `mywebsite/app`, eg.: `cp -R ../cakephp/app/Console ./app`.

Your folder structure should look like this now:

    mywebsite/
        app/              <- Your App
            Console/      <- Copied app/Console Folder
        app-backup/       <- Backup Copy of Your App
        cake/             <- 1.3 Version of CakePHP
        lib/              <- 2.x Version of CakePHP
            Cake/
        plugins/
        vendors/
        .htaccess
        index.php
    

Now we can run the upgrade shell by `cd`'ing into your `app` folder and running the command:

    ./Console/cake upgrade all
    

This will do **most** of the work to upgrade your app to 2.x. Check things over in your upgraded `app` folder. If everything looks good then congratulate yourself and delete your `mywebsite/cake` folder. Welcome to 2.x!

---

# Completion Shell | CakePHP

[Skip to content](https://book.cakephp.org/2.x/console-and-shells/completion-shell.html#VPContent)

Return to top

Completion Shell [​](https://book.cakephp.org/2.x/console-and-shells/completion-shell.html#completion-shell)

=============================================================================================================

Added in version 2.5

Working with the console gives the developer a lot of possibilities but having to completely know and write those commands can be tedious. Especially when developing new shells where the commands differ per minute iteration. The Completion Shells aids in this matter by providing an API to write completion scripts for shells like bash, zsh, fish etc.

Sub Commands [​](https://book.cakephp.org/2.x/console-and-shells/completion-shell.html#sub-commands)

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

The Completion Shell consists of a number of sub commands to assist the developer creating it's completion script. Each for a different step in the autocompletion process.

### commands [​](https://book.cakephp.org/2.x/console-and-shells/completion-shell.html#commands)

For the first step commands outputs the available Shell Commands, including plugin name when applicable. (All returned possibilities, for this and the other sub commands, are separated by a space.) For example:

    ./Console/cake Completion commands
    

Returns:

    acl api bake command_list completion console i18n schema server test testsuite upgrade
    

Your completion script can select the relevant commands from that list to continue with. (For this and the following sub commands.)

### subCommands [​](https://book.cakephp.org/2.x/console-and-shells/completion-shell.html#subcommands)

Once the preferred command has been chosen subCommands comes in as the second step and outputs the possible sub command for the given shell command. For example:

    ./Console/cake Completion subcommands bake
    

Returns:

    controller db_config fixture model plugin project test view
    

### options [​](https://book.cakephp.org/2.x/console-and-shells/completion-shell.html#options)

As the third and final options outputs options for the given (sub) command as set in getOptionParser. (Including the default options inherited from Shell.) For example:

    ./Console/cake Completion options bake
    

Returns:

    --help -h --verbose -v --quiet -q --connection -c --theme -t
    

Bash Example [​](https://book.cakephp.org/2.x/console-and-shells/completion-shell.html#bash-example)

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

The following bash example comes from the original author:

    # bash completion for CakePHP console
    
    _cake()
    {
        local cur prev opts cake
        COMPREPLY=()
        cake="${COMP_WORDS[0]}"
        cur="${COMP_WORDS[COMP_CWORD]}"
        prev="${COMP_WORDS[COMP_CWORD-1]}"
    
        if [[ "$cur" == -* ]] ; then
            if [[ ${COMP_CWORD} = 1 ]] ; then
                opts=$(${cake} Completion options)
            elif [[ ${COMP_CWORD} = 2 ]] ; then
                opts=$(${cake} Completion options "${COMP_WORDS[1]}")
            else
                opts=$(${cake} Completion options "${COMP_WORDS[1]}" "${COMP_WORDS[2]}")
            fi
    
            COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
            return 0
        fi
    
        if [[ ${COMP_CWORD} = 1 ]] ; then
            opts=$(${cake} Completion commands)
            COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
            return 0
        fi
    
        if [[ ${COMP_CWORD} = 2 ]] ; then
            opts=$(${cake} Completion subcommands $prev)
            COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
            if [[ $COMPREPLY = "" ]] ; then
                COMPREPLY=( $(compgen -df -- ${cur}) )
                return 0
            fi
            return 0
        fi
    
    
        opts=$(${cake} Completion fuzzy "${COMP_WORDS[@]:1}")
        COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
        if [[ $COMPREPLY = "" ]] ; then
            COMPREPLY=( $(compgen -df -- ${cur}) )
            return 0
        fi
        return 0;
    }
    
    complete -F _cake cake Console/cake

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40  
41  
42  
43  
44  
45  
46  
47  
48  
49  
50

---

# HttpSocket | CakePHP

[Skip to content](https://book.cakephp.org/2.x/core-utility-libraries/httpsocket.html#VPContent)

Return to top

HttpSocket [​](https://book.cakephp.org/2.x/core-utility-libraries/httpsocket.html#httpsocket)

===============================================================================================

`class` **HttpSocket**(mixed $config = array())

CakePHP includes an HttpSocket class which can be used easily for making requests. It is a great way to communicate with external webservices, or remote APIs.

Making a request [​](https://book.cakephp.org/2.x/core-utility-libraries/httpsocket.html#making-a-request)

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

You can use HttpSocket to create most kinds of HTTP requests with the different HTTP methods.

`method` HttpSocket::**get**($uri, $query, $request)

`method` HttpSocket::**post**($uri, $data, $request)

`method` HttpSocket::**put**($uri, $data, $request)

`method` HttpSocket::**delete**($uri, $query, $request)

`method` HttpSocket::**patch**($uri, $data, $request)

`method` HttpSocket::**request**($request)

Handling the response [​](https://book.cakephp.org/2.x/core-utility-libraries/httpsocket.html#handling-the-response)

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

Responses from requests made with `HttpSocket` are instances of `HttpResponse`. This object gives you a few accessor methods to access the contents of an HTTP response. This class implements the [ArrayAccess](https://www.php.net/manual/en/class.arrayaccess.php)
 and [\_\_toString()](https://www.php.net/manual/en/language.oop5.magic.php#language.oop5.magic.tostring)
, so you can continue using the `$http->response` as array and the return of request methods as string:

    App::uses('HttpSocket', 'Network/Http');
    
    $http = new HttpSocket();
    $response = $http->get('https://cakephp.org');
    
    // Check the body for the presence of a title tag.
    $titlePos = strpos($response->body, '<title>');
    
    // Get the status code for the response.
    $code = $response->code;

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

The `HttpResponse` has the following attributes:

*   `body` returns body of HTTP response (normally the HTML).
*   `headers` returns array with headers.
*   `cookies` returns array with new cookies (cookies from others request are not stored here).
*   `httpVersion` returns string with HTTP version (from first line in response).
*   `code` returns the integer with HTTP code.
*   `reasonPhrase` returns the string with HTTP code response.
*   `raw` returns the unchanged response from server.

The `HttpResponse` also exposes the following methods:

*   `body()` returns the body
*   `isOk()` returns if code is 200;
*   `isRedirect()` returns if code is 301, 302, 303 or 307 and the _Location_ header is set.
*   `getHeader()` allows you to fetch headers, see the next section.

### Getting headers from a response [​](https://book.cakephp.org/2.x/core-utility-libraries/httpsocket.html#getting-headers-from-a-response)

Following others places in core, the HttpSocket does not change the casing of headers. `2616` states that headers are case insensitive, and HttpSocket preserves the values the remote host sends:

    HTTP/1.1 200 OK
    Date: Mon, 16 Apr 2007 04:14:16 GMT
    server: CakeHttp Server
    content-tyPe: text/html
    

Your `$response->headers` (or `$response['header']`) will contain the exact keys sent. In order to safely access the header fields, it's best to use `getHeader()`. If your headers looks like:

    Date: Mon, 16 Apr 2007 04:14:16 GMT
    server: CakeHttp Server
    content-tyPe: text/html
    

You could fetch the above headers by calling:

    // $response is an instance of HttpResponse
    // get the Content-Type header.
    $response->getHeader('Content-Type');
    
    // get the date
    $response->getHeader('date');

1  
2  
3  
4  
5  
6  

Headers can be fetched case-insensitively.

### Automatically handling a redirect response [​](https://book.cakephp.org/2.x/core-utility-libraries/httpsocket.html#automatically-handling-a-redirect-response)

When the response has a valid redirect status code (see `HttpResponse::isRedirect`), an extra request can be automatically done according to the received _Location_ header:

    <?php
    App::uses('HttpSocket', 'Network/Http');
    
    $HttpSocket = new HttpSocket();
    $response = $HttpSocket->get('http://example.com/redirecting_url', array(), array('redirect' => true));

1  
2  
3  
4  
5  

The _redirect_ option can take the following values

*   **true** : all redirecting responses will fire a consequent new request
*   **integer** : the set value is the maximum number of redirections allowed (after reaching it, the _redirect_ value is considered as **false**)
*   **false** (default) : no consequent request will be fired

The returned `$response` will be the final one, according to the settings.

### Handling SSL certificates [​](https://book.cakephp.org/2.x/core-utility-libraries/httpsocket.html#handling-ssl-certificates)

When making requests to SSL services HttpSocket will attempt to validate the SSL certifcate using peer validation. If the certificate fails peer validation or does not match the hostname being accessed the connection will fail, and an exception will be thrown. By default HttpSocket will use the mozilla certificate authority file to verify SSL certificates. You can use the following options to configure how SSL certificates are handled:

*   `ssl_verify_peer` Set to false to disable SSL verification. This is **not recommended**.
*   `ssl_verify_host` Set to false if you wish to ignore hostname match errors when validating certificates.
*   `ssl_allow_self_signed` Set to true to enable self-signed certificates to be accepted. This requires `ssl_verify_peer` to be enabled.
*   `ssl_cafile` Set to the absolute path of the Certificate Authority file that you wish to use for verifying SSL certificates.

These options are provided as constructor arguments:

    $socket = new HttpSocket(array(
        'ssl_allow_self_signed' => true
    ));

1  
2  
3  

Would allow self-signed certificates for all requests made with the created socket.

Added in version 2.3

SSL certificate validation was added in 2.3.

### Creating a custom response class [​](https://book.cakephp.org/2.x/core-utility-libraries/httpsocket.html#creating-a-custom-response-class)

You can create your own response class to use with HttpSocket. You could create the file `app/Lib/Network/Http/YourResponse.php` with the content:

    App::uses('HttpResponse', 'Network/Http');
    
    class YourResponse extends HttpResponse {
    
        public function parseResponse($message) {
            parent::parseResponse($message);
            // Make what you want
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  

Before your request you'll need to change the responseClass property:

    App::uses('HttpSocket', 'Network/Http');
    
    $http = new HttpSocket();
    $http->responseClass = 'YourResponse';

1  
2  
3  
4  

Changed in version 2.3

As of 2.3.0 you should extend `HttpSocketResponse` instead. This avoids a common issue with the HTTP PECL extension.

### Downloading the results [​](https://book.cakephp.org/2.x/core-utility-libraries/httpsocket.html#downloading-the-results)

HttpSocket has a new method called setContentResource(). By setting a resource with this method, the content will be written to this resource, using fwrite(). To you download a file, you can do:

    App::uses('HttpSocket', 'Network/Http');
    
    $http = new HttpSocket();
    $f = fopen(TMP . 'bakery.xml', 'w');
    $http->setContentResource($f);
    $http->get('https://bakery.cakephp.org/comments.rss');
    fclose($f);

1  
2  
3  
4  
5  
6  
7  

NOTE

The headers are not included in file, you will only get the body content written to your resource. To disable saving into the resource, use `$http->setContentResource(false)`.

Using authentication [​](https://book.cakephp.org/2.x/core-utility-libraries/httpsocket.html#using-authentication)

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

HttpSocket supports a HTTP Basic and Digest authentication methods out of the box. You can also create custom authentication objects to support protocols like OAuth. To use any authentication system you need to configure the `HttpSocket` instance:

    App::uses('HttpSocket', 'Network/Http');
    
    $http = new HttpSocket();
    $http->configAuth('Basic', 'user', 'password');

1  
2  
3  
4  

The above would configure the `HttpSocket` instance to use Basic authentication using `user` and `password` as the credentials.

### Creating a custom authentication object [​](https://book.cakephp.org/2.x/core-utility-libraries/httpsocket.html#creating-a-custom-authentication-object)

You can now create your own authentication method to use with HttpSocket. You could create the file `app/Lib/Network/Http/YourMethodAuthentication.php` with the content:

    class YourMethodAuthentication {
    
    /**
     * Authentication
     *
     * @param HttpSocket $http
     * @param array $authInfo
     * @return void
     */
        public static function authentication(HttpSocket $http, &$authInfo) {
            // Do something, for example set $http->request['header']['Authentication'] value
        }
    
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

To configure HttpSocket to use your auth configuration, you can use the new method `configAuth()`:

    $http->configAuth('YourMethod', array('config1' => 'value1', 'config2' => 'value2'));
    $http->get('http://secure.your-site.com');

1  
2  

The `authentication()` method will be called to append the request headers.

### Using a HttpSocket with a proxy [​](https://book.cakephp.org/2.x/core-utility-libraries/httpsocket.html#using-a-httpsocket-with-a-proxy)

As part of auth configuration, you can configure proxy authentication. You can create your customized method to proxy authentication in the same class of authentication. For example:

    class YourMethodAuthentication {
    
    /**
     * Authentication
     *
     * @param HttpSocket $http
     * @param array $authInfo
     * @return void
     */
        public static function authentication(HttpSocket $http, &$authInfo) {
            // Do something, for example set $http->request['header']['Authentication'] value
        }
    
    /**
     * Proxy Authentication
     *
     * @param HttpSocket $http
     * @param array $proxyInfo
     * @return void
     */
        public static function proxyAuthentication(HttpSocket $http, &$proxyInfo) {
            // Do something, for example set $http->request['header']['Proxy-Authentication'] value
        }
    
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  

NOTE

To use a proxy, you must call the `HttpSocket::configProxy()` similar to `HttpSocket::configAuth()`.

---

# App Class | CakePHP

[Skip to content](https://book.cakephp.org/2.x/core-utility-libraries/app.html#VPContent)

Return to top

App Class [​](https://book.cakephp.org/2.x/core-utility-libraries/app.html#app-class)

======================================================================================

`class` **App**

The app class is responsible for path management, class location and class loading. Make sure you follow the [File And Classname Conventions](https://book.cakephp.org/2.x/getting-started/cakephp-conventions.html#file-and-classname-conventions)
.

Packages [​](https://book.cakephp.org/2.x/core-utility-libraries/app.html#packages)

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

CakePHP is organized around the idea of packages, each class belongs to a package or folder where other classes reside. You can configure each package location in your application using `App::build('APackage/SubPackage', $paths)` to inform the framework where should each class be loaded. Almost every class in the CakePHP framework can be swapped with your own compatible implementation. If you wish to use your own class instead of the classes the framework provides, just add the class to your libs folder emulating the directory location of where CakePHP expects to find it.

For instance if you'd like to use your own HttpSocket class, put it under:

    app/Lib/Network/Http/HttpSocket.php
    

Once you've done this App will load your override file instead of the file inside CakePHP.

Loading classes [​](https://book.cakephp.org/2.x/core-utility-libraries/app.html#loading-classes)

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

`static` App::**uses**(string $class, string $package)

rtype  
void

Classes are lazily loaded in CakePHP, however before the autoloader can find your classes you need to tell App, where it can find the files. By telling App which package a class can be found in, it can properly locate the file and load it the first time a class is used.

Some examples for common types of classes are:

Console Commands  
`App::uses('AppShell', 'Console/Command');`

Console Tasks  
`App::uses('BakeTask', 'Console/Command/Task');`

Controllers  
`App::uses('PostsController', 'Controller');`

Components  
`App::uses('AuthComponent', 'Controller/Component');`

Models  
`App::uses('MyModel', 'Model');`

Behaviors  
`App::uses('TreeBehavior', 'Model/Behavior');`

Views  
`App::uses('ThemeView', 'View');`

Helpers  
`App::uses('HtmlHelper', 'View/Helper');`

Libs  
`App::uses('PaymentProcessor', 'Lib');`

Vendors  
`App::uses('Textile', 'Vendor');`

Utilities  
`App::uses('CakeText', 'Utility');`

So basically the second param should simply match the folder path of the class file in core or app.

NOTE

Loading vendors usually means you are loading packages that do not follow conventions. For most vendor packages using `App::import()` is recommended.

### Loading files from plugins [​](https://book.cakephp.org/2.x/core-utility-libraries/app.html#loading-files-from-plugins)

Loading classes in plugins works much the same as loading app and core classes except you must specify the plugin you are loading from:

    // Load the class Comment in app/Plugin/PluginName/Model/Comment.php
    App::uses('Comment', 'PluginName.Model');
    
    // Load the class CommentComponent in
    // app/Plugin/PluginName/Controller/Component/CommentComponent.php
    App::uses('CommentComponent', 'PluginName.Controller/Component');

1  
2  
3  
4  
5  
6  

Finding paths to packages using App::path() [​](https://book.cakephp.org/2.x/core-utility-libraries/app.html#finding-paths-to-packages-using-app-path)

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

`static` App::**path**(string $package, string $plugin = null)

rtype  
array

Used to read information stored path:

    // return the model paths in your application
    App::path('Model');

1  
2  

This can be done for all packages that are apart of your application. You can also fetch paths for a plugin:

    // return the component paths in DebugKit
    App::path('Component', 'DebugKit');

1  
2  

`static` App::**paths**( )

rtype  
array

Get all the currently loaded paths from App. Useful for inspecting or storing all paths App knows about. For a paths to a specific package use `App::path()`

`static` App::**core**(string $package)

rtype  
array

Used for finding the path to a package inside CakePHP:

    // Get the path to Cache engines.
    App::core('Cache/Engine');

1  
2  

`static` App::**location**(string $className)

rtype  
string

Returns the package name where a class was defined to be located at.

Adding paths for App to find packages in [​](https://book.cakephp.org/2.x/core-utility-libraries/app.html#adding-paths-for-app-to-find-packages-in)

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

`static` App::**build**(array $paths = array(), mixed $mode = App::PREPEND)

rtype  
void

Sets up each package location on the file system. You can configure multiple search paths for each package, those will be used to look for files one folder at a time in the specified order. All paths must be terminated with a directory separator.

Adding additional controller paths for example would alter where CakePHP looks for controllers. This allows you to split your application up across the filesystem.

Usage:

    //will setup a new search path for the Model package
    App::build(array('Model' => array('/a/full/path/to/models/')));
    
    //will setup the path as the only valid path for searching models
    App::build(array('Model' => array('/path/to/models/')), App::RESET);
    
    //will setup multiple search paths for helpers
    App::build(array(
        'View/Helper' => array('/path/to/helpers/', '/another/path/')
    ));

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

If reset is set to true, all loaded plugins will be forgotten and they will be needed to be loaded again.

Examples:

    App::build(array('controllers' => array('/full/path/to/controllers/')));
    //becomes
    App::build(array('Controller' => array('/full/path/to/Controller/')));
    
    App::build(array('helpers' => array('/full/path/to/views/helpers/')));
    //becomes
    App::build(array('View/Helper' => array('/full/path/to/View/Helper/')));

1  
2  
3  
4  
5  
6  
7  

Changed in version 2.0

`App::build()` will not merge app paths with core paths anymore.

### Add new packages to an application [​](https://book.cakephp.org/2.x/core-utility-libraries/app.html#add-new-packages-to-an-application)

`App::build()` can be used to add new package locations. This is useful when you want to add new top level packages or, sub-packages to your application:

    App::build(array(
        'Service' => array('%s' . 'Service' . DS)
    ), App::REGISTER);

1  
2  
3  

The `%s` in newly registered packages will be replaced with the `APP` path. You must include a trailing `/` in registered packages. Once packages are registered, you can use `App::build()` to append/prepend/reset paths like any other package.

Changed in version 2.1

Registering packages was added in 2.1

Finding which objects CakePHP knows about [​](https://book.cakephp.org/2.x/core-utility-libraries/app.html#finding-which-objects-cakephp-knows-about)

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

`static` App::**objects**(string $type, mixed $path = null, boolean $cache = true)

rtype  
mixed Returns an array of objects of the given type or false if incorrect.

You can find out which objects App knows about using `App::objects('Controller')` for example to find which application controllers App knows about.

Example usage:

    //returns array('DebugKit', 'Blog', 'User');
    App::objects('plugin');
    
    //returns array('PagesController', 'BlogController');
    App::objects('Controller');

1  
2  
3  
4  
5  

You can also search only within a plugin's objects by using the plugin dot syntax. :

    // returns array('MyPluginPost', 'MyPluginComment');
    App::objects('MyPlugin.Model');

1  
2  

Changed in version 2.0

1.  Returns `array()` instead of false for empty results or invalid types
2.  Does not return core objects anymore, `App::objects('core')` will return `array()`.
3.  Returns the complete class name

Locating plugins [​](https://book.cakephp.org/2.x/core-utility-libraries/app.html#locating-plugins)

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

`static` App::**pluginPath**(string $plugin)

rtype  
string

Plugins can be located with App as well. Using `App::pluginPath('DebugKit');` for example, will give you the full path to the DebugKit plugin:

    $path = App::pluginPath('DebugKit');

1  

Locating themes [​](https://book.cakephp.org/2.x/core-utility-libraries/app.html#locating-themes)

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

`static` App::**themePath**(string $theme)

rtype  
string

Themes can be found `App::themePath('purple');`, would give the full path to the purple theme.

Including files with App::import() [​](https://book.cakephp.org/2.x/core-utility-libraries/app.html#including-files-with-app-import)

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

`static` App::**import**(mixed $type = null, string $name = null, mixed $parent = true, array $search = array(), string $file = null, boolean $return = false)

rtype  
boolean

At first glance `App::import` seems complex, however in most use cases only 2 arguments are required.

NOTE

This method is equivalent to `require`'ing the file. It is important to realize that the class subsequently needs to be initialized.

    // The same as require('Controller/UsersController.php');
    App::import('Controller', 'Users');
    
    // We need to load the class
    $Users = new UsersController();
    
    // If we want the model associations, components, etc to be loaded
    $Users->constructClasses();

1  
2  
3  
4  
5  
6  
7  
8  

**All classes that were loaded in the past using App::import('Core', $class) will need to be loaded using App::uses() referring to the correct package. This change has provided large performance gains to the framework.**

Changed in version 2.0

*   The method no longer looks for classes recursively, it strictly uses the values for the paths defined in `App::build()`
*   It will not be able to load `App::import('Component', 'Component')` use `App::uses('Component', 'Controller');`.
*   Using `App::import('Lib', 'CoreClass');` to load core classes is no longer possible.
*   Importing a non-existent file, supplying a wrong type or package name, or null values for `$name` and `$file` parameters will result in a false return value.
*   `App::import('Core', 'CoreClass')` is no longer supported, use `App::uses()` instead and let the class autoloading do the rest.
*   Loading Vendor files does not look recursively in the vendors folder, it will also not convert the file to underscored anymore as it did in the past.

Overriding classes in CakePHP [​](https://book.cakephp.org/2.x/core-utility-libraries/app.html#overriding-classes-in-cakephp)

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

You can override almost every class in the framework, exceptions are the `App` and `Configure` classes. Whenever you like to perform such overriding, just add your class to your `app/Lib` folder mimicking the internal structure of the framework. Some examples to follow:

*   To override the `Dispatcher` class, create `app/Lib/Routing/Dispatcher.php`
*   To override the `CakeRoute` class, create `app/Lib/Routing/Route/CakeRoute.php`
*   To override the `Model` class, create `app/Lib/Model/Model.php`

When you load the overridden classes now, the files in `app/Lib` will be loaded instead of the built-in core ones.

Loading Vendor Files [​](https://book.cakephp.org/2.x/core-utility-libraries/app.html#loading-vendor-files)

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

You can use `App::uses()` to load classes in vendors directories. It follows the same conventions as loading other files:

    // Load the class Geshi in app/Vendor/Geshi.php
    App::uses('Geshi', 'Vendor');

1  
2  

To load classes in subdirectories, you'll need to add those paths with `App::build()`:

    // Load the class ClassInSomePackage in
    // app/Vendor/SomePackage/ClassInSomePackage.php
    App::build(array('Vendor' => array(APP . 'Vendor' . DS . 'SomePackage' . DS)));
    App::uses('ClassInSomePackage', 'Vendor');

1  
2  
3  
4  

Your vendor files may not follow conventions, have a class that differs from the file name or does not contain classes. You can load those files using `App::import()`. The following examples illustrate how to load vendor files from a number of path structures. These vendor files could be located in any of the vendor folders.

To load **app/Vendor/geshi.php**:

    App::import('Vendor', 'geshi');

1  

NOTE

The geshi file must be a lower-case file name as CakePHP will not find it otherwise.

To load **app/Vendor/flickr/flickr.php**:

    App::import('Vendor', 'flickr', array('file' => 'flickr/flickr.php'));

1  

To load **app/Vendor/some.name.php**:

    App::import('Vendor', 'SomeName', array('file' => 'some.name.php'));

1  

To load **app/Vendor/services/well.named.php**:

    App::import(
        'Vendor',
        'WellNamed',
        array('file' => 'services' . DS . 'well.named.php')
    );

1  
2  
3  
4  
5  

To load **app/Plugin/Awesome/Vendor/services/well.named.php**:

    App::import(
        'Vendor',
        'Awesome.WellNamed',
        array('file' => 'services' . DS . 'well.named.php')
    );

1  
2  
3  
4  
5  

To load **app/Plugin/Awesome/Vendor/Folder/Foo.php**:

    App::import(
        'Vendor',
        'Awesome.Foo',
        array('file' => 'Folder' . DS . 'Foo.php'));

1  
2  
3  
4  

It wouldn't make a difference if your vendor files are inside your /vendors directory. CakePHP will automatically find it.

To load **vendors/vendorName/libFile.php**:

    App::import(
        'Vendor',
        'aUniqueIdentifier',
        array('file' => 'vendorName' . DS . 'libFile.php')
    );

1  
2  
3  
4  
5  

App Init/Load/Shutdown Methods [​](https://book.cakephp.org/2.x/core-utility-libraries/app.html#app-init-load-shutdown-methods)

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

`static` App::**init**( )

rtype  
void

Initializes the cache for App, registers a shutdown function.

`static` App::**load**(string $className)

rtype  
boolean

Method to handle the automatic class loading. It will look for each class' package defined using `App::uses()` and with this information it will resolve the package name to a full path to load the class from. File name for each class should follow the class name. For instance, if a class is name `MyCustomClass` the file name should be `MyCustomClass.php`

`static` App::**shutdown**( )

rtype  
void

Object destructor. Writes cache file if changes have been made to the `$_map`.

---

# Content Security Policy Middleware | CakePHP

[Skip to content](https://book.cakephp.org/6.x/security/content-security-policy.html#VPContent)

Return to top

Content Security Policy Middleware [​](https://book.cakephp.org/6.x/security/content-security-policy.html#content-security-policy-middleware)

==============================================================================================================================================

The `CspMiddleware` makes it simpler to add Content-Security-Policy headers in your application. Before using it you should install `paragonie/csp-builder`:

    composer require paragonie/csp-builder

1  

You can then configure the middleware using an array, or passing in a built `CSPBuilder` object:

    use Cake\Http\Middleware\CspMiddleware;
    
    $csp = new CspMiddleware([\
        'script-src' => [\
            'allow' => [\
                'https://www.google-analytics.com',\
            ],\
            'self' => true,\
            'unsafe-inline' => false,\
            'unsafe-eval' => false,\
        ],\
    ]);
    
    $middlewareQueue->add($csp);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

If you want to use a more strict CSP configuration, you can enable nonce based CSP rules with the `scriptNonce` and `styleNonce` options. When enabled these options will modify your CSP policy and set the `cspScriptNonce` and `cspStyleNonce` attributes in the request. These attributes are applied to the `nonce` attribute of all script and CSS link elements created by `HtmlHelper`. This simplifies the adoption of policies that use a [nonce-base64](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src)
 and `strict-dynamic` for increased security and easier maintenance:

    $policy = [\
        // Must exist even if empty to set nonce for for script-src\
        'script-src' => [],\
        'style-src' => [],\
    ];
    // Enable automatic nonce addition to script & CSS link tags.
    $csp = new CspMiddleware($policy, [\
        'scriptNonce' => true,\
        'styleNonce' => true,\
    ]);
    $middlewareQueue->add($csp);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11

---

# NumberHelper | CakePHP

[Skip to content](https://book.cakephp.org/2.x/core-libraries/helpers/number.html#VPContent)

Return to top

NumberHelper [​](https://book.cakephp.org/2.x/core-libraries/helpers/number.html#numberhelper)

===============================================================================================

`class` **NumberHelper**(View $view, array $settings = array())

The NumberHelper contains convenient methods that enable display numbers in common formats in your views. These methods include ways to format currency, percentages, data sizes, format numbers to specific precisions and also to give you more flexibility with formatting numbers.

Changed in version 2.1

`NumberHelper` have been refactored into `CakeNumber` class to allow easier use outside of the `View` layer. Within a view, these methods are accessible via the `NumberHelper` class and you can call it as you would call a normal helper method: `$this->Number->method($args);`.

All of these functions return the formatted number; They do not automatically echo the output into the view.

`method` CakeNumber::**currency**(float $number, string $currency = 'USD', array $options = array())

`method` CakeNumber::**defaultCurrency**(string $currency)

`method` CakeNumber::**addFormat**(string $formatName, array $options)

`method` CakeNumber::**precision**(mixed $number, int $precision = 3)

`method` CakeNumber::**toPercentage**(mixed $number, int $precision = 2, array $options = array())

`method` CakeNumber::**fromReadableSize**(string $size, $default)

`method` CakeNumber::**toReadableSize**(string $dataSize)

`method` CakeNumber::**format**(mixed $number, mixed $options=false)

`method` CakeNumber::**formatDelta**(mixed $number, mixed $options=array())

WARNING

Since 2.4 the symbols are now UTF-8. Please see the migration guide for details if you run a non-UTF-8 app.

---

# Components | CakePHP

[Skip to content](https://book.cakephp.org/6.x/controllers/components.html#VPContent)

Return to top

Components [​](https://book.cakephp.org/6.x/controllers/components.html#components)

====================================================================================

Components are packages of logic that are shared between controllers. CakePHP comes with a fantastic set of core components you can use to aid in various common tasks. You can also create your own components. If you find yourself wanting to copy and paste things between controllers, you should consider creating your own component to contain the functionality. Creating components keeps controller code clean and allows you to reuse code between different controllers.

For more information on the components included in CakePHP, check out the chapter for each component:

*   [Flash](https://book.cakephp.org/6.x/controllers/components/flash.html)
    
*   [Form Protection Component](https://book.cakephp.org/6.x/controllers/components/form-protection.html)
    
*   [Checking HTTP Cache](https://book.cakephp.org/6.x/controllers/components/check-http-cache.html)
    

Configuring Components [​](https://book.cakephp.org/6.x/controllers/components.html#configuring-components)

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

Many of the core components require configuration. One example would be the [Form Protection Component](https://book.cakephp.org/6.x/controllers/components/form-protection.html)
. Configuration for these components, and for components in general, is usually done via `loadComponent()` in your Controller's `initialize()` method or via the `$components` array:

    class PostsController extends AppController
    {
        public function initialize(): void
        {
            parent::initialize();
            $this->loadComponent('FormProtection', [\
                'unlockedActions' => ['index'],\
            ]);
            $this->loadComponent('Flash');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

You can configure components at runtime using the `setConfig()` method. Often, this is done in your controller's `beforeFilter()` method. The above could also be expressed as:

    public function beforeFilter(EventInterface $event): void
    {
        $this->FormProtection->setConfig('unlockedActions', ['index']);
    }

1  
2  
3  
4  

Like helpers, components implement `getConfig()` and `setConfig()` methods to read and write configuration data:

    // Read config data.
    $this->FormProtection->getConfig('unlockedActions');
    
    // Set config
    $this->Flash->setConfig('key', 'myFlash');

1  
2  
3  
4  
5  

As with helpers, components will automatically merge their `$_defaultConfig` property with constructor configuration to create the `$_config` property which is accessible with `getConfig()` and `setConfig()`.

### Aliasing Components [​](https://book.cakephp.org/6.x/controllers/components.html#aliasing-components)

One common setting to use is the `className` option, which allows you to alias components. This feature is useful when you want to replace `$this->Flash` or another common Component reference with a custom implementation:

    // src/Controller/PostsController.php
    class PostsController extends AppController
    {
        public function initialize(): void
        {
            $this->loadComponent('Flash', [\
                'className' => 'MyFlash',\
            ]);
        }
    }
    
    // src/Controller/Component/MyFlashComponent.php
    use Cake\Controller\Component\FlashComponent;
    
    class MyFlashComponent extends FlashComponent
    {
        // Add your code to override the core FlashComponent
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

The above would _alias_ `MyFlashComponent` to `$this->Flash` in your controllers.

NOTE

Aliasing a component replaces that instance anywhere that component is used, including inside other Components.

### Loading Components on the Fly [​](https://book.cakephp.org/6.x/controllers/components.html#loading-components-on-the-fly)

You might not need all of your components available on every controller action. In situations like this you can load a component at runtime using the `loadComponent()` method in your controller:

    // In a controller action
    $this->loadComponent('OneTimer');
    $time = $this->OneTimer->getTime();

1  
2  
3  

NOTE

Keep in mind that components loaded on the fly will not have missed callbacks called. If you rely on the `beforeFilter` or `startup` callbacks being called, you may need to call them manually depending on when you load your component.

Using Components [​](https://book.cakephp.org/6.x/controllers/components.html#using-components)

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

Once you've included some components in your controller, using them is pretty simple. Each component you use is exposed as a property on your controller. If you had loaded up the `Cake\Controller\Component\FlashComponent` in your controller, you could access it like so:

    class PostsController extends AppController
    {
        public function initialize(): void
        {
            parent::initialize();
            $this->loadComponent('Flash');
        }
    
        public function delete()
        {
            if ($this->Post->delete($this->request->getData('Post.id')) {
                $this->Flash->success('Post deleted.');
    
                return $this->redirect(['action' => 'index']);
            }
        }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  

NOTE

Since both Models and Components are added to Controllers as properties they share the same 'namespace'. Be sure to not give a component and a model the same name.

Changed in version 5.1.0

Components are able to use [Dependency Injection](https://book.cakephp.org/6.x/development/dependency-injection.html)
 to receive services.

Creating a Component [​](https://book.cakephp.org/6.x/controllers/components.html#creating-a-component)

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

Suppose our application needs to perform a complex mathematical operation in many different parts of the application. We could create a component to house this shared logic for use in many different controllers.

The first step is to create a new component file and class. Create the file in **src/Controller/Component/MathComponent.php**. The basic structure for the component would look something like this:

    namespace App\Controller\Component;
    
    use Cake\Controller\Component;
    
    class MathComponent extends Component
    {
        public function doComplexOperation($amount1, $amount2)
        {
            return $amount1 + $amount2;
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

NOTE

All components must extend `Cake\Controller\Component`. Failing to do this will trigger an exception.

Components can use [Dependency Injection](https://book.cakephp.org/6.x/development/dependency-injection.html)
 to receive services as constructor parameters:

    namespace App\Controller\Component;
    
    use Cake\Controller\Component;
    use App\Service\UserService;
    
    class SsoComponent extends Component
    {
        private Users $users;
    
        public function __construct(
            ComponentRegistry $registry,
            array $config = [],
            UserService $users
        ) {
            parent::__construct($registry, $config);
            $this->users = $users;
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

### Including your Component in your Controllers [​](https://book.cakephp.org/6.x/controllers/components.html#including-your-component-in-your-controllers)

Once our component is finished, we can use it in the application's controllers by loading it during the controller's `initialize()` method. Once loaded, the controller will be given a new attribute named after the component, through which we can access an instance of it:

    // In a controller
    // Make the new component available at $this->Math,
    // as well as the standard $this->Flash
    public function initialize(): void
    {
        parent::initialize();
        $this->loadComponent('Math');
        $this->loadComponent('Flash');
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  

When including Components in a Controller you can also declare a set of parameters that will be passed on to the Component's constructor. These parameters can then be handled by the Component:

    // In your controller.
    public function initialize(): void
    {
        parent::initialize();
        $this->loadComponent('Math', [\
            'precision' => 2,\
            'randomGenerator' => 'srand',\
        ]);
        $this->loadComponent('Flash');
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

The above would pass the array containing precision and randomGenerator to `MathComponent::initialize()` in the `$config` parameter.

### Using Other Components in your Component [​](https://book.cakephp.org/6.x/controllers/components.html#using-other-components-in-your-component)

Sometimes one of your components may need to use another component. You can load other components by adding them to the $components property:

    // src/Controller/Component/CustomComponent.php
    namespace App\Controller\Component;
    
    use Cake\Controller\Component;
    
    class CustomComponent extends Component
    {
        // The other component your component uses
        protected array $components = ['Existing'];
    
        // Execute any other additional setup for your component.
        public function initialize(array $config): void
        {
            $this->Existing->foo();
        }
    
        public function bar()
        {
            // ...
        }
    }
    
    // src/Controller/Component/ExistingComponent.php
    namespace App\Controller\Component;
    
    use Cake\Controller\Component;
    
    class ExistingComponent extends Component
    {
        public function foo()
        {
            // ...
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  

NOTE

In contrast to a component included in a controller no callbacks will be triggered on a component's component.

### Accessing a Component's Controller [​](https://book.cakephp.org/6.x/controllers/components.html#accessing-a-component-s-controller)

From within a Component you can access the current controller through the registry:

    $controller = $this->getController();

1  

Component Callbacks [​](https://book.cakephp.org/6.x/controllers/components.html#component-callbacks)

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

Components also offer a few request life-cycle callbacks that allow them to augment the request cycle.

`method` Class::**beforeFilter**(EventInterface $event): void

`method` Class::**startup**(EventInterface $event): void

`method` Class::**beforeRender**(EventInterface $event): void

`method` Class::**afterFilter**(EventInterface $event): void

`method` Class::**beforeRedirect**(EventInterface $event, $url, Response $response): void

Using Redirects in Component Events [​](https://book.cakephp.org/6.x/controllers/components.html#using-redirects-in-component-events)

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

To redirect from within a component callback method you can use the following:

    public function beforeFilter(EventInterface $event): void
    {
        if (...) {
            $event->setResult($this->getController()->redirect('/'));
    
            return;
        }
    
        ...
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

By setting a redirect as event result you let CakePHP know that you don't want any other component callbacks to run, and that the controller should not handle the action any further. As of 4.1.0 you can raise a `RedirectException` to signal a redirect:

    use Cake\Http\Exception\RedirectException;
    use Cake\Routing\Router;
    
    public function beforeFilter(EventInterface $event): void
    {
        throw new RedirectException(Router::url('/'))
    }

1  
2  
3  
4  
5  
6  
7  

Raising an exception will halt all other event listeners and create a new response that doesn't retain or inherit any of the current response's headers. When raising a `RedirectException` you can include additional headers:

    throw new RedirectException(Router::url('/'), 302, [\
        'Header-Key' => 'value',\
    ]);

1  
2  
3

---

# REST | CakePHP

[Skip to content](https://book.cakephp.org/6.x/development/rest.html#VPContent)

Return to top

REST [​](https://book.cakephp.org/6.x/development/rest.html#rest)

==================================================================

REST is a foundational concept to the open web. CakePHP provides functionality to build applications that expose REST APIs with low complexity abstractions and interfaces.

CakePHP provides methods for exposing your controller actions via HTTP methods, and serializing view variables based on content-type negotiation. Content-Type negotiation allows clients of your application to send requests with serialize data and receive responses with serialized data via the `Accept` and `Content-Type` headers, or URL extensions.

Getting Started [​](https://book.cakephp.org/6.x/development/rest.html#getting-started)

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

To get started with adding a REST API to your application, we'll first need a controller containing actions that we want to expose as an API. A basic controller might look something like this:

    // src/Controller/RecipesController.php
    use Cake\View\JsonView;
    
    class RecipesController extends AppController
    {
        public function viewClasses(): array
        {
            return [JsonView::class];
        }
    
        public function index()
        {
            $recipes = $this->Recipes->find('all')->all();
            $this->set('recipes', $recipes);
            $this->viewBuilder()->setOption('serialize', ['recipes']);
        }
    
        public function view($id)
        {
            $recipe = $this->Recipes->get($id);
            $this->set('recipe', $recipe);
            $this->viewBuilder()->setOption('serialize', ['recipe']);
        }
    
        public function add()
        {
            $this->request->allowMethod(['post', 'put']);
            $recipe = $this->Recipes->newEntity($this->request->getData());
            if ($this->Recipes->save($recipe)) {
                $message = 'Saved';
            } else {
                $message = 'Error';
            }
            $this->set([\
                'message' => $message,\
                'recipe' => $recipe,\
            ]);
            $this->viewBuilder()->setOption('serialize', ['recipe', 'message']);
        }
    
        public function edit($id)
        {
            $this->request->allowMethod(['patch', 'post', 'put']);
            $recipe = $this->Recipes->get($id);
            $recipe = $this->Recipes->patchEntity($recipe, $this->request->getData());
            if ($this->Recipes->save($recipe)) {
                $message = 'Saved';
            } else {
                $message = 'Error';
            }
            $this->set([\
                'message' => $message,\
                'recipe' => $recipe,\
            ]);
            $this->viewBuilder()->setOption('serialize', ['recipe', 'message']);
        }
    
        public function delete($id)
        {
            $this->request->allowMethod(['delete']);
            $recipe = $this->Recipes->get($id);
            $message = 'Deleted';
            if (!$this->Recipes->delete($recipe)) {
                $message = 'Error';
            }
            $this->set('message', $message);
            $this->viewBuilder()->setOption('serialize', ['message']);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40  
41  
42  
43  
44  
45  
46  
47  
48  
49  
50  
51  
52  
53  
54  
55  
56  
57  
58  
59  
60  
61  
62  
63  
64  
65  
66  
67  
68  
69  

In our `RecipesController`, we have several actions that define the logic to create, edit, view and delete recipes. In each of our actions we're using the `serialize` option to tell CakePHP which view variables should be serialized when making API responses. We'll connect our controller to the application URLs with [Resource Routes](https://book.cakephp.org/6.x/development/routing.html#resource-routes)
:

    // in config/routes.php
    $routes->scope('/', function (RouteBuilder $routes): void {
        $routes->setExtensions(['json']);
        $routes->resources('Recipes');
    });

1  
2  
3  
4  
5  

These routes will enable URLs like `/recipes.json` to return a JSON encoded response. Clients could also make a request to `/recipes` with the `Content-Type: application/json` header as well.

Encoding Response Data [​](https://book.cakephp.org/6.x/development/rest.html#encoding-response-data)

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

In the above controller, we're defining a `viewClasses()` method. This method defines which views your controller has available for content-negotitation. We're including CakePHP's `JsonView` which enables JSON based responses. To learn more about it and Xml based views see [JSON and XML views](https://book.cakephp.org/6.x/views/json-and-xml-views.html)
. is used by CakePHP to select a view class to render a REST response with.

Next, we have several methods that expose basic logic to create, edit, view and delete recipes. In each of our actions we're using the `serialize` option to tell CakePHP which view variables should be serialized when making API responses.

If we wanted to modify the data before it is converted into JSON we should not define the `serialize` option, and instead use template files. We would place the REST templates for our RecipesController inside **templates/Recipes/json**.

See the [Controller Viewclasses](https://book.cakephp.org/6.x/controllers.html#controller-viewclasses)
 for more information on how CakePHP's response negotiation functionality.

Parsing Request Bodies [​](https://book.cakephp.org/6.x/development/rest.html#parsing-request-bodies)

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

Creating the logic for the edit action requires another step. Because our resources are serialized as JSON it would be ergonomic if our requests also contained the JSON representation.

In our `Application` class ensure the following is present:

    $middlewareQueue->add(new BodyParserMiddleware());

1  

This middleware will use the `content-type` header to detect the format of request data and parse enabled formats. By default only `JSON` parsing is enabled by default. You can enable XML support by enabling the `xml` constructor option. When a request is made with a `Content-Type` of `application/json`, CakePHP will decode the request data and update the request so that `$request->getData()` contains the parsed body.

You can also wire in additional deserializers for alternate formats if you need them, using `BodyParserMiddleware::addParser()`.

---

# Validation | CakePHP

[Skip to content](https://book.cakephp.org/6.x/core-libraries/validation.html#VPContent)

Return to top

Validation [​](https://book.cakephp.org/6.x/core-libraries/validation.html#validation)

=======================================================================================

The validation package in CakePHP provides features to build validators that can validate arbitrary arrays of data with ease. You can find a [list of available Validation rules in the API](https://api.cakephp.org/5.x/class-Cake.Validation.Validation.html)
.

Creating Validators [​](https://book.cakephp.org/6.x/core-libraries/validation.html#creating-validators)

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

`class` Cake\\Validation\\**Validator**

Validator objects define the rules that apply to a set of fields. Validator objects contain a mapping between fields and validation sets. In turn, the validation sets contain a collection of rules that apply to the field they are attached to. Creating a validator is simple:

    use Cake\Validation\Validator;
    
    $validator = new Validator();

1  
2  
3  

Once created, you can start defining sets of rules for the fields you want to validate:

    $validator
        ->requirePresence('title')
        ->notEmptyString('title', 'Please fill this field')
        ->add('title', [\
            'length' => [\
                'rule' => ['minLength', 10],\
                'message' => 'Titles need to be at least 10 characters long',\
            ]\
        ])
        ->allowEmptyDateTime('published')
        ->add('published', 'boolean', [\
            'rule' => 'boolean',\
        ])
        ->requirePresence('body')
        ->add('body', 'length', [\
            'rule' => ['minLength', 50],\
            'message' => 'Articles must have a substantial body.',\
        ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

As seen in the example above, validators are built with a fluent interface that allows you to define rules for each field you want to validate.

There were a few methods called in the example above, so let's go over the various features. The `add()` method allows you to add new rules to a validator. You can either add rules individually or in groups as seen above.

### Requiring Field Presence [​](https://book.cakephp.org/6.x/core-libraries/validation.html#requiring-field-presence)

The `requirePresence()` method requires the field to be present in any validated array. If the field is absent, validation will fail. The `requirePresence()` method has 4 modes:

*   `true` The field's presence is always required.
*   `false` The field's presence is not required.
*   `create` The field's presence is required when validating a **create** operation.
*   `update` The field's presence is required when validating an **update** operation.

By default, `true` is used. Key presence is checked by using `array_key_exists()` so that null values will count as present. You can set the mode using the second parameter:

    $validator->requirePresence('author_id', 'create');

1  

If you have multiple fields that are required, you can define them as a list:

    // Define multiple fields for create
    $validator->requirePresence(['author_id', 'title'], 'create');
    
    // Define multiple fields for mixed modes
    $validator->requirePresence([\
        'author_id' => [\
            'mode' => 'create',\
            'message' => 'An author is required.',\
        ],\
        'published' => [\
            'mode' => 'update',\
            'message' => 'The published state is required.',\
        ],\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

### Allowing Empty Fields [​](https://book.cakephp.org/6.x/core-libraries/validation.html#allowing-empty-fields)

Validators offer several methods to control which fields accept empty values and which empty values are accepted and not forwarded to other validation rules for the named field. CakePHP provides empty value support for different shapes of data:

1.  `allowEmptyString()` Should be used when you want to only accept an empty string.
2.  `allowEmptyArray()` Should be used when you want to accept an array.
3.  `allowEmptyDate()` Should be used when you want to accept an empty string, or an array that is marshalled into a date field.
4.  `allowEmptyTime()` Should be used when you want to accept an empty string, or an array that is marshalled into a time field.
5.  `allowEmptyDateTime()` Should be used when you want to accept an empty string or an array that is marshalled into a datetime or timestamp field.
6.  `allowEmptyFile()` Should be used when you want to accept an array that contains an empty uploaded file.

You also can use following specific validators: `notEmptyString()`, `notEmptyArray()`, `notEmptyFile()`, `notEmptyDate()`, `notEmptyTime()`, `notEmptyDateTime()`.

The `allowEmpty*` methods support a `when` parameter that allows you to control when a field can or cannot be empty:

*   `false` The field is not allowed to be empty.
*   `create` The field can be empty when validating a **create** operation.
*   `update` The field can be empty when validating an **update** operation.
*   A callback that returns `true` or `false` to indicate whether a field is allowed to be empty. See the [Conditional Validation](https://book.cakephp.org/6.x/core-libraries/validation.html#conditional-validation)
     section for examples on how to use this parameter.

An example of these methods in action is:

    $validator->allowEmptyDateTime('published')
        ->allowEmptyString('title', 'Title cannot be empty', false)
        ->allowEmptyString('body', 'Body cannot be empty', 'update')
        ->allowEmptyFile('header_image', 'update');
        ->allowEmptyDateTime('posted', 'update');

1  
2  
3  
4  
5  

### Adding Validation Rules [​](https://book.cakephp.org/6.x/core-libraries/validation.html#adding-validation-rules)

The `Validator` class provides methods that make building validators simple and expressive. For example adding validation rules to a username could look like:

    $validator = new Validator();
    $validator
        ->email('username')
        ->ascii('username')
        ->lengthBetween('username', [4, 8]);

1  
2  
3  
4  
5  

See the [Validator API documentation](https://api.cakephp.org/5.x/class-Cake.Validation.Validator.html)
 for the full set of validator methods.

### Using Custom Validation Rules [​](https://book.cakephp.org/6.x/core-libraries/validation.html#using-custom-validation-rules)

In addition to using methods on the `Validator`, and coming from providers, you can also use any callable, including anonymous functions, as validation rules:

    // Use a global function
    $validator->add('title', 'custom', [\
        'rule' => 'validate_title',\
        'message' => 'The title is not valid'\
    ]);
    
    // Use an array callable that is not in a provider
    $validator->add('title', 'custom', [\
        'rule' => [$this, 'method'],\
        'message' => 'The title is not valid'\
    ]);
    
    // Use a closure
    $extra = 'Some additional value needed inside the closure';
    $validator->add('title', 'custom', [\
        'rule' => function ($value, $context) use ($extra) {\
            // Custom logic that returns true/false\
        },\
        'message' => 'The title is not valid'\
    ]);
    
    // Use a rule from a custom provider
    $validator->add('title', 'custom', [\
        'rule' => 'customRule',\
        'provider' => 'custom',\
        'message' => 'The title is not unique enough'\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  

Closures or callable methods will receive 2 arguments when called. The first will be the value for the field being validated. The second is a context array containing data related to the validation process:

*   **data**: The original data passed to the validation method, useful if you plan to create rules comparing values.
*   **providers**: The complete list of rule provider objects, useful if you need to create complex rules by calling multiple providers.
*   **newRecord**: Whether the validation call is for a new record or a preexisting one.
*   **entity**: The entity being validated if provided to `validate()`.

Closures should return boolean true if the validation passes. If it fails, return boolean false or for a custom error message return a string, see the [Conditional/Dynamic Error Messages](https://book.cakephp.org/6.x/core-libraries/validation.html#dynamic-validation-error-messages)
 section for further details.

Changed in version 5.3.0

The `entity` key was added to validation context.

### Conditional/Dynamic Error Messages [​](https://book.cakephp.org/6.x/core-libraries/validation.html#conditional-dynamic-error-messages)

Validation rule methods, being it [custom callables](https://book.cakephp.org/6.x/core-libraries/validation.html#custom-validation-rules)
, or [methods supplied by providers](https://book.cakephp.org/6.x/core-libraries/validation.html#adding-validation-providers)
, can either return a boolean, indicating whether the validation succeeded, or they can return a string, which means that the validation failed, and that the returned string should be used as the error message.

Possible existing error messages defined via the `message` option will be overwritten by the ones returned from the validation rule method:

    $validator->add('length', 'custom', [\
        'rule' => function ($value, $context) {\
            if (!$value) {\
                return false;\
            }\
    \
            if ($value < 10) {\
                return 'Error message when value is less than 10';\
            }\
    \
            if ($value > 20) {\
                return 'Error message when value is greater than 20';\
            }\
    \
            return true;\
        },\
        'message' => 'Generic error message used when `false` is returned'\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

### Conditional Validation [​](https://book.cakephp.org/6.x/core-libraries/validation.html#conditional-validation)

When defining validation rules, you can use the `on` key to define when a validation rule should be applied. If left undefined, the rule will always be applied. Other valid values are `create` and `update`. Using one of these values will make the rule apply to only create or update operations.

Additionally, you can provide a callable function that will determine whether or not a particular rule should be applied:

    $validator->add('picture', 'file', [\
        'rule' => ['mimeType', ['image/jpeg', 'image/png']],\
        'on' => function ($context) {\
            return !empty($context['data']['show_profile_picture']);\
        }\
    ]);

1  
2  
3  
4  
5  
6  

You can access the other submitted field values using the `$context['data']` array. The above example will make the rule for 'picture' optional depending on whether the value for `show_profile_picture` is empty. You could also use the `uploadedFile` validation rule to create optional file upload inputs:

    $validator->add('picture', 'file', [\
        'rule' => ['uploadedFile', ['optional' => true]],\
    ]);

1  
2  
3  

The `allowEmpty*`, `notEmpty*` and `requirePresence()` methods will also accept a callback function as their last argument. If present, the callback determines whether or not the rule should be applied. For example, a field is sometimes allowed to be empty:

    $validator->allowEmptyString('tax', 'This field is required', function ($context) {
        return !$context['data']['is_taxable'];
    });

1  
2  
3  

Likewise, a field can be required to be populated when certain conditions are met:

    $validator->notEmptyString('email_frequency', 'This field is required', function ($context) {
        return !empty($context['data']['wants_newsletter']);
    });

1  
2  
3  

In the above example, the `email_frequency` field cannot be left empty if the the user wants to receive the newsletter.

Further it's also possible to require a field to be present under certain conditions only:

    $validator->requirePresence('full_name', function ($context) {
        if (isset($context['data']['action'])) {
            return $context['data']['action'] === 'subscribe';
        }
    
        return false;
    });
    $validator->requirePresence('email');

1  
2  
3  
4  
5  
6  
7  
8  

This would require the `full_name` field to be present only in case the user wants to create a subscription, while the `email` field would always be required.

The `$context` parameter passed to custom conditional callbacks contains the following keys:

*   `data` The data being validated.
*   `newRecord` a boolean indicating whether a new or existing record is being validated.
*   `field` The current field being validated.
*   `providers` The validation providers attached to the current validator.

### Marking Rules as the Last to Run [​](https://book.cakephp.org/6.x/core-libraries/validation.html#marking-rules-as-the-last-to-run)

When fields have multiple rules, each validation rule will be run even if the previous one has failed. This allows you to collect as many validation errors as you can in a single pass. If you want to stop execution after a specific rule has failed, you can set the `last` option to `true`:

    $validator = new Validator();
    $validator
        ->add('body', [\
            'minLength' => [\
                'rule' => ['minLength', 10],\
                'last' => true,\
                'message' => 'Comments must have a substantial body.',\
            ],\
            'maxLength' => [\
                'rule' => ['maxLength', 250],\
                'message' => 'Comments cannot be too long.',\
            ],\
        ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

If the minLength rule fails in the example above, the maxLength rule will not be run.

Make Rules 'last' by default [​](https://book.cakephp.org/6.x/core-libraries/validation.html#make-rules-last-by-default)

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

You can have the `last` option automatically applied to each rule you can use the `setStopOnFailure()` method to enable this behavior:

    public function validationDefault(Validator $validator): Validator
    {
        $validator
            ->setStopOnFailure()
            ->requirePresence('email', 'create')
            ->notBlank('email')
            ->email('email');
    
        return $validator;
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

When enabled all fields will stop validation on the first failing rule instead of checking all possible rules. In this case only a single error message will appear under the form field.

### Adding Validation Providers [​](https://book.cakephp.org/6.x/core-libraries/validation.html#adding-validation-providers)

The `Validator`, `ValidationSet` and `ValidationRule` classes do not provide any validation methods themselves. Validation rules come from 'providers'. You can bind any number of providers to a Validator object. Validator instances come with a 'default' provider setup automatically. The default provider is mapped to the `Cake\Validation\Validation` class. This makes it simple to use the methods on that class as validation rules. When using Validators and the ORM together, additional providers are configured for the table and entity objects. You can use the `setProvider()` method to add any additional providers your application needs:

    $validator = new Validator();
    
    // Use an object instance.
    $validator->setProvider('custom', $myObject);
    
    // Use a class name. Methods must be static.
    $validator->setProvider('custom', 'App\Model\Validation');

1  
2  
3  
4  
5  
6  
7  

Validation providers can be objects, or class names. If a class name is used the methods must be static. To use a provider other than 'default', be sure to set the `provider` key in your rule:

    // Use a rule from the table provider
    $validator->add('title', 'custom', [\
        'rule' => 'customTableMethod',\
        'provider' => 'table'\
    ]);

1  
2  
3  
4  
5  

If you wish to add a `provider` to all `Validator` objects that are created in the future, you can use the `addDefaultProvider()` method as follows:

    use Cake\Validation\Validator;
    
    // Use an object instance.
    Validator::addDefaultProvider('custom', $myObject);
    
    // Use a class name. Methods must be static.
    Validator::addDefaultProvider('custom', 'App\Model\Validation');

1  
2  
3  
4  
5  
6  
7  

NOTE

DefaultProviders must be added before the `Validator` object is created therefore **config/bootstrap.php** is the best place to set up your default providers.

You can use the [Localized plugin](https://github.com/cakephp/localized)
 to get providers based on countries. With this plugin, you'll be able to validate model fields, depending on a country, ie:

    namespace App\Model\Table;
    
    use Cake\ORM\Table;
    use Cake\Validation\Validator;
    
    class PostsTable extends Table
    {
        public function validationDefault(Validator $validator): Validator
        {
            // add the provider to the validator
            $validator->setProvider('fr', 'Cake\Localized\Validation\FrValidation');
            // use the provider in a field validation rule
            $validator->add('phoneField', 'myCustomRuleNameForPhone', [\
                'rule' => 'phone',\
                'provider' => 'fr'\
            ]);
    
            return $validator;
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  

The localized plugin uses the two letter ISO code of the countries for validation, like en, fr, de.

There are a few methods that are common to all classes, defined through the [ValidationInterface interface](https://github.com/cakephp/localized/blob/master/src/Validation/ValidationInterface.php)
:

    phone() to check a phone number
    postal() to check a postal code
    personId() to check a country specific person ID

1  
2  
3  

### Nesting Validators [​](https://book.cakephp.org/6.x/core-libraries/validation.html#nesting-validators)

When validating [Modelless Forms](https://book.cakephp.org/6.x/core-libraries/form.html)
 with nested data, or when working with models that contain array data types, it is necessary to validate the nested data you have. CakePHP makes it simple to add validators to specific attributes. For example, assume you are working with a non-relational database and need to store an article and its comments:

    $data = [\
        'title' => 'Best article',\
        'comments' => [\
            ['comment' => ''],\
        ],\
    ];

1  
2  
3  
4  
5  
6  

To validate the comments you would use a nested validator:

    $validator = new Validator();
    $validator->add('title', 'not-blank', ['rule' => 'notBlank']);
    
    $commentValidator = new Validator();
    $commentValidator->add('comment', 'not-blank', ['rule' => 'notBlank']);
    
    // Connect the nested validators.
    $validator->addNestedMany('comments', $commentValidator);
    
    // Get all errors including those from nested validators.
    $validator->validate($data);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

You can create 1:1 'relationships' with `addNested()` and 1:N 'relationships' with `addNestedMany()`. With both methods, the nested validator's errors will contribute to the parent validator's errors and influence the final result. Like other validator features, nested validators support error messages and conditional application:

    $validator->addNestedMany(
        'comments',
        $commentValidator,
        'Invalid comment',
        'create'
    );

1  
2  
3  
4  
5  
6  

The error message for a nested validator can be found in the `_nested` key.

### Creating Reusable Validators [​](https://book.cakephp.org/6.x/core-libraries/validation.html#creating-reusable-validators)

While defining validators inline where they are used makes for good example code, it doesn't lead to maintainable applications. Instead, you should create `Validator` sub-classes for your reusable validation logic:

    // In src/Model/Validation/ContactValidator.php
    namespace App\Model\Validation;
    
    use Cake\Validation\Validator;
    
    class ContactValidator extends Validator
    {
        public function __construct()
        {
            parent::__construct();
            // Add validation rules here.
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  

Validating Data [​](https://book.cakephp.org/6.x/core-libraries/validation.html#validating-data)

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

Now that you've created a validator and added the rules you want to it, you can start using it to validate data. Validators are able to validate array data. For example, if you wanted to validate a contact form before creating and sending an email you could do the following:

    use Cake\Validation\Validator;
    
    $validator = new Validator();
    $validator
        ->requirePresence('email')
        ->add('email', 'validFormat', [\
            'rule' => 'email',\
            'message' => 'E-mail must be valid',\
        ])
        ->requirePresence('name')
        ->notEmptyString('name', 'We need your name.')
        ->requirePresence('comment')
        ->notEmptyString('comment', 'You need to give a comment.');
    
    $errors = $validator->validate($this->request->getData());
    if (empty($errors)) {
        // Send an email.
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

The `getErrors()` method will return a non-empty array when there are validation failures. The returned array of errors will be structured like:

    $errors = [\
        'email' => ['E-mail must be valid'],\
    ];

1  
2  
3  

If you have multiple errors on a single field, an array of error messages will be returned per field. By default the `getErrors()` method applies rules for the 'create' mode. If you'd like to apply 'update' rules you can do the following:

    $errors = $validator->validate($this->request->getData(), false);
    if (!$errors) {
        // Send an email.
    }

1  
2  
3  
4  

NOTE

If you need to validate entities you should use methods like `Cake\ORM\Table::newEntity()`, `Cake\ORM\Table::newEntities()`, `Cake\ORM\Table::patchEntity()`, `Cake\ORM\Table::patchEntities()` as they are designed for that.

Validating Entity Data [​](https://book.cakephp.org/6.x/core-libraries/validation.html#validating-entity-data)

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

Validation is meant for checking request data coming from forms or other user interfaces used to populate the entities.

The request data is validated automatically when using the `newEntity()`, `newEntities()`, `patchEntity()` or `patchEntities()` methods of `Table` class:

    // In the ArticlesController class
    $article = $this->Articles->newEntity($this->request->getData());
    if ($article->getErrors()) {
        // Do work to show error messages.
    }

1  
2  
3  
4  
5  

Similarly, when you need to validate multiple entities at a time, you can use the `newEntities()` method:

    // In the ArticlesController class
    $entities = $this->Articles->newEntities($this->request->getData());
    foreach ($entities as $entity) {
        if (!$entity->getErrors()) {
            $this->Articles->save($entity);
        }
    }

1  
2  
3  
4  
5  
6  
7  

The `newEntity()`, `patchEntity()`, `newEntities()` and `patchEntities()` methods allow you to specify which associations are validated, and which validation sets to apply using the `options` parameter:

    $valid = $this->Articles->newEntity($article, [\
        'associated' => [\
            'Comments' => [\
                'associated' => ['User'],\
                'validate' => 'special',\
            ],\
        ],\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  

Apart from validating user provided data maintaining integrity of data regardless where it came from is important. To solve this problem CakePHP offers a second level of validation which is called "application rules". You can read more about them in the [Applying Application Rules](https://book.cakephp.org/6.x/orm/validation.html#application-rules)
 section.

Core Validation Rules [​](https://book.cakephp.org/6.x/core-libraries/validation.html#core-validation-rules)

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

CakePHP provides a basic suite of validation methods in the `Validation` class. The Validation class contains a variety of static methods that provide validators for several common validation situations.

The [API documentation](https://api.cakephp.org/5.x/class-Cake.Validation.Validation.html)
 for the `Validation` class provides a good list of the validation rules that are available, and their basic usage.

Some of the validation methods accept additional parameters to define boundary conditions or valid options. You can provide these boundary conditions and options as follows:

    $validator = new Validator();
    $validator
        ->add('title', 'minLength', [\
            'rule' => ['minLength', 10],\
        ])
        ->add('rating', 'validValue', [\
            'rule' => ['range', 1, 5],\
        ]);

1  
2  
3  
4  
5  
6  
7  
8  

Core rules that take additional parameters should have an array for the `rule` key that contains the rule as the first element, and the additional parameters as the remaining parameters.

---

# Internationalization & Localization | CakePHP

[Skip to content](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html#VPContent)

Return to top

Internationalization & Localization [​](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html#internationalization-localization)

==================================================================================================================================================================

One of the best ways for an application to reach a larger audience is to cater to multiple languages. This can often prove to be a daunting task, but the internationalization and localization features in CakePHP make it much easier.

First, it's important to understand some terminology. _Internationalization_ refers to the ability of an application to be localized. The term _localization_ refers to the adaptation of an application to meet specific language (or culture) requirements (i.e. a "locale"). Internationalization and localization are often abbreviated as i18n and l10n respectively; 18 and 10 are the number of characters between the first and last character.

Setting Up Translations [​](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html#setting-up-translations)

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

There are only a few steps to go from a single-language application to a multi-lingual application, the first of which is to make use of the `__()` function in your code. Below is an example of some code for a single-language application:

    <h2>Popular Articles</h2>

1  

To internationalize your code, all you need to do is to wrap strings in `__()` like so:

    <h2><?= __('Popular Articles') ?></h2>

1  

Doing nothing else, these two code examples are functionally identical - they will both send the same content to the browser. The `__()` function will translate the passed string if a translation is available, or return it unmodified.

### Language Files [​](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html#language-files)

Translations can be made available by using language files stored in the application. The default format for CakePHP translation files is the [Gettext](https://en.wikipedia.org/wiki/Gettext)
 format. Files need to be placed under **resources/locales/** and within this directory, there should be a subfolder for each language the application needs to support:

    resources/
        locales/
            en_US/
                default.po
            en_GB/
                default.po
                validation.po
            es/
                default.po
    

The default domain is 'default', therefore the locale folder should at least contain the **default.po** file as shown above. A domain refers to any arbitrary grouping of translation messages. When no group is used, then the default group is selected.

The core strings messages extracted from the CakePHP library can be stored separately in a file named **cake.po** in **resources/locales/**. The [CakePHP localized library](https://github.com/cakephp/localized)
 houses translations for the client-facing translated strings in the core (the cake domain). To use these files, link or copy them into their expected location: **resources/locales/<locale>/cake.po**. If your locale is incomplete or incorrect, please submit a PR in this repository to fix it.

Plugins can also contain translation files, the convention is to use the `under_scored` version of the plugin name as the domain for the translation messages:

    MyPlugin/
        resources/
            locales/
                fr/
                    my_plugin.po
                    additional.po
                de/
                    my_plugin.po
    

Translation folders can be the two or three letter ISO code of the language or the full ICU locale name such as `fr_FR`, `es_AR`, `da_DK` which contains both the language and the country where it is spoken.

See [https://www.localeplanet.com/icu/](https://www.localeplanet.com/icu/)
 for the full list of locales.

Changed in version 4.5.0

As of 4.5.0 plugins can contain multiple translation domains. Use `MyPlugin.additional` to reference plugin domains.

An example translation file could look like this:

    msgid "My name is {0}"
    msgstr "Je m'appelle {0}"
    
    msgid "I'm {0,number} years old"
    msgstr "J'ai {0,number} ans"

1  
2  
3  
4  
5  

NOTE

Translations are cached - Make sure that you always clear the cache after making changes to translations! You can either use the [cache tool](https://book.cakephp.org/6.x/console-commands/cache.html)
 and run for example `bin/cake cache clear _cake_core_`, or manually clear the `tmp/cache/persistent` folder (if using file based caching).

### Extract Pot Files with I18n Shell [​](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html#extract-pot-files-with-i18n-shell)

To create the pot files from \_\_() and other internationalized types of messages that can be found in the application code, you can use the i18n command. Please read the [following chapter](https://book.cakephp.org/6.x/console-commands/i18n.html)
 to learn more.

### Setting the Default Locale [​](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html#setting-the-default-locale)

The default locale can be set in your **config/app.php** file by setting `App.defaultLocale`:

    'App' => [\
        ...\
        'defaultLocale' => env('APP_DEFAULT_LOCALE', 'en_US'),\
        ...\
    ]

1  
2  
3  
4  
5  

This will control several aspects of the application, including the default translations language, the date format, number format and currency whenever any of those is displayed using the localization libraries that CakePHP provides.

### Changing the Locale at Runtime [​](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html#changing-the-locale-at-runtime)

To change the language for translated strings you can call this method:

    use Cake\I18n\I18n;
    
    I18n::setLocale('de_DE');

1  
2  
3  

This will also change how numbers and dates are formatted when using one of the localization tools.

Using Translation Functions [​](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html#using-translation-functions)

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

CakePHP provides several functions that will help you internationalize your application. The most frequently used one is `__()`. This function is used to retrieve a single translation message or return the same string if no translation was found:

    echo __('Popular Articles');

1  

If you need to group your messages, for example, translations inside a plugin, you can use the `__d()` function to fetch messages from another domain:

    echo __d('my_plugin', 'Trending right now');

1  

NOTE

If you want to translate plugins that are vendor namespaced, you must use the domain string `vendor/plugin_name`. But the related language file will become `plugins/<Vendor>/<PluginName>/resources/locales/<locale>/plugin_name.po` inside your plugin folder.

Sometimes translations strings can be ambiguous for people translating them. This can happen if two strings are identical but refer to different things. For example, 'letter' has multiple meanings in English. To solve that problem, you can use the `__x()` function:

    echo __x('written communication', 'He read the first letter');
    
    echo __x('alphabet learning', 'He read the first letter');

1  
2  
3  

The first argument is the context of the message and the second is the message to be translated.

    msgctxt "written communication"
    msgid "He read the first letter"
    msgstr "Er las den ersten Brief"

1  
2  
3  

### Using Variables in Translation Messages [​](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html#using-variables-in-translation-messages)

Translation functions allow you to interpolate variables into the messages using special markers defined in the message itself or in the translated string:

    echo __("Hello, my name is {0}, I'm {1} years old", ['Sara', 12]);

1  

Markers are numeric, and correspond to the keys in the passed array. You can also pass variables as independent arguments to the function:

    echo __("Small step for {0}, Big leap for {1}", 'Man', 'Humanity');

1  

All translation functions support placeholder replacements:

    __d('validation', 'The field {0} cannot be left empty', 'Name');
    
    __x('alphabet', 'He read the letter {0}', 'Z');

1  
2  
3  

The `'` (single quote) character acts as an escape code in translation messages. Any variables between single quotes will not be replaced and is treated as literal text. For example:

    __("This variable '{0}' be replaced.", 'will not');

1  

By using two adjacent quotes your variables will be replaced properly:

    __("This variable ''{0}'' be replaced.", 'will');

1  

These functions take advantage of the [ICU MessageFormatter](https://php.net/manual/en/messageformatter.format.php)
 so you can translate messages and localize dates, numbers and currency at the same time:

    echo __(
        'Hi {0}, your balance on the {1,date} is {2,number,currency}',
        ['Charles', new DateTime('2014-01-13 11:12:00'), 1354.37]
    );
    
    // Returns
    Hi Charles, your balance on the Jan 13, 2014, 11:12 AM is $ 1,354.37

1  
2  
3  
4  
5  
6  
7  

Numbers in placeholders can be formatted as well with fine grain control of the output:

    echo __(
        'You have traveled {0,number} kilometers in {1,number,integer} weeks',
        [5423.344, 5.1]
    );
    
    // Returns
    You have traveled 5,423.34 kilometers in 5 weeks
    
    echo __('There are {0,number,#,###} people on earth', 6.1 * pow(10, 8));
    
    // Returns
    There are 6,100,000,000 people on earth

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

This is the list of formatter specifiers you can put after the word `number`:

*   `integer`: Removes the decimal part
*   `currency`: Puts the locale currency symbol and rounds decimals
*   `percent`: Formats the number as a percentage

Dates can also be formatted by using the word `date` after the placeholder number. A list of extra options follows:

*   `short`
*   `medium`
*   `long`
*   `full`

The word `time` after the placeholder number is also accepted and it understands the same options as `date`.

You can also use named placeholders like `{name}` in the message strings. When using named placeholders, pass the placeholder and replacement in an array using key/value pairs, for example:

    // echos:  Hi. My name is Sara. I'm 12 years old.
    echo __("Hi. My name is {name}. I'm {age} years old.", ['name' => 'Sara', 'age' => 12]);

1  
2  

### Plurals [​](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html#plurals)

One crucial part of internationalizing your application is getting your messages pluralized correctly depending on the language they are shown. CakePHP provides a couple ways to correctly select plurals in your messages.

#### Using ICU Plural Selection [​](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html#using-icu-plural-selection)

The first one is taking advantage of the `ICU` message format that comes by default in the translation functions. In the translations file you could have the following strings

    msgid "{0,plural,=0{No records found} =1{Found 1 record} other{Found # records}}"
    msgstr "{0,plural,=0{Ningún resultado} =1{1 resultado} other{# resultados}}"
    
    msgid "{placeholder,plural,=0{No records found} =1{Found 1 record} other{Found {1} records}}"
    msgstr "{placeholder,plural,=0{Ningún resultado} =1{1 resultado} other{{1} resultados}}"

1  
2  
3  
4  
5  

And in the application use the following code to output either of the translations for such string:

    __('{0,plural,=0{No records found }=1{Found 1 record} other{Found # records}}', [0]);
    
    // Returns "Ningún resultado" as the argument {0} is 0
    
    __('{0,plural,=0{No records found} =1{Found 1 record} other{Found # records}}', [1]);
    
    // Returns "1 resultado" because the argument {0} is 1
    
    __('{placeholder,plural,=0{No records found} =1{Found 1 record} other{Found {1} records}}', [0, 'many', 'placeholder' => 2])
    
    // Returns "many resultados" because the argument {placeholder} is 2 and
    // argument {1} is 'many'

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

A closer look to the format we just used will make it evident how messages are built:

    { [count placeholder],plural, case1{message} case2{message} case3{...} ... }

1  

The `[count placeholder]` can be the array key number of any of the variables you pass to the translation function. It will be used for selecting the correct plural form.

Note that to reference `[count placeholder]` within `{message}` you have to use `#`.

You can of course use simpler message ids if you don't want to type the full plural selection sequence in your code

    msgid "search.results"
    msgstr "{0,plural,=0{Ningún resultado} =1{1 resultado} other{{1} resultados}}"

1  
2  

Then use the new string in your code:

    __('search.results', [2, 2]);
    
    // Returns: "2 resultados"

1  
2  
3  

The latter version has the downside that there is a need to have a translation messages file even for the default language, but has the advantage that it makes the code more readable and leaves the complicated plural selection strings in the translation files.

Sometimes using direct number matching in plurals is impractical. For example, languages like Arabic require a different plural when you refer to few things and other plural form for many things. In those cases you can use the ICU matching aliases. Instead of writing:

    =0{No results} =1{...} other{...}

1  

You can do:

    zero{No Results} one{One result} few{...} many{...} other{...}

1  

Make sure you read the [Language Plural Rules Guide](https://unicode-org.github.io/cldr-staging/charts/37/supplemental/language_plural_rules.html)
 to get a complete overview of the aliases you can use for each language.

#### Using Gettext Plural Selection [​](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html#using-gettext-plural-selection)

The second plural selection format accepted is using the built-in capabilities of Gettext. In this case, plurals will be stored in the `.po` file by creating a separate message translation line per plural form:

    # One message identifier for singular
    msgid "One file removed"
    # Another one for plural
    msgid_plural "{0} files removed"
    # Translation in singular
    msgstr[0] "Un fichero eliminado"
    # Translation in plural
    msgstr[1] "{0} ficheros eliminados"

1  
2  
3  
4  
5  
6  
7  
8  

When using this other format, you are required to use another translation function:

    // Returns: "10 ficheros eliminados"
    $count = 10;
    __n('One file removed', '{0} files removed', $count, $count);
    
    // It is also possible to use it inside a domain
    __dn('my_plugin', 'One file removed', '{0} files removed', $count, $count);

1  
2  
3  
4  
5  
6  

The number inside `msgstr[]` is the number assigned by Gettext for the plural form of the language. Some languages have more than two plural forms, for example Croatian:

    msgid "One file removed"
    msgid_plural "{0} files removed"
    msgstr[0] "{0} datoteka je uklonjena"
    msgstr[1] "{0} datoteke su uklonjene"
    msgstr[2] "{0} datoteka je uklonjeno"

1  
2  
3  
4  
5  

Please visit the [Launchpad languages page](https://translations.launchpad.net/+languages)
 for a detailed explanation of the plural form numbers for each language.

Creating Your Own Translators [​](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html#creating-your-own-translators)

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

If you need to diverge from CakePHP conventions regarding where and how translation messages are stored, you can create your own translation message loader. The easiest way to create your own translator is by defining a loader for a single domain and locale:

    use Cake\I18n\Package;
    // Prior to 4.2 you need to use Aura\Intl\Package
    
    I18n::setTranslator('animals', function () {
        $package = new Package(
            'default', // The formatting strategy (ICU)
            'default'  // The fallback domain
        );
        $package->setMessages([\
            'Dog' => 'Chien',\
            'Cat' => 'Chat',\
            'Bird' => 'Oiseau'\
            ...\
        ]);
    
        return $package;
    }, 'fr_FR');

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

The above code can be added to your **config/bootstrap.php** so that translations can be found before any translation function is used. The absolute minimum that is required for creating a translator is that the loader function should return a `Cake\I18n\Package` object (prior to 4.2 it should be an `Aura\Intl\Package` object). Once the code is in place you can use the translation functions as usual:

    I18n::setLocale('fr_FR');
    __d('animals', 'Dog'); // Returns "Chien"

1  
2  

As you see, `Package` objects take translation messages as an array. You can pass the `setMessages()` method however you like: with inline code, including another file, calling another function, etc. CakePHP provides a few loader functions you can reuse if you just need to change where messages are loaded. For example, you can still use **.po** files, but loaded from another location:

    use Cake\I18n\MessagesFileLoader as Loader;
    
    // Load messages from resources/locales/folder/sub_folder/filename.po
    I18n::setTranslator(
        'animals',
        new Loader('filename', 'folder/sub_folder', 'po'),
        'fr_FR'
    );

1  
2  
3  
4  
5  
6  
7  
8  

### Creating Message Parsers [​](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html#creating-message-parsers)

It is possible to continue using the same conventions CakePHP uses, but use a message parser other than `PoFileParser`. For example, if you wanted to load translation messages using `YAML`, you will first need to created the parser class:

    namespace App\I18n\Parser;
    
    class YamlFileParser
    {
        public function parse($file)
        {
            return yaml_parse_file($file);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  

The file should be created in the **src/I18n/Parser** directory of your application. Next, create the translations file under **resources/locales/fr\_FR/animals.yaml**

    Dog: Chien
    Cat: Chat
    Bird: Oiseau

1  
2  
3  

And finally, configure the translation loader for the domain and locale:

    use Cake\I18n\MessagesFileLoader as Loader;
    
    I18n::setTranslator(
        'animals',
        new Loader('animals', 'fr_FR', 'yaml'),
        'fr_FR'
    );

1  
2  
3  
4  
5  
6  
7  

### Creating Generic Translators [​](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html#creating-generic-translators)

Configuring translators by calling `I18n::setTranslator()` for each domain and locale you need to support can be tedious, specially if you need to support more than a few different locales. To avoid this problem, CakePHP lets you define generic translator loaders for each domain.

Imagine that you wanted to load all translations for the default domain and for any language from an external service:

    use Cake\I18n\Package;
    // Prior to 4.2 you need to use Aura\Intl\Package
    
    I18n::config('default', function ($domain, $locale) {
        $locale = Locale::parseLocale($locale);
        $lang = $locale['language'];
        $messages = file_get_contents("http://example.com/translations/$lang.json");
    
        return new Package(
            'default', // Formatter
            null, // Fallback (none for default domain)
            json_decode($messages, true)
        )
    });

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  

The above example calls an example external service to load a JSON file with the translations and then just build a `Package` object for any locale that is requested in the application.

If you'd like to change how packages are loaded for all packages, that don't have specific loaders set you can replace the fallback package loader by using the `_fallback` package:

    I18n::config('_fallback', function ($domain, $locale) {
        // Custom code that yields a package here.
    });

1  
2  
3  

### Plurals and Context in Custom Translators [​](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html#plurals-and-context-in-custom-translators)

The arrays used for `setMessages()` can be crafted to instruct the translator to store messages under different domains or to trigger Gettext-style plural selection. The following is an example of storing translations for the same key in different contexts:

    [\
        'He reads the letter {0}' => [\
            'alphabet' => 'Él lee la letra {0}',\
            'written communication' => 'Él lee la carta {0}',\
        ],\
    ]

1  
2  
3  
4  
5  
6  

Similarly, you can express Gettext-style plurals using the messages array by having a nested array key per plural form:

    [\
        'I have read one book' => 'He leído un libro',\
        'I have read {0} books' => [\
            'He leído un libro',\
            'He leído {0} libros',\
        ],\
    ]

1  
2  
3  
4  
5  
6  
7  

### Using Different Formatters [​](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html#using-different-formatters)

In previous examples we have seen that Packages are built using `default` as first argument, and it was indicated with a comment that it corresponded to the formatter to be used. Formatters are classes responsible for interpolating variables in translation messages and selecting the correct plural form.

If you're dealing with a legacy application, or you don't need the power offered by the ICU message formatting, CakePHP also provides the `sprintf` formatter:

    return Package('sprintf', 'fallback_domain', $messages);

1  

The messages to be translated will be passed to the `sprintf()` function for interpolating the variables:

    __('Hello, my name is %s and I am %d years old', 'José', 29);

1  

It is possible to set the default formatter for all translators created by CakePHP before they are used for the first time. This does not include manually created translators using the `setTranslator()` and `config()` methods:

    I18n::setDefaultFormatter('sprintf');

1  

Localizing Dates and Numbers [​](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html#localizing-dates-and-numbers)

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

When outputting Dates and Numbers in your application, you will often need that they are formatted according to the preferred format for the country or region that you wish your page to be displayed.

In order to change how dates and numbers are displayed you just need to change the current locale setting and use the right classes:

    use Cake\I18n\I18n;
    use Cake\I18n\DateTime;
    use Cake\I18n\Number;
    
    I18n::setLocale('fr-FR');
    
    $date = new DateTime('2015-04-05 23:00:00');
    
    echo $date; // Displays 05/04/2015 23:00
    
    echo Number::format(524.23); // Displays 524,23

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

Make sure you read the [Date & Time](https://book.cakephp.org/6.x/core-libraries/time.html)
 and [Number](https://book.cakephp.org/6.x/core-libraries/number.html)
 sections to learn more about formatting options.

By default dates returned for the ORM results use the `Cake\I18n\DateTime` class, so displaying them directly in you application will be affected by changing the current locale.

### Parsing Localized Datetime Data [​](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html#parsing-localized-datetime-data)

When accepting localized data from the request, it is nice to accept datetime information in a user's localized format. In a controller, or [Middleware](https://book.cakephp.org/6.x/controllers/middleware.html)
 you can configure the Date, Time, and DateTime types to parse localized formats:

    use Cake\Database\TypeFactory;
    
    // Enable default locale format parsing.
    TypeFactory::build('datetime')->useLocaleParser();
    
    // Configure a custom datetime format parser format.
    TypeFactory::build('datetime')->useLocaleParser()->setLocaleFormat('dd-M-y');
    
    // You can also use IntlDateFormatter constants.
    TypeFactory::build('datetime')->useLocaleParser()
        ->setLocaleFormat([IntlDateFormatter::SHORT, -1]);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

The default parsing format is the same as the default string format.

### Converting Request Data from the User's Timezone [​](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html#converting-request-data-from-the-user-s-timezone)

When handling data from users in different timezones you will need to convert the datetimes in request data into your application's timezone. You can use `setUserTimezone()` from a controller or [Middleware](https://book.cakephp.org/6.x/controllers/middleware.html)
 to make this process simpler:

    // Set the user's timezone
    TypeFactory::build('datetime')->setUserTimezone($user->timezone);

1  
2  

Once set, when your application creates or updates entities from request data, the ORM will automatically convert datetime values from the user's timezone into your application's timezone. This ensures that your application is always working in the timezone defined in `App.defaultTimezone`.

If your application handles datetime information in a number of actions you can use a middleware to define both timezone conversion and locale parsing:

    namespace App\Middleware;
    
    use Cake\Database\TypeFactory;
    use Psr\Http\Message\ResponseInterface;
    use Psr\Http\Message\ServerRequestInterface;
    use Psr\Http\Server\MiddlewareInterface;
    use Psr\Http\Server\RequestHandlerInterface;
    
    class DatetimeMiddleware implements MiddlewareInterface
    {
        public function process(
            ServerRequestInterface $request,
            RequestHandlerInterface $handler
        ): ResponseInterface {
            // Get the user from the request.
            // This example assumes your user entity has a timezone attribute.
            $user = $request->getAttribute('identity');
            if ($user) {
                TypeFactory::build('datetime')
                    ->useLocaleParser()
                    ->setUserTimezone($user->timezone);
            }
    
            return $handler->handle($request);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  

Automatically Choosing the Locale Based on Request Data [​](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html#automatically-choosing-the-locale-based-on-request-data)

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

By using the `LocaleSelectorMiddleware` in your application, CakePHP will automatically set the locale based on the current user:

    // in src/Application.php
    use Cake\I18n\Middleware\LocaleSelectorMiddleware;
    
    // Update the middleware function, adding the new middleware
    public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue
    {
        // Add middleware and set the valid locales
        $middlewareQueue->add(new LocaleSelectorMiddleware(['en_US', 'fr_FR']));
        // To accept any locale header value
        $middlewareQueue->add(new LocaleSelectorMiddleware(['*']));
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  

The `LocaleSelectorMiddleware` will use the `Accept-Language` header to automatically set the user's preferred locale. You can use the locale list option to restrict which locales will automatically be used.

Translate Content/Entities [​](https://book.cakephp.org/6.x/core-libraries/internationalization-and-localization.html#translate-content-entities)

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

If you want to translate content/entities then you should look at the [Translate Behavior](https://book.cakephp.org/6.x/orm/behaviors/translate.html)
.

---

# Command Objects | CakePHP

[Skip to content](https://book.cakephp.org/6.x/console-commands/commands.html#VPContent)

Return to top

Command Objects [​](https://book.cakephp.org/6.x/console-commands/commands.html#command-objects)

=================================================================================================

`class` Cake\\Console\\**Command**

CakePHP comes with a number of built-in commands for speeding up your development, and automating routine tasks. You can use these same libraries to create commands for your application and plugins.

Creating a Command [​](https://book.cakephp.org/6.x/console-commands/commands.html#creating-a-command)

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

Let's create our first Command. For this example, we'll create a simple Hello world command. In your application's **src/Command** directory create **HelloCommand.php**. Put the following code inside it:

    <?php
    namespace App\Command;
    
    use Cake\Command\Command;
    use Cake\Console\Arguments;
    use Cake\Console\ConsoleIo;
    
    class HelloCommand extends Command
    {
        public function execute(Arguments $args, ConsoleIo $io): int
        {
            $io->out('Hello world.');
    
            return static::CODE_SUCCESS;
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  

Command classes must implement an `execute()` method that does the bulk of their work. This method is called when a command is invoked. Lets call our first command application directory, run:

    bin/cake hello

1  

You should see the following output:

    Hello world.
    

Our `execute()` method isn't very interesting let's read some input from the command line:

    <?php
    namespace App\Command;
    
    use Cake\Command\Command;
    use Cake\Console\Arguments;
    use Cake\Console\ConsoleIo;
    use Cake\Console\ConsoleOptionParser;
    
    class HelloCommand extends Command
    {
        protected function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
        {
            $parser->addArgument('name', [\
                'help' => 'What is your name',\
            ]);
    
            return $parser;
        }
    
        public function execute(Arguments $args, ConsoleIo $io): int
        {
            $name = $args->getArgument('name');
            $io->out("Hello {$name}.");
    
            return static::CODE_SUCCESS;
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  

After saving this file, you should be able to run the following command:

    bin/cake hello jillian
    
    # Outputs
    Hello jillian

1  
2  
3  
4  

Changing the Default Command Name [​](https://book.cakephp.org/6.x/console-commands/commands.html#changing-the-default-command-name)

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

CakePHP will use conventions to generate the name your commands use on the command line. If you want to overwrite the generated name implement the `defaultName()` method in your command:

    public static function defaultName(): string
    {
        return 'oh_hi';
    }

1  
2  
3  
4  

The above would make our `HelloCommand` accessible by `cake oh_hi` instead of `cake hello`.

Defining Arguments and Options [​](https://book.cakephp.org/6.x/console-commands/commands.html#defining-arguments-and-options)

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

As we saw in the last example, we can use the `buildOptionParser()` hook method to define arguments. We can also define options. For example, we could add a `yell` option to our `HelloCommand`:

    // ...
    protected function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
    {
        $parser
            ->addArgument('name', [\
                'help' => 'What is your name',\
            ])
            ->addOption('yell', [\
                'help' => 'Shout the name',\
                'boolean' => true,\
            ]);
    
        return $parser;
    }
    
    public function execute(Arguments $args, ConsoleIo $io): int
    {
        $name = $args->getArgument('name');
        if ($args->getOption('yell')) {
            $name = mb_strtoupper($name);
        }
        $io->out("Hello {$name}.");
    
        return static::CODE_SUCCESS;
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  

See the [Option Parsers](https://book.cakephp.org/6.x/console-commands/option-parsers.html)
 section for more information.

Creating Output [​](https://book.cakephp.org/6.x/console-commands/commands.html#creating-output)

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

Commands are provided a `ConsoleIo` instance when executed. This object allows you to interact with `Cake\Console\ConsoleIo::out()` and `Cake\Console\ConsoleIo::err()` to emit on `stdout`, and `stderr`. Files can be created with overwrite confirmation with `Cake\Console\ConsoleIo::createFile()`. :ref:\`command-helpers provide 'macros' for output generation. See the [Command Input/Output](https://book.cakephp.org/6.x/console-commands/input-output.html)
 section for more information.

Using Models in Commands [​](https://book.cakephp.org/6.x/console-commands/commands.html#using-models-in-commands)

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

You'll often need access to your application's business logic in console commands. You can load models in commands, just as you would in a controller using `$this->fetchTable()` since command use the `LocatorAwareTrait`:

    <?php
    declare(strict_types=1);
    
    namespace App\Command;
    
    use Cake\Command\Command;
    use Cake\Console\Arguments;
    use Cake\Console\ConsoleIo;
    use Cake\Console\ConsoleOptionParser;
    
    class UserCommand extends Command
    {
        // Define the default table. This allows you to use `fetchTable()` without any argument.
        protected $defaultTable = 'Users';
    
        protected function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
        {
            $parser
                ->addArgument('name', [\
                    'help' => 'What is your name'\
                ]);
    
            return $parser;
        }
    
        public function execute(Arguments $args, ConsoleIo $io): int
        {
            $name = $args->getArgument('name');
            $user = $this->fetchTable()->findByUsername($name)->first();
    
            $io->out(print_r($user, true));
    
            return static::CODE_SUCCESS;
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  

The above command, will fetch a user by username and display the information stored in the database.

Exit Codes and Stopping Execution [​](https://book.cakephp.org/6.x/console-commands/commands.html#exit-codes-and-stopping-execution)

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

When your commands hit an unrecoverable error you can use the `abort()` method to terminate execution:

    // ...
    public function execute(Arguments $args, ConsoleIo $io): int
    {
        $name = $args->getArgument('name');
        if (strlen($name) < 5) {
            // Halt execution, output to stderr, and set exit code to 1
            $io->error('Name must be at least 4 characters long.');
            $this->abort();
        }
    
        return static::CODE_SUCCESS;
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

You can also use `abort()` on the `$io` object to emit a message and code:

    public function execute(Arguments $args, ConsoleIo $io): int
    {
        $name = $args->getArgument('name');
        if (strlen($name) < 5) {
            // Halt execution, output to stderr, and set exit code to 99
            $io->abort('Name must be at least 4 characters long.', 99);
        }
    
        return static::CODE_SUCCESS;
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  

You can pass any desired exit code into `abort()`.

TIP

Avoid exit codes 64 - 78, as they have specific meanings described by `sysexits.h`. Avoid exit codes above 127, as these are used to indicate process exit by signal, such as SIGKILL or SIGSEGV.

You can read more about conventional exit codes in the sysexit manual page on most Unix systems (`man sysexits`), or the `System Error Codes` help page in Windows.

Calling other Commands [​](https://book.cakephp.org/6.x/console-commands/commands.html#calling-other-commands)

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

You may need to call other commands from your command. You can use `executeCommand` to do that:

    // You can pass an array of CLI options and arguments.
    $this->executeCommand(OtherCommand::class, ['--verbose', 'deploy']);
    
    // Can pass an instance of the command if it has constructor args
    $command = new OtherCommand($otherArgs);
    $this->executeCommand($command, ['--verbose', 'deploy']);

1  
2  
3  
4  
5  
6  

NOTE

When calling `executeCommand()` in a loop, it is recommended to pass in the parent command's `ConsoleIo` instance as the optional 3rd argument to avoid a potential "open files" limit that could occur in some environments.

Setting Command Description [​](https://book.cakephp.org/6.x/console-commands/commands.html#setting-command-description)

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

You may want to set a command description via:

    class UserCommand extends Command
    {
        public static function getDescription(): string
        {
            return 'My custom description';
        }
    }

1  
2  
3  
4  
5  
6  
7  

This will show your description in the Cake CLI:

    bin/cake
    
    App:
      - user
      └─── My custom description

1  
2  
3  
4  
5  

As well as in the help section of your command:

    cake user --help
    My custom description
    
    Usage:
    cake user [-h] [-q] [-v]

1  
2  
3  
4  
5  

Grouping Commands [​](https://book.cakephp.org/6.x/console-commands/commands.html#grouping-commands)

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

By default in the help output CakePHP will group commands into core, app, and plugin groups. You can customize the grouping of commands by implementing `getGroup()`:

    class CleanupCommand extends Command
    {
        public static function getGroup(): string
        {
            return 'maintenance';
        }
    }

1  
2  
3  
4  
5  
6  
7  

Added in version 5.3.0

Custom grouping support was added.

Testing Commands [​](https://book.cakephp.org/6.x/console-commands/commands.html#testing-commands)

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

To make testing console applications easier, CakePHP comes with a `ConsoleIntegrationTestTrait` trait that can be used to test console applications and assert against their results.

To get started testing your console application, create a test case that uses the `Cake\TestSuite\ConsoleIntegrationTestTrait` trait. This trait contains a method `exec()` that is used to execute your command. You can pass the same string you would use in the CLI to this method.

Let's start with a very simple command, located in **src/Command/UpdateTableCommand.php**:

    namespace App\Command;
    
    use Cake\Command\Command;
    use Cake\Console\Arguments;
    use Cake\Console\ConsoleIo;
    use Cake\Console\ConsoleOptionParser;
    
    class UpdateTableCommand extends Command
    {
        protected function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
        {
            $parser->setDescription('My cool console app');
    
            return $parser;
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  

To write an integration test for this command, we would create a test case in **tests/TestCase/Command/UpdateTableTest.php** that uses the `Cake\TestSuite\ConsoleIntegrationTestTrait` trait. This command doesn't do much at the moment, but let's just test that our command's description is displayed in `stdout`:

    namespace App\Test\TestCase\Command;
    
    use Cake\TestSuite\ConsoleIntegrationTestTrait;
    use Cake\TestSuite\TestCase;
    
    class UpdateTableCommandTest extends TestCase
    {
        use ConsoleIntegrationTestTrait;
    
        public function testDescriptionOutput()
        {
            $this->exec('update_table --help');
            $this->assertOutputContains('My cool console app');
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

Our test passes! While this is very trivial example, it shows that creating an integration test case for console applications can follow command line conventions. Let's continue by adding more logic to our command:

    namespace App\Command;
    
    use Cake\Command\Command;
    use Cake\Console\Arguments;
    use Cake\Console\ConsoleIo;
    use Cake\Console\ConsoleOptionParser;
    use Cake\I18n\DateTime;
    
    class UpdateTableCommand extends Command
    {
        protected function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
        {
            $parser
                ->setDescription('My cool console app')
                ->addArgument('table', [\
                    'help' => 'Table to update',\
                    'required' => true\
                ]);
    
            return $parser;
        }
    
        public function execute(Arguments $args, ConsoleIo $io): int
        {
            $table = $args->getArgument('table');
            $this->fetchTable($table)->updateQuery()
                ->set([\
                    'modified' => new DateTime()\
                ])
                ->execute();
    
            return static::CODE_SUCCESS;
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  

This is a more complete command that has required options and relevant logic. Modify your test case to the following snippet of code:

    namespace Cake\Test\TestCase\Command;
    
    use Cake\Command\Command;
    use Cake\I18n\DateTime;
    use Cake\TestSuite\ConsoleIntegrationTestTrait;
    use Cake\TestSuite\TestCase;
    
    class UpdateTableCommandTest extends TestCase
    {
        use ConsoleIntegrationTestTrait;
    
        protected $fixtures = [\
            // assumes you have a UsersFixture\
            'app.Users',\
        ];
    
        public function testDescriptionOutput()
        {
            $this->exec('update_table --help');
            $this->assertOutputContains('My cool console app');
        }
    
        public function testUpdateModified()
        {
            $now = new DateTime('2017-01-01 00:00:00');
            DateTime::setTestNow($now);
    
            $this->loadFixtures('Users');
    
            $this->exec('update_table Users');
            $this->assertExitCode(Command::CODE_SUCCESS);
    
            $user = $this->getTableLocator()->get('Users')->get(1);
            $this->assertSame($user->modified->timestamp, $now->timestamp);
    
            DateTime::setTestNow(null);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  

As you can see from the `testUpdateModified` method, we are testing that our command updates the table that we are passing as the first argument. First, we assert that the command exited with the proper status code, `0`. Then we check that our command did its work, that is, updated the table we provided and set the `modified` column to the current time.

Remember, `exec()` will take the same string you type into your CLI, so you can include options and arguments in your command string.

### Testing Interactive Commands [​](https://book.cakephp.org/6.x/console-commands/commands.html#testing-interactive-commands)

Consoles are often interactive. Testing interactive commands with the `Cake\TestSuite\ConsoleIntegrationTestTrait` trait only requires passing the inputs you expect as the second parameter of `exec()`. They should be included as an array in the order that you expect them.

Continuing with our example command, let's add an interactive confirmation. Update the command class to the following:

    namespace App\Command;
    
    use Cake\Command\Command;
    use Cake\Console\Arguments;
    use Cake\Console\ConsoleIo;
    use Cake\Console\ConsoleOptionParser;
    use Cake\I18n\DateTime;
    
    class UpdateTableCommand extends Command
    {
        protected function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
        {
            $parser
                ->setDescription('My cool console app')
                ->addArgument('table', [\
                    'help' => 'Table to update',\
                    'required' => true\
                ]);
    
            return $parser;
        }
    
        public function execute(Arguments $args, ConsoleIo $io): int
        {
            $table = $args->getArgument('table');
            if ($io->ask('Are you sure?', 'n', ['y', 'n']) !== 'y') {
                $io->error('You need to be sure.');
                $this->abort();
            }
            $this->fetchTable($table)->updateQuery()
                ->set([\
                    'modified' => new DateTime()\
                ])
                ->execute();
    
            return static::CODE_SUCCESS;
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  

Now that we have an interactive command, we can add a test case that tests that we receive the proper response, and one that tests that we receive an incorrect response. Remove the `testUpdateModified` method and, add the following methods to **tests/TestCase/Command/UpdateTableCommandTest.php**:

    public function testUpdateModifiedSure()
    {
        $now = new DateTime('2017-01-01 00:00:00');
        DateTime::setTestNow($now);
    
        $this->loadFixtures('Users');
    
        $this->exec('update_table Users', ['y']);
        $this->assertExitCode(Command::CODE_SUCCESS);
    
        $user = $this->getTableLocator()->get('Users')->get(1);
        $this->assertSame($user->modified->timestamp, $now->timestamp);
    
        DateTime::setTestNow(null);
    }
    
    public function testUpdateModifiedUnsure()
    {
        $user = $this->getTableLocator()->get('Users')->get(1);
        $original = $user->modified->timestamp;
    
        $this->exec('my_console best_framework', ['n']);
        $this->assertExitCode(Command::CODE_ERROR);
        $this->assertErrorContains('You need to be sure.');
    
        $user = $this->getTableLocator()->get('Users')->get(1);
        $this->assertSame($original, $user->timestamp);
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  

In the first test case, we confirm the question, and records are updated. In the second test we don't confirm and records are not updated, and we can check that our error message was written to `stderr`.

### Assertion methods [​](https://book.cakephp.org/6.x/console-commands/commands.html#assertion-methods)

The `Cake\TestSuite\ConsoleIntegrationTestTrait` trait provides a number of assertion methods that make help assert against console output:

    // assert that the command exited as success
    $this->assertExitSuccess();
    
    // assert that the command exited as an error
    $this->assertExitError();
    
    // assert that the command exited with the expected code
    $this->assertExitCode($expected);
    
    // assert that stdout contains a string
    $this->assertOutputContains($expected);
    
    // assert that stderr contains a string
    $this->assertErrorContains($expected);
    
    // assert that stdout matches a regular expression
    $this->assertOutputRegExp($expected);
    
    // assert that stderr matches a regular expression
    $this->assertErrorRegExp($expected);

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  

### Debug Helpers [​](https://book.cakephp.org/6.x/console-commands/commands.html#debug-helpers)

You can use `debugOutput()` to output the exit code, stdout and stderr of the last run command:

    $this->exec('update_table Users');
    $this->assertExitCode(Command::CODE_SUCCESS);
    $this->debugOutput();

1  
2  
3  

Added in version 4.2.0

The `debugOutput()` method was added.

Lifecycle Callbacks [​](https://book.cakephp.org/6.x/console-commands/commands.html#lifecycle-callbacks)

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

Like Controllers, Commands offer lifecycle events that allow you to observe the framework calling your application code. Commands have:

*   `Command.beforeExecute` is called before a command's `execute()` method. The event is passed the `Arguments` parameter as `args` and the `ConsoleIo` parameter as `io`. This event cannot be stopped or have its result replaced.
*   `Command.afterExecute` is called after a command's `execute()` method is complete. The event contains `Arguments` as `args`, `ConsoleIo` as `io` and the command result as `result`. This event cannot be stopped or have its result replaced.

Added in version 5.3.0

The `beforeExecute()` and `afterExecute()` hook methods were added.

### beforeExecute() [​](https://book.cakephp.org/6.x/console-commands/commands.html#beforeexecute)

`method` Cake\\Console\\Command::**beforeExecute**(EventInterface $event, Arguments $args, ConsoleIo $io): void

Called before the `execute()` method runs. Useful for initialization and validation:

    use Cake\Event\EventInterface;
    
    class MyCommand extends Command
    {
        public function beforeExecute(EventInterface $event, Arguments $args, ConsoleIo $io): void
        {
            parent::beforeExecute($event);
    
            $io->out('Starting command execution');
    
            if (!$this->checkPrerequisites()) {
                $io->abort('Prerequisites not met');
            }
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  

### afterExecute() [​](https://book.cakephp.org/6.x/console-commands/commands.html#afterexecute)

`method` Cake\\Console\\Command::**afterExecute**(EventInterface $event, Arguments $args, ConsoleIo $io): void

Called after the `execute()` method completes. Useful for cleanup and logging:

    public function afterExecute(EventInterface $event, Arguments $args, ConsoleIo $io, mixed $result): void
    {
        parent::afterExecute($event);
    
        $this->cleanup();
        $io->out('Command execution completed');
    }

1  
2  
3  
4  
5  
6  
7

---

# Sessions | CakePHP

[Skip to content](https://book.cakephp.org/6.x/development/sessions.html#VPContent)

Return to top

Sessions [​](https://book.cakephp.org/6.x/development/sessions.html#sessions)

==============================================================================

CakePHP provides a wrapper and suite of utility features on top of PHP's native `session` extension. Sessions allow you to identify unique users across requests and store persistent data for specific users. Unlike Cookies, session data is not available on the client side. Usage of `$_SESSION` is generally avoided in CakePHP, and instead usage of the Session classes is preferred.

Session Configuration [​](https://book.cakephp.org/6.x/development/sessions.html#session-configuration)

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

Session configuration is generally defined in **/config/app.php**. The available options are:

*   `Session.timeout` - The number of _minutes_ a session can remain 'idle'. If no request is received for `timeout` minutes, CakePHP's session handler will expire the session. You can set this option to `0` to disable server side idle timeouts.
*   `Session.defaults` - Allows you to use the built-in default session configurations as a base for your session configuration. See below for the built-in defaults.
*   `Session.handler` - Allows you to define a custom session handler. The core database and cache session handlers use this. See below for additional information on Session handlers.
*   `Session.ini` - Allows you to set additional session ini settings for your config. This combined with `Session.handler` replace the custom session handling features of previous versions
*   `Session.cookie` - The name of the cookie to use. Defaults to value set for `session.name` php.ini config.
*   `Session.cookiePath` - The url path for which session cookie is set. Maps to the `session.cookie_path` php.ini config. Defaults to base path of app.

CakePHP's defaults `session.cookie_secure` to `true`, when your application is on an SSL protocol. If your application serves from both SSL and non-SSL protocols, then you might have problems with sessions being lost. If you need access to the session on both SSL and non-SSL domains you will want to disable this:

    Configure::write('Session', [\
        'defaults' => 'php',\
        'ini' => [\
            'session.cookie_secure' => false\
        ]\
    ]);

1  
2  
3  
4  
5  
6  

CakePHP also sets the [SameSite](https://owasp.org/www-community/SameSite)
 attribute to `Lax` by default for session cookies, which helps protect against CSRF attacks. You can change the default value by setting `session.cookie_samesite` php.ini config:

    Configure::write('Session', [\
        'defaults' => 'php',\
        'ini' => [\
            'session.cookie_samesite' => 'Strict',\
        ],\
    ]);

1  
2  
3  
4  
5  
6  

The session cookie path defaults to app's base path. To change this you can use the `session.cookie_path` ini value. For example if you want your session to persist across all subdomains you can do:

    Configure::write('Session', [\
        'defaults' => 'php',\
        'ini' => [\
            'session.cookie_path' => '/',\
            'session.cookie_domain' => '.yourdomain.com',\
        ],\
    ]);

1  
2  
3  
4  
5  
6  
7  

By default PHP sets the session cookie to expire as soon as the browser is closed, regardless of the configured `Session.timeout` value. The cookie timeout is controlled by the `session.cookie_lifetime` ini value and can be configured using:

    Configure::write('Session', [\
        'defaults' => 'php',\
        'ini' => [\
            // Invalidate the cookie after 30 minutes\
            'session.cookie_lifetime' => 1800\
        ]\
    ]);

1  
2  
3  
4  
5  
6  
7  

The difference between `Session.timeout` and the `session.cookie_lifetime` value is that the latter relies on the client telling the truth about the cookie. If you require stricter timeout checking, without relying on what the client reports, you should use `Session.timeout`.

Please note that `Session.timeout` corresponds to the total time of inactivity for a user (i.e. the time without visiting any page where the session is used), and does not limit the total amount of minutes a user can stay active on the site.

Built-in Session Handlers & Configuration [​](https://book.cakephp.org/6.x/development/sessions.html#built-in-session-handlers-configuration)

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

CakePHP comes with several built-in session configurations. You can either use these as the basis for your session configuration, or you can create a fully custom solution. To use defaults, simply set the 'defaults' key to the name of the default you want to use. You can then override any sub setting by declaring it in your Session config:

    Configure::write('Session', [\
        'defaults' => 'php'\
    ]);

1  
2  
3  

The above will use the built-in 'php' session configuration. You could augment part or all of it by doing the following:

    Configure::write('Session', [\
        'defaults' => 'php',\
        'cookie' => 'my_app',\
        'timeout' => 4320 // 3 days\
    ]);

1  
2  
3  
4  
5  

The above overrides the timeout and cookie name for the 'php' session configuration. The built-in configurations are:

*   `php` - Saves sessions with the standard settings in your php.ini file.
*   `cake` - Saves sessions as files inside `tmp/sessions/`. This is a good option when on hosts that don't allow you to write outside your own home dir.
*   `database` - Use the built-in database sessions. See below for more information.
*   `cache` - Use the built-in cache sessions. See below for more information.

### Session Handlers [​](https://book.cakephp.org/6.x/development/sessions.html#session-handlers)

Session handlers can also be defined in the session config array. By defining the 'handler.engine' config key, you can name the class name, or provide a handler instance. The class/object must implement the native PHP `SessionHandlerInterface`. Implementing this interface will allow `Session` to automatically map the methods for the handler. Both the core Cache and Database session handlers use this method for saving sessions. Additional settings for the handler should be placed inside the handler array. You can then read those values out from inside your handler:

    'Session' => [\
        'handler' => [\
            'engine' => 'DatabaseSession',\
            'model' => 'CustomSessions',\
        ],\
    ]

1  
2  
3  
4  
5  
6  

The above shows how you could setup the Database session handler with an application model. When using class names as your handler.engine, CakePHP will expect to find your class in the `Http\Session` namespace. For example, if you had an `AppSessionHandler` class, the file should be **src/Http/Session/AppSessionHandler.php**, and the class name should be `App\Http\Session\AppSessionHandler`. You can also use session handlers from inside plugins. By setting the engine to `MyPlugin.PluginSessionHandler`.

### Database Sessions [​](https://book.cakephp.org/6.x/development/sessions.html#database-sessions)

If you need to use a database to store your session data, configure as follows:

    'Session' => [\
        'defaults' => 'database'\
    ]

1  
2  
3  

This configuration requires a database table, having this schema:

    CREATE TABLE `sessions` (
      `id` char(40) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
      `created` datetime DEFAULT CURRENT_TIMESTAMP, -- Optional
      `modified` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, -- Optional
      `data` blob DEFAULT NULL, -- for PostgreSQL use bytea instead of blob
      `expires` int(10) unsigned DEFAULT NULL,
      PRIMARY KEY (`id`)
    ) ENGINE=InnoDB DEFAULT CHARSET=utf8;

1  
2  
3  
4  
5  
6  
7  
8  

You can find a copy of the schema for the sessions table in the [application skeleton](https://github.com/cakephp/app)
 in **config/schema/sessions.sql**.

You can also use your own `Table` class to handle the saving of the sessions:

    'Session' => [\
        'defaults' => 'database',\
        'handler' => [\
            'engine' => 'DatabaseSession',\
            'model' => 'CustomSessions',\
        ],\
    ]

1  
2  
3  
4  
5  
6  
7  

The above will tell Session to use the built-in 'database' defaults, and specify that a Table called `CustomSessions` will be the delegate for saving session information to the database.

### Cache Sessions [​](https://book.cakephp.org/6.x/development/sessions.html#cache-sessions)

The Cache class can be used to store sessions as well. This allows you to store sessions in a cache like APCu, or Memcached. There are some caveats to using cache sessions, in that if you exhaust the cache space, sessions will start to expire as records are evicted.

To use Cache based sessions you can configure you Session config like:

    Configure::write('Session', [\
        'defaults' => 'cache',\
        'handler' => [\
            'config' => 'session',\
        ],\
    ]);

1  
2  
3  
4  
5  
6  

This will configure Session to use the `CacheSession` class as the delegate for saving the sessions. You can use the 'config' key which cache configuration to use. The default cache configuration is `'default'`.

### Session Locking [​](https://book.cakephp.org/6.x/development/sessions.html#session-locking)

The app skeleton comes preconfigured with a session config like this:

    'Session' => [\
        'defaults' => 'php',\
    ],

1  
2  
3  

This means CakePHP will handle sessions via what is configured in your `php.ini`. In most cases this will be the default configuration so PHP will save any newly created session as a file in e.g. `/var/lib/php/session`

But this also means any computationally heavy task like querying a large dataset combined with an active session will **lock that session file** - therefore blocking users to e.g. open a second tab of your app to do something else in the meantime.

To prevent this behavior you will have to change the way how sessions are being handled in CakePHP by using a different session handler like [Sessions Cache Sessions](https://book.cakephp.org/6.x/development/sessions.html#sessions-cache-sessions)
 combined with the [Redis Engine](https://book.cakephp.org/6.x/core-libraries/caching.html#caching-redisengine)
 or another cache engine.

TIP

If you want to read more about Session Locking see [here](https://ma.ttias.be/php-session-locking-prevent-sessions-blocking-in-requests/)

Setting ini directives [​](https://book.cakephp.org/6.x/development/sessions.html#setting-ini-directives)

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

The built-in defaults attempt to provide a common base for session configuration. You may need to tweak specific ini flags as well. CakePHP exposes the ability to customize the ini settings for both default configurations, as well as custom ones. The `ini` key in the session settings, allows you to specify individual configuration values. For example you can use it to control settings like `session.gc_divisor`:

    Configure::write('Session', [\
        'defaults' => 'php',\
        'ini' => [\
            'session.cookie_name' => 'MyCookie',\
            'session.cookie_lifetime' => 1800, // Valid for 30 minutes\
            'session.gc_divisor' => 1000,\
            'session.cookie_httponly' => true\
        ]\
    ]);

1  
2  
3  
4  
5  
6  
7  
8  
9  

Creating a Custom Session Handler [​](https://book.cakephp.org/6.x/development/sessions.html#creating-a-custom-session-handler)

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

Creating a custom session handler is straightforward in CakePHP. In this example we'll create a session handler that stores sessions both in the Cache (APC) and the database. This gives us the best of fast IO of APC, without having to worry about sessions evaporating when the cache fills up.

First we'll need to create our custom class and put it in **src/Http/Session/ComboSession.php**. The class should look something like:

    namespace App\Http\Session;
    
    use Cake\Cache\Cache;
    use Cake\Core\Configure;
    use Cake\Http\Session\DatabaseSession;
    
    class ComboSession extends DatabaseSession
    {
        protected $cacheKey;
    
        public function __construct()
        {
            $this->cacheKey = Configure::read('Session.handler.cache');
            parent::__construct();
        }
    
        // Read data from the session.
        public function read($id): string
        {
            $result = Cache::read($id, $this->cacheKey);
            if ($result) {
                return $result;
            }
    
            return parent::read($id);
        }
    
        // Write data into the session.
        public function write($id, $data): bool
        {
            Cache::write($id, $data, $this->cacheKey);
    
            return parent::write($id, $data);
        }
    
        // Destroy a session.
        public function destroy($id): bool
        {
            Cache::delete($id, $this->cacheKey);
    
            return parent::destroy($id);
        }
    
        // Removes expired sessions.
        public function gc($expires = null): bool
        {
            return parent::gc($expires);
        }
    }

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  
19  
20  
21  
22  
23  
24  
25  
26  
27  
28  
29  
30  
31  
32  
33  
34  
35  
36  
37  
38  
39  
40  
41  
42  
43  
44  
45  
46  
47  
48  
49  

Our class extends the built-in `DatabaseSession` so we don't have to duplicate all of its logic and behavior. We wrap each operation with a `Cake\Cache\Cache` operation. This lets us fetch sessions from the fast cache, and not have to worry about what happens when we fill the cache. In **config/app.php** make the session block look like:

    'Session' => [\
        'defaults' => 'database',\
        'handler' => [\
            'engine' => 'ComboSession',\
            'model' => 'Session',\
            'cache' => 'apc',\
        ],\
    ],
    // Make sure to add a apc cache config
    'Cache' => [\
        'apc' => ['engine' => 'Apc']\
    ]

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

Now our application will start using our custom session handler for reading and writing session data.

`class` **Session**

Accessing the Session Object [​](https://book.cakephp.org/6.x/development/sessions.html#accessing-the-session-object)

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

You can access the session data any place you have access to a request object. This means the session is accessible from:

*   Controllers
*   Views
*   Helpers
*   Cells
*   Components

A basic example of session usage in controllers, views and cells would be:

    $name = $this->request->getSession()->read('User.name');
    
    // If you are accessing the session multiple times,
    // you will probably want a local variable.
    $session = $this->request->getSession();
    $name = $session->read('User.name');

1  
2  
3  
4  
5  
6  

In helpers, use `$this->getView()->getRequest()` to get the request object; In components, use `$this->getController()->getRequest()`.

Reading & Writing Session Data [​](https://book.cakephp.org/6.x/development/sessions.html#reading-writing-session-data)

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

`method` Session::**read**($key, $default = null): mixed

You can read values from the session using `Hash::extract()` compatible syntax:

    $session->read('Config.language', 'en');

1  

`method` Session::**readOrFail**($key): mixed

The same as convenience wrapper around non-nullable return value:

    $session->readOrFail('Config.language');

1  

This is useful, when you know this key has to be set and you don't want to have to check for the existence in code itself.

`method` Session::**write**($key, $value): void

`$key` should be the dot separated path you wish to write `$value` to:

    $session->write('Config.language', 'en');

1  

You may also specify one or multiple hashes like so:

    $session->write([\
      'Config.theme' => 'blue',\
      'Config.language' => 'en',\
    ]);

1  
2  
3  
4  

`method` Session::**delete**($key): void

When you need to delete data from the session, you can use `delete()`:

    $session->delete('Some.value');

1  

[Session::consume($key)](session::consume($key))

When you need to read and delete data from the session, you can use `consume()`:

    $session->consume('Some.value');

1  

`method` Session::**check**($key): bool

If you want to see if data exists in the session, you can use `check()`:

    if ($session->check('Config.language')) {
        // Config.language exists and is not null.
    }

1  
2  
3  

Destroying the Session [​](https://book.cakephp.org/6.x/development/sessions.html#destroying-the-session)

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

`method` Session::**destroy**(): void

Destroying the session is useful when users log out. To destroy a session, use the `destroy()` method:

    $session->destroy();

1  

Destroying a session will remove all serverside data in the session, but will **not** remove the session cookie.

Rotating Session Identifiers [​](https://book.cakephp.org/6.x/development/sessions.html#rotating-session-identifiers)

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

`method` Session::**renew**(): void

While the `Authentication Plugin` automatically renews the session id when users login and logout, you may need to rotate the session id's manually. To do this use the `renew()` method:

    $session->renew();

1  

Flash Messages [​](https://book.cakephp.org/6.x/development/sessions.html#flash-messages)

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

Flash messages are small messages displayed to end users once. They are often used to present error messages, or confirm that actions took place successfully.

To set and display flash messages you should use [FlashComponent](https://book.cakephp.org/6.x/controllers/components/flash.html)
 and [FlashHelper](https://book.cakephp.org/6.x/views/helpers/flash.html)

---

# Configuration | CakePHP

[Skip to content](https://book.cakephp.org/6.x/development/configuration.html#VPContent)

Return to top

Configuration [​](https://book.cakephp.org/6.x/development/configuration.html#configuration)

=============================================================================================

While conventions remove the need to configure all of CakePHP, you'll still need to configure a few things like your database credentials.

Additionally, there are optional configuration options that allow you to swap out default values & implementations with ones tailored to your application.

app.php, app\_local.example.php

configuration

Configuring your Application [​](https://book.cakephp.org/6.x/development/configuration.html#configuring-your-application)

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

Configuration is generally stored in either PHP or INI files, and loaded during the application bootstrap. CakePHP comes with one configuration file by default, but if required you can add additional configuration files and load them in your application's bootstrap code. `Cake\Core\Configure` is used for global configuration, and classes like `Cache` provide `setConfig()` methods to make configuration simple and transparent.

The application skeleton features a **config/app.php** file which should contain configuration that doesn't vary across the various environments your application is deployed in. The **config/app\_local.php** file should contain the configuration data that varies between environments and should be managed by configuration management, or your deployment tooling. Both of these files reference environment variables through the `env()` function that enables configuration values to set through the server environment.

### Loading Additional Configuration Files [​](https://book.cakephp.org/6.x/development/configuration.html#loading-additional-configuration-files)

If your application has many configuration options it can be helpful to split configuration into multiple files. After creating each of the files in your **config/** directory you can load them in **bootstrap.php**:

    use Cake\Core\Configure;
    use Cake\Core\Configure\Engine\PhpConfig;
    
    Configure::setConfig('default', new PhpConfig());
    Configure::load('app', 'default', false);
    Configure::load('other_config', 'default');

1  
2  
3  
4  
5  
6  

Environment Variables [​](https://book.cakephp.org/6.x/development/configuration.html#environment-variables)

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

Many modern cloud providers, like Heroku, let you define environment variables for configuration data. You can configure your CakePHP through environment variables in the [12factor app style](https://12factor.net/)
. Environment variables allow your application to require less state making your application easier to manage when it is deployed across a number of environments.

As you can see in your **app.php**, the `env()` function is used to read configuration from the environment, and build the application configuration. CakePHP uses `DSN` strings for databases, logs, email transports and cache configurations allowing you to easily vary these libraries in each environment.

For local development, CakePHP leverages [dotenv](https://github.com/josegonzalez/php-dotenv)
 to make local development automatically reload environment variables. Use composer to require this library and then there is a block of code in `bootstrap.php` that needs to be uncommented to harness it.

You will see a `config/.env.example` in your application. By copying this file into `config/.env` and customizing the values you can configure your application.

You should avoid committing the `config/.env` file to your repository and instead use the `config/.env.example` as a template with placeholder values so everyone on your team knows what environment variables are in use and what should go in each one.

Once your environment variables have been set, you can use `env()` to read data from the environment:

    $debug = env('APP_DEBUG', false);

1  

The second value passed to the env function is the default value. This value will be used if no environment variable exists for the given key.

### General Configuration [​](https://book.cakephp.org/6.x/development/configuration.html#general-configuration)

Below is a description of the variables and how they affect your CakePHP application.

debug Changes CakePHP debugging output. `false` = Production mode. No error messages, errors, or warnings shown. `true` = Errors and warnings shown.

App.namespace The namespace to find app classes under.

NOTE

When changing the namespace in your configuration, you will also need to update your **composer.json** file to use this namespace as well. Additionally, create a new autoloader by running `php composer.phar dumpautoload`.

App.baseUrl Un-comment this definition if you **don’t** plan to use Apache’s mod\_rewrite with CakePHP. Don’t forget to remove your .htaccess files too.

App.base The base directory the app resides in. If `false` this will be auto detected. If not `false`, ensure your string starts with a / and does NOT end with a /. For example, /basedir is a valid App.base.

App.encoding Define what encoding your application uses. This encoding is used to generate the charset in the layout, and encode entities. It should match the encoding values specified for your database.

App.webroot The webroot directory.

App.wwwRoot The file path to webroot.

App.fullBaseUrl The fully qualified domain name (including protocol) to your application's root. This is used when generating absolute URLs. By default this value is generated using the `$_SERVER` environment. However, you should define it manually to optimize performance or if you are concerned about people manipulating the `Host` header. In a CLI context (from command) the fullBaseUrl cannot be read from $\_SERVER, as there is no webserver involved. You do need to specify it yourself if you do need to generate URLs from a shell (for example, when sending emails).

App.imageBaseUrl Web path to the public images directory under webroot. If you are using a `CDN` you should set this value to the CDN's location.

App.cssBaseUrl Web path to the public css directory under webroot. If you are using a `CDN` you should set this value to the CDN's location.

App.jsBaseUrl Web path to the public js directory under webroot. If you are using a `CDN` you should set this value to the CDN's location.

App.paths Configure paths for non class based resources. Supports the `plugins`, `templates`, `locales` subkeys, which allow the definition of paths for plugins, view templates and locale files respectively.

App.uploadedFilesAsObjects Defines whether uploaded files are being represented as objects (`true`), or arrays (`false`). This option is being treated as enabled by default. See the [File Uploads section](https://book.cakephp.org/6.x/controllers/request-response.html#request-file-uploads)
 in the Request & Response Objects chapter for more information.

Security.salt A random string used in hashing. This value is also used as the HMAC salt when doing symmetric encryption.

Asset.timestamp Appends a timestamp which is last modified time of the particular file at the end of asset files URLs (CSS, JavaScript, Image) when using proper helpers. Valid values:

*   (bool) `false` - Doesn't do anything (default)
*   (bool) `true` - Appends the timestamp when debug is `true`
*   (string) 'force' - Always appends the timestamp.

Asset.cacheTime Sets the asset cache time. This determines the http header `Cache-Control`'s `max-age`, and the http header's `Expire`'s time for assets. This can take anything that you version of PHP's [strtotime function](https://php.net/manual/en/function.strtotime.php)
 can take. The default is `+1 day`.

### Using a CDN [​](https://book.cakephp.org/6.x/development/configuration.html#using-a-cdn)

To use a CDN for loading your static assets, change `App.imageBaseUrl`, `App.cssBaseUrl`, `App.jsBaseUrl` to point the CDN URI, for example: `https://mycdn.example.com/` (note the trailing `/`).

All images, scripts and styles loaded via HtmlHelper will prepend the absolute CDN path, matching the same relative path used in the application. Please note there is a specific use case when using plugin based assets: plugins will not use the plugin's prefix when absolute `...BaseUrl` URI is used, for example By default:

*   `$this->Helper->assetUrl('TestPlugin.logo.png')` resolves to `test_plugin/logo.png`

If you set `App.imageBaseUrl` to `https://mycdn.example.com/`:

*   `$this->Helper->assetUrl('TestPlugin.logo.png')` resolves to `https://mycdn.example.com/logo.png`.

### Database Configuration [​](https://book.cakephp.org/6.x/development/configuration.html#database-configuration)

See the [Database Configuration](https://book.cakephp.org/6.x/orm/database-basics.html#database-configuration)
 for information on configuring your database connections.

### Caching Configuration [​](https://book.cakephp.org/6.x/development/configuration.html#caching-configuration)

See the [Caching Configuration](https://book.cakephp.org/6.x/core-libraries/caching.html#cache-configuration)
 for information on configuring caching in CakePHP.

### Error and Exception Handling Configuration [​](https://book.cakephp.org/6.x/development/configuration.html#error-and-exception-handling-configuration)

See the [Error and Exception Configuration](https://book.cakephp.org/6.x/development/errors.html#error-configuration)
 for information on configuring error and exception handlers.

### Logging Configuration [​](https://book.cakephp.org/6.x/development/configuration.html#logging-configuration)

See the [Log Configuration](https://book.cakephp.org/6.x/core-libraries/logging.html#log-configuration)
 for information on configuring logging in CakePHP.

### Email Configuration [​](https://book.cakephp.org/6.x/development/configuration.html#email-configuration)

See the [Email Configuration](https://book.cakephp.org/6.x/core-libraries/email.html#email-configuration)
 for information on configuring email presets in CakePHP.

### Session Configuration [​](https://book.cakephp.org/6.x/development/configuration.html#session-configuration)

See the [Session Configuration](https://book.cakephp.org/6.x/development/sessions.html#session-configuration)
 for information on configuring session handling in CakePHP.

### Routing configuration [​](https://book.cakephp.org/6.x/development/configuration.html#routing-configuration)

See the [Routes Configuration](https://book.cakephp.org/6.x/development/routing.html#routes-configuration)
 for more information on configuring routing and creating routes for your application.

Additional Class Paths [​](https://book.cakephp.org/6.x/development/configuration.html#additional-class-paths)

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

Additional class paths are setup through the autoloaders your application uses. When using `composer` to generate your autoloader, you could do the following, to provide fallback paths for controllers in your application:

    "autoload": {
        "psr-4": {
            "App\\Controller\\": "/path/to/directory/with/controller/folders/",
            "App\\": "src/"
        }
    }

1  
2  
3  
4  
5  
6  

The above would setup paths for both the `App` and `App\Controller` namespace. The first key will be searched, and if that path does not contain the class/file the second key will be searched. You can also map a single namespace to multiple directories with the following:

    "autoload": {
        "psr-4": {
            "App\\": ["src/", "/path/to/directory/"]
        }
    }

1  
2  
3  
4  
5  

### Plugin, View Template and Locale Paths [​](https://book.cakephp.org/6.x/development/configuration.html#plugin-view-template-and-locale-paths)

Since plugins, view templates and locales are not classes, they cannot have an autoloader configured. CakePHP provides three Configure variables to setup additional paths for these resources. In your **config/app.php** you can set these variables:

    return [\
        // More configuration\
        'App' => [\
            'paths' => [\
                'plugins' => [\
                    ROOT . DS . 'plugins' . DS,\
                    '/path/to/other/plugins/',\
                ],\
                'templates' => [\
                    ROOT . DS . 'templates' . DS,\
                    ROOT . DS . 'templates2' . DS,\
                ],\
                'locales' => [\
                    ROOT . DS . 'resources' . DS . 'locales' . DS,\
                ],\
            ],\
        ],\
    ];

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  
18  

Paths should end with a directory separator, or they will not work properly.

Inflection Configuration [​](https://book.cakephp.org/6.x/development/configuration.html#inflection-configuration)

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

See the [Inflection Configuration](https://book.cakephp.org/6.x/core-libraries/inflector.html#inflection-configuration)
 docs for more information.

Configure Class [​](https://book.cakephp.org/6.x/development/configuration.html#configure-class)

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

`class` Cake\\Core\\**Configure**

CakePHP's Configure class can be used to store and retrieve application or runtime specific values. Be careful, this class allows you to store anything in it, then use it in any other part of your code: a sure temptation to break the MVC pattern CakePHP was designed for. The main goal of Configure class is to keep centralized variables that can be shared between many objects. Remember to try to live by "convention over configuration" and you won't end up breaking the MVC structure CakePHP provides.

### Writing Configuration data [​](https://book.cakephp.org/6.x/development/configuration.html#writing-configuration-data)

`static` Cake\\Core\\Configure::**write**(array|string $config, mixed $value = null): void

Use `write()` to store data in the application's configuration:

    Configure::write('Company.name', 'Pizza, Inc.');
    Configure::write('Company.slogan', 'Pizza for your body and soul');

1  
2  

NOTE

The `dot notation` used in the `$key` parameter can be used to organize your configuration settings into logical groups.

The above example could also be written in a single call:

    Configure::write('Company', [\
        'name' => 'Pizza, Inc.',\
        'slogan' => 'Pizza for your body and soul'\
    ]);

1  
2  
3  
4  

You can use `Configure::write('debug', $bool)` to switch between debug and production modes on the fly.

NOTE

Any configuration changes done using `Configure::write()` are in memory and will not persist across requests.

### Reading Configuration Data [​](https://book.cakephp.org/6.x/development/configuration.html#reading-configuration-data)

`static` Cake\\Core\\Configure::**read**(?string $var = null, mixed $default = null): mixed

Used to read configuration data from the application. If a key is supplied, the data is returned. Using our examples from write() above, we can read that data back:

    // Returns 'Pizza Inc.'
    Configure::read('Company.name');
    
    // Returns 'Pizza for your body and soul'
    Configure::read('Company.slogan');
    
    Configure::read('Company');
    // Returns:
    ['name' => 'Pizza, Inc.', 'slogan' => 'Pizza for your body and soul'];
    
    // Returns 'fallback' as Company.nope is undefined.
    Configure::read('Company.nope', 'fallback');

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  

If `$key` is left null, all values in Configure will be returned.

`static` Cake\\Core\\Configure::**readOrFail**(string $var): mixed

Reads configuration data just like `Cake\Core\Configure::read()` but expects to find a key/value pair. In case the requested pair does not exist, a `RuntimeException` will be thrown:

    Configure::readOrFail('Company.name');    // Yields: 'Pizza, Inc.'
    Configure::readOrFail('Company.geolocation');  // Will throw an exception
    
    Configure::readOrFail('Company');
    
    // Yields:
    ['name' => 'Pizza, Inc.', 'slogan' => 'Pizza for your body and soul'];

1  
2  
3  
4  
5  
6  
7  

### Checking to see if Configuration Data is Defined [​](https://book.cakephp.org/6.x/development/configuration.html#checking-to-see-if-configuration-data-is-defined)

`static` Cake\\Core\\Configure::**check**(string $var): bool

Used to check if a key/path exists and has non-null value:

    $exists = Configure::check('Company.name');

1  

### Deleting Configuration Data [​](https://book.cakephp.org/6.x/development/configuration.html#deleting-configuration-data)

`static` Cake\\Core\\Configure::**delete**(string $var): void

Used to delete information from the application's configuration:

    Configure::delete('Company.name');

1  

### Reading & Deleting Configuration Data [​](https://book.cakephp.org/6.x/development/configuration.html#reading-deleting-configuration-data)

`static` Cake\\Core\\Configure::**consume**(string $var): mixed

Read and delete a key from Configure. This is useful when you want to combine reading and deleting values in a single operation.

`static` Cake\\Core\\Configure::**consumeOrFail**(string $var): mixed

Consumes configuration data just like `Cake\Core\Configure::consume()` but expects to find a key/value pair. In case the requested pair does not exist, a `RuntimeException` will be thrown:

    Configure::consumeOrFail('Company.name');    // Yields: 'Pizza, Inc.'
    Configure::consumeOrFail('Company.geolocation');  // Will throw an exception
    
    Configure::consumeOrFail('Company');
    
    // Yields:
    ['name' => 'Pizza, Inc.', 'slogan' => 'Pizza for your body and soul'];

1  
2  
3  
4  
5  
6  
7  

Reading and writing configuration files [​](https://book.cakephp.org/6.x/development/configuration.html#reading-and-writing-configuration-files)

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

`static` Cake\\Core\\Configure::**config**(string $name, ConfigEngineInterface $engine): void

CakePHP comes with two built-in configuration file engines. `Cake\Core\Configure\Engine\PhpConfig` is able to read PHP config files, in the same format that Configure has historically read. `Cake\Core\Configure\Engine\IniConfig` is able to read ini config files. See the [PHP documentation](https://php.net/parse_ini_file)
 for more information on the specifics of ini files. To use a core config engine, you'll need to attach it to Configure using `Configure::config()`:

    use Cake\Core\Configure\Engine\PhpConfig;
    
    // Read config files from config
    Configure::config('default', new PhpConfig());
    
    // Read config files from another path.
    Configure::config('default', new PhpConfig('/path/to/your/config/files/'));

1  
2  
3  
4  
5  
6  
7  

You can have multiple engines attached to Configure, each reading different kinds or sources of configuration files. You can interact with attached engines using a few other methods on Configure. To check which engine aliases are attached you can use `Configure::configured()`:

    // Get the array of aliases for attached engines.
    Configure::configured();
    
    // Check if a specific engine is attached
    Configure::configured('default');

1  
2  
3  
4  
5  

`static` Cake\\Core\\Configure::**drop**(string $name): bool

You can also remove attached engines. `Configure::drop('default')` would remove the default engine alias. Any future attempts to load configuration files with that engine would fail:

    Configure::drop('default');

1  

### Loading Configuration Files [​](https://book.cakephp.org/6.x/development/configuration.html#loading-configuration-files)

`static` Cake\\Core\\Configure::**load**(string $key, string $config = 'default', bool $merge = true): bool

Once you've attached a config engine to Configure you can load configuration files:

    // Load my_file.php using the 'default' engine object.
    Configure::load('my_file', 'default');

1  
2  

Loaded configuration files merge their data with the existing runtime configuration in Configure. This allows you to overwrite and add new values into the existing runtime configuration. By setting `$merge` to `true`, values will not ever overwrite the existing configuration.

WARNING

When merging configuration files with $merge = true, dot notation in keys is not expanded:

    // config1.php
    'Key1' => [\
        'Key2' => [\
            'Key3' => ['NestedKey1' => 'Value'],\
        ],\
    ],
    
    // config2.php
    'Key1.Key2' => [\
        'Key3' => ['NestedKey2' => 'Value2'],\
    ]
    
    Configure::load('config1', 'default');
    Configure::load('config2', 'default', true);
    
    // Now Key1.Key2.Key3 has the value ['NestedKey2' => 'Value2']
    // instead of ['NestedKey1' => 'Value', 'NestedKey2' => 'Value2']

1  
2  
3  
4  
5  
6  
7  
8  
9  
10  
11  
12  
13  
14  
15  
16  
17  

### Creating or Modifying Configuration Files [​](https://book.cakephp.org/6.x/development/configuration.html#creating-or-modifying-configuration-files)

`static` Cake\\Core\\Configure::**dump**(string $key, string $config = 'default', array $keys = \[\]): bool

Dumps all or some of the data in Configure into a file or storage system supported by a config engine. The serialization format is decided by the config engine attached as $config. For example, if the 'default' engine is a `Cake\Core\Configure\Engine\PhpConfig`, the generated file will be a PHP configuration file loadable by the `Cake\Core\Configure\Engine\PhpConfig`

Given that the 'default' engine is an instance of PhpConfig. Save all data in Configure to the file \`my\_config.php\`:

    Configure::dump('my_config', 'default');

1  

Save only the error handling configuration:

    Configure::dump('error', 'default', ['Error', 'Exception']);

1  

`Configure::dump()` can be used to either modify or overwrite configuration files that are readable with `Configure::load()`

### Storing Runtime Configuration [​](https://book.cakephp.org/6.x/development/configuration.html#storing-runtime-configuration)

`static` Cake\\Core\\Configure::**store**(string $name, string $cacheConfig = 'default', ?array $data = null): bool

You can also store runtime configuration values for use in a future request. Since configure only remembers values for the current request, you will need to store any modified configuration information if you want to use it in subsequent requests:

    // Store the current configuration in the 'user_1234' key in the 'default' cache.
    Configure::store('user_1234', 'default');

1  
2  

Stored configuration data is persisted in the named cache configuration. See the [Caching](https://book.cakephp.org/6.x/core-libraries/caching.html)
 documentation for more information on caching.

### Restoring Runtime Configuration [​](https://book.cakephp.org/6.x/development/configuration.html#restoring-runtime-configuration)

`static` Cake\\Core\\Configure::**restore**(string $name, string $cacheConfig = 'default'): bool

Once you've stored runtime configuration, you'll probably need to restore it so you can access it again. `Configure::restore()` does exactly that:

    // Restore runtime configuration from the cache.
    Configure::restore('user_1234', 'default');

1  
2  

When restoring configuration information it's important to restore it with the same key, and cache configuration as was used to store it. Restored information is merged on top of the existing runtime configuration.

### Configuration Engines [​](https://book.cakephp.org/6.x/development/configuration.html#configuration-engines)

CakePHP provides the ability to load configuration files from a number of different sources, and features a pluggable system for [creating your own configuration engines](https://api.cakephp.org/5.x/interface-Cake.Core.Configure.ConfigEngineInterface.html)
. The built in configuration engines are:

*   [JsonConfig](https://api.cakephp.org/5.x/class-Cake.Core.Configure.Engine.JsonConfig.html)
    
*   [IniConfig](https://api.cakephp.org/5.x/class-Cake.Core.Configure.Engine.IniConfig.html)
    
*   [PhpConfig](https://api.cakephp.org/5.x/class-Cake.Core.Configure.Engine.PhpConfig.html)
    

By default your application will use `PhpConfig`.

---