# 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.

::: tip New to Gacela?
Start with the [Quickstart](https://gacela-project.com/docs/quickstart.md). It takes you from installation to a working module, then points to the next concept only when you need it.
:::

## Choose your path

<div class="gz-doc-grid">
  <a class="gz-doc-card" href="/docs/quickstart">
    <strong>Build your first module</strong>
    <span>Install Gacela and create a working Facade and Factory.</span>
  </a>
  <a class="gz-doc-card" href="/docs/getting-dependencies">
    <strong>Wire a dependency</strong>
    <span>Choose between Factory, Provider, bindings, Inject, and Service Map.</span>
  </a>
  <a class="gz-doc-card" href="/docs/upgrading">
    <strong>Upgrade to 2.0</strong>
    <span>Check requirements, replace removed APIs, and verify the migration.</span>
  </a>
  <a class="gz-doc-card" href="/used-in">
    <strong>Study a real application</strong>
    <span>See how the Phel language project structures production modules.</span>
  </a>
</div>

## Recommended journey

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

1. **Get a working result:** complete the [Quickstart](https://gacela-project.com/docs/quickstart.md) and run `example.php`.
2. **Understand the boundary:** read [Facade](https://gacela-project.com/docs/facade.md) and [Factory](https://gacela-project.com/docs/factory.md) while following the call inward.
3. **Add real dependencies:** use the [dependency decision guide](https://gacela-project.com/docs/getting-dependencies.md), then add Provider or Config only when required.
4. **Make it production-ready:** add [tests](https://gacela-project.com/docs/testing.md), [static analysis](https://gacela-project.com/docs/static-analysis.md), and [health checks](https://gacela-project.com/docs/health-checks.md).
5. **Inspect a real system:** compare the result with the [Phel production case study](https://gacela-project.com/used-in.md).

::: tip Find an answer quickly
Press <kbd>⌘ K</kbd> on macOS or <kbd>Ctrl K</kbd> on Windows/Linux to search every page. For wiring questions, start with [Getting dependencies](https://gacela-project.com/docs/getting-dependencies.md) instead of browsing individual APIs.
:::

## The module boundary

| Class | Responsibility | Called by |
|---|---|---|
| [Facade](https://gacela-project.com/docs/facade.md) | The module's public API | Other modules and entry points |
| [Factory](https://gacela-project.com/docs/factory.md) | Internal object construction | The module's Facade and services |
| [Provider](https://gacela-project.com/docs/provider.md) | Cross-module and infrastructure dependencies | The module's Factory |
| [Config](https://gacela-project.com/docs/config.md) | 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](https://gacela-project.com/docs/quickstart.md) demonstrates the complete flow.

## Common tasks

- [Bootstrap an application](https://gacela-project.com/docs/bootstrap.md)
- [Configure container bindings and lifetimes](https://gacela-project.com/docs/bindings.md)
- [Resolve a service in framework-managed code](https://gacela-project.com/docs/inject.md)
- [Inspect modules and dependency cycles from the CLI](https://gacela-project.com/docs/gacela-script.md)
- [Add health checks](https://gacela-project.com/docs/health-checks.md)
- [Test with isolated container state](https://gacela-project.com/docs/testing.md)
- [Enforce boundaries with PHPStan or Psalm](https://gacela-project.com/docs/static-analysis.md)

## 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`](/llms.txt) — compact index with page descriptions
- [`/llms-full.txt`](/llms-full.txt) — the complete documentation in one context file
- Append `.md` to a page URL — for example, [`/docs/bootstrap.md`](/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.