Upgrading To v1.15 From v1.14

Exciting New Features 🎉

Enhancements 🚀

Breaking Changes 🛠

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"))

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",
++ },
  1. 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:

return facades.Schema().Sql({SQL})
  1. 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{},
  }
}
  1. 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())
++ }

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 Sqlserver
++ "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 Sqlserver 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()