Phalconプロジェクトの作成と実行

Phalconとは？

Phalconは、C言語拡張として実装されたオープンソースの高性能PHP Webフレームワークです。この独自の実装方式により、Phalconは極めて低いリソース消費と非常に高速な実行を実現し、従来の多くのPHPフレームワークを上回るパフォーマンスを発揮します。PhalconはMVC（モデル–ビュー–コントローラー）アーキテクチャに準拠し、ORM（オブジェクト関係マッピング）、テンプレートエンジン、ルーティング、キャッシュ、イベントマネージャなど、多彩な機能コンポーネントを提供。開発者がパワフルで高性能なWebアプリやAPIを迅速に構築できるよう設計されています。

Phalconの主な特徴とメリット

• 卓越したパフォーマンス: C拡張として動作することで、PHPスクリプトの解析や読み込みのオーバーヘッドを回避し、ネイティブレベルの高速さを実現します。
• リソース効率が高い: メモリ消費が非常に少なく、パフォーマンスやスケーラビリティを重視するアプリケーションに最適です。
• 充実した機能: Webアプリ開発に必要な主要コンポーネントを標準搭載しているため、サードパーティ製ライブラリへの依存が減ります。
• 使いやすさ: 分かりやすく一貫したAPIと充実したドキュメントを備え、Phalcon初心者でも素早く学習できます。
• 高い疎結合性: 各コンポーネントは独立設計されており、プロジェクト要件に応じて自由に選択や差し替えが可能です。
• セキュリティ: 入力フィルタリングやCSRF対策など、多くのセキュリティ関連コンポーネントも搭載しています。

Phalconは、高パフォーマンスでスケーラブルなWebアプリ・APIの構築に最適な選択肢です。特に速度やリソース効率に厳しい要件を持つプロジェクトに適しています。

ServBayを使ってPhalconプロジェクトを作成・実行する

ServBayは、macOS専用のローカルWeb開発環境です。PHPの複数バージョン、各種データベース（MySQL, PostgreSQL, MongoDB, Redis）、Webサーバー（Caddy, Nginx, Apache）、その他開発ツールが統合されています。ServBayを活用すれば、Phalconプロジェクトに必要な実行環境を簡単に構築・管理できます。

本ガイドでは、ServBayのPHP環境を使って基本的なPhalconプロジェクトを作成し、Webサーバーでアクセス可能にする方法、さらにリレーショナルデータベース（MySQL）およびNoSQLデータベース（Redis）を統合するステップを解説します。

前提条件

開始前に、以下の条件が整っていることを確認してください：

1. ServBayがインストール済み・起動済みであること: macOSにServBayをインストール・起動してください。
2. 使用したいPHPバージョンを有効化済みであること: ServBay内でプロジェクトに利用するPHPバージョンが有効化されていること。
3. Phalconモジュールが有効化済みであること: ServBayにPhalconモジュールは内蔵されていますが、デフォルトでは無効の場合があります。ServBay付属Phalconモジュールの有効化方法の案内通り、利用PHPバージョンでPhalcon拡張を有効化し、PHPサービスを再起動してください。
4. Composerが利用可能であること: ServBayにはComposerが内蔵済みなので別途インストール不要です。ターミナルでcomposerコマンドを利用できるか確認してください。

PhalconのバージョンとDevToolsの選び方

PhalconフレームワークとDevTools（開発用CLIツール）は、利用するPHPバージョンに合ったものを選ぶ必要があります。下記表は、よく使われるPHPバージョンと推奨されるPhalcon・DevToolsのバージョン対応表です。

PHPバージョン	推奨Phalconフレームワーク	推奨Phalcon DevTools	注意点
PHP 5.6, 7.0, 7.1	Phalcon 3.4.5	3.4.x
PHP 7.2, 7.3, 7.4	Phalcon 4.1.2	~4.1（または4.3.x）
PHP 8.0, 8.1, 8.2	Phalcon 5.x	5.0.x（公式）	公式DevToolsはPHP8.xで互換性に問題がある場合あり。
PHP 8.3, 8.4	Phalcon 5.x	dev-master（修正版リポジトリ）	互換性のため、コミュニティ版（修正版）利用推奨。

重要: PHP8.x以降では、公式Phalcon DevToolsの互換性が万全でないことがあります。コミュニティが提供する修正版の利用がおすすめです。以降の手順ではComposerで修正版DevToolsを導入する方法も記載しています。

Phalconプロジェクトの作成

推奨ウェブサイト保存パス

