Skip to content

Commit 39a7515

Browse files
author
Karel Wintersky
committed
0.99.9
- Release candidate
1 parent cd44c54 commit 39a7515

File tree

6 files changed

+284
-77
lines changed

6 files changed

+284
-77
lines changed

‎.gitattributes

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,10 @@ docs export-ignore
1010
.gitignore export-ignore
1111

1212
makefile export-ignore
13+
TODO.md export-ignore
1314

1415
phpunit.xml export-ignore
1516
.php-cs-fixer.php export-ignore
1617

18+
19+

‎README.md

Lines changed: 194 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,203 @@
11
# Arris.Entity.File
22

3-
File Entity type for Arris µFramework.
3+
File Entity type for Arris µFramework. Simple OOP File wrapper.
44

5-
# Todo
5+
Класс `File` предоставляет объектно-ориентированный интерфейс для работы с файлами в PHP.
6+
Он инкапсулирует основные операции с файлами, такие как чтение, запись, перемещение, копирование,
7+
а также предоставляет информацию о файле (размер, MIME-тип, время изменения, etc).
68

7-
## open()
9+
## Константы режимов открытия файла
810

9-
возможно, имеет смысл переписать так, чтобы конструктор никогда не кидал исключение, но для работы с файлом сначала нужно было вызывать
10-
```php
11-
->open()
12-
```
13-
Чтобы именно `open()` создавал все структуры, а конструктор только запоминает имя... и может быть, вызывает open если есть параметр
14-
`force_open = false`. Это даст защиту от исключения в конструкторе.
11+
- `FM_READ` (`'r'`) - только для чтения
12+
- `FM_RW` (`'r+'`) - для чтения и записи
13+
- `FM_WRITE` (`'w+'`) - для записи (создает файл если не существует, обрезает существующий)
14+
- `FM_APPEND` (`'a+'`) - для добавления (создает файл если не существует)
15+
- `FM_CREATE` (`'c+'`) - для записи (создает файл если не существует, не обрезает существующий)
1516

16-
## `OperationState`
17+
## Основные методы
1718

