README

Table des matières

1. Description
2. Installation
3. Prérequis
4. Fonctionnalités
   • 4.1 TransformableProxy
   • 4.2 AttributeProxy
   • 4.3 GitPushDirective
   • 4.4 GitDiffDirective
   • 4.5 GitTagDirective
5. Configuration
   • 5.1 Publication de la configuration
   • 5.2 Configuration des dépôts Git
   • 5.3 Configuration des extensions
6. Documentation
7. Tests
8. Contribuer
9. Licence
10. Auteur
11. Dépendances

Description

Package d'utilitaires pour Laravel offrant des proxies pour l'hydratation automatique d'objets Transformable (Value Objects, Records, DTOs) depuis des sources variées (tableaux, JSON, colonnes de base de données) ainsi que des directives CLI pour automatiser les workflows Git (push, génération de diff pour revue IA, et versionnement sémantique).

Installation

composer require andydefer/laravel-utils

Publication de la configuration (optionnelle)

Pour personnaliser les paramètres du package (dépôts Git, extensions, etc.) :

php artisan vendor:publish --tag=utils-config

Cette commande publiera le fichier config/utils.php dans votre application.

Note : La publication de la configuration n'est pas obligatoire. Si vous ne publiez pas le fichier, le package utilisera les valeurs par défaut.

Prérequis

