Spi Laravel Package

Getting Started

Install the package with composer require tbachert/spi. This adds a Composer plugin used primarily by OpenTelemetry PHP SDK for dynamic extension loading. If you’re not leveraging OpenTelemetry’s autoconfiguration (e.g., you configure exporters/tracers manually), you can safely disable the plugin afterward via composer config allow-plugins.tbachert/spi false. Your first practical step is registering implementations—via composer config --json --merge extra.spi 'Namespace\\Service' '["Namespace\\Implementation"]' for declarative setup, or ServiceLoader::register(...) in bootstrap code.

Implementation Patterns

• Declarative registration (production-friendly): Use extra.spi in composer.json to list implementations—ideal for libraries expecting consumers to register their own providers (e.g., custom exporters). Register at install time: composer config --json --merge extra.spi."App\\Contracts\\MetricExporter" '["App\\Metrics\\PrometheusExporter"]'.
• Runtime registration (flexible, dev-time): Call ServiceLoader::register(...) in bootstrap/app.php or service providers for dynamic decisions (e.g., load DebugExporter only in local environment).
• Precompiled maps (performance): Set extra.spi-config.autoload-files: true in composer.json to convert register() calls into a static classmap, eliminating Composer plugin overhead at runtime—crucial for production.
• Lazy loading with error handling: Use ServiceLoader::load() + getIterator() to catch ServiceConfigurationError when providers fail to instantiate (e.g., missing dependencies), allowing fallback behavior.

Gotchas and Tips

• Constructor strictness: Providers must have a public zero-argument constructor—no autowiring. Avoid constructor injection in SPI implementations; use setters or manual wiring after instantiation.
• Autoloader pruning: By default, ServiceLoader::register()-using files are removed from autoload.files after precompilation. Set extra.spi-config.prune-autoload-files: false if those files contain critical side-effect bootstrapping (e.g., environment setup).
• Plugin trust friction: First install triggers Composer’s plugin prompt (Do you trust "tbachert/spi"). For non-OpenTelemetry apps, disable the plugin after installation (allow-plugins.tbachert/spi false) to reduce runtime attack surface.
• Validation debugging: If providers don’t load, run composer install -vvv to see plugin logs, and verify extra.spi entries match exact FQCNs. Double-check class existence and constructor signatures.
• DI integration gap: This package only loads instances—it doesn’t inject dependencies. Integrate manually (e.g., $provider->configure($this->app) in a Laravel ServiceProvider) or use reflection-based wiring post-load.