Goravel

https://www.goravel.dev
Admin
Goravel is a scalable web application framework designed for Gophers, providing a comprehensive set...
Tokens:188,992
Snippets:2,710
Trust Score:7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Package Installation Logic

Source: https://www.goravel.dev/digging-deeper/package-development.html

Defines package installation and uninstallation logic. It registers service providers, publishes config files, and handles their removal. This setup is executed via the `package:install` command.

```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() {
	// Initialize setup to get paths, this should be called at the beginning.
	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)
	}

	serviceProvider := "&hello.ServiceProvider{}"
	moduleImport := setup.Paths().Module().Import()

	setup.Install(
		// Register the service provider to the providers slice in bootstrap/providers.go
		modify.RegisterProvider(moduleImport, serviceProvider),

		// 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(),

		// Unregister the service provider from the providers slice in bootstrap/providers.go
		modify.UnregisterProvider(moduleImport, serviceProvider),
	).Execute()
}

```

--------------------------------

### Package Setup with Import Aliases

Source: https://www.goravel.dev/upgrade/v1.18.html

Package setup helpers now support import aliases in the format `"<alias> <import-path>"`. This is useful for improving readability when package import paths are long or a custom reference name is desired. This example demonstrates registering and unregistering a provider using an alias.

```go
serviceProvider := "&admin.ServiceProvider{}"
moduleImport := "admin " + setup.Paths().Module().Import()

setup.Install(
    modify.RegisterProvider(moduleImport, serviceProvider),
).Uninstall(
    modify.UnregisterProvider(moduleImport, serviceProvider),
).Execute()
```

--------------------------------

### Serve Command Implementation

Source: https://www.goravel.dev/digging-deeper/artisan-console.html

Example implementation of a Serve command that starts an HTTP server and supports graceful shutdown. It embeds context.Context and implements the Shutdownable interface.

```go
package commands

import (
  "errors"
  "net/http"

  "github.com/goravel/framework/contracts/console"
  "github.com/goravel/framework/contracts/console/command"
)

type Serve struct {
  server *http.Server
}

func (r *Serve) Signature() string   { return "serve" }
func (r *Serve) Description() string { return "Start the HTTP server" }
func (r *Serve) Extend() command.Extend {
  return command.Extend{Category: "server"}
}

func (r *Serve) Handle(ctx console.Context) error {
  if err := r.server.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
    return err
  }
  return nil
}

func (r *Serve) Shutdown(ctx console.Context) error {
  ctx.Info("received signal, shutting down gracefully...")
  return r.server.Shutdown(ctx)
}
```

--------------------------------

### Start a New Session

Source: https://www.goravel.dev/the-basics/session.html

Create a session instance using BuildSession and then start it using the Start method.

```go
session := facades.Session().BuildSession(driver)
session.Start()
```

--------------------------------

### Install All Facades

Source: https://www.goravel.dev/architecture-concepts/facades.html

Use the Artisan CLI to install all available facades.

```shell
# Install all facades
./artisan package:install --all
```

--------------------------------

### Install Goravel Package

Source: https://www.goravel.dev/digging-deeper/package-development.html

Users can install packages with a `setup/setup.go` file using the `package:install` command. This command automates the registration of service providers and publishing of configuration files.

```shell
./artisan package:install github.com/goravel/example-package
```

--------------------------------

### Install All Facades with Default Drivers

Source: https://www.goravel.dev/architecture-concepts/facades.html

Use the Artisan CLI to install all facades and apply their default drivers.

```shell
# Install all facades with default drivers
./artisan package:install --all --default
```

--------------------------------

### ORM Query Example

Source: https://www.goravel.dev/upgrade/v1.10.html

Demonstrates how to initialize and use the ORM query builder. This is a basic example of setting up a query.

```go
query := facades.Orm.Query()
query = query.Where()
```

--------------------------------

### Install AI SDK Facade and Provider

Source: https://www.goravel.dev/upgrade/v1.18.html

Install the AI SDK facade using Artisan and then install a specific provider package like goravel/openai.

```shell
go run .artisan package:install AI
```

--------------------------------

### Manual Installation of Goravel Lite Framework

Source: https://www.goravel.dev/getting-started/installation.html

Downloads the Goravel Lite framework, installs dependencies, sets up the .env file, generates the application key, and optionally installs additional facades.

```shell
git clone --depth=1 https://github.com/goravel/goravel-lite.git && rm -rf goravel-lite/.git*
s
cd goravel-lite && go mod tidy
cp .env.example .env
./artisan key:generate

// Install additional facades as needed, for example:
./artisan package:install Cache
```

--------------------------------

### Live Reload with Air

Source: https://www.goravel.dev/getting-started/installation.html

Starts the application with live reloading capabilities using the Air tool. Assumes Air is installed.

```shell
air
```

--------------------------------

### Manual Installation of Goravel Framework

Source: https://www.goravel.dev/getting-started/installation.html

Downloads the complete Goravel framework, installs dependencies, sets up the .env file, and generates the application key.

```shell
git clone --depth=1 https://github.com/goravel/goravel.git && rm -rf goravel/.git*
cd goravel && go mod tidy
cp .env.example .env
./artisan key:generate
```

--------------------------------

### Install Telemetry Package

Source: https://www.goravel.dev/digging-deeper/telemetry.html

Install the optional telemetry module using the `package:install` command. This command sets up configuration files, facade, service provider registration, and logging channel.

```shell
./artisan package:install Telemetry
```

--------------------------------

### Ensure String Starts with Prefix

Source: https://www.goravel.dev/digging-deeper/strings.html

The `Start` method prepends a given string to the target string only if it doesn't already start with it.

```go
import "github.com/goravel/framework/support/str"

str.Of("framework").Start("/").String() // "/framework"

str.Of("/framework").Start("/").String() // "/framework"
```

--------------------------------

### Localization Get Example

Source: https://www.goravel.dev/prologue/compare-with-laravel.html

Compares retrieving a translated string in Goravel and Laravel.

```go
facades.Lang(ctx).Get("messages.welcome")
```

```php
__('messages.welcome')
```

