Download the PHP package orangecat/module-visibility without Composer

Orangecat_Visibility

Guest access controls for Magento 2 B2B storefronts — force login redirect with URL whitelisting and selective price/cart hiding for guests.

Module: Orangecat_Visibility Version: 1.0.0 License: OSL-3.0 Author: Oliverio Gombert [email protected]

Table of Contents

1. Overview
2. Theme Compatibility
3. Requirements
4. Installation
5. What Gets Installed
6. Configuration
7. Store Admin Guide
8. Guest Experience
9. Developer Guide
10. REST API
11. Frontend Routes Reference
12. DevOps & Integrator Notes

Overview

Orangecat_Visibility controls what unauthenticated (guest) visitors can see and access on a B2B storefront. It provides two independent, non-overlapping operating modes that can be enabled separately.

The module handles:

• Force Login mode — redirect guests away from any page not on a URL whitelist, preserving the original URL so the visitor lands back on it after login.
• Catalog Visibility mode — when Force Login is off, selectively hide product prices and/or the Add to Cart button for guests without blocking navigation.
• URL Whitelist — a per-store, admin-managed table of URL rules with pluggable matching strategies (static exact match or regex). System-critical URLs (login, logout, forgot password, etc.) are pre-seeded and protected from accidental deletion.
• Server-side cart protection — blocks guest POST requests to the Add to Cart controller even when the button is CSS-hidden, preventing bypass via direct HTTP calls.
• Post-login redirect — after the guest authenticates, the browser returns to the page they originally requested.

Position in the Orangecat B2B Dependency Chain

This module is standalone and does not depend on Orangecat_Company. It can be installed independently on any Magento 2 storefront.

Operating Modes

The two modes are mutually exclusive by design: when Force Login is active, the catalog visibility flags have no effect (guests are redirected before seeing any catalog content).

Theme Compatibility

For full Hyvä/Breeze Catalog Visibility support, add dedicated plugins targeting the theme-specific block classes and register them under the appropriate area in etc/frontend/di.xml. The VisibilityChecker service is theme-agnostic and can be injected directly.

Requirements

Installation

Via Git Submodule (recommended for this project)

Enable the Module

Run inside the PHP container (reward shell):

What Gets Installed

Database Tables

visibility_whitelist

Stores the URL rules used by the Force Login whitelist checker.

Indexes: store_id (btree), editable (btree), url_rule + store_id (btree).

EAV Attributes

None.

Data Patches

AddDefaultWhitelistRules

Inserts 21 pre-seeded whitelist rules on first setup:upgrade. Rules with editable = 0 are system-protected and cannot be deleted from the admin UI.

INSERT IGNORE is used so re-running setup:upgrade never duplicates existing rows.

Configuration

Path: Stores → Configuration → Orangecat → Visibility (B2B)

General Settings

Catalog Visibility

These settings apply only when Force Login is disabled. They have no effect when visibility/general/enabled = 1.

Store Admin Guide

Accessing Settings

• Whitelist rules: Admin menu → Visibility → Whitelist
• Module configuration: Admin menu → Visibility → Settings (or Stores → Configuration → Orangecat → Visibility (B2B))

Enabling Force Login

1. Go to Stores → Configuration → Orangecat → Visibility (B2B).
2. Under General Settings, set Enable Redirect to Login to Yes.
3. Optionally change Target URL to a custom landing page (e.g., /company/account/create for a B2B registration-first flow).
4. Save Config and flush cache.

Once active, every guest who reaches the Magento application layer and requests a URL not on the whitelist will be redirected to the target URL.

Enabling Catalog Visibility Restrictions

1. Keep Enable Redirect to Login set to No.
2. Under Catalog Visibility:
   • Set Hide Price For Guest to Yes to remove prices from the catalog for guests.
   • Set Hide Add to Cart Button For Guest to Yes to hide cart controls without hiding prices.
3. Save Config and flush cache.

When Hide Price is Yes, the Add to Cart button is automatically also hidden, regardless of the Add to Cart toggle, because allowing purchase without a visible price is illogical.

Managing the Whitelist

Path: Admin menu → Visibility → Whitelist

The grid shows all rules with columns: ID, Label, URL Rule, Strategy, Store View. Rows with editable = false show no Edit or Delete action links.

Adding a Rule

1. Click Add New Rule.
2. Fill in:
   • Label — unique descriptive name (e.g., My Custom Page).
   • URL Rule — the URL path to allow (e.g., /about-us).
   • Strategy — Static Match for exact path comparison; Regex Match for pattern matching.
   • Store View — limit the rule to a specific store view, or leave as All Store Views.
