Download the PHP package cashdash-pro/zaar without Composer
On this page you can find all versions of the php package cashdash-pro/zaar. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download cashdash-pro/zaar
More information about cashdash-pro/zaar
Files in cashdash-pro/zaar
Package zaar
Short Description A robust Laravel package for Shopify authentication handling both embedded and external app flows. Features JWT session management, seamless online/offline token handling, and automatic re-authentication for embedded apps. Built for Laravel 10+ and PHP 8.2+.
License MIT
Homepage https://github.com/nick-potts/laravel-shopify
Informations about the package zaar
Zaar - Laravel Shopify Authentication Made Easy
Overview
Zaar is a Laravel package that simplifies Shopify authentication for your Laravel applications. It provides seamless integration for both embedded and external Shopify apps, handling session management, authentication flows, and user management.
Features
- 🔒 Secure authentication for embedded and external Shopify apps
- 🔄 Session management with online/offline token support
- 🛡️ Built-in CSRF protection configuration
- 🔌 Easy integration with Laravel's authentication system
- 📱 Support for both web and API authentication
- 🎯 Public app endpoints support
- ⚡ Automatic Axios interceptor setup for session tokens
Installation
The install command will:
- Publish the configuration file
- Create necessary migrations
- Set up Axios interceptors (optional)
- Add the
@zaarHead
directive to your Blade layout (optional)
Core Concepts
Authentication Flow and Events
Zaar implements different authentication strategies but follows a consistent flow through the run()
method. Here's how it works:
Embedded Apps (Admin Panel)
-
Online Session (
withOnlineSession
)- Validates Shopify's session token
- Extracts user and shop information
- Fires
OnlineSessionLoaded
-
User Resolution (
withUser
)- Uses session data to find/create user
- Can be customized via
findUserUsing
/createUserUsing
-
Domain Resolution (
withDomain
)- Uses domain from session token by default
- Can be overridden via
setShopifyDomain
(good for store switching)
- Offline Session (Conditional)
- Only if configured for offline tokens
- Fires
OfflineSessionLoaded
External Apps (API/Standalone)
The same flow is followed, but with key differences:
-
Online Session (
withOnlineSession
)- Tries to load the online session from the authenticated user
- Fires
OnlineSessionLoaded
if successful
-
User Resolution (
withUser
)- Uses your existing authenticated user (configured via 'guards' in zaar.php)
-
Domain Resolution (
withDomain
)- Must be explicitly provided via
setShopifyDomain
- Critical for determining which store to use
- Must be explicitly provided via
- Offline Session (Conditional)
- Required for external apps
- Fires
OfflineSessionLoaded
Common Steps (Both Types)
After strategy-specific steps:
-
Session Merging (
mergeSessions
)- Combines available session data
- Creates unified access token available via
Zaar::session()
-
Data Binding (
bindData
)- Makes sessions available via container
- Enables
Zaar::session()
,Zaar::onlineSession()
,Zaar::offlineSession()
helpers
-
Store Loading (
withShopifyModel
)- Loads/creates Shopify store record
- Fires
ShopifyTenantLoaded
- Event Dispatch (
dispatchEvents
)- Fires all accumulated events
- Ends with
SessionAuthenticated
This flow ensures consistent behavior while accommodating the different requirements of embedded and external apps.
Event Flow and Importance
The events in Zaar are fired in a specific order through dispatchEvents()
, each serving a crucial purpose:
-
OnlineSessionLoaded
- Fired when an online session token is validated
- Contains user identity from Shopify
- Perfect for tracking user activity or session starts
- Only fires for embedded apps or when online token exists
-
OfflineSessionLoaded
- Fired when offline token is available
- Critical for setting up API access
- Use this to initialize API clients or background job configurations
- Contains the permanent access token
-
ShopifyTenantLoaded
- Most important event for multi-tenant apps
- Fired when the Shopify store model is loaded
- This is your chance to:
- Set up database connections
- Initialize tenant-specific services
- Configure API settings
- Load store preferences
- Always fires regardless of authentication type
SessionAuthenticated
- Final event with complete context
- Provides access to:
- Session data (merged online/offline)
- Shopify store model
- Authenticated user
- Perfect for:
- Logging successful authentications
- Starting background processes
- Initializing store-specific features
Additional Critical Events
These events fire during specific operations:
-
ShopifyFoundEvent
- Fires when an existing store is found
- Critical for:
- Updating store metadata
- Syncing store settings
- Checking for plan changes
- Validating store status
-
ShopifyCreated
- Fires for new store installations
- Use for:
- Initial store setup
- Creating default settings
- Welcome notifications
- First-time configurations
-
ShopifyUserCreated
- Fires when a new user is created
- Perfect for:
- Setting up user preferences
- Sending welcome emails
- Initial role assignment
ShopifyOnlineSessionCreated
/ShopifyOfflineSessionCreated
- Fire when new sessions are created
- Use for:
- Token storage
- Session monitoring
- Access logging
The event system is designed to give you complete control over the authentication and initialization process. Each event provides specific context and timing for different aspects of your application's setup.
Domain Resolution
The most important configuration in Zaar is setting up how shop domains are resolved. This controls which store is loaded for both embedded and external apps:
This resolver is called during the authentication flow and determines which store's data and sessions are loaded. For external apps, you must return a domain. For embedded apps, returning null
will use the domain from Shopify's session token.
Usage
Middleware Types
-
Embedded Apps (
shopify.web
)- For apps within Shopify Admin iframe
- Handles session token exchange
- Includes necessary headers
- Example:
-
External Apps (
shopify
)- For standalone/API applications
- Uses offline tokens
- No iframe handling
- Example:
- Public Endpoints (
shopify.public
)- For public-facing endpoints
- Limited shop context
- Example:
Session Management
-
Accessing Sessions
- Manual Session Control
User Management
Configuration
Environment Setup
Package Configuration
Frontend Integration
The package automatically sets up Axios interceptors:
Advanced Usage
Repository Configuration
Testing
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
- CashDash
- All Contributors
License
The MIT License (MIT). Please see License File for more information.
All versions of zaar with dependencies
firebase/php-jwt Version ^6.10
illuminate/contracts Version ^10.0||^11.0|^12.0
laravel/prompts Version ^0.1.0|^0.2.0|^0.3.0|^1.0
spatie/laravel-package-tools Version ^1.16