gacela-project/gacela

Gacela helps you separate your project into modules

2.3.0 2026-08-15 09:23 UTC

Requires

• php: >=8.3
• gacela-project/container: ^2.0.2

Requires (Dev)

• bamarni/composer-bin-plugin: ^1.8
• ergebnis/composer-normalize: ^2.50
• friendsofphp/php-cs-fixer: ^3.95
• illuminate/config: ^11.28 || ^12.0
• illuminate/console: ^11.28 || ^12.0
• illuminate/container: ^11.28 || ^12.0
• illuminate/contracts: ^11.28 || ^12.0
• illuminate/events: ^11.28 || ^12.0
• illuminate/support: ^11.28 || ^12.0
• infection/infection: ^0.34
• nikic/php-parser: ^5.4
• phpbench/phpbench: ^1.4
• phpmetrics/phpmetrics: ^2.9
• phpstan/phpstan: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/phpunit: ^12.5
• psalm/plugin-phpunit: ^0.19.7
• symfony/config: ^7.0 || ^8.0
• symfony/console: ^7.0 || ^8.0
• symfony/dependency-injection: ^7.0 || ^8.0
• symfony/http-kernel: ^7.0 || ^8.0
• symfony/var-dumper: ^7.0 || ^8.0
• vimeo/psalm: ^6.16

Suggests

• gacela-project/gacela-env-config-reader: Allows to read .env config files
• gacela-project/gacela-yaml-config-reader: Allows to read yml/yaml config files
• illuminate/support: Allows to register Gacela\LaravelBridge\GacelaServiceProvider in a Laravel application
• phpunit/phpunit: Allows to extend Gacela\Framework\Testing\GacelaTestCase in your tests
• symfony/console: Allows to use vendor/bin/gacela script
• symfony/http-kernel: Allows to register Gacela\SymfonyBridge\GacelaBundle in a Symfony application

MIT

• Jose M. Valera Reales
• Jesus Valera Reales

• framework
• php
• modular
• kernel

Published on Packagist.org on 2026-08-15 09:25 UTC

README

Gacela — build modular PHP applications

Gacela normalizes module boundaries so parts of your application communicate through a single entry point, without leaking internals.

Each module is built from four pillars — only the first two are required:

• Facade — public API, the only way in
• Factory — creates internal services
• Provider — wires external dependencies (optional)
• Config — reads project config (optional)

Installation

composer require gacela-project/gacela

Requires PHP 8.3+. Coming from 1.x? See UPGRADE.md.

Module structure

app/
├── gacela.php
├── config/
└── src/
    └── Blog/
        ├── BlogFacade.php
        ├── BlogFactory.php
        ├── BlogProvider.php
        └── BlogConfig.php

That is what make:module App/Blog below writes. Pass --short-name for Facade.php instead of BlogFacade.php — both resolve; the prefix is the default because it survives being read out of context.

CLI

vendor/bin/gacela init                  # scaffold gacela.php
vendor/bin/gacela make:module App/Blog  # scaffold a module
vendor/bin/gacela                       # every command

Modules can be inspected, validated and prepared for production — see CLI commands.

Documentation

Start with getting started, then getting a dependency — the one that answers "how do I reach that from here". docs/ is the full index; the rest:

• Upgrading from 1.x
• CLI commands
• Container configuration — bindings, contextual bindings, attributes, hooks
• Caching and cacheable methods
• Static analysis (PHPStan / Psalm)
• Module health checks
• Events
• Testing
• Opcache preload and production performance
• Full reference: gacela-project.com
• Symfony bundle — bootstrap Gacela from the kernel, reach Symfony services, bin/console gacela:*
• Laravel provider — bootstrap Gacela when the app boots, reach Laravel services, artisan gacela:*
• Examples:
  • gacela-example
  • symfony-gacela-example — Gacela with Symfony 7.4
  • laravel-gacela-example — Gacela with Laravel 12

Contributing

Report issues, share ideas, or open a pull request.

Inspired by Spryker.