Integration and Operations

This document provides an overview of how the hypervel/cache package integrates with the Hyperf framework and the operational tools available for managing caches in production. It covers the bootstrap process, dependency registration, and the operational utilities that enable cache management and observability.

For detailed information about specific operational components, see:

• Framework integration mechanics: Framework Integration
• Command-line tools: Console Commands
• Observability and lifecycle hooks: Event System
• Global helper functions: Helper Functions

---

Integration Architecture

The cache package integrates with Hyperf through the ConfigProvider pattern, which is Hyperf's standard mechanism for package discovery and registration. The ConfigProvider class serves as the single entry point that registers all cache components with the framework's dependency injection container.

Figure 1: Package Discovery and Registration Flow

The registration process follows these steps:

1. Package Discovery: Hyperf reads the extra.hyperf.config key from composer.json46-48 to locate the ConfigProvider class
2. Configuration Assembly: The framework invokes ConfigProvider::__invoke() to retrieve the registration array
3. Component Registration: Dependencies, listeners, commands, and publishable assets are registered with the container
4. Configuration Publishing: Users can publish the default cache configuration to config/autoload/cache.php

Sources: composer.json42-52 src/ConfigProvider.php1-41

---

Dependency Registration

The cache package registers two primary service bindings with the dependency injection container:

Binding	Implementation	Resolution Strategy
Factory::class	CacheManager::class	Direct class binding
Store::class	fn($container) => $container->get(CacheManager::class)->driver()	Factory function returning default driver

The Factory interface binding allows applications to type-hint Factory and receive the CacheManager singleton. The Store interface binding provides direct access to the default cache store, bypassing the manager layer when only a single store is needed.

Figure 2: Dependency Injection Resolution

Sources: src/ConfigProvider.php19-22

---

Event Listeners

The package registers two event listeners that handle infrastructure setup during the server lifecycle:

Figure 3: Event Listener Registration and Execution

Both listeners extend BaseListener, which provides the swooleStores() helper method to filter configuration for Swoole-based stores. These listeners execute during the BeforeServerStart event, ensuring that Swoole tables and timers are properly initialized before the server accepts connections.

• CreateSwooleTable: Instantiates Swoole table instances for each configured Swoole store via SwooleTableManager
• CreateTimer: Sets up periodic timers for Swoole store eviction and maintenance tasks

Sources: src/ConfigProvider.php23-25 src/Listeners/BaseListener.php1-24 src/Listeners/CreateSwooleTable.php1-25

---

Console Commands

The package provides two console commands for cache management operations:

Figure 4: Console Command Architecture

These commands are registered with Hyperf's command system and available via the php bin/hyperf.php CLI interface:

• cache:clear: Flushes cache entries, with options for targeting specific stores or tags. Dispatches cache cleared events for observability.
• cache:prune-db-expired: Removes expired entries from database-backed caches to prevent table growth and maintain query performance.

Sources: src/ConfigProvider.php27-29

---

Configuration Publishing

The package includes a publishable configuration file that can be deployed to the application's configuration directory:

Figure 5: Configuration Publishing Flow

The publish configuration is defined in the ConfigProvider:

• Source: __DIR__ . '/../publish/cache.php' - The default configuration template bundled with the package
• Destination: BASE_PATH . '/config/autoload/cache.php' - The application's autoload configuration directory
• ID: config - Identifier for selective publishing

After publishing, users can customize the configuration to define cache stores, set the default driver, configure connection pools, and tune performance parameters.

Sources: src/ConfigProvider.php31-38

---

Autoloading and Global Helpers

The package registers a global helper function file through Composer's autoload configuration:

Figure 6: Global Helper Function Registration

The cache() helper provides a convenient global function for accessing the cache system without explicit dependency injection. The helper's behavior is polymorphic based on the number of arguments provided:

• Zero arguments: Returns the CacheManager instance for fluent API access
• One argument: Retrieves a cache value by key
• Two arguments: Stores a cache value with optional TTL

This approach mirrors Laravel's helper pattern, providing both convenience for simple use cases and power for complex scenarios.

Sources: composer.json27-29

---

Operational Flow Summary

The complete operational lifecycle follows this sequence:

1. Bootstrap Phase: Hyperf discovers and invokes ConfigProvider::__invoke()
2. Registration Phase: Dependencies, listeners, commands, and configuration are registered
3. Initialization Phase: CreateSwooleTable and CreateTimer listeners execute on BeforeServerStart
4. Runtime Phase: Application code accesses cache via dependency injection or global helper
5. Management Phase: Administrators use console commands for maintenance and monitoring

This architecture ensures that all cache infrastructure is properly initialized before the application serves requests, while providing operational tools for ongoing management and debugging.

Sources: src/ConfigProvider.php1-41 src/Listeners/BaseListener.php1-24 src/Listeners/CreateSwooleTable.php1-25

---

Subsystem Navigation

The following pages provide detailed documentation for each operational component:

• Framework Integration: Deep dive into Hyperf integration patterns, service resolution, and bootstrap lifecycle
• Console Commands: Complete documentation of cache:clear and cache:prune-db-expired commands
• Event System: Cache lifecycle events, custom listener registration, and observability patterns
• Helper Functions: Full API documentation for the cache() global helper function