PoiPHP ドキュメント

スポンサーリンク

概要(PoiPHP とは)

PoiPHP は「余計なものはポイ」という思想で作られた、軽量・明快・必要最小限の PHP フレームワークです。

  • ファイル名 = 画面(シンプルな構造)
  • action() に処理を書く(Controller クラス不要)
  • set() で値を渡し、テンプレートで表示
  • Model は必要な時だけロード
  • 生 SQL をそのまま書ける

インストール

PoiPHP は ZIP を展開するだけで使えます。特別なセットアップは不要です。

/your-app/
 ├ index.php        ← トップページの入口(actionを書く)
 ├ app.php          ← 複数ページ用エントリ(app.php?url=ページ名)
 ├ html/            ← テンプレート
 ├ models/          ← モデル(任意)
 └ PoiPHP/          ← フレームワーク本体
      ├ core/       ← フレームワーク内部クラス
      ├ poiphp.php  ← メインローダー
      └ config.php  ← フレームワーク設定
                

データベース設定

PoiPHP は PDO を使用しており、 config.phpの databaseセクションで DSN を指定します。

MySQL / MariaDB

MySQL を使用する場合は、以下のように DSN を記述します。

'database' => [
    'dsn'  => 'mysql:host=localhost;dbname=poiphp;charset=utf8mb4',
    'user' => 'root',
    'pass' => 'password',
],
SQLite(最小構成・設定が最も簡単)

SQLite を使う場合は DSN を sqlite:に変更します。

'database' => [
    'dsn'  => 'sqlite:' . POI_DIR . '/app.sqlite',
    'user' => null,
    'pass' => null,
],
PostgreSQL(生 SQL のみ利用可能)

Model の insert / update / delete は未対応ですが、query() で生 SQL は利用できます。

'database' => [
    'dsn'  => 'pgsql:host=localhost;dbname=poiphp',
    'user' => 'postgres',
    'pass' => 'password',
],
接続タイミング

PoiPHP は「必要な時だけ接続」する設計です。 Model をロードした時点で初めて DB に接続します。

config.php(設定ファイル)

PoiPHP の設定は PoiPHP/config.phpに記述します。 デバッグモード、データベース接続、アプリ固有の設定をまとめた シンプルで明快な構成です。

config.php の全体構造
return [

    // デバッグモード
    'debug' => true,

    // データベース設定(PDO)
    'database' => [
        'dsn'  => 'mysql:host=localhost;dbname=poiphp;charset=utf8mb4',
        'user' => 'root',
        'pass' => 'password',
    ],

    // SQLite の例
    // 'database' => [
    //     'dsn'  => 'sqlite:' . POI_DIR . '/app.sqlite',
    //     'user' => null,
    //     'pass' => null,
    // ],

    // PostgreSQL(生 SQL のみ利用可能)
    // 'database' => [
    //     'dsn'  => 'pgsql:host=localhost;dbname=poiphp',
    //     'user' => 'postgres',
    //     'pass' => 'password',
    // ],


    // レイアウト設定(任意)
    //'layout' => 'html/layout.html',
     'layout' => null,


    // アプリ固有の設定
    'app' => [
        'base_url' => '',
        'default_controller' => 'index',
    ],
];
    

debug(デバッグモード)

'debug' =>trueの場合、エラー画面に詳細情報が表示されます。 本番環境では falseに設定してください。

database(データベース設定)

PoiPHP は PDO を使用しており、DSN を記述するだけで DB を切り替えられます。

MySQL / MariaDB の例
'database' => [
    'dsn'  => 'mysql:host=localhost;dbname=poiphp;charset=utf8mb4',
    'user' => 'root',
    'pass' => 'password',
],
    
SQLite の例(最小構成)
'database' => [
    'dsn'  => 'sqlite:' . POI_DIR . '/app.sqlite',
    'user' => null,
    'pass' => null,
],
    
PostgreSQL(生 SQL のみ利用可能)
'database' => [
    'dsn'  => 'pgsql:host=localhost;dbname=poiphp',
    'user' => 'postgres',
    'pass' => 'password',
],
    

PoiPHP は「必要な時だけ接続」する設計です。 $c->loadModel()を呼んだ時点で初めて DB に接続します。

layout(レイアウト設定)

PoiPHP は layout.html を使った 1 レイアウト方式を採用しています。
全ページ共通のヘッダー・フッター・HTML 構造を layout.html にまとめて記述し、
ページごとの内容は <?= $_poi_content ?>の位置に差し込まれます。

設定例

'layout' => 'html/layout.html',