18-
```php
19-
<?php
19+
### `__construct(string $path, bool $force_open = false)`
20+
21+
Конструктор класса.
22+
23+
**Параметры:**
24+
- `$path` - путь к файлу
25+
- `$force_open` - открыть файл сразу после создания объекта
26+
27+
**Исключения:**
28+
- `FileException` - другие ошибки работы с файлом
29+
30+
### `open(string $mode = self::FM_APPEND): self`
31+
32+
Открывает файл, создавая файловый хэндлер.
33+
34+
**Параметры:**
35+
- `$mode` - режим открытия (используйте константы класса)
36+
37+
**Возвращает:**
38+
- `self` - текущий объект для цепочки вызовов
39+
40+
### `getContent(int $position = 0, ?int $length = null): string`
41+
Получить содержимое файла.
42+
43+
**Параметры:**
44+
- `$position` - позиция начала чтения
45+
- `$length` - количество байт для чтения (null - до конца файла)
46+
47+
**Возвращает:**
48+
- `string` - содержимое файла
49+
50+
**Исключения:**
51+
- `FileException` - если не удалось прочитать файл
52+
53+
### `putContent(string $content, int $flag = 0): int`
54+
Записать содержимое в файл.
55+
56+
**Параметры:**
57+
- `$content` - данные для записи
58+
- `$flag` - флаги (например, FILE_APPEND)
59+
60+
**Возвращает:**
61+
- `int` - количество записанных байт
62+
63+
**Исключения:**
64+
- `FileException` - если не удалось записать в файл
65+
66+
### `close(bool $just_in_case = true): self`
67+
Закрывает файловый хэндлер.
68+
69+
**Параметры:**
70+
- `$just_in_case` - если true, не вызывает исключение если файл не открыт
71+
72+
**Возвращает:**
73+
- `self` - текущий объект для цепочки вызовов
74+
75+
**Исключения:**
76+
- `FileException` - если файл не открыт и `$just_in_case = false`
77+
78+
### `delete(bool $just_in_case = true): bool`
79+
Удалить файл.
80+
81+
**Параметры:**
82+
- `$just_in_case` - если true, не вызывает исключение если файл не существует
83+
84+
**Возвращает:**
85+
- `bool` - true в случае успеха
86+
87+
**Исключения:**
88+
- `FileException` - если не удалось удалить файл и `$just_in_case = false`
89+
90+
### `truncate(int $size = 0): bool`
91+
Урезает файл до указанной длины.
92+
93+
**Параметры:**
94+
- `$size` - новый размер файла
95+
96+
**Возвращает:**
97+
- `bool` - true в случае успеха
98+
99+
**Исключения:**
100+
- `FileException` - при ошибках
101+
102+
### `move(string $newPath): bool`
103+
Перемещает файл.
104+
105+
**Параметры:**
106+
- `$newPath` - новый путь
107+
108+
**Возвращает:**
109+
- `bool` - true в случае успеха
110+
111+
**Исключения:**
112+
- `FileException` - при ошибках
113+
114+
### `copy(string $targetPath): self`
115+
Копирует файл.
116+
117+
**Параметры:**
118+
- `$targetPath` - путь назначения
119+
120+
**Возвращает:**
121+
- `self` - новый объект File для скопированного файла
122+
123+
**Исключения:**
124+
- `FileException` - если не удалось скопировать
125+
126+
## Методы получения информации о файле
127+
128+
### `getExtension(): string`
129+
Получить расширение файла (без точки).
130+
131+
### `getFilename(): string`
132+
Получить имя файла (без пути).
133+
134+
### `getFilenameWithoutExtension(): string`
135+
Получить имя файла без расширения.
136+
137+
### `getDirectory(): string`
138+
Получить путь к директории файла.
139+
140+
### `getSize(): int`
141+
Получить размер файла в байтах.
142+
143+
### `getLength(): int`
144+
Алиас для `getSize()`.
145+
146+
### `getMimeType(): string`
147+
Получить MIME-тип файла.
148+
149+
### `getLastModifiedTime(): int`
150+
Получить время последнего изменения файла (timestamp).
151+
152+
### `getHash(string $algorithm = 'sha256'): string`
153+
Получить хэш файла.
154+
155+
### `getPath(): string`
156+
Получить путь к файлу.
157+
158+
### `getFileOwner(): array`
159+
Возвращает UID и GID владельца файла.
160+
161+
## Методы проверки
162+
163+
### `isReadable(): bool`
164+
Проверить, является ли файл читаемым.
165+
166+
### `isWritable(): bool`
167+
Проверить, является ли файл записываемым.
168+
169+
### `isExecutable(): bool`
170+
Проверить, является ли файл исполняемым.
171+
172+
### `isLink(): bool`
173+
Проверить, является ли файл символической ссылкой.
174+
175+
### `isImage(): bool`
176+
Проверить, является ли файл изображением.
177+
178+
### `isVideo(): bool`
179+
Проверить, является ли файл видео.
180+
181+
### `exists(): bool`
182+
Проверить существование файла.
183+
184+
## Статические методы
185+
186+
### `create(string $path, string $content = ''): self`
187+
Создать новый файл.
188+
189+
### `createTemp(string $prefix = '', string $content = ''): self`
190+
Создает новый временный файл.
191+
192+
### `match(string $pattern, string $test, int $flags): bool`
193+
Проверяет, совпадает ли строка с шаблоном (использует fnmatch).
194+
195+
## Вспомогательные методы
196+
197+
### `writeFromPosition(string $content, int $position): int`
198+
Записывает данные в файл с указанной позиции.
199+
200+
### `readFromPosition(int $position = 0, ?int $length = null): string`
201+
Читает данные из файла с указанной позиции.
20202

21-
namespace Arris\Entity\File;
22203

23-
class OperationState
24-
{
25-
public bool $success;
26-
public ?string $operation;
27-
public int $bytes_processed;
28-
public ?int $position;
29-
public ?string $error;
30-
}
31-
```

‎TODO.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Todo
2+
3+
## open()
4+
5+
возможно, имеет смысл переписать так, чтобы конструктор никогда не кидал исключение, но для работы с файлом сначала нужно было вызывать
6+
```php
7+
->open()
8+
```
9+
Чтобы именно `open()` создавал все структуры, а конструктор только запоминает имя... и может быть, вызывает open если есть параметр
10+
`force_open = false`. Это даст защиту от исключения в конструкторе.
11+
12+
## `OperationState`
13+
14+
```php
15+
<?php
16+
17+
namespace Arris\Entity\File;
18+
19+
class OperationState
20+
{
21+
public bool $success;
22+
public ?string $operation;
23+
public int $bytes_processed;
24+
public ?int $position;
25+
public ?string $error;
26+
}
27+
28+
/**
29+
* Сбрасывает состояние операций
30+
*/
31+
private function resetState(): void
32+
{
33+
$this->lastOperationState = new OperationState();
34+
$this->lastOperationState->success = false;
35+
$this->lastOperationState->operation = null;
36+
$this->lastOperationState->bytes_processed = 0;
37+
$this->lastOperationState->position = null;
38+
$this->lastOperationState->error = null;
39+
}
40+
```

‎sources/Exceptions/FileException.php

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<?php
2+
3+
namespace Arris\Entity\Exceptions;
4+
5+
class FileException extends \Exception
6+
{
7+
public static function create($message = __CLASS__, $args = [], $code = 0): static
8+
{
9+
return new static(vsprintf($message, $args), $code);
10+
}
11+
12+
}

0 commit comments

Comments
 (0)