From 25cd5d26fc5b7b9a3c7867a693da7bcfa544c46d Mon Sep 17 00:00:00 2001 From: Chemaclass Date: Wed, 14 Jul 2021 13:41:07 +0200 Subject: [PATCH 1/3] Link the docs to the website --- docs/002_facade.md | 34 +--------- docs/003_factory.md | 34 +--------- docs/004_config.md | 113 +------------------------------- docs/005_dependency_provider.md | 43 +----------- 4 files changed, 9 insertions(+), 215 deletions(-) diff --git a/docs/002_facade.md b/docs/002_facade.md index 30c22333..53bc1832 100644 --- a/docs/002_facade.md +++ b/docs/002_facade.md @@ -2,40 +2,10 @@ # Facade -The Facade is the entry point of your module. See an example: +Check the full `Facade` documentation here: [https://gacela-project.com/docs/facade/](https://gacela-project.com/docs/facade/) -```php -# src/Calculator/FacadeInterface.php -interface FacadeInterface -{ - public function sum(): void; -} -``` - -```php -# src/Calculator/Facade.php -/** - * @method Factory getFactory() - */ -final class Facade extends AbstractFacade implements FacadeInterface -{ - public function sum(int ...$numbers): int - { - $this->getFactory() - ->createAdder() - ->add(...$numbers); - } -} -``` - -A Facade is a "ready to use" thing: - -```php -$facade = new Facade(); -$result = $facade->sum(2, 3); -``` +A Facade is the entry point of your module. The Facade uses the Factory to create the module's domain instances and executes the desired behaviour from them. -Nothing less, nothing more. [<< Basic Concepts](../docs/001_basic_concepts.md) | [Factory >>](../docs/003_factory.md) diff --git a/docs/003_factory.md b/docs/003_factory.md index 6ef6a3ae..bf398ce7 100644 --- a/docs/003_factory.md +++ b/docs/003_factory.md @@ -2,39 +2,9 @@ # Factory +Check the full `Factory` documentation here: [https://gacela-project.com/docs/factory/](https://gacela-project.com/docs/factory/) + The Factory is the place where you create your domain services and objects. The Facade is the class that can access the Factory. -```php -# src/Calculator/Factory.php -/** - * @method Config getConfig() - */ -final class Factory extends AbstractFactory -{ - public function createAdder(): AdderInterface - { - return new Adder( - // ... - ); - } -} -``` - -```php -# src/Calculator/Facade.php -/** - * @method Factory getFactory() - */ -final class Facade extends AbstractFacade implements FacadeInterface -{ - public function sum(int ...$numbers): int - { - return $this->getFactory() - ->createAdder() - ->add(...$numbers); - } -} -``` - [<< Facade](../docs/002_facade.md) | [Config >>](../docs/004_config.md) diff --git a/docs/004_config.md b/docs/004_config.md index 4225e335..c5371fb3 100644 --- a/docs/004_config.md +++ b/docs/004_config.md @@ -2,118 +2,11 @@ # Config +Check the full `Config` documentation here: [https://gacela-project.com/docs/config/](https://gacela-project.com/docs/config/) + Use a Config Class to construct your business domain classes by injecting the data from the Config using the Factory when you do the creation of your domain classes. -In order to achieve that, you need to create a `gacela.json` file in your application root with the following values: - -### gacela.json examples - -Using PHP config files: - -```json -{ - "config": { - "type": "php", - "path": "config/*.php", - "path_local": "config/local.php" - } -} -``` - -Using `.env` config files: - -```json -{ - "config": { - "type": "env", - "path": ".env*", - "path_local": ".env.local" - } -} -``` - -Or even multiple types of config files: - -```json -{ - "config": [ - { - "type": "php", - "path": "config/*.php", - "path_local": "config/local.php" - }, - { - "type": "env", - "path": ".env*", - "path_local": ".env.local" - } - ] -} -``` - -- `"type"`: possible values `php` or `env` -- `"path"`: the path of the folder which contains your application configuration. - You can use `?` or `*` in order to match 1 or multiple characters. - Check [`glob()`](https://www.php.net/manual/en/function.glob.php) function for more info. -- `"path_local"`: this is the last file loaded, which means, it will override the previous configuration, - so you can add it to your `.gitignore` and set your own local config values. ---- - -> This is tightly coupled with the infrastructure layer, because there is I/O involved. -> It's not bad itself, you just need to be aware of potential risks, though. Don't -> access data from your `config` files (files under the gacela.json `path` directory) directly in your domain services. -> In this way, you would couple your logic with infrastructure code, and not be able to unit test it. - -### An example - -```json -# gacela.json -{ - "config": { - "type": "php", - "path": "config/*.php", - "path_local": "config/local.php" - } -} -``` - -```php -# config/default.php -use src\Calculator\Config; - -return [ - Config::MAX_ADDITIONS => 20, -]; -``` - -```php -# src/Calculator/Config.php -final class Config extends AbstractConfig -{ - public const MAX_ADDITIONS = 'MAX_ADDITIONS'; - - public function getMaxAdditions(): int - { - return $this->get(self::MAX_ADDITIONS, $default = 0); - } -} -``` - -```php -# src/Calculator/Factory.php -/** - * @method Config getConfig() - */ -final class Factory extends AbstractFactory -{ - public function createAdder(): AdderInterface - { - return new Adder( - $this->getConfig()->getMaxAdditions() - ); - } -} -``` +In order to achieve that, you need to create a `gacela.json` file in your application root. [<< Factory](../docs/003_factory.md) | [Dependency Provider >>](../docs/005_dependency_provider.md) diff --git a/docs/005_dependency_provider.md b/docs/005_dependency_provider.md index 608254aa..cd1f8eac 100644 --- a/docs/005_dependency_provider.md +++ b/docs/005_dependency_provider.md @@ -2,47 +2,8 @@ # Dependency Provider -This is the place where you can define the dependencies that a particular module has with other modules. - -In this example you can see that in the `Calculator` we have a service (`Adder`) which needs the `AnotherModuleFacade` -as a dependency. In this case, we can define the dependency inside the `DependencyProvider`. - -```php -# src/Calculator/Factory.php -final class Factory extends AbstractFactory -{ - public function createAdder(): AdderInterface - { - return new Adder( - $this->getAnotherModuleFacade() - ); - } - - private function getAnotherModuleFacade(): AnotherModuleFacade - { - return $this->getProvidedDependency(DependencyProvider::FACADE_ANOTHER_MODULE); - } -} -``` +Check the full `DependencyProvider` documentation here: [https://gacela-project.com/docs/dependency-provider/](https://gacela-project.com/docs/dependency-provider/) -```php -# src/Calculator/DependencyProvider.php -final class DependencyProvider extends AbstractDependencyProvider -{ - public const FACADE_ANOTHER_MODULE = 'FACADE_ANOTHER_MODULE'; - - public function provideModuleDependencies(Container $container): void - { - $this->addFacadeAnotherModule($container); - } - - private function addFacadeAnotherModule(Container $container): void - { - $container->set(self::FACADE_ANOTHER_MODULE, function (Container $container): AnotherModuleFacade { - return $container->getLocator()->get(AnotherModuleFacade::class); - }); - } -} -``` +This is the place where you can define the dependencies that a particular module has with other modules. [<< Config](../docs/004_config.md) | [Code Generator >>](../docs/006_code_generator.md) From 78d0357936365e22655292c0f215eb1effc75384 Mon Sep 17 00:00:00 2001 From: JesusValera Date: Thu, 15 Jul 2021 20:16:53 +0200 Subject: [PATCH 2/3] Remove docs folder --- README.md | 17 +++----- docs/001_basic_concepts.md | 43 ------------------- docs/002_facade.md | 11 ----- docs/003_factory.md | 10 ----- docs/004_config.md | 12 ------ docs/005_dependency_provider.md | 9 ---- docs/006_code_generator.md | 15 ------- docs/README.md | 14 ------ .../gacela-logo-blue.svg => gacela-logo.svg | 0 9 files changed, 5 insertions(+), 126 deletions(-) delete mode 100644 docs/001_basic_concepts.md delete mode 100644 docs/002_facade.md delete mode 100644 docs/003_factory.md delete mode 100644 docs/004_config.md delete mode 100644 docs/005_dependency_provider.md delete mode 100644 docs/006_code_generator.md delete mode 100644 docs/README.md rename docs/imgs/gacela-logo-blue.svg => gacela-logo.svg (100%) diff --git a/README.md b/README.md index bba10d77..0e2e9abc 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,5 @@

