onairos/laravel.txt

The Onairos Library is a collection of functions that enable Applications to connect and communicate data with Onairos Identities via User Authorization. Integration for developers is seamless, simple and effective for all applications. LLM SDK capabiliti

# Onairos NPM Package - Laravel Integration Context

## Laravel Integration Overview
- **Package Version**: 2.2.1+
- **Laravel Support**: Laravel 9+ with Vite
- **Integration Types**: Blade Templates, Vue.js, React, Mixed Approaches
- **Build System**: Vite with custom plugins
- **Mobile Support**: Auto-detection with responsive OAuth flows

## Key Laravel-Specific Features ✅
1. **Blade Template Integration**: Direct PHP template support without React setup
2. **Vite Plugin System**: Custom plugins for Laravel, Vue, and React optimization
3. **Multi-Framework Support**: Seamless Vue.js and React integration within Laravel
4. **Mobile-First Design**: Automatic mobile detection with appropriate OAuth flows
5. **Laravel Backend Integration**: PHP controllers and route handlers
6. **Production Optimization**: Laravel-specific build and deployment strategies

## Laravel Integration Architecture ✅

### Entry Points
- **Main Package**: `onairos` (standard React components)
- **Laravel Blade**: `onairos/blade` (vanilla JS helpers)
- **Vite Plugin**: `onairos/vite-plugin` (build-time optimization)
- **Vue Component**: `onairos/src/laravel/OnairosVue.vue` (Vue 3 SFC)

### Build Targets
- **UMD Bundle**: `dist/onairos.bundle.js` (browser globals)
- **ES Module**: `dist/onairos.esm.js` (modern imports)
- **Laravel Specific**: `dist/onairos-laravel.js` (Blade helpers)

## Integration Approaches ✅

### 1. Blade Templates (PHP-Focused)
**Use Case**: Traditional Laravel apps with minimal JavaScript
**Technology Stack**: PHP Blade + Vanilla JS + Tailwind CSS

**Implementation**:
```javascript
// Vite plugin handles build-time optimization
onairosLaravelPlugin({
  bladeSupport: true,      // Watch .blade.php files
  injectGlobals: true,     // Auto-inject helpers
  optimizeDeps: true,      // Optimize for Laravel
  enableHMR: true          // Hot module replacement
})
```

**Runtime Flow**:
1. `initializeOnairosForBlade()` sets up global configuration
2. `createOnairosButton()` generates DOM elements with event handlers
3. Mobile detection switches between popup/redirect OAuth flows
4. Custom events communicate with Laravel backend

### 2. Vue.js Integration
**Use Case**: Laravel apps using Vue.js as primary frontend
**Technology Stack**: PHP Blade + Vue 3 + Composition API + Vite

**Implementation**:
```javascript
// Specialized Vue plugin with auto-imports
onairosVuePlugin({
  autoImport: true,        // Auto-import OnairosButton in .vue files
  optimizeDeps: true       // Optimize Vue + Onairos dependencies
})
```

**Component Architecture**:
- **OnairosVue.vue**: Complete Vue 3 component with Composition API
- **Props System**: Vue-style props with validation and defaults
- **Event System**: Vue custom events (@complete, @error, @loading)
- **Reactive State**: Vue reactivity for loading, success, error states

### 3. React Integration
**Use Case**: Laravel apps using React as primary frontend
**Technology Stack**: PHP Blade + React 18 + JSX + Vite

**Implementation**:
```javascript
// React-specific optimizations
onairosReactPlugin({
  autoImport: true,        // Auto-import in .jsx/.tsx files
  optimizeDeps: true       // Optimize React + Onairos bundle
})
```

**Integration Pattern**:
- Uses existing `OnairosButton` React component
- Laravel Vite plugin handles React-specific builds
- Automatic JSX transformation and optimization

## Technical Implementation Details ✅

### Vite Plugin System
**Core Plugin**: `onairosLaravelPlugin()`
- **Development**: Injects initialization scripts, enables HMR
- **Production**: Optimizes bundles, handles asset generation
- **File Watching**: Watches .blade.php files for changes
- **Dependency Optimization**: Pre-bundles Onairos for faster dev server

**Specialized Plugins**:
- `onairosVuePlugin()`: Vue-specific optimizations and auto-imports
- `onairosReactPlugin()`: React-specific optimizations and auto-imports

### Mobile Detection & OAuth Flow
```javascript
// Automatic mobile detection
const isMobile = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent) || (window.innerWidth <= 768);

// OAuth flow selection
if (isMobile) {
  // Redirect-based flow for mobile browsers
  window.location.href = authUrl;
} else {
  // Popup-based flow for desktop
  window.open(authUrl, 'onairosAuth', 'width=450,height=700');
}
```

