Upgrading To v1.15 From v1.14

Exciting New Features 🎉

• Migration supports using Go language migration
• Testing supports HTTP testing

Enhancements 🚀

• HTTP supports return Stream
• HTTP supports setting timeout
• HTTP supports setting custom recovery method
• Request supports configure Filter
• Request adds the BindQuery method
• Validation supports Regex rules
• Schedule supports control log output
• Schedule adds the Shutdown method
• Mail supports Mailable template
• The trace in error log output supports jumping
• Log supports printing key-value pairs in Context
• Support directly setting DSN to connect to the database
• The Create method of Orm supports using map to create
• Orm adds configuration items
• Orm adds Restore method
• Orm's Log integrated Log module
• Postgres and Sqlserver drivers support Schema
• Add about command
• Add db:show command
• Add db:table command
• Optimize Artisan output style
• Auth adds the Id method
• Multiple Auth.Guard can set their own TTL

Breaking Changes 🛠

• The name of Postgresql driver changes to Postgres
• Modify the Orm.Transaction method callback parameter type
• Optimize the Delete and ForceDelete methods of Orm
• Optimize the Decrement and Increment methods of Cache
• Optimize the Call method of Artisan
• Rename the Clear method of Testing.Database to Shutdown
• Optimize the Build method of Testing.Database
• Optimize the Request.Input* method
• Optimize the validation.PrepareForValidation method
• Optimize the Worker method of the Queue module

v1.15.3

• Go Migration supports Boolean field
• Go Migration supports custom field
• Optimize Artisan log output rules

v1.15.4

Upgrade the related packages: goravel/gin: v1.3.3, goravel/fiber: v1.3.3

• Fix the problem that ctx is nil in PrepareForValidation
• Fix the problem that the Orm WithContext method reports an error in Fiber driver under high concurrency
• Optimize the packaging volume
• Optimize the problem that the model ID is nested multiple times
• Add artisan command alias

v1.15.5

Upgrade the related packages: goravel/redis: v1.3.1, goravel/fiber: v1.3.4

• Fix the problem that Throttle fails to store in Redis driver
• Fix the problem that Fallback fails to work in Fiber driver

v1.15.6

• Fix the problem that the Orm WithContext method reports an error in concurrent execution

Upgrade Guide

Estimated Upgrade Time: 10 Minutes

As Golang v1.21 is no longer maintained, the Golang version of Goravel supports has been upgraded from 1.21 to 1.22. Please update the version in the go.mod file.

1. Updating Dependencies

go get -u github.com/goravel/framework@v1.15.2

// If using gin
go get -u github.com/goravel/gin@v1.3.2

// If using fiber
go get -u github.com/goravel/fiber@v1.3.2

// If using redis
go get -u github.com/goravel/redis@v1.3.0

// If using S3
go get -u github.com/goravel/s3@v1.3.2

// If using Oss
go get -u github.com/goravel/oss@v1.3.2

// If using Cos
go get -u github.com/goravel/cos@v1.3.2

// If using Minio
go get -u github.com/goravel/minio@v1.3.2

// If using Cloudinary
go get -u github.com/goravel/cloudinary@v1.3.1

go mod tidy

2. If you are using the Postgresql driver

Need to modify accordingly: The name of Postgresql driver changes to Postgres

3. If you are using the Orm.Transaction method

Need to modify accordingly: Modify the Orm.Transaction method callback parameter type

4. If you are using the Delete or ForceDelete method of Orm

Need to modify accordingly: Optimize the Delete and ForceDelete methods of Orm

5. If you are using the Decrement and Increment methods of Cache

Need to modify accordingly: Optimize the Decrement and Increment methods of Cache

6. If you are using the Worker method of the Queue module

Need to modify accordingly: Optimize the Worker method of the Queue module

7. If you are using the Call method of Artisan

Need to modify accordingly: Optimize the Call method of Artisan

8. If you are using the Clear method of Testing.Database

Need to modify accordingly: Rename the Clear method of Testing.Database to Shutdown

9. If you are using the Build method of Testing.Database

Need to modify accordingly: Optimize the Build method of Testing.Database

10. If you are using the Migration module

Modify the configuration in config/database.go:

-- "migrations": "migrations",
++ "migrations": map[string]any{
++  "driver": "sql",
++  "table":  "migrations",
++ },

11. If you are using the Request.Input* method

Need to modify accordingly: Optimize the Request.Input* method

12. If you are using the validation.PrepareForValidation method

Need to modify accordingly: Optimize the validation.PrepareForValidation method

13. If you are using the Mail module

Modify the way Subject is set:

-- import "github.com/goravel/framework/contracts/mail"
++ import "github.com/goravel/framework/mail"

-- Content(mail.Content{Subject: "Subject", Html: "<h1>Hello Goravel</h1>"})
++ Content(mail.Html("<h1>Hello Goravel</h1>")).Subject("Subject")

