Conventions Reference

Core finds most module code by building a class name as a string, so a typo means the feature silently doesn’t exist. Copy names from here rather than from memory, and run php artisan module:doctor to check.

Throughout this page, {M} is the name field from module.json, for example PterodactylService.

Service module classes

Class	Called by	Signature	Static?
`Modules\{M}\Services\ModuleServiceActions`	`CreateServiceJob`, `HandleConfigurableOptionsChangeService`	`createServerForService(Service $s, array $cfg = []): void` `hasExistingConfiguration(Service $s): bool` `createServer(Product $p, User $u, array $cfg = []): Service` `createServerForServiceWithoutProduct(Service $s, array $cfg = []): void`	instance
`Modules\{M}\Services\Actions\SuspendServerService`	`ServiceManagementService`	`suspendServer(int $serviceId): array`	static
`Modules\{M}\Services\Actions\UnsuspendServerService`	`ServiceManagementService`	`unsuspendServer(int $serviceId): array`	static
`Modules\{M}\Services\Actions\DeleteServerService`	`ServiceManagementService`	`deleteServer(int $serviceId): array`	static
`Modules\{M}\Services\RenewService`	`RenewServiceController`, `SubscriptionJob`, `OrderService`	extends `BaseRenewService`, override `onAfterRenewal(Service $s, string $cycle): void`	instance
`Modules\{M}\Services\CancelService`	`CancelServiceController`, `CancellationVerificationService`	extends `BaseCancelService`, implement `remoteResourceId()` and `deleteRemoteResource()`	instance
`Modules\{M}\Services\UpgradeService`	`HandleUpgradeService`	`processUpgrade(Service $s, Invoice $i): bool`	instance (container)
`Modules\{M}\Services\DowngradeService`	`HandleDowngradeService`	`processDowngrade(Service $s, Invoice $i): bool`	instance (container)
`Modules\{M}\Services\AddonService`	`HandleAddonService`, `HandleAddon`	`applyAddon(Service $s, array $addon, int $qty = 1): array` `removeAddon(Service $s, array $addon, int $qty = 1): array`	instance (container)
`Modules\{M}\Services\MarketCheckoutConfig`	`MarketController`, `ServiceCreationService`	`getCheckoutFields(): array` `getServiceConfigFields(): array` `validateCheckoutData(array $d): array` `getServerConfiguration(int $productId): array` (optional)	static
`Modules\{M}\Services\ServiceControlsService`	`ServiceControlLoader`	`getServiceControls($serviceConfig = null, $serviceId = null): array`	instance
`Modules\{M}\Services\ServiceDetails`	`ServiceDetailsController` (user and admin)	`getSections(Service $s): array` `getTabConfig(): array` `getServiceData(Service $s): array` `getAvailableActions(Service $s): array` `updateAccount(Service $s, array $d): array` `changeOwner(Service $s, int $ownerId): array`	instance
`Modules\{M}\Services\{M}`	`ProductController`, `ConfigurableOptionGroupController`, `AddonPresetGroupController`	Your own methods, for admin dropdowns	instance

Only ModuleServiceActions and the three Actions\* classes are needed for a working module. Everything else gates an optional feature.

ServiceControlLoader always passes two arguments to getServiceControls(), so declare both even if you ignore them.

There used to be a Modules\{M}\Services\{M}Service class for termination. It never resolved, because the lookup produced names like PterodactylServiceService. Termination goes through Actions\DeleteServerService via ServiceManagementService::executeModuleAction(). Ignore that pattern if you see it in older code.

Gateway module classes

Class	Called by	Notes
`Modules\{M}\Services\{M}PaymentService`	`PaymentServiceProvider`, `PaymentGatewayManager`	Required. Extend `BasePaymentService`.
`Modules\{M}\Http\Controllers\PaymentController`	routes	Extend `ModulePaymentController`, set `$paymentServiceClass` and `$gatewayName`
`Modules\{M}\Http\Controllers\SettingsController`	routes	Extend `ModuleSettingsController`
`Modules\{M}\Services\CheckoutHandler`	`CheckoutService`	Optional. `shouldHandleCheckout()` plus `handleCheckout()` (23 args)
`Modules\{M}\Services\RenewalHandler`	`RenewServiceController`	Optional. `shouldHandleRenewal()` plus `handleRenewal()` (7 args)
`Modules\{M}\Services\InvoicePaymentHandler`	`PaymentController`	Optional. `shouldHandleInvoicePayment()` plus `handleInvoicePayment()` (6 args)

Gateway key: Str::lower(Str::before($moduleName, 'Gateway')), so AcmeGateway gives acme. getGatewayName() must return it.

PaymentGatewayInterface

createPayment(float $amount, string $currency, array $metadata = []): array
executePayment(string $paymentId, ?string $payerId = null): bool
getPaymentDetails(string $paymentId): array
getApprovalUrl(string $paymentId, array $paymentDetails): ?string
getConfig(): array
validateNotification(array $data): bool
getVerificationMethod(): string                  // 'webhook' | 'redirect' | 'both'
getPaymentToken(string $paymentId, int $userId): ?PaymentToken     // from the base
createPaymentToken(array $tokenData): PaymentToken                 // from the base
handlePaymentSuccess(string $paymentId, array $paymentData): array // from the base

