Upgrade v1.10.0 (#13)

* v1.10.0

* Upgrade v1.10.0

* Optimize space

* Optimize description

.vuepress/config/sidebar/en.ts

@@ -105,14 +105,6 @@ export function getEnSidebar(): SidebarConfigArray {
           text: "Artisan Console",
           link: "/digging-deeper/artisan-console",
         },
-        {
-          text: "Authentication",
-          link: "/digging-deeper/authentication",
-        },
-        {
-          text: "Authorization",
-          link: "/digging-deeper/authorization",
-        },
         {
           text: "Cache",
           link: "/digging-deeper/cache",
@@ -143,6 +135,28 @@ export function getEnSidebar(): SidebarConfigArray {
         },
       ],
     },
+    {
+      text: "Security",
+      // collapsible: true,
+      children: [
+        {
+          text: "Authentication",
+          link: "/security/authentication",
+        },
+        {
+          text: "Authorization",
+          link: "/security/authorization",
+        },
+        {
+          text: "Encryption",
+          link: "/security/encryption",
+        },
+        {
+          text: "Hashing",
+          link: "/security/hashing",
+        },
+      ],
+    },
     {
       text: "ORM",
       // collapsible: true,

.vuepress/config/sidebar/zh.ts

@@ -105,14 +105,6 @@ export function getZhSidebar(): SidebarConfigArray {
           text: "Artisan 命令行",
           link: "/zh/digging-deeper/artisan-console",
         },
-        {
-          text: "用户验证",
-          link: "/zh/digging-deeper/authentication",
-        },
-        {
-          text: "用户授权",
-          link: "/zh/digging-deeper/authorization",
-        },
         {
           text: "缓存系统",
           link: "/zh/digging-deeper/cache",
@@ -143,6 +135,28 @@ export function getZhSidebar(): SidebarConfigArray {
         },
       ],
     },
