GitHub

Laravel on OxPHP

Laravel is the canonical framework-mode application: a single front controller at public/index.php, with static assets served straight from public/. OxPHP's framework routing mode maps onto this exactly. Existing files are served from disk; everything else is dispatched to index.php.

Stack at a glance

  • OxPHP image: ghcr.io/oxphp/oxphp:0.13.0 (PHP 8.5)
  • Routing mode: Framework (ENTRY_FILE=index.php; DOCUMENT_ROOT left at the default /var/www/html/public)
  • Extensions added: pdo_mysql, intl
  • Services: OxPHP + MySQL
  • URL: http://localhost:8091 · internal http://localhost:9092/health

Project layout

text
laravel-oxphp/ ├── docker-compose.yml └── src/ # composer create-project laravel/laravel src ├── Dockerfile └── … # the Laravel application

Generate the app first:

bash
mkdir -p laravel-oxphp/src docker run --rm -v "$PWD/laravel-oxphp/src":/app -w /app \ composer:2 create-project laravel/laravel . --prefer-dist

Then point src/.env at the database service:

src/.env
APP_URL=http://localhost:8091 DB_CONNECTION=mysql DB_HOST=db DB_PORT=3306 DB_DATABASE=laravel DB_USERNAME=laravel DB_PASSWORD=laravel

Dockerfile and Compose

src/Dockerfile copies OxPHP into a php:8.5-zts-alpine base that carries Laravel's runtime extensions.

src/Dockerfile
ARG OXPHP_VERSION=0.13.0 ARG PHP_VERSION=8.5 ARG ALPINE_VERSION=3.23 # ── PHP base: Laravel runtime extensions ────────────────────── FROM php:${PHP_VERSION}-zts-alpine${ALPINE_VERSION} AS php-base RUN apk add --no-cache icu-libs \ && apk add --no-cache --virtual .build-deps icu-dev \ && docker-php-ext-install pdo_mysql intl \ && apk del .build-deps # ── Composer ────────────────────────────────────────────────── FROM composer:2 AS composer # ── OxPHP artifacts ─────────────────────────────────────────── FROM ghcr.io/oxphp/oxphp:${OXPHP_VERSION} AS oxphp # ── dev: OxPHP server + PHP CLI + Composer ──────────────────── FROM php-base AS dev RUN apk add --no-cache libgcc COPY --from=composer /usr/bin/composer /usr/local/bin/composer COPY --from=oxphp /usr/local/bin/oxphp /usr/local/bin/oxphp COPY --from=oxphp /usr/local/lib/liboxphp_bridge.so /usr/local/lib/ COPY --from=oxphp /usr/local/lib/php/extensions/ /tmp/oxphp-ext/ RUN cp /tmp/oxphp-ext/*/oxphp_sapi.so "$(php -r 'echo ini_get("extension_dir");')/" \ && rm -rf /tmp/oxphp-ext \ && echo "extension=oxphp_sapi.so" > /usr/local/etc/php/conf.d/oxphp-ext.ini RUN { \ echo "[opcache]"; echo "opcache.enable=1"; echo "opcache.enable_cli=1"; \ echo "opcache.validate_timestamps=1"; echo "opcache.revalidate_freq=0"; \ } > /usr/local/etc/php/conf.d/opcache-dev.ini RUN getent passwd www-data >/dev/null \ || adduser -D -H -u 82 -G www-data -s /sbin/nologin www-data RUN mkdir -p /var/www/html/public && chown -R www-data:www-data /var/www/html ENV LD_LIBRARY_PATH=/usr/local/lib WORKDIR /var/www/html COPY --chown=www-data:www-data . /var/www/html EXPOSE 80 9090 CMD ["oxphp"]

Install and first run

The dev image carries the PHP CLI and Composer, so artisan runs in the same container:

bash
docker compose up -d --build docker compose exec app php artisan key:generate docker compose exec app php artisan migrate

OxPHP notes

Note
  • ENTRY_FILE=index.php selects framework mode. Laravel's public/ becomes DOCUMENT_ROOT, and the framework's own .env, app/ and vendor/ stay outside the document root, where they are never reachable over HTTP.
  • The container environment overrides .env. OxPHP passes the container environment to PHP, and Laravel's dotenv loader does not override real environment variables, so DB_HOST, APP_ENV, etc. set in Compose win.
  • In the dev target OPcache revalidates on every request, so edits on the bind-mounted src/ take effect immediately. For production, set opcache.validate_timestamps=0 and drop the bind mount.

Verify

bash
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8091/ # 200 curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8091/up # 200 (health route) curl -s -o /dev/null -w "%{http_code}\n" http://localhost:9092/health # 200

Prompts for your agent

These prompts assume an agent with the OxPHP documentation MCP server connected. The agent reads the pages it needs itself.

prompt
Run my Laravel application on OxPHP locally. Read the `examples/framework/laravel` page through the OxPHP documentation MCP server. Write the Dockerfile and the Compose file for this repository specifically — keeping the database, cache and queue services it already uses — and give me the commands to bring it up the first time.
prompt
My Laravel app runs on OxPHP but something behaves differently than it did under PHP-FPM. Read the `examples/framework/laravel` page through the OxPHP documentation MCP server. Go through the OxPHP-specific notes on that page against my code and tell me which one explains what I am seeing.

See also

Found a mistake? Report it →