PHPackages                             clevis/files-upload-control - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. clevis/files-upload-control

ActiveLibrary[Utility & Helpers](/categories/utility)

clevis/files-upload-control
===========================

Files upload control for Nette Forms.

075[1 issues](https://github.com/Clevis/FilesUploadControl/issues)PHP

Since Mar 30Pushed 11y ago8 watchersCompare

[ Source](https://github.com/Clevis/FilesUploadControl)[ Packagist](https://packagist.org/packages/clevis/files-upload-control)[ RSS](/packages/clevis-files-upload-control/feed)WikiDiscussions master Synced today

READMEChangelogDependenciesVersions (1)Used By (0)

File Upload Control
===================

[](#file-upload-control)

Formulářová komponenta pro upload souborů. Pro použití si ho poděďte a vytvořte šablonu, ta výchozí vám nejspíš nebude k ničemu.

Umožňuje odeslání souborů dvěma způsoby:

- Normálně formulářově.
- Ajaxově.

Při zpracování formuláře dostanete jako hodnotu prvku pole entit, které reprezentují soubory. Viz napojení na model.

API těch ajaxových signálů bylo psané na míru [jQuery File Upload Plugin](https://github.com/blueimp/jQuery-File-Upload), ale mělo by být použitelné i s jinými nahrávadly. Viz napojení na frontend.

Kompatibilita
-------------

[](#kompatibilita)

Testy prochází jak na Nette `@dev` (momentálně nette/nette@ae11ca1), tak i na `2.0.12`.

Testy nebudou procházet v PHP 5.3 - párkrát jsem použil `$this` v closuře a možná sem tam nějaké to zkrácené pole... Ale samotná komponenta by v PHP 5.3 fungovat měla.

Napojení na Template factory
----------------------------

[](#napojení-na-template-factory)

Komponenta vyžaduje, aby v service containeru byla služba s názvem "templateFactory" s public metodou `createTemplate($file, Nette\Application\UI\Control $control)`.

Je to trochu špína, ale správným řešením se teď nebudu zdržovat (správné řešení by mít pro tu službu rozhranní v dalším balíčku, který by tento balíček vyžadoval; a vůbec nejlepší by bylo, kdyby to rozhranní bylo už v Nette).

Napojení na model
-----------------

[](#napojení-na-model)

Konstruktoru této komponenty se předává objekt `IFilesRepository`, který je zodpovědný za CRUD entit typu `IFileEntity`. Mělo by to být nasaditelné jak na `PetrP/Orm`, tak i `Tharos/LeanMapper`. Repository je také zodpovědné za přesun souboru někam mimo temp.

Pozor na to, že `saveFile` se volá pouze při uploadu přes signál. U souborů, které se uploadují přes formulář, si uložení entity musíte obstarat v obsluze formuláře.

Napojení na frontend
--------------------

[](#napojení-na-frontend)

Vlastností každého formulářového prvku v Nette je `htmlName`, od něj se odvozují názvy POST proměnných:

- `htmlName[]` - Nahrané soubory.
- `htmlName-autoUploaded[]` - ID souborů, které byly nahrané ajaxem. S tímto polem se pracuje pouze při odeslání formuláře.

Takže upload přes HTML obstará `` a případný ajaxový nahrávač také používá ten samý název (jen jinou URL, o tom dále).

Ajaxový nahrávač by měl po úspěšném ajaxovém uploadu do formuláře vložit ``, kde ve `value` bude ID nahraného souboru (získá z payloadu upload signálu). Tím si formulář "pamatuje", jaké soubory se přes něj nahrály a po odeslání si jejich entity vytáhne z repository.

Tato komponenta se neomezuje pouze na nahrávání nových souborů, lze ji úspěšně využít i pro změnu pořadí stávajících souborů. Prostě je vypíšete a ke každému přihodíte ten `hidden` s `htmlName-autoUploaded[]`. Nahodíte jQuery sortable a máte hotovo. Při zpracování dostanete pole všech souborů ve správném pořadí.

### Ajaxový upload signál

[](#ajaxový-upload-signál)

`{$control->getUploadLink()}`

Přijímá soubory v poli `htmlName[]`, vrací JSON payload v tomto formátu:

```
{
	"files": [
		{
			"id": 1,
			"name": "nazev-souboru.txt",
			"size": 123,
			"type": "text/plain",
			"delete_type": "DELETE",
			"delete_url": "URL delete signálu",
			"thumbnail_url": "URL náhledu",
			"url": "URL plné velikosti"
		},
		{
			"id": 1,
			"name": "jini-soubor.gif",
			"size": 666,
			"type": "image/gif",
			"delete_type": "DELETE",
			"delete_url": "URL delete signálu",
			"thumbnail_url": "...",
			"url": "..."
		},
		{
			"name": "prilis-velky-soubor.txt",
			"error": "Maximální povolená velikost souboru je 123."
		},
		{
			"name": "vice-problemu.gif",
			"error": [
				"Je vyžadována přípona TXT.",
				"Maximální povolená velikost souboru je 123."
			]
		}
	]
}

```

Hodnoty `thumbnail_url` a `url` jsou v odpovědi pouze v případě, že komponenta má definovaný IUrlProvider (viz `setUrlProvider`). Pokud by formát nevyhovoval, můžete předefinovat metody `createFilePayload()` a `createErrorPayload()`.

Při uploadu přes tento signál se provádí validace pouze podle těchto pravidel:

- `FilesUploadControl::MAX_FILE_SIZE`
- `FilesUploadControl::MIME_TYPE`
- `FilesUploadControl::IMAGE`
- `FilesUploadControl::RULE_EXTENSION`

Pokud jsou na controlu nasazené nějaké další validátory, tak na ty dojde až po odeslání formuláře.

### Ajaxový delete signál

[](#ajaxový-delete-signál)

`{$control->getDeleteLink(IFileEntity $file)}`

Pokud má komponenta nastavenou session section (viz `setAutoUploadsSessionSection()`), tak tímto signálem lze smazat soubory (resp. zavolat `IFilesRepositor::deleteFile()`), které byly uploadovány přes upload signál, ale ještě nebyly zpracovány při odeslání formuláře.

Ale i pokud session nastavená není, nebo v ní není ten soubor, tak se zavolají události `onBeforeDelete` a `onDelete`, takže si to chování můžete i rozšířit.

Bez ohledu na výsledek operace vrací tuto odpověď:

```
{
	"success": true
}

```

Nastavení komponenty
--------------------

[](#nastavení-komponenty)

Volitelné závislosti:

- `setUrlProvider(IFileUrlProvider $urlProvider)` - Pokud má upload signál vracet URL a URL náhledu, potřebuje vědět jak.
- `setAutoUploadsSessionSection(SessionSection $autoUploadsSession)` - Pokud chcete používat delete signál.

Události:

- `onAutoUpload(IFileEntity $file, \ArrayObject $filePayload)` - při upload signálu po uložení souboru. Může upravit payload (je to ArrayObject, protože s předáváním pole referencí jsem měl nějaké problémy, už nevím jaké).
- `onBeforeDelete(IFileEntity $file)` - před smazáním.
- `onDelete(IFileEntity $file)` - po smazání, i pokud neproběhlo. Tohle asi změním.

Obrana proti CSRF
-----------------

[](#obrana-proti-csrf)

Pokud je formulář chráněný pomocí `Form::addProtection()`, tak jsou chráněné i ajaxové signály této komponenty. Metody `getUploadLink()` a `getDeleteLink()` k URL signálu přidají token a ten se při zpracování signálu zkontroluje.

###  Health Score

22

—

LowBetter than 22% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity9

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 95% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/2980945?v=4)[roboclevis](/maintainers/roboclevis)[@roboclevis](https://github.com/roboclevis)

![](https://www.gravatar.com/avatar/4fc15198fe15683d84819a35719ca4b0887a807996b5f46be47124805e650323?d=identicon)[VaclavSir](/maintainers/VaclavSir)

---

Top Contributors

[![VaclavSir](https://avatars.githubusercontent.com/u/1473642?v=4)](https://github.com/VaclavSir "VaclavSir (19 commits)")[![radekbernatek](https://avatars.githubusercontent.com/u/3998427?v=4)](https://github.com/radekbernatek "radekbernatek (1 commits)")

### Embed Badge

![Health badge](/badges/clevis-files-upload-control/health.svg)

```
[![Health](https://phpackages.com/badges/clevis-files-upload-control/health.svg)](https://phpackages.com/packages/clevis-files-upload-control)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)