--------------------------------

### View Make Example

Source: https://www.goravel.dev/prologue/compare-with-laravel.html

Shows how to render a view in Goravel and Laravel.

```go
ctx.Response().View().Make("welcome.tmpl")
```

```php
view('welcome')
```

--------------------------------

### Install All Agent Skills

Source: https://www.goravel.dev/prologue/contributions.html

Install all available Goravel agent skills to the default directory at ~/.agents/skills.

```shell
goravel skill:install
```

--------------------------------

### Create New Goravel Project

Source: https://www.goravel.dev/getting-started/installation.html

Initializes a new Goravel project named 'blog' in the current directory using the installed Goravel installer.

```shell
goravel new blog
```

--------------------------------

### OpenAI Provider Configuration Example

Source: https://www.goravel.dev/ai/sdk.html

Example configuration for the OpenAI provider in `config/ai.go`. It includes API key, failover rules, base URL, and model settings. Ensure provider credentials are added to `.env`.

```go
package config

import (
    "github.com/goravel/framework/contracts/ai"
    openaifacades "github.com/goravel/openai/facades"
    "goravel/app/facades"
)

func init() {
    config := facades.Config()
    config.Add("ai", map[string]any{
        "default": "openai",
        "providers": map[string]any{
            "openai": map[string]any{
                "key": config.Env("OPENAI_API_KEY", ""),
                "failover": map[string][]string{
                    "context_length_exceeded": {
                        "maximum context length",
                        "/(?i)context.*length/",
                    },
                },
                "url": config.Env("OPENAI_BASE_URL", ""),
                "via": func() (ai.Provider, error) {
                    return openaifacades.OpenAI("openai")
                },
                "models": map[string]any{
                    "text": map[string]any{
                        "default": "",
                        "max_tokens": 0,
                    },
                    "audio": map[string]any{
                        "default": "",
                    },
                    "transcription": map[string]any{
                        "default": "",
                    },
                    "image": map[string]any{
                        "default": "",
                    },
                },
            },
        },
    })
}
```

--------------------------------

### Install/Uninstall Postgres Service Provider (Bootstrap Setup)

Source: https://www.goravel.dev/upgrade/v1.17.html

Use this snippet to register or unregister the Postgres service provider when using the bootstrap setup. It directly registers the provider using the module import path.

```go
    modify.When(func(_ map[string]any) bool {
      return env.IsBootstrapSetup()
    }, modify.RegisterProvider(moduleImport, postgresServiceProvider))
```

--------------------------------

### Install package service provider to bootstrap/providers.go

Source: https://www.goravel.dev/upgrade/v1.17.html

When Simplified Code Structure is launched, package service providers can be installed to 'bootstrap/providers.go' instead of 'config/app.go'. The 'packages.GetModulePath()' function is removed; use 'setup.Paths().Module().Import()' instead.

```go
// setup/setup.go
package main

import (
  "os"

  "github.com/goravel/framework/packages"
  "github.com/goravel/framework/packages/match"
  "github.com/goravel/framework/packages/modify"
  "github.com/goravel/framework/support/path"
)

func main() {
  // Initialize setup to get paths, this should be called at the beginning.
  setup := packages.Setup(os.Args) 

  appConfigPath := path.Config("app.go")
  postgresServiceProvider := "&postgres.ServiceProvider{}"

  // In the new code structures, the GetModulePath function is removed, use setup.Paths().Module().Import() instead
  modulePath := packages.GetModulePath() 
  moduleImport := setup.Paths().Module().Import() 

  packages.Setup(os.Args).Install( 
  setup.Install( 
      // Add postgres service provider
      modify.GoFile(appConfigPath). 
        Find(match.Imports()).Modify(modify.AddImport(modulePath)). 
        Find(match.Providers()).Modify(modify.Register(postgresServiceProvider)), 
      modify.RegisterProvider(moduleImport, postgresServiceProvider), 
      ...
    ).
    Uninstall(
      // Remove postgres service provider
      modify.GoFile(appConfigPath). 
        Find(match.Providers()).Modify(modify.Unregister(postgresServiceProvider)). 
        Find(match.Imports()).Modify(modify.RemoveImport(modulePath)), 
      modify.UnregisterProvider(moduleImport, postgresServiceProvider), 
      ...
    ).
    Execute()
}

```

--------------------------------

### User Authentication Example

Source: https://www.goravel.dev/prologue/compare-with-laravel.html

Illustrates how to log in a user in Goravel and Laravel.

```go
facades.Auth(ctx).Login(&user)
```

```php
Auth::login($user)
```

--------------------------------

### Process Run Example

Source: https://www.goravel.dev/prologue/compare-with-laravel.html

Shows how to run an external process or command in Goravel and Laravel.

```go
facades.Process().Run("ls", "-la")
```

```php
`Process::run('ls -la')`
```

--------------------------------

### Example Artisan Command Usage

Source: https://www.goravel.dev/digging-deeper/artisan-console.html

Illustrates how to pass arguments to an Artisan command.

```shell
./artisan send:emails SUBJECT EMAIL_1 EMAIL_2
```

--------------------------------

### Install AI Facade

Source: https://www.goravel.dev/ai/sdk.html

Installs the AI facade and core service provider using the Artisan command. This makes `facades.AI()` available and registers `make:agent` and `make:tool` commands.

```shell
./artisan package:install AI
```

--------------------------------

### Install Postgres Driver

Source: https://www.goravel.dev/upgrade/v1.16.html

Install the PostgreSQL driver package if you plan to use it for your database connections.

```shell
go get github.com/goravel/postgres
```

--------------------------------

### Making GET Requests

Source: https://www.goravel.dev/digging-deeper/http-client.html

Demonstrates how to perform a basic GET request to a specified URL.

```APIDOC
## GET Request

### Description
Performs an HTTP GET request to the specified URL.

### Method
GET

### Endpoint
`https://example.com`

### Request Example
```go
response, err := facades.Http().Get("https://example.com")
```