### Laravel Backend Integration
```php
// Example Laravel controller
class OnairosController extends Controller {
    public function callback(Request $request) {
        $data = $request->validate([
            'user_hash' => 'required|string',
            'connections' => 'required|array',
            'data_types' => 'required|array'
        ]);
        
        auth()->user()->update([
            'onairos_hash' => $data['user_hash'],
            'onairos_connections' => $data['connections']
        ]);
        
        return response()->json(['success' => true]);
    }
}
```

## Differences from Standard Integration ✅

### 1. Build System Integration
**Standard**: Uses webpack UMD build for browser globals
**Laravel**: Custom Vite plugins with Laravel-specific optimizations

### 2. Component Rendering
**Standard**: React components mounted via ReactDOM
**Laravel Blade**: Vanilla JS functions that generate DOM elements
**Laravel Vue**: Native Vue 3 single-file components
**Laravel React**: React components optimized for Laravel Vite

### 3. State Management
**Standard**: React state hooks and context
**Laravel Blade**: Global window objects and DOM manipulation
**Laravel Vue**: Vue 3 Composition API with reactive refs
**Laravel React**: React hooks within Laravel ecosystem

### 4. OAuth Flow Handling
**Standard**: Hardcoded popup approach
**Laravel**: Environment-aware with automatic mobile detection
- Desktop: Popup windows
- Mobile: Redirect-based flow with return URL handling

### 5. Styling Integration
**Standard**: Inline styles and CSS-in-JS
**Laravel**: 
- Tailwind CSS integration out of the box
- Scoped Vue styles for Vue components
- Laravel Mix/Vite asset compilation
- Global CSS injection for Blade templates

### 6. Development Experience
**Standard**: Create React App or manual webpack setup
**Laravel**: 
- Vite HMR with Blade file watching
- Automatic dependency optimization
- Laravel-specific error handling and debugging
- Integration with Laravel development tools

## Package Structure Changes ✅

### New Files Added
```
src/laravel/
├── blade-helpers.js         # Vanilla JS helpers for Blade templates
├── vite-plugin.js          # Custom Vite plugins for Laravel
└── OnairosVue.vue          # Vue 3 component for Laravel

LARAVEL_INTEGRATION_GUIDE.md # Comprehensive integration guide
laravel.txt                  # This context file
```

### Package.json Exports
```json
{
  "exports": {
    ".": {
      "import": "./dist/onairos.esm.js",
      "require": "./dist/onairos.bundle.js",
      "browser": "./dist/onairos.bundle.js"
    },
    "./laravel": {
      "import": "./dist/onairos.laravel.js",
      "require": "./dist/onairos.laravel.js"
    },
    "./blade": "./src/laravel/blade-helpers.js",
    "./vite-plugin": "./src/laravel/vite-plugin.js"
  }
}
```

### Webpack Configuration
```javascript
// Laravel-specific build target
{
  entry: {
    'onairos-laravel': path.resolve(__dirname, 'src', 'laravel', 'blade-helpers.js')
  },
  output: {
    filename: '[name].js',
    libraryTarget: 'umd',
    library: 'OnairosLaravel'
  }
}
```

## Developer Experience Improvements ✅

### 1. Installation Simplicity
```bash
# Single package for all Laravel integration types
npm install onairos

# Optional: Framework-specific plugins
npm install --save-dev @vitejs/plugin-vue      # For Vue
npm install --save-dev @vitejs/plugin-react    # For React
```

### 2. Configuration Patterns
**Blade Only**:
```javascript
// Minimal setup
onairosLaravelPlugin({ bladeSupport: true })
```

**Vue Integration**:
```javascript
// Vue + Laravel optimization
plugins: [laravel(), vue(), onairosVuePlugin()]
```

**React Integration**:
```javascript
// React + Laravel optimization  
plugins: [laravel(), react(), onairosReactPlugin()]
```

### 3. Environment Configuration
```env
# Laravel .env integration
VITE_ONAIROS_API_KEY=your_api_key
VITE_ONAIROS_TEST_MODE=true
VITE_ONAIROS_BASE_URL=https://api2.onairos.uk
```

### 4. Debug and Development
```javascript
// Enhanced debugging for Laravel
initializeOnairosForBlade({
  debug: true,                    // Enable console logging
  testMode: import.meta.env.DEV,  // Auto-detect dev environment
  autoDetectMobile: true          // Mobile detection logging
});
```

