Files
summercms/modules/backpack/README.md
Jakub Zych a0f5b5e561 docs(backpack,beachcomber,boardwalk,bonfire,bouncer): compile README Go examples via src= (quick-261118-qsd)
- backpack: Greeter and ExampleApp_Publish replace the whole-file fence
- beachcomber: Post's Searchable methods plus a new SearchIndexSchema, a
  Plugin.Boot that installs the gate, and the existing gate/search regions
- boardwalk: new example_test.go; the mount region runs in ExampleHandler
- bonfire: importPostsCommand and acmeMain (the binary's main as a function
  returning the exit code), run by ExampleExecute; ExampleCatalog_Has
- bouncer: users/FindByID and ExampleNewJWTGuard; RefreshRoute run by
  TestDocsRefreshRoute on a production compass config
2026-11-18 19:39:50 +01:00

92 lines
5.0 KiB
Markdown

# backpack
Per-instance application container that holds the configuration, a typed service registry, the event bus and the set of activated plugins.
`import "git.golem15.com/golem15/summercms/modules/backpack"`
**Name:** The one bag you pack for the beach; it carries everything the application needs: configuration, services, events and plugins.
## Overview
`backpack` plays the role of the Laravel service container that WinterCMS plugins reach through `App::make` and singleton bindings, without any process-global state: every `backpack.App` is independent, so tests and multiple instances in one process do not interfere. The generated `main` of an application loads configuration with [compass](../compass/README.md), creates the container with `backpack.New`, and hands it to [party](../party/README.md), which passes it to every plugin's Register and Boot. `backpack` deliberately does not import `party`, which keeps the dependency graph acyclic.
## Role in the framework
The root of the framework. It depends only on `compass` (configuration) and `festival` (events), and almost every other module (`lagoon`, `conga`, `cabana`, `surf`, `party`, `phrasebook`, `postcard`, `lighthouse`, `flare`, `beachcomber`) receives the application through it. It is the Go counterpart of Laravel's service container: one value handed to every plugin, with typed lookups instead of string keys. It stays its own module, separate from `party`, so the plugin registry can depend on it without an import cycle.
Use cases:
- Reach shared services from a plugin (the database connection, the blob bucket, the translator) without globals.
- Publish a plugin's own service once at Register time so other plugins can look it up by type.
- Read configuration and fire or listen to events from anywhere that holds the application.
## Features
- `backpack.New` wires a container around a loaded `*compass.Config`: `backpack.App.Config`, a fresh service registry in `backpack.App.Services` and a new [festival](../festival/README.md) bus in `backpack.App.Events`.
- Typed services keyed by the type argument: `backpack.App.Publish` stores a value under its type T and `backpack.App.Lookup` returns it. Publishing the same T twice or publishing nil is an error, so two plugins cannot silently replace each other's service. Framework modules share their infrastructure this way (for example the database handles published by [lagoon](../lagoon/README.md), or the translator from [phrasebook](../phrasebook/README.md)).
- Plugin presence checks: `backpack.App.SetPlugins` records the complete activated set before any plugin boots, and `backpack.App.HasPlugin` answers whether an optional integration partner is part of this build (the equivalent of WinterCMS's `PluginManager::exists`).
- `backpack.Registry` can be used on its own through `backpack.NewRegistry`; it is safe for concurrent use.
- Nil-safe methods: calls on a nil container or registry return an error or a zero value instead of panicking.
## Usage
```go src=modules/backpack/example_test.go#Greeter
// Greeter is a service the acme.greeter plugin offers to other plugins.
type Greeter interface {
Greet(name string) string
}
```
```go src=modules/backpack/example_test.go#ExampleApp_Publish
app := backpack.New(&compass.Config{})
app.SetPlugins([]string{"acme.greeter", "acme.blog"})
// acme.greeter, in its Register step: publish under the interface type.
var greeter Greeter = englishGreeter{}
if err := app.Publish(greeter); err != nil {
fmt.Println(err)
return
}
// acme.blog, in its Boot step: look the service up by the same type.
if app.HasPlugin("acme.greeter") {
if found, ok := app.Lookup[Greeter](); ok {
fmt.Println(found.Greet("blog"))
}
}
// A second Publish under the same type is refused.
fmt.Println(app.Publish(greeter) != nil)
// Output:
// Hello, blog
// true
```
Publish under an interface type when consumers should not depend on the concrete implementation; the lookup must use exactly the same type argument.
## API reference
| Identifier | Description |
|------------|-------------|
| `backpack.App` | The application container: configuration, service registry, event bus and the activated plugin set. |
| `backpack.New` | Creates a `backpack.App` around a loaded configuration, with an empty registry and a new event bus. |
| `backpack.App.Publish` / `backpack.App.Lookup` | Store and retrieve an app-scoped service by type. |
| `backpack.App.SetPlugins` / `backpack.App.HasPlugin` | Record the activated plugin IDs and check whether one is present. |
| `backpack.Registry` | Concurrency-safe typed service catalog behind `backpack.App.Services`. |
| `backpack.NewRegistry` | Returns an empty registry. |
| `backpack.Registry.Publish` / `backpack.Registry.Lookup` | Registry-level publish and lookup behind the `backpack.App` methods. |
## Dependencies
- SummerCMS modules: [compass](../compass/README.md), [festival](../festival/README.md).
- Third-party: none.
- Standard library: `fmt`, `reflect`, `sync`.
## Testing
```sh
go test ./modules/backpack/...
```
The tests build containers in memory and need no external services.