frankenphp

README

FrankenPHP: Modern App Server for PHP

FrankenPHP is a modern application server for PHP built on top of the Caddy web server.

FrankenPHP gives superpowers to your PHP apps thanks to its stunning features: Early Hints, worker mode, real-time capabilities, automatic HTTPS, HTTP/2, and HTTP/3 support...

FrankenPHP works with any PHP app and makes your Symfony projects faster than ever thanks to provided integration with the worker mode (Laravel Octane support coming).

FrankenPHP can also be used as a standalone Go library to embed PHP in any app using net/http.

Learn more on frankenphp.dev and in this slide deck:

Getting Started

docker run -v $PWD:/app/public \
    -p 80:80 -p 443:443 \
    dunglas/frankenphp

Go to https://localhost, and enjoy!

If you prefer not to use Docker, we provide standalone FrankenPHP binaries for Linux and macOS containing PHP 8.2 and most popular PHP extensions: Download FrankenPHP

Note: do not attempt to use https://127.0.0.1. Use localhost and accept the self-signed certificate. Caddy has an automatic TLS handling that auto-trusts some local-based hostnames like localhost, but it does not apply to IP addresses. More details on Caddy's "automatic https" docs.

Docs

• The worker mode
• Early Hints support (103 HTTP status code)
• Real-time
• Configuration
• Docker images
• Compile from sources
• Create static binaries
• Demo app (Symfony) and benchmarks
• Go library documentation
• Contributing and debugging

Examples and Skeletons

• Symfony apps
• WordPress
• Drupal
• Sulu

Documentation

Overview

Package frankenphp embeds PHP in Go projects and provides a SAPI for net/http.

This is the core of the FrankenPHP app server, and can be used in any Go program.

Index

• Variables
• func Init(options ...Option) error
• func NewRequestWithContext(r *http.Request, documentRoot string, l *zap.Logger) *http.Request
• func ServeHTTP(responseWriter http.ResponseWriter, request *http.Request) error
• func Shutdown()
• type FrankenPHPContext
  • func FromContext(ctx context.Context) (fctx *FrankenPHPContext, ok bool)
• type Option
  • func WithLogger(l *zap.Logger) Option
  • func WithNumThreads(numThreads int) Option
  • func WithWorkers(fileName string, num int, env map[string]string) Option
• type PHPConfig
  • func Config() PHPConfig
• type PHPVersion
  • func Version() PHPVersion

Examples

• ServeHTTP
• ServeHTTP (Workers)

Variables

var (
	InvalidRequestError         = errors.New("not a FrankenPHP request")
	AlreaydStartedError         = errors.New("FrankenPHP is already started")
	InvalidPHPVersionError      = errors.New("FrankenPHP is only compatible with PHP 8.2+")
	ZendSignalsError            = errors.New("Zend Signals are enabled, recompile PHP with --disable-zend-signals")
	NotEnoughThreads            = errors.New("the number of threads must be superior to the number of workers")
	MainThreadCreationError     = errors.New("error creating the main thread")
	RequestContextCreationError = errors.New("error during request context creation")
	RequestStartupError         = errors.New("error during PHP request startup")
	ScriptExecutionError        = errors.New("error during PHP script execution")
)

Functions

func Init

func Init(options ...Option) error

Init starts the PHP runtime and the configured workers.

func NewRequestWithContext

func NewRequestWithContext(r *http.Request, documentRoot string, l *zap.Logger) *http.Request

NewRequestWithContext creates a new FrankenPHP request context.

func ServeHTTP

func ServeHTTP(responseWriter http.ResponseWriter, request *http.Request) error

ServeHTTP executes a PHP script according to the given context.

Example

package main

import (
	"log"
	"net/http"

	"github.com/dunglas/frankenphp"
)

func main() {
	if err := frankenphp.Init(); err != nil {
		panic(err)
	}
	defer frankenphp.Shutdown()

	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		req := frankenphp.NewRequestWithContext(r, "/path/to/document/root", nil)
		if err := frankenphp.ServeHTTP(w, req); err != nil {
			panic(err)
		}
	})
	log.Fatal(http.ListenAndServe(":8080", nil))
}

Example (Workers)

package main

import (
	"log"
	"net/http"

	"github.com/dunglas/frankenphp"
)

func main() {
	if err := frankenphp.Init(
		frankenphp.WithWorkers("worker1.php", 4, map[string]string{"ENV1": "foo"}),
		frankenphp.WithWorkers("worker2.php", 2, map[string]string{"ENV2": "bar"}),
	); err != nil {
		panic(err)
	}
	defer frankenphp.Shutdown()

	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		req := frankenphp.NewRequestWithContext(r, "/path/to/document/root", nil)
		if err := frankenphp.ServeHTTP(w, req); err != nil {
			panic(err)
		}
	})
	log.Fatal(http.ListenAndServe(":8080", nil))
}

func Shutdown

func Shutdown()

Shutdown stops the workers and the PHP runtime.

Types

type FrankenPHPContext

type FrankenPHPContext struct {
	// The root directory of the PHP application.
	DocumentRoot string

	// The path in the URL will be split into two, with the first piece ending
	// with the value of SplitPath. The first piece will be assumed as the
	// actual resource (CGI script) name, and the second piece will be set to
	// PATH_INFO for the CGI script to use.
	//
	// Future enhancements should be careful to avoid CVE-2019-11043,
	// which can be mitigated with use of a try_files-like behavior
	// that 404s if the fastcgi path info is not found.
	SplitPath []string

	// Path declared as root directory will be resolved to its absolute value
	// after the evaluation of any symbolic links.
	// Due to the nature of PHP opcache, root directory path is cached: when
	// using a symlinked directory as root this could generate errors when
	// symlink is changed without php-fpm being restarted; enabling this
	// directive will set $_SERVER['DOCUMENT_ROOT'] to the real directory path.
	ResolveRootSymlink bool

	// CGI-like environment variables that will be available in $_SERVER.
	// This map is populated automatically, exisiting key are never replaced.
	Env map[string]string

	// The logger associated with the current request
	Logger *zap.Logger
	// contains filtered or unexported fields
}

FrankenPHPContext provides contextual information about the Request to handle.

func FromContext

func FromContext(ctx context.Context) (fctx *FrankenPHPContext, ok bool)

FromContext extracts the FrankenPHPContext from a context.

type Option

type Option func(h *opt) error

Option instances allow to configure FrankenPHP.

func WithLogger

func WithLogger(l *zap.Logger) Option

WithLogger configures the global logger to use.

func WithNumThreads

func WithNumThreads(numThreads int) Option

WithNumThreads configures the number of PHP threads to start.

func WithWorkers

func WithWorkers(fileName string, num int, env map[string]string) Option

WithWorkers configures the PHP workers to start.

type PHPConfig

type PHPConfig struct {
	Version                PHPVersion
	ZTS                    bool
	ZendSignals            bool
	ZendMaxExecutionTimers bool
}

func Config

func Config() PHPConfig

type PHPVersion

type PHPVersion struct {
	MajorVersion   int
	MinorVersion   int
	ReleaseVersion int
	ExtraVersion   string
	Version        string
	VersionID      int
}

func Version

func Version() PHPVersion

Version returns infos about the PHP version.