Erweiterte PHP 5-Dateiverwaltung

Diese API wird für Laufzeiten der ersten Generation unterstützt und kann beim Upgrade auf entsprechende Laufzeiten der zweiten Generation verwendet werden. Wenn Sie die App Engine PHP 7/8-Laufzeit aktualisieren, lesen Sie die Migrationsanleitung, um mehr über Ihre Migrationsoptionen für gebündelte Legacy-Dienste zu erfahren.

Berechtigungen, Caching und Metadatenoptionen

Der App Engine-Stream-Wrapper für Cloud Storage bietet die folgenden Optionen zum Konfigurieren Ihres Streams:

Option	Mögliche Werte	Beschreibung
acl	Einer der folgenden Werte: private public-read public-read-write authenticated-read bucket-owner-read bucket-owner-full-control project-private	Eine Beschreibung der Wirkung dieser Einstellungen in Cloud Storage finden Sie unter Vordefinierte ACLs. Wenn Sie acl nicht festlegen, legt Cloud Storage diesen Parameter auf null fest und verwendet die Standardobjekt-ACL, die dem Bucket zugeordnet ist, der die Datei enthält.
Content-Type	Jeder gültige MIME-Typ	Wenn Sie beim Hochladen eines Objekts keinen Inhaltstyp angeben, verwendet das Google Cloud Storage-System beim Bereitstellen des Objekts standardmäßig binary/octet-stream.
Content-Disposition	Jeder gültige Inhaltsanordnungswert	Ein Header, den Sie für ein Objekt festlegen können. Er gibt Präsentationsinformationen darüber an, wie die Objektdaten übertragen werden sollen.
Content-Encoding	Jeder gültige Komprimierungsalgorithmus	Der Komprimierungsalgorithmus für das Objekt, z. B. gzip. Beachten Sie, dass Google Cloud Storage Objekte basierend auf diesem Header nicht automatisch komprimiert oder dekomprimiert.
Content-Language	Jeder gültige Sprachcode nach ISO 639-1	Der Sprachcode des Inhalts nach ISO 639-1 (eine vollständige Liste finden Sie in Codes für die Darstellung von Namen von Sprachen).
enable_cache	"true" oder "false" (standardmäßig "true")	Aus Cloud Storage gelesene Dateien werden zur Leistungsverbesserung im Arbeitsspeicher gespeichert (siehe memcache). Caching kann mithilfe der Anweisung enable_cache im Streamkontext deaktiviert werden.
enable_optimistic_cache	"true" oder "false" (standardmäßig "false")	Sie können optimistisches Caching aktivieren, um das Dateiobjekt aus dem Cache zu lesen, ohne zu überprüfen, ob das zugrunde liegende Objekt seit dem letzten Cache-Speichervorgang in Cloud Storage geändert wurde. Optimistisches Caching ist ideal für Szenarien mit einem Schreib- und vielen Lesezugriffen.
metadata	Ein assoziatives Array, z. B.	['foo' => 'far', 'bar' => 'boo'] Siehe Benutzerdefinierte Metadaten lesen und schreiben.
read_cache_expiry_seconds	Die Dauer in Sekunden, die ein Objekt im Cache gültig bleibt	Sie können die Gültigkeitsdauer eines im Cache gespeicherten Objekts mit read_cache_expiry_seconds directive ändern. Dies gibt die Zeit an, nach der das Objekt beim nächsten Leseversuch erneut im Cache gespeichert wird. Standardmäßig ist dies auf 1 Stunde (3600) eingestellt.
writable_cache_expiry_seconds	Die Dauer in Sekunden, für die der schreibbare Status eines Buckets im Cache gespeichert wird	Der Cloud Storage-Stream-Wrapper speichert den schreibbaren Status von Buckets zur Leistungsverbesserung im Cache. Dies bedeutet, dass die schreibbaren Bits, die von verschiedenen Funktionen im Zusammenhang mit stat() zurückgegeben werden, vorübergehend nicht synchron sind, wenn sich die ACL des Buckets ändert. Standardmäßig ist dies auf 10 Minuten (600) eingestellt.

Das folgende Snippet zeigt die Verwendung von Streamoptionen:

$options = ['gs' => ['Content-Type' => 'text/plain']];
$context = stream_context_create($options);
file_put_contents("gs://${my_bucket}/hello_options.txt", $newFileContent, 0, $context);

In diesem Snippet ist $options eine Reihe von Argumenten, die der Stream beim Schreiben neuer Objekte verwendet. Diese können mit stream_context_set_default als Standardoptionen festgelegt werden.

Unterstützung von PHP 5-Dateisystemfunktionen in Cloud Storage

