# Gacela 2.0 documentation

> Gacela is a PHP 8.3+ library for building modular applications with explicit Facade, Factory, Provider, and Config boundaries.

Use these Markdown documents as the source of truth for installing, configuring, and using Gacela 2.0.

Recommended workflow: begin with the Quickstart, follow the caller through Facade and Factory, then consult Getting dependencies before adding Provider, Config, bindings, Inject, or Service Map.

## Getting started

- [Documentation](https://gacela-project.com/docs/index.md): Choose the shortest path from installation to a production-ready Gacela module.
- [Quickstart](https://gacela-project.com/docs/quickstart.md): Install Gacela 2.0 and build a working module in a few minutes.
- [Getting dependencies](https://gacela-project.com/docs/getting-dependencies.md): Choose the right dependency mechanism for module-internal, cross-module, and external services.
- [Bootstrap](https://gacela-project.com/docs/bootstrap.md): Bootstrap Gacela, configure environments, application paths, caching, and container behavior.
- [Upgrade from 1.21](https://gacela-project.com/docs/upgrading.md): Migrate an application from Gacela 1.21 to 2.0 safely.

## Build a module

- [Facade](https://gacela-project.com/docs/facade.md): Expose a small, stable public API for a Gacela module.
- [Factory](https://gacela-project.com/docs/factory.md): Create a module’s internal services and wire their dependencies.
- [Provider](https://gacela-project.com/docs/provider.md): Declare services a module needs from other modules or infrastructure.
- [Config](https://gacela-project.com/docs/config.md): Read typed application configuration inside a module.

## Dependency injection

- [Choose a mechanism](https://gacela-project.com/docs/getting-dependencies.md): Compare factories, providers, bindings, Inject, and Service Map.
- [Bindings & container](https://gacela-project.com/docs/bindings.md): Configure bindings, lifetimes, aliases, tags, hooks, and definitions.
- [Inject attribute](https://gacela-project.com/docs/inject.md): Inject services into constructors, properties, or setters with attributes.
- [Service Map](https://gacela-project.com/docs/service-map.md): Resolve Gacela services from classes created outside its container.
- [Extensions & plugins](https://gacela-project.com/docs/extensions.md): Extend framework configuration and hook into application bootstrap.
- [Module customization](https://gacela-project.com/docs/customization.md): Customize pillar suffixes, namespaces, and module discovery.

## Operations

- [Caching](https://gacela-project.com/docs/caching.md): Understand Gacela’s framework, method-result, and file-cache layers.
- [Cacheable methods](https://gacela-project.com/docs/cacheable-methods.md): Cache facade method results with explicit keys and invalidation.
- [Opcache preload](https://gacela-project.com/docs/opcache-preload.md): Generate and deploy an Opcache preload script for Gacela modules.
- [CLI reference](https://gacela-project.com/docs/gacela-script.md): Inspect, diagnose, warm, and visualize a Gacela application from the CLI.
- [Health checks](https://gacela-project.com/docs/health-checks.md): Expose module health through the doctor command or an application endpoint.
- [Events](https://gacela-project.com/docs/events.md): Observe bootstrap, configuration, container, cache, and module lifecycle events.

## Quality & integration

- [Testing](https://gacela-project.com/docs/testing.md): Test Gacela applications with isolated container state and event assertions.
- [Static analysis](https://gacela-project.com/docs/static-analysis.md): Configure PHPStan and Psalm for typed accessors and module boundaries.
- [Framework integration](https://gacela-project.com/docs/other-frameworks.md): Integrate Gacela with applications using another framework or container.
- [Single-file modules](https://gacela-project.com/docs/extra.md): Use advanced single-file module patterns when a small boundary is enough.

## Examples and project context

- [Production case study](https://gacela-project.com/used-in.md): Verified Gacela patterns from the Phel language project.
- [About Gacela](https://gacela-project.com/about-gacela.md): The module model and architectural motivation.
- [Complete documentation](https://gacela-project.com/llms-full.txt): All documentation in one Markdown context file.