Sistemul de fișiere
*******************

.[perex]
[api:Nette\Utils\FileSystem] este o clasă cu funcții utile pentru lucrul cu sistemul de fișiere. Un avantaj față de funcțiile native PHP este că aruncă excepții în caz de eroare.


Dacă aveți nevoie să căutați fișiere pe disc, utilizați [Finder|finder].

Instalare:

```shell
composer require nette/utils
```

Următoarele exemple presupun că a fost creat un alias:

```php
use Nette\Utils\FileSystem;
```


Manipulare
==========


copy(string $origin, string $target, bool $overwrite=true): void .[method]
--------------------------------------------------------------------------

Copiază un fișier sau un întreg director. În mod implicit, suprascrie fișierele și directoarele existente. Dacă parametrul `$overwrite` este setat la `false`, aruncă o excepție `Nette\InvalidStateException` dacă fișierul sau directorul țintă `$target` există. Aruncă o excepție `Nette\IOException` în caz de eroare.

```php
FileSystem::copy('/path/to/source', '/path/to/dest', overwrite: true);
```


createDir(string $dir, int $mode=0777): void .[method]
------------------------------------------------------

Creează un director dacă nu există, inclusiv directoarele părinte. Aruncă o excepție `Nette\IOException` în caz de eroare.

```php
FileSystem::createDir('/path/to/dir');
```


delete(string $path): void .[method]
------------------------------------

Șterge un fișier sau un întreg director, dacă există. Dacă directorul nu este gol, șterge mai întâi conținutul acestuia. Aruncă o excepție `Nette\IOException` în caz de eroare.

```php
FileSystem::delete('/path/to/fileOrDir');
```


makeWritable(string $path, int $dirMode=0777, int $fileMode=0666): void .[method]
---------------------------------------------------------------------------------

Setează permisiunile fișierului la `$fileMode` sau ale directorului la `$dirMode`. Parcurge recursiv și setează permisiunile pentru întregul conținut al directorului.

```php
FileSystem::makeWritable('/path/to/fileOrDir');
```


open(string $path, string $mode): resource .[method]
----------------------------------------------------

Deschide un fișier și returnează resursa. Parametrul `$mode` funcționează la fel ca în funcția nativă [`fopen()` |https://www.php.net/manual/en/function.fopen.php]. Aruncă o excepție `Nette\IOException` în caz de eroare.

```php
$res = FileSystem::open('/path/to/file', 'r');
```


read(string $file): string .[method]
------------------------------------

Returnează conținutul fișierului `$file`. Aruncă o excepție `Nette\IOException` în caz de eroare.

```php
$content = FileSystem::read('/path/to/file');
```


readLines(string $file, bool $stripNewLines=true): \Generator .[method]
-----------------------------------------------------------------------

Citește conținutul fișierului linie cu linie. Spre deosebire de funcția nativă `file()`, nu încarcă întregul fișier în memorie, ci îl citește continuu, permițând citirea fișierelor mai mari decât memoria disponibilă. `$stripNewLines` specifică dacă caracterele de sfârșit de linie `\r` și `\n` trebuie eliminate. Aruncă o excepție `Nette\IOException` în caz de eroare.

```php
$lines = FileSystem::readLines('/path/to/file');

foreach ($lines as $lineNum => $line) {
	echo "Line $lineNum: $line\n";
}
```


rename(string $origin, string $target, bool $overwrite=true): void .[method]
----------------------------------------------------------------------------

Redenumește sau mută fișierul sau directorul `$origin`. În mod implicit, suprascrie fișierele și directoarele existente. Dacă parametrul `$overwrite` este setat la `false`, aruncă o excepție `Nette\InvalidStateException` dacă fișierul sau directorul țintă `$target` există. Aruncă o excepție `Nette\IOException` în caz de eroare.

```php
FileSystem::rename('/path/to/source', '/path/to/dest', overwrite: true);
```


write(string $file, string $content, int $mode=0666): void .[method]
--------------------------------------------------------------------

Scrie șirul `$content` în fișierul `$file`. Aruncă o excepție `Nette\IOException` în caz de eroare.

```php
FileSystem::write('/path/to/file', $content);
```


Căi
===


isAbsolute(string $path): bool .[method]
----------------------------------------

Verifică dacă calea `$path` este absolută.

```php
FileSystem::isAbsolute('../backup'); // false
FileSystem::isAbsolute('/backup');   // true
FileSystem::isAbsolute('C:/backup'); // true
```


joinPaths(string ...$segments): string .[method]
------------------------------------------------
Unește toate segmentele căii și normalizează rezultatul.

```php
FileSystem::joinPaths('a', 'b', 'file.txt'); // 'a/b/file.txt'
FileSystem::joinPaths('/a/', '/b/');         // '/a/b/'
FileSystem::joinPaths('/a/', '/../b');       // '/b'
```


normalizePath(string $path): string .[method]
---------------------------------------------
Normalizează `..` și `.` și separatoarele de directoare din cale la cele specifice sistemului.

```php
FileSystem::normalizePath('/file/.');        // '/file/'
FileSystem::normalizePath('\file\..');       // '/file'
FileSystem::normalizePath('/file/../..');    // '/..'
FileSystem::normalizePath('file/../../bar'); // '/../bar'
```


unixSlashes(string $path): string .[method]
-------------------------------------------

Convertește slash-urile la `/`, utilizate în sistemele Unix.

```php
$path = FileSystem::unixSlashes($path);
```


platformSlashes(string $path): string .[method]
-----------------------------------------------

Convertește slash-urile la caracterele specifice platformei curente, adică `\` în Windows și `/` în alte sisteme.

```php
$path = FileSystem::platformSlashes($path);
```


resolvePath(string $basePath, string $path): string .[method]{data-version:4.0.6}
---------------------------------------------------------------------------------

Derivează calea finală din calea `$path` relativ la directorul de bază `$basePath`. Căile absolute (`/foo`, `C:/foo`) sunt lăsate neschimbate (doar normalizează slash-urile), căile relative sunt anexate la calea de bază.

```php
// Pe Windows, slash-urile din ieșire ar fi inverse (\)
FileSystem::resolvePath('/base/dir', '/abs/path');      // '/abs/path'
FileSystem::resolvePath('/base/dir', 'rel');            // '/base/dir/rel'
FileSystem::resolvePath('base/dir', '../file.txt');     // 'base/file.txt'
FileSystem::resolvePath('base', '');                    // 'base'
```


Acces static vs. non-static
===========================

Pentru a putea înlocui ușor clasa cu alta (mock), de exemplu în scopuri de testare, utilizați-o în mod non-static:

```php
class AnyClassUsingFileSystem
{
	public function __construct(
		private FileSystem $fileSystem,
	) {
	}

	public function readConfig(): string
	{
		return $this->fileSystem->read(/* ... */);
	}

	...
}
```