Der App Engine-Stream-Wrapper für Cloud Storage unterstützt viele native PHP-Dateisystemfunktionen. Einige Funktionen werden nicht unterstützt, bei anderen wurde die Unterstützung geändert. In der folgenden Tabelle sind alle diese nativen Funktionen aufgeführt und es wird angegeben, ob die Funktion unterstützt wird oder nicht. Wenn eine Funktion mit Änderungen oder Einschränkungen unterstützt wird, werden diese angegeben.

Dateisystemfunktion	Unterstützt?	Details
basename – gibt die nachgestellte Namenskomponente des Pfades zurück.	Unterstützt.
chgrp – ändert die Dateigruppe.	Nicht unterstützt.	Gibt immer false zurück.
chmod – ändert den Dateimodus.	Nicht unterstützt.	Gibt immer false zurück.
chown – ändert den Dateibesitzer.	Nicht unterstützt.	Gibt immer false zurück.
clearstatcache – löscht den Dateistatus-Cache.	Unterstützt.
copy – kopiert die Datei.	Unterstützt.
dirname – gibt den Pfad des übergeordneten Verzeichnisses zurück.	Unterstützt.	Wird unterstützt, enthält jedoch das gs://-Präfix.
disk_free_space – gibt den verfügbaren Speicherplatz im Dateisystem oder auf der Festplattenpartition zurück.	Nicht unterstützt.	Dies ist deaktiviert.
disk_total_space – gibt die Gesamtgröße eines Dateisystems oder einer Festplattenpartition zurück.	Nicht unterstützt.	Dies ist deaktiviert.
diskfreespace – Alias von disk_free_space.
fclose – schließt einen geöffneten Dateizeiger.	Unterstützt.
feof – prüft einen Dateizeiger auf ein Dateiende.	Unterstützt.
fflush – leert die Ausgabe in eine Datei.	Unterstützt.	Hat keine Wirkung. (Gibt immer true zurück.)
fgetc – ruft Zeichen vom Dateizeiger ab.	Unterstützt.
fgetcsv – ruft eine Zeile aus dem Dateizeiger ab und parst nach CSV-Feldern.	Unterstützt.
fgets – ruft eine Zeile aus dem Dateizeiger ab.	Unterstützt.
fgetss – ruft eine Zeile aus dem Dateizeiger ab und entfernt HTML-Tags.	Unterstützt.
file_exists – prüft, ob eine Datei oder ein Verzeichnis existiert.	Unterstützt.
file_get_contents – liest eine gesamte Datei in einen String.	Unterstützt.
file_put_contents – schreibt einen String in eine Datei.	Unterstützt.
file – liest eine gesamte Datei in ein Array.	Unterstützt.
fileatime – ruft die Zeit des letzten Zugriffs auf die Datei ab.	Nicht unterstützt.	Gibt immer 0 zurück.
filectime – ruft die Zeit der Änderung des Datei-Inodes ab.	Nicht unterstützt.	Gibt immer 0 zurück.
filegroup – ruft die Dateigruppe ab.	Nicht unterstützt.	Gibt immer 0 zurück.
fileinode – ruft den Datei-Inode ab.	Nicht unterstützt.	Gibt immer 0 zurück.
filemtime – ruft die Zeit der Änderung der Datei ab.	Unterstützt.
fileowner – ruft den Dateibesitzer ab.	Nicht unterstützt.	Gibt immer 0 zurück.
fileperms – ruft die Dateiberechtigungen ab.	Unterstützt.	Das Ausführungsbit ist immer ausgeschaltet.
filesize – ruft die Dateigröße ab.	Unterstützt.
filetype – ruft den Dateityp ab.	Unterstützt.
flock – portable Dateisperre ("beratend").	Nicht unterstützt.	Gibt immer false zurück.
fopen – öffnet eine Datei oder URL.	Unterstützt.	Unterstützt nur die folgenden Modi: r, rb, rt, w, wb und wt.
fpassthru – gibt alle verbleibenden Daten in einem Dateizeiger aus.	Unterstützt.
fputcsv – formatiert eine Zeile als CSV und schreibt sie in den Dateizeiger.	Unterstützt.
fputs – Alias von fwrite.
fread – binärsicheres Lesen von Dateien.	Unterstützt.
fscanf – parst Eingaben von einer Datei gemäß einem Format.	Unterstützt.
fseek – sucht nach einem Dateizeiger.	Unterstützt.	Unterstützt nur Dateien, die im Lesemodus geöffnet wurden.
fstat – ruft Informationen über eine Datei mit einem geöffneten Dateizeiger ab.	Unterstützt.
ftell – gibt die aktuelle Position des Lese-/Schreibzeigers der Datei zurück.	Unterstützt.
ftruncate – schneidet eine Datei auf eine bestimmte Länge ab.	Nicht unterstützt.	Gibt immer false zurück.
fwrite – binärsicheres Schreiben von Dateien.	Unterstützt.
glob – sucht Pfadnamen, die mit einem Muster übereinstimmen.	Unterstützt.
is_dir – gibt an, ob der Dateiname ein Verzeichnis ist.	Unterstützt.
is_executable – gibt an, ob der Dateiname ausführbar ist.	Nicht unterstützt.	Gibt immer false zurück.
is_file – gibt an, ob der Dateiname eine reguläre Datei ist.	Unterstützt.
is_link – gibt an, ob der Dateiname eine symbolische Verknüpfung ist.	Nicht unterstützt.	Gibt immer false zurück.
is_readable – gibt an, ob eine Datei existiert und lesbar ist.	Unterstützt.
is_uploaded_file – gibt an, ob die Datei über HTTP POST hochgeladen wurde.	Unterstützt.
is_writable – gibt an, ob der Dateiname beschreibbar ist.	Unterstützt.	Der Wert wird im Cache gespeichert und spiegelt Änderungen der Berechtigungen möglicherweise nicht sofort wider.
is_writeable – Alias von is_writable.
lchgrp – ändert die Gruppenzugehörigkeit von symlink.	Nicht unterstützt.	Dies ist deaktiviert.
lchown – ändert die Eigentümerschaft von symlink.	Nicht unterstützt.	Dies ist deaktiviert.
link – erstellt einen festen Link.	Nicht unterstützt.	Dies ist deaktiviert.
linkinfo – ruft Informationen über einen Link ab.	Nicht unterstützt.	Gibt immer -1 zurück.
lstat – liefert Informationen über eine Datei oder einen symbolischen Link.	Unterstützt.
mkdir – erstellt ein Verzeichnis.	Unterstützt.
move_uploaded_file – verschiebt eine hochgeladene Datei an einen anderen Speicherort.	Unterstützt.
parse_ini_file – parst eine Konfigurationsdatei.	Unterstützt.
pathinfo – gibt Informationen über einen Dateipfad zurück.	Unterstützt.
pclose – schließt einen Prozessdateizeiger.	Nicht unterstützt.	Dies ist deaktiviert.
popen – öffnet einen Prozessdateizeiger.	Nicht unterstützt.	Dies ist deaktiviert.
readfile – gibt eine Datei aus.	Unterstützt.
readlink – gibt das Ziel eines symbolischen Links zurück.	Nicht unterstützt.	Gibt immer false zurück.
realpath – gibt den kanonischen absoluten Pfadnamen zurück.	Nicht unterstützt.	Gibt immer false zurück.
rename – benennt eine Datei oder ein Verzeichnis um.	Unterstützt.
rewind – fährt die Position eines Dateizeigers zurück.	Unterstützt.	Wird nur für den Lesemodus unterstützt.
rmdir – entfernt das Verzeichnis.	Unterstützt.
set_file_buffer – Alias von stream_set_write_buffer.
stat – liefert Informationen über eine Datei.	Unterstützt.
symlink – erstellt einen symbolischen Link.	Nicht unterstützt.	Dies ist deaktiviert.
tempnam – erstellt eine Datei mit einem eindeutigen Dateinamen.	Unterstützt.	Siehe diese Hinweise.
tmpfile – erstellt eine temporäre Datei.	Unterstützt.	Gibt eine arbeitsspeichergestützte Datei ähnlich php://memory zurück.
touch – legt die Zeit für den Zugriff und die Änderung der Datei fest.	Nicht unterstützt.	Gibt immer false zurück.
umask – ändert das aktuelle umask.	Unterstützt.	Gilt nicht für Cloud Storage-Dateien.
unlink – löscht eine Datei.	Unterstützt.