- - Gacela logo - + Gacela logo

@@ -38,21 +36,16 @@ rules: - The `Config` gets the values from your defined config files. - The `DependencyProvider` uses the Locator to get the Facades from different modules. +### You can check the full documentation [here](https://gacela-project.com/) + +--- + ### Installation ```bash composer require gacela-project/gacela ``` -## Documentation - -- [Basic concepts](docs/001_basic_concepts.md): What are the characteristics of a module? -- [Facade](docs/002_facade.md): The entry point of your module -- [Factory](docs/003_factory.md): The place where you create your domain services and objects -- [Config](docs/004_config.md): Reads the values defined in your config path -- [DependencyProvider](docs/005_dependency_provider.md): It defines the dependencies between modules -- [Code generator](docs/006_code_generator.md): Some commands out-of-the-box for generating code - ### Examples You can see an example of a module using gacela in [this repository](https://github.com/gacela-project/gacela-example). diff --git a/docs/001_basic_concepts.md b/docs/001_basic_concepts.md deleted file mode 100644 index 8aa029e2..00000000 --- a/docs/001_basic_concepts.md +++ /dev/null @@ -1,43 +0,0 @@ -[Back to the index](../docs) - -# Basic concepts about modules - -First, what are the characteristics of a module? - -1. It encapsulates code to implement a particular functionality. -2. It has an interface that lets clients access its functionality. -3. It is easily pluggable with another module that expects its interface. -4. It is usually packaged in a single unit so that it can be easily deployed. - -## 1. Encapsulates a particular functionality - -Think about the design of a module. How do you visualize it? Simple. It depends on its domain. The internal details of a -module design should depend only on the domain where it belongs, but... - -- what about the common parts? -- how should a module interact with other modules? -- where are the instantiations of the domain services happening? -- how do I limit the boundaries between the infrastructure and the domain within my module? - -## 2. Clients can access its functionality via an interface - -The way a module will communicate with other modules will be ONLY via its Facade. That's it. - -The Facade is the source of truth of what that module does. It belongs to the application layer, it's a mediator between -the infrastructure (Factory & Config) and your domain logic (everything else in your module). - -## 3. Easily pluggable with another module - -There must be an easy way to define the dependencies between your modules. The basic idea is to be able to easily access -the facades of other modules by exposing their FacadeInterface. - -## 4. Usually packaged in a single unit - -You should consider a module as an individual thing in order to decouple it from the rest of your modules. The logic in -charge of reading from the IO (Config) is the only class which is coupled somehow with the infrastructure, but the rest -should be decouple from the outside. - -All the responsibilities that a module handles should remain close and together. The domain of that module should guide -its design. - -[Facade >>](../docs/002_facade.md) diff --git a/docs/002_facade.md b/docs/002_facade.md deleted file mode 100644 index 53bc1832..00000000 --- a/docs/002_facade.md +++ /dev/null @@ -1,11 +0,0 @@ -[Back to the index](../docs) - -# Facade - -Check the full `Facade` documentation here: [https://gacela-project.com/docs/facade/](https://gacela-project.com/docs/facade/) - -A Facade is the entry point of your module. - -The Facade uses the Factory to create the module's domain instances and executes the desired behaviour from them. - -[<< Basic Concepts](../docs/001_basic_concepts.md) | [Factory >>](../docs/003_factory.md) diff --git a/docs/003_factory.md b/docs/003_factory.md deleted file mode 100644 index bf398ce7..00000000 --- a/docs/003_factory.md +++ /dev/null @@ -1,10 +0,0 @@ -[Back to the index](../docs) - -# Factory - -Check the full `Factory` documentation here: [https://gacela-project.com/docs/factory/](https://gacela-project.com/docs/factory/) - -The Factory is the place where you create your domain services and objects. -The Facade is the class that can access the Factory. - -[<< Facade](../docs/002_facade.md) | [Config >>](../docs/004_config.md) diff --git a/docs/004_config.md b/docs/004_config.md deleted file mode 100644 index c5371fb3..00000000 --- a/docs/004_config.md +++ /dev/null @@ -1,12 +0,0 @@ -[Back to the index](../docs) - -# Config - -Check the full `Config` documentation here: [https://gacela-project.com/docs/config/](https://gacela-project.com/docs/config/) - -Use a Config Class to construct your business domain classes by injecting the data from the Config using the Factory -when you do the creation of your domain classes. - -In order to achieve that, you need to create a `gacela.json` file in your application root. - -[<< Factory](../docs/003_factory.md) | [Dependency Provider >>](../docs/005_dependency_provider.md) diff --git a/docs/005_dependency_provider.md b/docs/005_dependency_provider.md deleted file mode 100644 index cd1f8eac..00000000 --- a/docs/005_dependency_provider.md +++ /dev/null @@ -1,9 +0,0 @@ -[Back to the index](../docs) - -# Dependency Provider - -Check the full `DependencyProvider` documentation here: [https://gacela-project.com/docs/dependency-provider/](https://gacela-project.com/docs/dependency-provider/) - -This is the place where you can define the dependencies that a particular module has with other modules. - -[<< Config](../docs/004_config.md) | [Code Generator >>](../docs/006_code_generator.md) diff --git a/docs/006_code_generator.md b/docs/006_code_generator.md deleted file mode 100644 index 1b23068a..00000000 --- a/docs/006_code_generator.md +++ /dev/null @@ -1,15 +0,0 @@ -[Back to the index](../docs) - -# Code Generator - -Gacela Framework provides you some commands out-of-the-box to generate a `facade`, `factory`, `config`, -`dependency provider` or a full `module` with a single command. - -- `make:module `: Create a new Facade, Factory, Config, and DependencyProvider -- `make:file [facade, factory, dependency-provider, config]`: Create one or more files of the specified type/s - - -Example: -`./vendor/bin/gacela make:module App/TestModule` - -[<< Dependency Provider](../docs/005_dependency_provider.md) diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index ae4778d1..00000000 --- a/docs/README.md +++ /dev/null @@ -1,14 +0,0 @@ -[Back to the homepage](../README.md) - -

