Download the PHP package sympress/kernel without Composer

SymPress Kernel

sympress/kernel is the foundation package for SymPress. It gives WordPress projects one Symfony-powered application kernel, one shared dependency injection container, and a predictable way for Composer packages, plugins, MU plugins, and themes to contribute services.

WordPress stays the runtime. The kernel adds structure around bootstrapping, configuration, hooks, console commands, package discovery, and compiled service containers.

Why This Exists

WordPress projects often grow through plugin boot files, global functions, and runtime hook registration. That works well at small scale, but it becomes hard to test and hard to reason about once several packages need to collaborate.

The kernel keeps the parts WordPress is good at:

• the normal plugin, MU plugin, and theme lifecycle
• WordPress hooks as the integration boundary
• Composer packages that can be adopted one at a time

Then it adds the Symfony patterns that pay off in larger codebases:

• constructor-injected services
• bundle-level configuration
• compiler passes and autoconfiguration
• declarative hooks
• cached runtime containers
• Symfony-compatible bundle lifecycle hooks
• resettable services and service subscribers
• testable package boundaries

Requirements

• PHP ^8.5
• Composer
• WordPress
• Symfony DependencyInjection ^8.1.8, Config, Console, Filesystem, Routing, Service Contracts, EventDispatcher, Clock, ExpressionLanguage, and Yaml components

Installation

Boot the kernel from an MU plugin or another early WordPress bootstrap file:

After the kernel has booted, services can be resolved from the shared application container:

Minimal Bundle

SymPress discovers installed Composer packages that expose extra.kernel metadata. Projects that want to narrow discovery can set extra.kernel.package_prefixes in the root composer.json.

The machine-readable metadata contract is schema/kernel-extra.schema.json. Public entry points, lifecycle actions and container inspection commands are listed in resources/kernel-contracts.json and verified by the test suite.

The bundle class can stay small:

Add package services in Resources/config/services.yaml:

Register a WordPress hook declaratively:

The same hook can be registered with a service tag when central configuration is clearer:

Architecture

The runtime model has four layers:

1. App owns the singleton application instance and coordinates booting.
2. SiteKernel extends AbstractKernel and describes the WordPress site.
3. BundleDiscovery finds active kernel packages and creates a BundleRegistry.
4. Container implements Symfony's container interface, wraps a ContainerBuilder, then delegates to the compiled runtime container after boot.

Configuration is loaded in this order:

1. kernel package defaults
2. discovered bundle Resources/config/ directories
3. site root config/ directory

Within each config directory, the kernel loads:

