Skip to content

Commit 3ccddd6

Browse files
mychidarkomychidarko
committed
chore: update readme
1 parent 33400b8 commit 3ccddd6

File tree

1 file changed

+66
-65
lines changed

1 file changed

+66
-65
lines changed

‎README.md

+66-65
Original file line numberDiff line numberDiff line change
@@ -1,130 +1,131 @@
11
<!-- markdownlint-disable no-inline-html -->
22
<p align="center">
33
<br><br>
4-
<img src="https://leafphp.netlify.app/assets/img/leaf3-logo.png" height="100"/>
5-
<h1 align="center">Leaf Auth v2</h1>
4+
<img src="https://leafphp.dev/logo-circle.png" height="100"/>
5+
<h1 align="center">Leaf Auth</h1>
66
<br><br>
77
</p>
88

99
[![Latest Stable Version](https://poser.pugx.org/leafs/auth/v/stable)](https://packagist.org/packages/leafs/auth)
1010
[![Total Downloads](https://poser.pugx.org/leafs/auth/downloads)](https://packagist.org/packages/leafs/auth)
1111
[![License](https://poser.pugx.org/leafs/auth/license)](https://packagist.org/packages/leafs/auth)
1212

13-
Leaf auth is a simple but powerful module which comes with powerful functions for handling all your authentication needs.
14-
15-
v2 comes with tons of fixes, improvements and upgrades. Running on top of leaf db v2, it also has support for other database types like PostgreSQL, Sqlite and many more.
13+
Leaf provides a lightweight but very powerful authentication system to handle all the complexities of authentication in a few lines of code. We understand that authentication is a critical part of your application, so we've made it as simple and secure as possible.
1614

1715
## Installation
1816

19-
You can easily install Leaf using [Composer](https://getcomposer.org/).
17+
You can easily install Leaf Auth using the Leaf CLI:
2018

2119
```bash
22-
composer require leafs/auth
20+
leaf install auth
2321
```
2422

25-
Or with leaf db
23+
Or via composer:
2624

2725
```sh
28-
leaf install auth
26+
composer require leafs/auth
2927
```
3028

31-
## Basic Usage
32-
33-
After installing leaf auth, you need to connect to your database. v2 presents additional ways to achieve this.
29+
## Connecting to a database
3430

35-
### connect
36-
37-
The connect method allows you to pass in your database connection parameters directly to leaf auth.
31+
To do any kind of authentication, you need to connect to some kind of database which will store your users' data.
3832

3933
```php
40-
auth()->connect('127.0.0.1', 'dbname', 'username', 'password');
34+
auth()->connect([
35+
'dbtype' => '...',
36+
'charset' => '...',
37+
'port' => '...',
38+
'host' => '...',
39+
'dbname' => '...',
40+
'user' => '...',
41+
'password' => '...'
42+
]);
4143
```
4244

43-
### autoConnect
44-
45-
This method creates a database connection using your env variables.
45+
If you have an existing PDO connection, you can pass it to Leaf Auth:
4646

47-
```env
48-
DB_CONNECTION=mysql
49-
DB_HOST=127.0.0.1
50-
DB_PORT=3306
51-
DB_DATABASE=LEAF_DB_NAME
52-
DB_USERNAME=LEAF_DB_USERNAME
53-
DB_PASSWORD=
54-
```
47+
```php
48+
$db = new PDO('mysql:dbname=test;host=127.0.0.1', 'root', '');
5549

56-
And call `autoConnect` in your app.
50+
auth()->dbConnection($db);
5751

58-
```php
59-
auth()->autoConnect();
52+
// you can use leaf auth the same way you always have
6053
```
6154

62-
### db connection (v2 only)
55+
## Signing a user in
6356

64-
Leaf auth now allows you to directly pass a PDO connection into leaf auth. This allows you to share your connection with leaf auth and avoid multiple connections.
57+
To sign a user in, you can use the login() method. This method takes in an array of data you want to use to authenticate the user. This data is usually the user's email and password, but can be anything as long as the password field is present.
6558

6659
```php
67-
$auth = new Leaf\Auth;
68-
$auth->dbConnection($pdoConnecction);
60+
auth()->login([
61+
'email' => '[email protected]',
62+
'password' => 'password'
63+
]);
6964
```
7065

71-
This also means that you can share you leaf db v2 connection with leaf auth like this:
66+
## Signing a user up
67+
68+
To sign a user up is to create a new user account on your application. This is usually done by collecting the user's details and storing them in your database. You also need to validate the user's details to ensure they are correct and that they don't conflict with existing data.
69+
70+
Leaf allows you to do all this using the register() method. This method takes in an array of data you want to use to create the user.
7271

7372
```php
74-
$auth = new Leaf\Auth;
75-
$auth->dbConnection($db->connection());
73+
auth()->register([
74+
'username' => 'example',
75+
'email' => '[email protected]',
76+
'password' => 'password'
77+
]);
7678
```
7779

78-
### Leaf db (auth v2 + leaf 3 only)
79-
80-
If you are using leaf auth in a leaf 3 app, you will have access to the `auth` global as shown in some of the above connections. Along with this, if you already have a leaf db connection, you no longer need to explicitly connect to your database. Leaf auth searches for a leaf db instance and connects to it automatically.
80+
## Using Middleware
8181

82-
**Note that this only works in a leaf 3 app and only if you already have a leaf db connection.**
82+
Leaf Auth also provides a middleware that you can use to protect your routes. The auth middleware checks if a user is logged in and allows you to set a callback function to run if a user is not logged in.
8383

8484
```php
85-
<?php
86-
87-
db()->connect('127.0.0.1', 'dbname', 'username', 'password');
88-
89-
// you can use auth straight away without any connect
90-
auth()->login(...);
85+
auth()->middleware('auth.required', function () {
86+
response()->redirect('/login');
87+
});
9188
```
9289

93-
## 📚 Auth methods
90+
Once you have defined a callback for the middleware, you can use it in your routes like this:
9491

95-
After connecting your db, you can use any of the methods below.
96-
97-
WIP: This page will be updated
98-
99-
## ⚡️ Funtional Mode
92+
```php
93+
app()->get('/protected', ['middleware' => 'auth.required', function () {
94+
// this route is protected
95+
}]);
96+
97+
// or on a route group
98+
app()->group('/protected', ['middleware' => 'auth.required', function () {
99+
app()->get('/route', function () {
100+
// this route is protected
101+
});
102+
}]);
103+
```
100104

101-
When using leaf auth in a leaf 3 app, you will have access to the `auth`, `guard`, `hasAuth` and `sessionUser` globals.
105+
You can find the full documentation [here](https://leafphp.dev/docs/auth/protected-routes.html)
102106

103-
## 💬 Stay In Touch
107+
## Stay In Touch
104108

105109
- [Twitter](https://twitter.com/leafphp)
106110
- [Join the forum](https://github.com/leafsphp/leaf/discussions/37)
107111
- [Chat on discord](https://discord.com/invite/Pkrm9NJPE3)
108112

109-
## 📓 Learning Leaf 3
113+
## Learning Leaf PHP
110114

111115
- Leaf has a very easy to understand [documentation](https://leafphp.dev) which contains information on all operations in Leaf.
112116
- You can also check out our [youtube channel](https://www.youtube.com/channel/UCllE-GsYy10RkxBUK0HIffw) which has video tutorials on different topics
113-
- We are also working on codelabs which will bring hands-on tutorials you can follow and contribute to.
117+
- You can also learn from [codelabs](https://leafphp.dev/codelabs/) and contribute as well.
114118

115-
## 😇 Contributing
119+
## Contributing
116120

117121
We are glad to have you. All contributions are welcome! To get started, familiarize yourself with our [contribution guide](https://leafphp.dev/community/contributing.html) and you'll be ready to make your first pull request 🚀.
118122

119123
To report a security vulnerability, you can reach out to [@mychidarko](https://twitter.com/mychidarko) or [@leafphp](https://twitter.com/leafphp) on twitter. We will coordinate the fix and eventually commit the solution in this project.
120124

121-
## 🤩 Sponsoring Leaf
122-
123-
Your cash contributions go a long way to help us make Leaf even better for you. You can sponsor Leaf and any of our packages on [open collective](https://opencollective.com/leaf) or check the [contribution page](https://leafphp.dev/support/) for a list of ways to contribute.
125+
## Sponsoring Leaf
124126

125-
And to all our existing cash/code contributors, we love you all ❤️
127+
We are committed to keeping Leaf open-source and free, but maintaining and developing new features now requires significant time and resources. As the project has grown, so have the costs, which have been mostly covered by the team. To sustain and grow Leaf, we need your help to support full-time maintainers.
126128

127-
## 🤯 Links/Projects
129+
You can sponsor Leaf and any of our packages on [open collective](https://opencollective.com/leaf) or check the [contribution page](https://leafphp.dev/support/) for a list of ways to contribute.
128130

129-
- [Leaf Docs](https://leafphp.dev)
130-
- [Leaf CLI Docs](https://cli.leafphp.dev)
131+
And to all our [existing cash/code contributors](https://leafphp.dev#sponsors), we love you all ❤️

0 commit comments

Comments
 (0)