PHP Runner

PHP Runner is an OSC service that builds and runs PHP applications directly from a Git repository. You provide a source URL pointing to a PHP project, and OSC clones the repo, installs Composer dependencies, and serves the app with Apache — no Docker knowledge required.

It is the PHP counterpart to Web Runner (Node.js), Python Runner, Golang Runner, and .NET Runner.

Getting Started

Launch a PHP Runner instance from the OSC dashboard.

Prerequisites

  • An OSC account. Sign up here.
  • A PHP application in a Git repository, compatible with PHP 8.3.
  • For private repositories: a personal access token (PAT) with read access.

Serving Model

PHP Runner runs your application with Apache and mod_php, started in the foreground as the container's single process. This is different from every other OSC runner (Node.js, Python, Go, .NET, WebAssembly), which run a plain single-process server directly rather than a full web server. Apache with an embedded PHP interpreter was chosen specifically so that .htaccess files and mod_rewrite rules work the same way they would on a traditional PHP host — this matters for frameworks and CMS-style projects (Laravel, Symfony, WordPress-adjacent tooling) that rely on URL rewriting.

PHP Runner is pinned to PHP 8.3. Support for selecting a different PHP version is not available in this initial release.

Application Requirements

  • The app must be reachable over HTTP on the port provided via the PORT environment variable (OSC injects this automatically; Apache is configured to listen on it).
  • If a composer.json file is present at the build root, Composer dependencies are installed automatically (composer install --no-dev --no-interaction) before your app starts.
  • If your app needs a PHP extension that isn't in the base image — for example pdo_mysql, gd, or intl — install it with a setup.sh script. See System Dependencies below.

Entry Point Detection

The runner looks for your application's entry point in this order, using the first match:

  1. OscEntry (explicit override, if set)
  2. public/index.php (Laravel, Symfony, Slim)
  3. web/index.php (Drupal, and some Symfony layouts)
  4. index.php at the repository root

If none of these are found, the build fails. There is no special-casing for framework-specific dev servers (for example Laravel's artisan serve) in this release — if your framework needs an entry point other than the three conventions above, set OscEntry explicitly.

Create a PHP Runner Instance

Using the OSC dashboard

  1. Go to PHP Runner on OSC.
  2. Click Create instance.
  3. Fill in the required field:
  4. SourceUrl — HTTPS URL of the Git repository (append #branchname for a specific branch)
  5. Optional fields:
  6. GitHubToken — PAT for private repositories
  7. SubPath — subdirectory in the repo to use as the build root (for monorepos)
  8. OscEntry — override the auto-detected entry point
  9. ConfigService + OscAccessToken — load env vars from an App Config Service instance at startup
  10. ConfigApiKey — API key for the config service instance, if it requires one
  11. AnalyticsService — attach an analytics service to the instance
  12. Click Create.

Using the CLI

# Public repository
osc create eyevinn-php-runner myphpapp \
  -o SourceUrl="https://github.com/myorg/myphpapp"

# Private repository
osc create eyevinn-php-runner myphpapp \
  -o SourceUrl="https://github.com/myorg/myphpapp" \
  -o GitHubToken="ghp_..."

# Monorepo with a service in a subdirectory
osc create eyevinn-php-runner myservice \
  -o SourceUrl="https://github.com/myorg/monorepo" \
  -o SubPath="services/myservice"

Usage Example

A minimal PHP application compatible with PHP Runner:

<?php
// public/index.php
header('Content-Type: text/plain');
echo "Hello from PHP Runner on OSC!\n";

Push this to a GitHub repository with public/index.php at that path, then create an instance pointing to that repo. Once running, the instance URL is accessible publicly.

System Dependencies (setup.sh)

If your PHP application needs a PHP extension or OS-level package that isn't included in the base image, place a setup.sh file at the repository root. PHP Runner executes this script as root, after composer install completes and before the application starts.

Example setup.sh to install common extensions:

#!/bin/bash
set -e
apt-get update -qq
apt-get install -y --no-install-recommends libzip-dev libpq-dev
docker-php-ext-install pdo_mysql gd intl
apt-get clean && rm -rf /var/lib/apt/lists/*

Place this file at the root of your repository alongside composer.json.

Using a Parameter Store for Configuration

To inject environment variables (secrets, config) at startup without hardcoding them in the repo:

  1. Create an App Config Service instance.
  2. Store your secrets using the OSC parameter store.
  3. Set ConfigService to the App Config Service instance name and OscAccessToken to your OSC PAT when creating the PHP Runner instance.

The runner fetches all parameters from the config service on startup and injects them as environment variables — before composer install runs, so they're available both at install time and at runtime.

Resource Limits

PHP Runner instances have a 2 Gi memory limit, matching Golang Runner. See My Apps Runtime Limits for the full breakdown across all runtimes.

Good to Know

  • HA mode and stage/prod promotion: these My Apps features are being verified against PHP Runner and may not be fully supported in this initial release. If your workflow depends on HA or stage/prod promotion for a PHP app, check with the OSC team before relying on it.
  • PHP Runner deploys your own Git repository as a running service — it's not a general-purpose PHP hosting platform. See My Apps if this is your first time using this style of deployment on OSC.

Resources