動作仕様

  • config で 'layout' => 'html/layout.html' と設定した場合に、そのレイアウトが全ページに適用されます(ファイルが存在するだけでは適用されません)
  • ページごとに指定・変更する場合は $c->setLayoutFile('html/layout.html') を使います
  • レイアウトを使わない場合 → 'layout' => null(既定)

layout.html の最小例

<!DOCTYPE html>
<html lang="ja">
<head>
    <meta charset="UTF-8">
    <title><?= $s->html($title ?? "PoiPHP") ?></title>
</head>
<body>

<header>
    <!-- 共通ヘッダー -->
</header>

<main>
    <?= $_poi_content ?>
</main>

<footer>
    <!-- 共通フッター -->
</footer>

</body>
</html>

app(アプリ固有の設定)

base_url

アプリをサブディレクトリに配置する場合に設定します。 通常は空文字のままで問題ありません。

default_controller

URL に何も指定されなかった場合に呼ばれるコントローラ名です。 デフォルトは indexです。

Hello World(最初の1ページ)

まずは最小の画面を作ってみましょう。

index.php

<?php
require_once __DIR__ . '/PoiPHP/poiphp.php';

function action(&$c)
{
    $c->set("msg", "Hello PoiPHP!");
    $c->setTemplateFile("html/index.html");
}
                
html/index.html
<h1><?= $s->h($msg) ?></h1>
                

これだけで画面が表示されます。

動作の流れ(全体像)

URL → action() → set() → テンプレート → レイアウト → HTML 出力
                

複雑な仕組みはありません。 「必要な時だけ必要な処理をする」だけです。

ルーティング

PoiPHP のページは「PHP ファイル1つ=1ページ」で、そのファイルに書いた action() が実行されます。入口は2通りあります。

1. ファイルに直接アクセスする
index.php    ← require して action() を書いたファイル自身が実行されます
about.php    ← 同じ形で作れば、そのまま about.php として開けます
2. フロントコントローラ経由(複数ページ向け)
app.php?url=about    → about.php の action() が実行されます
app.php(指定なし)    → config の app.default_controller(既定は index)が実行されます

2 のページ側ファイルには action() だけを書き、require 行は不要です(読み込みは app.php 側が行います)。
なお index.php?url=about の形は使えません。index.php 自身が action() を持っているため、別ページの action() と衝突します。その場合はエラーメッセージで app.php 経由が案内されます。
Apache では .htaccess の RewriteRule で app.php に集約すると、きれいな URL にできます(README 参照)。

コントローラ

function action(&$c)
{
    // ビューに渡す値をセット
    $c->set("title", "Hello PoiPHP");

    // レイアウト(共通パーツ)の指定 [v1.1.0 新機能!]
    $c->header_file = 'header.html';
    $c->footer_file = 'footer.html';

    // メインコンテンツのテンプレートを指定
    $c->setTemplateFile("html/index.html");
}            
$c->header_file や $c->footer_file を指定すると、メインコンテンツを前後から挟む形で自動的に include されます。
指定しない場合は、メインコンテンツのみが出力されるため、AjaxのレスポンスやAPIの作成にもそのまま利用できます。

ビュー(テンプレート)

<h1><?= $s->html($title) ?></h1>
                

テンプレートで使える変数

PoiPHP のテンプレートでは、以下の変数が自動で利用できます。

  • $c… コントローラオブジェクト(セッション、CSRF、モデル読み込みなど。POST/GET の取得は $s 経由)
  • $s… サニタイズ(エスケープ)用オブジェクト
  • $_poi_content… layout.html 内で使用される、テンプレートの内容
$s->html()(HTML エスケープ)

テンプレートで値を表示する時は、必ず $s->html()を使って XSS を防ぎます。

<?= $s->html($value) ?>
$s->h()(短縮形)
<?= $s->h($value) ?>
$s のメソッド一覧(Sanitize)

PoiPHP のテンプレートおよびコントローラでは、入力値の取得と出力時のエスケープのために $s が利用できます。

■ 出力(エスケープ)
$s->html($value)
    HTML エスケープ(XSS 対策)。配列・多次元配列にも対応。

$s->h($value)
    $s->html() の短縮形。

$s->url($value)
    URL エンコード。GET パラメータに埋め込む時に使用。

$s->json($value)
    JSON エスケープ。JavaScript に安全に埋め込むための出力。
■ 入力(POST)
$s->post($key)
    $_POST[$key] を取得し、HTML エスケープして返す。

$s->postt($key)
    $_POST[$key] を取得 → エスケープ → trim() して返す。

