How Djebel Loads Libraries: Lazy, Eager, or Matching a Pattern

A Djebel library is a single class file living at .ht_djebel/app/lib/<id>/lib.php. A plugin that needs one asks for it by id and the framework requires the file — once, on demand.

That "on demand" part is the default, and it is usually what you want. But sometimes you know up front that a whole set of libs will be used on every request, and calling the loader by hand in each spot gets repetitive.

Two app.ini flags settle it, and they give you three ways to load. load_lib_loader is lazy — the loader is there, but nothing loads until a plugin asks. load_libs is eager — it loads at bootstrap, either libs you name outright or a pattern that matches a whole family by id. Lazy, eager, or matched: you choose per app.

---

A Library, Loaded on Request

You pull a lib in with one call:

Dj_App_Lib::loadLib('djebel-core-lib-http');
$http_obj = Dj_App_Core_Lib_Http::getInstance();

loadLib() uses require_once, so calling it again is free — the second call is a cheap check, not a re-read. That is what makes lazy loading practical: a plugin can call loadLib() right before it needs the lib, every time, without worrying about double-loading.

But for loadLib() to exist at all, the loader class has to be present. That is the first flag.

---

load_lib_loader — On Demand

Set this when you want the loader available and nothing loaded until a caller asks:

[app]
load_lib_loader = 1

Now Dj_App_Lib exists, and every Dj_App_Lib::loadLib('some-lib') scattered through your plugins works. Nothing is loaded at bootstrap — a request that never touches the HTTP lib never pays for it. This is the lean default, and it is what most apps want.

Leave it off and the loader class is never required — the first loadLib() call then fatals with "class not found". So if your code calls loadLib() anywhere, this flag needs to be on.

---

load_libs — Eager, at Bootstrap

Sometimes you already know a lib is needed everywhere. Rather than sprinkle loadLib() calls around, name it once and let the bootstrap load it before your code runs:

[app]
load_libs = djebel-core-lib-http

You can list several. Commas, pipes, and spaces all work as separators:

load_libs = djebel-core-lib-http, djebel-core-lib-session

Loading libs needs the loader, so load_libs turns it on for you — you do not have to set load_lib_loader as well.

To load every lib in your app/lib/ directory, use a truthy flag or the * wildcard:

load_libs = 1        ; or true, or *

---

Glob Patterns

Here is where it gets useful. A token in load_libs can be a glob matched against your lib ids, so you can bulk-load a family without listing each one.

Say your organization ships several libs under a shared prefix — orbisius-lib-http, orbisius-lib-cache, orbisius-lib-mail. Load them all with one pattern:

load_libs = orbisius*

Combine patterns in a list, and mix globs with exact ids:

load_libs = orbisius*, cool-app*, djebel-core-lib-http

The matching is the same you already know from the @dj_if config directive:

load_libs = orbisius*     ; starts with "orbisius"
load_libs = *-http        ; ends with "-http"
load_libs = *lib*         ; contains "lib"
load_libs = *             ; everything

Anything that does not match a pattern is simply not eager-loaded — it stays available on demand through loadLib(). Eager-loading a family and lazy-loading the rest is a perfectly good mix.

---

Parking a Lib

Sometimes a lib should sit in app/lib/ but stay out of a bulk load — you are mid-upgrade, half-migrated, or just want it temporarily off. Prefix its directory with zzz_skip_ and eager-loading passes it by:

app/lib/
    orbisius-lib-http/           <- loaded by orbisius*
    zzz_skip_orbisius-lib-mail/  <- parked; * and orbisius* skip it

A load_libs = * or load_libs = orbisius* sweep leaves the parked one alone — no code edits, no config gymnastics, just a rename.

There is still an escape hatch: naming it exactly loads it. Dj_App_Lib::loadLib('zzz_skip_orbisius-lib-mail') (or an exact load_libs = zzz_skip_orbisius-lib-mail) works — so you can test a parked lib on its own while keeping it out of the automatic sweep.

---

Which Should You Use?

Reach for load_lib_loader by default. On-demand loading keeps each request paying only for the libs it actually touches, which is the whole point of a lazy loader.

Reach for load_libs when a set of libs is genuinely used on every request, or when a shared prefix lets one glob stand in for a hand-maintained list. load_libs = orbisius* says "all our libs, always" without you updating app.ini every time a new one ships.

And you are never locked in — a glob eager-loads a family while everything else still loads the moment a caller asks for it.

---

Your Next Step

Open your app.ini. If you call loadLib() anywhere, make sure load_lib_loader = 1 is set. If you have a family of libs that every request uses, try replacing the scattered calls with a single load_libs = your-prefix*. Start with the libs you know are always needed — leave the occasional ones lazy.