インストール

動作要件

項目	バージョン / 備考
PHP	8.3 以降
拡張モジュール	`pdo_mysql`（または `pdo_pgsql`、`pdo_sqlite`、`pdo_sqlsrv`/`pdo_dblib`）、`openssl`、`json`
Web サーバー	Apache（`mod_rewrite`）または nginx
データベース	MySQL / MariaDB、PostgreSQL、SQLite、MS SQL Server

Flexagon は 2 つの Composer パッケージとして配布されています。

パッケージ	用途
`flexagon/framework`	フレームワークコア（ライブラリ）
`flexagon/skeleton`	アプリケーションスケルトン（プロジェクトテンプレート）

新規プロジェクト

composer create-project flexagon/skeleton myapp
cd myapp

myapp/
├── application/          # ドメインコード
├── public/               # ← ドキュメントルート
├── script/               # CLI ジョブ
├── flexagon.php
├── composer.json
└── vendor/
    └── flexagon/framework/   # フレームワークコア

フレームワークは単独でアップデートできます。

composer update flexagon/framework

既存プロジェクトへの追加

composer require flexagon/framework
composer exec flexagon init      # または php vendor/bin/flexagon init

init は、public/、application/、script/、flexagon.php など、プロジェクト構成を形作る 34 個のファイルを作成します。既存のファイルには手を加えないため、アップグレード後に新たに追加された構成ファイルだけを追加する用途にも使えます。既存のファイルを上書きするには --force を指定してください。

create   flexagon.php
create   application/_Global.php
...
keep     public/index.php        ← 既存ファイルを保持

flexagon/framework だけをインストールした場合でも、StringUtil、ValidUtil、CryptoUtil などのユーティリティクラスや BaseModel はすぐに利用できます。ただし、DAO レイヤーを使うには、アプリケーション側で _Global を定義する必要があります。 定義がない場合は BaseGlobal のデフォルト値が使われるため致命的エラーにはなりませんが、データソース設定が空のためデータベースに接続できません。実際のアプリケーションでは、スケルトンパッケージから始めてください。

flexagon.php は 2 つのレイアウトを順に確認するため、フレームワークのインストール方法にかかわらず、エントリーポイントのコードは同じままです。

順序	パス	想定ケース
1	`vendor/flexagon/framework/Bootstrap.php`	Composer でのインストール
2	`application/_Flexagon.phar`（ファイル）	単一の PHAR としてパッケージ化

どちらも見つからない場合は、composer install を実行するか ant build で PHAR をビルドするよう促す RuntimeException を送出して停止します。Composer の files エントリーが先に登録されるよう、vendor/autoload.php はフレームワークより前に読み込まれます。

Bootstrap.php は application/_Global.php を含む最も近い親ディレクトリを探し、それを PROJECT_ROOT として使用します。そのため、フレームワークが vendor/ 配下にあっても PHAR 内にあっても、アプリケーションのパス解決は同じように動作します。

オートロード

アプリケーションのクラスは、composer.json の PSR-4 設定によって application/ にマッピングされます。

ExampleUser\UserDAO  →  application/ExampleUser/UserDAO.php

名前空間を追加するには、同じ名前のディレクトリを作成するだけです。composer.json を変更する必要はありません。

フレームワークは _Flexagon\ 名前空間、グローバルヘルパー（_echo、_t、___）、そして TemplateLoader を自動的に読み込みます。追加の設定は必要ありません。

データベース設定

application/_Config.php を編集します。

<?php
use _Flexagon\Libs\Env;
use _Flexagon\Models\DataSourceModel;

_Global::$DATA_SOURCES['default'] = new DataSourceModel(
    Env::get('DB_HOST', 'localhost'),
    Env::int('DB_PORT', 3306),
    Env::get('DB_USER'),
    Env::required('DB_PASSWORD'),
    Env::get('DB_NAME')
);

値は .env.php または環境変数から取得されます。詳しくは次のセクションを参照してください。

シークレット（`.env.php`）

パスワードやキーは application/ に置かないでください。プロジェクトルートで .env.example.php を .env.php にコピーして値を記入すると、_Config.php が Env を通じてその値を読み取ります。