Beachten Sie, dass die Funktionen der Dateistatistik in dieser Tabelle (file_exists, filemtime, filesize, fstat, is_file, is_dir, is_writable und stat) auf Anfragebasis im Cache gespeichert werden. Sie können diesen Cache durch Aufrufen von clearstatcache leeren.

Zusätzlich werden folgende PHP-Verzeichnislesefunktionen unterstützt:

Funktionsname
opendir
readdir
rewinddir
closedir

Hinweis: Da Cloud Storage-Auflistungsvorgänge mit Eventual Consistency erfolgen, spiegelt readdir die Änderung möglicherweise nicht unmittelbar nach dem Hinzufügen, Umbenennen oder Entfernen eines Objekts wider.

Mit PHP 5 include und require

Die Verwendung von include und require in Bezug auf eine Cloud Storage-Datei ist standardmäßig deaktiviert, um die Sicherheit Ihrer Anwendung aufrechtzuerhalten. So können Sie sie jedoch aktivieren:

Wenn Sie PHP-Code aus Google Cloud Storage mit include oder require in Ihre Anwendung einfügen möchten, müssen Sie mit der google_app_engine.allow_include_gs_buckets-Anweisung in der php.ini-Datei angeben, in welchen Buckets diese Dateien enthalten sind.

Benutzerdefinierte Metadaten lesen und schreiben

