Nette Documentation Preview

syntax
Funcțiile sistemului de fișiere
*******************************

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


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

Instalare:

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

Următoarele exemple presupun că este definit următorul alias de clasă:

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


Manipulare .[#toc-manipulation]
===============================


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

Copiază un fișier sau un întreg director. Suprascrie în mod implicit fișierele și directoarele existente. Dacă `$overwrite` este setat la `false` și există deja un `$target`, se aruncă o excepție `Nette\InvalidStateException`. Lansează o excepție `Nette\IOException` în cazul în care apare o eroare.

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


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

Creează un director dacă acesta nu există, inclusiv directoarele părinte. Lansează o excepție `Nette\IOException` în cazul în care apare o eroare.

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


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

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

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


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

Stabilește permisiunile fișierelor la `$fileMode` sau permisiunile directoarelor la `$dirMode`. Traversează și stabilește în mod recursiv permisiunile pentru întregul conținut al directorului.

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


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

Deschide fișierul și returnează resursa. Parametrul `$mode` funcționează la fel ca funcția nativă `fopen()`:https://www.php.net/manual/en/function.fopen.php. În cazul în care apare o eroare, se ridică excepția `Nette\IOException`.

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


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

Citește conținutul unui fișier `$file`. Aruncă o excepție `Nette\IOException` în cazul în care apare o 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()`, aceasta nu citește întregul fișier în memorie, ci îl citește continuu, astfel încât să poată fi citite fișiere mai mari decât memoria disponibilă. `$stripNewLines` specifică dacă se elimină sau nu caracterele de întrerupere a liniei `\r` și `\n`.
În caz de eroare, se ridică o excepție `Nette\IOException`.

```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ă un fișier sau un director specificat de `$origin` în `$target`. Suprascrie în mod implicit fișierele și directoarele existente. Dacă `$overwrite` este setat la `false` și `$target` există deja, se aruncă o excepție `Nette\InvalidStateException`. Lansează o excepție `Nette\IOException` în cazul în care apare o eroare.

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


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

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

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


Căi de acces .[#toc-paths]
==========================


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

Determină dacă `$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 traseului ș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 separatorii de directoare din calea de acces.

```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 în `/` utilizate pe sistemele Unix.

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


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

Convertește slash-urile în caractere specifice platformei curente, de exemplu `\` pe Windows și `/` în alte sisteme.

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


Abordare statică vs. non-statică .[#toc-static-vs-non-static-approach]
======================================================================

Pentru a înlocui cu ușurință clasa `FileSystem` cu o altă clasă, 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(/* ... */);
	}

	...
}
```

Funcțiile sistemului de fișiere

Nette\Utils\FileSystem este o clasă care conține funcții utile pentru lucrul cu un sistem de fișiere. Un avantaj față de funcțiile native PHP este că acestea aruncă excepții în caz de erori.

Dacă trebuie să căutați fișiere pe disc, utilizați Finder.

Instalare:

composer require nette/utils

Următoarele exemple presupun că este definit următorul alias de clasă:

use Nette\Utils\FileSystem;

Manipulare

copy(string $origin, string $target, bool $overwrite=true)void

Copiază un fișier sau un întreg director. Suprascrie în mod implicit fișierele și directoarele existente. Dacă $overwrite este setat la false și există deja un $target, se aruncă o excepție Nette\InvalidStateException. Lansează o excepție Nette\IOException în cazul în care apare o eroare.

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

createDir(string $directory, int $mode=0777)void

Creează un director dacă acesta nu există, inclusiv directoarele părinte. Lansează o excepție Nette\IOException în cazul în care apare o eroare.

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

delete(string $path): void

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

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

makeWritable(string $path, int $dirMode=0777, int $fileMode=0666)void

Stabilește permisiunile fișierelor la $fileMode sau permisiunile directoarelor la $dirMode. Traversează și stabilește în mod recursiv permisiunile pentru întregul conținut al directorului.

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

open(string $path, string $mode): resource

Deschide fișierul și returnează resursa. Parametrul $mode funcționează la fel ca funcția nativă fopen(). În cazul în care apare o eroare, se ridică excepția Nette\IOException.

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

read(string $file): string

Citește conținutul unui fișier $file. Aruncă o excepție Nette\IOException în cazul în care apare o eroare.

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

readLines(string $file, bool $stripNewLines=true): \Generator

Citește conținutul fișierului linie cu linie. Spre deosebire de funcția nativă file(), aceasta nu citește întregul fișier în memorie, ci îl citește continuu, astfel încât să poată fi citite fișiere mai mari decât memoria disponibilă. $stripNewLines specifică dacă se elimină sau nu caracterele de întrerupere a liniei \r și \n. În caz de eroare, se ridică o excepție Nette\IOException.

$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

Redenumește sau mută un fișier sau un director specificat de $origin în $target. Suprascrie în mod implicit fișierele și directoarele existente. Dacă $overwrite este setat la false și $target există deja, se aruncă o excepție Nette\InvalidStateException. Lansează o excepție Nette\IOException în cazul în care apare o eroare.

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

write(string $file, string $content, int $mode=0666)void

Scrie $content pe un fișier $file. Aruncă o excepție Nette\IOException în caz de eroare.

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

Căi de acces

isAbsolute(string $path)bool

Determină dacă $path este absolut.

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

joinPaths(string …$segments)string

Unește toate segmentele traseului și normalizează rezultatul.

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

Normalizează .. și . și separatorii de directoare din calea de acces.

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

unixSlashes(string $path)string

Convertește slash-urile în / utilizate pe sistemele Unix.

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

platformSlashes(string $path)string

Convertește slash-urile în caractere specifice platformei curente, de exemplu \ pe Windows și / în alte sisteme.

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

Abordare statică vs. non-statică

Pentru a înlocui cu ușurință clasa FileSystem cu o altă clasă, de exemplu în scopuri de testare, utilizați-o în mod non-static:

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


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

	...
}