Gacela documentation

Build modular PHP applications with a small, predictable vocabulary: 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

Build your first module Install Gacela and create a working Facade and Factory. Wire a dependency Choose between Factory, Provider, bindings, Inject, and Service Map. Upgrade to 2.0 Check requirements, replace removed APIs, and verify the migration. Study a real application See how the Phel language project structures production modules.

Recommended journey

Follow this sequence once; use search and the task index after that:

Get a working result: complete the Quickstart and run example.php.
Understand the boundary: read Facade and Factory while following the call inward.
Add real dependencies: use the dependency decision guide, then add Provider or Config only when required.
Make it production-ready: add tests, static analysis, and health checks.
Inspect a real system: compare the result 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

You do not need all four classes in every module. Start with a Facade and Factory; add a Provider when the module crosses a boundary, and a Config when it needs application settings.

Design outside-in

Gacela works best when you 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.

This keeps the public API driven by real use cases instead of exposing internal classes speculatively. The Quickstart demonstrates the complete flow.

Common tasks

Documentation for coding agents

Machine-readable entry points are available:

/llms.txt — compact index with page descriptions
/llms-full.txt — the complete documentation in one context file
Append .md to a page URL — for example, /docs/bootstrap.md

When prompting an agent, give it https://gacela-project.com/llms.txt for discovery or https://gacela-project.com/llms-full.txt when the entire documentation fits the task's context budget.