Zum Anhängen benutzerdefinierter Metadaten an eine Datei, die in Google Cloud Storage geschrieben wird, fügen Sie die Metadaten zu $options hinzu, bevor Sie den Streamkontext für den Aufruf file_put_contents erstellen.

In diesem Beispiel erhalten Metadaten namens foo den far-Wert und eine andere namens bar den boo-Wert. In diesem Beispiel wird auch der Inhaltstyp auf text/plain gesetzt. Der Streamkontext wird mithilfe dieser Informationen in $options erstellt, und die Datei wird mithilfe von file_put_contents() sowie der Metadaten und dem Inhaltstyp in Cloud Storage geschrieben:

$metadata = ['foo' => 'bar', 'baz' => 'qux'];
$options = [
    'Content-Type' => 'text/plain',
    'metadata' => $metadata
];
$context = stream_context_create(['gs' => $options]);
file_put_contents("gs://${my_bucket}/hello_metadata.txt", $newFileContent, 0, $context);

Zum Lesen der benutzerdefinierten Metadaten und des Inhaltstyps für eine Datei rufen Sie fopen für die Datei auf und verwenden dann CloudStorageTools::getContentType() und CloudStorageTools::getMetaData(), um den Inhaltstyp bzw. die Metadaten abzurufen.

Die benutzerdefinierten Metadaten und der Inhaltstyp sind verfügbar, wenn Sie den vom Aufruf fopen zurückgegebenen Dateizeiger erhalten haben.

$fp = fopen("gs://${my_bucket}/hello_metadata.txt", 'r');
$content_type = CloudStorageTools::getContentType($fp);
$metadata = CloudStorageTools::getMetaData($fp);

Lesevorgänge im Cache gespeicherter Dateien

Standardmäßig werden Dateilesevorgänge vom App Engine-Stream-Wrapper für Cloud Storage in memcache gespeichert, um die Leistung der folgenden Lesevorgänge zu erhöhen. Caching kann mithilfe der Anweisung enable_cache im Streamkontext deaktiviert werden.

Hinweis: Wenn Caching aktiviert ist, werden Dateien, die aus Cloud Storage gelesen werden, beim Lesen im Cache gespeichert. Der Cache enthält auch die Dateiinformationen zur Schreibbarkeit. is_writable könnte also veraltete Dateiinformationen abfragen. Wenn Sie außerdem die ACL für einen Cloud Storage-Bucket ändern, um der Anwendung Schreibberechtigungen zu gewähren oder zu verweigern, kann es einige Zeit dauern, bis diese Änderung berücksichtigt wird.

Zur weiteren Leistungsverbesserung können Sie auch optimistisches Caching aktivieren. Dabei wird das Dateiobjekt aus dem Cache gelesen, ohne dass geprüft wird, ob das zugrunde liegende Objekt in Google Cloud Storage seit dem letzten Caching geändert wurde. Zum Aktivieren verwenden Sie die Anweisung enable_optimistic_cache (standardmäßig auf false gesetzt). Optimistisches Caching ist ideal für Szenarien mit einem Schreib- und vielen Lesezugriffen.

Sie können auch die Gültigkeitsdauer eines im Cache gespeicherten Objekts mit read_cache_expiry_seconds ändern. Nach dieser Dauer wird das Objekt beim nächsten Leseversuch wieder im Cache gespeichert. Standardmäßig ist dies auf 1 Stunde (3600) eingestellt.

In diesem Beispiel ist optimistisches Caching aktiviert und Dateiobjekte sind so konfiguriert, dass sie nach 5 Minuten für die erneute Speicherung im Cache aus Google Cloud Storage markiert werden.

$options = [
    'gs' => [
        'enable_cache' => true,
        'enable_optimistic_cache' => true,
        'read_cache_expiry_seconds' => 300,
    ]
];
$context = stream_context_create($options);
file_put_contents("gs://${my_bucket}/hello_caching.txt", $newFileContent, 0, $context);