Reorganize RSpade directory structure for clarity
Improve Jqhtml_Integration.js documentation with hydration system explanation Add jqhtml-laravel integration packages for traditional Laravel projects 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
root
339
node_modules/@jqhtml/core/laravel-bridge/LARAVEL_INTEGRATION.md
generated
vendored
339
node_modules/@jqhtml/core/laravel-bridge/LARAVEL_INTEGRATION.md
generated
vendored
@@ -1,339 +0,0 @@
|
||||
# JQHTML Laravel Integration
|
||||
|
||||
The JQHTML Laravel Bridge is included with the `@jqhtml/core` npm package, making it easy to integrate JQHTML error handling into your Laravel application without requiring a separate Composer package.
|
||||
|
||||
## Installation
|
||||
|
||||
### Step 1: Install JQHTML via npm
|
||||
|
||||
```bash
|
||||
npm install @jqhtml/core
|
||||
```
|
||||
|
||||
### Step 2: Load the Laravel Bridge in your Laravel application
|
||||
|
||||
#### Option A: In `AppServiceProvider` (Recommended)
|
||||
|
||||
Add to `app/Providers/AppServiceProvider.php`:
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
namespace App\Providers;
|
||||
|
||||
use Illuminate\Support\ServiceProvider;
|
||||
|
||||
class AppServiceProvider extends ServiceProvider
|
||||
{
|
||||
public function register()
|
||||
{
|
||||
// Load JQHTML Laravel Bridge from node_modules
|
||||
$jqhtmlBridge = base_path('node_modules/@jqhtml/core/laravel-bridge/autoload.php');
|
||||
|
||||
if (file_exists($jqhtmlBridge)) {
|
||||
require_once $jqhtmlBridge;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Option B: In `composer.json` autoload
|
||||
|
||||
Add to your `composer.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"autoload": {
|
||||
"files": [
|
||||
"node_modules/@jqhtml/core/laravel-bridge/autoload.php"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then run:
|
||||
```bash
|
||||
composer dump-autoload
|
||||
```
|
||||
|
||||
#### Option C: Manual inclusion in `bootstrap/app.php`
|
||||
|
||||
For Laravel 11+, add to `bootstrap/app.php`:
|
||||
|
||||
```php
|
||||
use Illuminate\Foundation\Application;
|
||||
|
||||
return Application::configure(basePath: dirname(__DIR__))
|
||||
->withProviders([
|
||||
// After creating the app, load JQHTML
|
||||
function ($app) {
|
||||
$jqhtmlBridge = base_path('node_modules/@jqhtml/core/laravel-bridge/autoload.php');
|
||||
if (file_exists($jqhtmlBridge)) {
|
||||
require_once $jqhtmlBridge;
|
||||
}
|
||||
}
|
||||
])
|
||||
->create();
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Publish the configuration file (optional)
|
||||
|
||||
Create `config/jqhtml.php`:
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
return [
|
||||
'source_maps_path' => storage_path('jqhtml-sourcemaps'),
|
||||
'show_source_context' => env('APP_DEBUG', false),
|
||||
'context_lines' => 5,
|
||||
'cache_compiled' => !env('APP_DEBUG', false),
|
||||
'compiled_path' => storage_path('jqhtml-compiled'),
|
||||
'enable_source_maps' => env('APP_DEBUG', false),
|
||||
'source_map_mode' => 'external', // 'inline', 'external', or 'both'
|
||||
];
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Error Handling
|
||||
|
||||
The bridge automatically catches and formats JQHTML template errors. When a JQHTML error occurs, it will be displayed with:
|
||||
|
||||
- Template file location with line and column numbers
|
||||
- Source code context with error highlighting
|
||||
- Helpful suggestions for common mistakes
|
||||
- Source map resolution (if available)
|
||||
|
||||
### In Your Blade Templates
|
||||
|
||||
If you're compiling JQHTML templates and want to catch errors:
|
||||
|
||||
```php
|
||||
use Jqhtml\LaravelBridge\JqhtmlException;
|
||||
|
||||
Route::post('/compile-template', function (Request $request) {
|
||||
$templatePath = resource_path('jqhtml/' . $request->input('template'));
|
||||
|
||||
// Use Node.js to compile (via shell_exec, Process, etc.)
|
||||
$result = shell_exec("node compile-jqhtml.js " . escapeshellarg($templatePath));
|
||||
$data = json_decode($result, true);
|
||||
|
||||
if (!$data['success']) {
|
||||
// Create exception from JS error data
|
||||
throw JqhtmlException::createFromJsError($data['error']);
|
||||
}
|
||||
|
||||
return response()->json(['compiled' => $data['code']]);
|
||||
});
|
||||
```
|
||||
|
||||
### Middleware Setup
|
||||
|
||||
Add to your middleware groups in `app/Http/Kernel.php`:
|
||||
|
||||
```php
|
||||
protected $middlewareGroups = [
|
||||
'web' => [
|
||||
// ... other middleware
|
||||
\Jqhtml\LaravelBridge\Middleware\JqhtmlErrorMiddleware::class,
|
||||
],
|
||||
];
|
||||
```
|
||||
|
||||
### Manual Exception Handling
|
||||
|
||||
```php
|
||||
use Jqhtml\LaravelBridge\JqhtmlException;
|
||||
|
||||
try {
|
||||
// Your JQHTML compilation or execution
|
||||
$compiled = compileJqhtmlTemplate($source);
|
||||
} catch (\Exception $e) {
|
||||
// Wrap in JQHTML exception for better display
|
||||
throw new JqhtmlException(
|
||||
$e->getMessage(),
|
||||
'templates/my-template.jqhtml',
|
||||
$lineNumber,
|
||||
$columnNumber,
|
||||
$sourceCode,
|
||||
'Check your template syntax'
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Node.js Integration
|
||||
|
||||
### Compilation Script
|
||||
|
||||
Create `compile-jqhtml.js` in your Laravel project root:
|
||||
|
||||
```javascript
|
||||
#!/usr/bin/env node
|
||||
|
||||
import { parse, generate } from '@jqhtml/core';
|
||||
import fs from 'fs';
|
||||
|
||||
const templatePath = process.argv[2];
|
||||
|
||||
try {
|
||||
const source = fs.readFileSync(templatePath, 'utf8');
|
||||
const ast = parse(source, templatePath);
|
||||
const { code, map } = generate(ast, { sourceMap: true });
|
||||
|
||||
console.log(JSON.stringify({
|
||||
success: true,
|
||||
code,
|
||||
map
|
||||
}));
|
||||
} catch (error) {
|
||||
// Format error for Laravel
|
||||
console.log(JSON.stringify({
|
||||
success: false,
|
||||
error: {
|
||||
message: error.message,
|
||||
filename: error.filename || templatePath,
|
||||
line: error.line,
|
||||
column: error.column,
|
||||
source: error.source,
|
||||
suggestion: error.suggestion
|
||||
}
|
||||
}));
|
||||
process.exit(1);
|
||||
}
|
||||
```
|
||||
|
||||
### Using with Laravel Mix/Vite
|
||||
|
||||
In `vite.config.js`:
|
||||
|
||||
```javascript
|
||||
import { defineConfig } from 'vite';
|
||||
import { parse, generate } from '@jqhtml/core';
|
||||
|
||||
export default defineConfig({
|
||||
plugins: [
|
||||
{
|
||||
name: 'jqhtml',
|
||||
transform(source, id) {
|
||||
if (id.endsWith('.jqhtml')) {
|
||||
try {
|
||||
const ast = parse(source, id);
|
||||
const { code, map } = generate(ast, { sourceMap: true });
|
||||
return { code, map };
|
||||
} catch (error) {
|
||||
// Error will be caught by Laravel bridge
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
});
|
||||
```
|
||||
|
||||
## API Endpoint Example
|
||||
|
||||
Create an API endpoint for compiling JQHTML templates:
|
||||
|
||||
```php
|
||||
// routes/api.php
|
||||
use Jqhtml\LaravelBridge\JqhtmlException;
|
||||
|
||||
Route::post('/api/jqhtml/compile', function (Request $request) {
|
||||
$template = $request->input('template');
|
||||
$filename = $request->input('filename', 'template.jqhtml');
|
||||
|
||||
// Execute Node.js compilation
|
||||
$process = new Process([
|
||||
'node',
|
||||
base_path('compile-jqhtml.js'),
|
||||
'--stdin'
|
||||
]);
|
||||
|
||||
$process->setInput(json_encode([
|
||||
'template' => $template,
|
||||
'filename' => $filename
|
||||
]));
|
||||
|
||||
$process->run();
|
||||
|
||||
if (!$process->isSuccessful()) {
|
||||
$output = json_decode($process->getOutput(), true);
|
||||
|
||||
if (isset($output['error'])) {
|
||||
throw JqhtmlException::createFromJsError($output['error']);
|
||||
}
|
||||
|
||||
throw new \Exception('Compilation failed');
|
||||
}
|
||||
|
||||
return response()->json(json_decode($process->getOutput(), true));
|
||||
});
|
||||
```
|
||||
|
||||
## Laravel Ignition Integration
|
||||
|
||||
The bridge automatically integrates with Laravel Ignition (if installed) to provide enhanced error display. No additional configuration needed.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Bridge not loading
|
||||
|
||||
Ensure `node_modules/@jqhtml/core` exists:
|
||||
```bash
|
||||
ls -la node_modules/@jqhtml/core/laravel-bridge/
|
||||
```
|
||||
|
||||
### Class not found errors
|
||||
|
||||
Clear Laravel's cache:
|
||||
```bash
|
||||
php artisan cache:clear
|
||||
php artisan config:clear
|
||||
composer dump-autoload
|
||||
```
|
||||
|
||||
### Source maps not working
|
||||
|
||||
Ensure the source map directory exists and is writable:
|
||||
```bash
|
||||
mkdir -p storage/jqhtml-sourcemaps
|
||||
chmod 755 storage/jqhtml-sourcemaps
|
||||
```
|
||||
|
||||
## Directory Structure
|
||||
|
||||
After installation, your Laravel project will have:
|
||||
|
||||
```
|
||||
your-laravel-project/
|
||||
├── node_modules/
|
||||
│ └── @jqhtml/
|
||||
│ └── core/
|
||||
│ ├── dist/ # JavaScript runtime
|
||||
│ └── laravel-bridge/ # PHP integration
|
||||
│ ├── src/ # PHP classes
|
||||
│ ├── config/ # Laravel config
|
||||
│ └── autoload.php # Autoloader
|
||||
├── config/
|
||||
│ └── jqhtml.php # Your config (optional)
|
||||
├── storage/
|
||||
│ ├── jqhtml-compiled/ # Compiled templates
|
||||
│ └── jqhtml-sourcemaps/ # Source maps
|
||||
└── compile-jqhtml.js # Node compilation script
|
||||
```
|
||||
|
||||
## Benefits of This Approach
|
||||
|
||||
1. **Single Package**: Everything comes from npm, no Composer package needed
|
||||
2. **Version Sync**: PHP and JS code always match versions
|
||||
3. **Simple Updates**: Just `npm update @jqhtml/core`
|
||||
4. **No Private Packagist**: No need for private Composer repositories
|
||||
5. **CI/CD Friendly**: Works with standard Node.js deployment pipelines
|
||||
|
||||
## License
|
||||
|
||||
MIT - Same as @jqhtml/core
|
||||
Reference in New Issue
Block a user