latte 3.1.3

dg · dg · commit a95425be7f41 · 2026-03-26T10:28:17.000+01:00
diff --git a/latte/cs/develop.texy b/latte/cs/develop.texy
@@ -216,6 +216,70 @@ Pokud je toto zapnuto, Latte kontroluje vykreslované atributy a vyvolá uživat
 Jakmile jsou všechna varování vyřešena, vypněte varování o migraci a **odstraňte všechny** filtry `|accept` ze svých šablon, protože již nejsou potřeba.
 
 
+Scopované proměnné cyklu .{data-version:3.1.3}
+==============================================
+
+Ve výchozím nastavení zůstávají proměnné definované v cyklu `{foreach}` (jako `$key` a `$value`) dostupné i po jeho skončení – stejně jako v samotném PHP. To může vést k nechtěnému přepsání proměnných, pokud má proměnná cyklu stejný název jako existující proměnná šablony.
+
+Funkce `ScopedLoopVariables` omezí platnost proměnných na tělo cyklu. Po jeho skončení se obnoví původní hodnota proměnné (pokud existovala), nebo se proměnná odstraní:
+
+```php
+$latte = new Latte\Engine;
+$latte->setFeature(Latte\Feature::ScopedLoopVariables);
+```
+
+Příklad rozdílu:
+
+```latte
+{var $item = 'original'}
+{foreach [1, 2] as $item}{$item}, {/foreach}
+{$item}
+```
+
+Bez `ScopedLoopVariables`: vypíše `1, 2, 2` (proměnná je přepsána)
+Se `ScopedLoopVariables`: vypíše `1, 2, original` (proměnná je obnovena)
+
+Funguje to i s destrukturováním, např. `{foreach $array as [$a, $b]}`.
+
+.[note]
+Proměnné cyklu používající reference (`{foreach $array as &$value}`) nebo přiřazení do vlastností (`{foreach $array as $obj->prop}`) nejsou scopovány, protože by to narušilo jejich účel.
+
+
+Automatické odsazení (Dedent) .{toc: Dedent}{data-version:3.1.3}
+================================================================
+
+Při používání párových značek jako `{if}`, `{foreach}` nebo `{block}` se vnořený obsah často odsazuje pro lepší čitelnost. Toto odsazení se ale ve výchozím nastavení přenáší do vygenerovaného výstupu. Funkce `Dedent` ho automaticky odstraní, takže výstup zůstane čistý bez ohledu na úroveň zanoření v šabloně:
+
+```php
+$latte = new Latte\Engine;
+$latte->setFeature(Latte\Feature::Dedent);
+```
+
+Příklad:
+
+```latte
+{if true}
+	Hello
+	World
+{/if}
+```
+
+Bez `Dedent` by výstup obsahoval odsazení (`\tHello\n\tWorld\n`). S `Dedent` se odsazení odstraní a výstupem je `Hello\nWorld\n`.
+
+Hlubší odsazení uvnitř bloku zůstává zachováno relativně k základnímu odsazení:
+
+```latte
+{if true}
+	Hello
+		Indented
+{/if}
+```
+
+Výstup: `Hello\n\tIndented\n`.
+
+Odsazení v bloku musí být konzistentní (buď tabulátory, nebo mezery). Pokud se mísí, Latte vyhodí výjimku `Inconsistent indentation`.
+
+
 Překládání v šablonách .{toc: TranslatorExtension}
 ==================================================
 