## Production Deployment ✅

### 1. Build Process
```bash
# Laravel standard build
npm run build

# Generates optimized bundles:
# - dist/onairos.bundle.js (UMD)
# - dist/onairos.esm.js (ES modules)
# - dist/onairos-laravel.js (Laravel-specific)
```

### 2. Laravel Optimization
```php
// Laravel production commands
php artisan optimize        # Route/config caching
php artisan view:cache     # Blade template caching
php artisan config:cache   # Environment caching
```

### 3. CDN Integration
```env
# Laravel asset CDN
ASSET_URL=https://your-cdn.com

# Automatic asset URL prefixing
# https://your-cdn.com/build/assets/onairos-laravel.abc123.js
```

## Testing Strategy ✅

### 1. Unit Tests
- Laravel Blade helpers functionality
- Vue component props and events
- Vite plugin configuration
- Mobile detection logic

### 2. Integration Tests
- Laravel controller callbacks
- OAuth flow completion
- Database integration
- Environment variable handling

### 3. End-to-End Tests
- Full Laravel application flows
- Mobile and desktop OAuth
- Vue/React component integration
- Production build verification

## Known Laravel-Specific Considerations ✅

### 1. CSRF Protection
Laravel CSRF tokens are automatically handled in AJAX requests when using Laravel's default Axios configuration.

### 2. Route Caching
OAuth callback routes must be registered before route caching in production.

### 3. Session Management
Laravel sessions are used for OAuth state management alongside Onairos user hashes.

### 4. Middleware Integration
Custom Laravel middleware can be created to handle Onairos authentication states.

### 5. Queue Integration
Heavy OAuth processing can be queued using Laravel's queue system for better performance.

## Migration from Standard Integration ✅

### For Existing React Users
- No changes needed to existing React components
- Optional: Add Laravel Vite plugin for optimization
- Optional: Use Laravel backend integration features

### For New Laravel Projects
- Choose integration approach (Blade/Vue/React)
- Install appropriate Vite plugins
- Follow Laravel-specific setup guide
- Configure environment variables

### For Hybrid Approaches
- Mix Blade templates with Vue/React components
- Use different integration methods in different parts of the app
- Leverage Laravel's flexibility for gradual adoption

## Performance Considerations ✅

### 1. Bundle Size Optimization
- Vite plugins optimize bundle splitting
- Laravel-specific builds exclude unnecessary dependencies
- Tree-shaking removes unused code

### 2. Loading Performance
- Lazy loading for Vue/React components
- Preloading critical OAuth dependencies
- Service worker integration for offline capability

### 3. Mobile Performance
- Automatic redirect vs popup optimization
- Touch-friendly UI components
- Reduced JavaScript payload for mobile

## Troubleshooting Guide ✅

### Common Issues

1. **Vite Plugin Not Working**
   - Clear Vite cache: `rm -rf node_modules/.vite`
   - Check plugin order in vite.config.js
   - Verify import paths

2. **Blade Helpers Unavailable**
   - Ensure `initializeOnairosForBlade()` is called
   - Check browser console for initialization errors
   - Verify script loading order

3. **Vue Component Not Rendering**
   - Confirm Vue 3 is properly installed
   - Check component registration
   - Verify Vite Vue plugin configuration

4. **Mobile OAuth Issues**
   - Test popup blockers disabled
   - Verify redirect URLs are whitelisted
   - Check mobile user agent detection

### Debug Commands
```javascript
// Check initialization status
console.log(typeof window.createOnairosButton); // Should be "function"
console.log(typeof window.OnairosConfig);       // Should be "object"

// Test mobile detection
console.log(window.OnairosUtils.isMobile);      // Boolean

// Verify Vite environment
console.log(import.meta.env.DEV);               // Development mode
console.log(import.meta.env.VITE_ONAIROS_*);    // Environment variables
```

## Future Laravel Enhancements 🚀

### Planned Features
1. **Artisan Commands**: CLI commands for setup and configuration
2. **Laravel Packages**: Composer package for PHP-side integration
3. **Blade Directives**: Custom `@onairos` Blade directive
4. **Middleware Package**: Pre-built authentication middleware
5. **Model Traits**: Eloquent traits for user Onairos data
6. **Testing Helpers**: Laravel testing utilities for Onairos

### Experimental Features
1. **Server-Side Rendering**: Laravel + Inertia.js SSR support
2. **API Resource Integration**: Laravel API resource transformers
3. **Livewire Components**: Native Livewire component integration
4. **Laravel Sail**: Docker development environment support