Posql (ポスキューエル) は、
ピュア PHP (標準バンドル以外に必要なモジュールなし) で作られた、
1 つのファイルを 1 つのデータベースとして扱う
データベースエンジン のクラス (ライブラリ系 DBMS) です。
PHP のバージョンに関係なく動作し、
SQLite より気軽に扱えることを目標とされています。
基本的な SQL 文法をサポートし
SQL-92 に準拠した設計で作られています。
パッケージには
GUI でデータベースを操作できる
PosqlAdmin (データベースマネージャ) が付属されています。
また、PEAR::DB, PEAR::MDB2 抽象化レイヤーを使用して
Posql を操作できるドライバや、PHP フレームワーク CakePHP から
Posql をデータベースとして扱える DBO ドライバもパッケージに同梱されています。
SQL ステートメントは、
PDO と互換性のある プリペアドステートメントや、
バインドメカニズムを使用することができます。
Posql データベースは、多数の同時アクセスに耐えられる
排他機構 (ロック) を実装しています。
複数のプロセスからの同時アクセスにより競合が発生するような場合でも、
アトミック操作に加え テスト・アンド・セット方式によって、
常にデータベースの安定性を保持します。
Posql は、
評価式 (WHERE 句など) で PHP 構文を使用することができます。
SQL92 - 99 標準の関数、文法を使用し SQL 構文で評価することも可能です。
評価エンジン切り替え機能によって、
その式の評価のされかたを PHP モード、SQL モードと、
その時に応じて切り替えることができます。
Posql は他のライブラリやフレームワークと衝突しないよう、
グローバル空間を汚さず設計されています。
定義されるものはクラス数個のみで、
Posql* (Posql_Config, Posql_Utils, etc.)
等のクラスが定義されます。
Posql バージョン 2.11 から、 SELECT サブクエリ (副問い合わせ) が実装され 扱える SQL が大幅に広がりました。 サブクエリは SELECT, INSERT, UPDATE または DELETE の各ステートメントの中の評価式など、 式が使えるところであればどこにでも使用できます。 それにあわせて EXISTS, ANY, SOME, ALL 演算子が実装されています。 バージョン 2.15 から、 UNION, INTERSECT, EXCEPT 演算子が実装されています。 また、今まではエイリアス名を指定する演算子が AS のみだったのを改善し、 ホワイトスペース区切りでも適応可能となりました。 バージョン 2.16 では、 GROUP BY 句において、 今までは 1 つのカラム名のみ指定可能だったのを改善し、 任意の評価式を複数 指定できるようになりました。 また、日時を扱う strftime や extract 関数が実装されました。 最新バージョン 2.17 では、 SELECT の速度が 約 80% 向上したという劇的な改善がされています。 また、JavaScript の関数 escape/unescape, encodeURI/decodeURI, encodeURIComponent/decodeURIComponent が互換実装され、PHP と JavaScript 間の連携をとる際に便利になりました。 JavaScript 関数の互換実装については API マニュアル を参照ください。 クエリーキャッシュ機能も実装されています。 setUseQueryCache(true/false) をコールすることによって、 クエリをキャッシュし 高速に結果セットが得られる仕組みになっています。 その他、いくつかのバグや不具合に対して より 標準 SQL に準じた修正がされ、 広く普及している MySQL, PostgreSQL, SQLite などの DBMS, RDBMS との互換性が 高くなっています。
このドキュメントは、PHP から Posql を API として扱うため、 またクラスメソッド、プロパティの用途についてのリファレンスです。
このドキュメントは Posql で実装されている API の全てではありません。
ドキュメントに収まらない詳細は、
ソースコード "posql.php" 内の各クラスを参照してください。
Posql ソースコードは、できるかぎりわかりやすい
(変数名の省略や三項演算子を控えた) コーディングがされています。
PHPDoc と呼ばれるコメント形式も可能な限りされています。
そのためにソースコードのサイズが大きくなることは、この限りではありません。
Posql は 現バージョン (Version 2.17) では、
グローバル関数空間を使っていません。
クラスのインスタンスを生成する必要があります。
$posql = new Posql;
ここで、引数に対象のデータベースとなるファイル名を渡すと
データベースを新規で作ります。
もしすでにデータベースが存在している場合は、単にスキップされます。
コンストラクタの詳細は Posql (コンストラクタ)
を参照してください。
Posql は SQL 文法を除けば
query(),
fetch(),
isError(),
lastError()
最低限このメソッドのみで扱うことができます。
query() は 任意の SQL クエリを実行します。
fetch() は 結果セットから 1 つの列を 取り出します。
isError() は、エラーが発生しているかどうかを調べます。
lastError() は、直前のエラーメッセージを取得します。
$posql = new Posql('foo.db');
$sql = "CREATE TABLE foo (
id INTEGER PRIMARY KEY,
name VARCHAR(255) DEFAULT ''
)";
$posql->query($sql);
if ($posql->isError()) {
die($posql->lastError());
}
上のような流れで SQL ステートメントを実行することができます。
Posql がサポートする SQL 文法については、 同梱されている マニュアル Posql SQL Reference を参照してください。
続いてデータを挿入 (INSERT) します。
$sql = "INSERT INTO foo (name) VALUES ('Hello!')";
$posql->query($sql);
if ($posq->isError()) {
die($posql->lastError());
}
テーブル foo に 1 列 データを挿入しました。 それを取得 (SELECT) します。
$sql = 'SELECT * FROM foo';
$stmt = $posql->query($sql);
if ($posq->isError()) {
die($posql->lastError());
}
print "<pre>";
while ($row = $stmt->fetch()) {
print_r($row);
}
print "</pre>";
上の例では、テーブル foo から データを取得し、 ループに fetch() を使用し、 各列のデータを表示します。
以下に各メソッドの説明を記します。
$db_path = 'foo.db'; $posql = new Posql($db_path);
上の例のようにすると、'foo.db' をファイル名として (実際には その後に拡張子 .php が付加され) データベースをオープンします。
データベースは 1 つのファイルとして物理的に生成されます。
対象のディレクトリに対し 書き込み権限 (パーミッション)
がない場合は、接続タイムアウト、またはエラーになる可能性があります。
データベースとしてファイルが生成されると、
そのパーミッションは 666 (rw-rw-rw-) に設定されます。
データベースにはヘッダー情報とメタ情報が書き込まれます。
データベースの作成時、Posql はデータベースの拡張子を
.php に修正しようと試みます。
これはデータベースに対し、
ダイレクトにアクセスされた場合のセキュリティ上の対処です。
データベースは、サーバーのドキュメントルート外に置くことを推奨しますが、
環境によってはそれが不可能かもしれません。
その場合は拡張子を .php にすることが好ましいです。
必要に応じ、
setExt(), getExt()
メソッドを使用し、拡張子を変更することができます。
引数 table が文字列として、 fields が連想配列として渡されると、 table をテーブルとみなし CREATE TABLE コマンドを実行します。 もし、すでにテーブルが存在する場合でもエラーになりません。 これは IF NOT EXISTS 制約と同じ働きをします。
$db_path = 'foo.db';
$table = 'foo';
$defaults = array(
'name' => '',
'data' => NULL
);
$posql = new Posql($db_path, $table, $defaults);
このように引数を指定してインスタンスを生成すると、 次のような流れで処理されます。
データベース (foo.db) が存在しなかった場合は 以下のように処理されます。
データベース (foo.db) がすでに存在している場合は 以下のような処理になります。
戻り値は 各 SQL コマンドによって異なります。
SELECT のような結果が配列となる問い合わせを実行すると、
Posql_Statement オブジェクトのインスタンスが返ります。
Posql_Statement クラスは PHP 5 にバンドルされている
PDO (PDOStatement) クラスをモデルに設計されています。
ステートメントは PDO と互換性がある操作が可能です。
PDO の詳細については、
PHP マニュアル (PDOStatement)
を参照してください。
PDO との互換性 についての様々な操作に限らず、
PDO::FETCH_* 定数が Posql_Statement においても
同様に扱うことができます。
ステートメントの詳細は、下で解説する
Posql_Statement クラスのメソッド
を参照してください。
$posql = new Posql; $sql = "SELECT 100 * 100, 'hoge' AS hoge"; $stmt = $posql->query($sql); print $stmt->fetchAllHTMLTable();
上の例は、FROM 句を省略した SELECT コマンドを実行します。 この例の取得方法の詳細は、 下で解説する fetchAllHTMLTable を参照してください。
$posql = new Posql('foo.db');
$sql = "CREATE TABLE foo (id PRIMARY KEY, name)";
$result = $posql->query($sql);
var_dump($result);
上の例は CREATE TABLE コマンドを実行します。 この場合、出力される戻り値は TRUE もしくは FALSE になります。 基本的に Posql 側から エラーを出力することはありません。 エラーについては下で解説する isError(), lastError(), getErrors() を参照してください。
$sql = 'hoge';
$result = $posql->query($sql);
if ($posql->isError()) {
die('エラーです');
}
上の例は、不正な SQL コマンドを発行し 明示的にエラーを発生させています。 この場合、"エラーです" と出力されスクリプトは終了します。
$sql = 'hogehoge';
$result = $posql->query($sql);
if ($posql->isError()) {
die($posql->lastError());
}
上の例は、最後のエラーメッセージと共にスクリプトを終了させます。
Posql のエラー情報は スタッカブルに保持しています。 lastError() によって取得したメッセージは、 次にコールした時にはすでに破棄されています。 仮に再度 lastError をコールすると、空の文字列 ('') が返されます。
$posql = new Posql;
$posql->query('hello!');
$posql->query('how are you?');
if ($posql->isError()) {
foreach ($posql->getErrors() as $error) {
echo $error, "<br/>\n";
}
die;
}
上の例は、全てのエラーメッセージと共にスクリプトを終了させます。
引数 path をデータベースのファイル名とし、接続を試みます。 もしファイル path が存在しない場合、 createDatabase() がコールされます。 ファイルがある場合は、isDatabase() により path が有効な Posql データベースであるかチェックされます。 引数 table および fields が渡されると、 createTable() が呼ばれます。 テーブルがすでに存在する場合でもエラーと扱われません。 テーブルがない場合は、table を テーブル名、 fields を テーブルのカラム、および DEFAULT 制約 の値として作成を試みます。 成功すると TRUE、失敗時に FALSE を返します。
$posql = new Posql;
$result = $posql->open('/path/to/file.ext');
var_dump($result);
上の例は、/path/to/file.ext をデータベースファイルとして オープンまたは作成します。
引数 path をデータベースのファイル名とし、作成を試みます。 ファイルが物理的に生成されるため、 対象のディレクトリに書き込み権限がないとエラーになるかもしれません。 データベースが生成されると、ヘッダー情報とメタ情報が書き込まれます。
また、その後のカレントのデータベースは 生成されたファイルが対象にされます。 対象のデータベースは setPath(), を使用することで変更できます。 引数 perms はデータベースのファイル属性 (パーミッション) です。 デフォルトは 666 (rw-rw-rw-) ですが、 perms に任意の数値を 与えることで変更することができます。
データベースの作成時、Posql はデータベースの拡張子を
.php に修正しようと試みます。
これはデータベースに対し、
ダイレクトにアクセスされた場合のセキュリティ上の対処です。
データベースは、サーバーのドキュメントルート外に置くことを推奨しますが、
環境によってはそれが不可能かもしれません。
その場合は拡張子を .php にすることが好ましいです。
必要に応じ、
setExt(), getExt()
メソッドを使用し、拡張子を変更することができます。
成功すると TRUE、失敗時に FALSE を返します。
$posql = new Posql;
$result = $posql->createDatabase('new_db');
var_dump($result);
上の例は、new_db を Posql データベースとして新規に 作成します。 物理的には その new_db の後に拡張子 .php が付加され、 new_db.php というファイルが作成されます。
引数 table をテーブル名、 引数 fields は連想配列として キーを フィールド名、 値を DEFAULT 制約 としてのデフォルト値として テーブルを定義します。
PRIMARY KEY (主キー) を指定するには、 最初のカラム名を 引数 primary_key として渡します。 主キーであるプライマリキーは、 下で解説される rowid の参照として値を保持します。 主キーは、意図的に変更しない限り 数値型であり auto increment, UNIQUE 制約として扱われます。
成功すると TRUE、失敗時に FALSE を返します。
$db_path = 'foo.db';
$table_name = 'foo';
$defaults = array(
'id' => 0,
'name' => 'anonymous',
'text' => ''
);
$primary_key = 'id';
$posql = new Posql;
$posql->createDatabase($db_path);
if ($posql->isError()) {
die($posql->lastError());
}
$result = $posql->createTable($table_name, $defaults, $primary_key);
var_dump($result);
上の例は、'foo.db' というデータベースを作成後、 そのデータベース上に foo というテーブルを作成します。
現バージョン (2.17) では、 単独での INDEX, UNIQUE, CHECK 等は実装されていません。 そのかわり Posql には、以下の 3 つの特別なカラムがあります。
これらの特別なカラムはレコードが変化するとき、常に更新/追加されます。 また、同じ名前のカラム (例えば rowid) を生成しようとする場合、 その名前空間は Posql 側に常に上書きされます。 この 3 つの特別なカラムは、テーブル作成時にカラムの最後に追加されます。
CREATE TABLE foo (
id integer PRIMARY KEY,
name string DEFAULT '',
addr int(10) DEFAULT 0,
text string DEFAULT NULL
);
上のSQLを実行すると、foo の持つカラムは
このような順序で生成されます。
最初のカラム id に PRIMARY KEY を指定していることで、
id は rowid の参照として働きます。
describe() メソッドを使用することで、 テーブルの定義を参照することができます。
あるテーブルにおいて、カラム数や制約数が勝手に制限されることはありません。 単一の行に格納できるデータのサイズは、デフォルトで 約 2 GB です。 この数値は、行に限らず最大の列数にも影響します。 この値は getMax(), setMax() により取得、設定できます。
テーブルを削除するには dropTable() メソッドを使用します。
Posql に PHP 関数 を UDF (ユーザ定義関数) として登録します。 登録された関数は、SQL ステートメントの中からコールできます。 UDF は、SELECT および UPDATE ステートメント、主な 評価式の中など、 関数をコールできる全ての SQL ステートメントで使用可能です。
注意: SQL モード の中でのみ利用できます。
SQL モード、および PHP モードについては
getEngine(),
setEngine() を参照してください。
引数 funcname は、SQL ステートメントで使用する関数名 として 文字列で渡します。 引数 callback は、定義された SQL 関数を処理するためのコールバック関数 を指定します。 sqlite_create_function() と同じ指定の仕方で登録できます。
注意: コールバック関数は Posql で有効な型 (例えば スカラー型) を返す必要があります。
// The function is defined beforehand.
function posql_udf_crc32($value = null){
// The CRC32 function of interchangeable MySQL.
$result = null;
if ($value !== null) {
$result = sprintf('%u', crc32($value));
}
return $result;
}
// Register the UDF function as CRC32.
$posql = new Posql('foo.db');
$posql->setEngine('SQL');
$result = $posql->createFunction('crc32', 'posql_udf_crc32');
if (!$result || $posql->isError()) {
die($posql->lastError());
}
$sql = "SELECT CRC32('abc')";
$stmt = $posql->query($sql);
var_dump($stmt->fetchAll());
上の例では、MySQL 互換の CRC32 チェックサムを生成する関数を登録し、 それを実行します。 あらかじめ、setEngine() によって SQL モードにしておきます。
対象のデータベースを物理削除します。 物理削除とは、データベース (ファイル) そのものを削除するということです。 削除後、Posql によりそれを復旧することはできません。
引数 path が渡されると、 path を対象のデータベースとします。 省略された場合は、カレントのデータベースが対象になります。 カレントのデータベースは getPath(), setPath() メソッドを使用することで 取得、変更できます。
引数 force が FALSE の場合は、データベースがロック中だった場合、 ロックが解除されるまで待機します。 force が TRUE の場合、ロック状態に関係なくデータベースを削除します。 force のデフォルト値は FALSE です。
成功すると TRUE、失敗時に FALSE を返します。
$db_path = 'foo.db';
$posql = new Posql;
$posql->createDatabase($db_path);
if ($posql->isError()) {
die($posql->lastError());
}
$result = $posql->dropDatabase($db_path);
var_dump($result);
上の例は foo.db というデータベースを作成し、 作成されたとたんに削除します。
引数 table として渡されたテーブルを削除します。 データベースのメタ情報と、テーブルデータ全てが物理的に完全に削除されます。
成功すると TRUE、失敗時に FALSE を返します。
$defaults = array(
'name' => '',
'text' => ''
);
$posql = new Posql('foo.db', 'foo', $defaults);
$data = array(
'name' => 'foo',
'text' => 'Hello!'
);
$affected_rows = $posql->insert('foo', $data);
var_dump($affected_rows);
引数の rows は上の例のように、連想配列で渡します。 また、2 次元の配列を渡すこともできます。
$defaults = array(
'name' => '',
'text' => ''
);
$posql = new Posql('foo.db', 'foo', $defaults);
$data = array(
array('name' => 'foo', 'text' => 'Hi!'),
array('name' => 'bar', 'text' => 'Hello!')
);
$affected_rows = $posql->insert('foo', $data);
var_dump($affected_rows);
このようにして渡すことにより、 メモリ領域を使用するかわりに、 大量のデータを追加する際に高速化がはかれます。
また、書き込み時に ctime, utime の特殊カラムにおいて値が変化します。 それぞれ、その時の time() 値がセットされます。
影響を受けた (挿入された) 列の数が返ります。
対象のデータベースにおいて、 引数 table をテーブルとし、 引数 expr が 真 になる列を 引数 row の値どおりに変更 (アップデート) します。
$defaults = array(
'name' => '',
'text' => ''
);
$posql = new Posql('foo.db', 'foo', $defaults);
$data = array('name' => 'bar');
$expr = 'rowid = 1';
$affected_rows = $posql->update('foo', $data, $expr);
var_dump($affected_rows);
引数 expr が SQL ステートメント上での WHERE 句 になります。 expr のデフォルト値は TRUE です (すべて更新されます)。
更新された列において、 特殊カラム utime の値が変化します。 その時の time() 値がセットされます。
影響を受けた (変更された) 列の数が返ります。
対象のデータベースにおいて、 引数 table をテーブルとし、 引数 expr が 真 (TRUE) になる列を 物理削除します。
$defaults = array(
'name' => '',
'text' => ''
);
$posql = new Posql('foo.db', 'foo', $defaults);
$expr = 'rowid = 1';
$affected_rows = $posql->delete('foo', $expr);
var_dump($affected_rows);
引数 expr が SQL ステートメント上での WHERE 句 になります。 expr のデフォルト値は FALSE です (削除されません)。
影響を受けた (削除された) 列の数が返ります。
replace メソッドは、引数も含め 基本的に insert() と同じです。 違いとして、 UNIQUE 制約違反が起こった場合 制約違反の原因となった既存の行は、 現在行の INSERT に先立って削除されます。 そのため、INSERT は常に行われコマンドは通常動作を続けます。 Posql の UNIQUE 制約違反は PRIMARY KEY の衝突です。 引数である配列 row のカラムが省略された場合は デフォルト値が使われます。 デフォルト値が存在しない場合は NULL になります。
影響を受けた列の数が返ります。 これは、削除、挿入された行の総数です。 もし返り値が 1 であれば、 行が 1 つ挿入され、削除された行はないという事になります。 もし返り値が 1 よりも大きければ、 新しい行が挿入される前に、 1 つまたはそれ以上の行が削除されたという事になります。
対象のデータベースにおいて、 第一引数 table をテーブルとし、 テーブルの列を走査し、引数 expr が 真 (TRUE) になる列を取得します。
戻り値は 結果セットを保持する Posql_Statement オブジェクトのインスタンスです。
select メソッドでは 結合 (JOIN) はできません。
テーブルを結合するには、
multiSelect() メソッド を使用します。
select メソッドは引数を 1 つの連想配列として渡すことができます。 引数が多いため、配列で渡すことは有用です。
$args = array();
$args['select'] = '*';
$args['from'] = 'foo';
$args['where'] = 'rowid = 1';
$stmt = $posql->select($args);
while ($row = $stmt->fetch()) {
print_r($row);
}
上の例のように、キーを 句として 連想配列で渡すことができます。 配列のキーは、それぞれの『句』(例えば 'from') または 引数名 (例えば table) などが解釈できます。
columns は任意の評価式、カラム名を指定します。 複数指定する場合は、カンマ (,) 区切りで渡します。 columns が指定された場合は、指定されたカラム 以外を除いた配列が返ります。 また、結果セットは columns の並び順どおりになります。 columns に * を指定すると、 その 1 つの評価式は指定されたすべてのテーブルのすべてのカラムで置き換えられます。
expr は WHERE 句として扱われます。 expr が指定された場合、結果セットは expr の評価式が 真 (TRUE) となる列のみに限定されます。
group を指定すると、 結果セットの中の 1 つ以上の行を結合し、 出力時に 1 行とすることができます。 これは結果セットの中に集約関数がある場合、特に有用です。
having を指定することで、 group によってグループ化された結果セットを 評価式が真となるレコードのみに更に絞り込むことができます。 group を使用しないで having を使用することもできます。
order が指定された場合は、 結果セットは 指定されたカラムを基準に昇順 (ASC)、または降順 (DESC) にソートされます。
limit が指定された場合、 結果配列の数を limit 通りの数に限定された配列が返ります。 カンマ (,) で区切った値を指定すると、 結果セットのオフセット (,) 上限数 と、結果セットの先頭からスキップする行数を指定できます。
table (最初の引数) 以外は省略可能です。
結果は、下で解説する Posql_Statement クラスのインスタンスが返ります。
以下にいくつか例をあげます。 これらの例で使用されている 結果セットの取得方法は、 例を簡潔にするために 簡単な方法を使用しています。 結果セットの取得方法の詳細については、 fetch(), fetchAll(), fetchAllHTMLTable(), を参照してください。 (foo.db にはあらかじめ適当な列があることを想定します。)
$defaults = array(
'name' => '',
'text' => ''
);
$posql = new Posql('foo.db', 'foo', $defaults);
$stmt = $posql->select('foo');
print $stmt->fetchAllHTMLTable();
上の例は、条件式なしで全ての列が結果セットに含まれます。
$defaults = array(
'name' => '',
'text' => ''
);
$posql = new Posql('foo.db', 'foo', $defaults);
$args = array();
$args['table'] = 'foo';
$args['cols'] = 'name, text';
$args['expr'] = "name = 'foo'";
$stmt = $posql->select($args);
print $stmt->fetchAllHTMLTable();
上の例は、name というカラムが 'foo' という値に限定された結果になります。
$defaults = array(
'name' => '',
'text' => ''
);
$posql = new Posql('foo.db', 'foo', $defaults);
$args = array(
'from' => 'foo',
'col' => 'COUNT(*)'
);
$stmt = $posql->select($args);
print $stmt->fetchAllHTMLTable();
上の例は、全ての列数が結果セットに含まれます。
$defaults = array(
'name' => '',
'text' => ''
);
$posql = new Posql('foo.db', 'foo', $defaults);
$args = array(
'from' => 'foo',
'cols' => 'COUNT(*) AS cnt'
);
$stmt = $posql->select($args);
print $stmt->fetchAllHTMLTable();
上の例は、全ての列数を cnt という別名として結果セットに含みます。
$defaults = array(
'name' => '',
'text' => ''
);
$posql = new Posql('foo.db', 'foo', $defaults);
$args = array();
$args['from'] = 'foo';
$args['select'] = 'name, MAX(rowid) AS max_rowid';
$args['group'] = 'name';
$stmt = $posql->select($args);
print $stmt->fetchAllHTMLTable();
上の例は、rowid の最大値を name カラムでグループ化し、取得します。
$defaults = array(
'name' => '',
'text' => ''
);
$posql = new Posql('foo.db', 'foo', $defaults);
$args = array();
$args['from'] = 'foo';
$args['order'] = 'utime DESC, ctime DESC';
$stmt = $posql->select($args);
print $stmt->fetchAllHTMLTable();
上の例は、全ての列を取得し、 それを utime, ctime の順で降順にソートした結果セットが返ります。
$defaults = array(
'name' => '',
'text' => ''
);
$posql = new Posql('foo.db', 'foo', $defaults);
$args = array();
$args['table'] = 'foo';
$args['order'] = 'rowid';
$args['limit'] = 1;
$args['offset'] = 2;
$result = $posql->select($args);
print $stmt->fetchAllHTMLTable();
上の例は、オフセット 2 、 上限値 1 として結果を限定します。
対象のデータベースにおいて、 第一引数 tables を複数のテーブルとし、 データベースの列を走査し、引数 expr が 真 (TRUE) になる列を 結合し、連想配列として取得します。
multiSelect() メソッドも select() メソッドと同様に 引数を 1 つの連想配列として渡すことができます。 引数が多いため、配列で渡すことは有用です。
$args = array();
$args['select'] = '*';
$args['from'] = 'foo LEFT JOIN bar ON foo.col = bar.col';
$args['order'] = 'rowid DESC';
$stmt = $posql->multiSelect($args);
while ($row = $stmt->fetch()) {
print_r($row);
}
select メソッドとの違いは、tables に複数のテーブルを指定することです。 複数のテーブルは 結合演算子 (JOIN 等) を使用して結合します。
戻り値は 結果セットを保持する Posql_Statement クラスのインスタンスです。
$defaults = array(
'name' => '',
'text' => ''
);
$posql = new Posql('foo.db', 'foo', $defaults);
$data = array(
array('name' => 'foo', 'text' => 'Hi!'),
array('name' => 'bar', 'text' => 'Hello!')
);
$affected_rows = $posql->insert('foo', $data);
$posql->createTable('bar', $defaults);
if ($posql->isError()) {
die($posql->lastError());
}
$data = array(
'name' => 'bar',
'text' => 'hi, bar!'
);
$posql->insert('bar', $data);
if ($posql->isError()) {
die($posql->lastError());
}
$tables = 'foo LEFT JOIN bar USING(name)';
$stmt = $posql->multiSelect($tables);
print $stmt->fetchAllHTMLTable();
上の例では、USING(name) を使用して 結合します。
カレントのデータベースにおいて、 引数 table をテーブルを対象とし、 データベースの列を走査し、 引数 expr が 真 (TRUE) になる列数を数値で取得します。
count メソッドは、
SELECT COUNT(*) のショートカットと扱えます。
列のカウント数が数値 (int) として返ります。
$defaults = array(
'name' => '',
'text' => ''
);
$posql = new Posql('foo.db', 'foo', $defaults);
$data = array(
array('name' => 'foo', 'text' => 'Hi!'),
array('name' => 'bar', 'text' => 'Hello!')
);
$affected_rows = $posql->insert('foo', $data);
printf('<p>affected_rows: %d</p>', $affected_rows);
$count = $posql->count('foo');
printf('<p>count: %u</p>', $count);
上の例は、テーブル foo の全ての列数を取得し、表示します。
カレントのデータベースにおいて、 引数 table をテーブルを対象とし、 テーブルの情報を連想配列で取得します。 table が省略されると すべてのテーブルの情報を取得します。
テーブル名が指定されると、 結果セットには そのテーブルのカラム名、 CREATE TABLE 時の DEFAULT 制約の値が含まれます。
戻り値は 結果セットを保持する Posql_Statement クラスのインスタンスです。
$posql = new Posql('foo.db');
$stmt = $posql->describe();
var_dump($stmt->fetchAll());
上の例は、データベース foo.db の各情報を出力します。
queryf メソッドは、query() メソッドと、 sprintf() 関数を合わせたようなものです。 第一引数を フォーマット文字列、 次の引数はフォーマット文字列の引数 (変換指定子) となり、 その次の引数は、 次の変換指定子となります。 つまり可変引数になります。 引数を 1 つのみで呼び出すと、 query() メソッドを呼び出したことと同じ動作になります。
戻り値は query() メソッドと同じく、 SELECT コマンドのような結果セットが配列となる場合は すべての結果セットを保持する Posql_Statement クラスのインスタンスが返ります。 列を操作するような (INSERT, UPDATE 等の) コマンドの場合は、 影響を受けた列の数が返ります。
queryf() メソッドは sprintf() 関数の フォーマットの変換指定子のほかに、 いくつか拡張した変換指定子が利用できます。
base64_decode('encoded_string')
のように SQL ステートメントに変換します。
これは、あらゆる文字列を崩さずに 使用することが可能となります。
特に、BLOB のようなデータに有用です。
$posql = new Posql('foo.db');
$sql = "SELECT * FROM %s WHERE strlen(%s) == %1n OR %s = %q";
$stmt = $posql->queryf($sql, "foo", "bar", 123456789, "baz", "value");
var_dump($stmt->fetchAll());
// It is to be converted as follows.
// "SELECT * FROM foo WHERE strlen(bar) == 1 OR baz = 'value'";
上の例は、123456789 が、%1n によって 1 に変換されています。 また、 value に対して引用符でクォートされています。
$posql = new Posql('foo.db');
$sql = "INSERT INTO foo (name, text) VALUES (%10n, %.10q)";
$ret = $posql->queryf($sql, "123456789123456789", str_repeat("abc", 100));
var_dump($ret);
// It is to be converted as follows.
// "INSERT INTO foo (name, text) VALUES (1234567891, 'abcabc...')";
上の例は、"123456789123456789" (18 桁) が、%10n によって 10 桁 に変換されています。 また、 str_repeat("abc", 100) (300 Bytes) に対して %.10q を使用することで、 'abcabc...' となり、 ドット(.) をあわせても 10 Bytes 以下に変換されています。
// example: handle binary data
$posql = new Posql('foo.db');
$posql->createTable('image', array('name' => '', 'type' => '', 'data' => ''));
$path = "http://example.com/hoge.gif";
$type = "image/gif";
$name = "hoge.gif";
$sql = "INSERT INTO image (name, type, data) VALUES(%q, %q, %B)";
$ret = $posql->queryf($sql, $name, $type, file_get_contents($path));
// it will be like convert below
// "INSERT ... VALUES('hoge.gif', 'image/gif', base64_decode('omit...'))";
上の例は、%B を使用することで BLOB を base64 で一旦エンコードしてから、 パーサーに渡す文字列は 自動的にデコードされるように変換されます。
$posql = new Posql('foo.db');
$sql = "INSERT INTO foo (text) VALUES (%q)";
$ret = $posql->queryf($sql, "I'm feeling happy!");
var_dump($ret);
// to "INSERT INTO foo (text) VALUES ('I\'m feeling happy!')";
上の例は、 シングルクォート (') を含む文字列がエスケープされ、その文字列を 引用符で囲いクォートしています。
exec メソッドは INSERT, UPDATE のような、 結果セットを含まない SQL ステートメントを実行する際に使用します。
query() メソッドでも 同じ結果になる場合が殆どかもしれません。 このメソッドは必ず スカラー型 (数値) を返す点が異なります。 また、PDO との互換性のために実装されたメソッドでもあります。
Posql_Statement::execute() メソッドによって実行される SQL ステートメントを準備します。 SQL ステートメントは、文が実行されるときに実際の値に置き換えられる 0 個もしくはそれ以上の名前 (:name) もしくは疑問符 (?) パラメータマークを含むことができます。
PDO と同等の扱いができます。
戻り値は、 SQL ステートメントを保持する Posql_Statement オブジェクトが返ります。
$sql = 'SELECT name, colour, calories
FROM fruit
WHERE calories < :calories AND colour = :colour';
$stmt = $posql->prepare($sql);
$stmt->execute(array(':calories' => 150, ':colour' => 'red'));
$red = $stmt->fetchAll();
$stmt->execute(array('calories' => 175, 'colour' => 'yellow'));
$yellow = $stmt->fetchAll();
上の例は、名前付きパラメータを用いて SQL ステートメントを準備します。
$sql = 'SELECT name, colour, calories
FROM fruit
WHERE calories < ? AND colour = ?';
$stmt = $posql->prepare($sql);
$stmt->execute(array(150, 'red'));
$red = $stmt->fetchAll();
$stmt->execute(array(175, 'yellow'));
$yellow = $stmt->fetchAll();
上の例は、疑問符パラメータを用いて SQL ステートメントを準備します。
SQL ステートメントの中で 文字列が安全に処理できるようにエスケープします。
対象の文字列 string を渡します。 渡された値は、その型によって適切にエスケープされます。 文字列の場合は、引用符(') で囲われます。
エスケープされた文字列が返ります。
vacuum メソッドは SQLite における拡張機能であり、 それは PostgreSQL における同様のコマンドをモデルにした機能であり、 その機能をモデルにした Posql の拡張機能です。 vacuum が実行されると、そのときに対象とされているデータベースを 物理的に最適化することとみなし、それを実行します。
vacuum は、スクリプトの終了時に自動的に呼ばれます。 何か特別な処理をしない限り、明示的に実行する必要はありません。
成功時に TRUE、失敗時に FALSE が返ります。
トランザクションを開始します。 トランザクションブロックが開始された以降の SQL ステートメントは全て、 明示的な commit() もしくは rollBack() が実行されるまで、 単一のトランザクションブロックの中で実行されます。
Posql は Version 2.09 から、ロールバックやアトミックなコミットを伴う トランザクションをサポートしました。
トランザクションは、そのブロック間のデータベースの処理が 『全て実行される』か、『全て実行されない』かのどちらかになります。
Posql は現時点 (Version 2.17) では ネストしたトランザクションをサポートしていません。 トランザクションの中で別のトランザクションを開始しようとすると エラーになります。
トランザクション中の createDatabase(), dropDatabase() は例外であり、トランザクションのサポート対象にはなりません。
トランザクションのブロック内で 複数の SQL ステートメントを実行することは、 確実にデータの一貫性を保つために役立ちますが、 トランザクション開始時および終了時には 一時的に処理速度や、ディスク使用量に影響がでます。
Posql は現時点 (Version 2.17) で 一時ファイルを生成することはありません。 それはトランザクション時も同じで、 すべて 1 つのデータベース (ファイル) 内で 一時的なバックアップ領域や更新、削除領域を作り、処理しています。 そのため、とくにトランザクションでは処理速度の低下などに影響がでてしまいます。
データベースの操作時に、適切なロック処理 (排他処理) は自動的に行われます。 一貫性を保つための必要性がない限り、 Posql を扱う上でトランザクションは頻繁に行う必要ありません。
成功時に TRUE、失敗時に FALSE が返ります。
現在のトランザクション ブロック内で行われた全ての処理を 恒久的なものとして確定し、 処理結果が全てデータベースに実際に反映され、トランザクションを終了します。
トランザクションをアボートするには rollBack() を使用してください。 トランザクションが開始されていない状態で commit() を実行しても特に問題はありませんが、エラーが発生します。
成功時に TRUE、失敗時に FALSE が返ります。
beginTransaction() によって開始された トランザクションをロールバックし、 そのトランザクション ブロック内で行われた全ての更新を廃棄し、 トランザクションを終了します。
トランザクションを正常に終了させるには commit() を使用してください。 トランザクションが開始されていない状態で rollBack() を実行しても問題はありませんが、エラーが発生します。
成功時に TRUE、失敗時に FALSE が返ります。
getPager メソッドは、 デフォルトで組み込まれているページャークラス Posql_Pager のオブジェクトインスタンスを設定・取得します。
引数 total_count は、列の総数を渡します。 引数 curpage は、現在のページ番号を渡します。 引数 perpage は、1 ページ内のアイテム数を渡します。 引数 range は、ウィンドウ内のページャーリンクの個数を渡します。
ページャーのページ番号は 1 から始まります。
Posql_Pager オブジェクトのインスタンスが返ります。
Posql_Pager クラスのプロパティは以下のように構成されています。
以下はページャーの設置例です。
<?php
$posql = new Posql('pager_sample');
$sql = "CREATE TABLE IF NOT EXISTS pages (
id INTEGER PRIMARY KEY,
msg TEXT
)";
$posql->exec($sql);
$stmt = $posql->query("SELECT COUNT(*) FROM pages");
$count = $stmt->fetchColumn(0);
if (!$count) {
// 1000 件インサート
$data = array();
for ($i = 1; $i <= 1000; $i++) {
$data[] = array(
'msg' => sprintf('current page is %d.', $i)
);
}
$count = $posql->insert('pages', $data);
}
$curpage = 1;
if (isset($_GET['page']) && is_numeric($_GET['page'])) {
$curpage = $_GET['page'];
}
// 1 ページに表示する件数
$perpage = 5;
// ページ内のリンクの個数
$range = 10;
// ページャーを生成
$pager = $posql->getPager($count, $curpage, $perpage, $range);
// データを取得
$sql = "SELECT * FROM pages LIMIT ? OFFSET ?";
$stmt = $posql->prepare($sql);
$stmt->execute(array($pager->limit, $pager->offset));
$stmt->setFetchMode('assoc');
?>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Posql Pager Sample</title>
<style>
* {
font-family: verdana;
}
.pager li {
display: block;
float: left;
margin: 5px;
padding: 0;
border: 1px solid #999;
}
.pager a {
display: block;
margin: 0;
padding: 4px 8px;
font-size: x-small;
text-decoration : none;
color: #333;
}
.pager a:hover {
color: #333;
background: #ccccff;
text-decoration: none;
}
</style>
</head>
<body>
<h1>Posql Pager Sample</h1>
<hr>
<?php while ($row = $stmt->fetch()): ?>
<div>
<?php printf('id:%d msg:%s', $row['id'], $row['msg']) ?>
</div>
<hr>
<?php endwhile; ?>
<?php /* ここからページャー */ ?>
<ul class="pager">
<?php if ($pager->currentPage != 1): ?>
<li><a href="index.php?page=1"><<</a></li>
<?php endif; ?>
<?php if ($pager->prev): ?>
<li><a href="index.php?page=<?php echo $pager->prev ?>"><</a></li>
<?php endif; ?>
<?php foreach ($pager->pages as $page): ?>
<li><a href="index.php?page=<?php echo $page?>"><?php echo $page?></a></li>
<?php endforeach; ?>
<?php if ($pager->next): ?>
<li><a href="index.php?page=<?php echo $pager->next ?>">></a></li>
<?php endif; ?>
<?php if ($pager->currentPage != $pager->totalPages): ?>
<li><a href="index.php?page=<?php echo $pager->totalPages ?>">>></a></li>
<?php endif; ?>
</ul>
<?php /* ここまでページャー */ ?>
</body>
</html>
Posql データベース に直近に挿入されたレコードの rowid の値を返します。 接続上において、まだ挿入されていない場合は NULL が返ります。
このメソッドで返される値は、下で解説する getLastInsertId() と同じです。 PDO との互換性のために提供されています。
Posql_Statement クラスは、 SQL ステートメントの結果セットの操作や バインドメカニズム (bind*) を可能とするクラスです。
Posql_Statement は PHP 5.1* から標準でバンドルされている
PDO をモデルに設計されています。
PDO の詳細については、
PHP マニュアル (PDOStatement)
を参照してください。
PDO との互換性 についての様々な操作に限らず、
PDO::FETCH_* 定数が Posql_Statement においても
同様に扱うことができます。
引数 fetch_mode に 取得方法を指定することができます。
取得方法には、文字列で直接指定することができます。(例: 'ASSOC')
文字列で渡した際に 大文字小文字の区別はされません。
fetch_mode に、PDO::FETCH_* 定数を使用することも可能です。
引数 args_1, args_2 は、それぞれの取得方法に渡す引数を指定します。
返り値は、取得形式によって異なります。 失敗した場合は FALSE を返します。
$stmt = $posql->prepare('SELECT name, colour FROM fruit');
$stmt->execute();
print 'FETCH_ASSOC:';
$result = $stmt->fetch('assoc'); // or PDO::FETCH_ASSOC
var_dump($result);
print 'FETCH_BOTH:';
$result = $stmt->fetch('both'); // or PDO::FETCH_BOTH
var_dump($result);
print 'FETCH_COLUMN';
$result = $stmt->fetch('column'); // or PDO::FETCH_COLUMN
var_dump($result);
print 'FETCH_OBJ';
$result = $stmt->fetch('obj'); // or PDO::FETCH_OBJ
var_dump($result);
上の例は、いくつかの異なる取得方法で行を取得します。
引数 fetch_mode は、
上で解説されている
fetch() メソッドと
同じ取得方法を指定することができます。
fetch_mode に PDO::FETCH_* 定数を渡すこともできます。
Posql では、拡張された取得方法として 'HTMLTable' を渡すことができます。 (大文字小文字の区別はされません)
'HTMLTable' についての詳細は、下で解説する fetchAllHTMLTable() を参照してください。 結果として、このメソッドを使用した場合と同じになります。
返り値は、取得形式によって異なります。 失敗した場合は 空の配列 ( array() ) が返ります。
$stmt = $posql->prepare('SELECT name, colour FROM fruit');
$stmt->execute();
$result = $stmt->fetchAll();
var_dump($result);
上の例は、結果セットに残っている全ての行を表示します。
引数 caption に <caption> 要素を指定することができます。 引数 attr には、<table> 要素の属性 (attributes) が指定できます。 この 2 つの引数は、順序が異なっていても適切に処理されます。
列に含まれる 文字列は HTML 実体 (entity) として escapeHTML() メソッドによってエスケープされます。
返り値は、全ての列を含む table 要素の文字列です。
$sql = "SELECT 1, NULL, TRUE, FALSE, 'hoge', 'I''m feeling happy!' AS happy";
$stmt = $posql->prepare($sql);
$stmt->execute();
$result = $stmt->fetchAllHTMLTable($sql,
array(
'border' => 1,
'class' => 'my-class',
'style' => array(
'padding' => '5px',
'color' => '#333',
'background' => '#fff'
)
)
);
print $result;
上の例のように属性を設定することができます。 属性は 'border=1' のような文字列でも適応されます。
準備されたプリペアドステートメントを実行します。 引数 params を指定する場合は、 実行される SQL 文の中のバインドパラメータと同数の要素からなる 値の配列を渡します。
他のメソッドと同様に PDOStatement::execute() と同じ操作ができます。
成功すると TRUE, 失敗時に FALSE を返します。
$sql = "SELECT * FROM foo WHERE name = ? OR rowid = ? ";
$stmt = $posql->prepare($sql);
$stmt->execute(array('foo', 1));
print $stmt->fetchAll('HTMLTable');
上の例は、疑問符(?) プレースホルダ を伴う プリペアドステートメントを実行します。
準備された SQL ステートメント中で、 対応する名前 (:name) もしくは 疑問符 (?) プレースホルダに パラメータをバインドします。 bindValue() と異なり、 変数は参照としてバインドされ、 execute() がコールされたときのみ評価されます。
他のメソッドと同様に PDOStatement::bindParam() と同じ操作ができます。
※ 引数 type, length は実装されていません。指定しても単に無視されます。
成功すると TRUE, 失敗時に FALSE を返します。
$calories = 150;
$colour = 'red';
$stmt = $posql->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < :calories AND colour = :colour');
$stmt->bindParam(':calories', $calories);
$stmt->bindParam(':colour', $colour);
$stmt->execute();
上の例は、名前付けされたプレースホルダ (:name) を用いて バインドされた PHP 変数によって プリペアドステートメントを実行します。
$calories = 150;
$colour = 'red';
$stmt = $posql->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < ? AND colour = ?');
$stmt->bindParam(1, $calories);
$stmt->bindParam(2, $colour);
$stmt->execute();
上の例は、疑問符 (?) プレースホルダを用いて バインドされた PHP 変数によって プリペアドステートメントを実行します。
プリペアドステートメントで使用する SQL 文の中で、 対応する名前 (:name) あるいは疑問符 (?) のプレースホルダに値をバインドします。
他のメソッドと同様に PDOStatement::bindValue() と同じ操作ができます。
※ 引数 type, length は実装されていません。指定しても単に無視されます。
成功すると TRUE, 失敗時に FALSE を返します。
$calories = 150;
$colour = 'red';
$stmt = $posql->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < :calories AND colour = :colour');
$stmt->bindValue(':calories', $calories);
$stmt->bindValue(':colour', $colour);
$stmt->execute();
上の例は、 名前付けされたプレースホルダ (:name) を用いて バインドされた値によって プリペアドステートメントを実行します。
$calories = 150;
$colour = 'red';
$stmt = $posql->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < ? AND colour = ?');
$stmt->bindValue(1, $calories);
$stmt->bindValue(2, $colour);
$stmt->execute();
上の例は、疑問符 (?) プレースホルダを用いて バインドされた 値によって プリペアドステートメントを実行します。
SQL クエリからの結果セット中にある カラムにバインドされた 特定の値を取得するための準備をします。 fetch() もしくは fetchAll() がコールされる度に、 カラムにバインドされた全ての変数は更新されます。
注意: カラムに関する情報は ステートメントが実行 (execute) されるまで利用できません。
他のメソッドと同様に PDOStatement::bindColumn() と同じ操作ができます。
※ 引数 type, length は実装されていません。指定しても単に無視されます。
引数 column には、 結果セットに含まれる ( 1 から始まる) カラム番号 もしくはカラム名を指定します。 カラム名を使用する場合、 大文字小文字が一致する必要があります。
引数 var は、参照渡しとなり カラムがバインドされる PHP 変数を指定します。
成功すると TRUE, 失敗時に FALSE を返します。
// Declare the variables beforehand.
$id = null;
$name = null;
$utime = null;
// Execute the prepare-statements
$posql = new Posql('foo.db');
$sql = "SELECT id, name, utime FROM foo";
$stmt = $posql->prepare($sql);
$stmt->execute();
// Bind with the columns index
$stmt->bindColumn(1, $id);
$stmt->bindColumn(2, $name);
// Bind with the columns name
$stmt->bindColumn('utime', $utime);
// Loop by fetch
while ($stmt->fetch()) {
print '[id] ' . $id;
print '[name] ' . $name;
print '[utime] ' . $utime;
print '<hr>';
}
上の例は、バインドした結果セットを PHP 変数に出力します。 (あらかじめ foo.db には何らかのデータがあることを想定します)
setFetchMode メソッドでデフォルトフェッチモードを設定しておくと、 fetch(), fetchAll() をコールする際に引数を渡す必要がなくなります。 引数 fetch_mode で設定されたフェッチモードがデフォルトとなり、 各フェッチメソッドに設定が引き継がれます。
引数 fetch_mode に 取得方法を指定することができます。
取得方法には、文字列で直接指定することができます。(例: 'ASSOC')
文字列で渡した際に 大文字小文字の区別はされません。
fetch_mode に、PDO::FETCH_* 定数を使用することも可能です。
引数 args_1, args_2 は、 それぞれの取得方法に渡す引数を指定することができます。
他のメソッドと同様に PDOStatement::setFetchMode() と同じ操作ができます。
成功すると TRUE, 失敗時に FALSE を返します。
class Posql_Fetch_Class_Sample {
function Posql_Fetch_Class_Sample($arg1 = null, $arg2 = null){
print ' new Posql_Fetch_Class_Sample(';
var_dump($arg1);
var_dump($arg2);
print ')';
}
}
$posql = new Posql;
$sql = "SELECT 1 c1, 2 c2, 3 c3
UNION
SELECT 4, 5, 6
UNION
SELECT 7, 8, 9
UNION
SELECT 10, 11, 12
UNION
SELECT 13, 14, 15";
$stmt = $posql->prepare($sql);
$stmt->execute();
print 'FETCH_ASSOC:';
$stmt->setFetchMode('assoc'); // or PDO::FETCH_ASSOC
$result = $stmt->fetch();
var_dump($result);
print 'FETCH_BOTH:';
$stmt->setFetchMode('both'); // or PDO::FETCH_BOTH
$result = $stmt->fetch();
var_dump($result);
print 'FETCH_COLUMN';
$stmt->setFetchMode('column'); // or PDO::FETCH_COLUMN
$result = $stmt->fetch();
var_dump($result);
print 'FETCH_OBJ';
$stmt->setFetchMode('obj'); // or PDO::FETCH_OBJ
$result = $stmt->fetch();
var_dump($result);
print 'FETCH_CLASS';
$stmt->setFetchMode('class', // or PDO::FETCH_CLASS
'Posql_Fetch_Class_Sample',
array('arg1_sample', 'arg2_sample'));
$result = $stmt->fetch();
var_dump($result);
上の例は、いくつかの異なる取得方法で行を取得します。
引数 column_key には、 行から処理したい 0 から始まるカラム番号、 または文字列でカラム名を指定します。 省略された場合は最初のカラムをフェッチします。
行がもうない場合は FALSE を返します。
fetchColumn メソッドは、 fetch('column', column_key); と指定してフェッチしたことと同じです。
他のメソッドと同様に PDOStatement::fetchColumn() と同じ操作ができます。
引数 class_name には、生成するクラス名を渡します。 引数 class_args には、クラスのコンストラクタに与えたい引数を配列で渡します。
class_name のデフォルトは stdClass です。
行がもうない場合、あるいはエラー時に FALSE を返します。
fetchObject メソッドは、
fetch('class', class_name, class_args);
または
fetch('object');
と指定してフェッチしたことと同じです。
他のメソッドと同様に PDOStatement::fetchObject() と同じ操作ができます。
rowCount は 相当する ステートメント オブジェクトによって実行された 直近の DELETE, INSERT, UPDATE 文によって作用した行数を返します。
他のメソッドと同様に PDOStatement::rowCount() と同じ操作ができます。
ステートメント オブジェクトに相当する結果セットにあるカラム数を返します。
他のメソッドと同様に PDOStatement::columnCount() と同じ操作ができます。
Posql_Statement クラスは PDO (PDOStatement) と互換性がありますが、 PEAR::MDB2 と互換性のあるメソッドも含まれています。 このドキュメントでは解説されていませんが、 getColumnNames(), fetchRow(), numRows(), numCols(), hasRows(), free() 等のメソッドが利用できます。
より詳しい情報については、ソースコード 内の Posql_Statement クラスを参照してください。
Posql_Charset クラスは、文字コードを扱うライブラリです。 拡張モジュール mbstring, iconv の順で、 どちらかが有効であれば優先して使い、どちらも無効の場合は PHP コードで書かれた独自メソッドを使い文字コードの判別を行います。
mbstring ライブラリは、特定の Unicode (UTF-16, UTF-32) に対応していなかったり、サロゲートペアの妥当性があったりします。 iconv ライブラリは、正当な文字しか認識しないため 不正なキャラクタが現れるとエラーを発生させたりします。 Posql_Charset クラスは、それぞれの特徴を補完して 文字コードを判断、もしくは変換します。
mbstring では 'SJIS-win'、 iconv では 'CP932' (SJIS-open) という違いについても Posql_Charset クラスは広くマッピングし、 どちらの指定でも対応できる実装をしています。
Posql_Charset クラスは、Posql のインスタンスから
pcharset としてアクセスできるため、
メソッドの定義には Posql->pcharset->method()
と表現します。
引数 encodings が単一の文字コードを示す文字列で渡されると、 その文字コードかどうかが検出されます。 encodings が省略されるか、'auto' として渡されると 自動で文字コードを検出します。 'auto' の大文字小文字の区別はされません。 複数の文字コードを指定するには、配列 またはカンマ(,) で区切った文字列で指定します。
検出された文字コードが返ります。 失敗またはエラー時に FALSE が返ります。
以下は、戻り値となる文字コードのリストです。
引数はすべて文字列として扱います。 引数 string を 文字エンコーディング from から to に変換して返します。
引数 to を省略すると 'UTF-8' に変換されます。 引数 from を省略、または 'auto' を渡すと 自動で内部文字エンコーディングを検出し、to に変換します。 'auto' の大文字小文字の区別はされません。
拡張モジュール mbstring が有効なら、 mb_convert_encoding() を使います。mbstring が無効で 拡張モジュール iconv が有効の場合は iconv() によって変換されます。 変換できなかった場合は FALSE が返ります。
このメソッドは、mb_convert_encoding() と同じ引数の渡しかたができます。
$posql = new Posql;
$encodings = array(
'EUC-JP',
'SJIS',
'JIS',
'UTF-8',
'UTF-16',
'UTF-32'
);
$string = 'あいうえおabcdef';
foreach ($encodings as $charset) {
$string = $posql->pcharset->convert($string, $charset);
$encoding = $posql->pcharset->detectEncoding($string);
$result = array(
"to_encoding" => $charset,
"detect_encoding" => $encoding,
"converted_string" => $string
);
// All right, if "to_encoding" equaled "detect_encoding".
print "<pre>";
var_dump($result);
print "</pre>";
}
Posql_ECMA クラスは、 PHP 上で JavaScript の関数・メソッドを互換実装したクラスです。 (ECMA-262 3rd edition)
Posql Version 2.17 現在、 UTF-8 での妥当性を確認しています。
ソースのほとんどは、 SpiderMonkey からヒントを得ています。
Posql_ECMA は、PHP と JavaScript 間の値の渡し合い、 連携を行う際に有用かつ便利なライブラリです。
Posql_ECMA クラスは、Posql のインスタンスから
プロパティ ecma としてアクセスできるため、
メソッドの定義には Posql->ecma->method()
と表現します。
なお、ドキュメントに不足と思われる項目については Core JavaScript リファレンス から参照ください。
文字列における文字は左から右の方向にインデックス化されます。 一番最初の文字のインデックスは 0 です。 与える index が範囲外の場合、空文字列を返します。
以下の例は、'c' という文字列を返します。
$posql = new Posql;
echo $posql->ecma->charAt('abcde', 2);
Unicode コードポイントの範囲は、0 から 1,114,111 (0x10FFFF) です。 最初の 128 の Unicode コードポイントは、ASCII 文字エンコーディングに直接対応しています。 charCodeAt は常に 65,536 (2 の16乗) より小さい値を返すであろうことに注意してください。 与えられたインデックスが 0 と 文字列の長さの間にない場合、charCodeAt は NaN を返します。
Unicode の値の指定のシーケンスを使用することによって生成された文字列を返します。
以下の例は、'ABC' という文字列を返します。
$posql = new Posql; echo $posql->ecma->fromCharCode(65, 66, 67);
文字列 string の中で、 指定された値 search が最初に現れたインデックスを返します。 offset から検索を始め、値が見つけられない場合、-1 を返します。 最初の文字の位置は 0 です。
$posql = new Posql;
echo $posql->ecma->indexOf('abcde', 'a'); // output: 0
echo $posql->ecma->indexOf('abcde', 'c'); // output: 2
echo $posql->ecma->indexOf('abcde', 'c', 2); // output: 2
文字列 string の中で、 指定された値が最後に現れるインデックスを返します。 値が見つけられない場合、-1 を返します。 呼び出す文字列は、offset から検索を始め、逆方向に検索されます。 最初の文字の位置は 0 です。
$posql = new Posql;
echo $posql->ecma->lastIndexOf('foobarbaz', 'a'); // output: 7
echo $posql->ecma->lastIndexOf('foobarbaz', 'z'); // output: 8
echo $posql->ecma->lastIndexOf('foobarbaz', 'a', 5); // output: 4
echo $posql->ecma->lastIndexOf('foobarbaz', 'x'); // output: -1
length は JavaScript/ECMAScript では、 プロパティですが、メソッドとして実装されています。
文字列における文字の数を Unicode 単位で返します。 空文字列の場合、length は 0 です。
$posql = new Posql;
echo $posql->ecma->length('abcdef'); // output: 6
echo $posql->ecma->length('あいう'); // output: 3
slice メソッドは、1 つの文字列からテキストを取り出し、新しい文字列を返します。 一方の文字列におけるテキストへの変更は、他の文字列に影響を与えません。 slice メソッドは、end を含まずにテキストを取り出します。 slice($string, 1, 4) は、2 番目から 4 番目までの文字 (1 番目、2 番目、3 番目にインデックスされた文字) を取り出します。 負の数のインデックスを指定したときは、end は文字列の最後からのオフセットを示します。 slice($string, 2, -1) は、3 番目の文字から、 文字列の最後の文字から数えて 2 番目の文字までを取り出します。
$posql = new Posql;
echo $posql->ecma->slice('abcdef', 1); // output: bcdef
echo $posql->ecma->slice('abcdef', -2); // output: ef
echo $posql->ecma->slice('abcdef', 2, 4); // output: cd
echo $posql->ecma->slice('abcdef', -2, 5); // output: e
split メソッドは、新しい配列を返します。 split メソッドが新しい配列を文字列から取り出すとき、 separator は文字列から削除され、部分文字列から成る配列が返ります。 separator が空の文字列 ('') であるとき、 split メソッドは、空の配列ではなく、1 つの空文字列を含む配列を返します。
$posql = new Posql;
var_export($posql->ecma->split('foo bar baz', ' '));
// output:
// array ( 0 => 'foo', 1 => 'bar', 2 => 'baz', )
var_export($posql->ecma->split('foo bar baz', 'a'));
// output:
// array ( 0 => 'foo b', 1 => 'r b', 2 => 'z', )
var_export($posql->ecma->split('foo bar baz', ''));
// output:
// array ( 0 => 'f', 1 => 'o', 2 => 'o', 3 => ' ',
// 4 => 'b', 5 => 'a', 6 => 'r', 7 => ' ',
// 8 => 'b', 9 => 'a', 10 => 'z', )
start は文字のインデックスです。 一番最初の文字のインデックスは 0 で、 最後の文字のインデックスは、文字列の長さから 1 を引いた数です。 substr は start から文字の取り出しを開始し、length 個の文字を集めます (start から文字列の最後までの長さが指定した length より短かった場合は、 length より少ない数の文字を返します)。
start が正の数かつ文字列の長さ以上である場合、substr は空の文字列を返します。 start が負の数である場合、substr はそれを文字列の最後から数えた文字のインデックスとして使用します。 start が負の数かつ start の絶対値が文字列の長さより大きい場合、 substr は開始インデックスとして 0 を使用します。
length が 0 あるいは負の数の場合、 substr は空の文字列を返します。 length が省略された場合、start から文字列の最後までの文字を取り出します。
$posql = new Posql; $string = 'abcdefghij'; var_dump($posql->ecma->substr($string, 1, 2)); // output: 'bc' var_dump($posql->ecma->substr($string, -2, 2)); // output: 'ij' var_dump($posql->ecma->substr($string, 1)); // output: 'bcdefghij' var_dump($posql->ecma->substr($string, -20, 2)); // output: 'ab' var_dump($posql->ecma->substr($string, 20, 2)); // output: ''
substring は begin から end 未満の文字を取り出します。特に、
begin が end より大きかった場合、substring は 2 つの引数が交換されたものとして実行されます。
例えば、substring($string, 1, 0) == substring($string, 0, 1) です。
$posql = new Posql; $string = 'abcdefghij'; var_dump($posql->ecma->substring($string, 1)); // output: 'bcdefghij' var_dump($posql->ecma->substring($string, -2)); // output: 'abcdefghij' var_dump($posql->ecma->substring($string, 2, 5)); // output: 'cde' var_dump($posql->ecma->substring($string, 5, 2)); // output: 'cde' var_dump($posql->ecma->substring($string, -2, 5)); // output: 'abcde' var_dump($posql->ecma->substring($string, 0, 0)); // output: '' var_dump($posql->ecma->substring($string, 20, 2)); // output: 'cdefghij'
toLowerCase メソッドは、小文字に変換された文字列の値を返します。 toLowerCase メソッドは、文字列の値、それ自身には影響を与えません。
$posql = new Posql;
var_dump($posql->ecma->toLowerCase('ABCdefG')); // output: 'abcdefg'
toUpperCase メソッドは、大文字に変換された文字列の値を返します。 toUpperCase メソッドは、文字列の値、それ自身には影響を与えません。
$posql = new Posql;
var_dump($posql->ecma->toUpperCase('abcDEFg')); // output: 'ABCDEFG'
引数で与えられた値を表す文字列を返します。
toString メソッドは、コードとして有効な表現を返すとは限りません。 文字列として表現を返すだけです。 JavaScript/ECMAScript との互換性のため提供されています。
escape および unescape 関数は文字列をエンコードしたりデコードしたりします。 escape 関数は ISO Latin 文字セットで表された引数の 16 進エンコーディングを返します。 unescape は指定した 16 進エンコーディングの値に対する ASCII 文字列を返します。
escape および unescape 関数は 非 ASCII 文字に対しては正しく機能せず、非推奨です。 互換性のため提供されています。
escape および unescape 関数は文字列をエンコードしたりデコードしたりします。 escape 関数は ISO Latin 文字セットで表された引数の 16 進エンコーディングを返します。 unescape は指定した 16 進エンコーディングの値に対する ASCII 文字列を返します。
escape および unescape 関数は 非 ASCII 文字に対しては正しく機能せず、非推奨です。 互換性のため提供されています。
特定の文字の実体を UTF-8 文字エンコーディングで表された 1 つ、2 つ、 あるいは、3 つのエスケープシーケンスに置き換えることで、 統一資源識別子 (Uniform Resource Identifier (URI)) をエンコードします。
URI は完全な URI であることが想定されます。 そして、URI において特別な意味を持つ予約された文字 (reserved characters) はエンコードされません。
encodeURI は、それ自身では、XMLHttpRequest などのための、 適切な HTTP GET 及び POST リクエストを作成できないことに注意してください。 なぜなら、encodeURI では、GET 及び POST リクエスト において特別な文字として扱われる、 '&', '+', '=' がエンコードされないからです。 ですが、encodeURIComponent は、 これらの文字をエンコードします。
特定の文字の実体を、UTF-8 文字エンコーディングで表された 1 つ、2 つ、あるいは、 3 つのエスケープシーケンスに置き換えることで、 統一資源識別子 (Uniform Resource Identifier (URI)) の要素をエンコードします。
URI は完全な URI であることが想定されます。 そして、URI において特別な意味を持つ予約された文字 (reserved characters) はエンコードされません。
encodeURIComponent は、 次を除く全ての文字をエスケープします: アルファベット、数字、- _ . ! ~ * ' ( )
encodeURI、 もしくはそれに類似したルーチンによって作成された 統一資源識別子 (Uniform Resource Identifier (URI)) をデコードします。
エンコードされた URI 内のエスケープシーケンスをそれぞれが表す文字に置き換えます。 encodeURI によってエンコードされていないであろうエスケープシーケンスは、デコードされません。
encodeURIComponent、 もしくはそれに類似したルーチンによって作成された 統一資源識別子 (Uniform Resource Identifier (URI)) の要素をデコードします。
エンコードされた URI の要素内のエスケープシーケンスをそれぞれが表す文字に置き換えます。
Posql_Archive クラスは、圧縮・解凍やアーカイブを扱うクラスです。
Posql Version 2.17 現在、 AlphamericHTML を実装しています。
AlphamericHTML は、 文字列を LZ77 アルゴリズムにより圧縮・解凍し、 エンコードされた値は英数字 [0-9A-Za-z_] (AlphamericString) のみからなる文字列になります。
Posql_Archive クラスは、Posql のインスタンスから
プロパティ archive としてアクセスできるため、
メソッドの定義には Posql->archive->method()
と表現します。
引数 s を対象の文字列とし、 AlphamericHTML 形式でエンコードします。
AlphamericHTML は、 文字列を LZ77 アルゴリズムにより圧縮・解凍し、 エンコードされた値は英数字 [0-9A-Za-z_] (AlphamericString) のみからなる文字列になります。
エンコードされた文字列が返ります。
引数 a を対象の文字列とし、 AlphamericHTML 形式でデコードします。
デコードされた文字列が返ります。
下の例では、 文字列が圧縮され AlphamericString に変換されていることがわかります。
$posql = new Posql; $string = 'Hello,Hello,abcabcabcabcabcabc'; echo '<div>original string:</div>'; var_dump($string); // 'Hello,Hello,abcabcabcabcabcabc' $encode = $posql->archive->encodeAlphamericString($string); echo '<div>encodeAlphamericString:</div>'; var_dump($encode); // 'Y8Z5CCFXC_v4Z123_yD' $decode = $posql->archive->decodeAlphamericString($encode); echo '<div>decodeAlphamericString:</div>'; var_dump($decode); // 'Hello,Hello,abcabcabcabcabcabc' echo '<div>compare:</div>'; var_dump($string === $decode); // true
Posql は、現バージョン (2.17) では設定ファイルや .ini ファイルなど 外部ファイルによる 初期設定を一切 必要としません。
もし何かしらの設定変更が必要な場合は、 以下で解説する各メソッドから変更することができます。
引数 tolower が 真 (TRUE) として渡された場合は、 すべて小文字で返されます。 デフォルト (FALSE) はすべて大文字で返されます。
現バージョン (Version 2.17) では、以下のエンジンがサポートされています。
デフォルトの評価エンジンは SQL モード です。
実行エンジンは、 SQL ステートメント中以外なら、どのタイミングでも 何度でも切り替え可能です。 複雑な処理が必要になった場合は PHP。 セキュリティのために、また SQL 文法の互換性のため SQL、と自由に変更できます。
大文字小文字の区別はされません。
設定に成功すると 設定する前の実行エンジン を文字列で返します。 失敗 (サポートされていないエンジン) の場合は、FALSE を返します。
Posql の PHP モード中での SQL ステートメントで使える関数は、 すべて 実行中の PHP に依存します。 関数の中には 意図しない関数が多く含まれるかもしれません。 そのため、ファイル IO、入出力、その他のプログラム制御関数の一部は デフォルトで使用不可になっています。 これは最低限の SQL ステートメントに対するバリデートです。 これらの関数についての詳細は ソースコード内のクラス 'Posql_Config' における $disableFuncs にデフォルト状態が記されていますが、 このメソッドを利用することで取得できます。
戻り値は、禁止関数が全て含まれた配列です。
Posql の PHP モード中での SQL ステートメントで禁止する関数を設定します。 配列で 1 つ以上の、または 文字列として関数名 func を渡します。
禁止関数をすべてクリア (削除) するには、引数に何も渡さずにコールします。
戻り値は、追加または削除された禁止関数の数です。
$posql = new Posql('foo.db');
$posql->setEngine('PHP');
$funcs = $posql->getDisableFunctions();
print '<pre>';
print "disable functions:\n";
print_r($funcs);
$affected = $posql->setDisableFunctions('hoge');
print "disable functions: After:\n";
$funcs = $posql->getDisableFunctions();
print_r($funcs);
$affected = $posql->setDisableFunctions();
print "affected disable functions:\n";
var_dump($affected);
$disable_funcs = array('eval', 'exit', 'fopen');
$affected = $posql->setDisableFunctions($disable_funcs);
print "After the disable functions:\n";
$funcs = $posql->getDisableFunctions();
print_r($funcs);
print "\n---------------\n";
print "Try calls fopen() function on expression:\n";
$stmt = $posql->query("SELECT fopen('somefile', 'r')");
print "results:\n";
var_dump($stmt->fetchAll());
print "errors: \n";
print $posql->lastError();
上の例では、いくつかの設定テストの後、禁止関数の実行を試みます。
設定されている文字コードのデフォルトは UTF-8 です。 この文字コードは、SQL ステートメントにおける一部の関数でヒントのため利用されます。 実行中のスクリプトの文字コードに合わせることを推奨します。
この設定は PHP モードでも、SQL 構文を違和感なく記述できるようにするため、 また、1 つの イコール記号 (=) の前に $var などと (仮に外部から) 記述されてしまった場合、 PHP は、変数名から関数をコールすることができるためのバリデートにもなっています。
この設定はデフォルトで ON (有効) になっています。
SELECT ($func = 'unlink') AND $func('somefile');
上のように SQL ステートメントが外部から実行された場合、 PHP モードでは関数を実行してしまうかもしれません。 この設定を ON (TRUE) にしておくと、
SELECT ($func == 'unlink') AND $func('somefile');
上の例は比較演算子に変わるため、ある程度は関数のコールを制御することができます。
SELECT ... WHERE rowid = 1
上の例の場合は 1 つの イコール記号 (=) が 2 つになり、 比較演算子に変わるため、比較する際に 有用かもしれません。
SELECT ... WHERE rowid == 1
Posql 内部では、データの格納時に PHP 関数の serialize, unserialize でエンコードおよび デコードをしています。 このプロパティの設定により、挙動を変えることができます。 デフォルトのエンコード関数は、serialize です。
引数として渡す関数は PHP のリソース以外の型を文字列に変換できなければなりません。 成功すると 前に設定されていたエンコード関数名を返します。 失敗すると FALSE を返します。
Posql 内部では、データの格納時に PHP 関数の serialize, unserialize でエンコードおよび デコードをしています。 このプロパティの設定により、挙動を変えることができます。 デフォルトのデコード関数は、unserialize です。
引数として渡す関数は 文字列から 有効な PHP の型に変換できなければなりません。 成功すると 前に設定されていたデコード関数名を返します。 失敗すると FALSE を返します。
// This example might function as a compression database
function posql_extra_encode($value){
return gzcompress(serialize($value));
}
function posql_extra_decode($value){
return unserialize(gzuncompress($value));
}
// If the argument is given, it will be an error.
$posql = new Posql;
$posql->setEncoder('posql_extra_encode');
$posql->setDecoder('posql_extra_decode');
if ($posql->isError()) {
die($posql->lastError());
}
// Begin setting here.
$posql->open('foo.db');
$posql->exec("CREATE TABLE foo (col)");
if ($posql->isError()) {
die($posql->lastError());
}
$posql->exec("INSERT INTO foo (col) VALUES('abcabcabcabc')");
if ($posql->isError()) {
die($posql->lastError());
}
$stmt = $posql->query("SELECT * FROM foo");
print $stmt->fetchAllHTMLTable();
上の例は、列ごとにデータを圧縮し、圧縮データベースとして利用できます。 拡張モジュール zlib が有効になっている必要があります。
// This example might function as a compression database
// PHP5+ will be warned "Strict non-static"
class Posql_Extra_Serializer {
function encode($value){
$value = serialize($value);
if (extension_loaded('lzf')) {
$value = lzf_compress($value);
} else if (extension_loaded('zlib')) {
$value = gzcompress($value, 9);
} else if (extension_loaded('bz2')) {
$value = bzcompress($value);
}
return $value;
}
function decode($value){
if (extension_loaded('lzf')) {
$value = lzf_decompress($value);
} else if (extension_loaded('zlib')) {
$value = gzuncompress($value);
} else if (extension_loaded('bz2')) {
$value = bzdecompress($value);
}
$value = unserialize($value);
return $value;
}
}
// If the argument is given, it will be an error.
$posql = new Posql;
// assign the serializer function
$posql->setEncoder(array('Posql_Extra_Serializer', 'encode'));
$posql->setDecoder(array('Posql_Extra_Serializer', 'decode'));
if ($posql->isError()) {
die($posql->lastError());
}
// Begin setting here.
$posql->open('foo.db');
$posql->exec("CREATE TABLE foo (col)");
if ($posql->isError()) {
die($posql->lastError());
}
$posql->exec("INSERT INTO foo (col) VALUES('abcabcabcabc')");
if ($posql->isError()) {
die($posql->lastError());
}
$stmt = $posql->query("SELECT * FROM foo");
print $stmt->fetchAllHTMLTable();
上の例は、クラスメソッドを利用する方法です。
Posql は、排他ロック中のみ一時的に空のディレクトリを生成します。 ロック用ディレクトリはデータベースファイルと同じ場所に生成され 瞬時に削除されますが、 これは対象の (データベースファイルがある) ディレクトリに 「書き込み権限」が必要となることを示しています。 ロック用ディレクトリ名の命名規則は、
'.' + データベース名 + '.lock'
となります。データベース名が
'my_database'
の場合、ロック用ディレクトリ名は
'.my_database.lock'
となります。名前の衝突については通常、考慮する必要はありません。
デッドロックとみなされるまでのタイムアウトは デフォルトで 10 分です。 タイムアウトを過ぎるとロック用ディレクトリは破棄され、 処理が続行されます。
引数の timeout は、分数で扱われます。 timeout のデフォルト値は 10 です。 timeout は 1 より大きい値を数値で渡します。
成功すると TRUE を、失敗またはエラー時に FALSE を返します。
Posql で現在実装されているクエリキャッシュは、 SELECT ステートメントの結果セットを保存しておき、 同じクエリが要求された場合 検索を行わずキャッシュに保存されている結果を返す機能です。 テーブルが更新されると、キャッシュはそれに合わせて 新しい結果セットに更新されます。
クエリキャッシュを利用することにより、 処理時間のかかる複雑なステートメントなどが 2 回目以降、 少しの処理だけで結果セットとして返されるため高速化につながります。 そのかわり、キャッシュ記憶領域を必要とするためディスク容量が増します。 クエリキャッシュはデータベース内のプライベートな領域に保存されるため、 基本的に外側から操作など必要としません。
クエリキャッシュを使用している場合は TRUE を、 使用していない場合は FALSE を返します。
この値のデフォルトは FALSE (使用しない) に設定されています。
clearQueryCache() メソッドを利用することで 全てのクエリキャッシュをクリア (物理的に削除) することができます。
クエリキャッシュを使用する場合は TRUE を、 使用しない場合は FALSE を渡します。
クエリキャッシュの上限となる列数 (キャッシュの数) が数値で返ります。
デフォルトの上限値は 1024 です。
この値を超えて新しいクエリキャッシュが保存されようとする場合、 古いクエリキャッシュから順に削除されシフトします。
引数にはクエリキャッシュの上限となる列数 (キャッシュの数) を数値で渡します。
クエリキャッシュについての詳細は getUseQueryCache() を参照ください。
clearQueryCache メソッドは、 保存されている全てのクエリキャッシュをクリア (物理的に削除) します。
削除されたクエリキャッシュの列数が返ります。
getMicrotime メソッドは、 PHP5 での microtime(true); と同じ値を返します。 PHP のバージョン互換性のため提供されています。
マイクロ秒まで含めた現在の Unix タイムスタンプを float で返します。
有効な Posql データベースファイルだった場合は TRUE、 無効な形式だった場合は FALSE が返ります。
戻り値は、ファイルパスではなく、データベース名が返ります。 ファイルパスを取得したい場合は getPath() メソッドを使用してください。
Posql データベース に直近に挿入されたレコードの rowid の値を返します。 接続上において、まだ挿入されていない場合は NULL が返ります。
引数 major が 真 (TRUE) として渡された場合、 メジャーバージョン (例えば '2') が返ります。 デフォルトは (FALSE) です。 引数を省略した場合、'2.17' のようなバージョンが返ります。
引数で与えられた tablename がテーブルとして存在していれば TRUE、 存在しない場合は FALSE が返ります。
引数 class が存在しているかどうかを、 __autoload() のコールを抑制して (オートロードしないで) 調べます。
クラスが存在する場合は TRUE、存在しない場合は FALSE を返します。
引数 string が SQL ステートメントで有効な表現になるよう 適切にエスケープして返します。
引数 escape_wildcards が 真 (TRUE) で渡された場合、 LIKE 演算子のワイルドカードも同時にエスケープします。
引数 enclose が 真 (TRUE) で渡された場合、 文字列 string 全体を シングルクォート (') で囲って返します。
LIKE ワイルドカードのエスケープが必要な場合や 文字列のクォートが不要な場合を除いて、 quote() メソッドのほうが 適切という可能性が高いことに注意してください。
LIKE ワイルドカード文字を含むエスケープの例:
$posql = new Posql('math_db');
$posql->exec("DROP TABLE IF EXISTS math");
$posql->exec("CREATE TABLE IF NOT EXISTS math (
id integer,
expr varchar(255),
res integer,
primary key(id)
)");
for ($i = 1; $i <= 10; $i++) {
$expr = sprintf('%d %% %d / %d + %d', $i, $i, $i, $i);
$stmt = $posql->queryf('SELECT %s', $expr);
$res = $stmt->fetchColumn(0);
$stmt = $posql->prepare("INSERT INTO math (expr, res) VALUES(?, ?)");
$stmt->execute(array($expr, $res));
}
$search = $posql->escape('5 % 5', true);
$sql = "SELECT id, expr, res FROM math WHERE expr LIKE '" . $search . "%'";
$stmt = $posql->query($sql);
echo $stmt->fetchAllHTMLTable();
引数 pattern 内に含まれる LIKE ワイルドカード文字を エスケープして返します。
LIKE ワイルドカードは '%' と '_' の文字です。
このメソッドは、LIKE ワイルドカード文字をエスケープするだけの機能です。 ほとんどの場合、 quote() または escape() メソッドのほうが 適切という可能性が高いことに注意してください。
引数で与えられた html が HTML もしくは XML 文字列だった場合、 htmlspecialchars() 関数に ENT_QUOTES オプションを付加し、実行します。 結果、HTML および XML 特殊文字をエンティティに変換して返します。 html が配列だった場合は、再帰的に処理されます。 引数 charset が与えられると、それを文字コードとして処理します。 省略された場合は 内部文字コード getCharset(), setCharset() で使用されるプロパティが代用されます。
引数 array を対象とし、 1 つ以上の引数をソートに使用するテンプレートと解釈し、 配列 array のキーを中心にソートします。
$array = array(
'id' => 1,
'name' => 'foo',
'text' => 'hello!'
);
print "<br/><b>original:</b><br/><pre>\n";
print_r($array);
$template = array('name', 'id', 'text');
$posql = new Posql;
$posql->sortByTemplate($array, $template);
print "\n<b>after:</b><br/>\n";
print_r($array);
print "</pre>";
// output:
// array(
// [name] => foo
// [id] => 1
// [text] => hello!
// );
上の例は、最後のコメントのような結果になります。
引数 path をファイルパスとみなし、それをフルパスにして返します。
引数 check_exists が 真 (TRUE) で渡された場合、 戻り値となるファイルパスに実際にファイルが存在するかどうか調べ 存在しなかった場合、戻り値は FALSE となります。
ファイル filename 内の行番号 line_number に 文字列または配列として渡す引数 append_data を追加します。
引数 append_data が配列で渡されると、引数 glue によって連結されます。
ファイルに追加された (書き込まれた) バイト数が返ります。
このメソッドは、 memory_limit を超えるような巨大なファイルに対しても 正常に書き込めるよう設計されています。
1,100,one 2,200,two 3,300,three
上のような CSV ファイル sample.csv に対しての例:
$posql = new Posql;
$filename = 'sample.csv';
$append_data = ',Append';
$line_number = 2;
$written_bytes = $posql->appendFileLine(
$filename,
$append_data,
$line_number
);
echo '<pre>', file_get_contents($filename), '</pre>';
結果は以下のようになります。
1,100,one 2,200,two,Append 3,300,three
ファイル filename 内の行番号 line_number に 文字列または配列として渡す引数 insert_data を挿入します。
引数 insert_data が配列で渡されると、引数 glue によって連結されます。
ファイルに挿入された (書き込まれた) バイト数が返ります。
このメソッドは、 memory_limit を超えるような巨大なファイルに対しても 正常に書き込めるよう設計されています。
1,100,one 2,200,two 3,300,three
上のような CSV ファイル sample.csv に対しての例:
$posql = new Posql;
$filename = 'sample.csv';
$insert_data = '2,150,Insert';
$line_number = 2;
$written_bytes = $posql->insertFileLine(
$filename,
$insert_data,
$line_number
);
echo '<pre>', file_get_contents($filename), '</pre>';
結果は以下のようになります。
1,100,one 2,150,Insert 2,200,two 3,300,three
ファイル filename 内の行番号 line_number の文字列を、 文字列または配列として渡す引数 replacement に置換します。
引数 replacement が配列で渡されると、引数 glue によって連結されます。
書き込まれたバイト数が返ります。
このメソッドは、 memory_limit を超えるような巨大なファイルに対しても 正常に書き込めるよう設計されています。
1,100,one 2,200,two 3,300,three
上のような CSV ファイル sample.csv に対しての例:
$posql = new Posql;
$filename = 'sample.csv';
$replacement = '2,222,Replace';
$line_number = 2;
$written_bytes = $posql->replaceFileLine(
$filename,
$replacement,
$line_number
);
echo '<pre>', file_get_contents($filename), '</pre>';
結果は以下のようになります。
1,100,one 2,222,Replace 3,300,three
主なドキュメント、およびマニュアルは以下のリンクに含まれています。