Outils d'images Laravel

Génération d'images déterministe et pilotée par des requêtes pour Laravel - inspiré par vite-imagetools.

• Appelez-le une fois dans Blade/PHP et obtenez une URL publique

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

• Les fichiers sont écrits sur le disque de votre système de fichiers configuré avec des noms stables (par exemple hero--a1b2c3d4e5.webp), parfaits pour la mise en cache CDN à long terme.
• Un petit manifeste PHP fait correspondre votre demande canonique au fichier stocké, de sorte que les appels ultérieurs sont instantanés.

Caractéristiques

• 🔁 Noms de fichiers déterministes basés sur la source + options de requête triées
• 🧩 API de requête simple: w, h, fit, q, format
• 📦 Un disque pour tous les gouverner - fonctionne avec public, S3/R2 ou n'importe quel disque Laravel
• 🔎 Commande Scanner pour pré-générer toutes les images référencées dans votre code
• 🧹 Commande Clear pour supprimer les fichiers générés et le manifeste

Exigences

• PHP 8.2+
• Laravel 10+ (fonctionne avec 10/11/12)
• Pilote d'image : Imagick (recommandé) ou GD pour spatie/image

Installation de l'application

composer require isapp/laravel-imagetools

L'auto-découverte enregistrera le fournisseur de service et la façade ImageTools.

Publier la configuration (optionnel)

Si vous souhaitez personnaliser les paramètres par défaut, publiez le fichier de configuration :

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

Démarrage rapide

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

PHP pur

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

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

Également pris en charge (et détecté par l'analyseur) :

{{ 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') }}

Configuration

Toutes les options se trouvent à l'adresse config/image-tools.php (avec des commentaires en ligne). Vous pouvez également les contrôler 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

Options clés :

• disk - Disque du système de fichiers Laravel où les fichiers traités sont écrits et servis (public, s3, r2, ...).
• manifest_path - Chemin d'accès au fichier manifeste PHP qui stocke le mappage.
• blade_paths - Répertoires avec les modèles Blade à analyser pour les utilisations.
• php_paths - Répertoires PHP supplémentaires à analyser (contrôleurs, services, etc.).

La requête est canonisée: les clés de la requête sont triées avant le hachage, donc ?h=630&w=1200 équivaut à ?w=1200&h=630.

Options de requête

Commandes

Pré-générer à partir du code (adapté à CI)

Analyse votre base de code et génère des images pour les utilisations découvertes.

php artisan imagetools:generate

L'analyseur examine config('image-tools.blade_paths') et config('image-tools.php_paths') et détecte :

• ImageTools::asset('…')
• Les appels résolus par le conteneur (par exemple app(ImageTools::class)->asset('…'), app('image-tools')->asset('…'), App::make(...)->asset('…'))

Effacer les fichiers générés

Supprime tous les fichiers référencés dans le manifeste actuel et supprime ensuite le fichier manifeste.

php artisan imagetools:clear

Ce qui est écrit

• Un fichier traité sur le disque configuré, sous image-tools/<name>--<hash>.<ext>.
• Un manifeste PHP (par défaut bootstrap/cache/image-tools.php) avec des entrées telles que

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

Conseils

• Lesnoms déterministes → cache CDN long sont sûrs ; changez les options ou la source pour casser le cache.
• Disques: pour S3/R2 configurez un bucket public ou utilisez des URLs signées si nécessaire.
• Qualité/Formats: webp/avif l'emporte généralement ; mesurez avant/après.

Dépannage

• Class ...\ImageTools not found - assurez-vous que le paquet est installé et découvert automatiquement ; exécutez composer dump-autoload.
• ImagickException /Extension manquante: installez et activez Imagick (de préférence) ou GD pour votre moteur d'exécution PHP.
• width(): Argument #1 must be of type int - passez des valeurs numériques dans la requête (w=640, et non w=640px).
• fit nécessite w et h - si vous utilisez fit, indiquez les deux dimensions.
• Pas d'URL / 404 - vérifiez que le site disk configuré dispose d'un générateur d'URL (php artisan storage:link pour le disque public ).

Versionnement

Ce paquetage suit SemVer. Jusqu'à 1.0.0, les versions mineures (0.x) peuvent inclure des changements importants.

Sécurité

Si vous découvrez un problème de sécurité, veuillez envoyer un courriel à contact@isapp.be au lieu d'ouvrir un problème public.

Contribuer

Les contributions sont les bienvenues ! Si vous avez des suggestions d'améliorations, de nouvelles fonctionnalités, ou si vous trouvez des problèmes, n'hésitez pas à soumettre une demande d'extraction ou à ouvrir un problème dans ce dépôt.

Merci de contribuer à l'amélioration de ce paquet pour la communauté !

Licence

Ce projet est un logiciel libre sous licence MIT.

Vous êtes libre de l'utiliser, de le modifier et de le distribuer dans vos projets, tant que vous respectez les termes de la licence.

Crédits

Construit par ISAPP. Utilise l'excellent spatie/image.

Consultez nos services de développement de logiciels sur isapp.be.