3. Click Save Rule.

Matching Strategies

Regex example: URL Rule /product/view with Regex Match will match /product/view/id/42 and any other path containing that substring. To match exactly, anchor the pattern: ^/product/view$.

Deleting a Rule

System-protected rules (editable = 0) cannot be deleted from the UI. To remove them, delete the row directly in the database or via a custom data patch.

Guest Experience

This module has no dedicated frontend pages or templates. Its effect is entirely behavioral:

Force Login mode active

• Any URL request that is not on the whitelist triggers an immediate HTTP redirect to the configured target URL (default: the customer login page).
• After successful login, the guest is redirected back to the page they originally requested. The original URL is saved in CustomerSession::setBeforeAuthUrl() before the redirect.
• AJAX requests are not redirected (preventing broken JSON responses).
• Static asset file extensions (.css, .js, .png, .jpg, .gif, .svg) bypass the check.

Catalog Visibility mode active (Force Login off)

• Hide Price: Product prices appear as $0.00 at the model level, and the rendered price boxes and amount containers are hidden via injected style="display:none;". The product:price:amount Open Graph meta tag is also stripped from the HTML.
• Hide Add to Cart: The tocart form, Add to Cart button (by CSS class and by id="product-addtocart-button"), and the minicart wrapper are hidden via injected style="display:none;". Any direct POST to /checkout/cart/add by a guest is blocked server-side with an error message and a redirect to the login page.

Logged-in customers are never affected by either mode.

Developer Guide

Module Structure

Key Classes

Model/VisibilityChecker

Central service injected by all catalog visibility plugins. Uses FPC-safe Magento\Framework\App\Http\Context (not CustomerSession) to determine guest status, making it compatible with full-page cache.

Api/Data/WhitelistEntryInterface

Standard getters/setters for each field.

Api/Repository/WhitelistRepositoryInterface

Returns the full WhitelistEntry\Collection. There is no getById, save, or delete in the service contract — CRUD for whitelist rules is handled by the admin controllers directly via the model factory.

Model/Strategy/MatcherInterface

All matchers implement this interface. Registered via StrategyManager in etc/di.xml:

Plugins

All frontend plugins are declared in etc/frontend/di.xml (frontend area only).

Observers

This module registers no observers.

JS Components

This module provides no JavaScript components — all guest-restriction logic is server-side PHP.

Email Templates

This module sends no email.

ACL Resources

Adding Custom Logic

• Add a new URL matching strategy — implement Model\Strategy\MatcherInterface, then register it in etc/di.xml under the StrategyManager strategies array argument with a unique identifier key. It appears automatically in the admin Strategy dropdown via Model\Source\Strategy.
• Extend catalog visibility to Hyvä/Breeze blocks — inject VisibilityChecker into a new plugin targeting the theme-specific block class; call shouldHidePrice() or shouldHideAddToCart() to apply the same logic. Register in etc/frontend/di.xml.
• Add a third operating mode — add config fields to system.xml, add reader methods to VisibilityChecker, and wire new plugins; VisibilityChecker is the single point of truth for all guest-state checks.

REST API

This module exposes no REST API endpoints. There is no etc/webapi.xml file.

Frontend Routes Reference

This module has no frontend routes. There is no etc/frontend/routes.xml file. All guest-facing behavior is enforced through plugins on existing Magento controllers and rendering classes.

DevOps & Integrator Notes

Deployment Checklist

Integration Token Scope

This module manages frontend behavior only. No integration token permissions are required to interact with whitelist rules — all management is done via the Admin UI.

Minimum ACL permissions for admin users who need to manage the whitelist:

• Orangecat_Visibility::whitelist
• Orangecat_Visibility::config (for store configuration access)

Disabling Without Uninstalling

Set visibility/general/enabled = No and both catalog flags to No in store configuration. This disables all guest restrictions without removing any data.

Data Integrity

• visibility_whitelist.store_id has a CASCADE DELETE constraint on store.store_id. Deleting a store view removes its specific whitelist rules. Rules with store_id = 0 (all store views) are unaffected.
• The label column has a unique constraint. Duplicate labels are rejected at the database level.
• The data patch uses INSERT IGNORE to be idempotent — safe to run setup:upgrade multiple times.
• System-protected rules (editable = 0) are not deletable via the Admin UI, but can be removed directly in the database if needed. Removing them while Force Login is active may lock guests out of login or other essential flows.
• No data is removed when the module is disabled. The visibility_whitelist table and its rows persist.