Skip to content

Image - Popis tříd

Dokumentace tříd pro zpracování obrázků v core/Image/.

Třída Image

Frontendu třída (fasáda) pro práci s obrázky. Poskytuje jednoduché statické metody pro resize a crop operace.

Namespace: Petrovo\Image Soubor: core/Image/Image.php

Principy

  • Statická API – všechny metody jsou statické
  • Dvě varianty – ze souboru (resize(), crop()) nebo z obsahu (resizeFromContent(), cropFromContent())
  • GD rozšíření – vnitřně používá PHP GD library pro zpracování
  • Bezpečné oprávnění – výstupní soubory mají oprávnění 0666

Klíčové metody

Změna velikosti

Metoda Popis
resize(string $inName, string $outName, string $outType = 'webp', int $outMaxLongerSide = 1600, int $outMaxShorterSide = 1600, int $outQuality = 98, string $hardSite = ''): bool Změň velikost obrázku ze souboru
resizeFromContent(string $content, string $outName, string $outType = 'webp', int $outMaxLongerSide = 1600, int $outMaxShorterSide = 1600, int $outQuality = 98, string $hardSite = ''): bool Změň velikost obrázku z binárního obsahu

Ořezávání

Metoda Popis
crop(string $inName, string $outName, string $outType = 'webp', int $outWidth = 100, int $outHeight = 100, int $outQuality = 98, string $cropPosition = 'center'): bool Ořízni obrázek ze souboru
cropFromContent(string $content, string $outName, string $outType = 'webp', int $outWidth = 100, int $outHeight = 100, int $outQuality = 98, string $cropPosition = 'center'): bool Ořízni obrázek z binárního obsahu

Parametry resize metod

Image::resize(
    $inName,              // Cesta k vstupnímu obrázku
    $outName,             // Cesta pro uložení výstupního obrázku
    $outType = 'webp',    // Formát výstupu: 'webp', 'jpg', 'jpeg' (default: 'webp')
    $outMaxLongerSide,    // Maximální délka delší strany (default: 1600, max: 1600)
    $outMaxShorterSide,   // Maximální délka kratší strany (default: 1600, max: 1600)
    $outQuality = 98,     // Kvalita (1-100, default: 98)
    $hardSite = ''        // Režim zmenšování (detaily níže)
)

Výstupní formáty:

  • 'webp' – WebP (výchozí, lépe kompresuje)
  • 'jpg' nebo 'jpeg' – JPEG

Parametr hardSite (chování při zmenšování):

  • '' (prázdný, default) – Automatické rozhodnutí. Pokud je obrázek >1.5× širší/vyšší, použije se 'x' nebo 'y'
  • 'x' – Fixní šířka na $outMaxLongerSide, výška se proporcionálně zmenší
  • 'y' – Fixní výška na $outMaxShorterSide, šířka se proporcionálně zmenší
  • 'hs' – Hard size (full) – obrázek se zmenší a vycentruje na pevných rozměrech (doplnění bílou barvou)
  • 'cf' – Center fill – obrázek se vyplní na pevné rozměry a vycentruje

Malé obrázky: Pokud je vstupní obrázek menší než $outMaxLongerSide a není nastaveno $hardSite, vrátí se původní obsah bez změny.

Parametry crop metod

Image::crop(
    $inName,                  // Cesta k vstupnímu obrázku
    $outName,                 // Cesta pro uložení oříznutého obrázku
    $outType = 'webp',        // Formát výstupu: 'webp', 'jpg', 'jpeg'
    $outWidth = 100,          // Šířka výstupu v pixelech (default: 100)
    $outHeight = 100,         // Výška výstupu v pixelech (default: 100)
    $outQuality = 98,         // Kvalita (1-100, default: 98)
    $cropPosition = 'center'  // Pozice oříznutí (detaily níže)
)

Pozice oříznutí ($cropPosition):

  • 'center' (default) – Střed obrázku
  • 'top' – Horní část (vertikálně)
  • 'bottom' – Dolní část (vertikálně)
  • 'left' – Levá část (horizontálně)
  • 'right' – Pravá část (horizontálně)

Chování orientace: Pokud je obrázek wider (šířka > výška) a zvolíš 'top', automaticky se konvertuje na 'left'. Pokud je obrázek wider a zvolíš 'bottom', automaticky se konvertuje na 'right'.

Malé obrázky: Pokud je vstupní obrázek menší než cílové rozměry ($outWidth, $outHeight), vrátí se původní obsah beze změny.