If you are using the From method:

-- import "github.com/goravel/framework/contracts/mail"
++ import "github.com/goravel/framework/mail"

-- From(mail.From{Address: testFromAddress, Name: testFromName}
++ From(mail.Address(testFromAddress, testFromName)

If you are using the Queue method:

-- import "github.com/goravel/framework/contracts/mail"
++ import "github.com/goravel/framework/mail"

-- Queue(mail.Queue{Connection: "high", Queue: "mail"})
++ Queue(mail.Queue().Connection("high").Queue("mail"))

14. If you are using the validation.PrepareForValidation method

Need to modify accordingly: Optimize the validation.PrepareForValidation method

Feature Introduction

Migration supports using Go language migration

Previously, the framework only supported SQL migrations. When you wanted to switch databases, the differences in SQL syntax between different databases made the migration process extremely difficult. In addition, code could not be executed in migration files, making it impossible to perform logical judgments when repairing data.

Now, the framework supports generating migration files directly using Go language, making it easy for developers to write complex migration logic. However, in the current version, the modification of table fields has not been implemented, only supporting operations such as creating tables, deleting tables, and creating indexes. If you want to make modifications, you need to use the Sql method to execute SQL statements directly. The ability to modify table fields will be supported in future versions.

In version v1.15, the framework supports both Go language migration (default) and SQL migration, but SQL migration will be removed in version v1.16.

Switching from SQL migration to Go language migration

If you are using SQL migration, you can switch to Go language migration by following these steps:

1. Modify the configuration in config/database.go;

-- "migrations": "migrations",
++ "migrations": map[string]any{
++  "driver": "default",
++  "table":  "migrations",
++ },

2. Use the go run . artisan make:migration {NAME} command to create a migration file;

Execute the migration and rollback statements in the original SQL migration file in the Up and Down methods of the generated file, and use the facades.Schema().HasTable method to check if the table exists:

func (r *M20241207095921CreateUsersTable) Up() error {
  if !facades.Schema().HasTable("users") {
    return facades.Schema().Sql({SQL})
  }

  return nil
}

3. Register the migration file in the database/kernel.go file;

Create a new database/kernel.go file and register migration files and Seeders:

package database

import (
  "github.com/goravel/framework/contracts/database/schema"
  "github.com/goravel/framework/contracts/database/seeder"

  "goravel/database/migrations"
  "goravel/database/seeders"
)

type Kernel struct {
}

func (kernel Kernel) Migrations() []schema.Migration {
  return []schema.Migration{
    &migrations.M20241207095921CreateUsersTable{},
  }
}

func (kernel Kernel) Seeders() []seeder.Seeder {
  return []seeder.Seeder{
    &seeders.DatabaseSeeder{},
  }
}

4. Modify the app/providers/database_service_provider.go file to complete the registration, and move the Seeder originally registered here to database/kernel.go::Seeders;

-- func (receiver *DatabaseServiceProvider) Boot(app foundation.Application) {
--  facades.Seeder().Register([]seeder.Seeder{
--   &seeders.DatabaseSeeder{},
--  })
-- }
++ func (receiver *DatabaseServiceProvider) Boot(app foundation.Application) {
++  kernel := database.Kernel{}
++  facades.Schema().Register(kernel.Migrations())
++  facades.Seeder().Register(kernel.Seeders())
++ }

5. Backup the existing migrations table data, then delete the migrations table;

6. Execute the go run . artisan migrate command to perform the migration, after the migration is complete, a new migrations table will be generated.

View Documentation

Testing supports HTTP testing

goravel/framework: v1.15.0

The framework has added the Testing.Http module, which supports testing HTTP requests, allowing you to simulate requests, get responses, and assert responses.

View Documentation

HTTP supports return Stream

goravel/framework: v1.15.0

View Documentation

HTTP supports setting timeout

goravel/framework: v1.15.0

You can set the timeout time by configuring http.request_timeout in the config/http.go file, which defaults to 3 seconds.

HTTP supports setting custom recovery method

goravel/framework: v1.15.0

View Documentation

Request supports configure Filter

goravel/framework: v1.15.0

View Documentation

Request adds the BindQuery method

goravel/framework: v1.15.0

Support using ctx.Request().BindQuery() to bind parameters directly from the link.

View Documentation

Validation supports Regex rules

goravel/framework: v1.15.0

validator, err := ctx.Request().Validate(map[string]string{
  "code": `required|regex:^\d{4,6}$`,
})

Schedule supports control log output

goravel/framework: v1.15.0

When app.debug is false, only error level logs will be output.

Schedule adds the Shutdown method

goravel/framework: v1.15.0

The Shutdown method can be used to gracefully stop the Schedule.

View Documentation

Mail supports Mailable template

goravel/framework: v1.15.0

View Documentation

The trace in error log output supports jumping

goravel/framework: v1.15.0

In the error log output, clicking on the trace will jump to the line of code where the error occurred.

Log supports printing key-value pairs in Context

goravel/framework: v1.15.0

ctx.WithValue("a", "b")
facades.Log().WithContext(ctx).Info("Hello Goravel")

// Output: 
[2024-12-15 16:36:58] local.info: Hello Goravel 
Context: map[a:b]

Support directly setting DSN to connect to the database

goravel/framework: v1.15.0

View Documentation

The Create method of Orm supports using map to create

goravel/framework: v1.15.0

View Documentation

Orm adds configuration items

goravel/framework: v1.15.0

The configurations are for specific situations and are not required for normal use, not add them to the configuration file by default.

// config/database.go
"{driver_name}": map[string]any{
  "driver":   "{driver_name}",
  "host":     config.Env("DB_HOST", "127.0.0.1"),
  ...
++ "schema": "goravel",// Set the default schema for the connection, only for Postgres and SQL Server
++ "no_lower_case": false,// Set whether to convert the table name to lowercase
++ "name_replacer": strings.NewReplacer("id", "ID"),// Set the columns name replacement
},

Orm adds Restore method

goravel/framework: v1.15.0

Add the Restore method to the Orm module, which can be used to restore soft deleted data, and add Restored, Restoring events.

View Documentation

Orm's Log integrated Log module

goravel/framework: v1.15.0

Previously, Orm's log output was directly output to the console, now Orm's log output will be integrated into the Log module, and can be printed to the console and log file at the same time.

Postgres and SQL Server drivers support Schema

goravel/framework: v1.15.0

View Documentation

Add about command

goravel/framework: v1.15.0

Add the about command, which can be used to view the framework version, configuration, etc.

go run . artisan about

Add db:show command

goravel/framework: v1.15.0

Add the db:show command, which can be used to view the database connection information.

go run . artisan db:show

Add db:table command

goravel/framework: v1.15.0

Add the db:table command, which can be used to view the table structure.

go run . artisan db:table
go run . artisan db:table users

Optimize Artisan output style

goravel/framework: v1.15.0

Optimize Artisan output style, add color, making the output more beautiful.

Auth adds the Id method

goravel/framework: v1.15.0

id, err := facades.Auth(ctx).ID()

Multiple Auth.Guard can set their own TTL

goravel/framework: v1.15.0

Previously, multiple Guards shared the jwt.ttl configuration. Now you can set the TTL for each Guard separately by setting it in the config/auth.go file. If not set, the jwt.ttl configuration will be used by default.

// config/auth.go
"guards": map[string]any{
  "user": map[string]any{
    "driver": "jwt",
++  "ttl": 60,
  },
},

The name of Postgresql driver changes to Postgres

goravel/framework: v1.15.0

The name of the Postgresql driver has been changed to postgres. If you are using the Postgresql driver, you need to modify the configration file:

// config/database.go
"postgres": map[string]any{
  -- "driver":   "postgresql",
  ++ "driver":   "postgres",
  "host":     config.Env("DB_HOST", "127.0.0.1"),
}

Modify the Orm.Transaction method callback parameter type

goravel/framework: v1.15.0

The facades.Orm().Transaction() method callback parameter type has been changed from func(tx orm.Transaction) error to func(tx orm.Query) error, if you are using this method, please modify accordingly.

-- facades.Orm().Transaction(func(tx orm.Transaction) error {
++ facades.Orm().Transaction(func(tx orm.Query) error {
  var user models.User

  return tx.Find(&user, user.ID)
})

Optimize the Delete and ForceDelete methods of Orm

goravel/framework: v1.15.0

If you are passing an ID to the Delete or ForceDelete method to delete data, use the Where method instead:

-- facades.Orm().Query().Delete(&models.User{}, 10)
++ facades.Orm().Query().Where("id", 10).Delete(&models.User{})

-- facades.Orm().Query().Delete(&models.User{}, []uint{1, 2, 3})
++ facades.Orm().Query().WhereIn("id", []uint{1, 2, 3}).Delete(&models.User{})

-- facades.Orm().Query().ForceDelete(&models.User{}, 10)
++ facades.Orm().Query().ForceDelete("id", 10).Delete(&models.User{})

Delete and ForceDelete methods support deleting data without passing parameters:

res, err := facades.Orm().Query().Model(&models.User{}).Where("id", 1).Delete()
res, err := facades.Orm().Query().Table("users").Where("id", 1).Delete()

Optimize the Decrement and Increment methods of Cache

goravel/framework: v1.15.0

The input and output types of the Decrement and Increment methods have been changed from int to int64:

-- Decrement(key string, value ...int) (int, error)
++ Decrement(key string, value ...int64) (int64, error)

-- Increment(key string, value ...int) (int, error)
++ Increment(key string, value ...int64) (int64, error)

Optimize the Call method of Artisan

goravel/framework: v1.15.0

The facades.Artisan().Call() method will panic if an error is encountered during execution. It now returns an error, so handle the error if you are using this method.

err := facades.Artisan().Call("command:name")

Rename the Clear method of Testing.Database to Shutdown

goravel/framework: v1.15.0

In order to keep the method name consistent with other modules, we renamed the Clear method to Shutdown.

database, err := facades.Testing().Docker().Database()
-- err := database.Clear()
++ err := database.Shutdown()

Optimize the Build method of Testing.Database

goravel/framework: v1.15.0

Previously, when calling the Build method, the database migration would be performed automatically. After the upgrade, you need to manually call the Migrate method to perform the migration, making database control more flexible.

database, err := facades.Testing().Docker().Database()
err := database.Build()
++ err := database.Migrate()

Optimize the Request.Input* method

goravel/framework: v1.15.0

goravel/gin: v1.3.0

goravel/fiber: v1.3.0

Previously, the Request.Input* method could only get data from the Body, now it will look for data in the Body, Query, and Param in order. Previously, when passing a second parameter (default value) to the Request.Input* method, if the key existed but was empty, the default value would be returned. Now, an empty string will be returned, as an empty string is also a valid value, only when the key does not exist, the default value will be returned.

You need to check all the places where the Request.Input* method is used to ensure that the parameters passed are correct and the return values are as expected.

Optimize the validation.PrepareForValidation method

goravel/framework: v1.15.0

Modify the input parameter type and add the http.Context parameter:

import github.com/goravel/framework/validation

-- validator, err := facades.Validation().Make(input, rules, validation.PrepareForValidation(func(data validationcontract.Data) error {
++ validator, err := facades.Validation().Make(input, rules, validation.PrepareForValidation(func(ctx http.Context, data validationcontract.Data) error {
  if name, exist := data.Get("name"); exist {
 return data.Set("name", name)
  }

  return nil
}))

Optimize the Worker method of the Queue module

goravel/framework: v1.15.0

When the Worker method does not need to set parameters, it can be kept empty:

-- facades.Queue().Worker(nil).Run()
++ facades.Queue().Worker().Run()

When you need to set parameters, the parameters are changed from pointers to instances:

-- facades.Queue().Worker(&queue.Args{Connection: "redis").Run()
++ facades.Queue().Worker(queue.Args{Connection: "redis").Run()

Go Migration supports Boolean field

goravel/framework: v1.15.3

table.Boolean("is_admin")

Go Migration supports custom field

goravel/framework: v1.15.3

If you are using column types that framework does not support yet, you can use the Column method to customize the field type:

table.Column("geometry", "geometry")

Optimize Artisan log output rules

goravel/framework: v1.15.3

Previously, Artisan log only output error level logs, now all levels of logs will be output. If you want to disable console printing logs and are using the single or daily log driver, please set the logging.channels.single.print or logging.channels.daily.print configuration to false.

Fix the problem that ctx is nil in PrepareForValidation

goravel/framework: v1.15.4

goravel/gin: v1.3.3

goravel/fiber: v1.3.3

Before the fix, ctx was always nil in the PrepareForValidation method, now it will be correctly passed as a parameter. If you are using the validation.PrepareForValidation method, please modify accordingly.

import (
  github.com/goravel/framework/validation
  contarctsvalidate "github.com/goravel/framework/contracts/validation"
)

-- validation.PrepareForValidation(func(ctx http.Context, data contarctsvalidate.Data) error {
++ validation.PrepareForValidation(ctx, func(ctx http.Context, data contarctsvalidate.Data) error {

Fix the problem that the Orm WithContext method reports an error in Fiber driver under high concurrency

goravel/framework: v1.15.4

goravel/fiber: v1.3.3

For details: #866

Optimize the packaging volume

goravel/framework: v1.15.4

For details: #865

Optimize the problem that the model ID is nested multiple times

goravel/framework: v1.15.4

For details: #898

Add artisan command alias

goravel/framework: v1.15.4

// Before
go run  . artisan key:generate

// After
./artisan key:generate

Fix the problem that Throttle fails to store in Redis driver

goravel/framework: v1.15.5

goravel/redis: v1.3.1

When using the Redis driver, Throttle fails to store normally, causing the limit to fail.

Issue: #625

Fix the problem that Fallback fails to work in Fiber driver

goravel/framework: v1.15.5

goravel/fiber: v1.3.4

When using the Fiber driver, if Fallback is set, other routes will fail to work.

Issue: #624

Fix the problem that the Orm WithContext method reports an error in concurrent execution

goravel/framework: v1.15.6

When using the WithContext method to set Context, it was reported an error in concurrent execution.