$s->posts($key)
    $_POST[$key] を取得 → エスケープ → $_SESSION[$key] に保存して返す。

$s->postst($key)
    $_POST[$key] を取得 → エスケープ → trim() → $_SESSION[$key] に保存して返す。

$s->postRaw($key)
    $_POST[$key] をエスケープなしで取得。DB へ保存する値は、こちらで受け取ってください(表示時に $s->html() でエスケープします)。
■ 入力(GET)
$s->get($key)
    $_GET[$key] を取得し、HTML エスケープして返す。

$s->gett($key)
    $_GET[$key] を取得 → エスケープ → trim() して返す。

$s->gets($key)
    $_GET[$key] を取得 → エスケープ → $_SESSION[$key] に保存して返す。

$s->getst($key)
    $_GET[$key] を取得 → エスケープ → trim() → $_SESSION[$key] に保存して返す。

$s->getRaw($key)
    $_GET[$key] をエスケープなしで取得。数値として扱う値などはこちらを使います。
$_poi_content(layout 専用)

$_poi_contentは PoiPHP が自動で用意する変数で、テンプレートの内容がそのまま入ります。 開発者が定義する必要はありません。

レイアウト(layout.html)

PoiPHP では、config でレイアウトを設定すると、すべてのテンプレートは layout.htmlを通して表示されます。 テンプレート側は「中身だけ」書けばよく、ヘッダーやフッターは layout にまとめて管理できます。

layout.html(共通レイアウト)
<!DOCTYPE html>
<html lang="ja">
<head>
    <meta charset="UTF-8">
    <title><?= $s->html($title ?? "PoiPHP") ?></title>
</head>
<body>

<?= $_poi_content ?>   <!-- ← テンプレートの内容がここに入る -->

</body>
</html>
    

$_poi_contentは PoiPHP が自動で用意する変数で、テンプレートの内容がそのまま入ります。 開発者が定義する必要はありません。

テンプレート側(例:html/bbs.html)
<h1>簡易掲示板</h1>

<form method="post">
    <input type="hidden" name="_token" value="<?= $s->html($c->csrf) ?>">

    名前:<br>
    <input type="text" name="name"><br><br>

    本文:<br>
    <textarea name="body"></textarea><br><br>

    <button>投稿</button>
</form>

<hr>

<?php foreach ($list as $p): ?>
    <div>
        <strong><?= $s->h($p["name"]) ?></strong>
        (<?= $s->html($p["created_at"]) ?>)<br>
        <?= nl2br($s->h($p["body"])) ?>
    </div>
<?php endforeach; ?>
    

テンプレートにはヘッダーやフッターを書く必要はありません。 すべて layout.html に任せることで、ページ全体の統一感を保てます。

コントローラ側の設定
$c->setTemplateFile("html/bbs.html");
    

config で 'layout' => 'html/layout.html' と設定しておけば、コントローラ側はこれだけで layout.html が適用されます。ページ単位で指定する場合は $c->setLayoutFile("html/layout.html") を使います。

データベース対応状況

PoiPHP は PDO を使用した必要最小限の DB ラッパーを提供しており、以下のデータベースに対応しています。

SQLite        ✔ 標準対応(最小構成・設定が最も簡単)
MySQL         ✔ 対応(config.php に DSN / user / pass を記述)
MariaDB       ✔ 対応(MySQL と同等)
PostgreSQL    △ 生 SQL は利用可能(Model の insert/update/delete は未対応)
その他        ✘ 非対応(動作保証なし)
    

PoiPHP は ORM を搭載していません。 必要な時だけモデルをロードし、必要なクエリだけを実行する シンプルで明快な設計です。

モデル(Model)

PoiPHP のモデルは「1 テーブル = 1 クラス」のシンプルな仕組みです。
必要な時だけ $c->loadModel() でロードし、データベース操作を行います。

モデル定義(models/User.php)
<?php
class UserModel extends Model
{
    public function __construct($db)
    {
        parent::__construct($db, "users");   // 対応するテーブル名
    }
}
    

loadModel("User") は models/User.php を読み、クラス UserModel(モデル名+Model)を探します。
ファイルを作らない場合は汎用 Model が使われ、テーブル名はモデル名の小文字(User → user)になります。テーブル名がそれで合う場合は、ファイル自体が不要です。
独自メソッドを追加したい時だけ、上記の形でファイルを作ります。

モデルの読み込み
$userModel = $c->loadModel("User");
    
提供されるメソッド(仕様)
findAll()                     
    テーブルの全件を配列で返します。

find($id)                     
    主キー(id)で1件取得します。見つからなければ null。

