パッケージ - Octane - 《Laravel 11.x ドキュメント》日本語

はじめに
インストール
サーバーの前提条件
アプリケーションの提供
依存性注入とOctane
同時タスク
Octaneキャッシュ
- キャッシュ間隔
テーブル

はじめに

Laravel Octane は、高性能なアプリケーションサーバー（FrankenPHP、Open Swoole、Swoole、RoadRunnerを含む）を使用してアプリケーションのパフォーマンスを向上させます。Octaneはアプリケーションを一度起動し、メモリに保持し、超音速の速度でリクエストを処理します。

インストール

OctaneはComposerパッケージマネージャーを介してインストールできます：

composer require laravel/octane

Octaneをインストールした後、octane:install Artisanコマンドを実行して、Octaneの設定ファイルをアプリケーションにインストールできます：

php artisan octane:install

サーバーの前提条件

Laravel OctaneはPHP 8.1+を必要とします。

FrankenPHP

FrankenPHPは、Goで書かれたPHPアプリケーションサーバーで、早期ヒント、Brotli、Zstandard圧縮などの最新のWeb機能をサポートしています。Octaneをインストールし、FrankenPHPをサーバーとして選択すると、Octaneは自動的にFrankenPHPのバイナリをダウンロードしてインストールします。

Laravel Sailを介したFrankenPHP

Laravel Sailを使用してアプリケーションを開発する予定の場合、OctaneとFrankenPHPをインストールするために次のコマンドを実行する必要があります：

./vendor/bin/sail up
./vendor/bin/sail composer require laravel/octane

次に、octane:install Artisanコマンドを使用してFrankenPHPのバイナリをインストールする必要があります：

./vendor/bin/sail artisan octane:install --server=frankenphp

最後に、アプリケーションのdocker-compose.ymlファイルのlaravel.testサービス定義にSUPERVISOR_PHP_COMMAND環境変数を追加します。この環境変数には、SailがOctaneを使用してアプリケーションを提供するために使用するコマンドが含まれます：

services:
  laravel.test:
   environment:
   SUPERVISOR_PHP_COMMAND: "/usr/bin/php -d variables_order=EGPCS /var/www/html/artisan octane:start --server=frankenphp --host=0.0.0.0 --admin-port=2019 --port=80"
   XDG_CONFIG_HOME:  /var/www/html/config
   XDG_DATA_HOME:  /var/www/html/data

HTTPS、HTTP/2、およびHTTP/3を有効にするには、代わりにこれらの変更を適用します：

services:
  laravel.test:
   ports:
        - '${APP_PORT:-80}:80'
        - '${VITE_PORT:-5173}:${VITE_PORT:-5173}'
        - '443:443'
        - '443:443/udp'
   environment:
   SUPERVISOR_PHP_COMMAND: "/usr/bin/php -d variables_order=EGPCS /var/www/html/artisan octane:start --host=localhost --port=443 --admin-port=2019 --https"
   XDG_CONFIG_HOME:  /var/www/html/config
   XDG_DATA_HOME:  /var/www/html/data

通常、FrankenPHP Sailアプリケーションにはhttps://localhostを介してアクセスする必要があります。https://127.0.0.1を使用するには追加の設定が必要であり、推奨されていません。

Dockerを介したFrankenPHP

FrankenPHPの公式Dockerイメージを使用すると、パフォーマンスが向上し、静的インストールのFrankenPHPには含まれていない追加の拡張機能を使用できます。さらに、公式Dockerイメージは、WindowsなどのネイティブにサポートされていないプラットフォームでFrankenPHPを実行するためのサポートを提供します。FrankenPHPの公式Dockerイメージは、ローカル開発と本番使用の両方に適しています。

FrankenPHPを使用したLaravelアプリケーションをコンテナ化するための出発点として、次のDockerfileを使用できます：

FROM dunglas/frankenphp
RUN install-php-extensions \
   pcntl
   # Add other PHP extensions here...
