meinverband/api

REST API for mein verband application - Composer package for Contao and WordPress integration

v1.0.0 2025-12-18 11:12 UTC

Requires

• php: >=8.1
• guzzlehttp/guzzle: ^7.0
• psr/log: ^3.0

Requires (Dev)

• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^10.0
• squizlabs/php_codesniffer: ^3.7

MIT

• Your Name

• rest
• api
• composer
• wordpress
• contao
• meinverband

README

Eine PHP-Bibliothek für die Integration der MeinVerband API in Contao und WordPress Projekte.

Über die VerbandsCloud

Die VerbandsCloud wird von der syscape® GmbH im Auftrag des Deutschen Imkerbundes entwickelt und betrieben. Diese API-Bibliothek ermöglicht die Integration von Vereins- und Mitgliederdaten aus der VerbandsCloud in externe Systeme.

Beispiel-Konfiguration für Imkervereine:

• Landesverband: Hessische Imker
• API-URL: https://hessen.meinverband.online/api_server.php/api

Installation

Installieren Sie die Bibliothek über Composer:

composer require meinverband/api

Verwendung

Basis-Setup

<?php

use MeinVerband\Api\MeinVerbandApi;

// 1. Konfiguration über .env/.env.local (empfohlen)
$api = new MeinVerbandApi();

// 2. Manuelle Konfiguration
$api = new MeinVerbandApi(
    'https://hessen.meinverband.online/api_server.php/api', 
    'verein-xxx', 
    'your_password'
);

// Optional: Bearer Token für zusätzliche Authentifizierung (falls benötigt)
// $api->setAuthToken('your-bearer-token');

Konfiguration

Umgebungsvariablen (.env/.env.local)

Erstellen Sie eine .env.local Datei im Projektstamm:

# Beispiel für Hessische Imker Landesverband
MEINVERBAND_API_URL=https://hessen.meinverband.online/api_server.php/api
MEINVERBAND_API_USER=verein-xxx  # Ihr Vereins-User
MEINVERBAND_API_PASSWORD=your_api_password
MEINVERBAND_API_TIMEOUT=30
MEINVERBAND_API_VERIFY_SSL=true

Wichtig: Die MeinVerband API verwendet ein spezielles Format:

• Alle Requests werden als POST gesendet an /api_server.php/api
• JSON-Parameter im api_request Feld: {"api_action": "list,verein", "api_user": "verein-120", "api_pwd": "password"}
• Antworten enthalten CSV-Daten, die automatisch geparst werden

Die `.env.local` Datei sollte **nicht** ins Git-Repository committet werden (steht bereits in `.gitignore`).

## Verfügbare API-Endpunkte

Die MeinVerband API bietet folgende Endpunkte:

### Verein
- `list,verein` - Alle Vereine abrufen

### Mitglied
- `list,mitglied` - Alle Mitglieder abrufen
- `list,mitglied_funktionen` - Mitglied-Funktionen abrufen
- `list,mitglied_nur_funktionenaere` - Nur Funktionäre abrufen
- `list,mitglied_hsv_bsv_bsv_nach` - HSV/BSV Mitglieder abrufen
- `list,user` - User-Daten abrufen
- `list,user_nur_funktionenaere` - User-Funktionäre abrufen
- `list,user_hsv_bsv_bsv_nach` - User HSV/BSV abrufen

### API
- `info,api` - API-Informationen und Statistiken abrufen

Vereine verwalten

// Alle Vereine abrufen (api_action: list,verein)
$response = $api->verein()->getAll();

if ($response['api_status'] === 'success') {
    $vereine = $response['parsed_data'];
    
    foreach ($vereine as $verein) {
        echo $verein['verein_name'] . "\n";
        echo 'Mitglieder: ' . $verein['mitglied_count'] . "\n";
        echo 'Aktive: ' . $verein['mitglied_active_count'] . "\n\n";
    }
}

Mitglieder verwalten

// Alle Mitglieder abrufen
$response = $api->mitglied()->getAll();

if ($response['api_status'] === 'success') {
    $mitglieder = $response['parsed_data']; // Geparste CSV-Daten
    
    foreach ($mitglieder as $mitglied) {
        echo $mitglied['firstname'] . ' ' . $mitglied['lastname'] . "\n";
        echo 'Email: ' . $mitglied['email'] . "\n";
        echo 'Völker: ' . $mitglied['voelker'] . "\n\n";
    }
}

// Funktionäre abrufen (api_action: list,mitglied_nur_funktionenaere)
$funktionaere = $api->mitglied()->getNurFunktionaere();

// HSV/BSV Mitglieder (api_action: list,mitglied_hsv_bsv_bsv_nach)  
$hsvBsv = $api->mitglied()->getHsvBsvBsvNach();

// User-Daten abrufen (api_action: list,user)
$users = $api->mitglied()->getUsers();

// User-Funktionäre (api_action: list,user_nur_funktionenaere)
$userFunktionaere = $api->mitglied()->getUserNurFunktionaere();

// Rohdaten zugreifen
$csvData = $response['csv_data']; // Original CSV-String
$count = $response['csv_count'];   // Anzahl der Datensätze

