README

🌍 ImpactCO2 PHP Client

Une librairie PHP simple et robuste pour interagir avec l'API ImpactCO2 de l'ADEME. Calculez facilement l'empreinte carbone de vos activités (transport, chauffage, alimentation, etc.) directement depuis votre application PHP.

Retrouvez le projet ainsi que la documentation officielle de l'API ImpactCO2 sur impactco2.fr.

📋 Table des matières

• Prérequis
• Installation
• Démarrage rapide
• Utilisation détaillée
  • Configuration du client
  • Transport
  • Chauffage
  • Fruits et légumes
  • Thématiques
  • Détail d'une thématique
  • Alimentation
• Gestion des erreurs
• Tests
• Contribuer
• Licence

🔧 Prérequis

• PHP 8.3 ou supérieur
• Extension JSON activée
• Composer pour la gestion des dépendances

📦 Installation

Installez la librairie via Composer :

composer require jokod/impactco2-php

🚀 Démarrage rapide

Voici un exemple simple pour calculer les émissions CO₂e d'un trajet en voiture :

<?php

require 'vendor/autoload.php';

use Jokod\Impactco2Php\Client;
use Jokod\Impactco2Php\Endpoints\TransportEndpoint;
use Jokod\Impactco2Php\Enum\TransportsEnum;

// Créer le client
$client = new Client();

// Calculer les émissions pour un trajet de 100 km en voiture
$endpoint = new TransportEndpoint(100, [TransportsEnum::CAR]);
$result = $client->execute($endpoint);

// $result est une ApiResponse : getData() retourne les données (objets de la librairie), getWarning() un éventuel avertissement
foreach ($result->getData() as $transport) {
    echo $transport->getName() . ' : ' . $transport->getValue() . ' kg CO2e' . PHP_EOL;
}

📚 Utilisation détaillée

Configuration du client

Le client peut être configuré avec plusieurs options :

use Jokod\Impactco2Php\Client;
use Jokod\Impactco2Php\Enum\LanguagesEnum;

$client = new Client([
    'api_key'  => 'votre_cle_api',     // Optionnel - Clé API si nécessaire
    'language' => LanguagesEnum::FR     // Optionnel - Langue (FR, EN, ES)
]);

Options disponibles :

Format des réponses : execute() retourne toujours une ApiResponse avec :