COPY . /app
ENTRYPOINT ["php", "artisan", "octane:frankenphp"]

次に、開発中にアプリケーションを実行するために次のDocker Composeファイルを利用できます：


# compose.yaml
services:
  frankenphp:
   build:
   context: .
   entrypoint: php artisan octane:frankenphp --workers=1 --max-requests=1
   ports:
      - "8000:8000"
   volumes:
      - .:/app

公式FrankenPHPドキュメントを参照して、DockerでFrankenPHPを実行する方法についての詳細を確認できます。

RoadRunner

RoadRunnerは、Goを使用して構築されたRoadRunnerバイナリによって動作します。RoadRunnerベースのOctaneサーバーを初めて起動すると、OctaneはRoadRunnerバイナリをダウンロードしてインストールするオプションを提供します。

Laravel Sailを介したRoadRunner

Laravel Sailを使用してアプリケーションを開発する予定の場合、OctaneとRoadRunnerをインストールするために次のコマンドを実行する必要があります：

./vendor/bin/sail up
./vendor/bin/sail composer require laravel/octane spiral/roadrunner-cli spiral/roadrunner-http

次に、Sailシェルを起動し、rr実行可能ファイルを使用して最新のLinuxベースのRoadRunnerバイナリを取得します：

./vendor/bin/sail shell
# Sailシェル内で...
./vendor/bin/rr get-binary

次に、アプリケーションのdocker-compose.ymlファイルのlaravel.testサービス定義にSUPERVISOR_PHP_COMMAND環境変数を追加します。この環境変数には、SailがOctaneを使用してアプリケーションを提供するために使用するコマンドが含まれます：

services:
  laravel.test:
   environment:
   SUPERVISOR_PHP_COMMAND: "/usr/bin/php -d variables_order=EGPCS /var/www/html/artisan octane:start --server=roadrunner --host=0.0.0.0 --rpc-port=6001 --port=80"

最後に、rrバイナリが実行可能であることを確認し、Sailイメージをビルドします：

chmod +x ./rr
./vendor/bin/sail build --no-cache

Swoole

Laravel Octaneアプリケーションを提供するためにSwooleアプリケーションサーバーを使用する予定の場合、Swoole PHP拡張をインストールする必要があります。通常、これはPECLを介して行うことができます：

pecl install swoole

Open Swoole

Laravel Octaneアプリケーションを提供するためにOpen Swooleアプリケーションサーバーを使用する予定の場合、Open Swoole PHP拡張をインストールする必要があります。通常、これはPECLを介して行うことができます：

pecl install openswoole

Open Swooleを使用したLaravel Octaneは、Swooleが提供する同じ機能（同時タスク、ティック、間隔など）を提供します。

Laravel Sailを介したSwoole

Sailを介してOctaneアプリケーションを提供する前に、最新のLaravel Sailバージョンを持っていることを確認し、アプリケーションのルートディレクトリ内で./vendor/bin/sail build --no-cacheを実行します。

また、Laravel Sailを使用してSwooleベースのOctaneアプリケーションを開発することもできます。Laravel SailにはデフォルトでSwoole拡張が含まれています。ただし、Sailで使用されるdocker-compose.ymlファイルを調整する必要があります。

始めるには、アプリケーションのdocker-compose.ymlファイルのlaravel.testサービス定義にSUPERVISOR_PHP_COMMAND環境変数を追加します。この環境変数には、SailがOctaneを使用してアプリケーションを提供するために使用するコマンドが含まれます：

services:
  laravel.test:
   environment:
   SUPERVISOR_PHP_COMMAND: "/usr/bin/php -d variables_order=EGPCS /var/www/html/artisan octane:start --server=swoole --host=0.0.0.0 --port=80"

最後に、Sailイメージをビルドします：

./vendor/bin/sail build --no-cache

Swooleの設定

Swooleには、必要に応じてoctane設定ファイルに追加できるいくつかの追加設定オプションがあります。これらのオプションは、通常変更する必要がないため、デフォルトの設定ファイルには含まれていません：

