Laravel Shopify Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**
   ```bash
   composer require kyon147/laravel-shopify
   php artisan vendor:publish --tag=shopify-config

• Publishes config/shopify-app.php and migrations for Shopify integration.

2. Run Migrations

   php artisan migrate
   

   • Creates shops table with required fields (e.g., shopify_offline_access_token, shopify_offline_refresh_token).

3. Configure .env

   SHOPIFY_API_KEY=your_api_key
   SHOPIFY_API_SECRET=your_api_secret
   SHOPIFY_APP_URL=https://your-app-url.com
   SHOPIFY_EXPIRING_OFFLINE_TOKENS=true  # Required for new public apps (post-April 2026)
   

4. First Use Case: OAuth Flow

   • Add routes in routes/web.php:

     Route::shopify();
     

   • Visit /shopify/auth in your browser to trigger the OAuth flow. The package now throws an exception if the API route is accessed directly in a browser (e.g., /shopify/api/products), preventing accidental exposure.

5. Access Shopify API

   use Osiset\ShopifyApp\Facades\Shopify;
   
   $shop = Shopify::getCurrentShop();
   $apiHelper = Shopify::apiHelper();
   $products = $apiHelper->call('GET', '/products');
   

Implementation Patterns

Core Workflows

1. OAuth and Session Management

• Auth Flow:

  • Use Route::shopify() to auto-register OAuth routes (/shopify/auth, /shopify/auth/callback).
  • Customize auth scopes in config/shopify-app.php:

    'scopes' => ['write_products', 'read_orders'],
    

  • Security: Redirect URLs in OAuth and billing views are now escaped to prevent XSS vulnerabilities.

• Session Tokens:

  • For public apps, use SHOPIFY_EXPIRING_OFFLINE_TOKENS=true to handle expiring tokens.
  • The package auto-refreshes tokens via OfflineAccessTokenRefresher before API calls.

• Managed App Installations:

  • Use SessionToken for Checkout UI Extensions or Section Blocks:

    $sessionToken = Shopify::getSessionToken();
    

2. Webhooks

• Register webhook subscriptions in AppServiceProvider:

  public function boot()
  {
      Shopify::subscribe('orders/create', 'App\Http\Controllers\WebhookController@handleOrder');
  }
  

• Handle webhooks in a controller:

  public function handleOrder(Request $request)
  {
      $topic = $request->input('topic');
      $payload = $request->input('payload');
      // Process payload...
  }
  

3. SPA Integration

• Billable Middleware:
  • Protect SPA routes with billing checks:

    Route::middleware(['shopify.billable'])->group(function () {
        Route::get('/dashboard', [DashboardController::class, 'index']);
    });
    

• AppBridge:
  • Use Shopify::appBridge() to generate scripts for Vue/React:

    {!! Shopify::appBridge() !!}
    

4. Data Models

• Extend ShopModel for custom shop data:

  use Osiset\ShopifyApp\Models\ShopModel;
  
  class MyShop extends ShopModel
  {
      protected $table = 'shops';
  }
  

• Access shop data:

  $shop = MyShop::find($shopDomain);
  $shop->shopify_access_token; // Auto-decrypted
  

Integration Tips

API Helper

• Use apiHelper() for REST/GraphQL calls:

  $apiHelper = Shopify::apiHelper();
  $response = $apiHelper->call('GET', '/products', ['limit' => 10]);
  

• GraphQL Support:

  $response = $apiHelper->graphql([
      'query' => '{ products(first: 10) { edges { node { title } } } }'
  ]);
  

Checkout UI Extensions

• Generate session tokens for extensions:

  $sessionToken = Shopify::getSessionToken();
  

• Include in your extension’s session_token field.

Billing and Subscriptions

• Use BillableMiddleware to enforce subscriptions:

  Route::middleware(['shopify.billable'])->group(function () {
      // Protected routes
  });
  

• Customize billing logic in app/Http/Middleware/ShopifyBillableMiddleware.php.

Testing

• Mock Shopify responses in tests:

  $this->mockShopifyApi('GET', '/products', ['products' => []]);
  

New: Proactive Token Refresh

• Background Token Refresh:
  • Schedule a command to proactively refresh expiring offline tokens:

    php artisan shopify:refresh-offline-tokens
    

  • Queue Support: Target specific queues or connections:

    php artisan shopify:refresh-offline-tokens --queue=shopify_queue --connection=database
    

Gotchas and Tips

Pitfalls

1. Expiring Offline Tokens

• Issue: Public apps require expiring offline tokens (post-April 2026). If SHOPIFY_EXPIRING_OFFLINE_TOKENS=false, tokens won’t refresh.

• Fix:

  • Set SHOPIFY_EXPIRING_OFFLINE_TOKENS=true in .env.
  • Run migrations to add shopify_offline_* columns.
  • New: Use the shopify:refresh-offline-tokens command to preemptively refresh tokens before expiration.

• Debugging:

  • Check OfflineAccessTokenRefresher logs for refresh failures.
  • Verify shopify_offline_access_token_expires_at is set correctly.

2. Webhook Verification

• Issue: Webhook payloads may fail verification if SHOPIFY_API_SECRET is incorrect or HMAC headers are missing.
• Fix:
  • Double-check .env for SHOPIFY_API_SECRET.
  • Ensure Shopify’s webhook secret matches your app’s secret.

3. Session Token for Extensions

• Issue: Checkout UI Extensions require a session_token, but Shopify::getSessionToken() may return null if not properly configured.
• Fix:
  • Ensure SHOPIFY_SESSION_TOKEN_ENABLED=true in config/shopify-app.php.
  • For Section Blocks, use Shopify::getSessionTokenForBlock().

4. SPA AppBridge Conflicts

• Issue: AppBridge scripts may conflict with other JS libraries or Blade templates.
• Fix:
  • Exclude AppBridge from auth pages:

    'app_bridge_exclude_routes' => ['shopify.auth', 'shopify.callback'],
    

  • Use Shopify::appBridge(['exclude' => true]) conditionally.

5. Token Encryption

• Issue: If APP_KEY changes, encrypted tokens (e.g., shopify_access_token) become unreadable.
• Fix:
  • Keep APP_KEY consistent across environments.
  • Use php artisan key:generate sparingly.

6. API Route Exposure

• New: The package now throws an exception if API routes (e.g., /shopify/api/*) are accessed directly in a browser.
• Fix:
  • Ensure API routes are only called via JavaScript or backend logic.
  • Use Shopify::apiHelper() in controllers or services, not directly in Blade templates.

Debugging Tips

Logging

• Enable debug mode in config/shopify-app.php:

  'debug' => env('SHOPIFY_DEBUG', false),
  

• Check logs for OAuth errors, token refreshes, or webhook failures.

Common Errors