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

# From v2.2 to v2.3

> How to upgrade your Shopper installation from v2.2 to v2.3.

<Info>
  **Estimated Upgrade Time:** 5-10 minutes for most applications.
</Info>

## Updating Dependencies

Update your `composer.json` file to require Shopper 2.3:

```json theme={null}
"require": {
    "shopper/framework": "^2.3"
}
```

Then run:

```bash theme={null}
composer update -W
```

After updating Composer dependencies, run the migrations:

```bash theme={null}
php artisan migrate
```

***

## New Features

### Product Tags

Shopper 2.3 introduces **Product Tags**, simple flat labels you can attach to products for cross-cutting organization. Unlike categories (hierarchical) or collections (rule-based), tags are flexible and ideal for seasonal labels, marketing campaigns, or storefront filtering.

See the [Product Tags documentation](/v2/product-tags) for full details.

#### New Permissions

New permissions have been added for **tags**. For existing installations, create them and assign to your admin role:

```php theme={null}
use Shopper\Core\Models\Permission;
use Spatie\Permission\Models\Role;

Permission::generate('tags', 'products');

$admin = Role::findByName('administrator');
$admin->givePermissionTo([
    'browse_tags',
    'read_tags',
    'edit_tags',
    'add_tags',
    'delete_tags',
]);
```

<Warning>
  If you don't create these permissions, users will not be able to access the Tags page or manage tags from the product form.
</Warning>

#### New Feature Flag

A new `tag` feature flag has been added to `config/shopper/features.php`. If you have a published config file, add:

```php theme={null}
use Shopper\Enum\FeatureState;

return [
    // ... existing features
    'tag' => FeatureState::Enabled,
];
```

Set to `FeatureState::Disabled` if you don't need tags in your store.

#### Published Components

If you have published product components via `php artisan shopper:component:publish product`, add the new tag page to your `config/shopper/components/product.php`:

```php theme={null}
'pages' => [
    // ... existing pages
    'tag-index' => \Shopper\Livewire\Pages\Tag\Index::class,
],
```

***

## Migration Checklist

<Steps>
  <Step title="Update dependencies">
    Update `shopper/framework` to `^2.3` in `composer.json`, then run `composer update -W`.
  </Step>

  <Step title="Run migrations">
    Run `php artisan migrate` to create the `product_tags` table.
  </Step>

  <Step title="Create new permissions">
    Run `Permission::generate('tags', 'products')` and assign the five generated permissions (`browse_tags`, `read_tags`, `edit_tags`, `add_tags`, `delete_tags`) to the `administrator` role.
  </Step>

  <Step title="Update published config files">
    If you have published `config/shopper/features.php`, add the `tag` feature flag. If you have published `config/shopper/components/product.php`, add the `tag-index` component entry.
  </Step>

  <Step title="Clear caches">
    Run `php artisan optimize:clear`.
  </Step>
</Steps>