- Gacela logo -

- -## Documentation - -- [How to start](001_basic_concepts.md) - - [Facade](002_facade.md): The entry point of your module - - [Factory](003_factory.md): The place where you create your domain services and objects - - [Config](004_config.md): Reads the values defined in your config path - - [DependencyProvider](005_dependency_provider.md): It defines the dependencies between modules - - [Code generator](006_code_generator.md): Some commands out-of-the-box for generating code diff --git a/docs/imgs/gacela-logo-blue.svg b/gacela-logo.svg similarity index 100% rename from docs/imgs/gacela-logo-blue.svg rename to gacela-logo.svg From 2231d938d6e9ed927b0baf40978bee900d4fffe3 Mon Sep 17 00:00:00 2001 From: Chemaclass Date: Thu, 15 Jul 2021 21:00:58 +0200 Subject: [PATCH 3/3] Update documentation in the readme --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 0e2e9abc..f95c708c 100644 --- a/README.md +++ b/README.md @@ -31,14 +31,10 @@ scalability. It will certainly encourage your modules to interact with each othe rules: - Different modules can interact **only** via their `Facade`. -- The `Facade` has access to the `Factory`. -- The `Factory` creates the objects from the module and has access to the Module's `Config`. -- The `Config` gets the values from your defined config files. -- The `DependencyProvider` uses the Locator to get the Facades from different modules. - -### You can check the full documentation [here](https://gacela-project.com/) - ---- +- The [`Facade`](https://gacela-project.com/docs/facade/) has access to the `Factory`. +- The [`Factory`](https://gacela-project.com/docs/factory/) creates the objects from the module and has access to the Module's `Config`. +- The [`Config`](https://gacela-project.com/docs/config/) gets the values from your defined config files. +- The [`DependencyProvider`](https://gacela-project.com/docs/dependency-provider/) uses the Locator to get the Facades from different modules. ### Installation @@ -46,6 +42,10 @@ rules: composer require gacela-project/gacela ``` +### Documentation + +You can check the full documentation in the official [website](https://gacela-project.com/). + ### Examples You can see an example of a module using gacela in [this repository](https://github.com/gacela-project/gacela-example).