From 8984e0368ad457a2280b5a3208bf015d86e3271e Mon Sep 17 00:00:00 2001 From: John Watkins Date: Mon, 12 Jun 2023 12:30:18 -0500 Subject: [PATCH 1/3] Start development.md --- DEVELOPMENT.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 DEVELOPMENT.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000..4b43520 --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,78 @@ +This file includes details for developers contributing to this code base. + +## Code Architecture + +This package follows a simple dependency-injection pattern. There are two types of components within this pattern. Both are registered in [the Plugin class](/includes/classes/Plugin.php). + +1. Modules: Modules are loaded on every execution. The implement the `Module` interface and include a `register` method that performs setup actions. The `register` method is called automatcically when the module is instantiated. +2. Services: Services are loaded when they are declared as dependencies for Modules and other Services. They implement the `Service` interface. If a service should only be instantiated once and shared throughout the system, it should instead implement the `SharedService` interace. + +### Declaring Dependencies + +Once a Service has been declared in [the Plugin class](/includes/classes/Plugin.php) and implements either `Service` or `SharedService`, it will automatically be passed to any module or service in the system that declares it via a type hint in its own constructor. For example: + + +```PHP +// Service class added to the services array in Plugin.php +class MyService implements Service { + public function say_hello() { + echo 'hello'; + } +} + +class MyModule implements Module { + private $my_service; + + public function construct( Service $my_service ) { // Automatically passed in. + $this->my_service = $my_service; + } + + public function register() { + // setup actions + } + + public function greet() { + $this->my_service->say_hello(); + } +} +``` + +A dependency can also be an interface. The system only allows one implementation of an interface to be registered at a time. For example: + +```PHP +interface MyInterface { + public function say_hello(); +} + +class MyService implements Service, MyInterface { + public function say_hello() { + echo 'hello'; + } +} + +class MyModule implements Module { + private $my_service; + + public function construct( MyInterface $my_service ) { // Automatically passed in. The dependency injector will detect the concrete class that implements the interface. + $this->my_service = $my_service; + } + + public function register() { + // setup actions + } + + public function greet() { + $this->my_service->say_hello(); + } +} +``` + +## Unit Testing + +Unit tests run inside a GitHub Action on Pull Requests. Running tests locally requires Docker. Once Docker is running, run tests with the following commands: + +```bash +npm install # Installs the @wordpress/env package. +npm run env-start # Starts the WordPress environment. +npm run test:php # Runs the PHP unit tests. +``` From e7165c7d7b143f5dce94788e07d1ac3ce2053bc7 Mon Sep 17 00:00:00 2001 From: John Watkins Date: Mon, 12 Jun 2023 12:33:05 -0500 Subject: [PATCH 2/3] Spelling --- DEVELOPMENT.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 4b43520..0b13cd4 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -4,8 +4,8 @@ This file includes details for developers contributing to this code base. This package follows a simple dependency-injection pattern. There are two types of components within this pattern. Both are registered in [the Plugin class](/includes/classes/Plugin.php). -1. Modules: Modules are loaded on every execution. The implement the `Module` interface and include a `register` method that performs setup actions. The `register` method is called automatcically when the module is instantiated. -2. Services: Services are loaded when they are declared as dependencies for Modules and other Services. They implement the `Service` interface. If a service should only be instantiated once and shared throughout the system, it should instead implement the `SharedService` interace. +1. Modules: Modules are loaded on every execution. They implement the `Module` interface and include a `register` method that performs setup actions. The `register` method is called automatically when the module is instantiated. +2. Services: Services are loaded when they are declared as dependencies for Modules and other Services. They implement the `Service` interface, but if a service should only be instantiated once and shared throughout the system, it should instead implement the `SharedService` interace. ### Declaring Dependencies From d7e5135affe7495949e7cc3c72a98919b03b3236 Mon Sep 17 00:00:00 2001 From: John Watkins Date: Mon, 12 Jun 2023 12:37:15 -0500 Subject: [PATCH 3/3] clarity --- DEVELOPMENT.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 0b13cd4..b34abaf 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -5,7 +5,7 @@ This file includes details for developers contributing to this code base. This package follows a simple dependency-injection pattern. There are two types of components within this pattern. Both are registered in [the Plugin class](/includes/classes/Plugin.php). 1. Modules: Modules are loaded on every execution. They implement the `Module` interface and include a `register` method that performs setup actions. The `register` method is called automatically when the module is instantiated. -2. Services: Services are loaded when they are declared as dependencies for Modules and other Services. They implement the `Service` interface, but if a service should only be instantiated once and shared throughout the system, it should instead implement the `SharedService` interace. +2. Services: Services are loaded when they are declared as dependencies for Modules and other Services. They implement the `Service` interface, but if a service should only be instantiated once and shared throughout the system, it should instead implement the `SharedService` interface. ### Declaring Dependencies @@ -37,7 +37,7 @@ class MyModule implements Module { } ``` -A dependency can also be an interface. The system only allows one implementation of an interface to be registered at a time. For example: +A dependency can also be an interface. The system only allows one implementation of an interface to be registered at a time and will automatically detect the registered service class that implements that interface. For example: ```PHP interface MyInterface {