README

# Activity/Todolog

Un package Laravel pour capturer et logger automatiquement les actions utilisateur dans les applications Datastar.

## Vue d'ensemble

Activity/Todolog intercepte de manière transparente toutes les actions Datastar (création, suppression, modification, toggle) et les enregistre dans un fichier de log structuré. Ce package est conçu pour faciliter l'implémentation de systèmes d'historique, d'audit, et de fonctionnalités undo/redo dans les applications utilisant Datastar.

## Fonctionnalités

- **Capture automatique** de toutes les actions Datastar via middleware
- **Détection intelligente** du type d'action (create, delete, edit, toggle, etc.)
- **Sauvegarde des états** avant et après chaque action
- **Configuration flexible** pour personnaliser le comportement
- **Logging structuré** en format JSON
- **Zéro configuration** pour une utilisation de base
- **Compatible** avec tous les contrôleurs utilisant Datastar

## Prérequis

- PHP 8.1+
- Laravel 10.0+
- Package [activity/todolog](https://github.com/todolog)

## Installation

### 1. Installation via Composer

```bash
composer require activity/todolog
```

### 2. Publication des assets (optionnel)

```bash
# Publier la configuration et le fichier log
php artisan vendor:publish --tag=todolog

# Ou publier séparément
php artisan vendor:publish --tag=config --provider="Activity\Todolog\TodologServiceProvider"
php artisan vendor:publish --tag=logs --provider="Activity\Todolog\TodologServiceProvider"
```

Le package s'enregistre automatiquement grâce à l'auto-discovery de Laravel.

## Configuration

### Configuration par défaut

Le package fonctionne immédiatement sans configuration. Il utilise les paramètres par défaut suivants :

```php
// config/datastar-logger.php
return [
    'enabled' => env('DATASTAR_LOGGER_ENABLED', true),
    'log_path' => storage_path('logs/datastar_actions.log'),
    'target_model' => \App\Models\Task::class,
    'method_mappings' => [
        'store' => 'create',
        'destroy' => 'delete',
        'toggleComplete' => 'toggle',
        'update' => 'edit',
        'getForm' => 'edit-form',
        'fieldValidate' => 'field-validation',
    ],
    'undoable_actions' => ['create', 'delete', 'toggle', 'edit'],
    'max_log_size' => 10 * 1024 * 1024, // 10MB
    'keep_logs' => 5,
];
```

### Variables d'environnement

Ajoutez à votre fichier `.env` :

```env
# Activer/désactiver le logging
DATASTAR_LOGGER_ENABLED=true

# Désactiver en production pour les performances
# DATASTAR_LOGGER_ENABLED=false
```

## Utilisation

### Fonctionnement automatique

Une fois installé, le package capture automatiquement toutes les actions Datastar. Aucune modification de votre code existant n'est nécessaire.

### Actions supportées

Le package détecte automatiquement les types d'actions suivants :

| Méthode contrôleur | Type d'action | Description |
|-------------------|---------------|-------------|
| `store()` | `create` | Création d'une nouvelle entité |
| `destroy()` | `delete` | Suppression d'une entité |
| `update()` | `edit` | Modification d'une entité |
| `toggleComplete()` | `toggle` | Changement d'état booléen |
| `getForm()` | `edit-form` | Affichage formulaire d'édition |
| `fieldValidate()` | `field-validation` | Validation de champ |

### Format des logs

Chaque action est enregistrée au format JSON dans `storage/logs/datastar_actions.log` :

```json
{
  "timestamp": "2025-01-19T15:30:45.123456Z",
  "user_id": 123,
  "action": "delete",
  "target_id": 456,
  "before_state": {
    "id": 456,
    "title": "Acheter du pain",
    "is_completed": false,
    "created_at": "2025-01-19T10:00:00.000000Z"
  },
  "after_state": null,
  "can_undo": true
}
```

### Exemple de workflow

```html
<!-- Votre code Datastar existant -->
<button data-on-click="@action(['TaskController', 'destroy'], ['task' => $task->id])">
    Supprimer
</button>

<input data-on-change="@action(['TaskController', 'toggleComplete'], ['task' => $task->id])"
       type="checkbox">

<form data-on-submit="@action(['TaskController', 'store'])">
    <!-- Formulaire -->
</form>
```

Le package capture automatiquement ces actions et les enregistre.

## Configuration avancée

### Personnaliser le modèle cible

```php
// config/datastar-logger.php
'target_model' => \App\Models\MonModele::class,
```

### Ajouter des mappings d'actions

```php
// config/datastar-logger.php
'method_mappings' => [
    'store' => 'create',
    'destroy' => 'delete',
    'maMethodePersonnalisee' => 'action-custom',
    // ...
],
```

### Contrôler quelles actions sont loggées

```php
// config/datastar-logger.php
'undoable_actions' => ['create', 'delete', 'edit'],
```

### Rotation des logs

Le package gère automatiquement la rotation des fichiers de log :

```php
// config/datastar-logger.php
'max_log_size' => 10 * 1024 * 1024, // 10MB avant rotation
'keep_logs' => 5, // Garder 5 fichiers archivés
```

## Utilisation avec différents environnements

### Développement
```env
DATASTAR_LOGGER_ENABLED=true
APP_DEBUG=true
```

### Production
```env
DATASTAR_LOGGER_ENABLED=false  # Ou true selon les besoins d'audit
APP_DEBUG=false
```

### Tests
```env
# .env.testing
DATASTAR_LOGGER_ENABLED=false
```

## Lecture des logs

### Lecture programmatique

```php
// Lire les dernières actions
$logFile = storage_path('logs/datastar_actions.log');
$lines = file($logFile, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);

$actions = [];
foreach (array_slice($lines, -100) as $line) {
    $actions[] = json_decode($line, true);
}

// Actions les plus récentes en premier
$recentActions = array_reverse($actions);
```

### Analyse avec outils externes

Les logs étant en format JSON ligne par ligne, ils sont compatibles avec :

- **jq** pour le parsing en ligne de commande
- **Elasticsearch** pour l'indexation et recherche
- **Splunk** pour l'analyse de logs
- Outils de monitoring personnalisés

Exemple avec jq :
```bash
# Voir les 10 dernières actions
tail -10 storage/logs/datastar_actions.log | jq '.'

# Filtrer par utilisateur
cat storage/logs/datastar_actions.log | jq 'select(.user_id == 123)'

# Compter les actions par type
cat storage/logs/datastar_actions.log | jq -r '.action' | sort | uniq -c
```

## Performances

### Impact minimal

- **Overhead négligeable** grâce au middleware optimisé
- **Écriture asynchrone** dans le fichier de log
- **Désactivation facile** en production si nécessaire

### Recommandations de production

```env
# Option 1 : Désactiver complètement
DATASTAR_LOGGER_ENABLED=false

# Option 2 : Logger seulement les actions critiques
DATASTAR_LOGGER_ENABLED=true
# Puis personnaliser 'undoable_actions' dans la config
```

## Cas d'usage

### Système d'audit
Tracer toutes les modifications des utilisateurs pour la conformité.

### Historique d'actions
Afficher un historique des actions récentes dans l'interface utilisateur.

### Système undo/redo
Base pour implémenter des fonctionnalités d'annulation/refaire.

### Analyse comportementale
Comprendre comment les utilisateurs interagissent avec l'application.

### Debug et support
Investiguer les problèmes reportés par les utilisateurs.

## Développement

### Structure du package

```
src/
├── Http/Middleware/
│   └── TodoActionLogger.php      # Middleware principal
├── Services/
│   ├── ActionDetector.php        # Détection du type d'action
│   ├── StateCapture.php          # Capture des états avant/après
│   └── ActionLogger.php          # Écriture des logs
├── config/
│   └── datastar-logger.php       # Configuration par défaut
└── TodologServiceProvider.php    # Service Provider Laravel
```

### Extensibilité

Le package est conçu pour être facilement extensible. Vous pouvez :

- Ajouter de nouveaux types d'actions dans `method_mappings`
- Personnaliser la capture d'état via `StateCapture`
- Modifier le format de log via `ActionLogger`
- Ajouter des filtres personnalisés dans le middleware

## Contribution

Les contributions sont les bienvenues ! Merci de :

1. Fork le projet
2. Créer une branche feature (`git checkout -b feature/amelioration`)
3. Commit vos changements (`git commit -am 'Ajouter nouvelle fonctionnalité'`)
4. Push sur la branche (`git push origin feature/amelioration`)
5. Créer une Pull Request

## Support

Pour toute question ou problème :

1. Vérifiez d'abord la section de dépannage ci-dessous
2. Consultez les issues existantes sur GitHub
3. Créez une nouvelle issue avec un maximum de détails

## Dépannage

### Le package ne capture aucune action

**Vérifiez :**
1. `DATASTAR_LOGGER_ENABLED=true` dans `.env`
2. Les actions utilisent bien la syntaxe Datastar (`@action`)
3. Le middleware est bien enregistré : `php artisan route:list --verbose`

### Erreur "Model not found"

**Solution :**
Vérifiez que `target_model` dans la config pointe vers le bon modèle.

### Fichier de log non créé

**Solution :**
```bash
# Donner les permissions d'écriture
chmod 755 storage/logs
touch storage/logs/datastar_actions.log
chmod 644 storage/logs/datastar_actions.log
```

### Performance dégradée

**Solutions :**
1. Désactiver en production : `DATASTAR_LOGGER_ENABLED=false`
2. Réduire les actions loggées dans `undoable_actions`
3. Utiliser un système de queue pour l'écriture asynchrone

## Licence

MIT

## Auteur

Développé avec ♥ pour la communauté Laravel/Datastar.
activity / todolog

Maintainers

Details

README