<?php
// .env.php — git の管理対象外。public/ 配下には絶対に置かない
return [
    'DB_USER'     => 'app',
    'DB_PASSWORD' => 's3cr3t',
    'DB_NAME'     => 'service',
    'SESSION_ENCRYPTION_STRING' => '...',
];

メソッド	戻り値
`Env::get($key, $default = null)`	値、または `$default`
`Env::required($key)`	値。存在しないか空の場合は例外を送出
`Env::int($key, $default)` / `Env::bool($key, $default)`	型付きの値。解析できない場合は例外を送出
`Env::has($key)`	キーが設定されているかどうか

値はプロセスの環境変数、.env.php、デフォルト値の順に検索されます。本番環境では、同じキーを PHP-FPM の env[...]、Docker、または利用しているプラットフォームで設定し、.env.php を置かずに運用することもできます。このファイルは通常の PHP なので、opcache によってコンパイル済みの状態が保持され、値の型もそのまま維持されます。ファイルは Env が初めて使われたときに読み込まれるため、これを使わないアプリケーションには一切コストがかかりません。別のファイルを読み込むには、起動前に ENV_FILE を定義するか、Env::load($path) を呼び出してください。各サーバーの .env.php をプロジェクトの外（/etc/flexagon/ など）に置く方法は、application/_Config/README.md で説明しています。

putenv() や $_ENV には何も書き込まれず、エラーメッセージにはキー名は含まれても値が含まれることはありません。また、DataSourceModel を var_dump() するとパスワードは *** と表示されます。

flexagon check は、.env.php が public/ 配下にある場合や git で追跡されている場合には失敗し、.env.example.php にあるキーのうち未設定のもの、_Config.php に直接書かれたパスワード、残っている .env（Flexagon はこれを読み込みません）、そして opcache.file_cache（コンパイル済みのシークレットをディスクに書き出します）について警告を出します。

AI コーディングエージェントを遠ざける

シークレットを .env.php に置いておけば、application/ 配下のファイルはエージェントに読ませても安全です。あとは、その 1 つのファイルをエージェント側でブロックしてください。Claude Code 向けには、スケルトンに .claude/settings.json が同梱されています（存在しない場合は flexagon init が作成します）。

{
  "permissions": {
    "deny": ["Read(./.env.php)", "Read(./**/.env.php)"]
  },
  "sandbox": {
    "filesystem": { "denyRead": ["./.env.php"] }
  }
}

permissions.deny は Read ツールをブロックし、sandbox.filesystem.denyRead は cat .env.php のようなシェルコマンドもブロックします。両方を併用してください。ほかのエージェントにはそれぞれ独自の除外設定があります。コードを実行できるエージェントであれば、実行時に値を出力することは依然として可能です（php -r 'echo Env::get(...)'）。そのため、エージェントには本番用ではなく、開発用の認証情報を記載した開発用の .env.php を渡してください。

最初のページ

<?php
// public/hello.php
_Global::$SITE_TITLE = 'Hello';

TemplateLoader::show('head');
echo '<h1>Hello, Flexagon</h1>';
TemplateLoader::show('tail');

http://127.0.0.1:9001/hello を開くと、ページが表示されます。

環境チェック

プロジェクトのレイアウトと実行時の設定に矛盾がないかを確認します。

php script/flexagon.php check     # どのインストール方法でも動作
php vendor/bin/flexagon check     # Composer でインストールした場合にも利用可能

ok       php 8.3.33
ok       opcache.save_comments
ok       project layout
ok       bootstrap
warn     data sources  default still contains template placeholders
ok       display_errors  off

気づかないうちに問題を引き起こしかねない設定ミスを検出します。 opcache.save_comments が無効になっていると、@encrypt や @db_auto_timestamp はエラーを出さずに無視されます。_Config.php を public/ 配下に置くと、データベースの認証情報が Web 経由で漏えいするおそれがあります。このコマンドは問題を検出すると終了ステータス 1 で終了するため、デプロイパイプラインにも組み込めます。

チェック項目の一覧はフレームワーク CLI を参照してください。

インストール

動作要件#

新規プロジェクト#

既存プロジェクトへの追加#

オートロード#

データベース設定#

シークレット（.env.php）#

AI コーディングエージェントを遠ざける#

最初のページ#

環境チェック#