• getData() : les données (objets de la librairie selon l'endpoint : Thematic[], Transport[], ECV, ou tableau brut pour Alimentation, Chauffage, Fruits et légumes)
• getWarning() : message d'avertissement éventuel renvoyé par l'API (null si absent)

1. Transport

Calculez les émissions de CO₂e pour différents moyens de transport sur une distance donnée.

Exemple basique

use Jokod\Impactco2Php\Endpoints\TransportEndpoint;
use Jokod\Impactco2Php\Enum\TransportsEnum;

// Comparer plusieurs transports pour 50 km
$endpoint = new TransportEndpoint(
    distance: 50,
    transports: [
        TransportsEnum::CAR,
        TransportsEnum::ELECTRIC_CAR,
        TransportsEnum::TGV,
        TransportsEnum::PLANE
    ]
);

$result = $client->execute($endpoint);
// $result->getData() : tableau d'objets Transport

Exemple avancé avec toutes les options

$endpoint = new TransportEndpoint(
    distance: 100,                          // Distance en km
    transports: [TransportsEnum::CAR],      // Liste des transports (optionnel)
    displayAll: false,                      // Afficher tous les transports pertinents
    occupencyRate: 2,                       // Taux d'occupation du véhicule (1 à 11)
    includeConstruction: 1,                 // Inclure les émissions de construction (0 ou 1)
    ignoreRadiativeForcing: 0,              // Ignorer le forçage radiatif avion (0 ou 1)
    numberOfPassenger: 2                    // Nombre de passagers pour le covoiturage (0 à 10)
);

Identifiants de transport : au-delà des constantes de TransportsEnum, l'endpoint accepte tout identifiant entier positif renvoyé par l'API, y compris les variantes détaillées (ex. 100 à 204 : voitures par taille/carburant, covoiturages détaillés, etc.). Vous pouvez donc passer directement ces IDs dans transports.

Transports disponibles

TransportsEnum::PLANE                    // Avion
TransportsEnum::TGV                      // TGV
TransportsEnum::INTERCITY                // Intercités
TransportsEnum::CAR                      // Voiture thermique
TransportsEnum::ELECTRIC_CAR             // Voiture électrique
TransportsEnum::BUS                      // Bus
TransportsEnum::THERMAL_BUS              // Bus thermique
TransportsEnum::ELECTRIC_BUS             // Bus électrique
TransportsEnum::GNV_BUS                  // Bus GNV
TransportsEnum::TRAMWAY                  // Tramway
TransportsEnum::METRO                    // Métro
TransportsEnum::RER_TRANSILIEN           // RER/Transilien
TransportsEnum::TER                      // TER
TransportsEnum::WALKING                  // Marche à pied
TransportsEnum::BIKE                    // Vélo
TransportsEnum::SCOOTER                  // Scooter thermique
TransportsEnum::ELECTRIC_SCOOTER         // Scooter électrique
TransportsEnum::MOTORCYCLE               // Moto
TransportsEnum::ELECTRIC_BIKE            // Vélo électrique
TransportsEnum::CARPOOLING_1             // Covoiturage 1 personne
TransportsEnum::CARPOOLING_2             // Covoiturage 2 personnes
TransportsEnum::CARPOOLING_3             // Covoiturage 3 personnes
TransportsEnum::CARPOOLING_4             // Covoiturage 4 personnes
TransportsEnum::ELECTRIC_CARPOOLING_1    // Covoiturage électrique 1 personne
TransportsEnum::ELECTRIC_CARPOOLING_2    // Covoiturage électrique 2 personnes
TransportsEnum::ELECTRIC_CARPOOLING_3    // Covoiturage électrique 3 personnes
TransportsEnum::ELECTRIC_CARPOOLING_4    // Covoiturage électrique 4 personnes
TransportsEnum::CAMPER_VAN               // Camping-car
TransportsEnum::LIGHT_MOTORCYCLE         // Moto thermique (<= 250 cm³)
TransportsEnum::ELECTRIC_MOPED           // Scooter électrique
TransportsEnum::CARGO_BIKE               // Vélo cargo triporteur
TransportsEnum::VAN                      // Van

2. Chauffage

Calculez les émissions de CO₂e pour le chauffage d'une surface donnée.

use Jokod\Impactco2Php\Endpoints\HeaterEndpoint;
use Jokod\Impactco2Php\Enum\HeaterEnum;

// Comparer différents types de chauffage pour 80 m²
$endpoint = new HeaterEndpoint(
    surface: 80,                            // Surface en m² (optionnel, défaut: 63)
    types: [
        HeaterEnum::GAS_HEATING,
        HeaterEnum::ELECTRIC_HEATING,
        HeaterEnum::HEAT_PUMP_HEATING
    ]
);

$result = $client->execute($endpoint);
// $result->getData() : tableau brut (structure renvoyée par l'API)

Types de chauffage disponibles

HeaterEnum::GAS_HEATING              // Chauffage au gaz
HeaterEnum::FUEL_OIL_HEATING         // Chauffage au fioul
HeaterEnum::ELECTRIC_HEATING         // Chauffage électrique
HeaterEnum::HEAT_PUMP_HEATING        // Pompe à chaleur
HeaterEnum::PELLET_STOVE_HEATING     // Poêle à granulés
HeaterEnum::WOOD_STOVE_HEATING       // Poêle à bois
HeaterEnum::DISTRICT_HEATING         // Réseau de chaleur
HeaterEnum::PELLET_BOILER_HEATING    // Chaudière à granulés

3. Fruits et légumes

Obtenez les émissions des fruits et légumes de saison.

use Jokod\Impactco2Php\Endpoints\FruitsVegetables;
use Jokod\Impactco2Php\Enum\FoodEnum;

// Fruits et légumes du mois de juin
$endpoint = new FruitsVegetables(
    month: 6,                               // Mois (1-12, optionnel, défaut: mois courant)
    categories: [
        FoodEnum::FRUITS,
        FoodEnum::VEGETABLES
    ]
);

$result = $client->execute($endpoint);
// $result->getData() : tableau brut (fruits et légumes du mois)

Catégories disponibles

FoodEnum::FRUITS                     // Fruits
FoodEnum::VEGETABLES                 // Légumes
FoodEnum::HERBS                      // Herbes aromatiques
FoodEnum::PASTA_RICE_CEREALS         // Pâtes, riz et céréales
FoodEnum::POTATOES_TUBERS            // Pommes de terre et tubercules
FoodEnum::NUTS_SEEDS                 // Fruits à coque et graines

4. Thématiques

Listez toutes les thématiques disponibles dans l'API. Les données sont retournées sous forme d'objets Thematic.

use Jokod\Impactco2Php\Endpoints\ThematicsEndpoint;

$endpoint = new ThematicsEndpoint();
$result = $client->execute($endpoint);

// Parcourir les thématiques (objets de la librairie)
foreach ($result->getData() as $thematic) {
    echo $thematic->getName() . PHP_EOL;
}
if ($result->getWarning() !== null) {
    echo 'Avertissement : ' . $result->getWarning();
}

5. Détail d'une thématique

Obtenez les émissions détaillées pour une thématique spécifique (ECV - Empreinte Carbone sur le cycle de Vie).

use Jokod\Impactco2Php\Endpoints\ThematicsEcvEndpoint;
use Jokod\Impactco2Php\Enum\ThematicEnum;

// Obtenir le détail de la thématique "meubles"
$endpoint = new ThematicsEcvEndpoint(
    id: ThematicEnum::FURNITURE,
    detail: 1                               // 0 = total uniquement, 1 = détail complet
);

$result = $client->execute($endpoint);
// $result->getData() : un objet ECV (détail de la thématique)

Thématiques disponibles

ThematicEnum::NUMERIC                    // Numérique
ThematicEnum::MEAL                       // Repas
ThematicEnum::DRINK                      // Boissons
ThematicEnum::TRANSPORT                  // Transport
ThematicEnum::CLOTHING                   // Habillement
ThematicEnum::APPLIANCE                  // Électroménager
ThematicEnum::FURNITURE                  // Meubles
ThematicEnum::HEATING                    // Chauffage
ThematicEnum::FRUITS_AND_VEGETABLES      // Fruits et légumes
ThematicEnum::DIGITAL_USAGE              // Usages numériques
ThematicEnum::CASE_STUDIES               // Études de cas

6. Alimentation

Obtenez les émissions par kg d'aliments, classées par catégorie.

use Jokod\Impactco2Php\Endpoints\AlimentationEndpoint;
use Jokod\Impactco2Php\Enum\AlimentationCategoryEnum;

// Par groupes d'aliments (viandes, poissons, produits laitiers...)
$endpoint = new AlimentationEndpoint(AlimentationCategoryEnum::GROUP);
$result = $client->execute($endpoint);

// Par rayons du magasin (boucherie, rayon frais...)
$endpoint = new AlimentationEndpoint(AlimentationCategoryEnum::RAYON);
$result = $client->execute($endpoint);

// Les 10 aliments les plus consommés en France
$endpoint = new AlimentationEndpoint(AlimentationCategoryEnum::POPULARITY);
$result = $client->execute($endpoint);
// $result->getData() : tableau brut selon la catégorie

Catégories disponibles

AlimentationCategoryEnum::GROUP          // Groupes d'aliments (viandes, poissons, etc.)
AlimentationCategoryEnum::RAYON          // Rayons du magasin
AlimentationCategoryEnum::POPULARITY     // Aliments les plus consommés

⚠️ Gestion des erreurs

La librairie utilise des exceptions pour gérer les erreurs :

use Jokod\Impactco2Php\Endpoints\TransportEndpoint;
use Jokod\Impactco2Php\Enum\TransportsEnum;
use Jokod\Impactco2Php\Exceptions\InvalidArgumentException;
use Jokod\Impactco2Php\Exceptions\Exception as Impactco2Exception;

// Validation des paramètres (ex. distance négative)
try {
    $endpoint = new TransportEndpoint(-100);
} catch (InvalidArgumentException $e) {
    echo "Paramètre invalide : " . $e->getMessage();
    return;
}

// Appel API avec un endpoint valide
$endpoint = new TransportEndpoint(100, [TransportsEnum::CAR]);
try {
    $result = $client->execute($endpoint);
} catch (Impactco2Exception $e) {
    echo "Erreur API : " . $e->getMessage();
}

Types d'exceptions :

• InvalidArgumentException : Paramètres invalides (distance négative, enum inconnu, etc.)
• Jokod\Impactco2Php\Exceptions\Exception : Erreurs de communication avec l'API (à ne pas confondre avec \Exception native PHP ; utiliser un alias comme Impactco2Exception pour plus de clarté)

🧪 Tests

Exécutez les tests unitaires avec PHPUnit :

# Installer les dépendances
composer install

# Lancer tous les tests
composer test
# ou
./vendor/bin/phpunit

# Avec couverture de code
composer test-coverage

🛠️ Contribuer

Les contributions sont les bienvenues ! Voici comment participer :

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

Normes de code

Le projet utilise :

• PHP-CS-Fixer pour le formatage du code
• GrumPHP pour les hooks git
• PHPUnit pour les tests

# Vérifier le formatage
make lint

# Corriger automatiquement
make fix

# Lancer les tests
make test

📄 Licence

Ce projet est sous licence MIT.

🔗 Liens utiles

• Documentation officielle ImpactCO2
• API ImpactCO2
• Package Packagist
• Repository GitHub

💬 Support

Si vous rencontrez un problème ou avez une question :

• Ouvrez une issue sur GitHub
• Consultez la documentation de l'API

Développé avec 💚 pour contribuer à la transition écologique