diff --git a/docs/configuration.md b/docs/configuration.md index 1a1d2d1..a0b525d 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -32,6 +32,11 @@ Only the second reason picks 0 out of 0 through 4; if your container is already anywhere below 5 works. Order among the configuration calls does not matter, so long as they all precede `Absorber::boot()`. +`Absorber::boot()` is idempotent, so calling it from more than one code path is safe — but the +first call is the one that counts, and the container it saw is the container the library keeps. +Setting a different one afterwards binds nothing into it, and leaves the accessors asking a +container that was never taught about this library. Set the container once, before booting. + ## Registering a sub-plugin | Key | Type | Required | Meaning | diff --git a/src/Absorber.php b/src/Absorber.php index 6df1dd6..6050100 100644 --- a/src/Absorber.php +++ b/src/Absorber.php @@ -122,6 +122,13 @@ public static function all(): array { * Bind the collaborators, then let the scheduler decide when they run. Idempotent — safe to * call from more than one code path. * + * Idempotent means the first call wins outright, and the container is part of what it wins. + * A Config::set_container() after this has returned binds nothing: the scheduler keeps the + * container it closed over, while the accessors and the notice trampolines resolve from + * whatever Config holds when they are called, so the two halves would answer to different + * containers and the accessors would ask an unbound one. Set the container first — the + * recommended slot is plugins_loaded priority 0 — and do not replace it afterwards. + * * The provider is constructed rather than resolved: it is what teaches the container about this * library, so the container cannot be asked to build it first. It is bound afterwards, and only * when nothing answers to `Provider_Interface` already, so a host may replace the whole set of