Folder & File

Folder と File ユーティリティは、ファイルの読み書きやフォルダ内のファイル名一覧の取得、 その他ディレクトリに関連するタスクにおいて便利なクラスです。

基本的な使い方

App::uses() を使ってクラスをロードします。

App::uses('Folder', 'Utility');
App::uses('File', 'Utility');

すると、新しいフォルダインスタンスをセットアップすることができるようになります。

$dir = new Folder('/path/to/folder');

インスタンスを作成したフォルダ内から .ctp の拡張子が付いたファイルを 正規表現検索する場合はこのようにします。

$files = $dir->find('.*\.ctp');

これでファイルの読み込みや、コンテンツの書き込み、ファイルの削除などが行えるようになります。

foreach ($files as $file) {
    $file = new File($dir->pwd() . DS . $file);
    $contents = $file->read();
    // $file->write('このファイルの内容を上書きします');
    // $file->append('このファイルの最後に追記します。');
    // $file->delete(); // このファイルを削除します
    $file->close(); // 終了時にファイルをクローズしましょう
}

Folder API

class Folder(string $path = false, boolean $create = false, mixed $mode = false)
// 0755 のパーミッションで新しいフォルダを作成します
$dir = new Folder('/path/to/folder', true, 0755);
property Folder::$path

フォルダの現在のパス。 Folder::pwd() は同じ情報を返します。

property Folder::$sort

ファイルリストを取得する際に、名前によるソートを実行するか否かの値。

property Folder::$mode

フォルダ作成時のモード。デフォルトでは 0755 。 Windows マシンでは何も影響しません。

static Folder::addPathElement(string $path, string $element)
戻り値の型:string

$path と $element の間に適切なスラッシュを加えて返します。

$path = Folder::addPathElement('/a/path/for', 'testing');
// $path は /a/path/for/testing となります

バージョン 2.5 で追加: 2.5 から $element パラメータは配列も使用できます。

Folder::cd(string $path)
戻り値の型:string

ディレクトリを $path へ移動します。失敗時には false が返ります。

$folder = new Folder('/foo');
echo $folder->path; // /foo が表示されます
$folder->cd('/bar');
echo $folder->path; // /bar が表示されます
$false = $folder->cd('/non-existent-folder');
Folder::chmod(string $path, integer $mode = false, boolean $recursive = true, array $exceptions = array())
戻り値の型:boolean

ディレクトリのモード(パーミッション)を再帰的に変更します。 ファイルのモードも同様に変更します。

$dir = new Folder();
$dir->chmod('/path/to/folder', 0755, true, array('skip_me.php'));
Folder::copy(array|string $options = array())
戻り値の型:boolean

(デフォルトでは再帰的に) ディレクトリをコピーします。 唯一のパラメータである $options にはコピー先のパスか、オプションの配列を指定します。

$folder1 = new Folder('/path/to/folder1');
$folder1->copy('/path/to/folder2');
// Will put folder1 and all its contents into folder2

$folder = new Folder('/path/to/folder');
$folder->copy(array(
    'to' => '/path/to/new/folder',
    'from' => '/path/to/copy/from', // will cause a cd() to occur
    'mode' => 0755,
    'skip' => array('skip-me.php', '.git'),
    'scheme' => Folder::SKIP, // Skip directories/files that already exist.
    'recursive' => true //set false to disable recursive copy
));

以下の3つの動作 (scheme) に対応します:

  • Folder::SKIP コピー・移動先にファイルやディレクトリが既に存在している場合は、スキップします。
  • Folder::MERGE コピー元とコピー先のディレクトリをマージします。コピー元のディレクトリにある ファイルは、対象のディレクトリにあるファイルを置き換えます。ディレクトリの中身はマージされます。
  • Folder::OVERWRITE 対象のディレクトリに存在するファイルやディレクトリはコピー元の ディレクトリの内容で上書きされます。対象とコピー先の両方にサブディレクトリが含まれる場合、 対象のディレクトリの内容は、コピー元の内容に削除や置き換えられます。

バージョン 2.3 で変更: copy() にマージ、スキップ、上書きの動作 (scheme) が追加されました。

static Folder::correctSlashFor(string $path)
戻り値の型:string

$path に与えるべき適切なスラッシュを返します。 (Windows のパスは ‘\’ で、その他のパスは ‘/’)

Folder::create(string $pathname, integer $mode = false)
戻り値の型:boolean

再帰的にディレクトリ構造を作成します。 /foo/bar/baz/shoe/horn のような深い階層の作成も可能です。

$folder = new Folder();
if ($folder->create('foo' . DS . 'bar' . DS . 'baz' . DS . 'shoe' . DS . 'horn')) {
    // 入れ子になっているフォルダの作成に成功
}
Folder::delete(string $path = null)
戻り値の型:boolean

