PowerCMS ブログ

ホーム > PowerCMS ブログ > 技術情報 > PowerCMS::Util(MTやPowerCMSを簡単に拡張するための様々な関数)

PowerCMS::Util PerlモジュールはMTやPowerCMSを簡単に拡張するためのライブラリです。ソースは mt/addons/PowerCMS.pack/lib/PowerCMS/Util.pm に置かれています。プラグイン内で以下のようにして利用することができます。

use lib qw( addons/PowerCMS.pack/lib );
use PowerCMS::Util qw( function1 function2 );

このエントリで(すべてではありませんが)いくつかの関数をご紹介します。

テンプレートのビルド
ファイルアップロード/画像加工
MT::Object関連
ファイル/ディレクトリ操作
パス及びURL関連
日付関連
メール関連
ユーザー/権限(パーミッション)関連
文字列操作

テンプレートのビルド

build_tmpl( $app, $tmpl, \%args [, \%params ] )

コンテクストをセットしてテンプレートのビルド(再構築)結果を返します。
引数 $tmpl には MT::Templateオブジェクト又は文字列のいずれかを指定します。
\%args(オプション)でMTオブジェクトの各オブジェクト ( MT::Blog,MT::Category, MT::Entry, MT::Author ) およびタイムスタンプ ( start,end ) を指定します。例:

    %args = ( blog     => $blog,     # optional
              entry    => $entry,    # optional
              category => $category, # optional
              author   => $author,   # optional
              start    => 'YYYYMMDDhhmmss', # optional
              end      => 'YYYYMMDDhhmmss', # optional
            );

\%params(オプション)で指定した値は<mt:var name='key'>で取り出すことができます。例:

    my %params = ( foo => 'bar', # => <mt:var name='foo'>
                   bar => 'buz', # => <mt:var name='bar'>
                 );

ファイルアップロード/画像加工

upload( $app, $blog, $name, $dir, \%params )

ブラウザからアップロードされたファイルを保存してアイテムに登録します。戻り値はアイテム( MT::Assetオブジェクト )の配列です。 $params{ no_asset } = 1を指定した場合はファイルパスの配列を返します。 $params{ singler } = 1を指定した場合配列ではなくスカラー型で値を返します。

引数 $name(必須)でinput要素のname属性を指定します。(<input type='file' name='[name]' />)
引数 $dir(必須)にファイルの保存場所をフルパスで指定します。
引数\%paramsで以下を指定可能です。

    %params = ( object => $obj,    # optional ( 指定したオブジェクトと保存したアイテムを関連付けます )
                author => $author, # optional ( MT::Authorオブジェクト/省略時は現在のユーザー )
                rename => 1,       # optional ( ファイルが存在する場合上書きせずに別名を付けます )
                label => 'foo',    # optional ( アイテムの名前 )
                description => 'bar', # optional ( アイテムの説明 )
                format_LF => 1,    # optional ( 改行コードをLFに揃えます )
                singler   => 1,    # optional ( アップロードされるファイルが1点の場合に指定 )
                no_asset  => 1,    # optional ( アイテムを保存せずにファイルのみを保存します )
               );

convert2thumbnail( $blog, $text, $type, $embed [ , $link, $dimension, $convert_gif_png ] ): テキストから IMG要素を抽出してファイルを検索し、存在すればサムネイルを作成します。引数 $text(必須) に処理対象のソース、$type にイメージの拡張子(省略時auto)、$embed(必須)にサムネイルのサイズ( $dimension で width か height を指定可能です)。$link(オプション)を指定した場合、サムネイルから指定サイズの画像にリンクが貼られます。 $dimension に width または height を指定します。デフォルトは width。 $convert_gif_png を指定すると作成されたサムネイルのパスを convert_gif_png に渡します。

create_thumbnail( $blog, $asset, %param )

MT::Asset オブジェクトからサムネイルを作成します。
引数 %param に $asset->thumbnail_file に渡すパラメタを指定します。例:

        %param = ( Width => 240, # required
                   Path  => $dir, # optional
                   # (省略時 $asset->_make_cache_path )
                   convert_gif_png => $convert_gif_png, # optional
                   # (指定した場合 convert_gif_png を呼び出す)
                  );

MT::Object関連

save_asset( $app, $blog, $params, $cb )