'swoole' => [
   'options' => [
   'log_file' => storage_path('logs/swoole_http.log'),
   'package_max_length' => 10 * 1024 * 1024,
   ],
],

アプリケーションの提供

Octaneサーバーは、octane:start Artisanコマンドを介して起動できます。デフォルトでは、このコマンドはアプリケーションのoctane設定ファイルのserver設定オプションで指定されたサーバーを利用します：

php artisan octane:start

デフォルトでは、Octaneはポート8000でサーバーを起動するため、http://localhost:8000を介してWebブラウザでアプリケーションにアクセスできます。

HTTPSを介したアプリケーションの提供

デフォルトでは、Octaneを介して実行されるアプリケーションは、http://で始まるリンクを生成します。アプリケーションのconfig/octane.php設定ファイル内で使用されるOCTANE_HTTPS環境変数は、アプリケーションをHTTPSで提供する際にtrueに設定できます。この設定値がtrueに設定されると、OctaneはLaravelにすべての生成されたリンクにhttps://をプレフィックスするよう指示します：

'https' => env('OCTANE_HTTPS', false),

Nginxを介したアプリケーションの提供

自分のサーバー設定を管理する準備ができていない場合や、堅牢なLaravel Octaneアプリケーションを実行するために必要なさまざまなサービスを設定することに自信がない場合は、Laravel Forgeを確認してください。

本番環境では、OctaneアプリケーションをNginxやApacheなどの従来のWebサーバーの背後で提供する必要があります。これにより、Webサーバーが画像やスタイルシートなどの静的アセットを提供し、SSL証明書の終了を管理できます。

以下のNginx設定例では、Nginxはサイトの静的アセットを提供し、ポート8000で実行されているOctaneサーバーにリクエストをプロキシします：

map $http_upgrade $connection_upgrade {
   default upgrade;
   ''      close;
}
server {
   listen 80;
   listen [::]:80;
   server_name domain.com;
   server_tokens off;
   root /home/forge/domain.com/public;
   index index.php;
   charset utf-8;
   location /index.php {
   try_files /not_exists @octane;
   }
   location / {
   try_files $uri $uri/ @octane;
   }
   location = /favicon.ico { access_log off; log_not_found off; }
   location = /robots.txt  { access_log off; log_not_found off; }
   access_log off;
   error_log  /var/log/nginx/domain.com-error.log error;
   error_page 404 /index.php;
   location @octane {
   set $suffix "";
   if ($uri = /index.php) {
   set $suffix ?$query_string;
   }
   proxy_http_version 1.1;
   proxy_set_header Host $http_host;
   proxy_set_header Scheme $scheme;
   proxy_set_header SERVER_PORT $server_port;
   proxy_set_header REMOTE_ADDR $remote_addr;
   proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
   proxy_set_header Upgrade $http_upgrade;
   proxy_set_header Connection $connection_upgrade;
   proxy_pass http://127.0.0.1:8000$suffix;
   }
}

ファイル変更の監視

Octaneサーバーが起動すると、アプリケーションは一度メモリにロードされるため、アプリケーションのファイルに対する変更はブラウザを更新しても反映されません。たとえば、routes/web.phpファイルに追加されたルート定義は、サーバーが再起動されるまで反映されません。便利なことに、--watchフラグを使用して、Octaneにアプリケーション内のファイル変更があるたびにサーバーを自動的に再起動するよう指示できます：

php artisan octane:start --watch

この機能を使用する前に、Nodeがローカル開発環境にインストールされていることを確認してください。さらに、プロジェクト内にChokidarファイル監視ライブラリをインストールする必要があります：

npm install --save-dev chokidar

アプリケーションのconfig/octane.php設定ファイル内のwatch設定オプションを使用して、監視するディレクトリやファイルを構成できます。

ワーカー数の指定

