Upgrade Guide

Bagisto is a complete Laravel application, not a package inside one. Upgrading means bringing your copy of the application files up to the new release, reconciling the files you changed, installing the new dependencies and running the migrations. The Bagisto repository keeps the full procedure and every breaking change in UPGRADE.md; this page tells you which copy to read, what to prepare, and which changes reach your own packages and themes.

Full Upgrade Procedure

Follow UPGRADE.md to upgrade from 2.4 to 2.5. It has the commands, the configuration files to bring across, and the code changes for each breaking change.

Which Document to Read

Each UPGRADE.md covers one release line. From an older release, work through them in order.

Upgrading	Read
2.4 to 2.5	UPGRADE.md on master
2.3 to 2.4	UPGRADE.md on the 2.4 branch
2.2 to 2.3	UPGRADE.md on the 2.3 branch
2.1 to 2.2	UPGRADE.md on the 2.2 branch

The CHANGELOG.md on the same branch lists what changed in each release of that line.

Before You Upgrade

• Back up the database and storage/. Some migrations rewrite existing rows and move uploads on disk, and their down() methods don't restore the old values.
• Check that APP_URL is the live store's address. Storage::url() builds the URLs of local uploads, such as channel logos, from it.
• Rehearse on a copy of the store, with a copy of its data, before you upgrade production.
• Plan for maintenance mode while the migrations run; see Before You Start.
• List your custom packages and themes, and check each one against the changes below. Edits inside packages/Webkul/ or vendor/ are overwritten, so move them into a package, a theme or an event listener first; see Extension Points at a Glance.

Never Run the Installer on an Existing Store

php artisan bagisto:install runs db:wipe and then migrate:fresh, which destroys your data. An upgrade only runs php artisan migrate.

Changes That Affect Packages and Themes

These 2.5 changes most often need work in a custom package or theme; UPGRADE.md has the migration steps.

• Laravel 13 and PHP 8.4. Several dependencies moved to a new major version, and PHP 8.4 deprecates implicitly nullable parameters, so write ?string $locale = null. See System Requirements.
• Search engines. Search runs through SearchEngineManager: the Elasticsearch repository and jobs were replaced, the settings moved to search_engines.* codes, and indexer:index --type=elastic is now --type=search. See Search Engines. A store with Elasticsearch credentials in .env must re-enter them in the admin after migrating; see Configure Elasticsearch.
• Relocated configuration codes. sales.checkout.my_cart.summary is now sales.checkout.mini_cart.summary, and catalog.products.storefront.buy_now_button_display is now catalog.products.product_view_page.buy_now_button_display. A migration moves stored values, but code reading the old codes must change; see Relocated Configuration Codes.
• Storefront breadcrumbs. Core's trails now load from the Shop package; remove them from your routes/breadcrumbs.php, or pages with a breadcrumb throw DuplicateBreadcrumbException. See Storefront Breadcrumbs Moved Into the Shop Package.
• Storage directories. Upload directories are plural and kebab-case, such as products/{id}. A migration moves the files, but not code that builds a path itself. See Storage Directories Renamed.
• Route names and translation keys. Route names are snake_case and translation keys kebab-case, so code naming an old one must change. See Route Names Are snake_case and Translation Keys Are kebab-case.
• Tailwind CSS 4. A theme or package with its own Tailwind build moves to the @tailwindcss/vite plugin and configures Tailwind in app.css. Some icon classes were renamed or removed. See Vite-Powered Theme Assets.
• Images. image_manager() returns Laravel's Illuminate\Image\ImageManager, and an image template is a class whose applyFilter() takes and returns Illuminate\Image\Image. See Image Cache.
• Theme section media. Sections store uploads as bare paths (themes/...), and static content markup may hold __media__/... references, so an overridden section view builds its URLs with bagisto_theme_storage() and passes markup through its resolveMarkup(). See Theme Sections.
• PostgreSQL. Custom queries must run on MySQL, MariaDB and PostgreSQL, for example with db_grammar()->caseInsensitiveLike() instead of 'like'. See Database Compatibility.
• Configuration files. The upgrade doesn't touch your config/ directory. Take config/responsecache.php from the release, and replace config/image.php with config/images.php. Take config/broadcasting.php too, or real-time admin notifications can't be switched on. The configuration files section of UPGRADE.md lists the rest.
• Omnibus registration. Merge the new Webkul\Omnibus entries into your composer.json, bootstrap/providers.php and config/concord.php; see The Omnibus Package.
• Smaller renames and removals. core()->country_name() and is_empty_date() are countryName() and isEmptyDate(), CoreConfigRepository::recursiveArray() and countDim() are flattenToConfigValues() and depthOf(), the customer phone key is phone, and the downloadable_products view is downloadable-products. The product image size and placeholder settings are gone; set them in your theme. Retired Magic AI models are gone, and a migration moves saved features to their replacements. See Low Impact Changes.

Related Pages

• Deployment: what a production server needs after the upgrade.
• Common Pitfalls: the symptom, cause and fix for problems developers hit again and again, such as a PHP version error.