アイテム (MT:Assetオブジェクト) を作成して保存します。引数 \%params(必須)は以下のように指定します。

    %params = ( file => $file,     # required
                author => $author, # required ( MT::Authorオブジェクト )
                label => $label,   # optional
                description => $description,  # optional
                parent => $parent_asset->id,  # optional
                object => $obj,    # optional ( 指定したオブジェクトとアイテムを関連付けます )
                tags => \@tags,    # optional ( 指定するタグの配列 ( 文字列 ) )
              );

$cb(オプション)を指定するとアイテム保存の直前に cms_pre_save.asset, 保存直後に cms_post_save.asset 及びcms_upload_file( cms_upload_image )コールバックをコールします。

get_asset_from_text( $text, $blog ): テキストからhttpではじまるURLへのリンクを抽出してテキストに含まれる MT::Asset オブジェクトの配列を返します。

association_link( $app, $author, $role, $blog ): 指定したブログに対してユーザーにロールを割り当てます。戻り値はMT::Associationオブジェクトです。

create_entry( $app, $blog, \%args, \%params[, $cb] )

MT::Entryオブジェクトを作成して保存します。
$params{ no_save } = 1を指定した場合MT::Entryオブジェクトのみを返します( 保存は行いません )。この場合、カテゴリーや関連オブジェクトはセットされないことに注意してください。
$params{ rebuildme } = 1を指定した場合保存後に再構築を実行します。
引数 \%args(必須)で MT::Entryオブジェクトの各カラムの値及びカスタムフィールド、カテゴリ、タグを指定します。例:

        %args = ( title => 'foo',
                # optional ( その他のカラム 例:text_more,excerptも同様に指定できます )
              text  => 'bar',
                # optional ( 一部のカラムでは指定がない場合ブログのデフォルト値が利用されます )
              author_id => 1, # optional ( 指定がない場合現在のユーザー )
              status => MT::Entry::RELEASE(), # optional ( 指定がない場合ブログのデフォルト )
              customfield_basename => 'buz',  # optional ( customfield_+フィールドのbasename )
              tags => \@tags, # optional ( 指定するタグの配列 ( 文字列 ) )
              category_id => 1, # optional ( カテゴリが一つの場合( カテゴリのID ) )
              categories => \@categories,
                # optional ( カテゴリが複数の場合( MT::Categoryオブジェクトの配列 ) )
             );

id( エントリーのID )を指定した場合、エントリーが存在すれば上書きします。複数のカテゴリを指定した場合最初のカテゴリがプライマリカテゴリに指定されます。
引数 \%params(オプション)で保存と再構築に関する指定を行います。

    %params = ( rebuildme => 1,    # optional 保存後に再構築を行います
                dependencies => 1, # optional 再構築時にインデックス等の関連アーカイブを再構築します
                no_save => 1,      # optional エントリーを保存せずにオブジェクトのみ返します(再構築は行われません)
                background => 1,   # optional バックグラウンドプロセスで再構築を実行します
             );

引数 $cb(オプション)を指定するとエントリーの保存前に cms_pre_save.entry( page ) エントリーの保存後に cms_pre_save.entry( page )コールバックをコールします。

ファイル/ディレクトリ操作

write2file ( $path, $data, $type, $blog ): フルパス ( フルパス ) とデータを指定してファイルを生成します。引数 $type(オプション)で'upload' 又は 'output'を指定します(省略の場合'output'); 引数 $blogを指定した場合相対パス ( %r や %s を含むパス ) の使用が可能です。

read_from_file( $path, $type, $blog ): 引数 $type(オプション)は'upload' 又は 'ascii'を指定します(省略の場合'ascii'); 引数 $blogを指定した場合相対パス ( %r や %s を含むパス ) の使用が可能です。

move_file( $from, $to, $blog ): $from から $to へファイルを移動します。引数 $blogを指定した場合相対パス ( %r や %s を含むパス ) の使用が可能です。

copy_item( $from, $to, $blog ): $from から $to へファイル(又はフォルダ)をコピーします。引数 $blogを指定した場合相対パス ( %r や %s を含むパス ) の使用が可能です。

get_children_files( $directory, $pattern ): ディレクトリ以下 ( サブディレクトリを含む ) のファイルの配列を返します。引数 $pattern(オプション)に正規表現パターンを渡すとマッチしたファイルのみを抽出します。

make_zip_archive( $directory, $zipfile_path[, $files ]): ディレクトリまたはファイルの配列を指定してZIPアーカイブファイルを作成します。戻り値は Archive::Zip モジュールの writeToFileNamed 関数の実行結果です。