管理のしやすさから、ServBayはすべてのWebプロジェクトをデフォルトのWebルートディレクトリ /Applications/ServBay/www 配下に配置することを推奨しています。本例でもそこにプロジェクトを作成します。

1. Webルートディレクトリに入りプロジェクトフォルダを作成

   ターミナルでServBayのWebルートディレクトリに移動し、新規プロジェクトフォルダ（例：servbay-phalcon-app）を作成します。

   cd /Applications/ServBay/www
   mkdir servbay-phalcon-app
   cd servbay-phalcon-app

2. Phalcon DevToolsのインストール

   Phalcon DevToolsは、プロジェクトスケルトンの生成、コード雛形の自動作成、DBマイグレーションなどのCLIツール群です。Composerでインストールします。PHPバージョンごとに導入コマンドが異なります。

   • PHP 5.6, 7.0, 7.1（Phalcon DevTools ^3.4）の場合:

     composer require phalcon/devtools:"^3.4"

   • PHP 7.2, 7.3, 7.4（Phalcon DevTools ~4.1）の場合:

     composer require phalcon/devtools:"~4.1"

   • PHP 8.0, 8.1, 8.2, 8.3, 8.4 (Phalcon DevTools dev-master 修正版) の場合: 公式DevToolsのPHP8.x対応が不完全なため、Composerでコミュニティの修正版を使います。まず、プロジェクトルート(/Applications/ServBay/www/servbay-phalcon-app)でcomposer.jsonを作成または編集し、修正版リポジトリの設定を追加します。

     {
        "repositories": [
           {
              "url": "https://github.com/daleffe/phalcon-devtools-5.x-fixed.git",
              "type": "git"
           }
        ],
        "require": {
           "phalcon/devtools": "dev-master"
        },
        "minimum-stability": "dev",
        "prefer-stable": true
     }

     その後、ComposerのアップデートコマンドでDevToolsをインストールします。

     composer update

   Composerにより、プロジェクトフォルダ（servbay-phalcon-app）直下にvendorディレクトリが作成され、DevToolsの実行ファイルはvendor/bin/phalconの位置に保存されます。

3. Phalcon DevToolsでプロジェクトスケルトンを生成

   先ほどインストールしたDevToolsコマンドで、Phalconプロジェクトの基本ディレクトリ構造（スケルトン）を生成します。実際のコードはサブフォルダ（例：同じくservbay-phalcon-app）内に作られます（これはDevToolsのデフォルト仕様です）。

   vendor/bin/phalcon project servbay-phalcon-app

   /Applications/ServBay/www/servbay-phalcon-app直下に新しいサブディレクトリ/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-appができ、その中にPhalconプロジェクトの雛形一式が生成されます。

4. プロジェクトコードディレクトリへ移動

   新しく作られたコードディレクトリに移動し、以降の操作はその中で実施します。

   cd servbay-phalcon-app

   現在地が /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app であることを確認してください。

プロジェクト環境の設定

Phalconプロジェクトの主な設定はapp/config/config.phpにまとまっています。ここでDB接続情報やアプリケーションのパスなど、重要な設定を行いましょう。

1. 設定ファイルの編集

   お好みのエディターで /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/config.php を開きます。DB設定部分を見つけて修正または追加してください。ServBayのMySQL/MariaDBデフォルトユーザー名はroot、パスワードは空ですが、安全のため必ず強力なパスワードを設定してください。下記のpasswordはサンプルなので、実際の環境に合わせて変更しましょう。データベース名servbay_phalcon_appもサンプル用です（データベースの手動作成が必要です）。

   return new \Phalcon\Config([
       // ... 他の設定 ...
       'database' => [
           'adapter' => 'Mysql', // または 'Postgres' など
           'host' => '127.0.0.1',
           'username' => 'root', // ServBayのデフォルトrootユーザー
           'password' => 'password', // <-- ご自身のパスワードに変更してください
           'dbname' => 'servbay_phalcon_app', // <-- データベース名も合わせてください
       ],
       // ... 他の設定 ...
   ]);

   重要: ServBayで該当データベースサービス（MySQLやMariaDB）が起動していること、またユーザー・パスワードが設定に一致していることを確認しましょう。servbay_phalcon_appデータベースはphpMyAdminまたはAdminer等のツールで事前に作成が必要です。

Webサーバーの設定（ServBay「ウェブサイト」機能）

ブラウザからPhalconプロジェクトへアクセスするには、ServBayのウェブサイト機能を使って仮想ホストを作成し、プロジェクトのWeb公開ディレクトリへルーティングする必要があります。

