diff --git a/en/architecture-concepts/facades.md b/en/architecture-concepts/facades.md
index bd2bdd56d..71c3ae6a6 100644
--- a/en/architecture-concepts/facades.md
+++ b/en/architecture-concepts/facades.md
@@ -4,58 +4,63 @@
## Introduction
-`facades` provide a "static" interface for the core functionality of the application and provide a more flexible, more elegant, and easy-to-test syntax.
-
-All `facades` of Goravel are defined under `github.com/goravel/framework/facades`. We can easily use `facades`:
+`facades` provide a "static" interface for the core functionality of the application and provide a more flexible, more elegant, and easy-to-test syntax. All `facades` of Goravel are defined under the `app/facades` folder:
```go
-import "github.com/goravel/framework/facades"
+import "app/facades"
-facades.Route().Run(facades.Config().GetString("app.host"))
+facades.Config().GetString("app.host")
```
## How Facades Work
-`facades` are generally instantiated in the `Register` or `Boot` stage of each module `ServerProvider`.
+Each service provider registers its corresponding bindings in the service container, then the service container providers vairous `Make*` functions to build the binding instances. The `facades` in the `app/facades` folder call these `Make*` functions to get the instances from the service container. Let's use the `Route` facade as an example:
+
+1. The `Route` service provider registers the `binding.Route` binding in the service container:
```go
-func (config *ServiceProvider) Register() {
- app := Application{}
- facades.Config = app.Init()
+type ServiceProvider struct {}
+
+func (r *ServiceProvider) Register(app foundation.Application) {
+ app.Singleton(binding.Route, func(app foundation.Application) (any, error) {
+ return NewRoute(app.MakeConfig())
+ })
}
+
+func (r *ServiceProvider) Boot(app foundation.Application) {}
```
-If the `facades` use other `facades`, then instantiate them in the `Boot` phase of the `ServerProvider`:
+2. The `Route` facade calls the `MakeRoute()` function to get the `Route` instance from the service container:
```go
-func (database *ServiceProvider) Boot() {
- app := Application{}
- facades.DB = app.Init()
+// app/facades/route.go
+package facades
+
+import (
+ "github.com/goravel/framework/contracts/route"
+)
+
+func Route() route.Route {
+ return App().MakeRoute()
}
```
-## Facade Class Reference
-
-| Facade | Document |
-| ----------- | ---------------------------------------------------------- |
-| App | [Container](../architecture-concepts/service-container.md) |
-| Artisan | [Command Console](../digging-deeper/artisan-console.md) |
-| Auth | [Authentication](../security/authentication.md) |
-| Cache | [Cache](../digging-deeper/cache.md) |
-| Config | [Configuration](../getting-started/configuration.md) |
-| Crypt | [Encryption](../security/encryption.md) |
-| Event | [Event](../digging-deeper/event.md) |
-| Gate | [Authorization](../security/authorization.md) |
-| Grpc | [Grpc](../the-basics/grpc.md) |
-| Hash | [Hashing](../security/hashing.md) |
-| Log | [Log](../the-basics/logging.md) |
-| Mail | [Mail](../digging-deeper/mail.md) |
-| Orm | [ORM](../orm/getting-started.md) |
-| Queue | [Queue](../digging-deeper/queues.md) |
-| RateLimiter | [RateLimiter](../the-basics/routing.md) |
-| Route | [Route](../the-basics/routing.md) |
-| Seeder | [Seeder](../database/seeding.md) |
-| Schedule | [Schedule](../digging-deeper/task-scheduling.md) |
-| Storage | [Storage](../digging-deeper/task-scheduling.md) |
-| Testing | [Testing](../testing/getting-started.md) |
-| Validation | [Validation](../digging-deeper/task-scheduling.md) |
+> Given that the `facades` is exposed to the application, you can also create your own `facades` or override the existing `facades` in the `app/facades` folder.
+
+## Install/Uninstall Facades
+
+[goravel/goravel](https://github.com/goravel/goravel) installs all `facades` by default and [goravel/goravel-lite](https://github.com/goravel/goravel-lite) only installs essential `facades` like `Artisan`, `Config`. You can install or uninstall other `facades` as needed via the `package:install` and `package:uninstall` commands.
+
+```shell
+# Install a specific facade
+./artisan package:install Route
+
+# Install all facades
+./artisan package:install --all
+
+# Install all facades with default drivers
+./artisan package:install --all --default
+
+# Uninstall a specific facade
+./artisan package:uninstall Route
+```
diff --git a/en/architecture-concepts/request-lifecycle.md b/en/architecture-concepts/request-lifecycle.md
index 73f7636db..b078a546b 100644
--- a/en/architecture-concepts/request-lifecycle.md
+++ b/en/architecture-concepts/request-lifecycle.md
@@ -4,10 +4,25 @@
## Introduction
-The `main.go` file serves as the entry point for all requests in the Goravel application. It utilizes the `bootstrap.Boot()` function to initialize the framework.
+Using any tool in the real world feels more intuitive when you know how it works. This document aims to give you a clear, high-level look at how Goravel functions. Don’t worry if you don’t get every term right away—just aim for a basic sense of how things work, and your expertise will grow as you explore the rest of the docs.
-Then a Goravel instance is created by `app := foundation.NewApplication()` in `bootstrap/app.go`.
+## Lifecycle Overview
-After this, use `app.Boot()` to load the [Service Provider](service-providers.md) registered, and `config.Boot()` to load the configuration files under the config directory.
+1. The `main.go` is the entry point of the application, it will call the `bootstrap.Boot()` function to initialize the framework, and use `app.Wait()` to keep the application running.
-Finally, start the HTTP server by using `facades.Route().Run(facades.Config().GetString("app.host"))` in `main.go`.
+2. The `bootstrap.Boot()` function will initialize a new Goravel application instance by calling `foundation.Setup()`, you can set service providers, routes, and other settings like migrations, schedules via `With*` functions here. Finally, call the `Start()` method to boot the application.
+
+3. In the `Start()` method, it will first load configuration, then register all service providers and other settings. Finally, boot all service providers, return the application instance.
+
+4. After the application is started, the http or grpc server will be started automatically if you have configured them. They are controled by [the runners of service providers](./service-providers.md#runners). You can normally use all facades in this stage, but remember that your customize code should be placed before `app.Wait()` in the `main.go` file. Or you can add your code into the `WithCallback` function in the `bootstrap/app.go` file to make sure your code is executed after the application is started.
+
+```go
+func Boot() contractsfoundation.Application {
+ return foundation.Setup().
+ WithConfig(config.Boot).
+ WithCallback(func() {
+ // Your custom code here, all facades are available here.
+ }).
+ Start()
+}
+```
diff --git a/en/architecture-concepts/service-container.md b/en/architecture-concepts/service-container.md
index e463445e9..8bbed269d 100644
--- a/en/architecture-concepts/service-container.md
+++ b/en/architecture-concepts/service-container.md
@@ -16,30 +16,27 @@ Almost all of your service container bindings will be registered within [service
package route
import (
- "github.com/goravel/framework/contracts/foundation"
+ "github.com/goravel/framework/contracts/foundation"
)
const Binding = "goravel.route"
-type ServiceProvider struct {
-}
+type ServiceProvider struct {}
func (route *ServiceProvider) Register(app foundation.Application) {
- app.Bind(Binding, func(app foundation.Application) (any, error) {
- return NewRoute(app.MakeConfig()), nil
- })
+ app.Bind(Binding, func(app foundation.Application) (any, error) {
+ return NewRoute(app.MakeConfig()), nil
+ })
}
-func (route *ServiceProvider) Boot(app foundation.Application) {
-
-}
+func (route *ServiceProvider) Boot(app foundation.Application) {}
```
As mentioned, you will typically be interacting with the container within service providers; however, if you would like to interact with the container outside of a service provider, you may do so via the `App` facade:
```go
facades.App().Bind("key", func(app foundation.Application) (any, error) {
- ...
+ ...
})
```
@@ -49,7 +46,7 @@ The `Singleton` method binds a class or interface into the container that should
```go
app.Singleton(key, func(app foundation.Application) (any, error) {
- return NewGin(app.MakeConfig()), nil
+ return NewGin(app.MakeConfig()), nil
})
```
@@ -67,7 +64,7 @@ If you need some extra parameters to construct the service provider, you can use
```go
app.BindWith(Binding, func(app foundation.Application, parameters map[string]any) (any, error) {
- return NewRoute(app.MakeConfig()), nil
+ return NewRoute(app.MakeConfig()), nil
})
```
@@ -97,4 +94,4 @@ instance, err := app.MakeWith(key, map[string]any{"id": 1})
### Other Methods
-The framework provides some convenient methods to quickly resolve various facades: `MakeArtisan`, `MakeAuth`, `MakeCache`, `MakeConfig`, `MakeCrypt`, `MakeEvent`, `MakeGate`, `MakeGrpc`, `MakeHash`, `MakeLog`, `MakeMail`, `MakeOrm`, `MakeQueue`, `MakeRateLimiter`, `MakeRoute`, `MakeSchedule`, `MakeStorage`, `MakeValidation`.
+The framework provides some convenient methods to quickly resolve various facades: `MakeArtisan`, `MakeAuth`, etc.
diff --git a/en/architecture-concepts/service-providers.md b/en/architecture-concepts/service-providers.md
index 4bcd2e996..f35916c1d 100644
--- a/en/architecture-concepts/service-providers.md
+++ b/en/architecture-concepts/service-providers.md
@@ -4,26 +4,42 @@
## Introduction
-The most important thing in the kernel boot operation is to load the `ServiceProvider`. All `ServiceProvider` under the application are configured in the `providers` array in `config/app.go`.
+The most important thing in the kernel boot operation is to load the `ServiceProvider`. All `ServiceProvider` under the application are configured in the `bootstrap/providers.go` file.
First, the kernel will call the `Register` method of all service providers. After all service providers have been registered, the kernel will call the `Boot` method of all `ServiceProvider` again.
The `ServiceProvider` is the key to the life cycle of Goravel. They enable the framework to contain various components, such as routing, database, queue, cache, etc.
-You can also customize your own provider, it can be stored under `app/providers` and registered in the `providers` array in `config/app.go`.
+## Create Service Provider
-The framework comes with a blank service provider `app/providers/app_service_provider.go` where you can implement simple boot logic. In bigger projects, you have the option to create new service providers for more precise control.
+Service providers contain a `Register` and a `Boot` method. Within the `Register` method, you should only bind things into [the service container](./service-container.md). You should never attempt to register any event listeners, routes, or any other piece of functionality within the `Register` method.
-ServiceProvider provides an optional method `Relationship() binding.Relationship`, used to declare the dependency relationship of the current ServicerProvider, the ServiceProvider that sets this method will not depend on the registration order, and the ServiceProvider that does not set it will be registered last, for example:
+```bash
+./artisan make:provider YourServiceProviderName
+```
+
+The Artisan CLI can generate a new provider via the `make:provider` command. The new service provider will be registered automatically in the `bootstrap/providers.go::Providers()` function and the function will be called by `WithProviders`.
```go
-type ServiceProvider struct {
+func Boot() contractsfoundation.Application {
+ return foundation.Setup().
+ WithProvders(Providers).
+ WithConfig(config.Boot).
+ Start()
}
+```
+
+## Dependency Relationship
+
+`ServiceProvider` provides an optional method `Relationship() binding.Relationship`, used to declare the dependency relationship, the `ServiceProvider` that sets this method will not depend on the registration order, and the `ServiceProvider` that does not set it will be registered last, for example:
+
+```go
+type ServiceProvider struct {}
func (r *ServiceProvider) Relationship() binding.Relationship {
return binding.Relationship{
Bindings: []string{
- BindingSession,
+ "custom",
},
Dependencies: []string{
binding.Config,
@@ -34,7 +50,90 @@ func (r *ServiceProvider) Relationship() binding.Relationship {
}
}
+func (r *ServiceProvider) Register(app foundation.Application) {
+ app.Singleton("custom", func(app foundation.Application) (any, error) {
+ return New()
+ })
+}
+
+func (r *ServiceProvider) Boot(app foundation.Application) {}
+```
+
+## Runners
+
+The `ServiceProvider` can also implement the `Runners` interface to run some code when the application starts. It's usually used to start/shutdown the service which is defined in the `ServiceProvider`. For example: `Route`, `Schedule`, `Queue`, etc. You don't need to start/shutdown these services with `Runners` in the `main.go` anymore, Goravel will take care of it.
+
+A `Runner` contains three methods: `ShouldRun()`, `Run()`, and `Shutdown()`.
+
+```go
+type Runner interface {
+ // ShouldRun determines whether the runner should be executed.
+ ShouldRun() bool
+ // Run starts the runner.
+ Run() error
+ // Shutdown gracefully stops the runner.
+ Shutdown() error
+}
+```
+
+There is an example of a `RouteRunner` defined in the `ServiceProvider` to start and shutdown the `Route` service.
+
+```go
+type ServiceProvider struct {}
+
func (r *ServiceProvider) Register(app foundation.Application) {}
func (r *ServiceProvider) Boot(app foundation.Application) {}
+
+func (r *ServiceProvider) Runners(app foundation.Application) []foundation.Runner {
+ return []foundation.Runner{NewRouteRunner(app.MakeConfig(), app.MakeRoute())}
+}
+```
+
+```go
+package route
+
+import (
+ "github.com/goravel/framework/contracts/config"
+ "github.com/goravel/framework/contracts/route"
+)
+
+type RouteRunner struct {
+ config config.Config
+ route route.Route
+}
+
+func NewRouteRunner(config config.Config, route route.Route) *RouteRunner {
+ return &RouteRunner{
+ config: config,
+ route: route,
+ }
+}
+
+func (r *RouteRunner) ShouldRun() bool {
+ return r.route != nil && r.config.GetString("http.default") != ""
+}
+
+func (r *RouteRunner) Run() error {
+ return r.route.Run()
+}
+
+func (r *RouteRunner) Shutdown() error {
+ return r.route.Shutdown()
+}
+```
+
+You can register your own `Runner` in the `bootstrap/app.go::WithRunners` function to run some code when the application starts.
+
+```go
+func Boot() contractsfoundation.Application {
+ return foundation.Setup().
+ WithConfig(config.Boot).
+ WithRunners(func() []foundation.Runner{
+ return []foundation.Runner{
+ NewYourCustomRunner(),
+ }
+ }).
+ Start()
+}
```
diff --git a/en/database/getting-started.md b/en/database/getting-started.md
index 0f935f6dc..898ed2c44 100644
--- a/en/database/getting-started.md
+++ b/en/database/getting-started.md
@@ -59,7 +59,7 @@ We have added two keys, `read` and `write`, in the database configuration. `192.
## Running Native SQL Queries
-After configuring the database connection, you can use `facades.DB()` to run queries. `facades.DB` provides various methods for running queries: `Select`, `Insert`, `Update`, `Delete`, and `Statement`.
+After configuring the database connection, you can use `facades.DB()` to run queries. `facades.DB()` provides various methods for running queries: `Select`, `Insert`, `Update`, `Delete`, and `Statement`.
### Select
@@ -163,15 +163,15 @@ Goravel provides several Artisan commands to help you understand the structure o
You can use the `db:show` command to view all tables in the database.
```bash
-go run . artisan db:show
-go run . artisan db:show --database=postgres
+./artisan db:show
+./artisan db:show --database=postgres
```
You can also use the `db:table` command to view the structure of a specific table.
```bash
-go run . artisan db:table
-go run . artisan db:table --database=postgres
+./artisan db:table
+./artisan db:table --database=postgres
```
### Table Overview
@@ -179,6 +179,6 @@ go run . artisan db:table --database=postgres
If you want to get an overview of a single table in the database, you can execute the `db:table` Artisan command. This command provides an overview of a database table, including its columns, types, attributes, keys, and indexes:
```bash
-go run . artisan db:table users
-go run . artisan db:table users --database=postgres
+./artisan db:table users
+./artisan db:table users --database=postgres
```
diff --git a/en/database/migrations.md b/en/database/migrations.md
index 7abb7831b..a9058acc0 100644
--- a/en/database/migrations.md
+++ b/en/database/migrations.md
@@ -22,11 +22,33 @@ The database migration files are stored in the `database/migrations` directory.
Use the `make:migration` command to create the migration:
```shell
-go run . artisan make:migration create_users_table
+./artisan make:migration
+./artisan make:migration create_users_table
```
This command will generate migration files in the `database/migrations` directory. Each migration file will begin with a timestamp, which Goravel will use to determine the execution order of the migration files.
+You can also create a migration for a specific model by using the `-m` or `--model` option:
+
+```shell
+./artisan make:migration create_users_table -m User
+```
+
+The model should be registered in the `bootstrap/app.go` file before running the command. This command will generate a migration file based on the structure defined in the `User` model.
+
+```go
+func Boot() contractsfoundation.Application {
+ return foundation.Setup().
+ WithConfig(config.Boot).
+ WithCallback(func() {
+ facades.Schema().Extend(schema.Extension{
+ Models: []any{models.User{}},
+ })
+ }).
+ Start()
+}
+```
+
### Quickly Create
Use `create_users_table` to automatically generate a table containing the infrastructure of `users`:
@@ -56,7 +78,8 @@ package migrations
import (
"github.com/goravel/framework/contracts/database/schema"
- "github.com/goravel/framework/facades"
+
+ "goravel/app/facades"
)
type M20241207095921CreateUsersTable struct {
@@ -99,14 +122,14 @@ func (r *M20241207095921CreateUsersTable) Connection() string {
## Register Migrations
-You need to register the migration files in the `database/kernel.go` file after the migration files are generated, if the migration files are generated by the `make:migration` command, the framework will automatically register them.
+A new migration created by `make:migration` will be registered automatically in the `bootstrap/migrations.go::Migrations()` function and the function will be called by `WithMigrations`. You need register the rule manually if you create the migration file by yourself.
```go
-// database/kernel.go
-func (kernel Kernel) Migrations() []schema.Migration {
- return []schema.Migration{
- &migrations.M20241207095921CreateUsersTable{},
- }
+func Boot() contractsfoundation.Application {
+ return foundation.Setup().
+ WithMigrations(Migrations).
+ WithConfig(config.Boot).
+ Start()
}
```
@@ -115,39 +138,39 @@ func (kernel Kernel) Migrations() []schema.Migration {
To run all of your outstanding migrations, execute the `migrate` Artisan command:
```shell
-go run . artisan migrate
+./artisan migrate
```
If you would like to see which migrations have run thus far, you may use the `migrate:status` Artisan command:
```shell
-go run . artisan migrate:status
+./artisan migrate:status
```
## Rolling Back Migrations
-To roll back the latest migration, use the `rollback` Artisan command:
+To roll back the latest migration batch, use the `rollback` Artisan command:
```shell
-go run . artisan migrate:rollback
+./artisan migrate:rollback
```
-If you want to roll back the last "batch" of migrations, which may include multiple migration files, you can specify the `batch` option, the number indicates which batch to roll back:
+If you want to roll back multiple migration batches, you can specify the `batch` option, the number indicates which batch to roll back:
```shell
-go run . artisan migrate:rollback --batch=2
+./artisan migrate:rollback --batch=2
```
You may roll back a limited number of migrations by providing the `step` option to the `rollback` command. For example, the following command will roll back the last five migrations:
```shell
-go run . artisan migrate:rollback --step=5
+./artisan migrate:rollback --step=5
```
The `migrate:reset` command will roll back all of your application's migrations:
```shell
-go run . artisan migrate:reset
+./artisan migrate:reset
```
### Roll Back & Migrate Using A Single Command
@@ -155,13 +178,13 @@ go run . artisan migrate:reset
The `migrate:refresh` command will roll back all of your migrations and then execute the `migrate` command. This command effectively re-creates your entire database:
```shell
-go run . artisan migrate:refresh
+./artisan migrate:refresh
```
You may roll back and re-migrate a limited number of migrations by providing the `step` option to the `refresh` command. For example, the following command will roll back and re-migrate the last five migrations:
```shell
-go run . artisan migrate:refresh --step=5
+./artisan migrate:refresh --step=5
```
### Drop All Tables & Migrate
@@ -169,7 +192,7 @@ go run . artisan migrate:refresh --step=5
The `migrate:fresh` command will drop all tables from the database and then execute the `migrate` command:
```shell
-go run . artisan migrate:fresh
+./artisan migrate:fresh
```
## Tables
diff --git a/en/database/queries.md b/en/database/queries.md
index ebf8ed54f..87343a12b 100644
--- a/en/database/queries.md
+++ b/en/database/queries.md
@@ -76,7 +76,7 @@ You can use the `FindOr` or `FirstOr` method, if the record is not found, it wil
```go
var user *User
-user, err = facades.DB().Table("users").Where("name", "John").FirstOr(&user, func() error {
+err = facades.DB().Table("users").Where("name", "John").FirstOr(&user, func() error {
return errors.New("no rows")
})
```
@@ -99,8 +99,10 @@ var products []Product
err := facades.DB().Table("products").Each(func(rows []db.Row) error {
for _, row := range rows {
var product Product
- err := row.Scan(&product)
- s.NoError(err)
+ if err := row.Scan(&product); err != nil {
+ return err
+ }
+
products = append(products, product)
}
@@ -117,8 +119,10 @@ var products []Product
err := facades.DB().Table("products").Chunk(2, func(rows []db.Row) error {
for _, row := range rows {
var product Product
- err := row.Scan(&product)
- s.NoError(err)
+ if err := row.Scan(&product); err != nil {
+ return err
+ }
+
products = append(products, product)
}
@@ -138,10 +142,9 @@ rows, err := facades.DB().Table("products").Cursor()
var products []Product
for row := range rows {
var product Product
- err = row.Scan(&product)
-
- s.NoError(err)
- s.True(product.ID > 0)
+ if err := row.Scan(&product); err != nil {
+ return err
+ }
products = append(products, product)
}
@@ -149,12 +152,22 @@ for row := range rows {
### Aggregates
-The query builder provides aggregate methods: `Count` `Sum`.
+The query builder provides aggregate methods: `Count`, `Sum`, `Avg`, `Min`, `Max`.
```go
count, err := facades.DB().Table("users").Count()
-sum, err := facades.DB().Table("users").Sum("age")
+var sum int
+err := facades.DB().Table("users").Sum("age", &sum)
+
+var avg float64
+err := facades.DB().Table("users").Avg("age", &avg)
+
+var min int
+err := facades.DB().Table("users").Min("age", &min)
+
+var max int
+err := facades.DB().Table("users").Max("age", &max)
```
### Checking if a Record Exists
@@ -203,7 +216,7 @@ Sometimes you may need to use raw expressions in your queries. You can use the `
```go
import "github.com/goravel/framework/database/db"
-facades.DB().Model(&user).Update("age", db.Raw("age - ?", 1))
+res, err := facades.DB().Model(&user).Update("age", db.Raw("age - ?", 1))
```
## Select
@@ -214,10 +227,10 @@ Of course, you may not always want to retrieve all columns from a database table
```go
// Select specific fields
-facades.DB().Select("name", "age").Get(&users)
+err := facades.DB().Select("name", "age").Get(&users)
// Use a subquery
-facades.DB().Select("name", db.Raw("(SELECT COUNT(*) FROM posts WHERE users.id = posts.user_id) as post_count")).Get(&users)
+err := facades.DB().Select("name", db.Raw("(SELECT COUNT(*) FROM posts WHERE users.id = posts.user_id) as post_count")).Get(&users)
```
### Distinct
@@ -226,7 +239,7 @@ The `Distinct` method will force the query to return unique results:
```go
var users []models.User
-facades.DB().Distinct("name").Find(&users)
+err := facades.DB().Distinct("name").Find(&users)
```
## Raw Methods
@@ -345,6 +358,22 @@ err := facades.DB().Table("users").Where("name", "John").WhereExists(func() db.Q
}).Get(&users)
```
+### WhereAll / WhereAny / WhereNone
+
+```go
+var products []Product
+facades.DB().Table("products").WhereAll([]string{"weight", "height"}, "=", 200).Find(&products)
+// SQL: SELECT * FROM products WHERE weight = ? AND height = ?
+
+var users []User
+facades.DB().Table("users").WhereAny([]string{"name", "email"}, "=", "John").Find(&users)
+// SQL: SELECT * FROM users WHERE (name = ? OR email = ?)
+
+var products []Product
+facades.DB().Table("products").WhereNone([]string{"age", "score"}, ">", 18).Find(&products)
+// SQL: SELECT * FROM products WHERE NOT (age > ?) AND NOT (score > ?)
+```
+
### Other Where Clauses
**WhereBetween / OrWhereBetween**
@@ -422,9 +451,9 @@ facades.DB().OrderByDesc("name")
The `Latest` method makes it easy to sort results by date. By default, results will be sorted by the `created_at` column:
```go
-facades.DB().Table("users").Latest().First(&user)
+err := facades.DB().Table("users").Latest().First(&user)
-facades.DB().Table("users").Latest("updated_at").First(&user)
+err := facades.DB().Table("users").Latest("updated_at").First(&user)
```
**InRandomOrder**
@@ -432,7 +461,7 @@ facades.DB().Table("users").Latest("updated_at").First(&user)
The `InRandomOrder` method is used to sort results randomly:
```go
-facades.DB().Table("users").InRandomOrder().First(&user)
+err := facades.DB().Table("users").InRandomOrder().First(&user)
```
### Grouping
@@ -458,7 +487,7 @@ Sometimes you may want a clause to only execute when a given condition is true.
```go
import "github.com/goravel/framework/contracts/database/db"
-facades.DB().Table("users").When(1 == 1, func(query db.Query) db.Query {
+err := facades.DB().Table("users").When(1 == 1, func(query db.Query) db.Query {
return query.Where("age", 25)
}).First(&user)
```
@@ -466,7 +495,7 @@ facades.DB().Table("users").When(1 == 1, func(query db.Query) db.Query {
You can also pass another closure as the third parameter to the `When` method. This closure will execute if the first parameter results in false:
```go
-facades.DB().Table("users").When(1 != 1, func(query db.Query) db.Query {
+err := facades.DB().Table("users").When(1 != 1, func(query db.Query) db.Query {
return query.OrderBy("name")
}, func(query db.Query) db.Query {
return query.OrderBy("id")
@@ -549,11 +578,10 @@ result, err := facades.DB().Table("products").Where("id", 1).Update(map[string]a
### Update JSON fields
```go
-facades.DB().Table("users").Where("id", 1).Update("options->enabled", true)
-facades.DB().Table("users").Where("id", 1).Update("options->languages[0]", "en")
-facades.DB().Table("users").Where("id", 1).Update("options->languages", []string{"en", "de"})
-
-facades.DB().Table("users").Where("id", 1).Update(map[string]any{
+result, err := facades.DB().Table("users").Where("id", 1).Update("options->enabled", true)
+result, err := facades.DB().Table("users").Where("id", 1).Update("options->languages[0]", "en")
+result, err := facades.DB().Table("users").Where("id", 1).Update("options->languages", []string{"en", "de"})
+result, err := facades.DB().Table("users").Where("id", 1).Update(map[string]any{
"preferences->dining->meal": "salad",
"options->languages[0]": "en",
"options->enabled": true,
@@ -611,13 +639,13 @@ The query builder also includes some functions that can help you implement "pess
To use a "shared lock", you may use the `SharedLock` method. A shared lock prevents the selected rows from being modified until the transaction is committed:
```go
-facades.DB().Table("users").Where("votes > ?", 100).SharedLock().Get(&users)
+err := facades.DB().Table("users").Where("votes > ?", 100).SharedLock().Get(&users)
```
You can also use the `LockForUpdate` method. Using the "update" lock can prevent rows from being modified or selected by other shared locks:
```go
-facades.DB().Table("users").Where("votes > ?", 100).LockForUpdate().Get(&users)
+err := facades.DB().Table("users").Where("votes > ?", 100).LockForUpdate().Get(&users)
```
## Debugging
@@ -627,13 +655,13 @@ You can use the `ToSQL` and `ToRawSql` methods to get the current query binding
With placeholder SQL:
```go
-facades.DB().Table("users").Where("id", 1).ToSql().Get(models.User{})
+err := facades.DB().Table("users").Where("id", 1).ToSql().Get(models.User{})
```
With bound values SQL:
```go
-facades.DB().Table("users").Where("id", 1).ToRawSql().Get(models.User{})
+err := facades.DB().Table("users").Where("id", 1).ToRawSql().Get(models.User{})
```
The methods that can be called after `ToSql` and `ToRawSql`: `Count`, `Insert`, `Delete`, `First`, `Get`, `Pluck`, `Update`.
diff --git a/en/database/seeding.md b/en/database/seeding.md
index 4e335eb61..fd984131e 100644
--- a/en/database/seeding.md
+++ b/en/database/seeding.md
@@ -11,7 +11,7 @@ Goravel includes the ability to seed your database with data using seed struct.
To generate a seeder, run the `make:seeder` [Artisan command](../digging-deeper/artisan-console.md). All seeders generated by the framework will be stored in the `database/seeders` directory:
```shell
-go run . artisan make:seeder UserSeeder
+./artisan make:seeder UserSeeder
```
By default, a seeder struct has two methods: `Signature` and `Run`. The `Signature` method sets the name of the seeder, while the `Run` method is triggered when the `db:seed` Artisan command is executed. You can use the `Run` method to insert data into your database in any way you prefer.
@@ -23,8 +23,8 @@ package seeders
import (
"github.com/goravel/framework/contracts/database/seeder"
- "github.com/goravel/framework/facades"
-
+
+ "goravel/app/facades"
"goravel/app/models"
)
@@ -74,34 +74,32 @@ func (s *DatabaseSeeder) Run() error {
You may run the `db:seed` Artisan command to seed your database. By default, the `db:seed` command runs the `database/seeders/database_seeder.go` file, which may in turn invoke other seed classes. However, you may use the `--seeder` option to specify a specific seeder class to run individually:
```shell
-go run . artisan db:seed
+./artisan db:seed
```
-If you want to execute other seeders when running the `db:seed` command, you can register the seeder in `app/providers/database_service_provider.go`, if the seeder is generated by the `make:seeder` command, the framework will automatically register it.
+If you want to execute other seeders when running the `db:seed` command, you can register the seeder in the `bootstrp/app.go::WithSeeders` function, if the seeder is generated by the `make:seeder` command, the framework will automatically register it.
```go
-// app/providers/database_service_provider.go
-func (receiver *DatabaseServiceProvider) Boot(app foundation.Application) {
- facades.Seeder().Register([]seeder.Seeder{
- &seeders.DatabaseSeeder{},
- &seeders.UserSeeder{},
- &seeders.PhotoSeeder{},
- })
+func Boot() contractsfoundation.Application {
+ return foundation.Setup().
+ WithSeeders(Seeders).
+ WithConfig(config.Boot).
+ Start()
}
-go run . artisan db:seed --seeder=UserSeeder PhotoSeeder // The signature of seeder
+./artisan db:seed --seeder=UserSeeder PhotoSeeder // The signature of seeder
```
You may also seed your database using the `migrate:fresh` and `migrate:refresh` command in combination with the `--seed` option, which will drop all tables and re-run all of your migrations. This command is useful for completely re-building your database. The `--seeder` option may be used to specify a specific seeder to run:
```shell
-go run . artisan migrate:fresh --seed
+./artisan migrate:fresh --seed
-go run . artisan migrate:fresh --seed --seeder=UserSeeder
+./artisan migrate:fresh --seed --seeder=UserSeeder
-go run . artisan migrate:refresh --seed
+./artisan migrate:refresh --seed
-go run . artisan migrate:refresh --seed --seeder=UserSeeder
+./artisan migrate:refresh --seed --seeder=UserSeeder
```
### Forcing Seeders To Run In Production
@@ -109,5 +107,5 @@ go run . artisan migrate:refresh --seed --seeder=UserSeeder
Some seeding operations may cause you to alter or lose data. In order to protect you from running seeding commands against your production database, you will be prompted for confirmation before the seeders are executed in the `production` environment. To force the seeders to run without a prompt, use the `--force` flag:
```shell
-go run . artisan db:seed --force
+./artisan db:seed --force
```
diff --git a/en/digging-deeper/artisan-console.md b/en/digging-deeper/artisan-console.md
index 13ffc38ca..10ff0c1ec 100644
--- a/en/digging-deeper/artisan-console.md
+++ b/en/digging-deeper/artisan-console.md
@@ -7,19 +7,19 @@
Artisan is the CLI tool that comes with Goravel for interacting with the command line. You can access it using `facades.Artisan()`. This tool has several useful commands that can assist you in the development of your application. Utilize the following command to view all available commands.
```shell
-go run . artisan list
+./artisan list
# or
-./artisan list
+go run . artisan list
```
Each command also has a "help" flag that shows and explains the arguments and options associated with the command:
```shell
-go run . artisan migrate --help
+./artisan migrate --help
```
-Instead of repeating `go run . artisan ...` command, you may want to add an alias to your shell configuration with the terminal command below:
+Instead of repeating `./artisan ...` command, you may want to add an alias to your shell configuration with the terminal command below:
```shell
echo -e "\r\nalias artisan=\"go run . artisan\"" >>~/.zshrc
@@ -33,19 +33,30 @@ artisan make:controller DemoController
You can also use `artisan` shell script like this:
-```shell
-./artisan make:controller DemoController
-```
-
### Generating Commands
You can use the `make:command` command to create a new command in the `app/console/commands` directory. Don't worry if this directory does not exist in your application, it will be created the first time you run the `make:command` command:
```shell
-go run . artisan make:command SendEmails
-go run . artisan make:command user/SendEmails
+./artisan make:command SendEmails
+./artisan make:command user/SendEmails
+```
+
+### Register Commands
+
+All commands should be registered via the `WithCommands` function in the `bootstrap/app.go` file:
+
+```go
+func Boot() contractsfoundation.Application {
+ return foundation.Setup().
+ WithCommands(Commands).
+ WithConfig(config.Boot).
+ Start()
+}
```
+A new command created by `make:command` will be registered automatically in the `bootstrap/commands.go::Commands()` function and the function will be called by `WithCommands`. You need register the command manually if you create the command file by yourself.
+
### Command Structure
After generating your command, assign suitable values to the signature and description properties of the struct. The `Handle` method will be called when your command is executed. You need to implement your logic in this method.
@@ -93,11 +104,67 @@ When you write console commands, it's typical to collect user input through `arg
Follow the arguments after the command:
```shell
-go run . artisan send:emails NAME EMAIL
+./artisan send:emails SUBJECT EMAIL_1 EMAIL_2
+```
+
+Definition：
+
+```go
+// send:emails Thank you for joining {{.AppName}}.
+``` + +### Sending Emails with Templates + +You can use the `Content` method to specify the template and pass dynamic data: + +```go +facades.Mail(). + To([]string{"user@example.com"}). + Subject("Welcome"). + Content(mail.Content{ + View: "welcome.tmpl", + With: map[string]any{ + "Name": "John", + "AppName": "Goravel", + }, + }). + Send() +``` + +### Custom Template Engines + +You can also register custom template engines in the configuration: + +```go +"template": map[string]any{ + "default": "blade", + "engines": map[string]any{ + "blade": map[string]any{ + "driver": "custom", + "via": func() (mail.Template, error) { + return NewBladeTemplateEngine(), nil + }, + }, + }, +} +``` + diff --git a/en/digging-deeper/package-development.md b/en/digging-deeper/package-development.md index 55a0f2f5f..328f3b80e 100644 --- a/en/digging-deeper/package-development.md +++ b/en/digging-deeper/package-development.md @@ -13,22 +13,20 @@ Here is an example for building a third-party package: [goravel/example-package] You can use easily create a package template using the Artisan command: ```shell -go run . artisan make:package sms +./artisan make:package sms ``` The created files are saved by default in the root `packages` folder, you can use `--root` option to customize: ```shell -go run . artisan make:package --root=pkg sms +./artisan make:package --root=pkg sms ``` ## Service Providers [Service providers](../architecture-concepts/service-providers.md) act as the bridge between your package and Goravel. They are typically located in the root of the package as a `service_provider.go` file. Their main function is to bind items into Goravel's service container and guide Goravel in loading package resources. -## Usage - -### Auto Install +## Install The Package When creating a package, if it contains a `setup/setup.go` file, you can define the package installation logic in this file, and then users can use the `package:install` command to install the package: @@ -40,45 +38,45 @@ The following is an explanation of the installation process defined in the `setu ```go // setup/setup.go +package main + +import ( + "os" + + "github.com/goravel/framework/packages" + "github.com/goravel/framework/packages/modify" + "github.com/goravel/framework/support/file" + "github.com/goravel/framework/support/path" +) + func main() { - // When installing in this way, the configuration file will be published to the project's config directory. - // You can also manually publish this configuration file: ./artisan vendor:publish --package=github.com/goravel/example-package - config, err := supportfile.GetPackageContent(packages.GetModulePath(), "setup/config/hello.go") + setup := packages.Setup(os.Args) + + // The config file will be published to the project's config directory automatically when installing by this way. + // You can also publish this config file manually: ./artisan vendor:publish --package=github.com/goravel/example-package + config, err := file.GetPackageContent(setup.Paths().Module().String(), "setup/config/hello.go") if err != nil { panic(err) } - // Execute installation or uninstallation operations based on user input parameters - packages.Setup(os.Args). - // Define installation process - Install( - // Find config/app.go file - modify.GoFile(path.Config("app.go")). - // Find imports and add import: examplepackage "github.com/goravel/example-package" - Find(match.Imports()).Modify(modify.AddImport(packages.GetModulePath(), "examplepackage")). - // Find providers and register service providers: &examplepackage.ServiceProvider{}，note that you need to add the import first, then you can register the service provider - Find(match.Providers()).Modify(modify.Register("&examplepackage.ServiceProvider{}")), - // Find hello.go file, create or overwrite file - modify.File(path.Config("hello.go")).Overwrite(config), - ). - // Define uninstallation process - Uninstall( - // Find config/app.go file - modify.GoFile(path.Config("app.go")). - // Find providers and unregister service providers: &examplepackage.ServiceProvider{} - Find(match.Providers()).Modify(modify.Unregister("&examplepackage.ServiceProvider{}")). - // Find imports and delete import: examplepackage "github.com/goravel/example-package"，note that you need to unregister the service provider first, then you can delete the import - Find(match.Imports()).Modify(modify.RemoveImport(packages.GetModulePath(), "examplepackage")), - // Find hello.go file, delete file - modify.File(path.Config("hello.go")).Remove(), - ). - // Execute installation or uninstallation operations - Execute() -``` + serviceProvider := "&hello.ServiceProvider{}" + moduleImport := setup.Paths().Module().Import() + + setup.Install( + // Add the service provider to the providers slice in bootstrap/providers.go + modify.AddProviderApply(moduleImport, serviceProvider), -### Manual Install + // Add the config file to the config directory + modify.File(path.Config("hello.go")).Overwrite(config), + ).Uninstall( + // Remove the config file from the config directory + modify.File(path.Config("hello.go")).Remove(), -Register the `ServiceProvider` in the package to `config/app.go::providers`, then export `facades` to the application. For detailed steps, refer to [goravel/example-package](https://github.com/goravel/example-package). + // Remove the service provider from the providers slice in bootstrap/providers.go + modify.RemoveProviderApply(moduleImport, serviceProvider), + ).Execute() +} +``` ## Resources @@ -173,7 +171,7 @@ func (receiver *ServiceProvider) Boot(app foundation.Application) { In the project, You can publish the resources registered in a package using `vendor:publish` Artisan command: ```shell -go run . artisan vendor:publish --package={You package name} +./artisan vendor:publish --package={You package name} ``` The command can use the following options: diff --git a/en/digging-deeper/pluralization.md b/en/digging-deeper/pluralization.md new file mode 100644 index 000000000..c39c6b34b --- /dev/null +++ b/en/digging-deeper/pluralization.md @@ -0,0 +1,120 @@ +# Pluralization + +[[toc]] + +## Introduction + +Strings are important for any web application. Goravel provides simple utilities to convert words between singular +and plural forms. It supports **English** by default, but you can add other languages or custom rules easily. + +## Basic Usage + +You can use the `Plural` and `Singular` methods from the `pluralizer` package. These handle most English words automatically. + +```go +import "github.com/goravel/framework/support/pluralizer" + +// Pluralize words +pluralizer.Plural("goose") // "geese" +pluralizer.Plural("car") // "cars" + +// Singularize words +pluralizer.Singular("geese") // "goose" +pluralizer.Singular("cars") // "car" +``` + +## Custom Rules + +Sometimes the default rules are not enough for specific words. Goravel lets you add your own rules to handle these cases. + +::: warning +Adding rules changes how pluralization works globally. You should do this when your application starts, +like in the `Boot` method of a Service Provider. +::: + +### Irregular Words + +If a word has a unique plural form, you can register it as an "irregular" word. This handles changes in both directions. + +```go +import ( + "github.com/goravel/framework/support/pluralizer" + "github.com/goravel/framework/support/pluralizer/rules" +) + +// Register that "mouse" becomes "mice" +pluralizer.RegisterIrregular("english", rules.NewSubstitution("mouse", "mice")) +``` + +### Uninflected Words + +Some words like "fish" or "media" do not change form or are always plural. You can mark these as "uninflected" +so the pluralizer skips them. + +```go +// "sheep" stays "sheep" in singular and plural +pluralizer.RegisterUninflected("english", "sheep", "fish") + +// "media" is always treated as plural +pluralizer.RegisterPluralUninflected("english", "media") + +// "data" is always treated as singular +pluralizer.RegisterSingularUninflected("english", "data") +``` + +## Language Support + +Goravel uses "english" by default, but you can switch languages or add new ones if you need to. + +### Switching Languages + +If you have other languages registered, you can switch the active one using `UseLanguage`. + +```go +if err := pluralizer.UseLanguage("spanish"); err != nil { + panic(err) +} + +// Get the current language name +name := pluralizer.GetLanguage().Name() +``` + +### Adding New Languages + +To add a language, you need to implement the `Language` interface. This defines how words change in that language. + +```go +import "github.com/goravel/framework/contracts/support/pluralizer" + +type Language interface { + Name() string + SingularRuleset() pluralizer.Ruleset + PluralRuleset() pluralizer.Ruleset +} +``` + +After implementing your language struct, register it and set it as active. + +```go +import "github.com/goravel/framework/support/pluralizer" + +func init() { + // Register the new language + if err := pluralizer.RegisterLanguage(&MyCustomLanguage{}); err != nil { + panic(err) + } + + // Set it as active + _ = pluralizer.UseLanguage("my_custom_language") +} +``` + +## Supported Languages + +Currently, the pluralizer supports the following languages out of the box: + +| Language | Code | Source | +|:---------|:----------|:-------------------------------------------------------------------------------------------| +| English | `english` | [View Source](https://github.com/goravel/framework/tree/master/support/pluralizer/english) | + +*More languages will be added in future releases. You are welcome to contribute new languages via Pull Request.* \ No newline at end of file diff --git a/en/digging-deeper/processes.md b/en/digging-deeper/processes.md new file mode 100644 index 000000000..f4c020503 --- /dev/null +++ b/en/digging-deeper/processes.md @@ -0,0 +1,404 @@ +# Processes + +[[toc]] + +## Introduction + +Goravel provides an expressive and elegant API around Go's standard `os/exec` package, allowing you to invoke external commands from your application seamlessly. By default, Go's process handling can be verbose; Goravel's `Process` facade simplifies this common task, offering a fluent interface for executing commands, handling output, and managing asynchronous processes. + +## Invoking Processes + +### Running Processes + +To run a process, you can use the `Run` or `Start` methods. The `Run` method will execute the command and wait for it to finish, while the `Start` method triggers the process asynchronously and returns control immediately. + +Here is how you execute a blocking command: + +```go +import ( + "fmt" + + "goravel/app/facades" +) + +func main() { + result, err := facades.Process().Run("echo", "Hello, World!") + if err != nil { + panic(err) + } + + fmt.Println(result.Output()) +} +``` + +The `Run` method returns a `Result` interface and an `error`. The error will be non-nil if the process failed to start or encountered a system error. The `Result` interface gives you convenient access to the output and status of the command: + +```go +result, _ := facades.Process().Run("ls", "-la") + +result.Command() // string: The original command +result.Error() // error: The error returned by the command execution +result.ErrorOutput() // string: Output from Stderr +result.ExitCode() // int: The exit code (e.g., 0, 1) +result.Failed() // bool: True if the exit code was not 0 +result.Output() // string: Output from Stdout +``` + +### Process Options + +You often need to customize how a command runs, such as where it runs or what environment variables it sees. The `Process` facade provides a fluent API for this. + +#### Path +You can use the `Path` method to specify the working directory for the command. If you don't set this, the process will execute in the current working directory of your application. + +```go +result, _ := facades.Process().Path("/var/www/html").Run("ls", "-la") +``` + +#### Timeout +To prevent a process from hanging indefinitely, you can enforce a timeout. If the process runs longer than the specified duration, it will be killed. + +```go +import "time" + +result, _ := facades.Process().Timeout(10 * time.Mintue).Run("sleep", "20") +``` + +#### Environment Variables +You can pass custom environment variables to the process using the `Env` method. The process will also inherit the system's environment variables. + +```go +// Passes FOO=BAR along with existing system envs +result, _ := facades.Process().Env(map[string]string{ + "FOO": "BAR", + "API_KEY": "secret", +}).Run("printenv") +``` + +#### Input (Stdin) +If your command expects input from standard input (stdin), you can provide it using the `Input` method. This accepts an `io.Reader`. + +```go +import "strings" + +// Pipes "Hello Goravel" into the cat command +result, _ := facades.Process(). + Input(strings.NewReader("Hello Goravel")). + Run("cat") +``` + +### Process Output + +You can access the process output after execution using the `Output` (standard output) and `ErrorOutput` (standard error) methods on the result object. + +```go +result, _ := facades.Process().Run("ls", "-la"); + +fmt.Println(result.Output()) +fmt.Println(result.ErrorOutput()) +``` + +If you need to process the output in real-time (streaming), you may register a callback using the `OnOutput` method. The callback receives two arguments: the output type (stdout or stderr) and the byte slice containing the output data. + +```go +import ( + "fmt" + "github.com/goravel/framework/contracts/process" +) + +result, _ := facades.Process().OnOutput(func(typ process.OutputType, b []byte) { + // Handle real-time streaming here + fmt.Print(string(b)) +}).Run("ls", "-la") +``` + +If you only need to verify that the output contains a specific string after execution, you can use the `SeeInOutput` or `SeeInErrorOutput` helper methods. + +```go +result, _ := facades.Process().Run("ls", "-la") + +if result.SeeInOutput("go.mod") { + // The file exists +} +``` + +#### Disabling Process Output + +If your process writes a large amount of data, you may want to control how it is stored. + +Using `Quietly` will prevent the output from bubbling up to the console or logs during execution, but the data will still be collected and available via `result.Output()`. + +If you do not need to access the final output at all and want to save memory, you can use `DisableBuffering`. This prevents the output from being stored in the result object, though you can still inspect the stream in real-time using `OnOutput`. + +```go +// Captures output but doesn't print it during execution +facades.Process().Quietly().Run("...") + +// Does not capture output (saves memory), but allows streaming +facades.Process().DisableBuffering().OnOutput(func(typ process.OutputType, b []byte) { + // ... +}).Run("...") +``` + +### Pipelines + +Sometimes you need to pipe the output of one process into the input of another. The `Process` facade makes this easy +using the `Pipe` method, which allows you to chain multiple commands together synchronously. + +```go +import "github.com/goravel/framework/contracts/process" + +result, err := facades.Process().Pipe(func(pipe process.Pipe) { + pipe.Command("echo", "Hello, World!") + pipe.Command("grep", "World") + pipe.Command("tr", "a-z", "A-Z") +}).Run() +``` + +::: warning +Process options such as `Timeout`, `Env`, or `Input` must be configured **after** the `Pipe` method is called. +Any configuration applied before the `Pipe` call will be ignored. + +```go +// Correct: Configuration applied after Pipe +facades.Process().Pipe(...).Timeout(10 * time.Second).Run() + +// Incorrect: Timeout will be ignored +facades.Process().Timeout(10 * time.Second).Pipe(...).Run() +``` +::: + +#### Pipeline Output & Keys + +You can inspect the output of the pipeline in real-time using the `OnOutput` method. When used with a pipe, +the callback signature changes to include a `key` (string), allowing you to identify which command produced the output. + +By default, the `key` is the numeric index of the command. However, you can assign a readable label to each command +using the `As` method, which is highly useful for debugging complex pipelines. + +```go +facades.Process().Pipe(func(pipe process.Pipe) { + pipe.Command("cat", "access.log").As("source") + pipe.Command("grep", "error").As("filter") +}).OnOutput(func(typ process.OutputType, line []byte, key string) { + // 'key' will be "source" or "filter" +}).Run() +``` + +## Asynchronous Processes + +While the `Run` method waits for the process to complete, `Start` can be used to invoke a process asynchronously. +This allows the process to run in the background while your application continues executing other tasks. The `Start` method returns a `Running` interface. + +```go +import "time" + +process, _ := facades.Process().Timeout(10 * time.Second).Start("sleep", "5") + +// Continue doing other work... + +result := process.Wait() +``` + +To check if a process has finished without blocking, you may use the `Done` method. This returns a standard Go channel +that closes when the process exits, making it ideal for use in `select` statements. + +```go +process, _ := facades.Process().Start("sleep", "5") + +select { +case <-process.Done(): + // Process finished successfully +case <-time.After(1 * time.Second): + // Custom logic if it takes too long +} + +result := process.Wait() +``` + +::: warning +Even if you use the `Done` channel to detect completion, you **must** call `Wait()` afterwards. +This ensures the process is properly "reaped" by the operating system and cleans up underlying resources. +::: + +### Process IDs & Signals + +You can retrieve the operating system's process ID (PID) for a running process using the `PID` method. + +```go +process, _ := facades.Process().Start("ls", "-la") + +println(process.PID()) +``` + +#### Sending Signals + +Goravel provides methods to interact with the process lifecycle. You can send a specific OS signal using +the `Signal` method, or use the `Stop` helper to attempt a graceful shutdown. + +The `Stop` method is particularly useful: it will first send a termination signal (defaulting to `SIGTERM`). +If the process does not exit within the provided timeout, it will be forcibly killed (`SIGKILL`). + +```go +import ( + "os" + "time" +) + +process, _ := facades.Process().Start("sleep", "60") + +// Manually send a signal +process.Signal(os.Interrupt) + +// Attempt to stop gracefully, wait 5 seconds, then force kill +process.Stop(5 * time.Second) +``` + +### Checking Process State + +You can inspect the current state of the process using the `Running` method. This is primarily useful for debugging +or health checks, as it provides a snapshot of whether the process is currently active. + +```go +// Snapshot check (useful for logs or metrics) +if process.Running() { + fmt.Println("Process is still active...") +} +``` + +::: tip +If you need to execute code **when** the process finishes, do not poll `Running()`. Instead, use the `Done()` channel +or the `Wait()` method, which are much more efficient than repeatedly checking the status. +::: + +## Concurrent Processes + +Goravel makes it easy to manage a pool of concurrent processes, allowing you to execute multiple commands simultaneously. +This is particularly useful for batch processing or running independent tasks in parallel. + +### Executing Pools + +To run a pool of processes, you may use the `Pool` method. This accepts a closure where you define the commands you wish to execute. + +By default, the `Pool` method waits for all processes to complete and returns a map of results keyed by the process name (or index). + +```go +results, err := facades.Process().Pool(func(pool process.Pool) { + pool.Command("sleep", "1").As("first") + pool.Command("sleep", "2").As("second") +}).Run() + +if err != nil { + panic(err) +} + +// Access results by their assigned key +println(results["first"].Output()) +println(results["second"].Output()) +``` + +### Naming Processes + +By default, processes in a pool are keyed by their numeric index (e.g., "0", "1"). However, for clarity and easier access +to results, you should assign a unique name to each process using the `As` method: + +```go +pool.Command("cat", "system.log").As("system") +``` + +### Pool Options + +The `Pool` builder provides several methods to control the execution behavior of the entire batch. + +#### Concurrency +You can control the maximum number of processes running simultaneously using the `Concurrency` method. + +```go +facades.Process().Pool(func(pool process.Pool) { + // Define 10 commands... +}).Concurrency(2).Run() +``` + +#### Total Timeout +You can enforce a global timeout for the entire pool execution using the `Timeout` method. If the pool takes longer +than this duration, all running processes will be terminated. + +```go +facades.Process().Pool(...).Timeout(1 * time.Minute).Run() +``` + +### Asynchronous Pools + +If you need to run the pool in the background while your application performs other tasks, you can use the `Start` +method instead of `Run`. This returns a `RunningPool` handle. + +```go +runningPool, err := facades.Process().Pool(func(pool process.Pool) { + pool.Command("sleep", "5").As("long_task") +}).Start() + +// Check if the pool is still running +if runningPool.Running() { + fmt.Println("Pool is active...") +} + +// Wait for all processes to finish and gather results +results := runningPool.Wait() +``` + +#### Interacting with Running Pools + +The `RunningPool` interface provides several methods to manage the active pool: + +* **`PIDs()`**: Returns a map of Process IDs keyed by the command name. +* **`Signal(os.Signal)`**: Sends a signal to all running processes in the pool. +* **`Stop(timeout, signal)`**: Gracefully stops all processes. +* **`Done()`**: Returns a channel that closes when the pool finishes, useful for `select` statements. + +```go +select { +case <-runningPool.Done(): + // All processes finished +case <-time.After(10 * time.Second): + // Force stop all processes if they take too long + runningPool.Stop(1 * time.Second) +} +``` + +### Pool Output + +You can inspect the output of the pool in real-time using the `OnOutput` method. + +::: warning +The `OnOutput` callback may be invoked concurrently from multiple goroutines. Ensure your callback logic is thread-safe. +::: + +```go +facades.Process().Pool(func(pool process.Pool) { + pool.Command("ping", "google.com").As("ping") +}).OnOutput(func(typ process.OutputType, line []byte, key string) { + // key will be "ping" + fmt.Printf("[%s] %s", key, string(line)) +}).Run() +``` + +### Per-Process Configuration + +Inside the pool definition, each command supports individual configuration methods similar to single processes: + +* **`Path(string)`**: Sets the working directory. +* **`Env(map[string]string)`**: Sets environment variables. +* **`Input(io.Reader)`**: Sets standard input. +* **`Timeout(time.Duration)`**: Sets a timeout for the specific command. +* **`Quietly()`**: Disables output capturing for this specific command. +* **`DisableBuffering()`**: Disables memory buffering (useful for high-volume output). + +```go +facades.Process().Pool(func(pool process.Pool) { + pool.Command("find", "/", "-name", "*.log"). + As("search"). + Path("/var/www"). + Timeout(10 * time.Second). + DisableBuffering() +}).Run() +``` diff --git a/en/digging-deeper/queues.md b/en/digging-deeper/queues.md index 24a6d7a4a..9eec382b2 100644 --- a/en/digging-deeper/queues.md +++ b/en/digging-deeper/queues.md @@ -65,8 +65,21 @@ After implementing the custom driver, you can add the configuration to `config/q By default, all of the jobs for your application are stored in the `app/jobs` directory. If the `app/Jobs` directory doesn't exist, it will be created when you run the `make:job` Artisan command: ```shell -go run . artisan make:job ProcessPodcast -go run . artisan make:job user/ProcessPodcast +./artisan make:job ProcessPodcast +./artisan make:job user/ProcessPodcast +``` + +### Register Jobs + +A new job created by `make:job` will be registered automatically in the `bootstrap/jobs.go::Jobs()` function and the function will be called by `WithJobs`. You need register the job manually if you create the job file by yourself. + +```go +func Boot() contractsfoundation.Application { + return foundation.Setup(). + WithJobs(Jobs). + WithConfig(config.Boot). + Start() +} ``` ### Class Structure @@ -101,76 +114,24 @@ func (r *ProcessPodcast) ShouldRetry(err error, attempt int) (retryable bool, de } ``` -### Register Job - -After creating the job, you need to register it in `app/provides/queue_service_provider.go`, so that it can be called correctly. If the job is generated by the `make:job` command, the framework will automatically register it. - -```go -func (receiver *QueueServiceProvider) Jobs() []queue.Job { - return []queue.Job{ - &jobs.Test{}, - } -} -``` - ## Start Queue Server -Start the queue server in `main.go` in the root directory. +The default queue worker will be run by the runner of queue seriver provider, if you want to start multiple queue workers with different configuration, you can create [a runner](../architecture-concepts/service-providers.md#runners) and add it to the `WithRunners` function in the `bootstrap/app.go` file: ```go -package main - -import ( - "github.com/goravel/framework/facades" - - "goravel/bootstrap" -) - -func main() { - // This bootstraps the framework and gets it ready for use. - bootstrap.Boot() - - // Start queue server by facades.Queue(). - go func() { - if err := facades.Queue().Worker().Run(); err != nil { - facades.Log().Errorf("Queue run error: %v", err) - } - }() - - select {} +func Boot() contractsfoundation.Application { + return foundation.Setup(). + WithConfig(config.Boot). + WithRunners(func() []contractsfoundation.Runner { + return []contractsfoundation.Runner{ + YourRunner, + } + }). + Start() } ``` -Different parameters can be passed in the `facades.Queue().Worker` method, you can monitor multiple queues by starting multiple `facades.Queue().Worker`. - -```go -// No parameters, default listens to the configuration in the `config/queue.go`, and the number of concurrency is 1 -go func() { - if err := facades.Queue().Worker().Run(); err != nil { - facades.Log().Errorf("Queue run error: %v", err) - } -}() - -// Monitor processing queue for redis link, and the number of concurrency is 10, and the number of retries is 3 -go func() { - if err := facades.Queue().Worker(queue.Args{ - Connection: "redis", - Queue: "processing", - Concurrent: 10, - Tries: 3, - }).Run(); err != nil { - facades.Log().Errorf("Queue run error: %v", err) - } -}() -``` - -## Stop Queue Server - -When the queue server is running, you can stop the queue server by calling the `Shutdown` method, this method will wait for the current running tasks to complete before stopping the queue. - -```go -err := facades.Queue().Worker().Shutdown() -``` +You can check [the default queue runner](https://github.com/goravel/framework/blob/master/queue/runners.go) for reference. ## Dispatching Jobs @@ -182,8 +143,8 @@ package controllers import ( "github.com/goravel/framework/contracts/queue" "github.com/goravel/framework/contracts/http" - "github.com/goravel/framework/facades" + "goravel/app/facades" "goravel/app/jobs" ) @@ -208,8 +169,8 @@ package controllers import ( "github.com/goravel/framework/contracts/queue" "github.com/goravel/framework/contracts/http" - "github.com/goravel/framework/facades" + "goravel/app/facades" "goravel/app/jobs" ) diff --git a/en/digging-deeper/strings.md b/en/digging-deeper/strings.md index 63698ad1b..dc8d7fafd 100644 --- a/en/digging-deeper/strings.md +++ b/en/digging-deeper/strings.md @@ -537,6 +537,30 @@ str.Of("Goravel").Pipe(func(s string) string { }).String() // "Goravel Framework" ``` +### `Plural` + +The `Plural` method converts a singular string to its plural form. This function supports any of +the languages supported by the [pluralizer](pluralization.md). + +```go +import "github.com/goravel/framework/support/str" + +plural := str.Of("goose").Plural().String() +// "geese" +``` + +You may provide an integer argument to the function to retrieve the singular or plural form of the string: + +```go +import "github.com/goravel/framework/support/str" + +plural := str.Of("goose").Plural(2).String() +// "geese" + +plural = str.Of("goose").Plural(1).String() +// "goose" +``` + ### `Prepend` The `Prepend` method prepends the given value to the string. @@ -653,6 +677,18 @@ str.Of(" Goravel ").RTrim().String() // " Goravel" str.Of("/framework/").RTrim("/").String() // "/framework" ``` +### `Singular` + +The `Singular` method converts a string to its singular form. This function supports any of +the languages supported by the [pluralizer](pluralization.md). + +```go +import "github.com/goravel/framework/support/str" + +singular := str.Of("heroes").Singular().String() +// "hero" +``` + ### `Snake` The `Snake` method converts the string to `snake_case`. diff --git a/en/digging-deeper/task-scheduling.md b/en/digging-deeper/task-scheduling.md index 5ac10fae0..45d7e3e2c 100644 --- a/en/digging-deeper/task-scheduling.md +++ b/en/digging-deeper/task-scheduling.md @@ -10,28 +10,20 @@ Goravel's command scheduler offers a fresh approach to managing scheduled tasks ## Defining Schedules -To schedule tasks for your application, you can define them in the `Schedule` method in `app\console\kernel.go`. Let's consider an example to understand this better. In this case, we want to schedule a closure that will run every day at midnight. Inside this closure, we will execute a database query to clear a table: +To schedule tasks for your application, you can define them in the `WithSchedule` function in the `bootstrap/app.go` file. Let's consider an example to understand this better. In this case, we want to schedule a closure that will run every day at midnight. Inside this closure, we will execute a database query to clear a table: ```go -package console - -import ( - "github.com/goravel/framework/contracts/console" - "github.com/goravel/framework/contracts/schedule" - "github.com/goravel/framework/facades" - - "goravel/app/models" -) - -type Kernel struct { -} - -func (kernel Kernel) Schedule() []schedule.Event { - return []schedule.Event{ - facades.Schedule().Call(func() { - facades.Orm().Query().Where("1 = 1").Delete(&models.User{}) - }).Daily(), - } +func Boot() contractsfoundation.Application { + return foundation.Setup(). + WithSchedule(func() []schedule.Event { + return []schedule.Event{ + facades.Schedule().Call(func() { + facades.Orm().Query().Where("1 = 1").Delete(&models.User{}) + }).Daily(), + } + }). + WithConfig(config.Boot). + Start() } ``` @@ -40,22 +32,7 @@ func (kernel Kernel) Schedule() []schedule.Event { In addition to scheduling closures, you can also schedule [Artisan commands](./artisan-console.md). For example, you may use the `Command` method to schedule an Artisan command using either the command's name or class. ```go -package console - -import ( - "github.com/goravel/framework/contracts/console" - "github.com/goravel/framework/contracts/schedule" - "github.com/goravel/framework/facades" -) - -type Kernel struct { -} - -func (kernel *Kernel) Schedule() []schedule.Event { - return []schedule.Event{ - facades.Schedule().Command("send:emails name").Daily(), - } -} +facades.Schedule().Command("send:emails name").Daily(), ``` ### Logging Level @@ -144,64 +121,12 @@ facades.Schedule().Call(func() { ## Running The Scheduler -Now that we have learned how to define scheduled tasks, let's discuss how to actually run them on our server. - -Add `go facades.Schedule().Run()` to the root `main.go` file. - -```go -package main - -import ( - "github.com/goravel/framework/facades" - - "goravel/bootstrap" -) - -func main() { - // This bootstraps the framework and gets it ready for use. - bootstrap.Boot() - - // Start schedule by facades.Schedule - go facades.Schedule().Run() - - select {} -} -``` - -You can also use the `schedule:run` command to manually run tasks: +The scheduler will be run automatically when calling `Start()` in the `bootstrap/app.go` file. You can also run tasks manually : ```shell ./artisan schedule:run ``` -## Stopping The Scheduler - -You can call the `Shutdown` method to gracefully shut down the scheduler. This method will wait for all tasks to complete before shutting down. - -```go -// main.go -bootstrap.Boot() - -// Create a channel to listen for OS signals -quit := make(chan os.Signal) -signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM) - -// Start schedule by facades.Schedule -go facades.Schedule().Run() - -// Listen for the OS signal -go func() { - <-quit - if err := facades.Schedule().Shutdown(); err != nil { - facades.Log().Errorf("Schedule Shutdown error: %v", err) - } - - os.Exit(0) -}() - -select {} -``` - ## View All Tasks You can use the `schedule:list` command to view all tasks: diff --git a/en/getting-started/compile.md b/en/getting-started/compile.md index 54306a8df..046268496 100644 --- a/en/getting-started/compile.md +++ b/en/getting-started/compile.md @@ -6,21 +6,21 @@ The Goravel project can be compiled with the following command: -``` -// Select the system to compile -go run . artisan build +```shell +# Select the system to compile +./artisan build -// Specify the system to compile -go run . artisan build --os=linux -go run . artisan build -o=linux +# Specify the system to compile +./artisan build --os=linux +./artisan build -o=linux -// Static compilation -go run . artisan build --static -go run . artisan build -s +# Static compilation +./artisan build --static +./artisan build -s -// Specify the output file name -go run . artisan build --name=goravel -go run . artisan build -n=goravel +# Specify the output file name +./artisan build --name=goravel +./artisan build -n=goravel ``` ## Manual compilation @@ -36,11 +36,10 @@ go build . The Following files and folders need to be uploaded to the server during deployment: ``` -./main // Compile the resulting binary file .env -./public -./storage -./resources +./main // Compile the resulting binary file +./public // if exists +./resources // if exists ``` ### Static compilation @@ -94,12 +93,15 @@ RUN sed -i 's/dl-cdn.alpinelinux.org/mirrors.tuna.tsinghua.edu.cn/g' /etc/apk/re RUN apk add tzdata && cp /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \ && echo "Asia/Shanghai" > /etc/timezone WORKDIR /www +COPY --from=builder /build/.env /www/.env COPY --from=builder /build/main /www/ + +# If exists COPY --from=builder /build/database/ /www/database/ COPY --from=builder /build/public/ /www/public/ COPY --from=builder /build/storage/ /www/storage/ COPY --from=builder /build/resources/ /www/resources/ -COPY --from=builder /build/.env /www/.env + ENTRYPOINT ["/www/main"] ``` @@ -137,7 +139,3 @@ import ( _ "time/tzdata" ) ``` - -## Reduce package size - -Commenting out the unused `ServiceProvider` in `config/app.go::providers` will effectively reduce the packaging volume. diff --git a/en/getting-started/configuration.md b/en/getting-started/configuration.md index a423598c9..bdfecdb5e 100644 --- a/en/getting-started/configuration.md +++ b/en/getting-started/configuration.md @@ -16,6 +16,19 @@ Note that the `.env` file should not be added to version control, because when m In addition, if an intruder gains access to your code repository, there will be a risk of exposing sensitive configuration. If you want to add a new configuration item, you can add it to the `.env.example` file to synchronize the configuration of all developers. + +### Register Configuration + +All configuration files will be registered via the `WithConfig` function in the `bootstrap/app.go` file. Given that it's a `init` function in the config file, you don't need to register each configuration file one by one. Just call the `WithConfig` function as follows: + +```go +func Boot() contractsfoundation.Application { + return foundation.Setup(). + WithConfig(config.Boot). + Start() +} +``` + ## Retrieve Environment Configuration Use the following method to obtain the configuration items in the `.env` file: @@ -56,5 +69,5 @@ facades.Config().Add("path.with.dot", map[string]any{"case3": "value3"}) You can use the `artisan about` command to view the framework version, configuration, etc. ```bash -go run . artisan about +./artisan about ``` diff --git a/en/getting-started/directory-structure.md b/en/getting-started/directory-structure.md index 05d3fd9d5..24373e54c 100644 --- a/en/getting-started/directory-structure.md +++ b/en/getting-started/directory-structure.md @@ -6,62 +6,50 @@ The default file structure can make you better start project advancement, and you can also add new folders freely, but do not modify the default folders. -## Root Directory - -### `app` Directory - -`app` contains the core code of the program. Almost all the logic in the program will be in this folder. - -### `bootstrap` Directory - -The `bootstrap` directory contains the framework startup file `app.go`. - -### `config` Directory - -The `config` directory contains all configuration files of the application. It is best to browse through these files and familiarize yourself with all the available options. - -### `database` Directory - -The `database` directory contains database migration files. - -### `public` Directory - -The `public` directory contains some static resources, such as images, certificates, etc. - -### `resources` Directory - -The `resources` directory contains your [views](../the-basics/views.md) as well as your raw, un-compiled assets such as CSS or JavaScript. - -### `routes` Directory - -The `routes` directory contains all the route definitions of the application. - -### `storage` Directory - -The `storage` directory contains the `logs` directory, and the `logs` directory contains the application log files. - -### `tests` Directory - -The `tests` directory contains your automated tests. - -## `app` Directory - -### `console` Directory - -The `console` directory contains all the custom `Artisan` commands of the application, and the console boot file `kernel.go`, which can be registered in this file [Task Scheduling](../digging-deeper/task-scheduling.md) - -### `http` Directory - -The `http` directory contains controllers, middleware, etc., and almost all requests that enter the application via the Web are processed here. - -### `grpc` Directory - -The `grpc` directory contains controllers, middleware, etc., and almost all requests that enter the application via the Grpc are processed here. - -### `models` Directory - -The `models` directory contains all data models. - -### `providers` Directory - -The `providers` directory contains all [Service Providers](../architecture-concepts/service-providers.md) in the program. The service provider guides the application to respond to incoming requests by binding services, registering for events, or performing any other tasks. +## Folder Tree + +``` +goravel/ +├── app/ # Core application logic +│ ├── console/ # Artisan console commands +│ ├── grpc/ # gRPC controllers and middleware +│ ├── http/ # HTTP controllers and middleware +│ │ ├── controllers/ # HTTP request handlers +│ │ ├── middleware/ # HTTP middleware (auth, cors, etc.) +│ ├── models/ # Database models and ORM entities +│ └── providers/ # Service providers +├── bootstrap/ # Application bootstrapping +│ └── app.go # Framework initialization and startup +├── config/ # Application configuration files +├── database/ # Database related files +│ ├── migrations/ # Database migration files +│ ├── seeders/ # Database seeders +├── resources/ # Raw, uncompiled assets +│ └── views/ # View templates +├── routes/ # Application route definitions +├── storage/ # Application storage +├── tests/ # Automated tests +├── .air.toml # Air hot reload configuration +├── .env.example # Environment variables template +├── artisan # Artisan console entry script +├── go.mod # Go module dependencies +├── go.sum # Go module checksums +├── main.go # Application entry point +``` + +## Customize Directory Structure + +You can customize the directory structure by calling the `WithPath()` function in the `bootstrap/app.go` file. For example, if you want to change the default `app` directory to `src`, you can modify the `bootstrap/app.go` file as follows: + +```go +func Boot() contractsfoundation.Application { + return foundation.Setup(). + WithPaths(func(paths configuration.Paths) { + paths.App("src") + }). + WithConfig(config.Boot). + Start() +} +``` + +There are many other paths you can customize, such as `Config`, `Database`, `Routes`, `Storage`, and `Resources`. Just call the corresponding method on the `paths` object to set your desired directory. diff --git a/en/getting-started/installation.md b/en/getting-started/installation.md index fc35b9235..d97aee581 100644 --- a/en/getting-started/installation.md +++ b/en/getting-started/installation.md @@ -22,6 +22,10 @@ goravel new blog ### Manual Installation +#### goravel/goravel + +The complete framework with full features. + ```shell // Download framework git clone --depth=1 https://github.com/goravel/goravel.git && rm -rf goravel/.git* @@ -33,26 +37,47 @@ cd goravel && go mod tidy cp .env.example .env // Generate application key -go run . artisan key:generate +./artisan key:generate +``` + +#### goravel/goravel-lite + +The lite framework with only essential features, suitable for building microservices or small applications. You can install additional facades as needed. + +```shell +// Download framework +git clone --depth=1 https://github.com/goravel/goravel-lite.git && rm -rf goravel-lite/.git* +s +// Install dependencies +cd goravel-lite && go mod tidy + +// Create .env environment configuration file +cp .env.example .env + +// Generate application key +./artisan key:generate + +// Install additional facades as needed, for example: +./artisan package:install Cache ``` -Please confirm your network if you encounter slow download dependencies. +> Please confirm your network if you encounter slow download dependencies. -## Start HTTP Service +## Start Services -### Start Service According To .env File In The Root Directory +### Start Services According To .env File In The Root Directory ```shell go run . ``` -### Specify .env File To Start Service +### Specify .env File To Start Services ```shell go run . --env=./.env ``` -### Start Service Using Environment Variables +### Start Services Using Environment Variables ```shell APP_ENV=production APP_DEBUG=true go run . @@ -147,7 +172,7 @@ All configuration files of the Goravel framework are placed in the `config` dire You need to generate the application key after Goravel is installed locally. Running the command below, a 32-bit string will be generated on the `APP_KEY` key in the `.env` file. This key is mainly used for data encryption and decryption. ```shell -go run . artisan key:generate +./artisan key:generate ``` ### Generate JWT Token @@ -155,7 +180,7 @@ go run . artisan key:generate You need to generate JWT Token if you use [Authentication](../security/authentication.md). ```shell -go run . artisan jwt:secret +./artisan jwt:secret ``` ### Encrypt and decrypt env file @@ -163,17 +188,17 @@ go run . artisan jwt:secret You may want to add the production environment env file to version control, but you don't want to expose sensitive information, you can use the `env:encrypt` command to encrypt the env file: ```shell -go run . artisan env:encrypt +./artisan env:encrypt // Specify the file name and key -go run . artisan env:encrypt --name .env.safe --key BgcELROHL8sAV568T7Fiki7krjLHOkUc +./artisan env:encrypt --name .env.safe --key BgcELROHL8sAV568T7Fiki7krjLHOkUc ``` Then use the `env:decrypt` command to decrypt the env file in the production environment: ```shell -GORAVEL_ENV_ENCRYPTION_KEY=BgcELROHL8sAV568T7Fiki7krjLHOkUc go run . artisan env:decrypt +GORAVEL_ENV_ENCRYPTION_KEY=BgcELROHL8sAV568T7Fiki7krjLHOkUc ./artisan env:decrypt // or -go run . artisan env:decrypt --name .env.safe --key BgcELROHL8sAV568T7Fiki7krjLHOkUc +./artisan env:decrypt --name .env.safe --key BgcELROHL8sAV568T7Fiki7krjLHOkUc ``` diff --git a/en/getting-started/packages.md b/en/getting-started/packages.md index 628b9466f..ec4802cea 100644 --- a/en/getting-started/packages.md +++ b/en/getting-started/packages.md @@ -1,7 +1,8 @@ # Excellent Extend Packages You can find extended packages for Goravel here, and you can also create a PR for [goravel/docs](https://github.com/goravel/docs) to commit your owner package, please improve the test coverage of your package as much as possible. -| Package | Description | Test Coverage | + +| Package | Description | Test Coverage* | | --------------------------------------------------------------------------------- | --------------------------------------------- | ------------- | | [goravel/gin](https://github.com/goravel/gin) | The Gin driver for `facades.Route()` | 83.1% | | [goravel/fiber](https://github.com/goravel/fiber) | The Fiber driver for `facades.Route()` | 81.0% | @@ -11,13 +12,24 @@ You can find extended packages for Goravel here, and you can also create a PR fo | [goravel/s3](https://github.com/goravel/s3) | A S3 disk driver for `facades.Storage()` | 77.8% | | [goravel/oss](https://github.com/goravel/oss) | A OSS disk driver for `facades.Storage()` | 76.5% | | [goravel/installer](https://github.com/goravel/installer) | Goravel installer | 76.2% | -| [goravel/cloudinary](https://github.com/goravel/cloudinary) | A Cloudinary disk driver for `facades.Storage() | 75.4% | | [goravel/postgres](https://github.com/goravel/postgres) | A Postgres database driver | 73.7% | | [goravel/mysql](https://github.com/goravel/mysql) | A MySQL database driver | 73.3% | | [goravel/sqlserver](https://github.com/goravel/sqlserver) | A Sqlserver database driver | 60.6% | | [goravel/sqlite](https://github.com/goravel/sqlite) | A Sqlite database driver | 45.2% | +| [portofolio-mager/goravel-mongodb](https://github.com/portofolio-mager/goravel-mongodb) | A MongoDB package | 16.9% | | [hulutech-web/goravel-kit-cli](https://github.com/hulutech-web/goravel-kit-cli) | A goravel scaffold commandline tool | 15.2% | | [hulutech-web/goravel-workflow](https://github.com/hulutech-web/goravel-workflow) | A workflow package | 4.4% | | [hulutech-web/goravel-crud](https://github.com/hulutech-web/goravel-crud) | A goravel crud package | 4.2% | | [hulutech-web/tinker](https://github.com/hulutech-web/tinker) | A goravel tinker package | 3.6% | | [hulutech-web/goravel-socket](https://github.com/hulutech-web/goravel-socket) | A webSocket package | 0% | + +***Note**: The packages have been ordered based on their test rate. + +💡 Tip: To help more developers discover your work, you can also add relevant topics to your repository. +Recommended topic: [`goravel-package`](https://github.com/topics/goravel-package) + +- On GitHub, navigate to the main page of the repository. +- In the top right corner of the page, to the right of "About", click gear icon (settings). +- Under "Topics", start to type the topic you want to add to your repository to display a dropdown menu of any matching topics. +- Click the topic you want to add or continue typing to create a new topic. For example: `goravel-package`, `goravel` and any other relevant keywords. +- Click `Save changes` — this will make your package more discoverable. diff --git a/en/index.md b/en/index.md index 2b57bb024..a04908d40 100644 --- a/en/index.md +++ b/en/index.md @@ -49,7 +49,7 @@ head: hero: name: Goravel text: Full-featured Golang Development Framework - tagline: High-performance, full-featured, easy-to-extend, PHPers' first choice. + tagline: Componentization, High-performance, easy-to-extend, PHPers' first choice. # image: /logo.svg actions: - theme: brand @@ -60,14 +60,14 @@ hero: link: https://github.com/goravel/goravel target: _blank features: + - title: 💻 Componentization + details: Modular design, each module is independent and can be used separately, making development and maintenance more convenient. - title: 🚀 High-performance details: Built with Golang, integrating multiple excellent extensions to create fast and responsive applications. - title: 🧰 Full-featured details: Includes ORM, HTTP, queue, task scheduling, logging, caching, and other basic tools for all web development. - title: 📈 Easy-to-extend details: The module provides multiple drivers, and can develop extension packages according to needs, suitable for applications of any scale, from small projects to large systems. - - title: 💻 Easy-to-deploy - details: Provides multiple packaging commands, supports Docker image deployment, no additional dependencies. - title: 👥 Active community details: Supported by an active community, they contribute to its development, documentation, and continuous support. - title: 🔄 PHPers' first choice diff --git a/en/orm/getting-started.md b/en/orm/getting-started.md index 31284217c..1d13ca122 100644 --- a/en/orm/getting-started.md +++ b/en/orm/getting-started.md @@ -22,8 +22,8 @@ For example, the model name is `UserOrder`, and the table name is `user_orders`. Use the `make:model` command to create a model: ```shell -go run . artisan make:model User -go run . artisan make:model user/User +./artisan make:model User +./artisan make:model user/User ``` Created model file is located in `app/models/user.go` file, the content is as follows: @@ -103,27 +103,34 @@ func (r *UserData) Scan(value any) (err error) { ./artisan make:model --table=users -f User ``` -If the data table has a field type that the framework cannot recognize, you can call the `facades.Schema().Extend` method to extend the field type in the `Boot` method of the `app/providers/database_service_provider.go` file: +If the data table has a field type that the framework cannot recognize, you can call the `facades.Schema().Extend` method to extend the field type in the `bootstrap/app.go::WithCallback` function: ```go import "github.com/goravel/framework/contracts/schema" -facades.Schema().Extend(&schema.Extension{ - GoTypes: []schema.GoType{ - { - Pattern: "uuid", - Type: "uuid.UUID", - NullType: "uuid.NullUUID", - Imports: []string{"github.com/google/uuid"}, - }, - { - Pattern: "point", - Type: "geom.Point", - NullType: "*geom.Point", - Imports: []string{"github.com/twpayne/go-geom"}, - }, - }, -}) +func Boot() contractsfoundation.Application { + return foundation.Setup(). + WithConfig(config.Boot). + WithCallback(func() { + facades.Schema().Extend(&schema.Extension{ + GoTypes: []schema.GoType{ + { + Pattern: "uuid", + Type: "uuid.UUID", + NullType: "uuid.NullUUID", + Imports: []string{"github.com/google/uuid"}, + }, + { + Pattern: "point", + Type: "geom.Point", + NullType: "*geom.Point", + Imports: []string{"github.com/twpayne/go-geom"}, + }, + }, + }) + }). + Start() +} ``` ### Specify Table Name @@ -172,7 +179,7 @@ func (r *User) Connection() string { ### Setting Global Scope -Model supports setting the `GlobalScope` method, which restricts the scope of the query, update, and delete operations: +Model supports setting the `GlobalScopes` method, which restricts the scope of the query, update, and delete operations: ```go import "github.com/goravel/framework/contracts/orm" @@ -182,15 +189,25 @@ type User struct { Name string } -func (r *User) GlobalScopes() []func(orm.Query) orm.Query { - return []func(orm.Query) orm.Query{ - func(query orm.Query) orm.Query { +func (r *User) GlobalScopes() map[string]func(orm.Query) orm.Query { + return map[string]func(orm.Query) orm.Query{ + "name": func(query orm.Query) orm.Query { return query.Where("name", "goravel") }, } } ``` +If you want to remove global scopes in a query, you can use the `WithoutGlobalScopes` function: + +```go +// Remove all global scopes +facades.Orm().Query().WithoutGlobalScopes().Get(&users) + +// Remove specified global scope +facades.Orm().Query().WithoutGlobalScopes("name").Get(&users) +``` + ## facades.Orm() available functions | Name | Action | @@ -205,6 +222,7 @@ func (r *User) GlobalScopes() []func(orm.Query) orm.Query { | Functions | Action | | --------------------------- | ----------------------------------------------------------------------------- | +| Avg | [Avg](#Avarage) | | BeginTransaction | [Begin transaction](#transaction) | | Commit | [Commit transaction](#transaction) | | Count | [Count](#count) | @@ -229,6 +247,8 @@ func (r *User) GlobalScopes() []func(orm.Query) orm.Query { | Join | [Join](#join) | | Limit | [Limit](#limit) | | LockForUpdate | [Pessimistic Locking](#pessimistic-locking) | +| Max | [Max](#Avarage) | +| Min | [Min](#Avarage) | | Model | [Specify a model](#specify-table-query) | | Offset | [Offset](#offset) | | Order | [Order](#order) | @@ -255,14 +275,17 @@ func (r *User) GlobalScopes() []func(orm.Query) orm.Query { | Scopes | [Scopes](#scopes) | | Select | [Specify Fields](#specify-fields) | | SharedLock | [Pessimistic Locking](#pessimistic-locking) | -| Sum | [Sum](#sum) | +| Sum | [Sum](#Avarage) | | Table | [Specify a table](#specify-table-query) | | ToSql | [Get SQL](#get-sql) | | ToRawSql | [Get SQL](#get-sql) | | Update | [Update a single column](#update-a-single-column) | | UpdateOrCreate | [Update or create](#update-or-create) | | Where | [Where](#where) | +| WhereAll | [WhereAll](#where) | +| WhereAny | [WhereAny](#where) | | WhereBetween | [WhereBetween](#where) | +| WhereNone | [WhereNone](#where) | | WhereNotBetween | [WhereNotBetween](#where) | | WhereNotIn | [WhereNotIn](#where) | | WhereNull | [WhereNull](#where) | @@ -439,6 +462,18 @@ facades.Orm().Query().OrWhere("name", "tom") facades.Orm().Query().OrWhereNotIn("name", []any{"a"}) facades.Orm().Query().OrWhereNull("name") facades.Orm().Query().OrWhereIn("name", []any{"a"}) + +var products []Product +facades.DB().Table("products").WhereAll([]string{"weight", "height"}, "=", 200).Find(&products) +// SQL: SELECT * FROM products WHERE weight = ? AND height = ? + +var users []User +facades.DB().Table("users").WhereAny([]string{"name", "email"}, "=", "John").Find(&users) +// SQL: SELECT * FROM users WHERE (name = ? OR email = ?) + +var products []Product +facades.DB().Table("products").WhereNone([]string{"age", "score"}, ">", 18).Find(&products) +// SQL: SELECT * FROM products WHERE NOT (age > ?) AND NOT (score > ?) ``` Query JSON columns @@ -831,8 +866,8 @@ You can execute a transaction by `Transaction` function. ```go import ( "github.com/goravel/framework/contracts/database/orm" - "github.com/goravel/framework/facades" + "goravel/app/facades" "goravel/app/models" ) @@ -905,10 +940,20 @@ var users []models.User facades.Orm().Query().Where("votes > ?", 100).LockForUpdate().Get(&users) ``` -### Sum +### Avarage ```go -sum, err := facades.Orm().Query().Model(models.User{}).Sum("id") +var sum int +err := facades.Orm().Query().Model(models.User{}).Sum("id", &sum) + +var avg float64 +err := facades.Orm().Query().Model(models.User{}).Average("age", &avg) + +var max int +err := facades.Orm().Query().Model(models.User{}).Max("age", &max) + +var min int +err := facades.Orm().Query().Model(models.User{}).Min("age", &min) ``` ## Events @@ -986,8 +1031,8 @@ func (u *User) DispatchesEvents() map[contractsorm.EventType]func(contractsorm.E If you are listening to many events on a given model, you may use observers to group all of your listeners into a single class. Observer classes have method names that reflect the Eloquent events you wish to listen for. Each of these methods receives the affected model as their only argument. The `make:observer` Artisan command is the easiest way to create a new observer class: ```shell -go run . artisan make:observer UserObserver -go run . artisan make:observer user/UserObserver +./artisan make:observer UserObserver +./artisan make:observer user/UserObserver ``` This command will place the new observer in your `app/observers` directory. If this directory does not exist, Artisan will create it for you. Your fresh observer will look like the following: @@ -1022,31 +1067,16 @@ func (u *UserObserver) ForceDeleted(event orm.Event) error { The template observer only contains some events, you can add other events according to your needs. -To register an observer, you need to call the `Observe` method on the model you wish to observe. You may register observers in the `Boot` method of your application's `app/providers/event_service_provider.go::Boot` service provider: +To register an observer, you need to call the `Observe` method on the model you wish to observe. You can register observers in the `bootstrap/app.go::WithCallback` function: ```go -package providers - -import ( - "github.com/goravel/framework/facades" - - "goravel/app/models" - "goravel/app/observers" -) - -type EventServiceProvider struct { -} - -func (receiver *EventServiceProvider) Register(app foundation.Application) { - facades.Event().Register(receiver.listen()) -} - -func (receiver *EventServiceProvider) Boot(app foundation.Application) { - facades.Orm().Observe(models.User{}, &observers.UserObserver{}) -} - -func (receiver *EventServiceProvider) listen() map[event.Event][]event.Listener { - return map[event.Event][]event.Listener{} +func Boot() contractsfoundation.Application { + return foundation.Setup(). + WithConfig(config.Boot). + WithCallback(func() { + facades.Orm().Observe(models.User{}, &observers.UserObserver{}) + }). + Start() } ``` diff --git a/en/prologue/compare-with-laravel.md b/en/prologue/compare-with-laravel.md new file mode 100644 index 000000000..d50752d85 --- /dev/null +++ b/en/prologue/compare-with-laravel.md @@ -0,0 +1,40 @@ +# Compare With Laravel + +Goravel is heavily inspired by the Laravel framework, aiming to bring similar elegance and simplicity to Go developers. Here are some key comparisons between Goravel and Laravel to help you understand how Goravel aligns with Laravel's features: + +| Feature | Goravel | Laravel | Code Example | +|------------------------|----------------------------------|----------------------------------|----------------------------------| +| [Artisan Console](https://www.goravel.dev/digging-deeper/artisan-console.html) | ✅ | ✅ | ./artisan key:generate{{ .csrf_token }} to your form in the view file.
+3. The middleware will automatically verify the token on form submission.
## Register Custom Delims And Functions
diff --git a/en/upgrade/history.md b/en/upgrade/history.md
index d79286b2c..920e4b67f 100644
--- a/en/upgrade/history.md
+++ b/en/upgrade/history.md
@@ -1,5 +1,6 @@
# History Upgrade
+- [Upgrading To v1.15 From v1.14](v1.15.md)
- [Upgrading To v1.14 From v1.13](v1.14.md)
- [Upgrading To v1.13 From v1.12](v1.13.md)
- [Upgrading To v1.12 From v1.11](v1.12.md)
diff --git a/en/upgrade/v1.17.md b/en/upgrade/v1.17.md
new file mode 100644
index 000000000..9c334c0db
--- /dev/null
+++ b/en/upgrade/v1.17.md
@@ -0,0 +1,395 @@
+# Upgrading To v1.17 From v1.16
+
+## Exciting New Features 🎉
+
+- [Goravel Lite](#goravel-lite)
+- [Simplified Code Structure](#simplified-code-structure)
+- [Process Facade](#process-facade)
+- [Pluralizer Package](#pluralizer-package)
+- [Service Provider Runners](#service-provider-runners)
+
+## Enhancements 🚀
+
+- [facades can be installed and uninstalled as needed](#facades-can-be-installed-and-uninstalled-as-needed)
+- [Mail can be sent via template](#mail-can-be-sent-via-template)
+- [The build command supports more flags](#the-build-command-supports-more-flags)
+- [Add and modify functions for DB and Orm](#add-and-modify-functions-for-db-and-orm)
+- [Add new functions for Schema](#add-new-functions-for-schema)
+- [Add new commands](#add-new-commands)
+- [Add csrf token middleware](#add-csrf-token-middleware)
+- [Command supports configure Arguments](#command-supports-configure-arguments)
+- [make:migration supports create migration via model](#make-migration-supports-create-migration-via-model)
+- [Optimize gRPC client connections](#optimize-grpc-connections)
+- [Log supports print json format](#log-supports-print-json-format)
+- [Http supports multiple clients](#http-supports-multiple-clients)
+- [Validation supports pass context](#validation-supports-pass-context)
+- [Add WithoutGlobalScopes function for Orm](#add-withoutglobalscopes-function-for-orm)
+
+## Breaking Changes 🛠
+
+- [Remove machinery queue driver](#remove-machinery-queue-driver)
+- [Switch log driver](#switch-log-driver)
+- [Optimize migrate:rollback command](#optimize-migrate-rollback-command)
+- [Remove Http.Request.Bind function](#remove-http-request-bind-function)
+
+## Upgrade Guide
+
+As [Golang v1.23 is no longer maintained](https://endoflife.date/go), the Golang version of Goravel supports has been upgraded from 1.23 to 1.24.
+
+goravel/example project from v1.16 to v1.17 PR can be used as an upgrade reference: [goravel/example#93](https://github.com/goravel/example/pull/93).
+
+### 1. Update Dependencies
+
+```shell
+go get github.com/goravel/framework@latest
+
+// If using gin
+go get github.com/goravel/gin@latest
+
+// If using fiber
+go get github.com/goravel/fiber@latest
+
+// If using redis
+go get github.com/goravel/redis@latest
+
+// If using S3
+go get github.com/goravel/s3@latest
+
+// If using Oss
+go get github.com/goravel/oss@latest
+
+// If using Cos
+go get github.com/goravel/cos@latest
+
+// If using Minio
+go get github.com/goravel/minio@latest
+
+go mod tidy
+```
+
+### 2. Add New Service Providers
+
+```go
+// config/app.go
+import (
+ ...
+ "github.com/goravel/framework/facades/process"
+ "github.com/goravel/framework/facades/view"
+)
+
+"providers": []foundation.ServiceProvider{
+ ...
+ &process.ServiceProvider{}, // [!code ++]
+ &view.ServiceProvider{}, // [!code ++]
+},
+```
+
+### 3. Modify Http Client Configuration
+
+Add new configuration in `config/http.go`:
+
+```go
+"client": map[string]any{ // [!code --]
+ "base_url": config.GetString("HTTP_CLIENT_BASE_URL"), // [!code --]
+ "timeout": config.GetDuration("HTTP_CLIENT_TIMEOUT"), // [!code --]
+ "max_idle_conns": config.GetInt("HTTP_CLIENT_MAX_IDLE_CONNS"), // [!code --]
+ "max_idle_conns_per_host": config.GetInt("HTTP_CLIENT_MAX_IDLE_CONNS_PER_HOST"), // [!code --]
+ "max_conns_per_host": config.GetInt("HTTP_CLIENT_MAX_CONN_PER_HOST"), // [!code --]
+ "idle_conn_timeout": config.GetDuration("HTTP_CLIENT_IDLE_CONN_TIMEOUT"), // [!code --]
+}, // [!code --]
+"default_client": config.Env("HTTP_CLIENT_DEFAULT", "default"), // [!code ++]
+"clients": map[string]any{ // [!code ++]
+ "default": map[string]any{ // [!code ++]
+ "base_url": config.Env("HTTP_CLIENT_BASE_URL", ""), // [!code ++]
+ "timeout": config.Env("HTTP_CLIENT_TIMEOUT", "30s"), // [!code ++]
+ "max_idle_conns": config.Env("HTTP_CLIENT_MAX_IDLE_CONNS", 100), // [!code ++]
+ "max_idle_conns_per_host": config.Env("HTTP_CLIENT_MAX_IDLE_CONNS_PER_HOST", 2), // [!code ++]
+ "max_conns_per_host": config.Env("HTTP_CLIENT_MAX_CONN_PER_HOST", 0), // [!code ++]
+ "idle_conn_timeout": config.Env("HTTP_CLIENT_IDLE_CONN_TIMEOUT", "90s"), // [!code ++]
+ }, // [!code ++]
+}, // [!code ++]
+```
+
+### 4. If you want to send mail via template
+
+Add new configuration in `config/mail.go`:
+
+```go
+// Template Configuration
+//
+// This controls template rendering for email views. Template engines are cached
+// globally and support both built-in drivers and custom implementations via factories.
+//
+// Available Drivers: "html", "custom"
+"template": map[string]any{
+ "default": config.Env("MAIL_TEMPLATE_ENGINE", "html"),
+ "engines": map[string]any{
+ "html": map[string]any{
+ "driver": "html",
+ "path": config.Env("MAIL_VIEWS_PATH", "resources/views/mail"),
+ },
+ },
+},
+```
+
+### 5. If you are using machinery queue driver
+
+Need to modify accordingly: [Remove machinery queue driver](#remove-machinery-queue-driver)
+
+### 6. If you created a custom log driver
+
+Need to modify accordingly: [Switch log driver](#switch-log-driver)
+
+### 7. If you are using Http.Request.Bind function
+
+Need to modify accordingly: [Remove Http.Request.Bind function](#remove-http-request-bind-function)
+
+### 8. If you are using validation.Make function or custom rules/filters
+
+Need to modify accordingly: [Validation supports pass context](#validation-supports-pass-context)
+
+### 9. If you are using global scopes in Orm
+
+Need to modify accordingly: [Add WithoutGlobalScopes function for Orm](#add-withoutglobalscopes-function-for-orm)
+
+## Feature Introduction
+
+### Goravel Lite
+
+We are excited to introduce [Goravel Lite](https://github.com/goravel/goravel-lite), a lightweight version of the Goravel framework, designed for developers who want to build applications with minimal dependencies and a smaller footprint. It provides the core features of Goravel while allowing developers to add only the components they need.
+
+- Only includes essential facades: `Artisan`, `Config`, reducing bloat and improving performance.
+- Other facades can be installed and uninstalled as needed via the `package:install` and `package:uninstall` commands.
+- `goravel/goravel` == `goravel/goravel-lite` + all facades. Any improvements for `goravel/goravel` should be submitted to `goravel/goravel-lite`, then a specify github action will sync the changes to `goravel/goravel`. And `goravel/goravel` is still the main repository for users to use Goravel framework.
+- `goravel/installer` will use `goravel/goravel-lite` as the default framework to create new Goravel projects, users can choose to install needed facades.
+
+### Simplified code structure
+
+The code structure has been simplified to improve maintainability and readability to consitent with Laravel. The old structure can still be used, it's a backward compatible change. It's a bit complicated to migrate from old structure to new structure, there is an example PR for reference if needed: [goravel/example#91](https://github.com/goravel/example/pull/91).
+
+1. Remove all `kenel.go` and default `*_service_providers.go` files. Move configurations in `*_service_providers.go` files to the `bootstrap` folder.
+2. Move all facades from framework intenal to the `app/facades` folder, users can customize or extend them as needed.
+3. Simplify the facades startup process, no need to run facades in `main.go` anymorem, please refer to [Service Provider Runners](../architecture-concepts/service-providers.md#runners) for more details.
+4. Support customize directory structure via the `WithPath()` function, please refer to [Customize Directory Structure](../getting-started/directory-structure.md#customize-directory-structure) for more details.
+
+### Process Facade
+
+Goravel now provides an expressive and elegant API around Go's standard `os/exec` package, allowing you to invoke external commands from your application seamlessly.
+
+[View Document](../digging-deeper/processes.md)
+
+### Pluralizer package
+
+Goravel now includes a pluralizer package that helps with converting words between singular and plural forms based on language rules. This is useful for applications that need to handle different languages and their grammatical rules.
+
+[View Document](../digging-deeper/pluralization.md)
+
+### Service Provider Runners
+
+Service Providers can now implement the `Runners` interface to run code when the application starts. This is typically used to start or shutdown services defined in the Service Provider, such as Route, Schedule, Queue, etc. You no longer need to start or shutdown these services manually in `main.go`, as Goravel will handle it for you.
+
+This feature is only available when using [the new simplified code structure](#simplified-code-structure).
+
+[View Document](../architecture-concepts/service-providers.md#runners)
+
+### Log supports print json format
+
+Goravel's logging system now supports outputting logs in JSON format, making it easier to integrate with log management systems and perform structured logging.
+
+```go
+"channels": map[string]any{
+ "daily": map[string]any{
+ "driver": "daily",
+ "path": "storage/logs/goravel.log",
+ "level": config.Env("LOG_LEVEL", "debug"),
+ "days": 7,
+ "print": true,
+ // the value can be "text" or "json"
+ "formatter": "json", // [!code ++]
+ },
+},
+```
+
+### Http supports multiple clients
+
+Goravel's HTTP client module now supports multiple clients, allowing you to define and use different HTTP clients with their own configurations for various purposes within your application.
+
+[View Document](../digging-deeper/http-client.md#making-requests)
+
+### Validation supports pass context
+
+Goravel's validation module now supports passing context to validation functions, enabling more flexible and dynamic validation scenarios based on the context of the request or operation.
+
+```go
+validator, err := facades.Validation().Make(input, rules) // [!code --]
+validator, err := facades.Validation().Make(ctx, input, rules) // [!code ++]
+```
+
+Custom rules and filters also support context parameter:
+
+```go
+type Rule interface {
+ Signature() string
+ Passes(data Data, val any, options ...any) bool // [!code --]
+ Message() string // [!code --]
+ Passes(ctx context.Context, data Data, val any, options ...any) bool // [!code ++]
+ Message(ctx context.Context) string // [!code ++]
+}
+
+type Filter interface {
+ Signature() string
+ Handle() any // [!code --]
+ Handle(ctx context.Context) any // [!code ++]
+}
+```
+
+### Add WithoutGlobalScopes function for Orm
+
+A new `WithoutGlobalScopes` function has been added to the Orm package, allowing you to exclude all global scopes from a query. This is useful when you want to retrieve records without the constraints imposed by global scopes.
+
+```go
+var user []User
+err := facades.Orm().Model(&User{}).WithoutGlobalScopes().Get(&user)
+err := facades.Orm().Model(&User{}).WithoutGlobalScopes("name").Get(&user)
+```
+
+In order to support set global scope name, the `GlobalScope` interface of model has been modified:
+
+```go
+import "github.com/goravel/framework/contracts/orm"
+
+type User struct {
+ orm.Model
+ Name string
+}
+
+func (r *User) GlobalScopes() []func(orm.Query) orm.Query { // [!code --]
+func (r *User) GlobalScopes() map[string]func(orm.Query) orm.Query { // [!code ++]
+ return map[string]func(orm.Query) orm.Query{
+ "name": func(query orm.Query) orm.Query {
+ return query.Where("name", "goravel")
+ },
+ }
+}
+```
+
+### facades can be installed and uninstalled as needed
+
+Follow the release of [Goravel Lite](#goravel-lite), now facades can be installed and uninstalled as needed via the `package:install` and `package:uninstall` commands. Notice: this feature is only available when you project is built with Goravel Lite or upgrades to [the new simplified code structure](#simplified-code-structure).
+
+[View Document](../architecture-concepts/facades.md#install-uninstall-facades)
+
+### Mail can be sent via template
+
+Mail sending now supports templates, allowing you to send emails using predefined templates for better consistency and easier management. The template supports http and custom drivers.
+
+[View Document](../digging-deeper/mail.md#using-template)
+
+### The build command supports more flags
+
+Add new `--arch` and `--static` flags to the `build` command, allowing you to specify the target architecture and whether to build a static binary.
+
+### Add and modify functions for DB and Orm
+
+New functions:
+
+- `Avg(column string, dest any) error`: Calculate the average value of a column.
+- `Min(column string, dest any) error`: Find the minimum value of a column.
+- `Max(column string, dest any) error`: Find the maximum value of a column.
+- `WhereAll(columns []string, args ...any) Query`: Adds a "where all columns match" clause to the query.
+- `WhereAny(columns []string, args ...any) Query`: Adds a "where any column matches" clause to the query.
+- `WhereNone(columns []string, args ...any) Query`: Adds a "where none of the columns match" clause to the query.
+
+Modified functions:
+
+```go
+// Before
+Sum(column string) (int64, error)
+
+// After
+Sum(column string, dest any) error
+```
+
+### Add new functions for Schema
+
+New functions have been added to the Schema package to enhance database schema management capabilities.
+
+- `DateTimes`: Create `created_at` and `updated_at` columns on the table.
+- `ForeignID`: Create an unsigned big integer column for foreign keys.
+- `ForeignUlid`: Create a ULID column for foreign keys.
+- `ForeignUuid`: Create a UUID column for foreign keys.
+
+### Add new commands
+
+- `make:provider`: Create a new service provider class.
+- `make:view`: Create a new view template file.
+
+### Add csrf token middleware
+
+A new middleware has been added to protect against Cross-Site Request Forgery (CSRF) attacks. This middleware can be applied to routes to ensure that requests are coming from authenticated sources.
+
+[View Document](../the-basics/views.md#csrf-token-middleware)
+
+### Command supports configure Arguments
+
+Commands now support configuring arguments, allowing you to define and handle command-line arguments more effectively within your custom commands.
+
+[View Document](../digging-deeper/artisan-console.md#arguments)
+
+### make:migration supports create migration via model
+
+The `make:migration` command has been enhanced to support creating migrations based on existing models. This allows for quicker migration creation by leveraging the structure defined in your models.
+
+[View Document](../database/migrations.md#create-migrations)
+
+### Optimize gRPC client connections
+
+A client connection pool has been implemented for gRPC clients to optimize performance and resource utilization. This allows for reusing existing connections rather than creating new ones for each request, reducing latency and improving efficiency.
+
+### Remove machinery queue driver
+
+The machinery queue driver has been removed totally given it's deprecated in v1.16. Please follow the guidelines in the [v1.16 upgrade document](./v1.16.md#optimize-queue-module-configuration) to migrate to other queue drivers if you are still using it.
+
+### Switch log driver
+
+The log driver has been switched from `logrus` to `log/slog` for better performance and structured logging capabilities.
+
+The custom log driver interface has been modified:
+
+```go
+// framework/contracts/log/Logger
+package log
+
+type Logger interface {
+ // Handle pass channel config path here
+ Handle(channel string) (Hook, error) // [!code --]
+ Handle(channel string) (Handler, error) // [!code ++]
+}
+```
+
+You can use `log.HookToHandler` function to adapt old custom log drivers:
+
+```go
+type CustomLogger struct {}
+
+func (logger *CustomLogger) Handle(channel string) (log.Handler, error) {
+ hook := /* your old custom log driver logic */
+
+ return log.HookToHandler(hook), nil
+}
+```
+
+### Optimize migrate:rollback command
+
+Previously, the `migrate:rollback` command only rolls back one migration at a time, it's not consistent with Laravel's behavior. Now the command will roll back all migrations from the last batch by default. You can still use the `--step` option to specify the number of batches to roll back.
+
+### Remove Http.Request.Bind function
+
+The `Bind` function on the `Http.Request` interface has been removed. You can now use the `Bind` method via `response`.
+
+```go
+var user User
+response, err := facades.Http().Bind(&user).Get("https://github.com") // [!code --]
+response, err := facades.Http().Get("https://github.com") // [!code ++]
+err = response.Bind(&user) // [!code ++]
+```