パス及びURL関連

site_path( $blog ): ブログのサイト・パスを常に末尾の / (スラッシュ) を省略して返します。アーカイブ・パスの指定がある場合はアーカイブ・パスを返します。

site_url( $blog ): ブログのURLを常に末尾の / ( スラッシュ ) を省略して返します。末尾の / を含む完全なURLを返す場合は add_slash 関数をあわせて利用してください。

relative2path( $path, $blog ): 相対パス ( %r や %s を含むパス ) をフルパスに変換します。

path2relative( $path, $blog ): フルパスを相対パス ( %r や %s を含むパス ) に変換します。

path2url( $path, $blog ): フルパスからURLを生成します。

url2path( $path, $blog ): URLからサーバーのフルパスを生成します。

powercms_files_dir(): PowerCMSがファイル(キャッシュ、バックアップ、一時ファイル、設定等)を保存するディレクトリのパスを取得します。通常は /path/to/mt_dir/powercms_files です(環境設定 PowerCMSFilesDir で設定を変更できます)。ディレクトリが存在しない場合は自動的に生成されます。

powercms_files_dir_path(): PowerCMSがファイル( キャッシュ、バックアップ、一時ファイル、設定等 )を保存するディレクトリのパスを取得します(パスの取得のみで生成は行いません)。

make_dir( $dir ): ディレクトリを作成します。

file_extension( $file, $nolc ): ファイルの拡張子を返します。第二引数を省略した場合、値は小文字に変換されて返されます。

file_label( $file ): ファイルパスからファイル名を抽出し、拡張子を除いたファイルを返します。例: file_label( '/path/to/file.jpg' ); # 'file'

file_basename( $file ): ファイルパスからファイル名を抽出します。

mime_type( $file )

ファイルパスからファイルの MIME タイプを返します。例:

   mime_type( '/path/to/file.html' ); # 'text/html'

is_writable( $path, $blog ): 指定したパスがアプリケーションから書き込み可能なパスであるかどうかを調べます。 TempDir ImportPath SupportDirectoryPath PowerCMSFilesDirのいずれか以下のパスである場合に 1 を返します。第二引数 $blog を指定している場合、指定したパスがブログの公開パス以下のパスである場合は 1 を返します。

日付関連

current_ts( $blog ): 現在のタイムスタンプを YYYYMMDDhhmmss 形式で返します。

next_date( $blog, $ts ): $ts ( YYYYMMDDhhmmss ) の24時間後のタイムスタンプを返します。

prev_date( $blog, $ts ): $ts ( YYYYMMDDhhmmss ) の24時間前のタイムスタンプを返します。

valid_ts( $ts ): $ts ( YYYYMMDDhhmmss ) の書式が妥当で且つ存在している日時の場合 1 を返します。

month2int( $month ): 月を表す文字列( 例: January, Jan, jan ) から数字を返します。

メール関連

send_mail( $from, $to, $subject, $body [, \@cc, \@bcc, \%params_for_callback ] ) send_mail( \%args, \%params_for_callback )

指定の $to へメールを送信します(呼出し方は2種類あります)。 $from, $to, $subject, $body のいずれかが空の場合はメール送信せずにリターンします。また、実際の送信前にpre_send_mailコールバックを\%args 形式で呼び出します。
コールバックが0を返した場合は、メール送信せずにリターンします。
第2の呼び出しインターフェースでは、Content-Typeを指定可能です。
引数 \%params_for_callbacks(オプション)で呼び出し側でコールバックされたときに渡すものを自由に指定できます。以下のようにkeyを入れてください。keyがない場合は、'default'が自動的に入ります。例:

    %params_for_callbacks = (
        key => '呼び出しを特定する文字列',
        another params ...
    );

第2の呼び出しインターフェース引数 \%args は以下のように指定します。

    %args = (
        from    => $from,    # required
        to      => $to,      # required
        subject => $subject, # required
        body    => $body,    # required
        cc      => \@cc,     # optional
        bcc     => \@bcc,    # optional
        content_type => $content_type, # optional
    );

コールバック

pre_send_mail( $app, \%args, \%spec )
%args の中の特定のキーの値を変更することで、後続の実際のメール送信対象を変更可能です。
コールバックが偽を返すとメール送信が行われません。

send_multipart_mail( \%args )

