1. Usage rapide #

2. Options et paramètres courants #

Les options ci‑dessous sont les paramètres habituellement proposés pour une commande de génération de statistiques. Adaptez selon la signature réelle.

• –date-from=YYYY-MM-DD
  • Première date incluse (début de la période).
  • Si omis : comportement par défaut souvent = premier jour du mois précédent ou calcul sur la dernière période disponible.
• –date-to=YYYY-MM-DD
  • Dernière date incluse (fin de la période).
  • Si omis : souvent = dernier jour du mois précédent ou aujourd’hui selon implémentation.
• –naf=CODE
  • Filtre sur un ou plusieurs codes NAF (séparés par des virgules).
  • Exemple : --naf=47.11A,62.01Z
• –output=(csv|json|db)
  • Format de sortie souhaité.
  • csv : fichier CSV écrit dans storage/exports ou répertoire configuré.
  • json : fichier JSON.
  • db : persiste les résultats en base (table de statistiques).
• –chunk=NUMBER
  • Taille des batchs pour traitement par lots (utile pour limiter la mémoire).
• –limit=NUMBER
  • Nombre maximal d’enregistrements à traiter (utile en phase de test).
• –dry-run
  • Simule l’exécution sans écrire de fichiers ni modifier la base.
• –force
  • Forcer l’écrasement des fichiers existants ou forcer l’insertion en base.
• -v / -vv / -vvv
  • Niveau de verbosité pour le débogage.
• –help
  • Affiche l’aide détaillée.

3. Exemples d’exécution #

• Exécution quotidienne pour la journée précédente (mode production) : php artisan stats:naf-codes --date-from=2026-05-17 --date-to=2026-05-17 --output=csv

• Exécution mensuelle (tous les 1er du mois pour le mois précédent) : php artisan stats:naf-codes --date-from=2026-04-01 --date-to=2026-04-30 --output=db --force

• Simulation (dry run) : php artisan stats:naf-codes --date-from=2026-05-01 --date-to=2026-05-31 --dry-run -v

• Filtrer sur plusieurs codes NAF et exporter en JSON : php artisan stats:naf-codes --date-from=2026-01-01 --date-to=2026-03-31 --naf=47.11A,62.01Z --output=json

4. Scénarios d’exécution en batch / cron #

Ci‑dessous des exemples pratiques et robustes pour mettre la commande en production.

1. Exécution quotidienne (cron)

• But : calculer les stats pour la journée précédente chaque matin à 02:00.
• Exemple de crontab : 0 2 * * * cd /chemin/vers/app && /usr/bin/php artisan stats:naf-codes --date-from=$(date -d ‘yesterday’ +%F) --date-to=$(date -d ‘yesterday’ +%F) >> /var/log/stats-naf-codes.log 2>&1

2. Exécution mensuelle via le scheduler Laravel (recommandé)

• Ajouter dans app/Console/Kernel.php : $schedule->command(‘stats:naf-codes --date-from={start} --date-to={end}’)->monthlyOn(1, ‘03:00’)->withoutOverlapping();
• Remarques :
  • Utiliser withoutOverlapping() pour éviter double exécution si la tâche précédente n’est pas terminée.
  • Remplacer {start}/{end} par une logique calculée (ou exécuter la commande sans dates et laisser la commande calculer la période par défaut).

3. Planification système avec sortie vers fichiers horodatés

• Exemple (cron) pour sauvegarder chaque exécution avec date : 30 3 * * * cd /chemin/vers/app && /usr/bin/php artisan stats:naf-codes --date-from=$(date -d ‘yesterday’ +%F) --date-to=$(date -d ‘yesterday’ +%F) --output=csv && mv storage/exports/stats-naf-codes.csv storage/exports/stats-naf-codes-$(date +%F).csv

5. Emplacement des fichiers et persistance #

• Exports fichiers : typiquement dans storage/exports ou un dossier configurable.
• Logs : storage/logs/laravel.log ou un channel dédié (ex. stats) si configuré.
• Persistance en base : si la commande supporte --output=db, les résultats sont insérés dans la table de statistiques (ex. stats_naf_codes) — vérifier la migration/table dans le projet.

6. Bonnes pratiques d’exploitation #

• Exécutions lourdes : lancer sur une machine avec suffisamment de ressources ou découper le traitement en chunks (–chunk) pour limiter la mémoire.
• Monitoring : rediriger la sortie vers un fichier de log et configurer une rotation logrotate.
• Verrouillage : utiliser withoutOverlapping() ou mécanismes de lock pour éviter des exécutions concurrentes.
• Retours/Alertes : en cas d’échec, envoyer une alerte (mail/Slack) en utilisant la sortie d’erreur ou un service de monitoring.
• Tests en pré-production : toujours lancer avec --dry-run et --limit pour valider la logique avant production.

7. Gestion des erreurs et codes de sortie #

• Code de sortie 0 : succès.
• Code non nul : erreur. Vérifier storage/logs/laravel.log pour la stack trace.
• En cas d’erreurs fréquentes :
  • Contrôler la consommation mémoire et le temps d’exécution (max_execution_time / memory_limit).
  • Vérifier les verrous DB et la charge sur la base.
  • Relancer manuellement en mode verbose pour diagnostiquer : php artisan stats:naf-codes --date-from=… -vvv

8. Intégration continue / déploiement #

• Déployer la commande avec le code (app/Console/Commands/StatsNafCodes.php).
• Mettre à jour le scheduler (Kernel.php) si vous automatisez via Laravel scheduler.
• Documenter les variables d’environnement nécessaires (DB, chemins, credentials d’export si S3, etc.) et les droits d’écriture sur storage/exports.

9. Exemple de fichier de log attendu #

• Sortie standard (résumé) : [2026-05-18 03:00:01] INFO: Début génération stats naf codes (2026-05-17 → 2026-05-17) [2026-05-18 03:02:42] INFO: Processed 12 345 establishments in 161s [2026-05-18 03:02:42] INFO: Results written to storage/exports/stats-naf-codes-2026-05-17.csv [2026-05-18 03:02:42] INFO: End

• En cas d’erreur : [2026-05-18 03:01:12] ERROR: PDOException: SQLSTATE[…] (détails) Vérifier les logs complets pour le stack trace.

10. FAQ rapide #