1. ServBayアプリ起動
2. 「ウェブサイト」設定を開く：ServBayメイン画面から「ウェブサイト」を選択します。
3. 新規ウェブサイト追加：追加ボタンをクリック。
   • 名称: 分かりやすい任意の名前（例：My First Phalcon Dev Site）を入力
   • ドメイン名: 任意のアクセス用ローカルドメイン（例：servbay-phalcon-test.local）。ServBayは.localドメインをローカルへ自動DNS解決します。
   • サイト種別: PHPを選びます。
   • PHPバージョン: Phalconモジュールを有効化したバージョンを指定
   • ウェブサイトルート: 重要なポイントです。Phalconプロジェクトのエントリーポイントindex.phpは通常publicディレクトリ内なので、サイトルートを /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public に指定してください。
4. 設定を保存：新規設定を保存すると、各種設定が適用されます。場合によりWebサーバー（CaddyやNginx）の再起動が必要です。

詳細な設定手順は 最初のウェブサイト追加 も参考にしてください。設定完了後は、ローカルドメイン解決やWebサーバー設定もServBayが自動で処理してくれます。

サンプルコードの追加

動作確認用に簡単なコードを追加してみましょう。

1. ルーティングの設定

   /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/routes.php を編集し、ルートパス / を処理するシンプルなルーティング規則を追加します。

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   // デフォルトルートを定義。'/'はIndexControllerのindexActionにマッピング
   $router->add(
       '/',
       [
           'controller' => 'index',
           'action'     => 'index',
       ]
   );
   
   // ...他のルーティング設定も追加可...
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

2. コントローラの作成

   /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/controllers/IndexController.php を編集（なければ新規作成）し、シンプルなindexActionメソッドを追加します。

   <?php
   namespace App\Controllers; // 名前空間に注意
   
   use Phalcon\Mvc\Controller;
   
   class IndexController extends Controller
   {
       // ルートパス'/'のリクエストを処理
       public function indexAction()
       {
           // 単純な文字列をレスポンスとして返す
           return 'Hello ServBay!';
       }
   }

サイトへアクセス

すべてのファイルを保存し、ServBayが動作していることを確認してください。その後、ブラウザで設定したローカルドメインにアクセスします：

https://servbay-phalcon-test.local

正しく設定されていれば、Hello ServBay!と表示されます。

データベース統合

Phalconには強力なDB抽象化レイヤやORMが組み込まれています。ServBayでは複数のデータベースが利用可能です。ここではMySQLとRedisの例を紹介します。

リレーショナルデータベース例：MySQL

PhalconのDBアダプタを使ってServBayのMySQLに接続し、簡単なデータの挿入と取得を実演します。

1. データベース構造の作成（マイグレーション利用）

   Phalcon DevToolsは、DBスキーマのバージョン管理ができるマイグレーション機能をサポートしています。

   • マイグレーションファイルの生成: プロジェクトコードディレクトリ（/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app）で、空のマイグレーションファイルを生成します。

     vendor/bin/phalcon migration generate

     これでmigrationsディレクトリ内にYYYYMMDDHHMMSS_MigrationName.php形式のファイルが生成されます。

   • マイグレーションファイルの編集: 新しく作成されたマイグレーションファイルを開き、morphメソッド内でusersテーブルの定義を記述します。

     <?php
     
     use Phalcon\Db\Column;
     use Phalcon\Db\Index;
     use Phalcon\Migrations\Mvc\Model\Migration;
     
     /**
      * Class UsersMigration_100
      */
     class UsersMigration_100 extends Migration // クラス名はファイル名と一致させる必要あり
     {
         /**
          * マイグレーションの実行
          *
          * @return void
          */
         public function morph()
         {
             $this->morphTable('users', [
                 'columns' => [
                     new Column(
                         'id',
                         [
                             'type'          => Column::TYPE_INTEGER,
                             'autoIncrement' => true,
                             'notNull'       => true,
                             'primary'       => true,
                         ]
                     ),
                     new Column(
                         'name',
                         [
                             'type'    => Column::TYPE_VARCHAR,
                             'size'    => 255,
                             'notNull' => true,
                         ]
                     ),
                     new Column(
                         'email',
                         [
                             'type'    => Column::TYPE_VARCHAR,
                             'size'    => 255,
                             'notNull' => true,
                             'unique'  => true,
                         ]
                     ),
                 ],
                 'indexes' => [
                     new Index('PRIMARY', ['id'], 'PRIMARY'),
                     new Index('email_UNIQUE', ['email'], 'UNIQUE'),
                 ],
                 'options' => [
                     'TABLE_ENGINE' => 'InnoDB',
                     'CHARACTER SET' => 'utf8mb4',
                     'COLLATE' => 'utf8mb4_unicode_ci',
                 ],
             ]);
         }
     
         /**
          * マイグレーションのロールバック
          *
          * @return void
          */
         public function down()
         {
             // オプション：ロールバックでテーブル削除などの処理を書く
             // $this->getConnection()->dropTable('users');
         }
     }

     注意: クラス名（例：UsersMigration_100）はファイル名と一致させてください。ファイル名には通常タイムスタンプとクラス名が含まれます。

   • マイグレーションの実行: プロジェクトディレクトリでマイグレーションを実行し、usersテーブルを作成します。

     vendor/bin/phalcon migration run

     もし接続エラーが出る場合は、app/config/config.phpのDB設定やServBayのMySQL/MariaDBサービス状態を再確認しましょう。

