memcache_add_server — Funktion · PHP-Referenz

Signatur

memcache_add_server(Memcache $memcache, string $host, int $port = 11211, bool $persistent = false, int $weight = 0, int $timeout = 1, int $retry_interval = 15, bool $status = true, callable $failure_callback = null, int $timeoutms = 0): bool

Beschreibung

memcache_add_server() registriert einen Memcached-Server im Verbindungspool des angegebenen Memcache-Objekts. Im Gegensatz zu memcache_connect() wird die tatsächliche TCP-Verbindung erst dann aufgebaut, wenn der Server zum ersten Mal tatsächlich benötigt wird (Lazy-Connect). Das ermöglicht es, mehrere Server zu einem Pool zusammenzufassen und so die Last zu verteilen.

Mit dem Parameter $weight lässt sich steuern, wie viele Schlüssel anteilig auf diesen Server entfallen. Ein Server mit höherem Gewicht erhält proportional mehr Cache-Einträge. Dies ist nützlich, wenn Server unterschiedlich viel RAM besitzen.

Schlägt die Verbindung zu einem Server fehl, wird er für $retry_interval Sekunden als nicht verfügbar markiert. Über den Parameter $failure_callback kann eine eigene Funktion registriert werden, die bei einem Verbindungsfehler aufgerufen wird. Der Parameter $status gibt an, ob der Server als online betrachtet werden soll – wird er auf false gesetzt, nimmt der Server nicht an der Schlüsselverteilung teil, bleibt aber im Pool registriert.

Diese prozedurale Funktion ist das Äquivalent zur objektorientierten Methode Memcache::addServer(). Die PECL-Erweiterung memcache (nicht zu verwechseln mit memcached) ist für PHP 5–8 verfügbar, wird aber nicht mehr aktiv weiterentwickelt. Für neue Projekte empfiehlt sich die neuere Memcached-Erweiterung.

Parameter

Name	Typ	Default	Beschreibung
$memcache Pflicht	Memcache		Das `Memcache`-Objekt, dem der Server hinzugefügt werden soll. Wird mit `memcache_connect()` oder `new Memcache()` erstellt.
$host Pflicht	string		Hostname oder IP-Adresse des Memcached-Servers. Es kann auch ein Unix-Socket-Pfad angegeben werden, z. B. `/var/run/memcached/memcached.sock`.
$port	int	11211	TCP-Port des Memcached-Servers. Bei Unix-Sockets muss dieser Wert auf `0` gesetzt werden.
$persistent	bool	false	Gibt an, ob eine persistente Verbindung verwendet werden soll, die zwischen Anfragen erhalten bleibt.
$weight	int	0	Relatives Gewicht dieses Servers im Pool. Ein höherer Wert bedeutet, dass mehr Cache-Schlüssel auf diesen Server verteilt werden.
$timeout	int	1	Verbindungs-Timeout in Sekunden. Wird dieser Wert zu groß gewählt, kann es zu langen Wartezeiten bei ausgefallenen Servern kommen.
$retry_interval	int	15	Zeit in Sekunden, nach der ein als ausgefallen markierter Server erneut versucht wird zu verbinden. Der Wert `-1` deaktiviert automatische Wiederverbindungsversuche.
$status	bool	true	Gibt an, ob der Server als online gilt und an der Schlüsselverteilung teilnimmt. `false` kann genutzt werden, um einen Server temporär aus dem Pool zu nehmen, ohne ihn zu entfernen.
$failure_callback	callable		Eine Callback-Funktion, die bei einem Verbindungsfehler aufgerufen wird. Sie erhält als Parameter `$host` (string) und `$port` (int) des fehlgeschlagenen Servers.
$timeoutms	int	0	Verbindungs-Timeout in Millisekunden. Falls gesetzt, überschreibt dieser Wert den Parameter `$timeout`.

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück, false bei einem Fehler. Da die Verbindung lazy aufgebaut wird, bedeutet true nur, dass der Server erfolgreich registriert wurde, nicht dass er erreichbar ist.

Beispiele

Mehrere Memcached-Server zum Pool hinzufügen

<?php
$memcache = new Memcache();

// Ersten Server mit höherem Gewicht hinzufügen (mehr RAM)
memcache_add_server($memcache, '192.168.1.10', 11211, false, 3);

// Zweiten Server mit niedrigerem Gewicht
memcache_add_server($memcache, '192.168.1.11', 11211, false, 1);

// Daten schreiben und lesen
$memcache->set('begruessung', 'Hallo Welt', 0, 60);
$wert = $memcache->get('begruessung');

echo $wert; // Hallo Welt

Hallo Welt

Server mit Fehler-Callback und Unix-Socket

<?php
function memcache_fehler(string $host, int $port): void {
    error_log("Memcache-Server nicht erreichbar: {$host}:{$port}");
}

$memcache = new Memcache();

// TCP-Server
memcache_add_server(
    $memcache,
    'cache1.example.com',
    11211,
    true,   // persistente Verbindung
    2,      // Gewicht
    1,      // Timeout in Sekunden
    15,     // Retry-Intervall
    true,   // Server ist online
    'memcache_fehler'
);

// Unix-Socket (Port muss 0 sein)
memcache_add_server(
    $memcache,
    '/var/run/memcached/memcached.sock',
    0,
    false,
    1
);

if ($memcache->set('nutzer_42', ['name' => 'Max', 'rolle' => 'admin'], 0, 300)) {
    echo 'Gespeichert.';
}

Gespeichert.

// Wichtig · Fallstricke

Veraltete Erweiterung: Die memcache-PECL-Erweiterung wird nicht mehr aktiv gepflegt. Für neue Projekte sollte die Memcached-Erweiterung (mit d am Ende) verwendet werden, die den binären Memcached-Protokoll unterstützt und mehr Features bietet.

Timeout-Einstellungen: Ein zu großer $timeout-Wert kann die Antwortzeiten der Anwendung erheblich beeinträchtigen, wenn ein Server nicht verfügbar ist. Typische Werte liegen zwischen 1 und 3 Sekunden.

Konsistentes Hashing: Die Schlüsselverteilung auf mehrere Server basiert auf einem einfachen Hashing-Verfahren. Fällt ein Server aus, werden seine Schlüssel auf andere Server umverteilt, was zu einem erhöhten Cache-Miss-Anteil führt. Die neuere Memcached-Erweiterung unterstützt konsistentes Hashing, das dieses Problem minimiert.

Siehe auch

memcache_connect memcache_pconnect Memcache::addServer memcache_get memcache_set memcache_close