+    {
+      text: "安全相关",
+      // collapsible: true,
+      children: [
+        {
+          text: "用户验证",
+          link: "/zh/security/authentication",
+        },
+        {
+          text: "用户授权",
+          link: "/zh/security/authorization",
+        },
+        {
+          text: "加密解密",
+          link: "/zh/security/encryption",
+        },
+        {
+          text: "哈希",
+          link: "/zh/security/hashing",
+        },
+      ],
+    },
     {
       text: "ORM",
       // collapsible: true,

ORM/getting-started.md

@@ -77,6 +77,27 @@ For example, the model name is `UserOrder`, the table name is `user_orders`.
 go run . artisan make:model User
 ```
 
+### Specify Table Name
+
+```go
+package models
+
+import (
+  "github.com/goravel/framework/database/orm"
+)
+
+type User struct {
+  orm.Model
+  Name   string
+  Avatar string
+  orm.SoftDeletes
+}
+
+func (r *User) TableName() string {
+  return "goravel_user"
+}
+```
+
 ## facades.Orm available functions
 
 | Name        | Action                                                      |
@@ -99,11 +120,14 @@ go run . artisan make:model User
 | Distinct      | [Filter Repetition](#Filter-Repetition)                 |
 | Driver        | [Get Driver](#Get-Driver)                               |
 | Exec          | [Execute native update SQL](#Execute-Native-Update-SQL) |
-| Find          | [Query one or multiple lines by ID](#Select)            |
-| First         | [Get one line](#Select)                                 |
-| FirstOrCreate | [Query or create](#Select)                              |
+| Find          | [Query one or multiple lines by ID](#Query-one-or-multiple-lines-by-ID)            |
+| First         | [Query one line](#Query-one-line)                       |
+| FirstOr | [Query or return data through callback](#Query-one-line)                     |
+| FirstOrCreate | [Retrieving Or Creating Models](#Retrieving-Or-Creating-Models)                     |
+| FirstOrNew | [Retrieving Or New Models](#Retrieving-Or-Creating-Models)                     |
+| FirstOrFail | [Not Found Error](#Not-Found-Error)                     |
 | ForceDelete   | [Force delete](#Delete)                                 |
-| Get           | [Query multiple lines](#Select)                         |
+| Get           | [Query multiple lines](#Query-multiple-lines)           |
 | Group         | [Group](#Group-By-&-Having)                             |
 | Having        | [Having](#Group-By-&-Having)                            |
 | Join          | [Join](#Join)                                           |
@@ -121,8 +145,9 @@ go run . artisan make:model User
 | Scopes        | [Scopes](#Execute-Native-SQL)                           |
 | Select        | [Specify Fields](#Specify-Fields)                       |
 | Table         | [Specify a table](#Specify-Table-Query)                 |
-| Update        | [Update a single column](#Save-Model)                   |
-| Updates       | [Update multiple columns](#Save-Model)                  |
+| Update        | [Update a single column](#Update-a-single-column)                   |
+| Updates       | [Update multiple columns](#Update-multiple-columns)                  |
+| UpdateOrCreate       | [Update or create](#Update-or-create)                  |
 | Where         | [Where](#Where)                                         |
 | WithTrashed   | [Query soft delete data](#Query-Soft-Delete-Data)       |
 
@@ -181,15 +206,25 @@ facades.Orm.WithContext(ctx).Query()
 
 ### Select
 
-Query one line
+#### Query one line
 
 ```go
 var user models.User
 facades.Orm.Query().First(&user)
 // SELECT * FROM users WHERE id = 10;
 ```
 
-Query one or multiple lines by ID
+Sometimes you may wish to perform some other action if no results are found. The findOr and firstOr methods will return a single model instance or, if no results are found, execute the given closure. You can set values to model in closure:
+
+```go
+facades.Orm.Query().Where("name", "first_user").FirstOr(&user, func() error {
+  user.Name = "goravel"
+
+  return nil
+})
+```
+
+#### Query one or multiple lines by ID
 
 ```go
 var user models.User
@@ -201,33 +236,54 @@ facades.Orm.Query().Find(&users, []int{1,2,3})
 // SELECT * FROM users WHERE id IN (1,2,3);
 ```
 
-When the primary key of the user table is `string` type, you need to specify the primary key when calling `Find` method
+#### When the primary key of the user table is `string` type, you need to specify the primary key when calling `Find` method
 
 ```go
 var user models.User
 facades.Orm.Query().Find(&user, "uuid=?" ,"a")
 // SELECT * FROM users WHERE uuid = "a";
 ```
 
-Query multiple lines
+#### Query multiple lines
 
 ```go
 var users []models.User
 facades.Orm.Query().Where("id in ?", []int{1,2,3}).Get(&users)
 // SELECT * FROM users WHERE id IN (1,2,3);
 ```
 
-Query or create
+#### Retrieving Or Creating Models
+
+The `FirstOrCreate` method will attempt to locate a database record using the given column / value pairs. If the model can not be found in the database, a record will be inserted with the attributes resulting from merging the first argument with the optional second argument:
+
+The `FirstOrNew` method, like `FirstOrCreate`, will attempt to locate a record in the database matching the given attributes. However, if a model is not found, a new model instance will be returned. Note that the model returned by `FirstOrNew` has not yet been persisted to the database. You will need to manually call the `Save` method to persist it:
 
 ```go
 var user models.User
-facades.Orm.Query().Where("sex = ?", 1).FirstOrCreate(&user, models.User{Name: "tom"})
+facades.Orm.Query().Where("sex", 1).FirstOrCreate(&user, models.User{Name: "tom"})
 // SELECT * FROM users where name="tom" and sex=1;
 // INSERT INTO users (name) VALUES ("tom");
 
-facades.Orm.Query().Where("sex = ?", 1).FirstOrCreate(&user, models.User{Name: "tom"}, , models.User{Avatar: "avatar"})
+facades.Orm.Query().Where("sex", 1).FirstOrCreate(&user, models.User{Name: "tom"}, models.User{Avatar: "avatar"})
 // SELECT * FROM users where name="tom" and sex=1;
 // INSERT INTO users (name,avatar) VALUES ("tom", "avatar");
+
+var user models.User
+facades.Orm.Query().Where("sex", 1).FirstOrNew(&user, models.User{Name: "tom"})
+// SELECT * FROM users where name="tom" and sex=1;
+
+facades.Orm.Query().Where("sex", 1).FirstOrNew(&user, models.User{Name: "tom"}, models.User{Avatar: "avatar"})
+// SELECT * FROM users where name="tom" and sex=1;
+```
+
+#### Not Found Error
+
+When not fount model, `First` doesn't return error, if you want return an error, you can use `FirstOrFail`:
+
+```go
+var user models.User
+err := facades.Orm.Query().FirstOrFail(&user)
+// err == orm.ErrRecordNotFound
 ```
 
 ### Where
@@ -367,7 +423,7 @@ result := facades.Orm.Query().Create(&users)
 
 ### Save Model
 
-Update a existing model
+#### Update a existing model
 
 ```go
 var user models.User
@@ -379,22 +435,32 @@ facades.Orm.Query().Save(&user)
 // UPDATE users SET name='tom', age=100, updated_at = '2022-09-28 16:28:22' WHERE id=1;
 ```
 
-Update a single column
+#### Update a single column
 
 ```go
-facades.Orm.Query().Model(&models.User{}).Where("name = ?", "tom").Update("name", "hello")
+facades.Orm.Query().Model(&models.User{}).Where("name", "tom").Update("name", "hello")
 // UPDATE users SET name='tom', updated_at='2022-09-28 16:29:39' WHERE name="tom";
 ```
 
-Update multiple columns
+#### Update multiple columns
 
 ```go
-facades.Orm.Query().Model(&user).Where("name = ?", "tom").Updates(User{Name: "hello", Age: 18})
+facades.Orm.Query().Model(&user).Where("name", "tom").Updates(User{Name: "hello", Age: 18})
 // UPDATE users SET name="hello", age=18, updated_at = '2022-09-28 16:30:12' WHERE name = "tom";
 ```
 
-> When updating with `struct`, Orm will only update non-zero fields. You might want to use `map` to update attributes or use `Select` to specify fields to update.
+> When updating with `struct`, Orm will only update non-zero fields. You might want to use `map` to update attributes or use `Select` to specify fields to update. Note that `struct` can only be `Model`, if you want to update with non `Model`, you need to use `.Table("users")`, however, the `updated_at` field cannot be updated automatically at this time.
 
+#### Update or create
+
+Query by `name`, if not exist, create by `name`, `avatar`, if exists, update `avatar` based on `name`:
+
+```go
+facades.Orm.Query().UpdateOrCreate(&user, User{Name: "name"}, User{Avatar: "avatar"})
+// SELECT * FROM `users` WHERE `users`.`name` = 'name' AND `users`.`deleted_at` IS NULL ORDER BY `users`.`id` LIMIT 1
+// INSERT INTO `users` (`created_at`,`updated_at`,`deleted_at`,`name`,`avatar`) VALUES ('2023-03-11 10:11:08.869','2023-03-11 10:11:08.869',NULL,'name','avatar')
+// UPDATE `users` SET `avatar`='avatar',`updated_at`='2023-03-11 10:11:08.881' WHERE `name` = 'name' AND `users`.`deleted_at` IS NULL AND `id` = 1
+```
 ### Delete
 
 Delete by model

README.md

@@ -29,17 +29,12 @@ Welcome star, PR and issues！
 - [x] Mail
 - [x] Validation
 - [x] Mock
+- [x] Hash
+- [x] Crypt
 
 ## Roadmap
 
-- [ ] Hash
-- [ ] Crypt
-- [ ] Support Websocket
-- [ ] Broadcasting
-- [ ] Delay Queue
-- [ ] Queue supports DB driver
-- [ ] Notifications
-- [ ] Optimize unit tests
+[For Detail](https://github.com/goravel/goravel/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)
 
 ## Documentation
 
@@ -49,6 +44,16 @@ Example [https://github.com/goravel/example](https://github.com/goravel/example)
 
 > To optimize the documentation, please submit a PR to the documentation repository [https://github.com/goravel/docs](https://github.com/goravel/docs)
 
+## Contributors
+
+This project exists thanks to all the people who contribute.
+
+<a href="https://github.com/hwbrzzl" target="_blank"><img src="https://avatars.githubusercontent.com/u/24771476?v=4" width="48" height="48"></a>
+<a href="https://github.com/merouanekhalili" target="_blank"><img src="https://avatars.githubusercontent.com/u/1122628?v=4" width="48" height="48"></a>
+<a href="https://github.com/hongyukeji" target="_blank"><img src="https://avatars.githubusercontent.com/u/23145983?v=4" width="48" height="48"></a>
+<a href="https://github.com/DevHaoZi" target="_blank"><img src="https://avatars.githubusercontent.com/u/115467771?v=4" width="48" height="48"></a>
+<a href="https://github.com/sidshrivastav" target="_blank"><img src="https://avatars.githubusercontent.com/u/28773690?v=4" width="48" height="48"></a>
+
 ## Group
 
 Welcome more discussion in Telegram.

architecutre-concepts/facades.md

@@ -39,13 +39,15 @@ func (database *ServiceProvider) Boot() {
 | Facade   | Document                                                |
 | -------- | ------------------------------------------------------- |
 | Artisan  | [Command Console](../digging-deeper/artisan-console.md) |
-| Auth     | [Authentication](../digging-deeper/authentication.md)   |
-| Gate     | [Authorization](../digging-deeper/authorization.md)     |
+| Auth     | [Authentication](../security/authentication.md)   |
+| Gate     | [Authorization](../security/authorization.md)     |
 | Cache    | [Cache](../digging-deeper/cache.md)                     |
 | Config   | [Configuration](../getting-started/configuration.md)    |
+| Crypt    | [Encryption](../security/encryption.md)    |
 | Orm      | [ORM](../orm/getting-started.md)                        |
 | Event    | [Event](../digging-deeper/event.md)                     |
 | Grpc     | [Grpc](../the-basics/grpc.md)                           |
+| Hash     | [Hashing](../security/hashing.md)                           |
 | Log      | [Log](../the-basics/logging.md)                         |
 | Queue    | [Queue](../digging-deeper/queues.md)                    |
 | Route    | [Route](../the-basics/routing.md)                       |

digging-deeper/filesystem.md

@@ -260,21 +260,27 @@ You need to implement the `github.com/goravel/framework/contracts/filesystem/Dri
 
 ```go
 type Driver interface {
-  WithContext(ctx context.Context) Driver
+  AllDirectories(path string) ([]string, error)
+  AllFiles(path string) ([]string, error)
+  Copy(oldFile, newFile string) error
+  Delete(file ...string) error
+  DeleteDirectory(directory string) error
+  Directories(path string) ([]string, error)
+  Exists(file string) bool
+  Files(path string) ([]string, error)
+  Get(file string) (string, error)
+  MakeDirectory(directory string) error
+  Missing(file string) bool
+  Move(oldFile, newFile string) error
+  Path(file string) string
   Put(file, content string) error
   PutFile(path string, source File) (string, error)
   PutFileAs(path string, source File, name string) (string, error)
-  Get(file string) (string, error)
   Size(file string) (int64, error)
-  Path(file string) string
-  Exists(file string) bool
-  Missing(file string) bool
-  Url(file string) string
   TemporaryUrl(file string, time time.Time) (string, error)
-  Copy(oldFile, newFile string) error
-  Move(oldFile, newFile string) error
-  Delete(file ...string) error
-  MakeDirectory(directory string) error
-  DeleteDirectory(directory string) error
+  WithContext(ctx context.Context) Driver
+  Url(file string) string
 }
 ```
+
+> Note: Since the configuration has not been loaded when the custom driver is registered, so please use `facades.Config.Env` to obtain the configuration in the custom driver.

digging-deeper/queues.md

@@ -192,6 +192,14 @@ err := facades.Queue.Chain([]queue.Jobs{
 }).Dispatch()
 ```
 
+### Delayed Dispatching
+
+If you would like to specify that a job should not be immediately available for processing by a queue worker, you may use the `Delay` method when dispatching the job. For example, let's specify that a job should not be available for processing until 10 minutes after it has been dispatched:
+
+```go
+err := facades.Queue.Job(&jobs.Test{}, []queue.Arg{}).Delay(time.Now().Add(100*time.Second)).Dispatch()
+```
+
 ### Customizing The Queue & Connection
 
 #### Dispatching To A Particular Queue