2. DB接続設定（前述済み）

   app/config/config.php の'database'設定が、ServBayのMySQL/MariaDBに正しく接続できるようになっていることを確認しましょう。

3. サンプルルーティングの追加

   app/config/routes.php に、ユーザーデータの追加・取得用ルートを追加してください。

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   $router->add('/', [
       'controller' => 'index',
       'action'     => 'index',
   ]);
   
   // ユーザー追加用ルート
   $router->add(
       '/mysql-add',
       [
           'controller' => 'index',
           'action'     => 'mysqlAdd',
       ]
   );
   
   // ユーザー取得用ルート
   $router->add(
       '/mysql',
       [
           'controller' => 'index',
           'action'     => 'mysql',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. コントローラでDB操作メソッドを実装

   app/controllers/IndexController.php にmysqlAddActionおよびmysqlActionメソッドを追記します。ここではPhalconのDBアダプタを直接利用します。

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql; // MySQLアダプタ読み込み
   use Phalcon\Db\Enum; // fetchAllのモード定数
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       // ユーザー追加例
       public function mysqlAddAction()
       {
           // サービスコンテナからDB接続を使っても良いですが、ここでは簡単のため毎回作成
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- ご自身のパスワードに変更してください
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           // ユーザーレコード挿入
           $success = $connection->insert(
               'users',
               ['ServBay Demo User', '[email protected]'],
               ['name', 'email']
           );
   
           // 結果出力
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       // ユーザー一覧取得・表示例
       public function mysqlAction()
       {
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- ご自身のパスワードに変更してください
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           // ユーザー全件取得
           $users = $connection->fetchAll('SELECT * FROM users', Enum::FETCH_ASSOC);
   
           // JSONで結果返却
           header('Content-Type: application/json');
           echo json_encode($users);
       }
   }

   注意: 実際の開発では、DB設定や接続はサービスコンテナに登録し、DI経由で各コントローラに渡す形が推奨です。ここはサンプル実装です。

5. 動作確認

   • ブラウザで https://servbay-phalcon-test.local/mysql-add にアクセス → "User added successfully."が表示されれば追加成功
   • 続いて https://servbay-phalcon-test.local/mysql にアクセス → usersテーブルの内容（追加済みデータ）がJSONで表示されます

NoSQLデータベース例：Redis

PhalconからServBayのRedisサービスをキャッシュに利用するサンプルです。

1. Redis拡張の導入確認

   ServBayのPHPパッケージには基本的に主要エクステンションが同梱されています。peclなどで手動導入せずとも、PHP拡張一覧から利用PHPバージョンでRedis拡張にチェックが入っていればOKです。

2. Redis接続設定

   app/config/config.php ファイルにRedisの接続情報を追記。デフォルトは127.0.0.1のポート6379です。

   return new \Phalcon\Config([
       // ... 他の設定 ...
       'cache' => [
           'adapter' => 'Redis',
           'host' => '127.0.0.1',
           'port' => 6379,
           'index' => 0, // デフォルトは0番DB
           'persistent' => false,
           'auth' => null, // Redisにパスワードありの場合のみ設定
       ],
       // ... 他の設定 ...
   ]);

3. サンプルルーティングの追加

   app/config/routes.php に、Redisキャッシュ検証用のルートを追加します。

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   $router->add('/', [
       'controller' => 'index',
       'action'     => 'index',
   ]);
   
   $router->add('/mysql-add', [
       'controller' => 'index',
       'action'     => 'mysqlAdd',
   ]);
   
   $router->add('/mysql', [
       'controller' => 'index',
       'action'     => 'mysql',
   ]);
   
   // Redisキャッシュ例のルート追加
   $router->add(
       '/redis',
       [
           'controller' => 'index',
           'action'     => 'redis',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. コントローラでRedisキャッシュの利用

   app/controllers/IndexController.php に redisAction を追加。

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql;
   use Phalcon\Db\Enum;
   use Phalcon\Cache\Adapter\Redis; // Redisキャッシュアダプタ
   use Phalcon\Storage\SerializerFactory; // シリアライザファクトリー
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       public function mysqlAddAction()
       {
           $connection = new Mysql([/* ... */]);
           $success = $connection->insert(/* ... */);
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       public function mysqlAction()
       {
           $connection = new Mysql([/* ... */]);
           $users = $connection->fetchAll('SELECT * FROM users', Enum::FETCH_ASSOC);
           header('Content-Type: application/json');
           echo json_encode($users);
       }
   
       // Redisキャッシュ例
       public function redisAction()
       {
           // シリアライザファクトリインスタンス
           $serializerFactory = new SerializerFactory();
   
           // Redisキャッシュのオプション指定
           // 設定内容はconfig.phpの'cache'セクションと一致させてください
           $options = [
               'defaultSerializer' => 'Json',
               'lifetime'          => 3600, // キャッシュ有効期間（秒）
               'host'              => '127.0.0.1',
               'port'              => 6379,
               'index'             => 0,
               // 'auth'           => 'your_redis_password', // パスワード設定時のみ
           ];
   
           // Redisキャッシュアダプタ作成
           $cache = new Redis($serializerFactory, $options);
   
           $cacheKey = 'my_servbay_redis_cache_key';
           $cachedData = $cache->get($cacheKey);
   
           if ($cachedData === null) {
               // キャッシュにデータがない場合
               echo "Data not found in cache, fetching from source...";
               $cachedData = 'Data fetched from source: Hello Redis from ServBay!';
               $cache->set($cacheKey, $cachedData);
               echo "Data stored in cache.";
           } else {
               // キャッシュヒット時
               echo "Data found in cache: ";
           }
   
           // キャッシュ取得データを返す
           return $cachedData;
       }
   }

   注意: 実際の開発では、キャッシュ設定もサービス登録し、共通インターフェースで全コントローラから使えるようにすることが推奨です。

5. 動作確認

   ブラウザで https://servbay-phalcon-test.local/redis へアクセス

   • 初回アクセス時は「Data not found in cache, fetching from source...Data stored in cache.」と「Data fetched from source: Hello Redis from ServBay!」が表示
   • キャッシュ有効期間内に再アクセスすると「Data found in cache: 」＋「Data fetched from source: Hello Redis from ServBay!」となり、Redisキャッシュから取得できたことを示します

よくある質問（FAQ）

• Q: サイトにアクセスすると404 Not Foundが出る場合は？
  • A: ServBayのウェブサイト設定で「ウェブサイトルート」がPhalconプロジェクトのpublicディレクトリ（/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public）を正しく指しているかご確認ください。またWebサーバー（CaddyやNginx）の稼働、ローカルドメイン解決の成功も要チェックです。
• Q: 「Class 'Phalcon\Mvc\Application' not found」など、Phalconモジュール未検出エラーの場合は？
  • A: 利用PHPバージョンでPhalcon拡張が有効になっていないことが主な原因です。ServBayの設定画面に戻り、対象PHPバージョンでPhalcon拡張にチェックを入れ、PHPサービスを再起動しましょう。ServBay付属Phalconモジュール有効化方法も参照ください。
• Q: データベース接続ができない場合は？
  • A: app/config/config.phpでの接続情報（ホスト、ユーザー名、パスワード、データベース名）が正しいか、またServBayでDBサービスが起動しているかご確認ください。該当DBに必要な権限の付与、対象データベースの作成も忘れずに。

まとめ

ServBayなら、高性能なPhalconフレームワーク向けローカル開発環境が誰でも簡単に構築できます。本ガイドでは、プロジェクトスケルトンの作成からWebサーバー設定、MySQL・Redis統合までの基本手順を解説しました。ServBayに内蔵された豊富なソフトウェアパッケージと分かりやすいGUIは、開発環境の煩雑なセットアップや管理作業を大幅に軽減してくれます。Phalconアプリ開発により集中できるはずです。このガイドがServBayとPhalconによる高効率Web開発の一助となれば幸いです！