Skip to content

Commit 552bfe5

Browse files
mychidarkomychidarko
committed
feat: update MVC docs
1 parent ea113fc commit 552bfe5

File tree

6 files changed

+417
-183
lines changed

6 files changed

+417
-183
lines changed

‎src/docs/auth/index.md‎

Lines changed: 0 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -91,34 +91,6 @@ auth()->dbConnection($db);
9191

9292
:::
9393

94-
## Auth + Leaf MVC
95-
96-
If you are using Leaf MVC, you can set up Leaf Auth to work with your default database connection by heading over to the `public/index.php` file and uncommenting the line that connects to the database:
97-
98-
```php
99-
/*
100-
|--------------------------------------------------------------------------
101-
| Sync Leaf Db with ORM and connect
102-
|--------------------------------------------------------------------------
103-
|
104-
| Sync Leaf Db with ORM and connect to the database
105-
| This allows you to use Leaf Db without having
106-
| to initialize it in your controllers.
107-
|
108-
| If you want to use a different connection from those
109-
| used in your models, you can remove the line below and
110-
| add your own connection with:
111-
| db()->connect(...)
112-
|
113-
| **Uncomment the line below to use Leaf Db**
114-
| **You don't need this line to use Leaf Auth**
115-
*/
116-
// \Leaf\Database::initDb(); [!code --]
117-
\Leaf\Database::initDb(); // [!code ++]
118-
```
119-
120-
That's all you need to do. Leaf Auth will automatically connect to your database using the details in your environment file. The auth configuration for your project can be found in the `config/auth.php` file. You can edit this file to change the configuration of Leaf Auth.
121-
12294
## Database Considerations
12395

12496
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:

‎src/docs/auth/mvc.md‎

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,245 @@ prev: false
55

66
# Auth in Leaf MVC
77