Plus protected function getGatewayName(): string.

Optional gateway interfaces

Interface	Adds
`App\Services\Payment\HandlesGatewayWebhook`	`handleWebhook(Request $r): Response`
`App\Services\Payment\GatewayVariantInterface`	`getGatewayVariants(): ?array`, `resolveVariant(string $k): bool`, `getModuleName(): string`
`App\Services\Payment\GatewayFlowProviderInterface`	`getGatewayFlowHandler(): object`

getConfig() shape

[
    'name' => 'Acme',              // internal
    'display_name' => 'Acme Pay',  // shown at checkout
    'description' => '...',
    'logo' => '/modules-logos/acme-gateway.png',
    'enabled' => bool,             // gates visibility entirely
    'mode' => 'sandbox',           // optional
]

handlePaymentSuccess() types

$paymentData['type'] is one of market, renewal, invoice, upgrade, downgrade, configurable_options_change, addon, balance, standalone.

OAuth provider modules

Discovered by App\Modules\OAuthProviderRegistry, which scans enabled modules whose name contains Provider.

Concern	Where
Discovery	`OAuthProviderRegistry::all()`, `forLogin()`, `forUser(?User)`
Required manifest keys	`link_url`, `link_column`, `logo`
Button colours	`colors` in `module.json` (`bg`, `text`, `hover`), else a built-in table by name
Driver registration	`$socialiteDriver` and `$socialiteProvider` on `OAuthProviderServiceProvider`
Credentials	Module model, passed per request with `Socialite::driver(...)->setConfig(new Config(...))`
Registration	`UserRegistrationService::registerViaOAuth($user, $key, $label, $linkColumn, $avatar, $extra)`
Consumers	`Auth\LoginController` and `MarketController` use `forLogin()`, `ProfileController` uses `forUser()`

registerViaOAuth() resolves by link column, then by email only if that account already carries the same provider ID, then creates. An email match on an unlinked account throws "...already exists but is not linked to {$label}", which each controller surfaces verbatim.Don’t relax that: matching on email alone is an account-takeover path.

Core base classes and interfaces

Class	Namespace	For
`BaseRenewService`	`App\Services`	Service renewal
`BaseCancelService`	`App\Services`	Service cancellation
`CancelServiceInterface`	`App\Contracts`	Cancellation contract
`RenewServiceInterface`	`App\Services`	Renewal contract
`BasePaymentService`	`App\Services\Payment`	Gateway payment service
`PaymentGatewayInterface`	`App\Services\Payment`	Gateway contract
`PaymentGatewayManager`	`App\Services\Payment`	Gateway registry and resolution
`ModulePaymentController`	`App\Http\Controllers\Payment`	Gateway payment controller
`ModuleSettingsController`	`App\Http\Controllers\Payment`	Declarative admin settings, any module type
`BaseModuleServiceProvider`	`App\Modules`	Shared module bootstrapping
`BaseModuleRouteServiceProvider`	`App\Modules`	Shared route wiring
`ServiceModuleServiceProvider`	`App\Modules`	Service module provider base
`GatewayModuleServiceProvider`	`App\Services\Payment\Modules`	Gateway provider base
`OAuthProviderServiceProvider`	`App\Modules`	OAuth provider base
`AddonModuleServiceProvider`	`App\Modules`	Addon provider base
`EmptyGatewayEventServiceProvider`	`App\Services\Payment\Modules`	Event provider for gateways with no listeners
`ModuleContracts`	`App\Modules`	The extension-point spec that drives `module:doctor`
`ModulePermissionRegistry`	`App\Modules`	Merges module permissions into core
`OAuthProviderRegistry`	`App\Modules`	Enabled OAuth providers
`ServiceControlLoader`	`App\Services`	Loads `ServiceControlsService`
`ModulePath`	`App\Support`	Module paths and groups

Core events

Event	Fires when
`UserRegistered`	A user registers
`ServiceCheckoutInitiated`	Checkout starts
`ServicePaymentCompleted`	Payment for a service succeeds
`InvoicePaid`, `StandaloneInvoicePaid`	An invoice is marked paid
`ServiceRenewalInitiated`, `ServiceRenewed`	Renewal starts, completes
`ServiceUpgradeCompleted`, `ServiceDowngradeCompleted`	A plan change completes
`ServiceConfigurationChanged`	Configurable options changed
`AddonPurchased`	An addon is bought
`ServiceSuspended`, `ServiceUnsuspended`	Suspension state changes
`ServiceTerminated`, `ServiceCancelled`	A service ends
`ServiceWarned`	An overdue warning is issued
`ServiceAutoRenewalToggled`	Auto-renew switched
`OrderRequiresManualApproval`	An order is held for review
`BankWireProofSubmitted`	Bank transfer proof uploaded
`TicketCreated`, `TicketMessageSent`, `TicketStatusChanged`, `TicketTransferred`	Support tickets
`DiscordLinked`, `DiscordUnlinked`	Discord link state

All post-events. None can veto or change the action.

Core jobs that call modules