diff --git a/latte/cs/filters.texy b/latte/cs/filters.texy
@@ -10,6 +10,8 @@ V šablonách můžeme používat funkce, které pomáhají upravit nebo přefor
 | `breakLines` | [Před konce řádku přidá HTML odřádkování |#breakLines]
 | `bytes`      | [formátuje velikost v bajtech |#bytes]
 | `clamp`      | [ohraničí hodnotu do daného rozsahu |#clamp]
+| `column`     | [extrahuje jeden sloupec z pole |#column]
+| `commas`     | [spojí pole čárkami |#commas]
 | `dataStream` | [konverze pro Data URI protokol |#dataStream]
 | `date`       | [formátuje datum a čas |#date]
 | `explode`    | [rozdělí řetězec na pole podle oddělovače |#explode]
@@ -259,6 +261,50 @@ Ohraničí hodnotu do daného inkluzivního rozsahu min a max.
 Existuje také jako [funkce |functions#clamp].
 
 
+column(string|int|null $columnKey, string|int|null $indexKey=null) .[filter]{data-version:3.1.3}
+------------------------------------------------------------------------------------------------
+Vrátí z vícerozměrného pole hodnoty jednoho sloupce `$columnKey` jako nové pole. Lze použít i na pole objektů pro získání hodnot vlastností.
+
+```latte
+{var $users = [
+	[id: 30, name: 'John', age: 30],
+	[id: 32, name: 'Jane', age: 25],
+	[id: 33, age: 35],
+]}
+
+{$users|column: 'name'}
+{* vrátí ['John', 'Jane'] *}
+
+{$users|column: 'name', 'id'}
+{* vrátí [30 => 'John', 32 => 'Jane'] *}
+```
+
+Pokud předáte `null` jako klíč sloupce, přeindexuje pole podle `$indexKey`.
+
+
+commas(?string $lastGlue=null) .[filter]{data-version:3.1.3}
+------------------------------------------------------------
+Spojí prvky pole čárkou a mezerou (`', '`). Jde o pohodlnou zkratku pro běžný výpis položek v čitelné podobě.
+
+```latte
+{var $items = ['jablka', 'pomeranče', 'banány']}
+{$items|commas}
+{* vypíše 'jablka, pomeranče, banány' *}
+```
+
+Lze zadat i vlastní oddělovač pro poslední dvojici položek:
+
+```latte
+{$items|commas: ' a '}
+{* vypíše 'jablka, pomeranče a banány' *}
+
+{=['PHP', 'JavaScript', 'Python']|commas: ', nebo '}
+{* vypíše 'PHP, JavaScript, nebo Python' *}
+```
+
+Viz také [#implode].
+
+
 dataStream(string $mimetype=detect) .[filter]
 ---------------------------------------------
 Konvertuje obsah do data URI scheme. Pomocí něj lze do HTML nebo CSS vkládat obrázky bez nutnosti linkovat externí soubory.
@@ -407,6 +453,8 @@ Můžete také použít alias `join`:
 {=[1, 2, 3]|join}         {* vypíše '123' *}
 ```
 
+Viz také [#commas], [#explode].
+
 
 indent(int $level=1, string $char="\t") .[filter]
 -------------------------------------------------
@@ -637,19 +685,21 @@ Pamatujte, že skutečný vzhled čísel se může lišit podle nastavení země
 
 padLeft(int $length, string $pad=' ') .[filter]
 -----------------------------------------------
-Doplní řetězec do určité délky jiným řetězcem zleva.
+Doplní řetězec nebo číslo do určité délky jiným řetězcem zleva.
 
 ```latte
 {='hello'|padLeft: 10, '123'}  {* vypíše '12312hello' *}
+{=123|padLeft: 5, '0'}         {* vypíše '00123' *}
 ```
 
 
 padRight(int $length, string $pad=' ') .[filter]
 ------------------------------------------------
-Doplní řetězec do určité délky jiným řetězcem zprava.
+Doplní řetězec nebo číslo do určité délky jiným řetězcem zprava.
 
 ```latte
 {='hello'|padRight: 10, '123'}  {* vypíše 'hello12312' *}
+{=123|padRight: 5, '0'}         {* vypíše '12300' *}
 ```
 
 
@@ -747,14 +797,14 @@ Viz také [#ceil], [#floor].
 
 slice(int $start, ?int $length=null, bool $preserveKeys=false) .[filter]
 ------------------------------------------------------------------------
-Extrahuje část pole nebo řetězce.
+Extrahuje část pole, řetězce nebo iterátoru.
 
 ```latte
 {='hello'|slice: 1, 2}           {* vypíše 'el' *}
 {=['a', 'b', 'c']|slice: 1, 2}   {* vypíše ['b', 'c'] *}
 ```
 
-Filtr funguje jako funkce PHP `array_slice` pro pole nebo `mb_substr` pro řetězce s fallbackem na funkci `iconv_substr` v režimu UTF‑8.
+Filtr funguje jako funkce PHP `array_slice` pro pole nebo `mb_substr` pro řetězce. Pro iterátory vrací generátor – prvky se čtou z původního zdroje jeden po druhém a po dosažení limitu se čtení zastaví. Celý iterátor se do paměti nenačítá.
 
 Pokud je start kladný, posloupnost začné posunutá o tento počet od začátku pole/řetezce. Pokud je záporný posloupnost začné posunutá o tolik od konce.
 
diff --git a/latte/cs/syntax.texy b/latte/cs/syntax.texy
@@ -250,6 +250,8 @@ A co když tag není na řádku sám, ale je tam i další obsah? Bílé znaky p
 
 Odsazení je tedy fakticky uvnitř `{if}`: pokud je `$foo` false, nevypíše se nic – ani odsazení, ani prázdný řádek. Pokud je `$foo` true, výstup přirozeně obsahuje odsazení. Prostě pište přehledně odsazené šablony a výstup bude vždy čistý.
 
+Pro ještě čistší výstup lze aktivovat funkci [Dedent |develop#Dedent], která odstraní i odsazení vzniklé zanořením v párových značkách jako `{if}` nebo `{foreach}`.
+
 
 Syntaktický cukr
 ================
diff --git a/latte/en/develop.texy b/latte/en/develop.texy
@@ -216,6 +216,70 @@ When enabled, Latte checks rendered attributes and triggers a user warning (`E_U
 Once all warnings are resolved, disable migration warnings and **remove all** `|accept` filters from your templates, as they are no longer needed.
 
 
+Scoped Loop Variables .{data-version:3.1.3}
+===========================================
+
+By default, variables defined in a `{foreach}` loop (like `$key` and `$value`) remain accessible after the loop ends – just like in PHP itself. This can lead to unintended variable overwrites when a loop variable has the same name as an existing template variable.
+
+The `ScopedLoopVariables` feature limits the scope of loop variables to the loop body. After the loop ends, the original variable value is restored (if it existed before), or the variable is unset:
+
+```php
+$latte = new Latte\Engine;
+$latte->setFeature(Latte\Feature::ScopedLoopVariables);
+```
+
+Example of the difference:
+
+```latte
+{var $item = 'original'}
+{foreach [1, 2] as $item}{$item}, {/foreach}
+{$item}
+```
+
+Without `ScopedLoopVariables`: outputs `1, 2, 2` (variable is overwritten)
+With `ScopedLoopVariables`: outputs `1, 2, original` (variable is restored)
+
+This also works with destructuring syntax, e.g. `{foreach $array as [$a, $b]}`.
+
+.[note]
+Loop variables using references (`{foreach $array as &$value}`) or property assignments (`{foreach $array as $obj->prop}`) are not scoped, as this would break their intended purpose.
+
+
+Automatic Dedentation .{toc: Dedent}{data-version:3.1.3}
+========================================================
+
+When using paired tags like `{if}`, `{foreach}`, or `{block}`, you often indent the nested content for readability. However, this indentation is included in the generated output by default. The `Dedent` feature automatically removes it, so the output stays clean regardless of how deeply you nest your Latte tags:
+
+```php
+$latte = new Latte\Engine;
+$latte->setFeature(Latte\Feature::Dedent);
+```
+
+Example:
+
+```latte
+{if true}
+	Hello
+	World
+{/if}
+```
+
+Without `Dedent`, the output would include the indentation (`\tHello\n\tWorld\n`). With `Dedent`, the indentation is stripped and the output is `Hello\nWorld\n`.
+
+Deeper indentation within a block is preserved relative to the base indentation:
+
+```latte
+{if true}
+	Hello
+		Indented
+{/if}
+```
+
+Output: `Hello\n\tIndented\n`.
+
+Indentation within a block must be consistent (either tabs or spaces). If they are mixed, Latte throws an `Inconsistent indentation` exception.
+
+
 Translation in Templates .{toc: TranslatorExtension}
 ====================================================
 
diff --git a/latte/en/filters.texy b/latte/en/filters.texy
@@ -10,6 +10,8 @@ In templates, we can use functions that help modify or reformat data into its fi
 | `breakLines` | [Inserts HTML line breaks before all newlines |#breakLines]
 | `bytes`      | [formats size in bytes |#bytes]
 | `clamp`      | [clamps a value to the given range |#clamp]
+| `column`     | [extracts a single column from an array |#column]
+| `commas`     | [joins an array with commas |#commas]
 | `dataStream` | [Data URI protocol conversion |#dataStream]
 | `date`       | [formats the date and time |#date]
 | `explode`    | [splits a string into an array by a delimiter |#explode]
@@ -259,6 +261,50 @@ Clamps a value to the given inclusive range of min and max.
 Also exists as a [function |functions#clamp].
 
 
+column(string|int|null $columnKey, string|int|null $indexKey=null) .[filter]{data-version:3.1.3}
+------------------------------------------------------------------------------------------------
+Returns the values of a single column `$columnKey` from a multidimensional array as a new array. Can also be used on arrays of objects to extract property values.
+
+```latte
+{var $users = [
+	[id: 30, name: 'John', age: 30],
+	[id: 32, name: 'Jane', age: 25],
+	[id: 33, age: 35],
+]}
+
+{$users|column: 'name'}
+{* returns ['John', 'Jane'] *}
+
+{$users|column: 'name', 'id'}
+{* returns [30 => 'John', 32 => 'Jane'] *}
+```
+
+If you pass `null` as the column key, it will reindex the array according to `$indexKey`.
+
+
+commas(?string $lastGlue=null) .[filter]{data-version:3.1.3}
+------------------------------------------------------------
+Joins array elements with a comma and space (`', '`). A convenient shortcut for listing items in a human-readable format.
+
+```latte
+{var $items = ['apples', 'oranges', 'bananas']}
+{$items|commas}
+{* outputs 'apples, oranges, bananas' *}
+```
+
+You can also provide a custom separator for the last pair of items:
+
+```latte
+{$items|commas: ' and '}
+{* outputs 'apples, oranges and bananas' *}
+
+{=['PHP', 'JavaScript', 'Python']|commas: ', or '}
+{* outputs 'PHP, JavaScript, or Python' *}
+```
+
+See also [#implode].
+
+
 dataStream(string $mimetype='detect') .[filter]
 -----------------------------------------------
 Converts content to the data URI scheme. This allows embedding images into HTML or CSS without needing to link external files.
@@ -407,6 +453,8 @@ You can also use the alias `join`:
 {=[1, 2, 3]|join}         {* outputs '123' *}
 ```
 
+See also [#commas], [#explode].
+
 
 indent(int $level=1, string $char="\t") .[filter]
 -------------------------------------------------
@@ -637,19 +685,21 @@ Remember that the actual appearance of numbers may vary depending on the country
 
 padLeft(int $length, string $pad=' ') .[filter]
 -----------------------------------------------
-Pads a string to a certain length with another string from the left.
+Pads a string or number to a certain length with another string from the left.
 
 ```latte
 {='hello'|padLeft: 10, '123'}  {* outputs '12312hello' *}
+{=123|padLeft: 5, '0'}         {* outputs '00123' *}
 ```
 
 
 padRight(int $length, string $pad=' ') .[filter]
 ------------------------------------------------
-Pads a string to a certain length with another string from the right.
+Pads a string or number to a certain length with another string from the right.
 
 ```latte
 {='hello'|padRight: 10, '123'}  {* outputs 'hello12312' *}
+{=123|padRight: 5, '0'}         {* outputs '12300' *}
 ```
 
 
@@ -747,14 +797,14 @@ See also [#ceil], [#floor].
 
 slice(int $start, ?int $length=null, bool $preserveKeys=false) .[filter]
 ------------------------------------------------------------------------
-Extracts a slice of an array or a string.
+Extracts a slice of an array, string, or iterator.
 
 ```latte
 {='hello'|slice: 1, 2}           {* outputs 'el' *}
 {=['a', 'b', 'c']|slice: 1, 2}   {* outputs ['b', 'c'] *}
 ```
 
-The filter works like the PHP function `array_slice` for arrays or `mb_substr` for strings, with a fallback to the `iconv_substr` function in UTF‑8 mode.
+The filter works like the PHP function `array_slice` for arrays or `mb_substr` for strings. For iterators, it returns a generator – elements are consumed from the source one by one and reading stops once the limit is reached. The entire iterator is never loaded into memory.
 
 If `start` is non-negative, the sequence will start at that offset from the beginning of the array/string. If `start` is negative, the sequence will start that far from the end.
 
diff --git a/latte/en/syntax.texy b/latte/en/syntax.texy
@@ -250,6 +250,8 @@ What if a tag isn't alone on a line, but appears alongside other content? The wh
 
 The indentation is effectively inside `{if}`: when `$foo` is false, nothing is output – not even the indentation or a blank line. When `$foo` is true, the output naturally includes the indentation. You simply write well-structured templates and the output is always clean.
 
+For even cleaner output, you can enable the [Dedent |develop#Dedent] feature, which also removes indentation caused by nesting within paired tags like `{if}` or `{foreach}`.
+
 
 Syntactic Sugar
 ===============