• PHP 8.1 ou supérieur
• Laravel 10.x, 11.x, 12.x, 13.x, 14.x ou 15.x
• andydefer/domain-structures ^1.0
• Git (pour les directives CLI)
• VS Code (optionnel, pour l'ouverture automatique des fichiers)

Fonctionnalités

TransformableProxy

Proxy statique pour créer des objets Transformable depuis diverses sources :

use AndyDefer\LaravelUtils\Proxies\TransformableProxy;
use App\ValueObjects\SlugVO;

// Depuis une chaîne
$slug = TransformableProxy::make(SlugVO::class, 'mon-slug');

// Depuis un tableau
$user = TransformableProxy::make(UserRecord::class, [
    'name' => 'John Doe',
    'email' => 'john@example.com',
]);

// Depuis du JSON
$product = TransformableProxy::make(ProductRecord::class, '{"name":"Laptop","price":999}');

// Avec nullable
$coordinates = TransformableProxy::make(CoordinatesVO::class, null, nullable: true);

AttributeProxy

Proxy pour créer des attributs Eloquent qui hydratent automatiquement des objets Transformable depuis les colonnes de base de données.

Méthodes disponibles

Exemple d'utilisation

use AndyDefer\LaravelUtils\Proxies\AttributeProxy;
use App\ValueObjects\SlugVO;
use App\ValueObjects\CoordinatesVO;
use App\Records\SettingsRecord;

class User extends Model
{
    // Attribut nullable (slug)
    protected function slug(): Attribute
    {
        return AttributeProxy::nullable(SlugVO::class, column: 'slug');
    }

    // Attribut required (coordinates)
    protected function coordinates(): Attribute
    {
        return AttributeProxy::required(CoordinatesVO::class, column: 'coordinates');
    }

    // Attribut nullable avec colonne différente
    protected function settings(): Attribute
    {
        return AttributeProxy::nullable(SettingsRecord::class, column: 'metadata');
    }

    // Attribut avec transformation personnalisée
    protected function customSlug(): Attribute
    {
        return AttributeProxy::nullable(
            SlugVO::class,
            column: 'slug',
            get: function ($value, $attributes) {
                return strtolower(trim($value));
            },
            set: function ($value) {
                return ['slug' => strtolower(trim($value))];
            }
        );
    }
}

// Utilisation
$user = User::find(1);
echo $user->slug->getValue();           // 'john-doe'
echo $user->coordinates->getLatitude()->getValue(); // 48.8566
echo $user->settings->theme;            // 'dark'

Gestion automatique du Set

Lorsque vous spécifiez une colonne (column), AttributeProxy gère automatiquement la persistance :

class Product extends Model
{
    protected function slug(): Attribute
    {
        // Le set est automatiquement géré
        return AttributeProxy::nullable(SlugVO::class, column: 'slug');
    }
}

// La valeur est automatiquement normalisée avant stockage
$product->slug = 'Mon Article';  // Stocké comme 'mon-article'

GitPushDirective

Directive CLI pour pousser du code vers des dépôts Git distants configurés avec mode interactif et options avancées.

# Mode interactif (demande le message, les cibles et les dossiers)
./bin/afya ugp

# Push avec simulation (dry-run)
./bin/afya ugp [github] --dry-run <message="Fix bug">

# Push avec force-with-lease
./bin/afya ugp [github] --force-with-lease <message="Hotfix">

# Push sans tests
./bin/afya ugp [github, o2switch] --no-tests <message="Feature: Ajout API">

Paramètres :

GitDiffDirective

Directive CLI pour générer un diff Git formaté pour la revue de code par IA.

# Génération simple (interactif)
./bin/afya ugd

# Génération non-interactive avec chemins et extensions
./bin/afya ugd [src, tests] [.php, .js] --no-interactive

# Utilisation des recettes d'extensions
./bin/afya ugd --frontend                # Frontend uniquement
./bin/afya ugd --backend                 # Backend uniquement
./bin/afya ugd --recipes                 # Sélection interactive des recettes

# Simulation (dry-run)
./bin/afya ugd [src] --dry-run

# Génération avec résumé de travail
./bin/afya ugd [src] --with-summary

Paramètres :

Recettes d'extensions par défaut :

GitTagDirective

Directive CLI pour créer des tags de version Git avec versioning sémantique (SemVer).

# Création d'un tag patch (défaut)
./bin/afya ugt

# Création d'un tag minor
./bin/afya ugt minor

# Création d'un tag major
./bin/afya ugt major

# Re-publication du dernier tag
./bin/afya ugt --republish

# Tag avec message personnalisé et simulation
./bin/afya ugt patch --dry-run <message="Release v1.0.1">

# Tag sans push automatique
./bin/afya ugt minor --no-push

Paramètres :

Fonctionnalités :

• Versionnement sémantique automatique (SemVer)
• Message personnalisé pour les tags
• Simulation (dry-run) sans effectuer de modifications
• Re-publication forcée des tags existants
• Gestion des erreurs et des cas limites
• Interface utilisateur enrichie avec couleurs et icônes

Exemple de sortie :

🏷️ GIT TAG

📋 Configuration:

🏷️  Type        minor
📦 Last tag     v0.1.0
🆕 New tag      v0.2.0
💬 Message      Version 0.2.0 - Ajout de nouvelles fonctionnalités
📤 Push         ✅ Yes

📦 Creating tag: v0.2.0

✅ Tag created: v0.2.0

📤 Pushing tag to remote...

✅ Tag pushed: v0.2.0

✅ Tag operation completed successfully!

Configuration

Publication de la configuration

Pour personnaliser les paramètres du package, publiez d'abord le fichier de configuration :

php artisan vendor:publish --tag=utils-config

Cette commande crée le fichier config/utils.php dans votre application.

Configuration des dépôts Git

// config/utils.php
return [
    'repositories' => [
        'github' => 'git@github.com:andydefer/laravel-utils.git',
        'o2switch' => 'ssh://user@domain.com/home/user/git/repo.git',
    ],
];

Configuration des extensions

// config/utils.php
return [
    // Extensions par défaut pour le diff
    'default_extensions' => ['php', 'js', 'ts', 'css', 'html', 'json', 'yaml', 'md'],
    
    // Recettes d'extensions
    'extension_recipes' => [
        'frontend' => ['js', 'ts', 'tsx', 'jsx', 'vue', 'css', 'scss', 'sass', 'less', 'html', 'xml'],
        'backend' => ['php', 'py', 'rb', 'go', 'rs', 'java', 'c', 'cpp', 'h', 'hpp'],
        'fullstack' => ['php', 'js', 'ts', 'tsx', 'jsx', 'vue', 'css', 'scss', 'html'],
    ],
];

Configuration du déploiement

// config/utils.php
return [
    // ... autres configurations ...
    
    'deployment' => [
        'ssh_key' => env('DEPLOY_SSH_KEY', 'o2switch'),
        'remote_path' => env('DEPLOY_REMOTE_PATH', '~/sites/laravel-utils.com'),
        'git_branch' => env('DEPLOY_GIT_BRANCH', 'master'),
    ],
];

Documentation

• TransformableProxy - Référence Technique
• AttributeProxy - Référence Technique
• GitPushDirective - Référence Technique
• GitDiffDirective - Référence Technique
• GitTagDirective - Référence Technique

Tests

composer test

Contribuer

1. Forker le projet
2. Créer une branche (git checkout -b feature/ma-fonctionnalite)
3. Commiter les changements (git commit -m 'Ajout de ma fonctionnalité')
4. Pusher (git push origin feature/ma-fonctionnalite)
5. Ouvrir une Pull Request

Licence

MIT © Andy Defer

Auteur

• Andy Defer - GitHub

Dépendances

• andydefer/domain-structures - Interfaces et classes de base pour les objets transformables
• illuminate/database - Pour les attributs Eloquent
• symfony/process - Pour l'exécution des commandes Git
• andydefer/laravel-directive - Pour l'infrastructure des directives CLI
• andydefer/console-writer - Pour l'interface utilisateur en CLI