API-Informationen abrufen

// API-Informationen abrufen (api_action: info,api)
$response = $api->api()->getInfo();

if ($response['api_status'] === 'success') {
    $info = $response['parsed_data'][0];
    echo 'API Modus: ' . $info['api_modus'] . "\n";
    echo 'Remote IP: ' . $info['remote_addr'] . "\n";
    
    // API-Aufruf-Statistiken
    $apiCounts = json_decode($response['api_count_json'], true);
    foreach ($apiCounts as $action => $timestamps) {
        echo "Action {$action}: " . count($timestamps) . " Aufrufe\n";
    }
}

Integration in Contao

<?php

// In einem Contao-Modul oder -Hook
use MeinVerband\Api\MeinVerbandApi;

class MeinVerbandModule extends \Contao\Module
{
    protected function compile()
    {
        // API-Client mit automatischer .env Konfiguration
        $api = new MeinVerbandApi();
        
        try {
            $vereinResponse = $api->verein()->getAll();
            $mitgliederResponse = $api->mitglied()->getAll();
            
            if ($vereinResponse['api_status'] === 'success') {
                $this->Template->vereine = $vereinResponse['parsed_data'];
            }
            
            if ($mitgliederResponse['api_status'] === 'success') {
                $this->Template->mitglieder = $mitgliederResponse['parsed_data'];
            }
        } catch (\Exception $e) {
            \System::log('MeinVerband API Fehler: ' . $e->getMessage(), __METHOD__, TL_ERROR);
        }
    }
}

Integration in WordPress

<?php

// In einem WordPress-Plugin oder Theme
add_action('init', function() {
    // API-Client mit automatischer .env Konfiguration  
    $api = new \MeinVerband\Api\MeinVerbandApi();
    
    try {
        // Vereine abrufen
        $vereinResponse = $api->verein()->getAll();
        
        // Mitglieder abrufen
        $mitgliederResponse = $api->mitglied()->getAll();
        
        // Funktionäre abrufen
        $funktionaereResponse = $api->mitglied()->getNurFunktionaere();
        
        if ($vereinResponse['api_status'] === 'success') {
            $vereine = $vereinResponse['parsed_data'];
            // Verarbeitung der Vereinsdaten...
        }
        
        if ($mitgliederResponse['api_status'] === 'success') {
            $mitglieder = $mitgliederResponse['parsed_data'];
            // Verarbeitung der Mitgliederdaten...
        }
    } catch (\Exception $e) {
        error_log('MeinVerband API Fehler: ' . $e->getMessage());
    }
});

Konfiguration

Sie können den API-Client mit verschiedenen Optionen konfigurieren:

$api = new MeinVerbandApi(
    'https://hessen.meinverband.online/api_server.php/api',
    'verein-120',
    'your_password',
    [
        'timeout' => 60,
        'verify' => false, // SSL-Verifizierung deaktivieren (nicht empfohlen)
    ]
);

Entwicklung

Abhängigkeiten installieren

composer install

Tests ausführen

composer test

Code-Style prüfen

composer phpcs

Statische Analyse

composer phpstan

Vollständiges Beispiel

<?php

require 'vendor/autoload.php';

use MeinVerband\Api\MeinVerbandApi;

// API-Client initialisieren
$api = new MeinVerbandApi();

try {
    // Vereinsdaten abrufen
    $vereinResponse = $api->verein()->getAll();
    if ($vereinResponse['api_status'] === 'success') {
        $vereine = $vereinResponse['parsed_data'];
        echo "Gefundene Vereine: " . count($vereine) . "\n";
    }
    
    // Alle Mitglieder abrufen  
    $mitgliederResponse = $api->mitglied()->getAll();
    if ($mitgliederResponse['api_status'] === 'success') {
        $mitglieder = $mitgliederResponse['parsed_data'];
        echo "Gefundene Mitglieder: " . count($mitglieder) . "\n";
    }
    
    // Nur Funktionäre abrufen
    $funktionaereResponse = $api->mitglied()->getNurFunktionaere();
    if ($funktionaereResponse['api_status'] === 'success') {
        $funktionaere = $funktionaereResponse['parsed_data'];
        echo "Gefundene Funktionäre: " . count($funktionaere) . "\n";
    }
    
    // API-Informationen abrufen
    $apiResponse = $api->api()->getInfo();
    if ($apiResponse['api_status'] === 'success') {
        $info = $apiResponse['parsed_data'][0];
        echo "API Modus: " . $info['api_modus'] . "\n";
    }
    
} catch (Exception $e) {
    echo "Fehler: " . $e->getMessage() . "\n";
}

Über das Projekt

Diese Bibliothek ermöglicht die Integration mit der VerbandsCloud des Deutschen Imkerbundes. Die VerbandsCloud wird von der syscape® GmbH bereitgestellt und verwaltet Vereins- und Mitgliederdaten für Imkervereine deutschlandweit.

Technische Details

• API-Provider: syscape® GmbH
• Auftraggeber: Deutscher Imkerbund
• User-Format: verein-xxx (entsprechend Ihrem Vereins-Code)
• Domain-Struktur: [landesverband].meinverband.online

Lizenz

MIT License