### Response Interface
The `framework/contracts/http/client.Response` interface provides methods to interact with the response, such as `Status()`, `Body()`, `Json()`, `Header()`, and more.
```

--------------------------------

### Install a Specific Facade

Source: https://www.goravel.dev/architecture-concepts/facades.html

Use the Artisan CLI to install a specific facade, such as the Route facade.

```shell
# Install a specific facade
./artisan package:install Route
```

--------------------------------

### Start Services Specifying .env File

Source: https://www.goravel.dev/getting-started/installation.html

Starts the Goravel application services using a specified .env file, useful for custom configurations.

```shell
go run . --env=./.env
```

--------------------------------

### Example HTML Email Template

Source: https://www.goravel.dev/digging-deeper/mail.html

An example of an HTML template file for an email, demonstrating the use of Go's template syntax for dynamic data insertion.

```html
<!-- resources/views/mail/welcome.html -->
<h1>Welcome {{.Name}}!</h1>
<p>Thank you for joining {{.AppName}}.</p>
```

--------------------------------

### Install Telemetry Module Facade

Source: https://www.goravel.dev/upgrade/v1.18.html

Install the Telemetry module facade using the Artisan command. This enables the collection of traces, metrics, and logs.

```shell
go run . artisan package:install Telemetry
```

--------------------------------

### Package Installation with Import Alias

Source: https://www.goravel.dev/digging-deeper/package-development.html

Demonstrates using an import alias for long or inconvenient package import paths. The alias is used consistently during installation and uninstallation.

```go
func main() {
	setup := packages.Setup(os.Args)

	serviceProvider := "&admin.ServiceProvider{}"
	moduleImport := "admin " + setup.Paths().Module().Import()

	setup.Install(
		modify.RegisterProvider(moduleImport, serviceProvider),
	).Uninstall(
		modify.UnregisterProvider(moduleImport, serviceProvider),
	).Execute()
}

```

--------------------------------

### Start Pool Asynchronously and Wait

Source: https://www.goravel.dev/digging-deeper/processes.html

Use the `Start` method to run a process pool in the background. It returns a `RunningPool` handle that can be used to check status and wait for completion.

```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()
```

--------------------------------

### Install AI Provider Packages

Source: https://www.goravel.dev/ai/sdk.html

Installs at least one AI provider package, such as OpenAI, Anthropic, or Gemini. This is required before prompting an agent.

```shell
./artisan package:install github.com/goravel/openai
./artisan package:install github.com/goravel/anthropic
./artisan package:install github.com/goravel/gemini
```

--------------------------------

### Seeder Call Example

Source: https://www.goravel.dev/prologue/compare-with-laravel.html

Demonstrates calling a seeder to populate the database in Goravel and Laravel.

```go
facades.Seeder().Call([]seeder.Seeder{&User{}})
```

```php
$this->call([User::class])
```

--------------------------------

### Application Bootstrapping with Providers

Source: https://www.goravel.dev/architecture-concepts/service-providers.html

The `Boot` function in `bootstrap/app.go` sets up the application, including loading service providers and configuration.

```go
func Boot() contractsfoundation.Application {
	return foundation.Setup().
		WithProvders(Providers).
		WithConfig(config.Boot).
		Create()
}
```

--------------------------------

### Docker Compose Build and Up

Source: https://www.goravel.dev/getting-started/compile.html

Build and start the Goravel application services using Docker Compose.

```shell
docker-compose build
docker-compose up
```

--------------------------------

### Logger Info Example

Source: https://www.goravel.dev/prologue/compare-with-laravel.html

Shows how to log an informational message in Goravel and Laravel.

```go
facades.Log().Info("message")
```

```php
Log::info('message')
```

--------------------------------

### Start an Asynchronous Process

Source: https://www.goravel.dev/digging-deeper/processes.html

Use `Start` to run a process in the background without blocking. It returns a `Running` interface that can be used to wait for completion or check status. Ensure `Wait()` is called after detecting completion to clean up resources.

```go
import "time"

running, err := facades.Process().Timeout(10 * time.Second).Start("sleep", "5")

// Continue doing other work...

result := running.Wait()
```

--------------------------------

### Default Function Example

Source: https://www.goravel.dev/digging-deeper/helpers.html

Use convert.Default to get the first non-zero value from a list of arguments. Returns the zero value if all provided values are zero.

```go
import "github.com/goravel/framework/support/convert"

func main() {
    convert.Default("", "foo")

    convert.Default("bar", "foo")

    convert.Default(0, 1)
}
```

--------------------------------

### Apply a Prefix to Routes

Source: https://www.goravel.dev/the-basics/routing.html

Add a common prefix to a set of routes. This example applies the 'users' prefix to a GET route, meaning the route will be accessible at /users.

```go
facades.Route().Prefix("users").Get("/", userController.Show)
```

--------------------------------

### Event Dispatch Example

Source: https://www.goravel.dev/prologue/compare-with-laravel.html

Shows how to dispatch an event in Goravel and Laravel.

```go
facades.Event().Job(&events.Order{}).Dispatch()
```

```php
Order::dispatch()
```

--------------------------------

### Define Route Returning JSON Collection

Source: https://www.goravel.dev/testing/http-tests.html

Example of defining a route that returns a JSON response containing a collection of items. This setup is used for testing collection assertions.

```go
type Item struct {
    ID int `json:"id"`
}

facades.Route().Get("/", func(ctx http.Context) http.Response {
    items := []Item{
        {ID: 1},
        {ID: 2},
    }
    return ctx.Response().Json(200, map[string]interface{}{
		"items": items,
    })
})
```

--------------------------------

### Define Routes within a Group

Source: https://www.goravel.dev/the-basics/routing.html

Organize related routes by grouping them. This example shows a single GET route within a group, demonstrating how to use the router instance provided to the group function.

```go
facades.Route().Group(func(router route.Router) {
  router.Get("group/{id}", func(ctx http.Context) http.Response {
    return ctx.Response().Success().String(ctx.Request().Query("id", "1"))
  })
})
```

--------------------------------

### Install Goravel Installer

Source: https://www.goravel.dev/getting-started/installation.html

Installs the latest version of the Goravel installer globally. This is the first step for using the Goravel installer method.

```shell
go install github.com/goravel/installer/goravel@latest
```

--------------------------------

### Configured WeatherTool with parameters and execution

Source: https://www.goravel.dev/ai/sdk.html

This example shows a more complete WeatherTool definition, including a specific name ('get_weather'), a description, JSON schema for parameters (requiring a 'city'), and an Execute method that returns formatted weather information.

```go
type WeatherTool struct {
}

