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

Phalconとは？

Phalconは、C言語の拡張モジュールとして実装された、オープンソースかつ高性能なPHP Webフレームワークです。このユニークな実装方式により、Phalconは非常に低いリソース消費と圧倒的な実行速度を誇り、従来のPHPフレームワークよりも優れたパフォーマンスを発揮します。PhalconはMVC（Model-View-Controller）アーキテクチャに従い、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などのリレーショナルデータベースやRedisなどのNoSQLデータベースとの統合までの流れを解説します。

前提条件

開始する前に、以下の条件を満たしていることを確認してください。

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フレームワークと専用開発ツール（Phalcon DevTools）のバージョンは、利用する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はPHP 8.xで互換性の問題が発生する可能性があります。
PHP 8.3, 8.4	Phalcon 5.x	dev-master（修正版リポジトリ）	互換性確保のため、コミュニティ修正版の利用を推奨。

重要: PHP 8.x以上では公式のPhalcon DevToolsとの互換性に課題があるため、コミュニティ版の修正リポジトリの使用を推奨します。後述の手順でComposerによる修正版DevTools導入方法も説明します。

Phalconプロジェクトの作成

推奨プロジェクト設置場所

プロジェクト管理を簡単にするため、ServBayではウェブサイトプロジェクトをデフォルトのルートディレクトリ /Applications/ServBay/www 下に設置することを推奨しています。本ガイドの例もこのディレクトリ内で作成します。

1. ルートディレクトリに移動し、プロジェクトフォルダを作成

   ターミナルを開き、ServBayのウェブサイトルートディレクトリに移動し、Phalconプロジェクト用の新規フォルダー（例: 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以降向け (Phalcon DevTools 修正版 dev-master): 公式DevToolsがPHP 8.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プロジェクトの基本構成ファイル群を生成しましょう。実際のプロジェクトコードはサブディレクトリ（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', // <-- 実際のDBパスワードに変更
           'dbname' => 'servbay_phalcon_app', // <-- 実際のDB名に変更
       ],
       // ... その他の設定 ...
   ]);

   重要: ServBayで該当DBサービス（MySQL/MariaDBなど）が起動していること、DBユーザーやパスワードが設定に合っていること、 servbay_phalcon_app データベースが作成済みであることも確認してください。DB作成・管理はphpMyAdminやAdminerなどServBay付属の管理ツールが利用できます。

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

Phalconプロジェクトをブラウザからアクセスできるようにするには、ServBayのウェブサイト機能を使って仮想ホストの設定を行い、プロジェクトの公開ディレクトリへルートを向ける必要があります。

1. ServBayアプリを起動
2. 「ウェブサイト」設定に移動: ServBayメイン画面の「ウェブサイト」セクションに進みます。
3. 新規ウェブサイト追加: ウェブサイト追加ボタンをクリック。
   • 名前: 識別しやすい名称（例: My First Phalcon Dev Site）
   • ドメイン: ブラウザでアクセスするための任意のドメイン名（例: servbay-phalcon-test.local）。ServBayは .local ドメインを自動でローカル解決します。
   • ウェブサイト種別: PHP を選択。
   • PHPバージョン: Phalconモジュールを有効化した該当PHPバージョンを選択。
   • ウェブサイトルートディレクトリ: ここが重要です。Phalconは public ディレクトリがエントリーポイントとなるため、ルートを /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public に指定します。
4. 保存して完了: 新しいウェブサイト設定を保存。必要に応じてWebサーバー（CaddyまたはNginx）を再起動してください。

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

サンプルコード追加

プロジェクトが正常動作するかを確認するため、簡単なサンプルコードを追加しましょう。

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が起動していることを確認してからブラウザで次のURLにアクセスします。

https://servbay-phalcon-test.local

設定が正しければ、ブラウザに Hello ServBay! の表示が出ます。

データベース統合

Phalconは強力なDB抽象層やORMを標準搭載しています。ServBayには各種DBが同梱されており、Phalconとの連携も容易です。ここではMySQLとRedisの例を紹介します。

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

ServBayのMySQLサービスへPhalconのDBアダプタから接続し、シンプルな挿入・検索を行う手順例です。

