Framework Integration

Purpose and Scope

This document covers how the hypervel/cache package integrates with the Hyperf framework through its registration and bootstrapping mechanisms. It explains the package's entry points, dependency injection configuration, and how various components are wired together during application startup.

For information about the specific console commands available after registration, see Console Commands. For details about the event system and available events, see Event System. For the global helper function API, see Helper Functions.

Package Structure and Registration

The package uses Hyperf's standard configuration provider pattern to register all its components with the framework container.

Composer Package Definition

The package is defined in composer.json1-53 with the following key integration points:

Configuration	Value	Purpose
Package Name	hypervel/cache	Composer identifier
Type	library	Package classification
Autoload PSR-4	Hypervel\Cache\ → src/	Class autoloading namespace
Autoload Files	src/Functions.php	Global helper functions
PHP Version	^8.2	Minimum PHP requirement
Hyperf Config Hook	Hypervel\Cache\ConfigProvider	Framework registration entry point

The extra.hyperf.config section at composer.json46-48 tells Hyperf to invoke the ConfigProvider class during application bootstrap.

Sources: composer.json1-53

ConfigProvider Registration Entry Point

The ConfigProvider class at src/ConfigProvider.php14-41 serves as the central registration point for all framework integrations. When invoked by Hyperf during bootstrap, it returns an array defining:

• dependencies: Container bindings for dependency injection
• listeners: Event listeners to register
• commands: Console commands to make available
• publish: Configuration files that can be published to the application

Sources: composer.json46-48 src/ConfigProvider.php14-41

Dependency Injection Bindings

The ConfigProvider registers two key container bindings at src/ConfigProvider.php19-22:

Factory Interface Binding

This binding maps the Hypervel\Cache\Contracts\Factory interface to the concrete CacheManager implementation. Applications can type-hint Factory in constructors or use make(Factory::class) to receive a CacheManager instance.

Sources: src/ConfigProvider.php20

Store Interface Binding

This binding resolves the Hypervel\Cache\Contracts\Store interface to the default cache driver configured in the application. It:

1. Retrieves the CacheManager from the container
2. Calls driver() with no arguments to get the default store
3. Returns the store instance (e.g., RedisStore, SwooleStore)

The default driver is determined by the CACHE_DRIVER environment variable or the cache.default configuration value.

Sources: src/ConfigProvider.php21 publish/cache.php22

Dependency Injection Flow

Sources: src/ConfigProvider.php19-22

Event Listener Registration

The package registers event listeners at src/ConfigProvider.php23-26 to hook into framework lifecycle events.

Registered Listeners

Listener Class	Event	Purpose
CreateSwooleTable	BeforeServerStart	Initialize Swoole tables before server starts
CreateTimer	Framework timing events	Create interval timers for cache maintenance

CreateSwooleTable Listener

The CreateSwooleTable listener at src/Listeners/CreateSwooleTable.php10-25 listens for the BeforeServerStart event. When triggered:

1. It iterates through all cache stores configured in the application
2. For each store using the swoole driver, it retrieves the configured table name
3. It calls SwooleTableManager::get() to initialize the Swoole table with the specified configuration

This ensures that Swoole shared memory tables are created before any workers start, as Swoole tables must be initialized in the master process before forking workers.

Sources: src/ConfigProvider.php23-26 src/Listeners/CreateSwooleTable.php10-25

Console Command Registration

The ConfigProvider registers console commands at src/ConfigProvider.php27-30 to provide administrative tools for cache management.

Registered Commands

Command Class	Command Name	Purpose
ClearCommand	cache:clear	Flush all or specific cache stores
PruneDbExpiredCommand	cache:prune-db-expired	Remove expired entries from database cache

These commands become available via the Hyperf CLI after the package is installed. For detailed documentation of each command's functionality and options, see Console Commands.

Command Registration Flow

The registration process makes commands discoverable to the Hyperf console kernel:

1. ConfigProvider returns command class names in the commands array
2. Hyperf's console component reads this array during bootstrap
3. Commands are instantiated and registered with the console kernel
4. Commands become available via php bin/hyperf.php <command-name>

Sources: src/ConfigProvider.php27-30 src/Console/PruneDbExpiredCommand.php1-66

Configuration Publishing

The package provides a publishable configuration file through the publish section at src/ConfigProvider.php31-38

Publication Configuration

Property	Value	Description
id	config	Publication identifier
description	"The config for cache."	Human-readable description
source	__DIR__ . '/../publish/cache.php'	Source file location
destination	BASE_PATH . '/config/autoload/cache.php'	Target location in application

Publishing Process

Users publish the configuration file by running:

This copies publish/cache.php1-111 to the application's config/autoload/ directory, where it can be customized.

Configuration Structure

The published configuration file provides:

Section	Lines	Purpose
Default Driver	publish/cache.php22	Sets cache.default from CACHE_DRIVER env var
Store Configurations	publish/cache.php37-83	Defines settings for each driver type
Swoole Tables	publish/cache.php91-97	Configures shared memory tables
Cache Prefix	publish/cache.php110	Application-specific key prefix from CACHE_PREFIX env var

Sources: src/ConfigProvider.php31-38 publish/cache.php1-111

Global Functions Autoloading

The package automatically loads global helper functions through Composer's files autoloading at composer.json27-29 This includes src/Functions.php which provides the cache() helper function for convenient cache access throughout the application.

The global function is available immediately after Composer's autoloader runs, before any framework-specific initialization. For detailed documentation of the helper function's usage patterns, see Helper Functions.

Sources: composer.json27-29

Complete Bootstrap Flow

The following diagram illustrates the complete integration flow from package installation to runtime usage:

Sources: composer.json1-53 src/ConfigProvider.php14-41 src/Listeners/CreateSwooleTable.php10-25

Environment Variable Configuration

The package respects several environment variables that control cache behavior. These are referenced in publish/cache.php1-111 and can be set in the application's .env file:

Environment Variable	Configuration Key	Default	Purpose
CACHE_DRIVER	cache.default	array	Default cache store to use
CACHE_PREFIX	cache.prefix	{app_name}_cache	Key prefix to avoid collisions
DB_CACHE_CONNECTION	cache.stores.database.connection	DB_CONNECTION	Database connection for cache
DB_CACHE_TABLE	cache.stores.database.table	cache	Table name for cache entries
DB_CACHE_LOCK_CONNECTION	cache.stores.database.lock_connection	null	Separate connection for locks
DB_CACHE_LOCK_TABLE	cache.stores.database.lock_table	cache_locks	Table name for lock entries

Sources: publish/cache.php22 publish/cache.php76-80 publish/cache.php110

Integration with Hyperf Configuration System

The package follows Hyperf's configuration conventions:

1. Autoload Configuration: Configuration files in config/autoload/ are automatically loaded and merged
2. Environment Variable Support: Uses env() helper for environment-aware configuration
3. Configuration Provider Pattern: Implements the standard Hyperf configuration provider interface
4. Service Registration: Uses the container's dependencies array for service bindings

This allows the cache package to integrate seamlessly with Hyperf's configuration and dependency injection systems without requiring manual registration or bootstrap code in the application.

Sources: src/ConfigProvider.php14-41 publish/cache.php1-111