システムが許可していた場合、再帰的にディレクトリを削除します。

$folder = new Folder('foo');
if ($folder->delete()) {
    // foo とその入れ子になっているフォルダの削除に成功
}
Folder::dirsize()
戻り値の型:integer

フォルダとその内容のサイズをバイト数で返します。

Folder::errors()
戻り値の型:array

最新のエラーを返します。

Folder::find(string $regexpPattern = '.*', boolean $sort = false)
戻り値の型:array

現在のディレクトリでマッチしたファイルを配列で返します。

// app/webroot/img/ フォルダ内の .png を検索し、ソートして返す
$dir = new Folder(WWW_ROOT . 'img');
$files = $dir->find('.*\.png', true);
/*
Array
(
    [0] => cake.icon.png
    [1] => test-error-icon.png
    [2] => test-fail-icon.png
    [3] => test-pass-icon.png
    [4] => test-skip-icon.png
)
*/

注釈

フォルダの find メソッドと findRecursive メソッドは、ファイルのみを検索します。 フォルダとファイルを取得したい場合は、 Folder::read() もしくは Folder::tree() 参照してください。

Folder::findRecursive(string $pattern = '.*', boolean $sort = false)
戻り値の型:array

カレントディレクトリ内とそれ以下のすべての一致するファイルの配列を返します。

// test もしくは index で始まるファイルを再帰的に検索する
$dir = new Folder(WWW_ROOT);
$files = $dir->findRecursive('(test|index).*');
/*
Array
(
    [0] => /var/www/cake/app/webroot/index.php
    [1] => /var/www/cake/app/webroot/test.php
    [2] => /var/www/cake/app/webroot/img/test-skip-icon.png
    [3] => /var/www/cake/app/webroot/img/test-fail-icon.png
    [4] => /var/www/cake/app/webroot/img/test-error-icon.png
    [5] => /var/www/cake/app/webroot/img/test-pass-icon.png
)
*/
Folder::inCakePath(string $path = '')
戻り値の型:boolean

ファイルが与えられた CakePath の中に存在すれば true を返します。

Folder::inPath(string $path = '', boolean $reverse = false)
戻り値の型:boolean

ファイルが与えられたパスの中に存在すれば true を返します。

$Folder = new Folder(WWW_ROOT);
$result = $Folder->inPath(APP);
// $result = true, /var/www/example/app/ は /var/www/example/app/webroot/ に含まれる

$result = $Folder->inPath(WWW_ROOT . 'img' . DS, true);
// $result = true, /var/www/example/app/webroot/ は
// /var/www/example/app/webroot/img/ に含まれる
static Folder::isAbsolute(string $path)
戻り値の型:boolean

与えられた $path が絶対パスであれば true を返します。

static Folder::isSlashTerm(string $path)
戻り値の型:boolean

与えられた $path がスラッシュで終了していれば true を返します。(つまり、 slash-terminated)

$result = Folder::isSlashTerm('/my/test/path');
// $result = false
$result = Folder::isSlashTerm('/my/test/path/');
// $result = true
static Folder::isWindowsPath(string $path)
戻り値の型:boolean

与えられた $path が Windows のパスであれば true を返します。

Folder::messages()
戻り値の型:array

直近で利用したメソッドのメッセージを取得します。

Folder::move(array $options)
戻り値の型:boolean

(デフォルトで再帰的に) ディレクトリを移動します。 $options パラメータは copy() のものと同じです。

static Folder::normalizePath(string $path)
戻り値の型:string

与えられた $path を適切なスラッシュに調整して返します。 (Windows のパスは ‘\’ で、その他のパスは ‘/’)

Folder::pwd()
戻り値の型:string

現在のパスを返します。

Folder::read(boolean $sort = true, array|boolean $exceptions = false, boolean $fullPath = false)
戻り値の型:

mixed

パラメータ:
  • $sort (boolean) – true の場合に結果をソートします。
  • $exceptions (mixed) – 無視するファイル名とフォルダ名の配列。 true もしくは ‘.’ が与えられた場合、隠しファイルもしくはドットファイルを無視します。
  • $fullPath (boolean) – true の場合に絶対パスで結果を返します。

現在のディレクトリのコンテンツを配列で返します。 戻り値は2つの配列となります。1つはディレクトリ名の配列。もう1つはファイル名の配列です。

$dir = new Folder(WWW_ROOT);
$files = $dir->read(true, array('files', 'index.php'));
/*
Array
(
    [0] => Array // フォルダー
        (
            [0] => css
            [1] => img
            [2] => js
        )
    [1] => Array // ファイル
        (
            [0] => .htaccess
            [1] => favicon.ico
            [2] => test.php
        )
)
*/
Folder::realpath(string $path)
戻り値の型:string

