PHPackages                             haxcode/magento-georouting - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. haxcode/magento-georouting

ActiveMagento2-module[Utility & Helpers](/categories/utility)

haxcode/magento-georouting
==========================

Intelligent geo-based store routing for Magento 2 with SEO protection and product availability checking

00PHP

Since Mar 3Pushed 2mo agoCompare

[ Source](https://github.com/haxcode-ts/Haxcode_GeoRouting-Magento)[ Packagist](https://packagist.org/packages/haxcode/magento-georouting)[ RSS](/packages/haxcode-magento-georouting/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Haxcode GeoRouting for Magento 2
================================

[](#haxcode-georouting-for-magento-2)

Intelligent geo-based store routing module for Magento 2 with comprehensive SEO protection, product availability checking, and user preference management.

Features
--------

[](#features)

### Core Functionality

[](#core-functionality)

- **Automatic Geo-Detection**: Automatically detects visitor's country and redirects to appropriate store
    - Visitors from Canada → CAD store (`/ca/`)
    - Visitors from US, China, and other countries → USD store (default)
- **Manual Store Switching**: Header dropdown with confirmation popup before switching
- **User Preference Memory**: Cookie-based storage remembers user's manual store selection (30 days default)
- **Product Availability Check**: Shows popup if product not available in target store

### SEO & Performance Safeguards

[](#seo--performance-safeguards)

- **Bot Detection**: Search engine crawlers are excluded from auto-redirects to avoid indexing issues
- **Hreflang Tags**: Automatic implementation of hreflang meta tags for proper SEO
- **Deep Link Safety**: Product/category URLs retain full path during redirects (e.g., `/product` → `/ca/product`)
- **CDN/Cache Compatible**: Works seamlessly with Cloudflare, Varnish, and other caching layers

### E-commerce Protection

[](#e-commerce-protection)

- **Checkout Protection**: Store switching blocked during cart/checkout to prevent order issues
- **Cart Awareness**: Warning popup when switching stores about potential cart changes
- **Fail-safe Fallback**: System defaults to USD store if geo-detection fails (no redirect loops)

Installation
------------

[](#installation)

### Method 1: Composer (Recommended)

[](#method-1-composer-recommended)

```
composer require haxcode/module-georouting
php bin/magento module:enable Haxcode_GeoRouting
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy
php bin/magento cache:flush
```

### Method 2: Manual Installation

[](#method-2-manual-installation)

1. Download or clone this repository
2. Copy the `GeoRouting` folder to `app/code/Haxcode/`
3. Run the following commands:

```
php bin/magento module:enable Haxcode_GeoRouting
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy
php bin/magento cache:flush
```

Configuration
-------------

[](#configuration)

### Admin Configuration

[](#admin-configuration)

Navigate to: **Stores → Configuration → Haxcode → Geo Routing**

#### General Settings

[](#general-settings)

- **Enable Geo Routing**: Enable/disable the module
- **Canada Store Code**: Store code for Canada (default: `ca`)
- **Default Store Code**: Store code for US/Default (default: `default`)
- **Cookie Lifetime**: Days to remember user preference (default: 30)
- **Exclude Search Engine Bots**: Prevent auto-redirect for SEO crawlers (recommended: Yes)
- **Protect Checkout Process**: Prevent store switching during cart/checkout (recommended: Yes)
- **Check Product Availability**: Show popup if product not available in target store (recommended: Yes)
- **Enable Hreflang Tags**: Add hreflang meta tags for SEO (recommended: Yes)

#### GeoIP Settings

[](#geoip-settings)

- **GeoIP Service**: Select detection method
    - **Cloudflare**: Uses Cloudflare's `CF-IPCountry` header (recommended if using Cloudflare)
    - **Server Variable**: Uses generic server variables (mod\_geoip, custom headers)
- **Cloudflare Country Header**: Header name (default: `HTTP_CF_IPCOUNTRY`)
- **Fallback Country Code**: Country to use if detection fails (default: `US`)

### Store Setup

[](#store-setup)

Ensure you have configured your stores in Magento:

1. **Stores → All Stores**
2. Create store views:
    - Default Store (USD) - Store Code: `default`
    - Canada Store (CAD) - Store Code: `ca`

### URL Configuration

[](#url-configuration)

Configure store URLs to include store code:

1. **Stores → Configuration → General → Web**
2. Set **Add Store Code to URLs**: Yes
3. Configure base URLs:
    - Default Store: `https://yushefashion.com/`
    - Canada Store: `https://yushefashion.com/ca/`

### Cloudflare Setup (Recommended)

[](#cloudflare-setup-recommended)

If using Cloudflare:

1. Enable **IP Geolocation** in Cloudflare Dashboard
2. The module will automatically use the `CF-IPCountry` header
3. No additional configuration needed

Usage
-----

[](#usage)

### Automatic Redirection

[](#automatic-redirection)

Once enabled, the module automatically:

1. Detects visitor's country on page load
2. Redirects to appropriate store (Canada → `/ca/`, Others → default)
3. Preserves URL path and query parameters
4. Skips redirect if user has manual preference or is a bot

### Manual Store Switching

[](#manual-store-switching)

Add store switcher to your header template:

```

        Select Store
        United States (USD)
        Canada (CAD)

Switch to Canada Store
Switch to US Store
```

### Product Availability Popup

[](#product-availability-popup)

When enabled, the module automatically:

1. Checks if current product exists in target store
2. Shows popup if product not available: "This product is not available in Canada store. Do you want to continue in the US store?"
3. Options: **Stay** (saves preference) or **Go to US Store** (switches store)

### JavaScript API

[](#javascript-api)

The module exposes a JavaScript API:

```
require(['Haxcode_GeoRouting/js/georouting'], function(georouting) {
    // Show manual switch popup
    georouting.showManualSwitchPopup('ca');

    // Show product availability popup
    georouting.showProductAvailabilityPopup('ca', 'default');

    // Save user preference
    georouting.saveUserPreference('ca');
});
```

How It Works
------------

[](#how-it-works)

### Request Flow

[](#request-flow)

1. **Page Request** → Observer checks if geo-routing should run
2. **Detection** → Gets country from Cloudflare/server headers
3. **Preference Check** → Checks if user has manual preference (cookie)
4. **Bot Check** → Excludes search engine crawlers
5. **Checkout Check** → Skips if in cart/checkout
6. **Product Check** → Validates product availability (if on product page)
7. **Redirect** → Redirects to appropriate store with preserved URL

### Cookie Management

[](#cookie-management)

- Cookie Name: `georouting_preference`
- Lifetime: Configurable (default 30 days)
- Scope: Site-wide
- Set when: User manually switches stores

### SEO Implementation

[](#seo-implementation)

#### Hreflang Tags

[](#hreflang-tags)

Automatically added to ``:

```

```

#### Bot Detection

[](#bot-detection)

The module detects common bots:

- Googlebot, Bingbot, Slurp (Yahoo)
- DuckDuckBot, Baiduspider, YandexBot
- AhrefsBot, SemrushBot, MJ12bot
- And more...

Scenarios
---------

[](#scenarios)

### Scenario 1: Canadian Visitor on Product Page

[](#scenario-1-canadian-visitor-on-product-page)

- **Visitor**: From Canada
- **Product**: Available in both US and CA stores
- **Result**: Auto-redirects to `/ca/product-name`

### Scenario 2: Canadian Visitor, Product Only in US Store

[](#scenario-2-canadian-visitor-product-only-in-us-store)

- **Visitor**: From Canada
- **Product**: Only available in US store
- **Result**: Shows popup: "This product is not available in Canada store. Do you want to continue in the US store?"
- **Options**:
    - **Stay in US Store** → Saves preference, stays on US store
    - **Go to Canada Store** → Redirects to CA store homepage

### Scenario 3: Manual Store Switch During Checkout

[](#scenario-3-manual-store-switch-during-checkout)

- **Action**: User tries to switch store
- **Result**: Blocked with message: "Store switching is not allowed during checkout. Please complete your order or clear your cart first."

### Scenario 4: User with Manual Preference

[](#scenario-4-user-with-manual-preference)

- **Previous Action**: User manually switched to US store
- **Current**: User from Canada visits site
- **Result**: No auto-redirect, stays on US store (preference remembered for 30 days)

### Scenario 5: Search Engine Bot

[](#scenario-5-search-engine-bot)

- **Visitor**: Googlebot
- **Result**: No redirect, allows bot to crawl all stores independently

Troubleshooting
---------------

[](#troubleshooting)

### Auto-redirect not working

[](#auto-redirect-not-working)

1. Check module is enabled: **Configuration → Geo Routing → Enable**
2. Verify store codes match configuration
3. Check if user has manual preference (clear cookies to test)
4. Review logs: `var/log/system.log` (search for "GeoRouting")

### Cloudflare country detection failing

[](#cloudflare-country-detection-failing)

1. Verify IP Geolocation is enabled in Cloudflare
2. Check header name in configuration matches `HTTP_CF_IPCOUNTRY`
3. Test with fallback country to verify module is working

### Popups not showing

[](#popups-not-showing)

1. Clear static content: `php bin/magento cache:clean`
2. Deploy static content: `php bin/magento setup:static-content:deploy`
3. Check browser console for JavaScript errors
4. Verify jQuery and Magento UI are loaded

### Hreflang tags not appearing

[](#hreflang-tags-not-appearing)

1. Enable in configuration: **Enable Hreflang Tags = Yes**
2. Clear page cache: `php bin/magento cache:clean full_page`
3. View page source to verify tags in ``

Logging
-------

[](#logging)

The module logs important events to `var/log/system.log`:

- Country detection results
- Bot detection
- Store switching actions
- Redirect operations
- Errors and exceptions

Search for `GeoRouting:` prefix in logs.

Compatibility
-------------

[](#compatibility)

- Magento 2.3.x, 2.4.x
- PHP 7.4, 8.0, 8.1, 8.2
- Works with:
    - Cloudflare
    - Varnish
    - Full Page Cache
    - All major themes

Support
-------

[](#support)

For issues, questions, or feature requests:

- GitHub Issues: [Create an issue](#)
- Email:

License
-------

[](#license)

Proprietary - Copyright (c) 2024 Haxcode

Changelog
---------

[](#changelog)

### Version 1.0.0

[](#version-100)

- Initial release
- Automatic geo-based routing
- Manual store switching with confirmation
- Product availability checking
- SEO-safe bot exclusion
- Hreflang implementation
- Checkout protection
- User preference memory
- Cloudflare integration

###  Health Score

19

—

LowBetter than 10% of packages

Maintenance56

Moderate activity, may be stable

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity12

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/4c10bfcc1b23f1b95bc9c30a12f744820ddb07153a05c7d8b6c6bc7b07f971bd?d=identicon)[haxcode](/maintainers/haxcode)

---

Top Contributors

[![haxcode-ts](https://avatars.githubusercontent.com/u/220289632?v=4)](https://github.com/haxcode-ts "haxcode-ts (6 commits)")

### Embed Badge

![Health badge](/badges/haxcode-magento-georouting/health.svg)

```
[![Health](https://phpackages.com/badges/haxcode-magento-georouting/health.svg)](https://phpackages.com/packages/haxcode-magento-georouting)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)