Laravel afbeeldingsgereedschap

Deterministische, query-gestuurde afbeeldingsgeneratie voor Laravel - geïnspireerd door vite-imagetools.

• Roep het één keer aan in Blade/PHP en krijg een openbare URL

  {{ ImageTools::asset('public/images/hero.jpg?w=1200&h=630&fit=contain&format=webp&q=82') }}
  

• Bestanden worden naar je geconfigureerde bestandssysteemschijf geschreven met stabiele namen (bijv. hero--a1b2c3d4e5.webp), perfect voor CDN caching met een lange levensduur.
• Een klein PHP manifest koppelt je canonieke verzoek aan het opgeslagen bestand, dus volgende aanroepen zijn direct.

Kenmerken

• 🔁 Deterministische bestandsnamen gebaseerd op de bron + gesorteerde query opties
• 🧩 E envoudige query API: w, h, fit, q, format
• 📦 E én schijf om ze allemaal te beheersen - werkt met public, S3/R2 of elke andere Laravel schijf
• 🔎 S canneropdracht om alle afbeeldingen waarnaar in je code wordt verwezen vooraf te genereren
• 🧹 Clear commando om gegenereerde bestanden en het manifest te verwijderen

Vereisten

• PHP 8.2+
• Laravel 10+ (werkt met 10/11/12)
• Stuurprogramma voor afbeeldingen: Imagick (aanbevolen) of GD voor spatie/image

Installatie

composer require isapp/laravel-imagetools

Auto-discovery registreert de serviceprovider en de ImageTools facade.

Configuratie publiceren (optioneel)

Als je de standaardinstellingen wilt aanpassen, publiceer dan het configuratiebestand:

php artisan vendor:publish --provider="Isapp\\ImageTools\\ServiceProvider"

Snel aan de slag

<img
  src="{{ ImageTools::asset('public/images/placeholder.jpg?w=640&q=75&format=webp') }}"
  width="640"
  height="360"
  alt="Placeholder"
/>

Zuiver PHP

use Isapp\\ImageTools\\Facades\\ImageTools;

$url = ImageTools::asset('resource/images/placeholder.jpg?w=640&q=75&format=webp');

Ook ondersteund (en gedetecteerd door de scanner):

{{ app(Isapp\ImageTools\ImageTools::class)->asset('resource/images/pic.jpg?w=800') }}
{{ app('image-tools')->asset('resource/images/pic.jpg?w=800') }}
{{ \Illuminate\Support\Facades\App::make('image-tools')->asset('resource/images/pic.jpg?w=800') }}
{{ App::make(Isapp\ImageTools\ImageTools::class)->asset('resource/images/pic.jpg?w=800') }}

Configuratie

Alle opties staan in config/image-tools.php (met inline commentaar). Je kunt ze ook regelen via ENV:

IMAGE_TOOLS_DISK=public
IMAGE_TOOLS_MANIFEST_PATH=bootstrap/cache/image-tools.php
IMAGE_TOOLS_BLADE_PATHS=resources/views,modules/*/resources/views
IMAGE_TOOLS_PHP_PATHS=app,modules

Belangrijkste opties:

• disk - Laravel bestandssysteem schijf waar verwerkte bestanden worden geschreven en geserveerd vanaf (public, s3, r2, ...).
• manifest_path - Pad naar het PHP manifest bestand dat de mapping opslaat.
• blade_paths - Directories met Blade sjablonen om te scannen op gebruik.
• php_paths - Extra PHP mappen om te scannen (controllers, services, etc.).

Het verzoek is gecanoniseerd: query sleutels worden gesorteerd voor het hashen, dus ?h=630&w=1200 is gelijk aan ?w=1200&h=630.

Query opties

Opdrachten

Vooraf genereren vanuit code (CI-vriendelijk)

Scant je codebase en genereert afbeeldingen voor ontdekte toepassingen.

php artisan imagetools:generate

De scanner kijkt in config('image-tools.blade_paths') en config('image-tools.php_paths') en detecteert:

• ImageTools::asset('…')
• Container-opgeloste aanroepen (bijv. app(ImageTools::class)->asset('…'), app('image-tools')->asset('…'), App::make(...)->asset('…'))

Wis gegenereerde bestanden

Verwijdert alle bestanden waarnaar in het huidige manifest wordt verwezen en verwijdert vervolgens het manifestbestand.

php artisan imagetools:clear

Wat wordt geschreven

• Een verwerkt bestand op de geconfigureerde schijf, onder image-tools/<name>--<hash>.<ext>.
• Een PHP manifest (standaard bootstrap/cache/image-tools.php) met vermeldingen als

  return [
      'resource/images/hero.jpg?h=630&w=1200&fit=contain&format=webp&q=82' => [
          'path' => 'image-tools/hero--a1b2c3d4e5.webp',
          'disk' => 'public',
      ],
  ];
  

Tips

• Deterministische namen → lange CDN cache is veilig; verander opties of de bron om de cache kapot te maken.
• Schijven: configureer voor S3/R2 een publieke emmer of gebruik ondertekende URL's zoals nodig.
• Kwaliteit/formaten: webp/avif wint meestal; meet voor/na.

Problemen oplossen

• Class ...\ImageTools not found - zorg ervoor dat het pakket is geïnstalleerd en automatisch wordt gedetecteerd; voer composer dump-autoload uit.
• ImagickException / extensie ontbreekt - installeer en activeer Imagick (voorkeur) of GD voor je PHP runtime.
• width(): Argument #1 must be of type int - geef numerieke waarden door in de query (w=640, niet w=640px).
• fitw en h zijn vereist - als je fit gebruikt, geef dan beide dimensies op.
• Geen URL / 404 - controleer of de geconfigureerde disk een URL-generator heeft (php artisan storage:link voor public schijf).

Versiebeheer

Dit pakket volgt SemVer. Tot 1.0.0 kunnen kleine versies (0.x) brekende veranderingen bevatten.

Beveiliging

Als je een beveiligingsprobleem ontdekt, stuur dan een e-mail naar contact@isapp.be in plaats van een openbaar probleem te openen.

Bijdragen

Bijdragen zijn welkom! Als je suggesties hebt voor verbeteringen, nieuwe functies of problemen vindt, voel je dan vrij om een pull request in te dienen of een probleem te openen in deze repository.

Bedankt voor je hulp om dit pakket beter te maken voor de gemeenschap!

Licentie

Dit project is open-sourced software gelicenseerd onder de MIT Licentie.

Je bent vrij om het te gebruiken, aan te passen en te verspreiden in je projecten, zolang je voldoet aan de voorwaarden van de licentie.

Credits

Gebouwd door ISAPP. Maakt gebruik van de uitstekende spatie/image.

Bekijk onze software ontwikkelingsdiensten op isapp.be.