本当のパスを取得します(”..” などを考慮して)

static Folder::slashTerm(string $path)
戻り値の型:string

引数の $path に (Windows や、その他の OS で正しい) 終端のスラッシュを付けたパスを返します。

Folder::tree(null|string $path = null, array|boolean $exceptions = true, null|string $type = null)
戻り値の型:mixed

入れ子になったディレクトリと各ディレクトリ中のファイルの配列を返します。

File API

class File(string $path, boolean $create = false, integer $mode = 755)
// 0644 のパーミッションで新しいファイルを作成します
$file = new File('/path/to/file.php', true, 0644);
property File::$Folder

ファイルが属するフォルダ・オブジェクト

property File::$name

拡張子付きのファイル名。 拡張子なしのファイル名を返す File::name() とは異なります。

property File::$info

ファイル情報の配列。代わりに File::info() を使用してください。

property File::$handle

ファイルをオープンしている場合のファイルハンドラを保持します。

property File::$lock

ファイルの読み書き時のロックを有効にします。

property File::$path

現在のファイルの絶対パス。

File::append(string $data, boolean $force = false)
戻り値の型:boolean

与えられたデータ文字列を現在のファイルに追記します。

File::close()
戻り値の型:boolean

ファイルがオープンされていた場合、そのファイルをクローズします。

File::copy(string $dest, boolean $overwrite = true)
戻り値の型:boolean

ファイルを $dest へコピーします。

File::create()
戻り値の型:boolean

ファイルを作成します。

File::delete()
戻り値の型:boolean

ファイルを削除します。

File::executable()
戻り値の型:boolean

ファイルが実行可能な場合に true を返します。

File::exists()
戻り値の型:boolean

ファイルが存在する場合に true を返します。

File::ext()
戻り値の型:string

ファイルの拡張子を返します。

File::Folder()
戻り値の型:Folder

現在のフォルダを返します。

File::group()
戻り値の型:integer

ファイルのグループを返します。エラーの場合は false を返します。

File::info()
戻り値の型:string

ファイル情報を返します。

バージョン 2.1 で変更: File::info() ファイルサイズと MIME タイプの情報が含まれるようになりました。

File::lastAccess()
戻り値の型:integer

最終アクセス時刻を返します。エラーの場合は false を返します。

File::lastChange()
戻り値の型:integer

最終更新時刻を返します。エラーの場合は false を返します。

File::md5(integer|boolean $maxsize = 5)
戻り値の型:string

ファイルサイズを事前にチェックした上で、ファイルの md5 チェックサムを取得します。 エラーの場合は false を取得します。

File::name()
戻り値の型:string

拡張子を省いたファイル名を返します。

File::offset(integer|boolean $offset = false, integer $seek = 0)
戻り値の型:mixed

現在オープンしているファイルのオフセット値を設定または取得します。

File::open(string $mode = 'r', boolean $force = false)
戻り値の型:boolean

現在のファイルを与えられた $mode でオープンします。

File::owner()
戻り値の型:integer

ファイルのオーナーを返します。

File::perms()
戻り値の型:string

ファイルの “chmod” (パーミッション) を返します。

static File::prepare(string $data, boolean $forceWindows = false)
戻り値の型:string

ASCII 文字列をファイルへ書き出す事前処理を行います。 現在の実行環境に合わせて改行文字を変換します。 Windows なら “\r\n” を、その他の環境なら “\n” が利用されます。

File::pwd()
戻り値の型:string

ファイルのフルパスを返します。

File::read(string $bytes = false, string $mode = 'rb', boolean $force = false)
戻り値の型:mixed

現在のファイルの内容を文字列で返します。失敗時は false を返します。

File::readable()
戻り値の型:boolean

ファイルが読み出し可能な場合に true を返します。

File::safe(string $name = null, string $ext = null)
戻り値の型:string

保存するファイル名を安全にします。

File::size()
戻り値の型:integer

ファイルサイズを返します。

File::writable()
戻り値の型:boolean

ファイルが書き込み可能な場合に true を返します。

File::write(string $data, string $mode = 'w', boolean$force = false)
戻り値の型:boolean

与えられたデータを現在のファイルへ書き込みます。

バージョン 2.1 で追加: File::mime()

File::mime()
戻り値の型:mixed

ファイルの MIME タイプを取得します。失敗時は false を取得します。

File::replaceText($search, $replace)
戻り値の型:boolean

ファイル内のテキストを置換します。失敗時に false を返し、成功時に true を返します。

バージョン 2.5 で追加: File::replaceText()