Skip to content

Commit

Permalink
Split readme into separate files
Browse files Browse the repository at this point in the history
  • Loading branch information
@glewe
glewe committed May 8, 2023
1 parent 2ae8271 commit 1a5c121
Show file tree
Hide file tree
Showing 3 changed files with 373 additions and 297 deletions.
306 changes: 9 additions & 297 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

[![PHP](https://img.shields.io/badge/Language-PHP-8892BF.svg)](https://www.php.net/)
[![Bootstrap 5](https://img.shields.io/badge/Styles-Bootstrap%205-7952b3.svg)](https://www.getbootstrap.com/)
[![Font Awesome](https://img.shields.io/badge/Icons-Font%20Awesome%206-1e7cd6.svg)](https://www.fontawesome.com/)
[![Bootstrap Icons](https://img.shields.io/badge/Icons-Bootstrap%20Icons-7952b3.svg)](https://icons.getbootstrap.com/)

CI4-Auth is a user, group, role and permission management library for Codeigniter 4.

Expand All @@ -14,317 +14,29 @@ quite large. I decided to build CI4-Auth based on Myth-Auth, changing and adding

## Requirements

- PHP 7.4+, 8.0+
- PHP 8.1+
- CodeIgniter 4.0+
- [RobThree TwoFactorAuth](http://github.com/RobThree/TwoFactorAuth)

## Features

- Core Myth-Auth features
- Role objects are consistently called "role" in the code (e.g. tables, variables, classes)
- Added "Groups" as an addl. object, functioning just like roles
- Separated user controller functions from the Auth Controller
- 2FA based on RobThree's TwoFactorAuth
- Added views to manage users, groups, roles and permissions
- Added Bootstrap 5 and Font Awesome 5 support
- Added views to setup 2FA and for 2FA PIN login
- Added database seeders to create sample data
- Language support for English, German and Spanish
- Bootstrap 5 (CDN)
- Font Awesome 6 (CDN)
- Bootstrap Icons (CDN)
- Google Font "Open Sans" (CDN)

## Installation
## Documentation

### Install Codeigniter

Install an appstarter project with Codigniter 4 as described [here](https://codeigniter.com/user_guide/installation/installing_composer.html).

Make sure your app and database is configured right and runs fine showing the Codigniter 4 welcome page.

Also, check the $baseUrl setting in **app/Config/App.php** points to your public directory to make sure that the navbar links work.

### Download CI4-Auth

Download the CI4-Auth archive from this repo here.

### Copy CI4-Auth to your ThirdParty folder

_Note: CI4-Auth is not available as a Composer package yet. It works from your ThirdParty folder._

Unzip the CI4-Auth archive and copy the 'lewe' directory to your **\app\ThirdParty** folder in your Codeigniter project.
You should see this tree section then:

```
project-root
- app
- ThirdParty
- lewe
- ci4-auth
- src
```

### Configuration

1. Add the Psr4 path in your **app/Config/Autoload.php** file as follows:

```php
public $psr4 = [
APP_NAMESPACE => APPPATH, // For custom app namespace
'Config' => APPPATH . 'Config',
'CI4\Auth' => APPPATH . 'ThirdParty/lewe/ci4-auth/src',
];
```

2. Edit **app/Config/Validation.php** and add the following value to the ruleSets array:

```php
public $ruleSets = [
Rules::class,
FormatRules::class,
FileRules::class,
CreditCardRules::class,
\CI4\Auth\Authentication\Passwords\ValidationRules::class
];
```

3. The "Remember Me" functionality is turned off by default. It can be turned on by setting the
`$allowRemembering` variable to `true` in **lewe/ci4-auth/src/Config/Auth.php**.

4. Edit **app/Config/Email.php** and verify that `fromName` and `fromEmail` are set as they are used when sending
emails for password resets, etc.

### Routes

The CI4-Auth routes are defined in **lewe/ci4-auth/src/Config/Routes.php**. Copy the routes group from there to your
**app/Config/Routes.php** file, right after the 'Route Definitions' header comment.

```php
/*
* --------------------------------------------------------------------
* Route Definitions
* --------------------------------------------------------------------
*/
//
// CI4-Auth Routes
//
$routes->group('', ['namespace' => 'CI4\Auth\Controllers'], function ($routes) {

// If you want to use group, login, permission or role filters in your route
// definitions, you need to add the filter aliases to your Config/Filters.php file.
// (see CI4-Auth readme).
//
// Sample routes with filters:
// $routes->match(['get', 'post'], 'roles', 'RoleController::index', ['filter' => 'group:Disney']);
// $routes->match(['get', 'post'], 'roles', 'RoleController::index', ['filter' => 'login']);
// $routes->match(['get', 'post'], 'roles', 'RoleController::index', ['filter' => 'permission:View Roles']);
// $routes->match(['get', 'post'], 'roles', 'RoleController::index', ['filter' => 'role:Administrator']);

$routes->get('/', 'AuthController::welcome');
$routes->get('/error_auth', 'AuthController::error');

...

});
```
### Filters

Filters allow you to restrict access to routes based on conditions, e.g. a permission or role membership.

CI4-Auth comes with four filter classes: `Group`, `Login`, `Permission` and `Role`. They reside in `lewe/ci4-auth/src/Filters/`.
You can use those filters in your route specifications. The filter is checked before the route is executed. In the
following example, the user must hold the 'Administrator' role to open the route:

```php
$routes->match(['get', 'post'], 'roles', 'RoleController::index', ['filter' => 'role:Administrator']);
```
You can also add several filters like so:

```php
$routes->match(['get', 'post'], 'roles', 'RoleController::index', ['filter' => 'role:Administrator', 'filter' => 'group:Admins']);
```
You must register the aliases for those filters in your **app/Config/Filter.php** file:

```php
...
use CI4\Auth\Filters\GroupFilter;
use CI4\Auth\Filters\LoginFilter;
use CI4\Auth\Filters\PermissionFilter;
use CI4\Auth\Filters\RoleFilter;

class Filters extends BaseConfig
{
/**
* Configures aliases for Filter classes to
* make reading things nicer and simpler.
*/
public array $aliases = [
...
'group' => GroupFilter::class,
'login' => LoginFilter::class,
'permission' => PermissionFilter::class,
'role' => RoleFilter::class,
];
```
### Views

The views that come with CI4-Auth are based on [Bootstrap 5](http://getbootstrap.com/) and [Font Awesome 6](https://fontawesome.com/).

If you like to use your own view you can override them editing the `$views` array in
**lewe/ci4-auth/src/Config/Auth.php**:

```php
public $views = [

// Welcome page
'welcome' => 'CI4\Auth\Views\welcome',

// Error page
'error_auth' => 'CI4\Auth\Views\error_auth',

// Auth
'login' => 'CI4\Auth\Views\auth\login',
'register' => 'CI4\Auth\Views\auth\register',
'forgot' => 'CI4\Auth\Views\auth\forgot',
'reset' => 'CI4\Auth\Views\auth\reset',

// Groups
'groups' => 'CI4\Auth\Views\groups\list',
'groupsCreate' => 'CI4\Auth\Views\groups\create',
'groupsEdit' => 'CI4\Auth\Views\groups\edit',

// Permissions
'permissions' => 'CI4\Auth\Views\permissions\list',
'permissionsCreate' => 'CI4\Auth\Views\permissions\create',
'permissionsEdit' => 'CI4\Auth\Views\permissions\edit',

// Roles
'roles' => 'CI4\Auth\Views\roles\list',
'rolesCreate' => 'CI4\Auth\Views\roles\create',
'rolesEdit' => 'CI4\Auth\Views\roles\edit',

// Users
'users' => 'CI4\Auth\Views\users\list',
'usersCreate' => 'CI4\Auth\Views\users\create',
'usersEdit' => 'CI4\Auth\Views\users\edit',

// Emails
'emailForgot' => 'CI4\Auth\Views\emails\forgot',
'emailActivation' => 'CI4\Auth\Views\emails\activation',
];
```

### Base Controller

In ***app/Controllers/BaseController.php** add 'auth', 'bs5' and 'session' to the $helpers array:

```php
/**
* An array of helpers to be loaded automatically upon class instantiation.
* These helpers will be available to all other controllers that extend
* BaseController.
*
* @var array
*/
protected $helpers = ['auth', 'bs5', 'session'];
```

### Passing custom config to Views

In case you have a custom configuration that you want to pass to your views (e.g. theme settings, language, etc.), the \_render() function of each CI4-Auth controller passes a variable called `$myConfig` to the view
if it exists. It is assumed that you set this variable in your BaseController.

### Database Migration

Assuming that your database is setup correctly but still empty you need to run the migrations now.

Copy the file **lewe/ci4-auth/src/Database/Migrations/..._create_auth_tables.php** to
**app/Database/Migrations**. Then run the command:

> php spark migrate

### Database Seeding

Assuming that the migrations have been completed successfully, you can run the seeders now to create the CI4-Auth sample data.

Copy the files **lewe/ci4-auth/src/Database/Seeds/\*.php** to **app/Database/Seeds**.
Then run the following command:

> php spark db:seed CI4AuthSeeder

All users created by the seed will have the password `Qwer!1234`.

### Run Application

Start your browser and navigate to your public directory. Use the menu to check out the views that come with
CI4-Auth.

## Services

The Services did not change and are from the Myth-Auth core. See there for their documentation.

## Helper Functions (Auth)

In addition to the helper functions that come with Myth-Auth, CI4-Auth provides these:

**dnd()**

- Function: Dump'n'Die. Returns a preformatted output of objects and variables.
- Parameters: Variable/Object, Switch to die after output or not
- Returns: Preformatted output

**has_permission()**

- Function: Checks whether the current user has the passed permission.
- Parameters: Permission ID
- Returns: `true` or `false`

**in_groups()**

- Function: Checks whether the current user is in at least one of the passed groups.
- Parameters: Group IDs or names (single item or array of items)
- Returns: `true` or `false`
- _Note: This is not the same helper as in Myth-Auth since Myth-Auth is inconcistent in
using the terms 'group' and 'role'._

**in_roles()**

- Function: Checks whether the current user is in at least one of the passed roles.
- Parameters: Role IDs or names (single item or array of items).
- Returns: `true` or `false`
- _Note: This is comparable to the in_groups() helper function in Myth-Auth._

## Helper Functions (Bootstrap 5)

In order to create Bootstrap objects quicker and to avoid duplicating code in views, these helper functions are
provided:

**bs5_alert()**

- Function: Creates a Bootstrap 5 alert box.
- Parameters: Array with alert box details.
- Returns: HTML

**bs5_cardheader()**

- Function: Creates a Bootstrap card header.
- Parameters: Array with card header details.
- Returns: HTML

**bs5_formrow()**

- Function: Creates a two-column form field div (text, email, select, password).
- Parameters: Array with form field details.
- Returns: HTML

**bs5_modal()**

- Function: Creates a modal dialog.
- Parameters: Array with modal dialog details.
- Returns: HTML

**bs5_searchform()**

- Function: Creates a search form field.
- Parameters: Array with search form details.
- Returns: HTML
- [Installation](docs/installation.cmd)
- [Helpers](docs/helpers.cmd)

## Disclaimer

Expand Down
Loading

0 comments on commit 1a5c121

Please sign in to comment.