8+
Leaf Auth comes with everything you need to authenticate users, including login, registration, account verification and more. You can add it to your Leaf MVC project using the Leaf CLI or composer:
9+
10+
::: code-group
11+
12+
```bash:no-line-numbers [Leaf CLI]
13+
leaf install auth
14+
```
15+
16+
```bash:no-line-numbers [Composer]
17+
composer require leafs/auth
18+
```
19+
20+
:::
21+
22+
Leaf Auth will automatically pick up your default database connection and will work with it, so you can immediately start working with it without any config. Checkout the following pages to authenticate users:
23+
24+
- [Login](/docs/auth/login)
25+
- [Register](/docs/auth/register)
26+
- [User Data](/docs/auth/user)
27+
- [Protected routes](/docs/auth/protected-routes)
28+
- [Roles & Permissions](/docs/auth/permissions)
29+
30+
## Configuring Auth
31+
32+
Although Leaf Auth works out of the box for most applications, you may have some specific requirements that you need to configure. You can configure Leaf Auth using your `.env` file:
33+
34+
```txt [.env]
35+
AUTH_DB_TABLE=users
36+
AUTH_DB_ID=id
37+
AUTH_TIMESTAMPS=true
38+
AUTH_TIMESTAMPS_FORMAT='YYYY-MM-DD HH:mm:ss'
39+
AUTH_SESSIONS=true
40+
```
41+
42+
These are options for the database table to store users, the primary key of the table, whether to use timestamps and the format of the timestamps, and whether to use sessions. If you need to configure something else, you will need to publish the entire auth config using the MVC CLI:
43+
44+
```bash:no-line-numbers
45+
php leaf config:publish auth
46+
```
47+
48+
This will generate a `config/auth.php` file with the default auth config. You can then edit this file to suit your needs.
49+
50+
```php
51+
<?php
52+
53+
use Leaf\Helpers\Password;
54+
55+
return [
56+
/*
57+
|--------------------------------------------------------------------------
58+
| Database table
59+
|--------------------------------------------------------------------------
60+
|
61+
| This is the table that leaf auth will perform authentication
62+
| checks on and edit/retrieve users from.
63+
|
64+
*/
65+
'db.table' => _env('AUTH_DB_TABLE', 'users'),
66+
67+
/*
68+
|--------------------------------------------------------------------------
69+
| ID Key
70+
|--------------------------------------------------------------------------
71+
|
72+
| Set your primary key name. For instance, you might have used id_user instead of id.
73+
| This setting allows you to quickly switch your key name
74+
|
75+
*/
76+
'id.key' => _env('AUTH_DB_ID', 'id'),
77+
78+
/*
79+
|--------------------------------------------------------------------------
80+
| Generate timestamps
81+
|--------------------------------------------------------------------------
82+
|
83+
| Automatically generate created_at/updated_at timestamps for register
84+
| and update methods
85+
|
86+
*/
87+
'timestamps' => true,
88+
89+
/*
90+
|--------------------------------------------------------------------------
91+
| Set timestamps format
92+
|--------------------------------------------------------------------------
93+
|
94+
| Use this property to specify the format that you want your timestamps to be saved in.
95+
| Be aware that auth uses the leafs/date module, so the accepted formats are listed in the leafs/date documentation
96+
|
97+
*/
98+
'timestamps.format' => 'YYYY-MM-DD HH:mm:ss',
99+
100+
/*
101+
|--------------------------------------------------------------------------
102+
| Encode password
103+
|--------------------------------------------------------------------------
104+
|
105+
| Password encode is run when leaf wants to encode passwords on register
106+
| This exact method is used by default in Leaf, so you can set it to null
107+
| if you want to.
108+
|
109+
| You can set your own implementation instead of Password::hash
110+
|
111+
*/
112+
'password.encode' => function ($password) {
113+
return Password::hash($password);
114+
},
115+
116+
/*
117+
|--------------------------------------------------------------------------
118+
| Verify Password
119+
|--------------------------------------------------------------------------
120+
|
121+
| This function is run to verify the password. This implementation is done
122+
| by default, so you can set it to null, and it will still work fine.
123+
|
124+
| You can add your own implementation instead of Password::verify
125+
|
126+
*/
127+
'password.verify' => function ($password, $hashedPassword) {
128+
return Password::verify($password, $hashedPassword);
129+
},
130+
131+
/*
132+
|--------------------------------------------------------------------------
133+
| Password Key
134+
|--------------------------------------------------------------------------
135+
|
136+
| The default password key. Leaf will expect this key to hold passwords
137+
| in your database.
138+
|
139+
*/
140+
'password.key' => 'password',
141+
142+
/*
143+
|--------------------------------------------------------------------------
144+
| Unique fields
145+
|--------------------------------------------------------------------------
146+
|
147+
| This is a list of items that should be unique to each user eg: email
148+
|
149+
*/
150+
'unique' => ['email'],
151+
152+
/*
153+
|--------------------------------------------------------------------------
154+
| Hidden fields
155+
|--------------------------------------------------------------------------
156+
|
157+
| This is a list of items that should be hidden when
158+
| a user object is returned. You should use the field name
159+
| exactly as it is in the database.
160+
|
161+
*/
162+
'hidden' => ['field.id', 'field.password'],
163+
164+
/*
165+
|--------------------------------------------------------------------------
166+
| Use session
167+
|--------------------------------------------------------------------------
168+
|
169+
| Use session based authentication instead of the default JWT based auth.
170+
|
171+
*/
172+
'session' => _env('AUTH_SESSION', true),
173+
174+
/*
175+
|--------------------------------------------------------------------------
176+
| Session lifetime
177+
|--------------------------------------------------------------------------
178+
|
179+
| Set the lifetime of the session. After this time, the session will expire and the user will have to login again.
180+
| You can either use '1 day' format or as an integer: 86400
181+
| You can also set session.lifetime to 0 to disable session expiration.
182+
|
183+
*/
184+
'session.lifetime' => 60 * 60 * 24,
185+
186+
/*
187+
|--------------------------------------------------------------------------
188+
| SESSION COOKIE PARAMS
189+
|--------------------------------------------------------------------------
190+
|
191+
| Set the session cookie params
192+
| Read more: https://www.php.net/manual/en/function.session-set-cookie-params.php
193+
|
194+
| secure: cookie should only be sent over secure connections (https)
195+
| httponly: cookie should only be accessible through HTTP requests
196+
| samesite: cookie should be sent with "SameSite" directives :-
197+
| Possible values for samesite: 'strict', 'lax', 'none' or null
198+
|
199+
|
200+
*/
201+
'session.cookie' => ['secure' => false, 'httponly' => true, 'samesite' => 'lax'],
202+
203+
/*
204+
|--------------------------------------------------------------------------
205+
| JWT Lifetime
206+
|--------------------------------------------------------------------------
207+
|
208+
| How long should JWT be valid for?
209+
|
210+
*/
211+
'token.lifetime' => 60 * 60 * 24 * 365,
212+
213+
/*
214+
|--------------------------------------------------------------------------
215+
| JWT Token Secret
216+
|--------------------------------------------------------------------------
217+
|
218+
| Secret string to encode JWT
219+
|
220+
*/
221+
'token.secret' => _env('AUTH_TOKEN_SECRET', '@leaf$MVC*JWT#AUTH.Secret'),
222+
223+
/*
224+
|--------------------------------------------------------------------------
225+
| Login params error
226+
|--------------------------------------------------------------------------
227+
|
228+
| Error to show when the login params aren't found in db
229+
|
230+
*/
231+
'messages.loginParamsError' => 'Incorrect credentials!',
232+
233+
/*
234+
|--------------------------------------------------------------------------
235+
| Password error
236+
|--------------------------------------------------------------------------
237+
|
238+
| Error to show when the login password is wrong
239+
|
240+
*/
241+
'messages.loginPasswordError' => 'Password is incorrect!',
242+
];
243+
```
244+
245+
While this is quite lengthy, it offers fine-grained control over how Leaf Auth works in your application.
246+
8247
## What to read next
9248

10249
Now that you have built a simple pre-launch page, the next step is to get you familiar with the basics of building a full-stack application with Leaf. So you can build and launch your next big idea *fast*.

0 commit comments

Comments
 (0)