• packages/*.{php,yaml,yml,ini}
• packages/{environment}/*.{php,yaml,yml,ini}
• services.{php,yaml,yml,ini}
• services_{environment}.{php,yaml,yml,ini}
• wordpress.{php,yaml,yml,ini}
• wordpress_{environment}.{php,yaml,yml,ini}

Files are imported through Symfony's DelegatingLoader with PHP, YAML, INI, glob, directory, and closure loaders. The kernel file locator also understands Symfony-style bundle resources such as @ProjectPlugin/Resources/config/foo.yaml.

The compiled container is cached under var/cache/{environment}/kernel. Production requests use the deployment fingerprint as the normal cache invalidation boundary and do not stat every bundle source file before each cache hit. Imported configuration resources are still validated so service wiring changes invalidate the runtime container. Deployment rollovers can use SYMPRESS_KERNEL_BUILD_ID to force a new cache identity, and SYMPRESS_KERNEL_VALIDATE_SOURCE_RESOURCES=1 opts back into source-level freshness checks when the request-time filesystem cost is acceptable. Immutable release snapshots should set SYMPRESS_KERNEL_IMMUTABLE_CACHE=1 together with a build ID: that skips the per-request config and discovery directory scans (about six to eight filesystem calls per bundle) and makes the build ID the only cache boundary.

Bundle discovery also stores the matching Composer package manifest under the kernel cache directory. The manifest is invalidated when Composer metadata such as composer.json, composer.lock, or vendor/composer/installed.php changes, so normal cache hits do not need to scan all installed packages.

Extension Points

Use these points before adding work to plugin boot files:

• Override AbstractKernel::build(ContainerBuilder $builder) for site-wide compiler passes or global container customization.
• Add DependencyInjection/{BundleName}Extension to expose classic Symfony-style bundle configuration. The kernel registers it automatically.
• Or keep configuration directly in the bundle with Symfony 8.1's configure(), prependExtension(), and loadExtension() methods. When no classic extension class exists, the kernel uses Symfony's BundleExtension.
• Override AbstractBundle::build(ContainerBuilder $builder) for package-level compiler passes. Call parent::build($builder) when you want to preserve the automatic extension registration from custom build logic.
• Add Resources/config/services.php, Resources/config/services.yaml, Resources/config/wordpress.php, .ini variants, or environment-specific variants for package configuration. Package-level config/ is still loaded as a compatibility fallback.
• Use the kernel.hook service tag or #[AsHook] attribute for WordPress actions and filters.
• Use #[Route] on controller services for Symfony-style frontend routes and WordPress REST routes. A route with format: 'json' is registered through WordPress as a REST endpoint; other routes are matched as frontend routes.
• Use Symfony's #[AsCommand] attribute to expose console commands through the kernel console integration.
• Use Symfony DI attributes from the component directly, including #[Autowire], #[AutowireIterator], #[AutowireLocator], #[AsAlias], #[AsDecorator], #[AsTagDecorator], #[AutowireDecorated], #[AutowireCallable], #[AutowireMethodOf], #[AutowireServiceClosure], #[AutowireInline], #[Required], #[Target], #[When], #[WhenNot], #[Lazy], #[AutoconfigureResourceTag], and #[Exclude].
• Use Symfony's #[RequiredBundle] attribute when one bundle must be loaded before another. Missing optional requirements can use ignoreOnInvalid: true.
• Depend on the synthetic services SymPress\Kernel\Container, SymPress\Kernel\SiteConfig, SymPress\Kernel\WpContext, SymPress\Kernel\Kernel\KernelInterface, and SymPress\Kernel\App when a service needs runtime context.

Package Manager

The package manager is an optional WordPress admin screen for inspecting kernel packages discovered from Composer metadata and running package lifecycle actions from the backend.

It is disabled by default because it can activate, deactivate, and delete Composer-backed WordPress packages. Enable it deliberately in site configuration only when that operational surface belongs in the install:

The manager respects WordPress file-modification policy and hides package actions when wp_is_file_mod_allowed() or DISALLOW_FILE_MODS blocks them. Direct symlink deletion is limited to the expected managed plugin or theme path.

Core Services

The runtime container exposes Symfony-compatible core IDs and aliases:

• kernel
• service_container
• parameter_bag
• event_dispatcher
• filesystem
• clock
• file_locator
• reverse_container
• config_cache_factory
• services_resetter
• container.env_var_processor
• container.expression_language
• kernel.container
• kernel.config
• kernel.context
• kernel.kernel
• kernel.app

Symfony\Contracts\Service\ResetInterface services are autoconfigured with the kernel.reset tag and wired into services_resetter. When the optional Symfony components are installed, EventDispatcher listeners, subscribers, LoggerAwareInterface, Clock aliases, and PSR/EventDispatcher aliases are autoconfigured in the same style as Symfony's DI ServicesBundle.

Console

Commands tagged with console.command or marked with #[AsCommand] are exposed through the kernel console integration. The kernel also ships lightweight container tooling:

Documentation

More focused docs live in docs/:

• docs/boot-and-bundles.md
• docs/dependency-injection.md
• docs/services-and-autowiring.md
• docs/attributes.md
• docs/hooks.md
• docs/routing.md
• docs/showcase-plugin.md

Development

License

This package is licensed under GPL-2.0-or-later.