デフォルトでは、Octaneはマシンが提供する各CPUコアに対してアプリケーションリクエストワーカーを起動します。これらのワーカーは、アプリケーションに入ってくるHTTPリクエストを処理するために使用されます。octane:startコマンドを呼び出すときに--workersオプションを使用して、起動したいワーカーの数を手動で指定できます：

php artisan octane:start --workers=4

Swooleアプリケーションサーバーを使用している場合、開始したい「タスクワーカー」の数も指定できます：

php artisan octane:start --workers=4 --task-workers=6

最大リクエスト数の指定

不要なメモリリークを防ぐために、Octaneは500リクエストを処理した後にワーカーを優雅に再起動します。この数を調整するには、--max-requestsオプションを使用できます：

php artisan octane:start --max-requests=250

ワーカーの再読み込み

Octaneサーバーのアプリケーションワーカーを優雅に再起動するには、octane:reloadコマンドを使用します。通常、これはデプロイ後に行うべきであり、新しくデプロイされたコードがメモリに読み込まれ、以降のリクエストに提供されるようにします：

php artisan octane:reload

サーバーの停止

Octaneサーバーを停止するには、octane:stop Artisanコマンドを使用します：

php artisan octane:stop

サーバーの状態を確認

Octaneサーバーの現在の状態を確認するには、octane:status Artisanコマンドを使用します：

php artisan octane:status

依存性注入とOctane

Octaneはアプリケーションを一度起動し、リクエストを処理している間メモリに保持するため、アプリケーションを構築する際に考慮すべきいくつかの注意点があります。たとえば、アプリケーションのサービスプロバイダーのregisterおよびbootメソッドは、リクエストワーカーが最初に起動したときに一度だけ実行されます。以降のリクエストでは、同じアプリケーションインスタンスが再利用されます。

このため、アプリケーションサービスコンテナやリクエストを任意のオブジェクトのコンストラクタに注入する際には特に注意が必要です。そうすることで、そのオブジェクトは以降のリクエストで古いバージョンのコンテナやリクエストを持つ可能性があります。

Octaneはリクエスト間でのファーストパーティフレームワークの状態のリセットを自動的に処理します。ただし、Octaneはアプリケーションによって作成されたグローバル状態をリセットする方法を常に知っているわけではありません。したがって、Octaneに優しい方法でアプリケーションを構築する方法を理解しておく必要があります。以下では、Octaneを使用する際に問題を引き起こす可能性のある最も一般的な状況について説明します。

コンテナ注入

一般的に、アプリケーションサービスコンテナやHTTPリクエストインスタンスを他のオブジェクトのコンストラクタに注入することは避けるべきです。たとえば、次のバインディングは、シングルトンとしてバインドされたオブジェクトにアプリケーションサービスコンテナ全体を注入します：

use App\Service;
use Illuminate\Contracts\Foundation\Application;
/**
 * Register any application services.
 */
public function register(): void
{
   $this->app->singleton(Service::class, function (Application $app) {
   return new Service($app);
   });
}

この例では、Serviceインスタンスがアプリケーションの起動プロセス中に解決されると、コンテナがサービスに注入され、その同じコンテナが以降のリクエストでServiceインスタンスによって保持されます。これは、特定のアプリケーションにとって問題ではないかもしれませんが、起動サイクルの後半や以降のリクエストで追加されたバインディングがコンテナに見つからないという予期しない問題を引き起こす可能性があります。

回避策として、シングルトンとしてのバインディングの登録を停止するか、常に現在のコンテナインスタンスを解決するコンテナリゾルバクロージャをサービスに注入することができます：

use App\Service;
use Illuminate\Container\Container;
use Illuminate\Contracts\Foundation\Application;
$this->app->bind(Service::class, function (Application $app) {
   return new Service($app);
});
$this->app->singleton(Service::class, function () {
   return new Service(fn () => Container::getInstance());
});

グローバルappヘルパーとContainer::getInstance()メソッドは、常にアプリケーションコンテナの最新バージョンを返します。

リクエスト注入

