Skip to content
On this page

Auth Config

Auth Config was added to give you more control over how leaf handles authentication in your apps. Auth has been configured perfectly for most apps, but not all use cases are the same, hence, this brilliant addition.

This also includes various configurations for doing things like:

  • Setting custom token lifetime
  • Hiding/Showing user fields
  • Adding/removing default timestamps
  • Changing the default password key
  • Setting custom password encode methods
  • Turning off password encoding totally
  • Setting custom password verify methods
  • Hiding/Showing password field
  • Adding custom validation messages
  • Configuring tokens


To set a config variable, you can simply call the config method.

auth()->config("item", "value");

You can also pass in an array to set multiple configs at once:

  "item" => "value",
  "item2" => "value"


Below is a list of all available settings.


The DB_TABLE config allows you to set a particular table which leaf auth will perform operations on. Leaf auth will use this database table for storing and retrieving users. By default, it is set to users. This allows you to login, signup, update and fetch users without explicitly adding a table each time.


This determines whether Leaf should add the default created_at and updated_at timestamps on register and update. Default is true.


This setting has gone through a lot of changes since v2.4 beta, and may not work exactly the same way. This setting is run when leaf wants to encode a password. It now uses PASSWORD_DEFAULT by defaullt for encryption.

// This turns off password encoding
auth()->config("PASSWORD_ENCODE", false);

// defult encoding (Leaf\Helpers\Password::hash)
auth()->config("PASSWORD_ENCODE", null);

// use md5. We're still keeping support for md5 :-)
auth()->config("PASSWORD_ENCODE", Password::MD5);

// use custom method
auth()->config("PASSWORD_ENCODE", function ($password) {
  return Password::hash($password);


This setting is called when Leaf tries to verify a password. It works just like PASSWORD_ENCODE above.

// This turns off password encoding
auth()->config("PASSWORD_VERIFY", false);

// defult encoding (Leaf\Helpers\Password::hash)
auth()->config("PASSWORD_VERIFY", null);

// use md5. We're still keeping support for md5 :-)
auth()->config("PASSWORD_VERIFY", Password::MD5);

// use custom method
auth()->config("PASSWORD_VERIFY", function ($password) {
  return Password::verify($password);


This allows you to change the password field name, maybe yours is passcode? This tells leaf to look for a user's password in that field. The example below tells leaf to search for passwords in the passcode column. (the default field is password)

auth()->config("PASSWORD_KEY", "passcode");


ID_KEY allows you to set your primary key name. For instance, you might have used _id instead of id. This setting allows you to quickly and effectively switch your key name.

auth()->config("ID_KEY", "_id");


This simply allows you to set the value for user ids on your own. This is done in order to add support for UUIDs in your registrations and not go with the default SQL increments.

auth()->config("USE_UUID", UUID::v4());


This is a boolean which determines whether to hide the id in the user object returned on login/register. Default is true.


This allows you to manually tell leaf auth that no password is required for authentication. When this is set to true, leaf auth will assume there is no password and act accordingly. If there is no password field set in the credentials passed into the login or register methods, leaf auth will automatically set this to true.


Just as the name implies, allows you to hide or show the password in the final results returned from auth. Default is true.


This is the error to show if there's an error with any parameter which isn't the password eg: username:

auth()->config("LOGIN_PARAMS_ERROR", "Username is incorrect!");

Default is Incorrect credentials!.


This is the error to show if there's an error with the password.

Default is Password is incorrect!.

auth()->config("LOGIN_PASSWORD_ERROR", "Password is incorrect!");


Use session based authentication instead of the default JWT based auth. Without this setting enbled, you can't use any of the session methods below. Default is false.


If true, a session will be created on a successful registration, else you it'll be created on login rather. Default is false.


The page route. Default is /auth/login.


The register page route. Default is /auth/register.


Logout route handler. Default is /auth/logout.


Home page route. Default is /home.


Add an auth token to the auth session? This allows you save a generated JWT to the session. You might want to use this if you want to extend your app into an API. Default is false.


How long the token can be used before it expires. Default is 1 day.


This is the secret key used to generate tokens for users on signup and register.

Leaf Auth Refactor 🔥

The leaf auth module has been broken up into subclasses for easier use and performance reasons. If you only use login and signup, there's no need to include a class with tons of features that you may not use.

This doesn't change the way leaf auth works as this was done for performance and maintainability reasons. You can still use the auth class just as done in Leaf 2, however, this has been optimized using static methods which means unnecessary code will not be run.

Auth Config has loaded