しっかり理解する CakePHP Upload プラグインの使い方 (1) 導入・DB, Model 変更

この記事を読むのに必要な時間は約 21 分です。

CakePHP で、画像のアップロードやサムネイル作成までを簡単に行える、Upload プラグインについて、実際の導入方法や使い方をご紹介したいと思います。

前回の記事で、どのようなことができるか、どう動作するかなどを解説しました。
→ CakePHP Upload プラグインの動作解説 : 画像のアップロードからサムネイル作成まで手軽にできる CakePHP Uploadプラグイン

今回は、導入方法、DB 変更、Model の変更・作成について解説したいと思います。

View や Controller は次回扱いたいと思います。

1. Upload プラグインの導入手順

導入には、いくつかの方法があります。

Composer を利用
Git を利用
手動

今回は、手っ取り早い「手動」で導入する方法をご紹介します。

Composer や Git での導入方法は、GitHub に記載されています。

1-1. ファイルのダウンロード・配置

(1) GitHub にアクセスします。右下の方にある、「Download ZIP」ボタンをクリックしてダウンロードします。

「cakephp-plugin-upload-master.zip」というファイルがダウンロードされます。

(2) ダウンロードした zip ファイルを解凍します。

(3) 解凍して作成されたディレクトリを「Upload」にリネームします。
Upload 直下に、README.md や composer.json 等のファイルがあれば、階層は OK です。

(4) Upload ディレクトリを、CakePHP のプラグイン用ディレクトリに配置します。
app/Plugin/Upload となれば OK です。

1-2. プラグインの読込

他のプラグイン導入時と同様に、読み込む設定を追加します。

app/Config/bootstrap.php に、以下の 1行を追加します。

CakePlugin::load('Upload');

もし、以下のようにプラグインを全て読み込む設定になっていれば、上記は不要です。

CakePlugin::loadAll();

2. DB 変更

Upload プラグインで使用するカラムやテーブルを追加します。

既存テーブルにカラム追加 or 新規テーブル追加についての解説は、前回記事をご覧ください。

2-1. 既存テーブルにカラム追加する場合

例えば、以下のように photo , photo_dir カラムを追加します。カラム名は後で Model を変更する際に使います。

この例は、GitHub上のdoc/example.rst (英語) に記載されているものを利用させていただきました。

CREATE table users (
    `id` int(10) unsigned NOT NULL auto_increment,
    `username` varchar(20) NOT NULL,
    `photo` varchar(255) DEFAULT NULL,
    `photo_dir` varchar(255) DEFAULT NULL,
    PRIMARY KEY (`id`)
);

以下、文末の () は実際に登録される値の例です。

photo には、アップロードされたファイル名が入ります。 ( “IMAGE01.jpg” など )

photo_dir には、アップロードされたファイルが格納されたディレクトリ名が入ります。 ( “2” など )

2-2. 新規テーブルを追加する場合

例えば、以下のようなテーブルを追加します。以下は、複数の Model と紐づく場合の想定です。

こちらは、公式 Doc にある Polymorphic に記載されている例 (英語) を利用させていただきました。

CREATE table attachments (
    `id` int(10) unsigned NOT NULL auto_increment,
    `model` varchar(20) NOT NULL,
    `foreign_key` int(11) NOT NULL,
    `name` varchar(32) NOT NULL,
    `attachment` varchar(255) NOT NULL,
    `dir` varchar(255) DEFAULT NULL,
    `type` varchar(255) DEFAULT NULL,
    `size` int(11) DEFAULT 0,
    `active` tinyint(1) DEFAULT 1,
    PRIMARY KEY (`id`)
);

以下、文末の () は実際に登録される/する値の例です。

model は、どの Model に紐づくレコードかを表します。(“User”など)

foreign_key は、参照先の Model の id を登録します。( 5 など )

attachment がアップロードしたファイル名が入るカラムです。任意のカラム名で構いません。私は file_name で利用しています。 ( “IMAGE01.jpg” など )

dir は、アップロードしたファイルが格納されたディレクトリ名が入ります。( “2” など )

type, size には、ファイル種類、ファイルサイズがそれぞれ入ります。無くても構いません。