findBy($column, $value)       
    任意のカラムで検索し、配列で返します。

insert($data)                 
    データを INSERT し、挿入された ID を返します。

update($id, $data)            
    主キーで UPDATE。成功時 true を返します(失敗時は例外が発生します)。

delete($id)                   
    主キーで DELETE。成功時 true を返します(失敗時は例外が発生します)。

query($sql, $params)          
    生 SQL(SELECT)を実行し、結果を配列で返します。

exec($sql, $params)           
    生 SQL(INSERT/UPDATE/DELETE)を実行し、成功/失敗を返します。

updateCount($id, $data)
    UPDATE を実行し、更新件数(rowCount)を返します。
    
使用例
// User モデルをロード
$userModel = $c->loadModel('User');

// 1件取得
$user = $userModel->find(1);

// 保存して新しいIDを受け取る
$newId = $userModel->insert(['name' => 'Taro']);

// 更新して影響があった件数を確認
$count = $userModel->updateCount(1, ['name' => 'Jiro']);
    

複雑な ORM 機能はありません。
必要な時に必要な処理だけを行う、軽量なモデルです。

ページネーション

PoiPHP 本体にはページャ生成機能は搭載していません。「総件数の取得」と「LIMIT / OFFSET での取得」を組み合わせる、シンプルなレシピで実装します。

Controller(例)
$page   = max(1, (int)($c->s->getRaw('page') ?? 1));
$limit  = 10;
$offset = ($page - 1) * $limit;

$User  = $c->loadModel('User');
$total = (int)$User->query("SELECT COUNT(*) AS cnt FROM users")[0]['cnt'];
$list  = $User->query("SELECT * FROM users ORDER BY id LIMIT {$limit} OFFSET {$offset}");

$pages = (int)ceil($total / $limit);

$c->set('list', $list);
$c->set('page', $page);
$c->set('pages', $pages);
$c->setTemplateFile('html/user_list.html');
    

LIMIT / OFFSET にはプレースホルダを使わず、(int) で整数化した値を埋め込みます(LIMIT へのバインドに対応しない DB があるためです)。

View(テンプレート)
<?php for ($i = 1; $i <= $pages; $i++): ?>
    <?php if ($i === $page): ?>
        <strong><?= $i ?></strong>
    <?php else: ?>
        <a href="?page=<?= $i ?>"><?= $i ?></a>
    <?php endif; ?>
<?php endfor; ?>
    

リンクの見た目は、お好みの CSS や Bootstrap のクラスを付けて調整してください。

セッション

PoiPHP のセッションは $c->sessionで扱います。 set / get / delete の3つの操作が利用できます。

$c->session->set("name", "bee");   // 保存
$name = $c->session->get("name");  // 取得
$c->session->delete("name");       // 削除
    

CSRF トークン

トークンはセッション開始時に自動生成され、$c->csrf で取り出せます。
チェックは自動では行われません。フォームには必ず _token を hidden で入れ、POST を処理する先頭で必ず自前で確認してください。

送信側(フォーム)
<form method="post">
    <input type="hidden" name="_token" value="<?= $s->html($c->csrf) ?>">
    <!-- フォームの内容 -->
    <button>送信</button>
</form>
    
受け側(POST 時のチェック)
if (($_SERVER['REQUEST_METHOD'] ?? 'GET') === 'POST') {
    if (!$c->session->checkToken($c->s->postRaw('_token'))) {
        http_response_code(403);
        exit('CSRF token mismatch');
    }
    // 通常の処理
}
    

ファイルアップロード

ファイルアップロードは $c->upload->save() を呼ぶだけです。
ディレクトリがなければ自動で作成し、ファイル名は衝突しないようリネームして保存されます。

// 第一引数:inputのname属性、第二引数:保存先ディレクトリ
$path = $c->upload->save("photo", "uploads");
                    
if ($path) {
    // 成功:保存されたパス(例:uploads/9f2ab1c4d5e6f708192a3b4c5d6e7f80_1730000000.jpg)が返ります
    // ※ファイル名は「ランダムな文字列_時刻.拡張子」にリネームされます
} elseif ($path === false) {
    // 拒否:拡張子が許可されていない、サイズ上限を超えた等
} else {
    // 未選択・アップロードエラー:null が返ります
}

// 公開フォームでは、許可リスト+サイズ上限の指定がおすすめです
$path = $c->upload->save("photo", "uploads", 2 * 1024 * 1024, ['jpg', 'png', 'gif']);
                        

API JSON 出力

JSON を返す場合は $c->json()を返すだけです。

return $c->json($data);