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

5.0 KiB

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, creates the container with backpack.New, and hands it to party, 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 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, or the translator from phrasebook).
  • 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

// Greeter is a service the acme.greeter plugin offers to other plugins.
type Greeter interface {
	Greet(name string) string
}
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, festival.
  • Third-party: none.
  • Standard library: fmt, reflect, sync.

Testing

go test ./modules/backpack/...

The tests build containers in memory and need no external services.