active は、不要になったら 0 (false) にして、表示されないようにするためのカラムです。無くても構いません。

model や foreign_key は、不要であれば無くても構いません。例えば、posts テーブルのみに紐付けるようであれば、model は “Post” 固定になりますし、foreign_key の代わりに、post_id としておけば良いでしょう。

2-3. 複数カラムを利用する場合

例えば、以下のように、既存の users テーブルに icon, bg, dir カラムを追加した場合だとします。

CREATE table users (
    `id` int(10) unsigned NOT NULL auto_increment,
    `username` varchar(20) NOT NULL,
    `icon` varchar(255) DEFAULT NULL,
    `bg` varchar(255) DEFAULT NULL,
    `dir` varchar(255) DEFAULT NULL,
    PRIMARY KEY (`id`)
);

以下、文末の () は実際に登録される値の例です。

4 行目 icon は、アイコン画像のファイル名用のカラムです。

5 行目 bg は、背景画像のファイル名用のカラムです。

6 行目 dir は、格納したディレクトリ名を登録するようのカラムです。

3. Model の変更・作成

DB 変更が完了したら、Model クラスを変更あるいは作成し、Behavior を登録しましょう。

3-1. 既存テーブルにカラム追加した場合

2-1. の例のように、users テーブルにカラム追加を行った場合、対応する User Model に変更を行います。

<?php
class User extends AppModel{
...

  public $actsAs = array(
    "Upload.Upload" => array(
      "photo" => array(
        "fields" => array(
          "dir" => "photo_dir",
        ),
      ),
    ),
  );
...
}
?>

6 行目 “Upload.Upload” で、プラグインを指定しています。プラグイン記法で Upload プラグインにある、Upload Behavior だよ、ということですね。

7 行目 “photo” は、このカラムに Upload Behavior を適用してファイル名を登録するよ、という指定になります。カラム名が他の名前であれば、そのカラム名に変更して下さい。

8-9 行目 “fields” は、ファイル名以外に登録される、dir・type・size をデフォルトのカラム名から変更する場合に指定します。ここでは、”dir” をデフォルトのカラム名 “dir” ではなく、”photo_dir” に登録するよ、という指定になります。

type や size の情報は、カラムも無いし、指定もされていないので、登録されずに破棄されます。

同テーブル内に、他の用途で type や size のカラムがある場合、Upload プラグインによって上書きされる可能性があるかも知れません。fields で関係ない値に指定すると良いかと思います。

その他、格納するディレクトリのベースを変更すること等もできますが、Behavior の設定周りは別記事にて扱いたいと思います。

3-2. 新規テーブル追加を行った場合

3-2-1. 追加したテーブル用の Model の作成

2-2. の例のように attachments テーブルを追加した場合、対応する Attachment モデルを新たに作成する必要があります。

以下のように、app/Model/Attachment.php を作成します。

<?php
class Attachment extends AppModel {
...
  public $actsAs = array(
    'Upload.Upload' => array(
      'attachment' => array(
        'thumbnailSizes' => array(
          'xvga' => '1024x768',
          'vga' => '640x480',
          'thumb' => '80x80',
        ),
      ),
    ),
  );
...
  public $belongsTo = array(
    'Post' => array(
      'className' => 'Post',
      'foreignKey' => 'foreign_key',
    ),
    'Message' => array(
      'className' => 'Message',
      'foreignKey' => 'foreign_key',
    ),
  );
...
}
?>

5 行目 “Upload.Upload” は 3-1. と同じです。

6 行目 “attachment” は、カラム名 attachment に Upload Behavior を適用するよ、ということです。カラム名 file_name にしている場合は、ここが “attachment” ではなく “file_name” になります。

7-10 行目では、”thumbnailSizes” として、サムネイル作成の指定を行っています。これは後で解説します。サムネイル作成が不要であれば、省略可能です。

この例では、”fields” を指定していません。これは、attachments テーブルに、”dir”, “type”, “size” のカラムがあるため、変更なしでデフォルトのままで、それぞれのカラムが利用されるために省略しています。

16-25 行目 $belongsTo で、リレーションを登録しています。これは Upload プラグインとは関係なく、通常のリレーション登録です。 attachments テーブルが 1:多の多に当たります。

