Skip to content

Commit e41b531

Browse files
lonnieezelllonnieezell
authored
Merge pull request #255 from codeigniter4/quick-start-docs
Added new quickstart docs.
2 parents ac7f1de + 3f443a8 commit e41b531

11 files changed

Lines changed: 383 additions & 13 deletions

‎README.md‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -6,28 +6,28 @@
66
[![Coverage Status](https://coveralls.io/repos/github/codeigniter4/shield/badge.svg?branch=develop)](https://coveralls.io/github/codeigniter4/shield?branch=develop)
77

88
Shield is an authentication and authorization framework for CodeIgniter 4. While it does provide a base set of tools
9-
that are commonly used in websites, it is designed to be flexible and easily customizable.
9+
that are commonly used in websites, it is designed to be flexible and easily customizable.
1010

11-
The primary goals for Shield are:
11+
The primary goals for Shield are:
1212
1. It must be very flexible and allow developers to extend/override almost any part of it.
1313
2. It must have security at its core. It is an auth lib after all.
1414
3. To cover many auth needs right out of the box, but be simple to add additional functionality to.
1515

1616
## Authentication Methods
1717

18-
Shield provides two primary methods of authentication out of the box:
18+
Shield provides two primary methods of authentication out of the box:
1919

20-
**Session-based**
20+
**Session-based**
2121

2222
This is your typical email/username/password system you see everywhere. It includes a secure "remember me" functionality.
23-
This can be used for standard web applications, as well as for single page applications. Includes full controllers and
23+
This can be used for standard web applications, as well as for single page applications. Includes full controllers and
2424
basic views for all standard functionality, like registration, login, forgot password, etc.
2525

26-
**Personal Access Codes**
26+
**Personal Access Codes**
2727

2828
These are much like the access codes that GitHub uses, where they are unique to a single user, and a single user
29-
can have more than one. This can be used for API authentication of third-party users, and even for allowing
30-
access for a mobile application that you build.
29+
can have more than one. This can be used for API authentication of third-party users, and even for allowing
30+
access for a mobile application that you build.
3131

3232
## Getting Started
3333

@@ -45,11 +45,11 @@ Installation is done through Composer.
4545

4646
> composer require codeigniter4/shield
4747

48-
See the [docs](docs) folder more specific instructions on installation and usage recommendations.
48+
See the [docs](docs/index.md) for more specific instructions on installation and usage recommendations.
4949

5050
## Contributing
5151

52-
Shield does accept and encourage contributions from the community in any shape. It doesn't matter
52+
Shield does accept and encourage contributions from the community in any shape. It doesn't matter
5353
whether you can code, write documentation, or help find bugs, all contributions are welcome.
5454

5555
## License
@@ -58,8 +58,8 @@ This project is licensed under the MIT License - see the [LICENSE.md](LICENSE) f
5858

5959
## Acknowledgements
6060

61-
Every open-source project depends on it's contributors to be a success. The following users have
62-
contributed in one manner or another in making Shield:
61+
Every open-source project depends on it's contributors to be a success. The following users have
62+
contributed in one manner or another in making Shield:
6363

6464
<a href="https://github.com/codeigniter4/shield/graphs/contributors">
6565
<img src="https://contrib.rocks/image?repo=codeigniter4/shield" />
@@ -68,7 +68,7 @@ contributed in one manner or another in making Shield:
6868
Made with [contrib.rocks](https://contrib.rocks).
6969

7070
The following articles/sites have been fundamental in shaping the security and best practices used
71-
within this library, in no particular order:
71+
within this library, in no particular order:
7272

7373
- [Google Cloud: 13 best practices for user account, authentication, and password management, 2021 edition](https://cloud.google.com/blog/products/identity-security/account-authentication-and-password-management-best-practices)
7474
- [NIST Digital Identity Guidelines](https://pages.nist.gov/800-63-3/sp800-63b.html)

docs/3 - auth_actions.md renamed to docs/auth_actions.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Authentication Actions
22

3+
- [Authentication Actions](#authentication-actions)
4+
- [Configuring Actions](#configuring-actions)
5+
- [Defining New Actions](#defining-new-actions)
6+
37
Authentication Actions are a way to group actions that can happen after login or registration.
48
Shield ships with two actions you can use, and makes it simple for you to define your own.
59

docs/2 - authentication.md renamed to docs/authentication.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,26 @@
11
# Authentication
22

3+
- [Authentication](#authentication)
4+
- [Available Authenticators](#available-authenticators)
5+
- [Auth Helper](#auth-helper)
6+
- [Authenticator Responses](#authenticator-responses)
7+
- [isOK()](#isok)
8+
- [reason()](#reason)
9+
- [extraInfo()](#extrainfo)
10+
- [Session Authenticator](#session-authenticator)
11+
- [attempt()](#attempt)
12+
- [check()](#check)
13+
- [loggedIn()](#loggedin)
14+
- [logout()](#logout)
15+
- [forget()](#forget)
16+
- [Access Token Authenticator](#access-token-authenticator)
17+
- [Access Token/API Authentication](#access-tokenapi-authentication)
18+
- [Generating Access Tokens](#generating-access-tokens)
19+
- [Revoking Access Tokens](#revoking-access-tokens)
20+
- [Retrieving Access Tokens](#retrieving-access-tokens)
21+
- [Access Token Lifetime](#access-token-lifetime)
22+
- [Access Token Scopes](#access-token-scopes)
23+
324
Authentication is the process of determining that a visitor actually belongs to your website,
425
and identifying them. Shield provides a flexible and secure authentication system for your
526
web apps and APIs.

docs/4 - authorization.md renamed to docs/authorization.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,22 @@
11
# Authorization
22

3+
- [Authorization](#authorization)
4+
- [Defining Available Groups](#defining-available-groups)
5+
- [Default User Group](#default-user-group)
6+
- [Defining Available Permissions](#defining-available-permissions)
7+
- [Assigning Permissions to Groups](#assigning-permissions-to-groups)
8+
- [Authorizing Users](#authorizing-users)
9+
- [can()](#can)
10+
- [inGroup()](#ingroup)
11+
- [Managing User Permissions](#managing-user-permissions)
12+
- [addPermission()](#addpermission)
13+
- [removePermission()](#removepermission)
14+
- [syncPermissions()](#syncpermissions)
15+
- [Managing User Groups](#managing-user-groups)
16+
- [addGroup()](#addgroup)
17+
- [removeGroup()](#removegroup)
18+
- [syncGroups()](#syncgroups)
19+
320
Authorization happens once a user has been identified through authentication. It is the process of
421
determining what actions a user is allowed to do within your site.
522

docs/1 - concepts.md renamed to docs/concepts.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,13 @@
22

33
This document covers some of the base concepts used throughout the library.
44

5+
- [Shield Concepts](#shield-concepts)
6+
- [Repository State](#repository-state)
7+
- [Settings](#settings)
8+
- [User Providers](#user-providers)
9+
- [User Identities](#user-identities)
10+
- [Password Validators](#password-validators)
11+
512
## Repository State
613

714
Shield is designed so that the initial setup of your application can all happen in code with nothing required to be
@@ -25,6 +32,7 @@ The only requirement is that your new class MUST extend the provided `UserModel`
2532
public $userProvider = 'CodeIgniter\Shield\Models\UserModel';
2633
```
2734

35+
<a name="identities" />
2836
## User Identities
2937

3038
User accounts are stored separately from the information needed to identify that user. These identifying pieces of data are

docs/7 - customization.md renamed to docs/customization.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
# Customizing Shield
22

3+
- [Customizing Shield](#customizing-shield)
4+
- [Route Configuration](#route-configuration)
5+
- [Custom Redirect URLs](#custom-redirect-urls)
6+
- [Extending the Controllers](#extending-the-controllers)
7+
38
## Route Configuration
49

510
If you need to customize how any of the auth features are handled, you will likely need to update the routes to point to the correct controllers. You can still use the `service('auth')->routes()` helper, but you will need to pass the `except` option with a list of routes to customize:

docs/5 - events.md renamed to docs/events.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,14 @@
22

33
Shield fires off several events during the lifecycle of the application that your code can tap into.
44

5+
- [Events](#events)
6+
- [Responding to Events](#responding-to-events)
7+
- [Event List](#event-list)
8+
- [register](#register)
9+
- [login](#login)
10+
- [failedLogin](#failedlogin)
11+
- [logout](#logout)
12+
513
## Responding to Events
614

715
When you want to respond to an event that Shield publishes, you will need to add it to your `app/Config/Events.php`

‎docs/index.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Shield Documentation
2+
3+
* [Installation Guide](install.md)
4+
* [Concepts You Need To Know](concepts.md)
5+
* [Quick Start Guide](quickstart.md)
6+
* [Authentication](authentication.md)
7+
* [Authorization](authorization.md)
8+
* [Auth Actions](auth_actions.md)
9+
* [Events](events.md)
10+
* [Testing](testing.md)
11+
* [Customization](customization.md)

docs/0 - install.md renamed to docs/install.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,15 @@
11
# Installation
22

3+
- [Installation](#installation)
4+
- [Troubleshooting](#troubleshooting)
5+
- [IMPORTANT: composer error](#important-composer-error)
6+
- [Note: migration error](#note-migration-error)
7+
- [Initial Setup](#initial-setup)
8+
- [Command Setup](#command-setup)
9+
- [Manual Setup](#manual-setup)
10+
- [Controller Filters](#controller-filters)
11+
- [Rate Limiting](#rate-limiting)
12+
313
These instructions assume that you have already [installed the CodeIgniter 4 app starter](https://codeigniter.com/user_guide/installation/installing_composer.html) as the basis for your new project, set up your `.env` file, and created a database that you can access via the Spark CLI script.
414

515
Installation is done through [Composer](https://getcomposer.org). The example assumes you have it installed globally.
@@ -11,6 +21,8 @@ If you have it installed as a phar, or othewise you will need to adjust the way
1121

1222
---
1323

24+
### Troubleshooting
25+
1426
#### IMPORTANT: composer error
1527

1628
If you get the following error:

0 commit comments

Comments
 (0)