On this page
Gacela documentation
Gacela splits a PHP application into modules, each with up to four classes: a Facade exposes a module, a Factory creates its internal services, a Provider supplies external dependencies, and a Config reads application settings.
Choose your path
Recommended journey
Follow this order once. After that, use search and the task list:
- Get a working result: complete the Quickstart and run
example.php. - Understand the boundary: read Facade and Factory, following the call inward.
- Add real dependencies: use the dependency decision guide. Add a Provider or a Config only when you need one.
- Make it production-ready: add tests, static analysis, and health checks.
- Inspect a real system: compare your module with the Phel production case study.
The module boundary
| Class | Responsibility | Called by |
|---|---|---|
| Facade | The module's public API | Other modules and entry points |
| Factory | Internal object construction | The module's Facade and services |
| Provider | Cross-module and infrastructure dependencies | The module's Factory |
| Config | Typed application settings | The module's Factory |
A module does not need all four. Start with a Facade and a Factory. Add a Provider when the module crosses a boundary, and a Config when it needs application settings.
Design outside-in
Follow the request from the caller into the module:
- Write the controller, command, or script call you want to make.
- Turn that call into a small Facade method.
- Let the Factory construct the service that fulfills it.
- Add a Provider or Config only when that service needs something outside the module.
Real use cases then shape the public API, and no internal class is exposed in advance. The Quickstart walks through the whole flow.
Common tasks
- Bootstrap an application
- Configure container bindings and lifetimes
- Resolve a service in framework-managed code
- Inspect modules and dependency cycles from the CLI
- Add health checks
- Test with isolated container state
- Enforce boundaries with PHPStan or Psalm
- Declare which modules may depend on which
Documentation for coding agents
Three machine-readable entry points:
/llms.txt: a compact index with page descriptions/llms-full.txt: the complete documentation in one file- Any page URL with
.mdappended, for example/docs/bootstrap.md
Give an agent https://gacela-project.com/llms.txt for discovery, or https://gacela-project.com/llms-full.txt when
the whole documentation fits its context budget.
To make an agent follow Gacela's module rules in your own project, see coding agents.