Submodules, providers and vendors

Submodules

A submodule is a separate top-level module whose name begins with a parent module's name. It is not nested on disk: it sits alongside every other module and has its own index.php and its own includes. The naming is what marks it as belonging to a family, and it lets a site pull in only the parts of a feature it wants.

The Member family is the worked example. Member owns the account itself; each concern that extends it lives in its own module named after Member:

• MemberAuthMethodEmail, MemberAuthMethodMobile - ways to sign in.
• MemberIdentity, MemberSetting, MemberVerification - profile, settings, contact verification.
• MemberFolder - a member-owned folder tree other tables can organise their rows into.

Nesting is decided by the longest matching name prefix. A module belongs to the longest existing module name that is a prefix of its own. So MemberFolderApi and MemberFolderAdmin are submodules of MemberFolder, not of Member, because MemberFolder is a longer prefix than Member. This keeps a family's admin and API surfaces attached to the exact part they extend.

Providers

A provider is an optional submodule where you usually include only one, the one your site needs. The parent module defines the contract; each provider implements it for a particular service, and you pick the provider that matches yours.

Payment ships with PaymentProviderStripe. Messaging ships one provider per channel and per service: MessagingEmailProviderSendgrid, MessagingSmsProviderTwilio, and MessagingNotificationProviderFirebase. A site includes the provider it uses for each channel and leaves the rest out; the parent module is written against the contract, not against any one provider.

Vendors

A vendor is the related pattern for a third-party service integration, named <Module>Vendor<Name>. Where a provider plugs into a feature module's contract, a vendor wraps an outside service a module talks to. Examples in the framework are StorageVendorAws and StorageVendorDropbox for Storage, CloudVendorGoogle and CloudVendorLocal, and LocationVendorGoogle. A top-level Vendor module sits alongside them.

This is an emerging convention rather than a fully formal one. The framework is only starting towards documenting it, so treat the names as the honest description of what exists today rather than a settled specification. The line between a provider and a vendor is not always sharp, and the set of vendor modules is still growing.

They are still ordinary modules

Whatever the pattern, a submodule, provider or vendor is a plain module: same directory layout, same index.php, same rule that it requires every module it uses. It registers with its parent the same way any module extends another - by calling the parent's config class - so the parent knows nothing about which providers or vendors exist. The naming groups a family for a reader; the wiring is the ordinary loose coupling every module uses.

Next: Building an admin system.