> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dezerx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# module.json and settings

> The manifest, the admin permissions it declares and the settings page core builds from a field list.

![The module.json keys and what reads each one](https://mintcdn.com/dezerx/dVNBM3sq4VCh7CKa/public/extensions/module-json/top.webp?fit=max\&auto=format\&n=dVNBM3sq4VCh7CKa\&q=85\&s=edd615dc3aa0b089b2d4a99c9bca8602)

## The manifest

```json module.json theme={null}
{
    "name": "AcmePanelService",
    "alias": "acmepanelservice",
    "description": "Provision and manage Acme game servers.",
    "category": "service",
    "display": "Acme Panel",
    "providers": ["Modules\\AcmePanelService\\Providers\\AcmePanelServiceServiceProvider"],
    "hasSettings": true,
    "settingsUrl": "/admin/acme-panel/settings",
    "permissions": {
        "category": "gateway_settings",
        "category_name": "Gateway & Service Settings",
        "nodes": {
            "/admin/acme-panel/settings": {
                "label": "Manage Acme Panel",
                "routes": ["/acme-panel/settings", "/acme-panel/test-connection"]
            }
        }
    },
    "logo": "/modules-logos/acme-panel-service.png"
}
```

The five required keys are `name`, `alias`, `description`, `category` and `providers`. `module:doctor` fails without them.

> [accordion] Every field
>
> | Field | Required | Used for |
> | - | - | - |
> | `name` | yes | StudlyCase. Namespace segment and what `Service.module` stores |
> | `alias` | yes | Lowercased name. Config, translation and view keys |
> | `description` | yes | Admin module list, and checkout for gateways |
> | `category` | yes | `service`, `gateway`, `social`, `registrar` or `addons` |
> | `providers` | yes | Fully qualified provider class names |
> | `display` | no | Friendly name. Always set it |
> | `logo` | no | Path under `public/`. Needed for login buttons |
> | `hasSettings`, `settingsUrl` | no | The Settings button in Admin, Modules |
> | `permissions` | no | Admin permission nodes |
> | `api` | no | API slug and API key permissions for module endpoints. See [API endpoints](https://docs.dezerx.com/extensions/tutorials/addons.md#api-endpoints) |
> | `secrets` | no | Tables and columns the Secrets vault should list, as `{table, columns}` |
> | `link_url`, `link_column`, `colors` | login providers | Button, route and users column. See [Login providers](https://docs.dezerx.com/extensions/tutorials/socials.md) |
> | `keywords`, `priority`, `files` | no | Unused by Spartan |

## Admin permissions

Declare them in `module.json`. Core merges them into the permission map and the admin role editor.

> [accordion] Routes leave off the /admin prefix
>
> Node keys carry the full path, the `routes` list does not. `module:doctor` flags it if you get this wrong.

> [accordion] Every node needs a category
>
> Without one, the role editor draws no checkbox and only a superadmin can use the page. Existing categories are `gateway_settings` and `addon_module_settings`.

> [accordion] Nodes can be method specific
>
> Prefix with a verb: `"DELETE:/admin/acme-panel/backups/{id}"`. A node with no routes is fine when your controller checks `$user->hasPermission(...)` itself.

> [accordion] Do not rename a node after release
>
> Keys are stored in each role's permissions. Renaming one silently removes access.

For a single route you can name the permission inline:

```php theme={null}
Route::get('/admin/acme-panel/settings', [SettingsController::class, 'index'])
    ->defaults('permission', '/admin/acme-panel/settings');
```

## Settings page without React

Extend `ModuleSettingsController`, return your values and a field list, and core renders the page. It takes the title, logo and back link from `module.json`. The page uses the Admin Modern theme.

![A generated module settings page in Admin Modern](https://mintcdn.com/dezerx/dVNBM3sq4VCh7CKa/public/extensions/module-json/settings-page.webp?fit=max\&auto=format\&n=dVNBM3sq4VCh7CKa\&q=85\&s=6727b2cad3900faf1a5a3198bdfde42b)

```php app/Http/Controllers/SettingsController.php theme={null}
class SettingsController extends ModuleSettingsController
{
    protected function settings(): array
    {
        $c = AcmePanelCredential::first();

        return ['url' => $c?->url ?? '', 'api_key' => $c?->api_key ?? ''];
    }

    protected function settingsDefinition(array $settings): array
    {
        return [
            'title' => 'Acme Panel',
            'description' => 'Where to reach your Acme install.',
            'update_url' => url('/admin/acme-panel/settings'),
            'test_url' => url('/admin/acme-panel/test-connection'),
            'fields' => [
                ['name' => 'url', 'type' => 'url', 'label' => 'API URL', 'required' => true],
                [
                    'name' => 'api_key',
                    'type' => 'password',
                    'label' => 'API key',
                    'required' => true,
                    'configured' => $settings['api_key'] !== '',
                ],
            ],
        ];
    }
}
```

> [!WARNING]
>
> Use `url()` for `update_url` and `test_url`, not `route()`. `route()` throws while the module is disabled.

> [accordion] Field types
>
> | Type | Notes |
> | - | - |
> | `text`, `email`, `url` | Plain inputs |
> | `password` | Reveal toggle. Shows "Stored" when `configured` is true |
> | `number` | Takes `min`, `max`, `step` |
> | `textarea` | Takes `rows`. Full width |
> | `select` | `options` as `[['value' => ..., 'label' => ...]]` |
> | `toggle` | Boolean switch |
> | `readonly` | Display only with a copy button. Good for callback URLs |
>
> Every field also takes `placeholder`, `help`, `max_length`, `full_width`, `copyable` and `visible_when` (`['field' => 'mode', 'equals' => 'live']`). For a rich text field you need a custom page, see [Admin pages](https://docs.dezerx.com/extensions/tutorials/admin-pages.md).

> [accordion] Definition keys
>
> | Key | Meaning |
> | - | - |
> | `title`, `description`, `update_url`, `fields` | Required |
> | `groups` | Tabs: `[['key' => 'connection', 'label' => 'Connection']]`. Tag fields with `'group'`. Tabs show only when more than one group has visible fields |
> | `test_url`, `test_label` | A header button that POSTs to the URL. Return `back()->with('success' or 'error', ...)` for a toast |
> | `notices` | Sidebar hints. A URL in one gets a copy button |
> | `status_cards` | Sidebar panels with `title`, `status`, `status_tone` (`success`, `warning`, `danger`, `neutral`) and `rows` |
>
> ```php theme={null}
> 'status_cards' => [[
>     'title' => 'Connection',
>     'status' => $settings['api_key'] ? 'Configured' : 'Not configured',
>     'status_tone' => $settings['api_key'] ? 'success' : 'neutral',
>     'rows' => [['label' => 'Webhook URL', 'value' => url('/api/acme/webhook'), 'copyable' => true]],
> ]],
> ```
>
> Saving submits every tab, not only the visible one.

Two helpers come with the base class:

> [card] resolveSecret()
>
> `resolveSecret($request, 'api_key', $stored)` keeps the saved secret when the password box is posted empty.

> [card] flushPaymentGatewayCache()
>
> Gateways must call it after saving, or checkout keeps a stale list for five minutes.

> [!TIP]
>
> Always ship a Test connection action. It turns a support ticket into a five minute setup.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.