tatter / handlers
Handler discovery and management, for CodeIgniter 4
Fund package maintenance!
tattersoftware
paypal.me/tatter
Installs: 10 958
Dependents: 6
Suggesters: 0
Security: 0
Stars: 3
Watchers: 2
Forks: 1
Open Issues: 1
Requires
- php: ^7.4 || ^8.0
Requires (Dev)
- codeigniter4/framework: ^4.1
- tatter/tools: ^2.0
This package is auto-updated.
Last update: 2024-10-18 02:49:20 UTC
README
Handler discovery and management, for CodeIgniter 4
Quick Start
- Install with Composer:
> composer require tatter/handlers
- Create a Factory to identify your handlers
- Discover classes from any namespace:
$widgets = WidgetFactory::findAll();
Features
Handlers allows developers to define and discover classes of predetermined types across all namespaces; it is essentially a database-free "model" for classes.
Installation
Install easily via Composer to take advantage of CodeIgniter 4's autoloading capabilities and always be up-to-date:
composer require tatter/handlers
Or, install manually by downloading the source files and adding the directory to app/Config/Autoload.php.
Configuration (optional)
The library's default behavior can be altered by extending its config file. Copy examples/Handlers.php to app/Config/ and follow the instructions in the comments. If no config file is found in app/Config the library will use its own.
Usage
Handlers uses relative paths to discover files that contain handler classes. Create a new folder in your project or module with an appropriate name for your implementation, e.g. app/Widgets/ or src/Reports.
Compatibility
In order for them be discovered as handlers your classes need to have a consistent class or
interface type and supply a unique ID via the class constant HANDLER_ID
.
Handlers will resolve class extensions by using this handler ID, so if you want your
app to "replace" a handler from another namespace then simply extend the original class and
leave the HANDLER_ID
constant the same.
Factories
Once your handler classes are created you will need a Factory that provides the lookup path
and expected class or interface to identify the handlers. Create the new class extending BaseFactory
:
<?php namespace App\Factories; use App\Interfaces\WidgetInterface; use Tatter\Handlers\BaseFactory; class WidgetFactory extends BaseFactory { public const HANDLER_PATH = 'Widgets'; public const HANDLER_TYPE = WidgetInterface::class; }
You can then use the BaseFactory
methods to locate all handler classes or a specific
handler by its ID:
use App\Factories\WidgetFactory; // Iterate through all discovered handlers foreach (WidgetFactory::findAll() as $class) { $widget = new $class($param1, $param2); $widget->display(); } // ... or get a single handler by specifying its ID $class = WidgetFactory::find('FancyHandler'); (new $class)->display();
Caching
Handlers scans through all namespaces to discover relevant classes. This distributed
filesystem read can be costly in large projects, so Handlers will cache the results
for an amount of time set in the config file (default: one day). You can disable Caching
using the config file by setting $cacheDuration
to null
.
Often it is a good idea to pre-cache handlers so the filesystem search does not happen on
an actual page load. This library includes FactoryFactory
, a "Factory to discover other
Factories". If you would like your Factories to be discoverable by FactoryFactory
and
thus their handlers enabled for auto-caching then place your Factory classes in the
Factories subfolder and provide them a HANDLER_ID
constant like any other handler.
Commands
To assist with FactoryFactory
's discovery of your factories and their handlers this
library includes two commands that will pre-cache all handler classes and clear the cached
values respectively:
# Discovers and caches all compatible factories and their handlers php spark handlers:cache # Clears all cached factories and handlers php spark handlers:clear
Set your cron job to run spark handlers:cache
on some interval smaller than the Config
$cacheDuration
to ensure your handlers are always at hand.
Examples
Here are some other libraries that implement their own Factory class with a set of handlers. Browse their code to get an idea of how you might use Handlers for your own projects.
- Tatter\Thumbnails: Modular thumbnail generation, for CodeIgniter 4
- Tatter\Exports: Modular file exports, for CodeIgniter 4