Storing Users in a Database

If you have a large or unknown number of users, it can be a good idea to store them in a database instead of the filesystem for the sake of performance or scaling.

From a fresh Statamic project#

If you installed Statamic using the statamic new command, or created a project based on the statamic/statamic repo, it will be configured to store users in files.

Statamic comes with an Eloquent driver to make the transition as seamless as possible.

Ensure you have a database configured.

In your user model, cast the preferences column to json.

class User extends Authenticatable
{
    protected function casts(): array 
    { 
        return [ 
            'preferences' => 'json', 
        ]; 
    } 

    // ...
}

If you plan to import existing file based users, you'll need to use UUIDs for the primary key. You can do this by adding a trait to your user model:
```
class User extends Authenticatable
{
    use \Illuminate\Database\Eloquent\Concerns\HasUuids; 

    // ...
}
```

In config/statamic/users.php, use the Eloquent repository.

-'repository' => 'file', 
+'repository' => 'eloquent',

In config/auth.php, use the Eloquent provider:

 'providers' => [
     'users' => [
-        'driver' => 'statamic', 
+        'driver' => 'eloquent', 
+        'model' => App\Models\User::class, 
     ]
 ]

Generate a migration for the role and user group pivot tables.

php please auth:migration

If you're planning to import existing file based users, edit the migration to change the id & user_id columns to the uuid type.

Schema::table('users', function (Blueprint $table) {
    $table->uuid('id')->change(); 
    $table->boolean('super')->default(false);
    $table->string('avatar')->nullable();
    $table->json('preferences')->nullable();
    $table->timestamp('last_login')->nullable();
    $table->string('password')->nullable()->change();
});

Schema::create('role_user', function (Blueprint $table) {
    $table->increments('id');
    $table->foreignId('user_id')->constrained('users')->cascadeOnDelete();  
    $table->uuid('user_id');  
    $table->foreign('user_id')->references('id')->on('users')->cascadeOnDelete();  
    $table->string('role_id');
});

Schema::create('group_user', function (Blueprint $table) {
    $table->increments('id');
    $table->foreignId('user_id')->constrained('users')->cascadeOnDelete();  
    $table->uuid('user_id');  
    $table->foreign('user_id')->references('id')->on('users')->cascadeOnDelete();  
    $table->string('group_id');
});

If you're using the database session driver and using UUIDs as the primary key for users, make sure to update the user_id column in the sessions table.
```
Schema::table('sessions', function (Blueprint $table) {  
    $table->foreignUuid('user_id')->nullable()->change();  
});  
```
If you've customized your user blueprint, edit the migration so it includes those fields as columns. You can also create a new migration file by running php artisan make:migration. You'll have to manually edit the migration file to reflect your changes. Read up on Laravel database migrations here.
```
$table->string('some_field');
```

Run the migrations:
```
php artisan migrate
```
If you have existing file based users, import them:
```
php please eloquent:import-users
```

If you are using the Statamic forgot password form, add the following method to your User model

public function sendPasswordResetNotification($token)
{
    $this->notify(new \Statamic\Notifications\PasswordReset($token));
}

In an existing Laravel app#

If you've installed Statamic into an existing Laravel app, it will already be configured to use the Eloquent driver.

You will need to run migrations to prepare your database for Statamic's user, password reset, and permission setup.

Configure the two separate password reset drivers. Unlike a regular Laravel installation, Statamic has a second table to track password activations which are the same as resets, but last a little longer before they expire. This is optional.

In config/auth.php add the following inside the passwords array:
```
'activations' => [
    'provider' => 'users',
    'table' => 'password_activation_tokens',
    'expire' => 4320,
    'throttle' => 60,
],
```
In config/statamic/users.php change the passwords array to:
```
'passwords' => [
    'resets' => 'users',
    'activations' => 'activations',
],
```
Create and run the migrations.

This will add some columns to the users table (like super, and last_login), create the role_user and group_user pivot tables, and create the password_activations table.
```
php please auth:migration
php artisan migrate
```

Optional: If you are using the Statamic forgot password form, add the following method to your User model

public function sendPasswordResetNotification($token)
{
    $this->notify(new \Statamic\Notifications\PasswordReset($token));
}

This assumes you are happy to use our opinionated setup. If you need something more custom you can create your own user driver.

Roles and Groups (optional)#

By default, roles and groups are stored in flat files. If you would like to store them in the database instead, follow these steps:

Specify the roles and groups tables in the config/statamic/users.php config file.

 'tables' => [
     'users' => 'users',
     'role_user' => 'role_user',
-    'roles' => false, 
+    'roles' => 'roles', 
     'group_user' => 'group_user',
-    'groups' => false, 
+    'groups' => 'groups', 
 ],

Run php please auth:migration to generate the required migrations for the roles and groups tables. This will create two migrations in the database/migrations directory. You can delete the duplicate the statamic_auth_table migration.
Run the migrations using php artisan migrate.
Finally, if you have existing file based roles and groups, you can import them using these commands:
```
php please eloquent:import-roles
php please eloquent:import-groups
```

From a fresh Statamic project#

In an existing Laravel app#

Roles and Groups (optional)#

Docs Feedback