---
title: "Configuration — Permissions for Laravel | Roundly"
description: "Every config key and its default — models, table names, holder key type, Gate hook, description fallback and cache."
url: https://roundly-consulting.com/open-source/docs/permissions-for-laravel/configuration
language: en
---

[All packages](https://roundly-consulting.com/open-source.md)

[Permissions for Laravel](https://roundly-consulting.com/open-source/docs/permissions-for-laravel.md)

# Configuration

The published config/permissions.php in full:

```php
return [
    'models' => [
        'role' => RoundlyConsulting\Permissions\Models\Role::class,
        'permission' => RoundlyConsulting\Permissions\Models\Permission::class,
    ],

    'table_names' => [
        'roles' => 'roles',
        'permissions' => 'permissions',
        'permission_role' => 'permission_role',
        'model_roles' => 'model_roles',
        'model_permissions' => 'model_permissions',
    ],

    'key_type' => env('PERMISSIONS_KEY_TYPE', 'bigint'),

    'register_gate_check' => true,

    'description_fallback' => env('PERMISSIONS_DESCRIPTION_FALLBACK', RoundlyConsulting\Translatable\Enums\FallbackMode::Fallback),

    'cache' => [
        'store' => env('PERMISSIONS_CACHE_STORE', 'default'),
        'key' => 'permissions.cache',
        'ttl' => env('PERMISSIONS_CACHE_TTL', 300), // seconds (at least 1)
    ],
];
```

## Every key

| Key | Default | Env | Purpose |
| --- | --- | --- | --- |
| `models.role` | Role::class | — | Role model; swap for a subclass to extend it. Anything else throws InvalidConfigurationException. |
| `models.permission` | Permission::class | — | Permission model; swap for a subclass. Anything else throws InvalidConfigurationException. |
| `table_names.roles` | roles | — | Roles table. |
| `table_names.permissions` | permissions | — | Permissions table. |
| `table_names.permission_role` | permission\_role | — | Role ↔ permission pivot. |
| `table_names.model_roles` | model\_roles | — | Holder ↔ role polymorphic pivot. |
| `table_names.model_permissions` | model\_permissions | — | Holder ↔ permission polymorphic pivot. |
| `key_type` | bigint | `PERMISSIONS_KEY_TYPE` | Holder key type — bigint, uuid or ulid. Types model\_id; set before you migrate. Unset or blank reads as bigint; any other value throws InvalidConfigurationException. |
| `register_gate_check` | true | — | Register the Gate::before hook so can:<permission> resolves. Accepts true/false, 1/0, on/off, yes/no; blank is not set, so true applies; anything else throws InvalidConfigurationException at boot. |
| `description_fallback` | Fallback | `PERMISSIONS_DESCRIPTION_FALLBACK` | How the translatable description falls back — Fallback, None or Any. A case or its string value (fallback, none, any); blank is not set, so Fallback applies; an unknown value throws InvalidConfigurationException instead of reading as Fallback. |
| `cache.store` | default | `PERMISSIONS_CACHE_STORE` | Cache store for the catalog; default — or a blank value, which is not set — uses the app’s default store. A non-string value throws. |
| `cache.key` | permissions.cache | — | Cache key for the catalog. A blank value is not set, so the default applies; a non-string value throws. |
| `cache.ttl` | 300 | `PERMISSIONS_CACHE_TTL` | Catalog TTL in seconds, at least 1 — short on purpose, it bounds a missed invalidation. An int or a canonical integer string; blank is not set, so 300 applies; “five”, “1.5” or 0 throws InvalidConfigurationException. |

There is no guard concept — no guard\_name column, config key or parameter. The package is single-guard by design.

## Environment

The deployment-sensitive keys are env-backed:

```bash
# bigint | uuid | ulid — set before you publish and run the migrations
PERMISSIONS_KEY_TYPE=bigint

# fallback | none | any
PERMISSIONS_DESCRIPTION_FALLBACK=fallback

# "default" uses the app's default cache store
PERMISSIONS_CACHE_STORE=default
PERMISSIONS_CACHE_TTL=300
```

Set table\_names and key\_type before you migrate — both are read when the migrations run, and column names are fixed. A blank table name is not set, so its default applies; a non-string table name throws InvalidConfigurationException.

## Show your open-source love

This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.

[More ways to support, including crypto](https://roundly-consulting.com/support-us.md)

By donating, you agree to our [donation terms](https://roundly-consulting.com/donation-terms.md).

[Support our open source work (opens in a new tab)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Join us on Patreon (opens in a new tab)](https://www.patreon.com/cw/roundly)

## Want this built into your product?

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.

[Get a quote in 48 hours](https://roundly-consulting.com/contact.md) [Browse all packages](https://roundly-consulting.com/open-source/docs/permissions-for-laravel.md)