ここでは、Post モデルと、Message モデルとに紐づくよう登録しています。Model 名とリレーション上の名前は同じなので、18, 22 行目の className は省略可能だと思います。

foreignKey が参照先モデル名 (単数形) + _id ではないため、19, 23 行目の指定が必要です。

User モデル専用で、model カラムなしで、foreign_key カラムの代わりに user_id を用意している場合であれば、foreignKey の指定は省略可能です。

その他、格納するディレクトリのベースを変更すること等もできますが、Behavior の設定周りは別記事にて扱いたいと思います。

3-2-2. 既存 Model の修正

作成した Model の参照先でも反対向きのリレーションを登録しましょう。リレーションを登録しておけば、find() で自動的に取得されたりします。不要であれば、リレーション登録しなくとも動かなくはないです。

3-2-1. で、Post モデルと Message モデルとのリレーションを登録したので、それぞれに反対向きのリレーションを登録します。

以下のように app/Model/Post.php を修正します。

<?php
class Post extends AppModel {
...
  public $hasMany = array(
...
    'Image' => array(
      'className' => 'Attachment',
      'foreignKey' => 'foreign_key',
      'conditions' => array(
        'Image.model' => 'Post',
      ),
    ),
...
  );
...
}
?>

ここでは、Attachment モデルを “Image” の別名で hasMany のリレーションを登録しています。別名での登録のため、7 行目 “className” の指定が必要になります。

外部キーも、Attachment モデル側が post_id というカラム名ではなく、foreign_key というカラム名になっているので、 8 行目 “foreignKey” の指定が必要になります。

User モデル専用で foreign_key カラムではなく、user_id を外部キーにしている場合であれば、foreignKey の指定は不要になります。

9 〜 11 行目で、取得する際の条件として、 attachments テーブルの model カラムの値が “Post” のものだけ、と絞り込んでいます。model の値が一致しないレコードまで含まれると、他のモデルと紐づいていたレコードまで結合されてきてしまいますので、これは必要になると思います。

注意点は、Attachment.model ではなく、別名の Image.model で指定するところでしょうか。この辺りは、Upload プラグインではなく Model のリレーション等の機能をご確認下さい。

User モデル専用といった場合は、絞り込む必要がないため、9 〜 11 行目の指定は、不要になります。

他に、active = 1 といった絞り込みを加えても良いかと思います。

これで “Post” を取得する際に同時に取得することができます。この辺りは、Upload プラグインとは関係ないですね。

以下のように、app/Model/Message.php を修正します。

<?php
class Message extends AppModel {
...
  public $hasMany = array(
...
    'Video' => array(
      'className' => 'Attachment',
      'foreignKey' => 'foreign_key',
      'conditions' => array(
        'Video.model' => 'Message',
      ),
    ),
...
  );
...
}
?>

Post モデルと同様なので、解説は省略します。

Video の別名で利用しているため、Upload プラグインは、動画のアップロードも出来るっぽいようです。試してはいないため、未確認です。

3-3. 複数カラムを利用する場合

以下のように、User Model に Behavior の設定を追加します。

<?php
class User extends AppModel{
...
  public $actsAs = array(
    "Upload.Upload" => array(
      "icon" => array(
        "thumnailSizes" => array(
          "thumb" => "[90x90]",
        ),
      "bg",
      ),
    ),
  );
...
}
?>

6,10 行目で、ファイル名が入る icon や bg カラムをそれぞれ指定しています。

今回は、ディレクトリ用のカラムとして、デフォルトと同じ dir カラムを用意しているため、”fields” のオプションは省略しています。

7-9 行目で、icon の方だけ、サムネイル作成を指定しています。bg は指定していないため、サムネイルは作成されません。

ひとこと

次回は、View や Controller について扱いたいと思います。Upload Behavior の設定については、更に次になるかと思います。

楽しみにお待ちいただければ幸いです。

[pn-box color=”lgray”]

次の記事は、以下になります。良かったら以下もご覧下さい。
しっかり理解する CakePHP Upload プラグインの使い方 (2) View や Controller の修正

[pn-box-close] [pn-cakephp-env plugins=”true”]

今回は以上です。

[pn-amzn-cakephp]