Třída Resize

Vnitřní třída pro zpracování změny velikosti. Volána z Image::resizeFromContent().

Namespace: Petrovo\Image\Processing Soubor: core/Image/Processing/Resize.php

Metoda

public static function fromContent(
    string $content,
    string $outName,
    string $outType = 'webp',
    int $outMaxLongerSide = 1600,
    int $outMaxShorterSide = 1600,
    int $outQuality = 98,
    string $hardSite = ''
): bool

Implementace

  1. Validace formátu – ověří, že $outType je validní (webp/jpg/jpeg)
  2. Čtení obrázku – imagecreatefromstring() parse binárního obsahu
  3. Detekce orientace – určí, jestli je obrázek horizontální či vertikální
  4. Automatické nastavení hardSite – pokud není explicitně nastaveno a obrázek je >1.5× stran
  5. Výpočet nových rozměrů – respektuje $outMaxLongerSide a $outMaxShorterSide
  6. Tvorba nového obrázku – imagecreatetruecolor() nebo imagecreate()
  7. Nastavení pozadí:
  8. Pro WebP/PNG: transparentní pozadí
  9. Pro JPEG: bílé pozadí
  10. Resampling – imagecopyresampled() zajistí kvalitní zmenšení
  11. Uložení – imagewebp() nebo imagejpeg()
  12. Automatické čištění – garbage collector uvolní paměť (PHP 8.0+)
  13. Oprávnění – chmod($outName, 0666) pro zápis adresářem

Vrácené hodnoty

  • true – úspěšné zpracování
  • false – chyba (např. nevalidní obrázek)

Třída Crop

Vnitřní třída pro zpracování ořezu. Volána z Image::cropFromContent().

Namespace: Petrovo\Image\Processing Soubor: core/Image/Processing/Crop.php

Metoda

public static function fromContent(
    string $content,
    string $outName,
    string $outType = 'webp',
    int $outWidth = 100,
    int $outHeight = 100,
    int $outQuality = 98,
    string $cropPosition = 'center'
): bool

Implementace

  1. Validace formátu – ověří, že $outType je validní (webp/jpg/jpeg)
  2. Čtení obrázku – imagecreatefromstring() parse binárního obsahu
  3. Detekce velikosti – zjistí rozměry vstupního obrázku
  4. Kontrola malých obrázků – vrátí originál, pokud je menší než cílové rozměry
  5. Výpočet škálování – max($outWidth / $width, $outHeight / $height) zajistí pokrytí
  6. Výpočet pozice oříznutí – na základě $cropPosition určí offset
  7. Detekce orientace – if ($width > $height) převrátí 'top'/'bottom' na 'left'/'right'
  8. Tvorba výstupního obrázku – imagecreatetruecolor() s bílým pozadím
  9. Resampling s offsetem – imagecopyresampled() s negativními offsety [-$intWidth, -$intHeight]
  10. Uložení – imagewebp() nebo imagejpeg()
  11. Automatické čištění – garbage collector uvolní paměť (PHP 8.0+)
  12. Oprávnění – chmod($outName, 0666) pro zápis adresářem

Vrácené hodnoty

  • true – úspěšné zpracování
  • false – chyba (např. nevalidní obrázek)

Výstupní oprávnění

Všechny operace nastavují oprávnění výstupního souboru na 0666, aby byl soubor přístupný ostatním procesům.

Formáty a kompatibilita

Vstupní formáty

  • Cokoliv, co PHP GD přijme: JPEG, PNG, GIF, WebP, BMP a další

Výstupní formáty

  • 'webp' – moderní formát s nejlepší kompresí
  • 'jpg' / 'jpeg' – kompatibilní JPEG

Kvalita

  • Rozsah: 1–100
  • Výchozí: 98 (vysoká kvalita)
  • Minimálně 1, maximálně 100

Shrnutí (pro vývojáře)

  • Používej Image:: fasádu – je to jednoduché a transparentní API
  • Dvě varianty: ze souboru (resize(), crop()) nebo z obsahu (resizeFromContent(), cropFromContent())
  • Pro změnu velikosti: Image::resize() nebo Image::resizeFromContent()
  • Pro ořez: Image::crop() nebo Image::cropFromContent()
  • Vrácení true/false znamená úspěch/neúspěch
  • Výstupní soubory jsou automaticky nastaveny na 0666 oprávnění
  • Vnitřní třídy (Resize, Crop) se nepoužívají přímo – vždy přes Image fasádu