func (r *WeatherTool) Name() string {
    return "get_weather"
}

func (r *WeatherTool) Description() string {
    return "Returns the current weather for a city."
}

func (r *WeatherTool) Parameters() map[string]any {
    return map[string]any{
        "type": "object",
        "properties": map[string]any{
            "city": map[string]any{
                "type": "string",
            },
        },
        "required": []string{"city"},
    }
}

func (r *WeatherTool) Execute(ctx context.Context, args map[string]any) (string, error) {
    city, _ := args["city"].(string)

    return fmt.Sprintf("Sunny, 25 C in %s", city), nil
}
```

--------------------------------

### Support both old and new code structures for package setup

Source: https://www.goravel.dev/upgrade/v1.17.html

To support both old and new code structures, check if the project uses the new structure via 'env.IsBootstrapSetup()'. Use 'match.ProvidersInConfig()' instead of 'match.Providers()' when adapting the old code structure.

```go
package main

import (
  "os"

```

--------------------------------

### Get Unique and Duplicate Items

Source: https://www.goravel.dev/digging-deeper/collections.html

Use `Unique` to get distinct items and `Duplicates` to get each duplicated value once. Both methods return a new collection.

```go
numbers := collect.New(1, 2, 2, 3, 3, 3)

numbers.Unique().All()     // []int{1, 2, 3}
numbers.Duplicates().All() // []int{2, 3}
```

--------------------------------

### Build and Configure Docker Image

Source: https://www.goravel.dev/testing/getting-started.html

Build the initiated Docker image and retrieve its configuration details for debugging and connection setup.

```go
err := database.Build()
err := cache.Build()
```

```go
config := database.Config()
config := cache.Config()
```

--------------------------------

### Set Up Test Environment with TestMain

Source: https://www.goravel.dev/testing/getting-started.html

Implement the `TestMain` function in your test file to define pre-test logic, such as setting up a Docker database, running migrations, and restarting the application. It also handles the shutdown of the Docker image after all tests complete.

```go
// tests/feature/main_test.go
package feature

import (
  "fmt"
  "os"
  "testing"

  "goravel/app/facades"
  "goravel/database/seeders"
)

func TestMain(m *testing.M) {
  database, err := facades.Testing().Docker().Database()
  if err != nil {
    panic(err)
  }

  if err := database.Build(); err != nil {
    panic(err)
  }
  if err := database.Ready(); err != nil {
    panic(err)
  }
  if err := database.Migrate(); err != nil {
    panic(err)
  }

  if err := facades.App().Restart(); err != nil {
    panic(err)
  }

  // Execute test cases
  exit := m.Run()

  // Uninstall the image after all test cases have been run
  if err := database.Shutdown(); err != nil {
    panic(err)
  }

  os.Exit(exit)
}
```

--------------------------------

### Serve Static Files and Directories

Source: https://www.goravel.dev/the-basics/routing.html

Configure routes to serve static files or entire directories. Use Static for directories, StaticFile for individual files, and StaticFS for custom file system implementations.

```go
import "net/http"

facades.Route().Static("static", "./public")
facades.Route().StaticFile("static-file", "./public/logo.png")
facades.Route().StaticFS("static-fs", http.Dir("./public"))
```

--------------------------------

### Define a basic view template

Source: https://www.goravel.dev/the-basics/views.html

Create a view file with the .tmpl extension in the application's resources/views directory. This example defines a simple HTML structure with a dynamic name.

```go
// resources/views/welcome.tmpl
{{ define "welcome.tmpl" }}
<html>
  <body>
  <h1>Hello, {{ .name }}</h1>
  </body>
</html>
{{ end }}
```

--------------------------------

### Use Multiple Authentication Guards

Source: https://www.goravel.dev/security/authentication.html

Demonstrates how to specify and use different authentication guards for operations like login, parsing, and retrieving user information.

```go
package main

import (
	"context"
	"errors"
	"github.com/goravel/framework/auth"
	"github.com/goravel/framework/facades"
	"your-project/app/models"
)

func main() {
	// Login with 'admin' guard
	token, err := facades.Auth(context.Background()).Guard("admin").LoginUsingID(1)

	// Parse token with 'admin' guard
	_, err = facades.Auth(context.Background()).Guard("admin").Parse(token)

	// Get user with 'admin' guard
	var user models.User
	err = facades.Auth(context.Background()).Guard("admin").User(&user)

	// Example of guard mismatch error
	userToken, _ := facades.Auth(context.Background()).Guard("user").LoginUsingID(2)
	_, err = facades.Auth(context.Background()).Guard("admin").Parse(userToken)
	if errors.Is(err, auth.ErrorGuardMismatch) {
		// Token was issued by a different guard
	}
}
```

--------------------------------

### Install Specific Agent Skills

Source: https://www.goravel.dev/prologue/contributions.html

Install one or more specific agent skills by providing their names.

```shell
goravel skill:install goravel-testing goravel-planning
```

--------------------------------

### Mocking Orm Facade for Begin, Commit, and Rollback

Source: https://www.goravel.dev/testing/mock.html

This example shows how to mock the Orm facade's Query().Begin() method and subsequently mock the transaction's Commit() and Rollback() methods. This is useful for testing scenarios involving explicit transaction control.

```go
func Begin() error {
  tx, _ := facades.Orm().Query().Begin()
  user := models.User{Name: "Goravel"}
  if err := tx.Create(&user); err != nil {
    return tx.Rollback()
  } else {
    return tx.Commit()
  }
}
```

--------------------------------

### Remove Values from Start of String

Source: https://www.goravel.dev/digging-deeper/strings.html

Removes specified values from the start of a string using the `ChopStart` method.

```go
import "github.com/goravel/framework/support/str"

str.Of("https://goravel.dev").ChopStart("http://", "https://").String() // goravel.dev
```

--------------------------------

### Create Directory

Source: https://www.goravel.dev/digging-deeper/filesystem.html

Creates a directory, including any necessary parent subdirectories, on the default storage disk.

```go
err := facades.Storage().MakeDirectory(directory)
```

--------------------------------

### Install Skills to Custom Directory

Source: https://www.goravel.dev/prologue/contributions.html

Install agent skills to a specific directory using the --path flag.

```shell
goravel skill:install --path ~/goravel-skills
```

--------------------------------

### Task Scheduling Command Example

Source: https://www.goravel.dev/prologue/compare-with-laravel.html

Compares scheduling a command to run daily in Goravel and Laravel.

```go
facades.Schedule().Command("emails:send").Daily()
```

```php
Schedule::command('emails:send')->daily()
```

--------------------------------

### Install Goravel CLI

Source: https://www.goravel.dev/prologue/contributions.html

Install the Goravel command-line tool to enable framework management and agent skill functionality.

```shell
go install github.com/goravel/installer/goravel@latest
```

--------------------------------

### Add File Storage Configuration

Source: https://www.goravel.dev/upgrade/v1.5.html

Create the `config/filesystems.go` file to configure the new File Storage Module. This is a required step for the upgrade.

```go
add config/filesystems.go file
```

--------------------------------

### Upgrade Goravel Installer

Source: https://www.goravel.dev/upgrade/v1.16.html

The `upgrade` command in `goravel/installer` is used to update the installer itself to the latest version or a specific version.

```shell
goravel upgrade
goravel upgrade v1.1.1
```

--------------------------------

### HTTP Client Get Request

Source: https://www.goravel.dev/prologue/compare-with-laravel.html

Demonstrates making an HTTP GET request to an external API in Goravel and Laravel.

```go
facades.Http().Get("https://api.com")
```

```php
Http::get('https://api.com')
```

--------------------------------

### HTTP Runner Implementation

Source: https://www.goravel.dev/architecture-concepts/service-providers.html

An example implementation of the `Runner` interface for handling HTTP server startup and shutdown. It checks configuration and route availability before running.

```go
package http

import (
	"github.com/goravel/framework/contracts/config"
	"github.com/goravel/framework/contracts/route"
)

type HTTPRunner struct {
	config config.Config
	route  route.Route
}

func NewHTTPRunner(config config.Config, route route.Route) *HTTPRunner {
	return &HTTPRunner{
		config: config,
		route:  route,
	}
}

func (r *HTTPRunner) Signature() string {
	return "goravel:http"
}

func (r *HTTPRunner) ShouldRun() bool {
	return r.route != nil && r.config.GetString("http.default") != ""
}

func (r *HTTPRunner) Run() error {
	return r.route.Run()
}

func (r *HTTPRunner) Shutdown() error {
	return r.route.Shutdown()
}
```

--------------------------------

### Add Package Routes

Source: https://www.goravel.dev/digging-deeper/package-development.html

Register routes from your package into the main application. Use `app.MakeRoute()` to get the router instance and define your routes within the service provider's `Boot` method.

```go
func (receiver *ServiceProvider) Boot(app foundation.Application) {
	route := app.MakeRoute()
	route.Get("sms", ***)
}
```

--------------------------------

### Get Resource Directory Path

Source: https://www.goravel.dev/digging-deeper/helpers.html

Use path.Resource() to get the absolute path to the resource directory or a file within it.

```go
import "github.com/goravel/framework/support/path"

path := path.Resource()
path := path.Resource("css/app.css")
```

--------------------------------

### Get Language Directory Path

Source: https://www.goravel.dev/digging-deeper/helpers.html

Use path.Lang() to get the absolute path to the lang directory or a file within it.

```go
import "github.com/goravel/framework/support/path"

path := path.Lang()
path := path.Lang("en.json")
```

--------------------------------

### Get Public Directory Path

Source: https://www.goravel.dev/digging-deeper/helpers.html

Use path.Public() to get the absolute path to the public directory or a file within it.

```go
import "github.com/goravel/framework/support/path"

path := path.Public()
path := path.Public("css/app.css")
```

--------------------------------

### Get Storage Directory Path

Source: https://www.goravel.dev/digging-deeper/helpers.html

Use path.Storage() to get the absolute path to the storage directory or a file within it.

```go
import "github.com/goravel/framework/support/path"

path := path.Storage()
path := path.Storage("app/file.txt")
```

--------------------------------

### Get Database Directory Path

Source: https://www.goravel.dev/digging-deeper/helpers.html

Use path.Database() to get the absolute path to the database directory or a file within it.

```go
import "github.com/goravel/framework/support/path"

path := path.Database()
path := path.Database("factories/user_factory.go")
```

--------------------------------

### Get Configuration Directory Path

Source: https://www.goravel.dev/digging-deeper/helpers.html

Use path.Config() to get the absolute path to the config directory or a file within it.

```go
import "github.com/goravel/framework/support/path"

path := path.Config()
path := path.Config("app.go")
```

--------------------------------

### Get Application Directory Path

Source: https://www.goravel.dev/digging-deeper/helpers.html

Use path.App() to get the absolute path to the app directory or a file within it.

```go
import "github.com/goravel/framework/support/path"

path := path.App()
path := path.App("http/controllers/controller.go")
```

--------------------------------

### Configure Database Connections and Read-Write Splitting

Source: https://www.goravel.dev/database/getting-started.html

Set up database connections, including read and write hosts for splitting traffic, in the `config/database.go` file. This configuration leverages environment variables for dynamic settings.

```go
import "github.com/goravel/framework/contracts/database"

// config/database.go
"connections": map[string]any{
  "mysql": map[string]any{
    "driver": "mysql",
    "read": []database.Config{
      {Host: "192.168.1.1", Port: 3306, Database: "forge", Username: "root", Password: "123123"},
    },
    "write": []database.Config{
      {Host: "192.168.1.2", Port: 3306, Database: "forge", Username: "root", Password: "123123"},
    },
    "host": config.Env("DB_HOST", "127.0.0.1"),
    "port":     config.Env("DB_PORT", 3306),
    "database": config.Env("DB_DATABASE", "forge"),
    "username": config.Env("DB_USERNAME", ""),
    "password": config.Env("DB_PASSWORD", ""),
    "charset":  "utf8mb4",
  },
}

```

--------------------------------

### Get Project Root Directory Path

Source: https://www.goravel.dev/digging-deeper/helpers.html

Use path.Base() to get the absolute path to the project root or a file within it.

```go
import "github.com/goravel/framework/support/path"

path := path.Base()
path := path.Base("vendor/bin")
```

--------------------------------

### Initialize and Use Native Validation Engine

Source: https://www.goravel.dev/upgrade/v1.18.html

Demonstrates how to create a validator instance with custom rules and filters, and retrieve validated data. Ensure the 'ctx' context is properly initialized.

```go
validator, err := facades.Validation().Make(ctx,
    map[string]any{
        "email": " User@Goravel.dev ",
        "scores": []int{1, 2},
    },
    map[string]any{
        "email": "required|email",
        "scores.*": "required|integer",
    },
    validation.Filters(map[string]any{
        "email": "trim|lower",
    }),
)

validated := validator.Validated()
scores := validated["scores"].([]int)
```

--------------------------------

### Start Services Using Default .env

Source: https://www.goravel.dev/getting-started/installation.html

Starts the Goravel application services using the .env file located in the root directory.

```shell
go run .
```

--------------------------------

### Configure GRPC Host and Port

Source: https://www.goravel.dev/upgrade/v1.10.html

The facades.Grpc.Run method now defaults to grpc.host and grpc.port, making it backward compatible without code modification.

```go
facades.Grpc.Run()
```

--------------------------------

### Verify Goravel AI Development Skill Installation

Source: https://www.goravel.dev/upgrade/v1.18.html

Verify the installation of the Goravel AI coding conventions skill by checking for the SKILL.md file.

```shell
ls -l .agents/skills/goravel-development/SKILL.md
```

--------------------------------

### Register Configuration with WithConfig

Source: https://www.goravel.dev/getting-started/configuration.html

Register all configuration files by calling the `WithConfig` function in the `bootstrap/app.go` file. This function is an `init` function, so individual registration is not required.

```go
func Boot() contractsfoundation.Application {
	return foundation.Setup().
		WithConfig(config.Boot).
		Create()
}
```

--------------------------------

### Register New Service Providers in App Config

Source: https://www.goravel.dev/upgrade/v1.13.html

Add the new testing, database, and gin service providers to your application's configuration. Ensure they are added in the correct order.

```go
import (
  "github.com/goravel/framework/testing"
  "github.com/goravel/gin"
)

// config/app.go
"providers": []foundation.ServiceProvider{
  ...
  &validation.ServiceProvider{},
  // New
  &testing.ServiceProvider{},
  &providers.AppServiceProvider{},
  ...
  &providers.ValidationServiceProvider{},
  // New
  &providers.DatabaseServiceProvider{},
  // New
  &gin.ServiceProvider{},
}
```

--------------------------------

### Start Queue Server with Custom Runners

Source: https://www.goravel.dev/digging-deeper/queues.html

Configure multiple queue workers with different settings by creating custom runners and adding them to the `WithRunners` function in `bootstrap/app.go`.

```go
func Boot() contractsfoundation.Application {
  return foundation.Setup().
    WithConfig(config.Boot).
    WithRunners(func() []contractsfoundation.Runner {
      return []contractsfoundation.Runner{
        YourRunner,
      }
    }).
    Create()
}
```

--------------------------------

### Create and Manipulate Fluent Strings

Source: https://www.goravel.dev/digging-deeper/strings.html

Demonstrates creating a fluent string instance, applying multiple operations like Trim, Lower, and UpperFirst, and retrieving the final string.

```go
import "github.com/goravel/framework/support/str"

str.Of("  Goravel  ").Trim().Lower().UpperFirst().String() // "Goravel"
```

--------------------------------

### Replace First Occurrence at Start of String

Source: https://www.goravel.dev/digging-deeper/strings.html

Use `ReplaceStart` to replace a substring only if it appears at the very beginning of the string. If the substring is not at the start, the string remains unchanged.

```go
import "github.com/goravel/framework/support/str"

str.Of("Hello World").ReplaceStart("Hello", "Goravel").String() // "Goravel World"

str.Of("Hello World").ReplaceStart("World", "Goravel").String() // "Hello World"
```

--------------------------------

### Start Services Using Environment Variables

Source: https://www.goravel.dev/getting-started/installation.html

Starts the Goravel application services and sets environment variables like APP_ENV and APP_DEBUG directly in the command.

```shell
APP_ENV=production APP_DEBUG=true go run .
```

--------------------------------

### Run Full Verification Suite

Source: https://www.goravel.dev/upgrade/v1.18.html

After completing upgrade steps, run the full verification suite to ensure all components are functioning correctly. This includes building the project, running vet checks, and executing tests.

```shell
go build ./...
go vet ./...
go test ./... 2>&1 || true
```

--------------------------------

### N+1 Query Problem Example

Source: https://www.goravel.dev/orm/relationships.html

Illustrates the N+1 query problem by retrieving all books and then querying for each book's author individually within a loop.

```go
var books []models.Book
facades.Orm().Query().Find(&books)

for _, book := range books {
  var author models.Author
  facades.Orm().Query().Find(&author, book.AuthorID)
}
```

--------------------------------

### Make a GET Request

Source: https://www.goravel.dev/digging-deeper/http-client.html

Use the `Get` method to fetch data from a specified URL. This method returns a response object and an error if the request fails.

```go
response, err := facades.Http().Get("https://example.com")
```

--------------------------------

### Verify Air Installation

Source: https://www.goravel.dev/getting-started/installation.html

Checks if the 'air' command is accessible in the system's PATH by displaying its location. Used to confirm Air is installed and configured correctly.

```bash
which air
```

--------------------------------

### Publish Package Assets

Source: https://www.goravel.dev/digging-deeper/package-development.html

Use the `Publishes` method in your service provider's `Boot` method to publish package assets like JavaScript, CSS, and images to the application's public directory.

```go
func (receiver *ServiceProvider) Boot(app foundation.Application) {
  app.Publishes("github.com/goravel/example-package", map[string]string{
    "public": app.PublicPath("vendor"),
  })
}
```

--------------------------------

### Publish Package Migrations

Source: https://www.goravel.dev/digging-deeper/package-development.html

Publish your package's migration files to the application's database migrations directory. Use the `Publishes` method in your service provider's `Boot` method, mapping the package's migration directory to the application's database path.

```go
func (receiver *ServiceProvider) Boot(app foundation.Application) {
  app.Publishes("github.com/goravel/example-package", map[string]string{
    "migrations": app.DatabasePath("migrations"),
  })
}
```

--------------------------------

### Mocking Schedule Facade for Cron Jobs

Source: https://www.goravel.dev/testing/mock.html

This example shows how to mock the Schedule facade for testing cron job definitions. It verifies that the Command and EveryMinute methods are invoked as expected.

```go
import (
  "testing"

  "github.com/goravel/framework/testing/mock"
  mocksschedule "github.com/goravel/framework/mocks/schedule"
  "github.com/stretchr/testify/assert"

  "goravel/app/facades"
)

func Schedule() error {
  return facades.Schedule().Command("my-command").EveryMinute()
}

func TestSchedule(t *testing.T) {
  mockFactory := mock.Factory()
  mockSchedule := mockFactory.Schedule()
  mockEvent := mocksschedule.NewEvent(t)
  mockSchedule.EXPECT().Command("my-command").Return(mockEvent).Once()
  mockEvent.EXPECT().EveryMinute().Return(nil).Once()

  assert.Nil(t, Schedule())
}
```

--------------------------------

### Simulate Basic HTTP GET Request

Source: https://www.goravel.dev/testing/http-tests.html

Use the `Http` method from `TestCase` to simulate a GET request and assert the status code. Ensure you pass `*testing.T` to `Http`.

```go
func (s *ExampleTestSuite) TestIndex() {
	response, err := s.Http(s.T()).Get("/users/1")
	s.Nil(err)
	response.AssertStatus(200)
}
```

--------------------------------

### Load Package Views

Source: https://www.goravel.dev/digging-deeper/package-development.html

Register the directory containing your package's views using `LoadViewsFrom` in your service provider's `Boot` method. This allows the application to find and render your package's views.

```go
func (receiver *ServiceProvider) Boot(app foundation.Application) {
    facades.View().LoadViewsFrom("/path/to/package/views")
}
```

--------------------------------

### Define Basic HTTP Routes

Source: https://www.goravel.dev/the-basics/routing.html

Define routes for GET, POST, PUT, DELETE, PATCH, OPTIONS, and ANY HTTP methods. The GET route returns a JSON response, while others delegate to a controller.

```go
facades.Route().Get("/", func(ctx http.Context) http.Response {
  return ctx.Response().Json(http.StatusOK, http.Json{
    "Hello": "Goravel",
  })
})
facades.Route().Post("/", userController.Show)
facades.Route().Put("/", userController.Show)
facades.Route().Delete("/", userController.Show)
facades.Route().Patch("/", userController.Show)
facades.Route().Options("/", userController.Show)
facades.Route().Any("/", userController.Show)
```

--------------------------------

### Configure Telemetry Processors

Source: https://www.goravel.dev/digging-deeper/telemetry.html

Set up trace and log processors. The 'batch' processor buffers data for production, while 'simple' is for debugging. Configurable via OTEL_TRACE_PROCESSOR_TYPE, OTEL_TRACE_EXPORT_INTERVAL, and OTEL_TRACE_EXPORT_TIMEOUT.

```go
"processor": map[string]any{
    "type":     config.Env("OTEL_TRACE_PROCESSOR_TYPE", "batch"),
    "interval": config.Env("OTEL_TRACE_EXPORT_INTERVAL", "5s"),
    "timeout":  config.Env("OTEL_TRACE_EXPORT_TIMEOUT", "30s"),
},
```

--------------------------------

### carbon.Now()

Source: https://www.goravel.dev/digging-deeper/helpers.html

Gets the current time.

```APIDOC
## carbon.Now()

### Description
Gets current time:

### Usage
```go
carbon.Now()
```
```

--------------------------------

### Add RunTLSWithCert Method

Source: https://www.goravel.dev/upgrade/v1.10.html

A new method, facades.Route.RunTLSWithCert, has been added for more specific TLS configurations.

```go
facades.Route.RunTLSWithCert()
```

--------------------------------

### Implement Batch-Receive Driver Interface

Source: https://www.goravel.dev/digging-deeper/queues.html

Example implementation of the `DriverWithReceive` interface for batch message consumption. This is suitable for high-throughput scenarios like Kafka or RabbitMQ.

```go
import (
  "context"
  "github.com/goravel/framework/contracts/queue"
)

type KafkaDriver struct{}

// Implement the base Driver interface
func (d *KafkaDriver) Driver() string {
  return "kafka"
}

func (d *KafkaDriver) Push(task queue.Task, queue string) error {
  // push job to Kafka
}

func (d *KafkaDriver) Pop(queue string) (queue.ReservedJob, error) {
  // standard single-job pop
}

// Implement the optional DriverWithReceive for batch consumption
func (d *KafkaDriver) Receive(ctx context.Context, queue string, count int) ([]queue.ReservedJob, error) {
  // batch receive up to `count` jobs, blocking until at least one is available or ctx expires
}
```

--------------------------------

### carbon.FromStdTime()

Source: https://www.goravel.dev/digging-deeper/helpers.html

Gets a Carbon object by `time.Time`.

```APIDOC
## carbon.FromStdTime()

### Description
Gets a Carbon object by `time.Time`.

### Method
`FromStdTime(t time.Time)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
carbon.FromStdTime(time.Now())
```

### Response
#### Success Response (Carbon Object)
Returns a Carbon object representing the provided `time.Time`.

#### Response Example
None provided in source.
```

--------------------------------

### Create and Use Metrics Instruments

Source: https://www.goravel.dev/digging-deeper/telemetry.html

Request a meter and create instruments for counting processed payments and measuring processing duration. Instruments should be created once and reused.

```go
package services

import (
    "context"
    "time"

    "go.opentelemetry.io/otel/metric"

    "github.com/goravel/framework/telemetry"

    "goravel/app/facades"
)

type PaymentService struct {
    processed metric.Int64Counter
    duration  metric.Float64Histogram
}

func NewPaymentService() (*PaymentService, error) {
    meter := facades.Telemetry().Meter("app")

    processed, err := meter.Int64Counter("payments.processed",
        metric.WithDescription("Number of processed payments"),
    )
    if err != nil {
        return nil, err
    }

    duration, err := meter.Float64Histogram("payments.duration",
        metric.WithUnit("s"),
        metric.WithDescription("Duration of payment processing"),
    )
    if err != nil {
        return nil, err
    }

    return &PaymentService{processed: processed, duration: duration}, nil
}

func (r *PaymentService) Charge(ctx context.Context, method string) error {
    start := time.Now()

    // Charge the payment...

    r.processed.Add(ctx, 1, metric.WithAttributes(
        telemetry.String("payment.method", method),
    ))
    r.duration.Record(ctx, time.Since(start).Seconds())

    return nil
}
```

--------------------------------

### Retrieving Request Host

Source: https://www.goravel.dev/the-basics/request.html

Get the host from the request.

```go
url := ctx.Request().Host()
```

--------------------------------

### Mocking Artisan Facade

Source: https://www.goravel.dev/testing/mock.html

Demonstrates how to mock the Artisan facade's Call method for testing.

```go
func ArtisanCall() {
  facades.Artisan().Call("list")
}

func TestArtisan(t *testing.T) {
  mockFactory := mock.Factory()
  mockArticle := mockFactory.Artisan()
  mockArticle.On("Call", "list").Once()

  assert.NotPanics(t, func() {
    ArtisanCall()
  })

  mockArticle.AssertExpectations(t)
}
```

--------------------------------

### carbon.FromTime()

Source: https://www.goravel.dev/digging-deeper/helpers.html

Gets a Carbon object by hour, minute, and second.

```APIDOC
## carbon.FromTime()

### Description
Gets a Carbon object by hour, minute, and second.

### Method
`FromTime(hour int, minute int, second int)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
carbon.FromTime(13, 14, 15)
```

### Response
#### Success Response (Carbon Object)
Returns a Carbon object representing the specified time.

#### Response Example
None provided in source.
```

--------------------------------

### Building URLs with URI Templates

Source: https://www.goravel.dev/digging-deeper/http-client.html

Illustrates how to construct dynamic URLs using placeholders and provide values for them.

```APIDOC
## URI Templates

### Description
Builds dynamic request URLs using placeholders and populates them with provided values.

### Method
GET

### Endpoint
`https://api.example.com/users/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID to use in the URL placeholder.

### Request Example
```go
response, err := facades.Http().
	WithUrlParameter("id", "123").
	Get("https://api.example.com/users/{id}")
```
```

```APIDOC
## Multiple URI Template Parameters

### Description
Builds dynamic request URLs with multiple placeholders and populates them with provided values.

### Method
GET

### Endpoint
`https://api.example.com/books/{bookId}/chapters/{chapterNumber}`

### Parameters
#### Path Parameters
- **bookId** (string) - Required - The book ID to use in the URL placeholder.
- **chapterNumber** (string) - Required - The chapter number to use in the URL placeholder.

### Request Example
```go
response, err := facades.Http().
    WithUrlParameters(map[string]string{
        "bookId":        "456",
        "chapterNumber": "7",
    }).
    Get("https://api.example.com/books/{bookId}/chapters/{chapterNumber}")
```
```

--------------------------------

### carbon.FromDate()

Source: https://www.goravel.dev/digging-deeper/helpers.html

Gets a Carbon object by year, month, and day.

```APIDOC
## carbon.FromDate()

### Description
Gets a Carbon object by year, month, and day.

### Method
`FromDate(year int, month int, day int)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
carbon.FromDate(2020, 1, 1)
```

### Response
#### Success Response (Carbon Object)
Returns a Carbon object representing the specified date.

#### Response Example
None provided in source.
```

--------------------------------

### carbon.FromTimestampNano()

Source: https://www.goravel.dev/digging-deeper/helpers.html

Gets a Carbon object by timestamp with nanosecond precision.

```APIDOC
## carbon.FromTimestampNano()

### Description
Gets a Carbon object by timestamp with nanosecond precision.

### Method
`FromTimestampNano(timestamp int64)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
carbon.FromTimestampNano(1649735755999999999)
```

### Response
#### Success Response (Carbon Object)
Returns a Carbon object representing the timestamp.

#### Response Example
None provided in source.
```

--------------------------------

### Command Usage with Options

Source: https://www.goravel.dev/digging-deeper/artisan-console.html

Illustrates how to pass options to Artisan commands via the command line.

```shell
./artisan emails --lang Chinese
./artisan emails -l Chinese
```

--------------------------------

### carbon.FromTimeNano()

Source: https://www.goravel.dev/digging-deeper/helpers.html

Gets a Carbon object by hour, minute, second, and nanosecond.

```APIDOC
## carbon.FromTimeNano()

### Description
Gets a Carbon object by hour, minute, second, and nanosecond.

### Method
`FromTimeNano(hour int, minute int, second int, nanosecond int)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
carbon.FromTimeNano(13, 14, 15, 999999999)
```

### Response
#### Success Response (Carbon Object)
Returns a Carbon object representing the specified time and nanosecond.

#### Response Example
None provided in source.
```

--------------------------------

### Manual Regular Compilation

Source: https://www.goravel.dev/getting-started/compile.html

Compile the project using the standard Go build command. Ensure necessary files are uploaded during deployment.

```shell
go build .
```
Tokens:
Raw