> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lunarphp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Storefront Session

The StorefrontSession facade manages session-bound resources like the active channel, currency, and customer.

## Overview

The `StorefrontSession` facade helps manage session-bound resources that a storefront typically needs, such as the active channel, currency, customer, and customer groups.

```php theme={null}
use Lunar\Facades\StorefrontSession;
```

When the facade is first resolved, it automatically calls `initChannel()`, `initCustomerGroups()`, `initCurrency()`, and `initCustomer()` to restore any previously set values from the session or fall back to defaults.

## Channels

### Initialize the Channel

This will set the channel based on what has been previously stored in the session, otherwise it will use the default channel.

```php theme={null}
StorefrontSession::initChannel();
```

<Info>
  This is automatically called when the facade is resolved.
</Info>

### Set the Channel

```php theme={null}
use Lunar\Models\Channel;

$channel = Channel::where('handle', 'webstore')->first();

StorefrontSession::setChannel($channel);
```

The `setChannel` method accepts a `Channel` model instance. The channel's handle is stored in the session so it can be restored on subsequent requests.

### Get the Channel

Returns the currently active `Channel` model.

```php theme={null}
StorefrontSession::getChannel();
```

## Customer Groups

### Initialize the Customer Groups

This will set the customer groups based on what has been previously stored in the session, otherwise it will use the default customer group.

```php theme={null}
StorefrontSession::initCustomerGroups();
```

<Info>
  This is automatically called when the facade is resolved.
</Info>

### Set the Customer Groups

```php theme={null}
use Lunar\Models\CustomerGroup;

$retail = CustomerGroup::where('handle', 'retail')->first();
$wholesale = CustomerGroup::where('handle', 'wholesale')->first();

// Set multiple customer groups
StorefrontSession::setCustomerGroups(collect([$retail, $wholesale]));

// Set a single customer group (calls setCustomerGroups under the hood)
StorefrontSession::setCustomerGroup($retail);
```

### Get the Customer Groups

Returns a `Collection` of `CustomerGroup` models.

```php theme={null}
StorefrontSession::getCustomerGroups();
```

### Reset the Customer Groups

Clears the customer groups from the session and resets the collection to empty.

```php theme={null}
StorefrontSession::resetCustomerGroups();
```

## Customer

### Initialize the Customer

This will set the customer based on what has been previously stored in the session, otherwise it will retrieve the latest customer associated with the authenticated user.

```php theme={null}
StorefrontSession::initCustomer();
```

<Info>
  This is automatically called when the facade is resolved.
</Info>

### Set the Customer

```php theme={null}
use Lunar\Models\Customer;

$customer = Customer::find($customerId);

StorefrontSession::setCustomer($customer);
```

<Warning>
  If a user is authenticated and the given customer does not belong to that user, a `Lunar\Exceptions\CustomerNotBelongsToUserException` will be thrown.
</Warning>

### Get the Customer

Returns the currently active `Customer` model, or `null` if no customer has been set.

```php theme={null}
StorefrontSession::getCustomer();
```

## Currencies

### Initialize the Currency

This will set the currency based on what has been previously stored in the session, otherwise it will use the default currency.

```php theme={null}
StorefrontSession::initCurrency();
```

<Info>
  This is automatically called when the facade is resolved.
</Info>

### Set the Currency

```php theme={null}
use Lunar\Models\Currency;

$currency = Currency::where('code', 'USD')->first();

StorefrontSession::setCurrency($currency);
```

The `setCurrency` method accepts a `Currency` model instance. The currency code is stored in the session so it can be restored on subsequent requests.

### Get the Currency

Returns the currently active `Currency` model.

```php theme={null}
StorefrontSession::getCurrency();
```

## Clearing the Session

To remove all storefront session data (channel, currency, customer, and customer groups), call the `forget` method.

```php theme={null}
StorefrontSession::forget();
```

This clears the stored values from the session but does not delete any database records.