TypePHP Native Core

English | 简体中文

An AOT-first, host-neutral application core for building CLI tools, workers, foreground daemons, and native Windows desktop applications with TypePHP and Zend PHP.

Native Core supplies the application lifecycle and portable service contracts; hosts own the process loop and platform integration. It is intentionally not a Web MVC/API framework. An HTTP host can be built on top, but routing, request/response abstractions, middleware, and a production server are outside the current scope.

Current release line: 0.1.0-alpha.2. Public APIs are still alpha.

Why TypePHP?

TypePHP brings an AOT compilation path to PHP. It lets an explicitly structured PHP application become native code and provides PHPX/C++ interop for operating-system APIs. Native Core is designed so the same application graph can be developed and tested quickly on Zend PHP, then validated and shipped through TypePHP AOT—without rewriting its lifecycle in a second language.

The result is a practical split:

• Zend PHP provides the familiar, fast edit-test loop and Composer tooling.
• TypePHP provides native compilation and a path to C++/platform integration.
• Native Core keeps lifecycle, cancellation, configuration, events, and logging consistent across both runtimes.

What Native Core provides

• Deterministic module startup and reverse-order cleanup from a finally boundary.
• Explicit modules and ServiceFactory objects instead of reflection or runtime scanning.
• Small replaceable ports for configuration, events, logging, clocks, cancellation, filesystems, process locks, and channels.
• AOT-friendly APIs: named callback objects, concrete types, explicit sources, and no runtime code generation.
• Console, foreground Daemon, and reusable Windows Desktop host contracts.
• PHP >=8.4, matching the minimum required by the current TypePHP compiler and generated programs, with no other runtime Composer dependencies.

Dependency direction is always:

Application / Host adapter  ->  Native Core

Platform handles and Win32, SDL, WebView, or daemon-specific behavior never enter src/.

Platform support

Native Core is cross-platform at the Core boundary. Native executables and platform adapters are still built and verified per operating system.

Area	Portability	Current evidence
Host-neutral Core, Console, and Worker	OS-neutral by contract	Zend PHP 8.4 CI on Ubuntu and Windows; TypePHP AOT verified on Windows x64
Foreground Daemon	Core loop is OS-neutral; signals and service integration are adapters	Zend regressions on Ubuntu/Windows and a Windows TypePHP smoke; POSIX signal behavior is not yet verified
Windows Desktop Host	Windows only	Zend contract regressions and a real TypePHP/Win32 desktop smoke
TypePHP AOT	TypePHP targets Linux, macOS, and Windows; each platform produces its own native artifact	This repository currently has native runtime evidence for Windows x64 only

macOS and Linux TypePHP builds are intended and supported by the architecture, but they are not marked confirmed here until the matching build and runtime smokes have actually run.

Installation

Install from Packagist:

composer require typephp-org/native-core:^0.1@alpha

The Composer package contains PHP source only. It does not bundle the TypePHP compiler, PHPX, PHP Embed, native runtime libraries, or build tools. TypePHP projects must list the Core and Host source files explicitly in project.yml.

Quick start

<?php

use TypePHP\NativeCore\Application\ApplicationContext;
use TypePHP\NativeCore\Application\NativeApplication;
use TypePHP\NativeCore\Host\Console\ConsoleHost;
use TypePHP\NativeCore\Host\Console\ConsoleProgram;

final class HelloProgram implements ConsoleProgram
{
    public function execute(ApplicationContext $context): int
    {
        $context->logger()->log('info', 'hello from native core');
        return 0;
    }
}

function main(): void
{
    NativeApplication::configure()
        ->build()
        ->run(new ConsoleHost(new HelloProgram()));
}

TypePHP AOT calls global main() directly. The Zend entrypoint is deliberately small:

<?php

require __DIR__ . '/../../vendor/autoload.php';
require __DIR__ . '/main.php';

main();

See examples/hello-console for the complete example.

Hosts

Host	Intended use	Boundary
Console	Commands and one-shot tools	The program returns an exit code.
Daemon	Foreground workers and service-manager processes	Work observes cooperative cancellation; service installation is external.
Windows Desktop	Win32 desktop application loops	The application owns windows, messages, rendering, and native resources through WindowsDesktopProgram.

Project layout

src/                  Host-neutral Core
hosts/                Console / Daemon / Windows Desktop adapters
examples/             Minimal Console / Worker / Daemon / Desktop examples
tests/                Dependency-free Zend PHP regressions
build/                TypePHP verification and packaging scripts
docs/                 Architecture, public API, toolchain, and evidence
template/             Minimal native application starter

Verification

Portable Zend PHP verification on Linux, macOS, or Windows:

composer install
php tests/lint.php
php tests/run.php
php tests/composer-autoload.php
php examples/hello-console/run-zend.php
php examples/worker/run-zend.php

On Windows, build\windows\run-tests.cmd is a convenience wrapper around the lint and regression commands. The following additional scripts exercise the currently verified Windows TypePHP AOT toolchain:

build\windows\build-typephp.cmd
build\windows\build-aot-integration.cmd
build\windows\build-daemon-smoke.cmd
build\windows\build-desktop-spike.cmd

Build scripts honor TYPEPHP_HOME, PHP_HOME, PHPX_HOME, and VS_BUILD_TOOLS; local installation paths are never part of the PHP API.

See the implementation status and capability matrix for the exact evidence boundary. The architecture, public API, and Web API roadmap describe the intended extension points.

License

TypePHP Native Core is released under the MIT License. TypePHP is a separate GPL open-source project and is not bundled with this package; use its compiler and runtime under the license shipped with the TypePHP release. See the TypePHP toolchain notes for build and ABI details.