一般的に、アプリケーションサービスコンテナやHTTPリクエストインスタンスを他のオブジェクトのコンストラクタに注入することは避けるべきです。たとえば、次のバインディングは、シングルトンとしてバインドされたオブジェクトにリクエストインスタンス全体を注入します：

use App\Service;
use Illuminate\Contracts\Foundation\Application;
/**
 * Register any application services.
 */
public function register(): void
{
   $this->app->singleton(Service::class, function (Application $app) {
   return new Service($app['request']);
   });
}

この例では、Serviceインスタンスがアプリケーションの起動プロセス中に解決されると、HTTPリクエストがサービスに注入され、その同じリクエストが以降のリクエストでServiceインスタンスによって保持されます。したがって、すべてのヘッダー、入力、およびクエリ文字列データが不正確になり、他のリクエストデータも同様です。

回避策として、シングルトンとしてのバインディングの登録を停止するか、常に現在のリクエストインスタンスを解決するリクエストリゾルバクロージャをサービスに注入することができます。また、最も推奨されるアプローチは、オブジェクトが必要とする特定のリクエスト情報をオブジェクトのメソッドのいずれかにランタイムで渡すことです：

use App\Service;
use Illuminate\Contracts\Foundation\Application;
$this->app->bind(Service::class, function (Application $app) {
   return new Service($app['request']);
});
$this->app->singleton(Service::class, function (Application $app) {
   return new Service(fn () => $app['request']);
});
// Or...
$service->method($request->input('name'));

グローバルrequestヘルパーは、アプリケーションが現在処理しているリクエストを常に返すため、アプリケーション内で安全に使用できます。

コントローラーメソッドやルートクロージャでIlluminate\Http\Requestインスタンスを型ヒントすることは許可されています。

設定リポジトリの注入

一般的に、設定リポジトリインスタンスを他のオブジェクトのコンストラクタに注入することは避けるべきです。たとえば、次のバインディングは、シングルトンとしてバインドされたオブジェクトに設定リポジトリを注入します：

use App\Service;
use Illuminate\Contracts\Foundation\Application;
/**
 * Register any application services.
 */
public function register(): void
{
   $this->app->singleton(Service::class, function (Application $app) {
   return new Service($app->make('config'));
   });
}

この例では、リクエスト間で設定値が変更されると、そのサービスは元のリポジトリインスタンスに依存しているため、新しい値にアクセスできません。

回避策として、シングルトンとしてのバインディングの登録を停止するか、クラスに設定リポジトリリゾルバクロージャを注入することができます：

use App\Service;
use Illuminate\Container\Container;
use Illuminate\Contracts\Foundation\Application;
$this->app->bind(Service::class, function (Application $app) {
   return new Service($app->make('config'));
});
$this->app->singleton(Service::class, function () {
   return new Service(fn () => Container::getInstance()->make('config'));
});

グローバルconfigは、常に設定リポジトリの最新バージョンを返すため、アプリケーション内で安全に使用できます。

メモリリークの管理

Octaneはリクエスト間でアプリケーションをメモリに保持するため、静的に維持される配列にデータを追加するとメモリリークが発生します。たとえば、次のコントローラーはメモリリークを持っています。なぜなら、アプリケーションへの各リクエストが静的$data配列にデータを追加し続けるからです：

use App\Service;
use Illuminate\Http\Request;
use Illuminate\Support\Str;
/**
 * Handle an incoming request.
 */
public function index(Request $request): array
{
   Service::$data[] = Str::random(10);
   return [
   // ...
   ];
}

アプリケーションを構築する際には、この種のメモリリークを作成しないよう特に注意する必要があります。ローカル開発中にアプリケーションのメモリ使用量を監視し、新しいメモリリークをアプリケーションに導入していないことを確認することをお勧めします。

同時タスク

この機能にはSwooleが必要です。

Swooleを使用する場合、軽量のバックグラウンドタスクを介して操作を同時に実行できます。これは、Octaneのconcurrentlyメソッドを使用して実現できます。このメソッドをPHPの配列分解と組み合わせて、各操作の結果を取得できます：

