Authentication #

Numerous web applications offer their users a means to authenticate and access the application by "logging in." Adding this functionality to web applications can be a challenging and potentially dangerous task. For this reason, Leaf provides a lightweight but very powerful authentication system known as Leaf Auth.

Leaf Auth gives you clean and simple functions to handle complex authentication flows in a few lines of code. It is customizable to the core and allows for a bunch of configuration options that determine how it handles authentication in general.

You can still handle authentication without using Leaf Auth, however, Leaf Auth is a more secure and reliable way to handle authentication in your apps.

Installing Leaf Auth #

You can install Leaf Auth using the Leaf CLI:

leaf install auth

Or with composer:

composer require leafs/auth

From there, you can link your database and start writing some awesome queries.

Database Considerations #

Leaf Auth doesn't give you any structure for your database, with that, you can structure your database in any way you prefer. However, there are some things you should note:

Database primary key #

By default, Leaf Auth assumes that your database primary key is id. If however, you have a database where you are using another field, say admin_id as the primary key, you will need to tell Leaf Auth the name of your primary key. You can do this using the ID_KEY config:

$auth = new Leaf\Auth;
$auth->config('ID_KEY', 'admin_id');

...

auth()->config('ID_KEY', 'admin_id');

Database table #

By default, Leaf Auth assumes that you will save your users in a database table named users, this might however not be the case for your application. If you want to use a different table, you can configure Leaf Auth using DB_TABLE:

$auth = new Leaf\Auth;
$auth->config('DB_TABLE', 'admins');

...

auth()->config('DB_TABLE', 'admins');

Database Connection #

After installing leaf auth, you would need to connect to a database. Leaf auth will search for users and add/update users in this database when a login/register or update operation is called. There are a couple of ways to connect to a database with leaf auth.

Manual Connection #

Leaf Auth provides a connect() method that allows you to connect to your database by passing in your database connection parameters. This is the most basic and straightforward way to connect to your database.

$auth = new \Leaf\Auth;

// syntax
$auth->connect(
  $host = '',
  string $dbname = '',
  string $user = '',
  string $password = ''
);

// example
$auth->connect('127.0.0.1', 'dbname', 'root', '');

// syntax
auth()->connect(
  $host = '',
  string $dbname = '',
  string $user = '',
  string $password = '',
  string $dbtype = ''
);

// example
auth()->connect('127.0.0.1', 'dbname', 'root', '', 'mysql');

Auto Connect #

Leaf Auth comes with an autoConnect() method that allows you to connect to your database using your environment variables. Most MVC frameworks and other libraries rely on a .env file for a lot of configuration including the database. With autoConnect, you can directly pick up these configs and create a connection from them.

example env:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=LeafMVC
DB_USERNAME=root
DB_PASSWORD=

Based on the example above, you can connect to your database using:

$auth = new Leaf\Auth;
$auth->autoConnect();

auth()->autoConnect();

PDO connection #

Leaf Auth also allows you to skip the entire connection process and share an existing PDO instance with leaf db. This allows you to gradually rewrite your existing apps with Leaf Auth without having multiple db connections and doing so at your own pace.

$db = new PDO('mysql:dbname=test;host=127.0.0.1', 'root', '');
$auth = new Leaf\Auth;

$auth->dbConnection($db);

// you can use leaf auth the same way you always have

$db = new PDO('mysql:dbname=test;host=127.0.0.1', 'root', '');

auth()->dbConnection($db);

// you can use leaf auth the same way you always have

Leaf Db has been rewritten based on PDO, this also means that you can pass your leaf db connection into leaf auth directly.

$auth->dbConnection($db->connection());

auth()->dbConnection(db()->connection());

<?php

db()->connect('127.0.0.1', 'dbname', 'username', 'password');

// you can use auth straight away without any connect
auth()->login(...);

<?php

require __DIR__ . "/vendor/autoload.php";

auth()->autoConnect();

app()->get("/", function () {
  // auth can be used here
  // auth()->...
});

app()->run();

Next Steps #