zapwebp / laravel
Laravel integration for Zapwebp transparency-safe image conversion engine.
Requires
- php: ^8.2
- illuminate/filesystem: ^10.0|^11.0|^12.0
- illuminate/process: ^10.0|^11.0|^12.0
- illuminate/support: ^10.0|^11.0|^12.0
- illuminate/validation: ^10.0|^11.0|^12.0
Requires (Dev)
- orchestra/testbench: ^8.0|^9.0
- phpunit/phpunit: ^10.0|^11.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
First-party Laravel bridge for the Zapwebp transparency-safe image conversion engine.
Covers: Laravel facade (Zap::convert, Zap::batch, Zap::check), Blade directives (@zapwebp, @picture, @srcset), Artisan commands (php artisan zap:convert), SafeImage validation rule, and automatic ConvertUploads middleware.
Does not cover: Client-side JavaScript bundling or remote cloud storage direct SDK bindings.
Applies to: zapwebp-laravel v1.0.0 and later, PHP >=8.2, Laravel >=10.0.
Quick start
composer require zapwebp/laravel
Convert an image using the Zap facade:
use Zapwebp\Laravel\Facades\Zap; $result = Zap::convert(storage_path('app/uploads/hero.png'), [ 'to' => 'webp', 'quality' => 85, 'clean' => true, ]); echo $result->outputPath; // /path/to/hero.webp echo $result->savedBytes(); // e.g. 45200 bytes
What it does
zapwebp-laravel bridges the Laravel framework with the Zapwebp conversion engine, executing conversions with process isolation and zero third-party telemetry:
- Transparency Preservation: Guaranteed alpha channel retention for WebP, AVIF, and PNG.
- Strict Process Isolation: Zero shell concatenation; uses PHP
Processarray argument passing. - Artisan Commands: CLI tools
php artisan zap:convertandphp artisan zap:check. - Blade Directives & Picture Helper:
@zapwebp,@picture, and@srcsetdirectives for instant modern responsive markup. - Laravel Facade: Clean, expressive syntax via
Zap::convert(),Zap::batch(),Zap::check(). - Validation Rule:
SafeImagerule verifies format integrity and alpha presence. - Upload Middleware:
ConvertUploadsmiddleware automatically converts incoming uploads on the fly. - Zero Third-Party Telemetry: 100% local in-memory or on-disk processing.
Requirements
- PHP >= 8.2
- Laravel >= 10.0
- Zapwebp CLI installed locally or globally (
npm install -g zapwebporpnpm add -D zapwebp)
Configuration
Publish the configuration file (optional):
php artisan vendor:publish --tag=zapwebp-config
In config/zapwebp.php:
return [ 'binary' => env('ZAPWEBP_BINARY', 'zap'), 'defaults' => [ 'format' => env('ZAPWEBP_DEFAULT_FORMAT', 'webp'), 'quality' => (int) env('ZAPWEBP_DEFAULT_QUALITY', 85), 'clean' => true, 'assert_alpha' => true, ], 'timeout' => 60, ];
Usage
1. Artisan Commands
# Convert a single asset php artisan zap:convert resources/images/logo.svg --to=webp # Batch convert an entire directory with scale variants php artisan zap:convert resources/images --to=webp --scale=1,2,3 --out=public/images # CI build check: asserts that all images are up-to-date and transparent php artisan zap:check resources/images
2. Blade Directives
{{-- Convert an image inline to WebP --}} <img src="@zapwebp('images/logo.png', ['width' => 200, 'quality' => 80])" alt="Logo"> {{-- Generate <picture> element with WebP + AVIF fallbacks --}} @picture('images/hero.png', ['alt' => 'Hero', 'class' => 'hero-banner'], ['formats' => ['avif', 'webp'], 'scales' => [1, 2, 3]]) {{-- Generate srcset attribute --}} <img src="{{ zap_url('images/logo.png') }}" srcset="@srcset('images/logo.png', [1, 2, 3])" alt="Logo">
3. Facade Conversion
use Zapwebp\Laravel\Facades\Zap; // Single image conversion returning ConversionResult $result = Zap::convert(storage_path('app/uploads/hero.png'), [ 'to' => 'webp', 'quality' => 85, 'clean' => true, ]); // Batch conversion $outputs = Zap::batch([ storage_path('app/uploads/icon.svg'), storage_path('app/uploads/banner.jpg'), ], [ 'to' => 'avif', ]);
4. Validation Rule
use Illuminate\Http\Request; use Zapwebp\Laravel\Rules\SafeImage; public function upload(Request $request) { $request->validate([ 'avatar' => ['required', 'file', new SafeImage(requireAlpha: true)], ]); }
5. Automatic Upload Middleware
In bootstrap/app.php or app/Http/Kernel.php:
use Zapwebp\Laravel\Middleware\ConvertUploads; ->withMiddleware(function (Middleware $middleware) { $middleware->append(ConvertUploads::class); })
Errors
| Code / Exception | Cause | Fix |
|---|---|---|
ZapwebpBinaryNotFoundException |
zap binary is not located in $PATH or configured path |
Install zapwebp via npm or set ZAPWEBP_BINARY in .env |
UnsafeSvgException |
Input SVG contains active scripts or external entities | Remove executable content from SVG |
AlphaDropException |
Converting transparent source to JPEG without background | Specify 'background' => '#ffffff' in options |
ConversionTimeoutException |
Conversion process exceeded configured timeout limit | Increase 'timeout' in config/zapwebp.php |
For agents
{
"tool": "zapwebp-laravel",
"facade": "Zapwebp\\Laravel\\Facades\\Zap",
"artisan": ["zap:convert", "zap:check"],
"blade": ["@zapwebp", "@picture", "@srcset"],
"middleware": "Zapwebp\\Laravel\\Middleware\\ConvertUploads",
"rule": "Zapwebp\\Laravel\\Rules\\SafeImage"
}
Related
- Laravel Documentation: Complete Laravel package walkthrough and test helpers.
- CLI Reference: Underlying terminal CLI executed by the package.
- Errors Reference: System error codes and fixes.
License
MIT © Eldrex Delos Reyes Bula