use App\Models\User;
use App\Models\Server;
use Laravel\Octane\Facades\Octane;
[$users, $servers] = Octane::concurrently([
   fn () => User::all(),
   fn () => Server::all(),
]);

Octaneによって処理される同時タスクは、Swooleの「タスクワーカー」を利用し、受信リクエストとはまったく異なるプロセス内で実行されます。同時タスクを処理するために利用可能なワーカーの数は、octane:startコマンドの--task-workersディレクティブによって決まります：

php artisan octane:start --workers=4 --task-workers=6

 <a name="ticks-and-intervals"></a>
## ティックと間隔
この機能には[Swoole](#swoole)が必要です。  
Swooleを使用する場合、指定された秒数ごとに実行される「ティック」操作を登録できます。`````tick`````メソッドを介して「ティック」コールバックを登録できます。`````tick`````メソッドに提供される最初の引数は、ティッカーの名前を表す文字列である必要があります。2番目の引数は、指定された間隔で呼び出されるコール可能なものである必要があります。  
この例では、10秒ごとに呼び出されるクロージャを登録します。通常、`````tick`````メソッドは、アプリケーションのサービスプロバイダーの`````boot`````メソッド内で呼び出されるべきです：  
``````php
Octane::tick('simple-ticker', fn () => ray('Ticking...'))
   ->seconds(10);
`


``````php
Octane::tick('simple-ticker', fn () => ray('Ticking...'))
   ->seconds(10)
   ->immediate();
`

Octaneキャッシュ

この機能にはSwooleが必要です。

Swooleを使用する場合、読み取りおよび書き込み速度が毎秒200万オペレーションに達するOctaneキャッシュドライバーを利用できます。したがって、このキャッシュドライバーは、キャッシュレイヤーから極端な読み取り/書き込み速度を必要とするアプリケーションにとって優れた選択肢です。

このキャッシュドライバーは Swooleテーブルによって動作します。キャッシュに保存されたすべてのデータは、サーバー上のすべてのワーカーが利用できます。ただし、サーバーが再起動されるとキャッシュデータはフラッシュされます：

Cache::store('octane')->put('framework', 'Laravel', 30);

Octaneキャッシュに許可される最大エントリ数は、アプリケーションのoctane設定ファイルで定義できます。

キャッシュ間隔

Laravelのキャッシュシステムによって提供される通常のメソッドに加えて、Octaneキャッシュドライバーには間隔ベースのキャッシュがあります。これらのキャッシュは指定された間隔で自動的に更新され、アプリケーションのサービスプロバイダーのbootメソッド内で登録する必要があります。たとえば、次のキャッシュは5秒ごとに更新されます：

use Illuminate\Support\Str;
Cache::store('octane')->interval('random', function () {
   return Str::random(10);
}, seconds: 5);

テーブル

この機能にはSwooleが必要です。

Swooleを使用する場合、独自の任意のSwooleテーブルを定義して操作できます。Swooleテーブルは極端なパフォーマンススループットを提供し、これらのテーブル内のデータはサーバー上のすべてのワーカーがアクセスできます。ただし、サーバーが再起動されると、内部のデータは失われます。

テーブルは、アプリケーションのoctane設定ファイルのtables設定配列内で定義する必要があります。最大1000行を許可するテーブルがすでに構成されています。文字列列の最大サイズは、以下のように列の型の後に列サイズを指定することで構成できます：

'tables' => [
   'example:1000' => [
   'name' => 'string:1000',
   'votes' => 'int',
   ],
],

テーブルにアクセスするには、Octane::tableメソッドを使用できます：

use Laravel\Octane\Facades\Octane;
Octane::table('example')->set('uuid', [
   'name' => 'Nuno Maduro',
   'votes' => 1000,
]);
return Octane::table('example')->get('uuid');

Swooleテーブルでサポートされている列の型は、string、int、floatです。