Job	Resolves
`CreateServiceJob`	`ModuleServiceActions`
`HandleUpgradeService`	`UpgradeService`
`HandleDowngradeService`	`DowngradeService`
`HandleAddonService`	`AddonService`
`HandleConfigurableOptionsChangeService`	`ModuleServiceActions`
`SubscriptionJob`	`RenewService`, `Services\Actions\*`

Middleware

Middleware	Use
`AdminMiddleware`	Admin only
`PermissionMiddleware`	Permission check, from route defaults or the merged map
`AdminReauthMiddleware`	Password reconfirmation for sensitive admin actions
`AdminAuditLogMiddleware`	Logs admin mutations
`ModuleServiceAuditLogMiddleware`	Logs module service panel actions
`CheckServicePermissions`	Sub-user permissions on `/service/{serviceId}/...`
`ServiceRoutesMiddleware`	Routes the request to the right service module
`CheckUserSuspension`	Blocks suspended users
`CheckIpBan`	IP bans
`Require2FA`	Enforces 2FA

Route files

File	Loaded by	Prefix and middleware
`web.php`	`RouteServiceProvider::map()`	`web`
`api.php`	`RouteServiceProvider::map()`	prefix `api`, name `api.`, middleware `api`
`settings.php`	`require` from `web.php`	admin stack, `/admin/{module}/...`
`panel.php`	`require` from `web.php`	`service/{serviceId}` plus service middleware
`payment.php`	`require` from `web.php`	`auth`, `verified`
`console.php`	The provider, after boot	not applicable, `Schedule::` calls

module.json fields

Field	Required	Used by
`name`	yes	Namespace segment, `Service.module`, everything
`alias`	yes	Config, translation and view keys
`description`	yes	Admin module list, gateway checkout
`category`	yes	Decides the group directory
`providers`	yes	Laravel provider registration
`display`	no	UI label. Set it: the fallback can surface your alias
`logo`	no	Admin list, checkout, login buttons
`hasSettings`, `settingsUrl`	no	Settings button in the admin module list
`permissions`	no	Admin permission nodes and route mapping
`link_url`, `link_column`, `colors`	OAuth	Login and profile buttons
`keywords`, `priority`, `files`	no	nwidart, unused by DezerX logic

permissions shape

"permissions": {
    "category": "gateway_settings",
    "category_name": "Gateway & Service Settings",
    "nodes": {
        "/admin/acme/settings": {
            "label": "Manage Acme",
            "routes": ["/acme/settings", "/acme/test-connection"]
        },
        "DELETE:/admin/acme/backups/{id}": { "label": "Delete Acme Backups" }
    }
}

Node keys are stored in AdminRole.permissions JSON, so never rename one after release. Routes omit the /admin prefix. A node with no category is grantable to superadmins only.

Existing categories you can add to: gateway_settings (“Gateway & Service Settings”) and addon_module_settings (“Addon Module Settings”).

Settings page definition

Returned from settingsDefinition(). Rendered by the shared admin/ModuleSettings page.

string

required

Heading shown on the page.

string

required

One line under the heading.

string

required

Where the form POSTs. Use url(), not route().

array

required

See field types.

array

Splits the form into tabs. Each entry takes key, label and optional description.

string

Adds a Test connection button to the header.

string

Overrides the button text.

string[]

Sidebar hints. Ones containing a URL get a copy button.

array

Sidebar panels. Take title, description, status, status_tone and rows.

module_name, display_name, logo, category, kind_label, back_url and back_label are filled in from module.json by ModuleSettingsController. You don’t set them.

Commands

php artisan make:module {Name} --type={service|gateway|provider|addon} [--webhook] [--enable]
php artisan module:doctor [{Name}...] [--json] [--strict]
php artisan module:list
php artisan module:enable {Name}
php artisan module:disable {Name}
php artisan module:migrate {Name}

composer dump-autoload            # after adding root-layout classes
php artisan route:clear && php artisan config:clear
vendor/bin/pest                   # test suite

make:payment-gateway still exists and works, but make:module --type=gateway supersedes it.

Things that still need a core change

What	Where
A sidebar link without seeding a row	`SidebarLink` table, via the admin UI
Replacing a string-resolved contract with a typed one	`App\Modules\ModuleContracts` plus the call site

Everything else, including admin routes, permissions, OAuth registration and provider branding, is declarable from the module itself.

GETTING STARTED

MAKE YOUR OWN

SPARTAN THEMES

Service module classes

Gateway module classes

OAuth provider modules

Core base classes and interfaces

Core events

Core jobs that call modules

Middleware

Route files

module.json fields

permissions shape

Settings page definition

Commands

Things that still need a core change

​Service module classes

​Gateway module classes

​OAuth provider modules

​Core base classes and interfaces

​Core events

​Core jobs that call modules

​Middleware

​Route files

​module.json fields

​permissions shape

​Settings page definition

​Commands

​Things that still need a core change

Service module classes

Gateway module classes

OAuth provider modules

Core base classes and interfaces

Core events

Core jobs that call modules

Middleware

Route files

module.json fields

permissions shape

Settings page definition

Commands

Things that still need a core change