添付ファイル付きメールを送信します。引数 \%args(必須)で添付ファイルの配列を含むパラメタを渡します。

    %args = (
        from      => $from,      # required
        to        => $to,        # optional
        subject   => $subject,   # optional
        cc        => $cc,        # optional
        bcc       => $bcc,       # optional
        attaches  => \@attaches, # optional
        cb_params => \$cb_params # optional
    );

$cb_paramsには send_mail 関数に渡すコールバック用のパラメタを指定します。パラメタの指定方法については send_mail 関数のドキュメントを参照してください。添付ファイルについては下記のように指定します。

    my @attaches = (
        {
            Path => '/path/to/file1.csv'
        },
        {
            Path => '/path/to/file1.jpg',
            Type     => 'image/jpeg',
            Encoding => 'base64',
        },
    );

mk_multipart_data( \%args ): 添付ファイル付きメール送信時に、send_mailに渡すためのContent-TypeとマルチパートなBodyを返します。
戻り値は、上記のリストです。( $content_type, $new_body )
引数 \%args (必須)で MIME::Bodyのbuild関数の引数に準じたパラメータを指定します。
%args = ( Body => \@body_lines, # required Attaches => \@attache_file_info, # optional ); @body_lines = ( $body ); # send_mailの$bodyをそのまま使う場合 @attache_file_info = ( { Path => '添付ファイルのパス', # 必須パラメータ、存在しなければ無視される Type => 'MIMEタイプ', # MIME::Entity的に必須、デフォルトmime_type()で生成 Encoding => 'エンコード方式' # なければMIME::Entityに推測させる }, );

get_mail( $server, $id, $passwd, $protocol, $delete )

メールを受信します。戻り値はメールと添付ファイルに関する情報の配列です。例:

    ( { from => $from,
        subject   => $subject1,
        body      => $body1,
        files     => \@files1,
        directory => $workdir1 },
      { from => $from2,
        subject   => $subject2,
        body      => $body2,
        files     => \@files2,
        directory => $workdir2 }
    )

引数 $delete に 1 値を渡すとメール受信後にメールをサーバーから削除します。

valid_email( $email ): メールアドレスが妥当な書式の場合に 1 を返します。

ユーザー/権限(パーミッション)関連

is_user_can( $blog, $user, $permission ): ブログに対してユーザーが特定の権限を持っている場合に 1 を返します。

get_permissions(): 実行中のアプリケーションのユーザーの MT::Permission オブジェクトをロードして返します。

get_user( $app ): ログイン中のユーザーの MT::Author オブジェクトを返します。 MTのユーザー、コメント投稿者、携帯のセッションID、携帯の個別機種IDの順にユーザーをチェックして、どれかに該当すればそのユーザーの MT::Author オブジェクトを返します。

文字列操作

get_utf( $text ): Unicode::Japaneseモジュールを利用して文字列を UTF8 コードで取り出します。 Perl-5.8.0 以降においては, utf-8 フラグのついた utf-8 文字列として返します。

utf8_on( $text ): 文字列にUTFフラグを付けて返します。

utf8_off( $text ): 文字列のUTFフラグを落とします。

to_utf8( $text ): MT::I18N::encode_text を呼び出して文字列をUTF8に変換します。

normalize( $text ): Unicode::Normalize モジュールを利用して文字列を正規化( NFKC )します。

extract_content( $start, $end, $data, $cont ): 開始ポイント、終了ポイントを指定してその間のコンテンツを抽出します。引数 $cont を指定した場合、抽出開始ポイント、終了ポイントの文字列を含む抽出結果を返します。

regex_replace( $pattern, $replace, $data ): 正規表現パターンを指定してデータを抽出します。

regex_extract( $pattern, $data ): MTのグローバルモディファイア regex_replace の実行結果を返します。

カテゴリー: 技術情報

投稿者: junnama

コメントを投稿する

名前
電子メール
URL

サインイン情報を記憶

PowerCMS ブログ

PowerCMS::Util(MTやPowerCMSを簡単に拡張するための様々な関数)

テンプレートのビルド

ファイルアップロード/画像加工

MT::Object関連

ファイル/ディレクトリ操作

パス及びURL関連

日付関連

メール関連

ユーザー/権限(パーミッション)関連

文字列操作

あなたへお勧めの記事

コメントを投稿する

Archives

Recent Entries

Categories

PowerCMS ブログ

PowerCMS::Util(MTやPowerCMSを簡単に拡張するための様々な関数)

この記事と関連性の高い記事

あなたへお勧めの記事

コメントを投稿する

Archives

Recent Entries

Categories