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.

New to Gacela?

Start with the Quickstart. It takes you from installation to a working module, then points to the next concept only when you need it.

Choose your path

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

Recommended journey

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

1. Get a working result: complete the Quickstart and run example.php.
2. Understand the boundary: read Facade and Factory while following the call inward.
3. Add real dependencies: use the dependency decision guide, then add Provider or Config only when required.
4. Make it production-ready: add tests, static analysis, and health checks.
5. Inspect a real system: compare the result with the Phel production case study.

Find an answer quickly

Press ⌘ K on macOS or Ctrl K on Windows/Linux to search every page. For wiring questions, start with Getting dependencies instead of browsing individual APIs.

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:

1. Write the controller, command, or script call you want to make.
2. Turn that call into a small Facade method.
3. Let the Factory construct the service that fulfills it.
4. 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

• 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

Documentation for coding agents

Every page has Copy Markdown and View Markdown actions above its title. Machine-readable entry points are also 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
• Use Copy agent prompt on any page to copy a source-of-truth instruction with its Markdown URL

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.