Add docs for module vs package

[circlecube]

Detail when we need a module vs simply a package.

[wpscholar]

Initial thoughts on this:

• A module is intended to be toggled on and off.
• If a customer is expected to be able to toggle, it should be a module.
• If support is expected to be able to toggle, it should be a module.
• Modules should be able to be turned off without breaking anything else.
• Packages are always on and always run their code.
• If something is a utility code base or something that would break things if disabled, it should be a package.
• By package, we mean Composer package.
• A module is a Newfold-specific creation.

[wpscholar]

More thoughts:

The idea behind modularization is to make it easy for us to split up the work and more easily maintain things. The separation between packages/modules is mainly based on the single responsibility principle. As I see it, anything related to onboarding should be in an onboarding package/module. I'm not sold on whether onboarding should be a toggleable module or not. Users don't need the ability to turn it off and on and support doesn't really need that capability either. Regardless, unless there is a technical reason why we can't include a certain bit of code in a module if the code is related to that module's single purpose, then I say we keep all those things together as long as we can follow reasonable architectural principles. For example, one of those technical reasons might be that we need JS as an NPM package. When discussing just data and PHP code, I don't think we necessarily need to split things out further. I think we should probably come up with some convention for the organization of code so it is clear what always loads vs. what loads when the module is enabled.

We do have examples in other modules where we have code that always loads vs. what is toggleable. For example, the e-commerce module can be toggled, but we do have some code that handles automatically adding PayPal partner attribution codes to outgoing PayPal requests. Since that is directly related to e-commerce, it makes sense to keep it in that module. We also have other modules that handle plugin activation/deactivation hooks and upgrade processes outside of the toggleable aspect of the module.

Ultimately, if we need the ability to toggle something, it should be a Newfold module. If we don't, just a Composer package will do. If we need a hybrid, then a Newfold module with the ability to load some code all the time is the way to go.

[wpscholar]

A module (the always loaded portion) would register data into the container and other modules can read what they need from the container. We'll need to structure and name things well in the container, but that gives the module control over naming/re-naming options, etc. as needed. The container can hold data, factories, services, and callback functions for computed data (https://github.com/newfold-labs/container). Each module that depends on the data should have its own safeguards should a specific property not be available in the container. We should also be careful to leverage a shared interface/API for injected dependencies. In this way, we have loose coupling between the modules.

[arunshenoy99]

Newfold Modules are a fundamental component of Newfold's development framework. They are essentially Composer packages that enable the implementation of various features and functionalities within Newfold plugins. Modules can be categorized into three distinct types based on their intended usage.

1. Toggleable Module

A Toggleable Module is designed to be flexible, allowing it to be activated or deactivated based on specific conditions. This type of module can be toggled on and off by either customers or support staff by setting an option, transient, query parameter, or via the user interface (UI). It follows a common registration process and executes its code only as part of the callback function provided during the registration.

Usage Guidelines:

• Choose a Toggleable Module when your feature needs to be dynamically enabled or disabled through various means.
• This includes scenarios where the feature should be configurable on a per-customer or per-sub-brand basis.
• Toggleable Modules should register themselves using the Module Registration process, as outlined in Module Registration.
• Code execution within a Toggleable Module should be limited to the callback function provided during registration.
• Ensure that your feature does not require execution before the plugins_loaded hook.

2. Non-Toggleable Module

Non-Toggleable Modules, as the name suggests, cannot be turned on or off dynamically. These modules are designed to serve as Composer packages without the need for intricate registration processes. They do not place their code within the register function and can be considered as standalone utility packages.

Usage Guidelines:

• Utilize Non-Toggleable Modules when you have utility code that may be reused across multiple modules.
• Utility code can encompass a wide range of functionalities, such as reading from files or aggregating complex actions into a single, reusable class or function.
• Non-Toggleable Modules provide a standardized interface for performing specific tasks or operations.
• They do not need to follow the registration process and should not place their code within the register function.

3. Hybrid Modules

Hybrid Modules offer a high degree of flexibility but come with potential risks and complexities. These modules register themselves using the standard registration process, including the execution of part of their code within the callback function provided during registration. However, they can also contain code outside of the register function.

Usage Guidelines:

• Choose a Hybrid Module when your feature requires code execution before the plugins_loaded hook.
• Hybrid Modules are suitable for scenarios where you need to tap into early hooks, such as modifying the behavior of login_redirect.
• Ensure that your module does not contain shared utility code, as other modules may use it as a dependency.
• Be cautious when using Hybrid Modules to avoid unintentional activation of features not intended to be turned on. This can happen when another module uses the hybrid module as a dependency and ends up enabling features that were intended to be disabled.

Best Practices

1. Module Naming: Follow the documentation on naming modules to ensure clear and descriptive names for your modules. Refer to Module Naming Guidelines.

2. Scope and Clarity: Always scope your modules appropriately and avoid generic names. Clearly define the purpose of your module in its description. If your feature doesn't fit the scope of an existing module, consider creating a new one.

3. Modularity: Keep your code modular and well-organized to enhance maintainability and reusability within Newfold projects.