# Upgrade Guide
Although Goyave is developed with backwards compatibility, breaking changes can happen, especially in the project's early days. This guide will help you to upgrade your applications using older versions of the framework. Bear in mind that if you are several versions behind, you will have to follow the instructions for each in-between versions.
# v2.x.x to v3.0.0
First, replace github.com/System-Glitch/goyave/v2
with github.com/System-Glitch/goyave/v3
.
# Routing changes
Routing has been improved by changing how validation and route-specific middleware are registered. The signature of the router functions have been simplified by removing the validation and middleware parameters from Route()
, Get()
, Post()
, etc. This is now done through two new chainable methods on the Route
:
router.Post("/echo", hello.Echo, hellorequest.Echo)
// Becomes
router.Post("/echo", hello.Echo).Validate(hello.EchoRequest)
router.Post("/echo", hello.Echo, nil, middleware.Trim, middleware.Gzip())
// Becomes
router.Post("/echo", hello.Echo).Middleware(middleware.Trim, middleware.Gzip())
router.Post("/echo", hello.Echo, hellorequest.Echo, middleware.Trim)
// Becomes
router.Post("/echo", hello.Echo).Validate(hello.EchoRequest).Middleware(middleware.Trim)
# Convention changes
This release brought changes to the conventions. Although your applications can still work with the old ones, it's recommended to make the change.
- Move
validation.go
andplaceholders.go
to a newhttp/validation
package. Don't forget to change thepackage
instruction in these files. - In
kernel.go
, import yourhttp/validation
package instead ofhttp/request
. - Validation rule sets are now located in a
request.go
file in the same package as the controller. So if you hadhttp/request/productrequest/product.go
, take the content of that file and move it tohttp/controller/product/request.go
. Rule sets are now named after the name of the controller handler they will be used with, and end withRequest
. For example, a rule set for theStore
handler will be namedStoreRequest
. If a rule set can be used for multiple handlers, consider using a name suited for all of them. The rules for a store operation are often the same for update operations, so instead of duplicating the set, create one unique set calledUpsertRequest
. You will likely just have to addRequest
at the end of the name of your sets. - Update your route definition by changing the rule sets you use.
router.Post("/echo", hello.Echo, hellorequest.Echo)
// Becomes
router.Post("/echo", hello.Echo).Validate(hello.EchoRequest)
# Validation changes
Although the validation changes are internally huge, there is only a tiny amount of code to change to update your application. You will have to update all your handlers accessing the request.Rules
field. This field is no longer a validation.RuleSet
and has been changed to *validation.Rules
, which will be easier to use, as the rules are already parsed. Refer to the alternative validation syntax documentation for more details about this new structure.
- The following rules now pass if the validated data type is not supported:
greater_than
,greater_than_equal
,lower_than
,lower_than_equal
,size
.
# Configuration changes
The new configuration system does things very differently internally, but should not require too many changes to make your project compatible. First, you will have to update your configuration files. Here is an example of configuration file containing all the core entries:
{
"app": {
"name": "goyave_template",
"environment": "localhost",
"debug": true,
"defaultLanguage": "en-US"
},
"server": {
"host": "127.0.0.1",
"maintenance": false,
"protocol": "http",
"domain": "",
"port": 8080,
"httpsPort": 8081,
"timeout": 10,
"maxUploadSize": 10,
"tls": {
"cert": "/path/to/cert",
"key": "/path/to/key"
},
},
"database": {
"connection": "mysql",
"host": "127.0.0.1",
"port": 3306,
"name": "goyave",
"username": "root",
"password": "root",
"options": "charset=utf8mb4&collation=utf8mb4_general_ci&parseTime=true&loc=Local",
"maxOpenConnections": 20,
"maxIdleConnections": 20,
"maxLifetime": 300,
"autoMigrate": false
}
}
If you were using any of the configuration entries above in your code, you should update the keys used in the calls of config.Get()
, config.GetString()
, config.Bool()
and config.Has()
. Keys are now dot-separated paths. For example, to access the database host
entry, the key is database.host
.
For more information, refer to the configuration reference.
If you are using the auth
package (basic auth, JWT), you will need to update your configuration entries too.
authUsername
becomesauth.basic.username
authPassword
becomesauth.basic.password
jwtExpiry
becomesauth.jwt.expiry
jwtSecret
becomesauth.jwt.secret
{
...
"auth": {
"jwt": {
"expiry": 300,
"secret": "jwt-secret"
},
"basic": {
"username": "admin",
"password": "admin"
}
}
}
Finally, config.Register()
function has changed signature. See the configuration documentation for more details on how to migrate.
# Minor changes
- Recovery middleware now correctly handles panics with a
nil
value. You may have to update your custom status handler for the HTTP500
error code. - Log
Formatter
now receive the length of the response (in bytes) instead of the full body.log.Formatter
is nowfunc(now time.Time, response *goyave.Response, request *goyave.Request, length int) string
.- If you were just using
len(body)
, just replace it withlength
. - If you were using the content of the body in your logger, you will have to implement a chained writer.
- Removed deprecated method
goyave.CreateTestResponse()
. Usegoyave.TestSuite.CreateTestResponse()
instead.
# v1.0.0 to v2.0.0
This first update comes with refactoring and package renaming to better fit the Go conventions.
goyave.Request.URL()
has been renamed togoyave.Request.URI()
.goyave.Request.URL()
is now a data accessor for URL fields.
- The
helpers
package has been renamed tohelper
.- The
filesystem
package thus has a different path:github.com/System-Glitch/goyave/v2/helper/filesystem
.
- The
TIP
Because this version contains breaking changes. Goyave had to move to v2.0.0
. You need to change the path of your imports to upgrade.
Change github.com/System-Glitch/goyave
to github.com/System-Glitch/goyave/v2
.