bouleluciole/laravel-eloquent-traits

Reusable Eloquent traits for UUID, ULID, Slugs and more

0.1 2026-01-05 15:16 UTC

Requires

• php: ^8.2
• illuminate/database: ^11.42|^12.0
• illuminate/support: ^11.42|^12.0
• intervention/image: ^3.11
• intervention/image-laravel: ^1.5

Requires (Dev)

• orchestra/testbench: ^9.15
• pestphp/pest: ^4.1
• pestphp/pest-plugin-laravel: ^4.0

MIT

• Boule Luciole

README

Une collection de traits Eloquent robustes et configurables pour automatiser les tâches répétitives de vos modèles Laravel : gestion des médias (compression, miniatures, nettoyage), slugs uniques et identifiants UUID.

🚀 Installation

Installez le package via Composer :

composer require bouleluciole/laravel-eloquent-traits

Le package nécessite PHP 8.2+ et Laravel 11.0+. Les fonctionnalités d'image dépendent de intervention/image (v3).

🛠 Fonctionnalités

1. Compression d'Images (CompressImage)

Compresse intelligemment vos images au format WebP pour économiser de l'espace disque tout en préservant la qualité.

use EloquentTraits\Traits\CompressImage;

class Post extends Model
{
    use CompressImage;

    // Champs à compresser (clé => disque ou simplement valeur si disque par défaut)
    protected $compressibleImageFields = [
        'photo_path' => 'public',
        'avatar'
    ];

    // Taille maximale autorisée en Ko (défaut: 500)
    protected $imageCompressionMaxSize = 800;
}

2. Génération de Miniatures (GeneratesThumbnail)

Génère automatiquement des thumbnails WebP lors de la sauvegarde. Supporte les fichiers locaux et les URLs distantes.

use EloquentTraits\Traits\GeneratesThumbnail;

class Photo extends Model
{
    use GeneratesThumbnail;

    protected $thumbnailConfig = [
        [
            'source' => 'photo_path',
            'target' => 'thumbnail',
            'width'  => 300,
            'height' => 200,
            'prefix' => 'thumbnails/posts/'
        ]
    ];
}

3. Nettoyage Automatique (DeletesFilesOnModel)

Supprime physiquement les fichiers du stockage lorsque le modèle est supprimé ou lorsqu'un champ de fichier est mis à jour. Gère nativement le SoftDeletes.

use EloquentTraits\Traits\DeletesFilesOnModel;

class Document extends Model
{
    use DeletesFilesOnModel;

    // Champs contenant des chemins de fichiers
    protected $fileFields = ['file_path', 'attachment'];

    // Disques à scanner pour la suppression
    protected $fileDisks = ['public', 's3'];
}

4. Slugs Uniques (GeneratesSlug)

Génère des slugs URL-friendly uniques. Si un slug existe déjà, il ajoute automatiquement un suffixe incrémental (ex: titre, titre-2, etc.).

use EloquentTraits\Traits\GeneratesSlug;

class Article extends Model
{
    use GeneratesSlug;

    protected string $slugSourceField = 'title'; // Défaut: 'name'
    protected string $slugColumn = 'slug';       // Défaut: 'slug'
}

5. Identifiants UUID (UseUuid)

Remplace les IDs incrémentaux par des UUIDs version 4 générés automatiquement.

use EloquentTraits\Traits\UseUuid;

class Order extends Model
{
    use UseUuid;

    // Désactive l'auto-incrémentation pour ce modèle
    public $incrementing = false;
    protected $keyType = 'string';
}

🧪 Tests

Le package est testé avec Pest PHP et utilise Orchestra Testbench pour simuler un environnement Laravel complet.

composer test

📖 Détails Techniques

Cycle de vie (Events)

Les traits utilisent les hooks standards d'Eloquent (creating, saving, saved, deleting, updating) pour agir au bon moment sans intervention manuelle.

Gestion du stockage

Tous les traits de fichiers respectent l'abstraction du système de fichiers de Laravel (Storage). Ils sont compatibles avec les disques local, public, s3, etc.

📄 Licence

Ce projet est sous licence MIT. Pour plus d'informations, veuillez consulter le fichier LICENSE.

🤝 Contribution

Les contributions sont les bienvenues !

1. Forkez le projet.
2. Créez votre branche de fonctionnalité (git checkout -b feature/AmazingFeature).
3. Commitez vos changements (git commit -m 'Add some AmazingFeature').
4. Pushez sur la branche (git push origin feature/AmazingFeature).
5. Ouvrez une Pull Request.

Développé avec ❤️ par Boule Luciole - [e-mail]