Add FrankenPHP support

[jaydrogers]

Franken PHP

🚀 What this PR does

• Adds FrankenPHP be offered as a variation
• Allow the PHP minor version to be selected with FrankenPHP
• Allow the "autorun" scripts and other custom init scripts to run before bringing up FrankenPHP
• Allow the PHP_ environment variables from other Server Side Up images to work with FrankenPHP

Create documentation

• Laravel + FrankenPHP
• Customizing start up with FrankenPHP
• Installing custom PHP extensions with FrankenPHP

Checklist

• Ensure SSL_MODE works as other variations
• Ensure custom extensions can be installed like other variations

[Sammyjo20]

This would be super cool to have! Great work on this so far!

[cloudflare-workers-and-pages]

Deploying serversideup-php with    Cloudflare Pages

Latest commit:	73b4031
Status:	✅  Deploy successful!
Preview URL:	https://9e48ab3c.serversideup-php.pages.dev
Branch Preview URL:	https://280-create-a-frankenphp-vari.serversideup-php.pages.dev

View logs

[GunniBusch]

This would really be a nice addition..

[thinkstylestudio]

This will be a wonderful addition!

[mihai-burduselu-ptt]

This would be a great feature! 🚀
Any updates here?

[jaydrogers]

Not sure how I missed your message @mihai-burduselu-ptt.

I am getting v3.4 updates out the door for the last major optimizations for fpm-nginx. Then it's FrankenPHP time 😎

[hstoenescu]

This is a great addition to serversideup. Any updates regarding frankenPHP?

[hookenz]

I'd like to see FrankenPHP added too.

[jaydrogers]

Thanks for your patience, all! I'm looking for the future of PHP and I really hope FrankenPHP is it.

I've been very busy with Spin and once I get this big release of Spin v3 out the door, then I will be swinging to this.

Exploring FrankenPHP is very important to me and I will definitely be getting this accomplished 💯

[jaydrogers]

I am back from holiday break and will be evaluating this for v3.6. I have taken about 3 attempts at this and have paused and deleted each time 🙃🔥

My challenge is I believe I need to compile FrankenPHP from source so I can maintain the "single source of truth" from the official Docker PHP images. I need to spend more time ensuring this is the way, since I haven't compiled a Go app in my life 😅

I will keep everyone posted once I have an update but please chime in below if you have any thoughts 🙏

[thomasaull]

@jaydrogers Not sure if this is feasible? The frankenphp images are based on the official docker images and add their stuff on top, so the php images would still be the source of truth? It’s additional work to keep the build working, which is done by the frankenphp maintainers anyway. Since it’s based on official docker images, you should be able to do anything you want with the frankenphp images, don’t you?

That being said, I have no deep understanding about what you’re adding, so my opinion might be invalid 😅

[jaydrogers]

Thanks for chiming in! Yes, you're totally right -- and I've tried this path. This might be a complicated for a single GitHub issue post, but here is an attempt on simpliying a few critical background parts:

1. I use https://www.php.net/releases/active.php as my "source of truth" in get-php-versions.sh
2. This builds a php-versions.yml file (base config is here)

If a new version of PHP is made available and FrankenPHP hasn't released that version yet, the build will fail.

This adds two layers of dependencies for all Server Side Up images (if they are FrankenPHP or not):

1. Official PHP images must be built
2. FrankenPHP must have images built with the EXACT patches that we're trying to use

This is where I hit my head against the wall and decided to take a break and circle back later 😃

I believe my latest theory was to use Multi-stage builds take the official build PHP image, check out a specific version of FrankenPHP, then compile it following their methods -- but I don't want to re-invent the wheel on compiling either 😅

Full build process

docker-php/.github/workflows/service_docker-build-and-publish.yml

