nette-cloudflare-r2
nette-cloudflare-r2 je rozšíření pro Nette pro ukládání souborů do Cloudflare R2: nahrávání po částech s průběhem, dočasné podepsané odkazy, více bucketů, pravidla životního cyklu a panel v Tracy.
nette-cloudflare-r2 je rozšíření pro Nette, přes které aplikace ukládá soubory do úložiště Cloudflare R2 místo na disk serveru. Aplikace, do které uživatelé nahrávají faktury, fotky nebo videa, plní adresář uploads/, ten roste v každé záloze a při přechodu na dva servery je potřeba ho nějak sdílet. R2 drží soubory mimo server, mluví stejným rozhraním jako Amazon S3 a Cloudflare za odchozí přenos dat z něj neúčtuje poplatek. Tohle rozšíření z něj dělá službu v kontejneru Nette: $r2->upload(), $r2->get(), $r2->getPresignedUrl().
Proč ne rovnou AWS SDK
Knihovna stojí na oficiálním AWS SDK pro PHP a S3 klienta z něj jde kdykoli vytáhnout (getS3Client()). SDK ale neví nic o Nette: o konfiguraci v NEONu, o objektu FileUpload z formuláře, o panelu v Tracy ani o tom, že R2 má adresu podle ID účtu a zvláštní adresy pro jurisdikce EU a FedRAMP. Rozšíření tohle všechno skládá z konfigurace a k S3 operacím přidává klienta REST API Cloudflare pro věci, které rozhraní S3 nemá: vlastní domény bucketu, veřejnou doménu r2.dev, notifikace o událostech, metriky účtu a dočasné přístupové údaje.
Co aplikace dostane
Velké soubory po částech
Soubor nad 100 MB se při nahrání sám přepne na vícedílný upload s částmi po 8 MB. Pro dlouhé nahrávání je ChunkedUploader, který po každé části zavolá funkci s počtem odeslaných bajtů, takže jde ukázat průběh, a umí přerušený upload navázat (resume()). Na snímku nahoře odeslal 20 MB soubor ve třech částech. Statistiky z getStats() (operace, nahrané a stažené bajty, chyby) počítají i tyto uploady: po zkoušce ukazují bytesUploaded 20 000 037.
Dočasné odkazy místo veřejných souborů
getPresignedUrl() vytvoří podepsaný odkaz ke stažení, getPresignedUploadUrl() odkaz, na který může nahrát přímo prohlížeč. Platnost je nejvýš sedm dní, delší hodnotu knihovna zkrátí. Faktura tak může zůstat v soukromém bucketu a zákazník dostane odkaz platný hodinu.
Formulář, více bucketů a třídy úložiště
uploadFile() přijme FileUpload z formuláře Nette, vezme z něj typ obsahu a uloží soubor pod jedinečným jménem do zvoleného adresáře. V konfiguraci jde pojmenovat víc bucketů (třeba images a backups) s vlastní veřejnou adresou a třídou úložiště a R2ClientFactory pro každý vytvoří klienta. Málo používaná data jdou do třídy STANDARD_IA rovnou při nahrání, nebo později přes pravidla životního cyklu, která umí soubory po zadané době přesunout, smazat nebo uklidit nedokončené vícedílné uploady.
Stažení z cizí adresy bez rizika pro vnitřní síť
StreamUploader::uploadFromUrl() stáhne soubor z adresy a uloží ho do R2. Před stažením přeloží jméno serveru na IP a odmítne jiné schéma než http a https i adresy z privátních, loopback a rezervovaných rozsahů, takže přes formulář „nahrát z URL“ nikdo nedosáhne na služby uvnitř sítě.
Vyzkoušeno proti rozhraní S3
Bez účtu Cloudflare nejde volat skutečné R2. Snímek proto ukazuje klienta R2Client napojeného přes S3 rozhraní na lokální MinIO: nahrání, metadata, podepsaný odkaz stažený bez přihlašovacích údajů, vícedílný upload, výpis, hromadné smazání a chybu 404 u smazaného souboru, která přišla jako ObjectException s kódem R2 10007. Testy v Nette Tester (konfigurace, volby uploadu, mapování chyb a statistiky nad napodobeným S3 klientem) prošly na PHP 8.1 i 8.4; integrační test proti R2 se bez proměnných R2_* přeskočí.
Chyby podle typu
R2Client převádí chyby S3 na výjimky podle kódu chyby, a když ho odpověď nenese, podle HTTP stavu. Chybějící objekt skončí jako ObjectException (kód 10007), chybějící bucket jako BucketException, špatné nebo nedostatečné přihlášení jako AuthenticationException, potíže s vícedílným uploadem jako UploadException a překročený limit jako RateLimitException, jejíž getRetryAfter() čte hlavičku Retry-After. Číslo chyby R2 vrací getR2ErrorCode(), HTTP stav getHttpStatusCode() a původní výjimku SDK getPrevious(). Chyba, kterou knihovna nezná, zůstane obecnou R2Exception s kódem 0.
Jak začít
composer require nks-hub/nette-cloudflare-r2
extensions:
r2: NksHub\NetteCloudflareR2\DI\CloudflareR2Extension
r2:
accountId: %env.R2_ACCOUNT_ID%
accessKeyId: %env.R2_ACCESS_KEY_ID%
secretAccessKey: %env.R2_SECRET_ACCESS_KEY%
defaultBucket: faktury
publicUrl: 'https://cdn.example.com'
tracy: %debugMode%
Potřeba je PHP 8.1 nebo novější, Nette 3 a účet Cloudflare s přístupovým klíčem k R2. Poslední verze je 1.1.2 ze 6. listopadu 2026.
Zdrojový kód
Kód je na GitHubu v repozitáři nks-hub/nette-cloudflare-r2 pod licencí MIT, balíček na Packagistu jako nks-hub/nette-cloudflare-r2.