Importer et exporter des modèles au format CSV

Introduction

Le module bowphp/csv permet d'exporter ou d'importer facilement des modèles au format CSV. Il s'appuie sur league/csv pour un traitement robuste des fichiers CSV.

Installation

composer require bowphp/csv

Configuration du modèle

Ajoutez le trait Bow\Csv\Csv à vos modèles :

app/Models/User.php

namespace App\Models;

use Bow\Csv\Csv;
use Bow\Database\Barry\Model;

class User extends Model
{
  use Csv;

  protected ?string $table = "users";
}

Exporter en CSV

Export basique

use App\Models\User;

// Exporter tous les utilisateurs en chaîne CSV
$user = new User();
$csv = $user->toCsv();

// Résultat:
// id,name,email,created_at,updated_at
// 1,John Doe,john@example.com,2025-01-01,2025-01-01
// 2,Jane Doe,jane@example.com,2025-01-02,2025-01-02

Export avec colonnes spécifiques

$user = new User();
$user->setCsvHeaders(["id", "name", "email"]);

$csv = $user->toCsv();

// Résultat:
// id,name,email
// 1,John Doe,john@example.com
// 2,Jane Doe,jane@example.com

Export et téléchargement

$user = new User();
$user->setCsvHeaders(["id", "name", "email"]);

// Télécharge le fichier CSV directement
$user->toCsv("users-export.csv");

Export dans un contrôleur

app/Controllers/ExportController.php

namespace App\Controllers;

use App\Models\User;

class ExportController
{
  public function exportUsers()
  {
    $user = new User();
    $user->setCsvHeaders(["id", "name", "email", "created_at"]);

    // Force le téléchargement
    return $user->toCsv("users-" . date("Y-m-d") . ".csv");
  }

  public function exportAllColumns()
  {
    // Exporter toutes les colonnes (headers par défaut: ["*"])
    $user = new User();
    return $user->toCsv("users-full.csv");
  }
}

Importer depuis un CSV

Import via le service

use Bow\Csv\CsvService;
use App\Models\User;

$service = new CsvService();
$service->import(
  new User(),
  "/chemin/vers/users.csv",
  ["name", "email", "password"]
);

Format du fichier CSV

Le fichier CSV doit contenir une ligne d'en-tête correspondant aux noms des colonnes. Les headers passés en paramètre doivent correspondre aux colonnes du fichier CSV.

Import via le modèle

use App\Models\User;

$user = new User();
$user->setCsvHeaders(["name", "email", "password"]);

// Importe chaque ligne du CSV comme nouvel enregistrement
$user->importCsv("/chemin/vers/users.csv");

Import dans un contrôleur

app/Controllers/ImportController.php

namespace App\Controllers;

use App\Models\User;
use Bow\Http\Request;

class ImportController
{
  public function importUsers(Request $request)
  {
    // Récupérer le fichier uploadé
    $file = $request->file("csv_file");

    if (!$file || !$file->isUploaded()) {
      return response_json(["error" => "Aucun fichier uploadé"], 400);
    }

    // Valider l'extension
    if ($file->getExtension() !== "csv") {
      return response_json(["error" => "Le fichier doit être au format CSV"], 400);
    }

    // Sauvegarder temporairement
    $tempPath = "/tmp/" . str_uuid() . ".csv";
    $file->moveTo($tempPath);

    try {
      $user = new User();
      $user->setCsvHeaders(["name", "email", "password"]);
      $user->importCsv($tempPath);

      // Supprimer le fichier temporaire
      unlink($tempPath);

      return response_json(["message" => "Import réussi"]);
    } catch (\Exception $e) {
      return response_json(["error" => $e->getMessage()], 500);
    }
  }
}

Helpers globaux

Deux fonctions globales sont disponibles :

// Exporter un modèle en CSV (retourne une chaîne)
$csv = app_export_model_to_csv(new User(), null, ["id", "name", "email"]);

// Exporter vers un fichier (force le téléchargement)
app_export_model_to_csv(new User(), "users.csv", ["id", "name", "email"]);

// Exporter toutes les colonnes
$csv = app_export_model_to_csv(new User(), null, ["*"]);

// Importer un CSV dans un modèle
app_import_csv_to_model(
  new User(),
  "/chemin/vers/users.csv",
  ["name", "email", "password"]
);

Référence API

Trait Csv

Méthode	Description
setCsvHeaders(array $headers)	Définit les colonnes à exporter/importer
toCsv(?string $filename = null)	Exporte en CSV (chaîne ou téléchargement)
importCsv(string $filename)	Importe depuis un fichier CSV

CsvService

Méthode	Description
export(Model $model, ?string $filename, array $headers = ['*'])	Exporte un modèle en CSV
import(Model $model, string $filename, array $headers)	Importe un CSV dans un modèle

Bonnes pratiques

Recommandations

• Définissez les headers : Utilisez setCsvHeaders() pour contrôler précisément les colonnes exportées.
• Validez les fichiers : Vérifiez l'extension et le contenu avant d'importer.
• Nettoyez les fichiers temporaires : Supprimez les fichiers uploadés après traitement.
• Gérez les erreurs : Entourez les imports d'un try/catch pour gérer les échecs.

Attention

• Le modèle doit utiliser le trait Bow\Csv\Csv pour les méthodes toCsv() et importCsv().
• Les headers du fichier CSV doivent correspondre aux noms de colonnes attendus.
• L'import crée de nouveaux enregistrements pour chaque ligne du CSV.

Il manque quelque chose ?

Si vous rencontrez des problèmes avec la documentation ou si vous avez des suggestions pour améliorer la documentation ou le projet en général, veuillez déposer une issue pour nous, ou envoyer un tweet mentionnant le compte Twitter @bowframework ou sur directement sur le github.