Lines 41 to 169 in 4807f98

	- name: Check out code
	uses: actions/checkout@v4
	- name: Prepare PHP versions for the matrix. 😎
	run: |
	chmod +x ./scripts/get-php-versions.sh
	./scripts/get-php-versions.sh
	env:
	SKIP_DOWNLOAD: false
	- name: Ensure our PHP Versions file exists.
	run: |
	if [ ! -f "${{ inputs.php-versions-file }}" ]; then
	echo "PHP Versions file does not exist. Exiting."
	exit 1
	else
	cat ${{ inputs.php-versions-file }}
	fi
	- name: Assemble PHP versions into the matrix. 😎
	id: get-php-versions
	run: |
	MATRIX_JSON=$(yq -o=json scripts/conf/php-versions.yml | jq -c '{include: [(.php_variations[] | {name, supported_os: (.supported_os // ["alpine", "bullseye", "bookworm"])} ) as $variation | .php_versions[] | .minor_versions[] | .patch_versions[] as $patch | .base_os[] as $os | select($variation.supported_os | if length == 0 then . else . | index($os.name) end) | {patch_version: $patch, base_os: $os.name, php_variation: $variation.name}]} | {include: (.include | sort_by(.patch_version | split(".") | map(tonumber) | . as $nums | ($nums[0]*10000 + $nums[1]*100 + $nums[2])) | reverse)}')
	echo "php-version-map-json=${MATRIX_JSON}" >> $GITHUB_OUTPUT
	echo "${MATRIX_JSON}" | jq '.'
	- name: Upload the php-versions.yml file
	uses: actions/upload-artifact@v4
	with:
	name: php-versions.yml
	path: ${{ inputs.php-versions-file }}
	docker-publish:
	needs: setup-matrix
	runs-on: ubuntu-24.04
	## Use AWS runners
	# runs-on:
	# - runs-on
	# - runner=4cpu-linux-x64
	# - run-id=${{ github.run_id }}
	strategy:
	matrix: ${{fromJson(needs.setup-matrix.outputs.php-version-map-json)}}
	steps:
	- name: Check out code.
	uses: actions/checkout@v4
	- name: Download PHP Versions file
	uses: actions/download-artifact@v4
	with:
	name: php-versions.yml
	path: ./artifacts
	- name: Move PHP Versions file
	run: mv ./artifacts/php-versions.yml ${{ inputs.php-versions-file }}
	##
	# Docker build & publish
	##
	- name: Login to DockerHub
	uses: docker/login-action@v3
	if: ${{ inputs.push-to-registry }}
	with:
	username: ${{ secrets.DOCKER_HUB_USERNAME }}
	password: ${{ secrets.DOCKER_HUB_ACCESS_TOKEN }}
	- name: Login to GitHub Container Registry
	uses: docker/login-action@v3
	if: ${{ inputs.push-to-registry && inputs.authenticate_with_ghcr }}
	with:
	registry: ghcr.io
	username: ${{ github.actor }}
	password: ${{ secrets.GITHUB_TOKEN }}
	- name: Set up QEMU
	uses: docker/setup-qemu-action@v3
	- name: Set up Docker Buildx
	uses: docker/setup-buildx-action@v3
	- name: "📦 Assemble the Docker Tags"
	run: |
	chmod +x ./scripts/assemble-docker-tags.sh
	./scripts/assemble-docker-tags.sh
	env:
	PHP_VERSIONS_FILE: "${{ inputs.php-versions-file }}"
	DEFAULT_IMAGE_VARIATION: ${{ inputs.default-image-variation }}
	PHP_BUILD_VERSION: ${{ matrix.patch_version }}
	PHP_BUILD_VARIATION: ${{ matrix.php_variation }}
	PHP_BUILD_BASE_OS: ${{ matrix.base_os }}
	DOCKER_TAG_PREFIX: ${{ inputs.tag-prefix }}
	DOCKER_REGISTRY_REPOSITORIES: ${{ inputs.registry-repositories }}
	RELEASE_TYPE: ${{ inputs.release-type }}
	GITHUB_RELEASE_TAG: ${{ github.ref_name }}
	GITHUB_REF_TYPE: ${{ github.ref_type }}
	- name: Set REPOSITORY_BUILD_VERSION
	id: set_version
	run: |
	if [ "${{ github.ref_type }}" == "tag" ]; then
	echo "🚀 Setting REPOSITORY_BUILD_VERSION to Tag"
	echo "REPOSITORY_BUILD_VERSION=${{ github.ref_name }}" >> $GITHUB_ENV
	else
	echo "👨‍🔬 Setting REPOSITORY_BUILD_VERSION to GIT Short SHA and GitHub Run ID"
	SHORT_SHA=$(echo ${{ github.sha }} | cut -c1-7)
	echo "REPOSITORY_BUILD_VERSION=git-${SHORT_SHA}-${{ github.run_id }}" >> $GITHUB_ENV
	fi
	- name: Build images
	uses: docker/build-push-action@v6
	with:
	file: src/variations/${{ matrix.php_variation }}/Dockerfile
	cache-from: type=gha
	cache-to: type=gha
	## Run-on cache
	# cache-from: type=s3,blobs_prefix=cache/${{ github.repository }}/,manifests_prefix=cache/${{ github.repository }}/,region=${{ env.RUNS_ON_AWS_REGION }},bucket=${{ env.RUNS_ON_S3_BUCKET_CACHE }}
	# cache-to: type=s3,blobs_prefix=cache/${{ github.repository }}/,manifests_prefix=cache/${{ github.repository }}/,region=${{ env.RUNS_ON_AWS_REGION }},bucket=${{ env.RUNS_ON_S3_BUCKET_CACHE }},mode=max
	build-args: |
	BASE_OS_VERSION=${{ matrix.base_os }}
	PHP_VERSION=${{ matrix.patch_version }}
	PHP_VARIATION=${{ matrix.php_variation }}
	REPOSITORY_BUILD_VERSION=${{ env.REPOSITORY_BUILD_VERSION }}
	platforms: |
	linux/amd64
	linux/arm64/v8
	pull: true
	push: ${{ inputs.push-to-registry }}
	tags: ${{ env.DOCKER_TAGS }}
	outputs: type=image,name=target,annotation-index.org.opencontainers.image.description=Supercharge your PHP experience with Docker images that are based off the official PHP images but are optimized to be run in production environments for Laravel and WordPress and more

[thomasaull]

@jaydrogers Thanks for the explaination, I definitely see your point. I guess it’s a trade of between path a) or b) where both require extra work then 😅

If it where up to me to decide, I'd probably add the additional dependency of frankenphp to the automated pipeline: Additionally check the frankenphp releases and only build this flavour of serversideup if the release is available. Again I might be missing something from a lack of knowledge.

Also the frankenphp images apparently are automatically built when a new php image is available: https://frankenphp.dev/docs/docker/#updates