1. DB構造作成（マイグレーション利用）

   Phalcon DevTools標準のマイグレーション機能でDB構造管理を行えます。

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

     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）はファイル名と一致させてください。ファイル名付与はDevToolsの命名規則に従ってください。

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

     vendor/bin/phalcon migration run

     接続エラーが出る場合は app/config/config.php のDB設定や、ServBayのMySQL/MariaDBサービス起動状況を確認してください。

2. DB接続設定（前述参照）

   app/config/config.php の 'database' 設定がServBayのMySQL/MariaDBサービス（デフォルトホスト: 127.0.0.1、ポート: 3306、ユーザー: root）に合っていることを再確認。

3. サンプルルート追加

   app/config/routes.php にDB操作用のルートを追加しましょう。

   <?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 メソッドを追加し、DB操作例を実装します。ここではPhalconのDBサービスを直接使用します。

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql; // MySQL DBアダプタ
   use Phalcon\Db\Enum; // fetchAll用のモード定数
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       // ユーザー挿入例
       public function mysqlAddAction()
       {
           // コンテナ登録している場合はサービスから取得
           // ここでは便宜上手動でコネクション作成（実アプリでは非推奨）
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- DBパスワード変更必須
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           // デモのユーザー挿入
           $success = $connection->insert(
               'users',
               ['ServBay Demo User', 'demo@servbay.test'],
               ['name', 'email']
           );
   
           // 結果表示
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       // ユーザー検索表示例
       public function mysqlAction()
       {
            // DBコネクション取得
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- DBパスワード変更必須
               '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コンテナでサービスとして管理し、各Action内で都度生成しないことを推奨します。

5. サンプル実行

   • ブラウザで https://servbay-phalcon-test.local/mysql-add にアクセスし「User added successfully.」と表示されれば挿入成功です。
   • 続けて https://servbay-phalcon-test.local/mysql にアクセスすると、users テーブルのデータがJSONで返ってくるはずです。

NoSQLデータベース例：Redis

ServBayのRedisサービスをPhalconアプリ内のキャッシュとして使う例です。

1. Redis拡張のインストール

   ServBay同梱のPHPパッケージには主要な拡張（Redis含む）が標準で入っています。利用PHPバージョンでRedis拡張が有効になっていることのみ確認してください。

2. Redis接続設定

   app/config/config.php にRedis接続情報を追加します。ServBayのRedisはデフォルトで 127.0.0.1 の6379ポートで起動。

   return new \Phalcon\Config([
       // ... その他の設定 ...
       'cache' => [
           'adapter' => 'Redis',
           'host' => '127.0.0.1',
           'port' => 6379,
           'index' => 0,
           'persistent' => false,
           'auth' => null, // パスワード利用時のみ入力
       ],
       // ... その他の設定 ...
   ]);

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 を追加し、Redisキャッシュ操作を実装します。

   <?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キャッシュ設定
           // 設定値はapp/config/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;
       }
   }

   注意: 実運用ではキャッシュオブジェクトをDIサービスとして全体管理する設計が推奨されます。

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: Phalconモジュール未認識エラー（Class 'Phalcon\Mvc\Application' not found等）の場合？
  • A: 利用中のPHPバージョンでPhalconエクステンションが有効になっていない可能性があります。ServBayのUIで該当PHPバージョンのPhalconエクステンションを有効化し、PHPサービスを再起動してください。ServBay同梱Phalconモジュールの有効化方法もご参照ください。
• Q: データベース接続に失敗する場合？
  • A: app/config/config.php のDB接続設定（ホスト、ユーザー名、パスワード、DB名）が正しいか、ServBayのDBサービス（MySQL/MariaDB）が起動しているか、指定ユーザーに必要な権限があるか、データベース自体作成済みかなどを確認しましょう。

まとめ

ServBayを活用すれば、Phalconフレームワークの高性能なローカル開発環境を簡単に構築することができます。本ガイドでは、プロジェクトスケルトンの作成からWebサーバーとの連携、MySQL・Redisなどのデータベース統合まで、基本的な流れを詳しくご紹介しました。ServBay標準搭載の各種ソフトウェアと便利な管理UIにより、ローカル開発環境の構築・維持が大幅に効率化され、Phalconアプリの開発に注力できるようになります。ぜひ本ガイドを参考に、ServBay×Phalconによる快適なWeb開発に挑戦してみてください！