1: <?php
2: /**
3: * CakePHP(tm) : Rapid Development Framework (https://cakephp.org)
4: * Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
5: *
6: * Licensed under The MIT License
7: * For full copyright and license information, please see the LICENSE.txt
8: * Redistributions of files must retain the above copyright notice.
9: *
10: * @copyright Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
11: * @link https://cakephp.org CakePHP(tm) Project
12: * @since 0.2.9
13: * @license https://opensource.org/licenses/mit-license.php MIT License
14: */
15: namespace Cake\Filesystem;
16:
17: use finfo;
18: use SplFileInfo;
19:
20: /**
21: * Convenience class for reading, writing and appending to files.
22: */
23: class File
24: {
25: /**
26: * Folder object of the file
27: *
28: * @var \Cake\Filesystem\Folder
29: * @link https://book.cakephp.org/3.0/en/core-libraries/file-folder.html
30: */
31: public $Folder;
32:
33: /**
34: * File name
35: *
36: * @var string
37: * https://book.cakephp.org/3.0/en/core-libraries/file-folder.html#Cake\Filesystem\File::$name
38: */
39: public $name;
40:
41: /**
42: * File info
43: *
44: * @var array
45: * https://book.cakephp.org/3.0/en/core-libraries/file-folder.html#Cake\Filesystem\File::$info
46: */
47: public $info = [];
48:
49: /**
50: * Holds the file handler resource if the file is opened
51: *
52: * @var resource|null
53: * https://book.cakephp.org/3.0/en/core-libraries/file-folder.html#Cake\Filesystem\File::$handle
54: */
55: public $handle;
56:
57: /**
58: * Enable locking for file reading and writing
59: *
60: * @var bool|null
61: * https://book.cakephp.org/3.0/en/core-libraries/file-folder.html#Cake\Filesystem\File::$lock
62: */
63: public $lock;
64:
65: /**
66: * Path property
67: *
68: * Current file's absolute path
69: *
70: * @var string|null
71: * https://book.cakephp.org/3.0/en/core-libraries/file-folder.html#Cake\Filesystem\File::$path
72: */
73: public $path;
74:
75: /**
76: * Constructor
77: *
78: * @param string $path Path to file
79: * @param bool $create Create file if it does not exist (if true)
80: * @param int $mode Mode to apply to the folder holding the file
81: * @link https://book.cakephp.org/3.0/en/core-libraries/file-folder.html#file-api
82: */
83: public function __construct($path, $create = false, $mode = 0755)
84: {
85: $splInfo = new SplFileInfo($path);
86: $this->Folder = new Folder($splInfo->getPath(), $create, $mode);
87: if (!is_dir($path)) {
88: $this->name = ltrim($splInfo->getFilename(), '/\\');
89: }
90: $this->pwd();
91: $create && !$this->exists() && $this->safe($path) && $this->create();
92: }
93:
94: /**
95: * Closes the current file if it is opened
96: */
97: public function __destruct()
98: {
99: $this->close();
100: }
101:
102: /**
103: * Creates the file.
104: *
105: * @return bool Success
106: */
107: public function create()
108: {
109: $dir = $this->Folder->pwd();
110:
111: if (is_dir($dir) && is_writable($dir) && !$this->exists() && touch($this->path)) {
112: return true;
113: }
114:
115: return false;
116: }
117:
118: /**
119: * Opens the current file with a given $mode
120: *
121: * @param string $mode A valid 'fopen' mode string (r|w|a ...)
122: * @param bool $force If true then the file will be re-opened even if its already opened, otherwise it won't
123: * @return bool True on success, false on failure
124: */
125: public function open($mode = 'r', $force = false)
126: {
127: if (!$force && is_resource($this->handle)) {
128: return true;
129: }
130: if ($this->exists() === false && $this->create() === false) {
131: return false;
132: }
133:
134: $this->handle = fopen($this->path, $mode);
135:
136: return is_resource($this->handle);
137: }
138:
139: /**
140: * Return the contents of this file as a string.
141: *
142: * @param string|bool $bytes where to start
143: * @param string $mode A `fread` compatible mode.
144: * @param bool $force If true then the file will be re-opened even if its already opened, otherwise it won't
145: * @return string|false string on success, false on failure
146: */
147: public function read($bytes = false, $mode = 'rb', $force = false)
148: {
149: if ($bytes === false && $this->lock === null) {
150: return file_get_contents($this->path);
151: }
152: if ($this->open($mode, $force) === false) {
153: return false;
154: }
155: if ($this->lock !== null && flock($this->handle, LOCK_SH) === false) {
156: return false;
157: }
158: if (is_int($bytes)) {
159: return fread($this->handle, $bytes);
160: }
161:
162: $data = '';
163: while (!feof($this->handle)) {
164: $data .= fgets($this->handle, 4096);
165: }
166:
167: if ($this->lock !== null) {
168: flock($this->handle, LOCK_UN);
169: }
170: if ($bytes === false) {
171: $this->close();
172: }
173:
174: return trim($data);
175: }
176:
177: /**
178: * Sets or gets the offset for the currently opened file.
179: *
180: * @param int|bool $offset The $offset in bytes to seek. If set to false then the current offset is returned.
181: * @param int $seek PHP Constant SEEK_SET | SEEK_CUR | SEEK_END determining what the $offset is relative to
182: * @return int|bool True on success, false on failure (set mode), false on failure or integer offset on success (get mode)
183: */
184: public function offset($offset = false, $seek = SEEK_SET)
185: {
186: if ($offset === false) {
187: if (is_resource($this->handle)) {
188: return ftell($this->handle);
189: }
190: } elseif ($this->open() === true) {
191: return fseek($this->handle, $offset, $seek) === 0;
192: }
193:
194: return false;
195: }
196:
197: /**
198: * Prepares an ASCII string for writing. Converts line endings to the
199: * correct terminator for the current platform. If Windows, "\r\n" will be used,
200: * all other platforms will use "\n"
201: *
202: * @param string $data Data to prepare for writing.
203: * @param bool $forceWindows If true forces Windows new line string.
204: * @return string The with converted line endings.
205: */
206: public static function prepare($data, $forceWindows = false)
207: {
208: $lineBreak = "\n";
209: if (DIRECTORY_SEPARATOR === '\\' || $forceWindows === true) {
210: $lineBreak = "\r\n";
211: }
212:
213: return strtr($data, ["\r\n" => $lineBreak, "\n" => $lineBreak, "\r" => $lineBreak]);
214: }
215:
216: /**
217: * Write given data to this file.
218: *
219: * @param string $data Data to write to this File.
220: * @param string $mode Mode of writing. {@link https://secure.php.net/fwrite See fwrite()}.
221: * @param bool $force Force the file to open
222: * @return bool Success
223: */
224: public function write($data, $mode = 'w', $force = false)
225: {
226: $success = false;
227: if ($this->open($mode, $force) === true) {
228: if ($this->lock !== null && flock($this->handle, LOCK_EX) === false) {
229: return false;
230: }
231:
232: if (fwrite($this->handle, $data) !== false) {
233: $success = true;
234: }
235: if ($this->lock !== null) {
236: flock($this->handle, LOCK_UN);
237: }
238: }
239:
240: return $success;
241: }
242:
243: /**
244: * Append given data string to this file.
245: *
246: * @param string $data Data to write
247: * @param bool $force Force the file to open
248: * @return bool Success
249: */
250: public function append($data, $force = false)
251: {
252: return $this->write($data, 'a', $force);
253: }
254:
255: /**
256: * Closes the current file if it is opened.
257: *
258: * @return bool True if closing was successful or file was already closed, otherwise false
259: */
260: public function close()
261: {
262: if (!is_resource($this->handle)) {
263: return true;
264: }
265:
266: return fclose($this->handle);
267: }
268:
269: /**
270: * Deletes the file.
271: *
272: * @return bool Success
273: */
274: public function delete()
275: {
276: if (is_resource($this->handle)) {
277: fclose($this->handle);
278: $this->handle = null;
279: }
280: if ($this->exists()) {
281: return unlink($this->path);
282: }
283:
284: return false;
285: }
286:
287: /**
288: * Returns the file info as an array with the following keys:
289: *
290: * - dirname
291: * - basename
292: * - extension
293: * - filename
294: * - filesize
295: * - mime
296: *
297: * @return array File information.
298: */
299: public function info()
300: {
301: if (!$this->info) {
302: $this->info = pathinfo($this->path);
303: }
304: if (!isset($this->info['filename'])) {
305: $this->info['filename'] = $this->name();
306: }
307: if (!isset($this->info['filesize'])) {
308: $this->info['filesize'] = $this->size();
309: }
310: if (!isset($this->info['mime'])) {
311: $this->info['mime'] = $this->mime();
312: }
313:
314: return $this->info;
315: }
316:
317: /**
318: * Returns the file extension.
319: *
320: * @return string|false The file extension, false if extension cannot be extracted.
321: */
322: public function ext()
323: {
324: if (!$this->info) {
325: $this->info();
326: }
327: if (isset($this->info['extension'])) {
328: return $this->info['extension'];
329: }
330:
331: return false;
332: }
333:
334: /**
335: * Returns the file name without extension.
336: *
337: * @return string|false The file name without extension, false if name cannot be extracted.
338: */
339: public function name()
340: {
341: if (!$this->info) {
342: $this->info();
343: }
344: if (isset($this->info['extension'])) {
345: return static::_basename($this->name, '.' . $this->info['extension']);
346: }
347: if ($this->name) {
348: return $this->name;
349: }
350:
351: return false;
352: }
353:
354: /**
355: * Returns the file basename. simulate the php basename() for multibyte (mb_basename).
356: *
357: * @param string $path Path to file
358: * @param string|null $ext The name of the extension
359: * @return string the file basename.
360: */
361: protected static function _basename($path, $ext = null)
362: {
363: // check for multibyte string and use basename() if not found
364: if (mb_strlen($path) === strlen($path)) {
365: return ($ext === null) ? basename($path) : basename($path, $ext);
366: }
367:
368: $splInfo = new SplFileInfo($path);
369: $name = ltrim($splInfo->getFilename(), '/\\');
370:
371: if ($ext === null || $ext === '') {
372: return $name;
373: }
374: $ext = preg_quote($ext);
375: $new = preg_replace("/({$ext})$/u", "", $name);
376:
377: // basename of '/etc/.d' is '.d' not ''
378: return ($new === '') ? $name : $new;
379: }
380:
381: /**
382: * Makes file name safe for saving
383: *
384: * @param string|null $name The name of the file to make safe if different from $this->name
385: * @param string|null $ext The name of the extension to make safe if different from $this->ext
386: * @return string The extension of the file
387: */
388: public function safe($name = null, $ext = null)
389: {
390: if (!$name) {
391: $name = $this->name;
392: }
393: if (!$ext) {
394: $ext = $this->ext();
395: }
396:
397: return preg_replace("/(?:[^\w\.-]+)/", '_', static::_basename($name, $ext));
398: }
399:
400: /**
401: * Get md5 Checksum of file with previous check of Filesize
402: *
403: * @param int|bool $maxsize in MB or true to force
404: * @return string|false md5 Checksum {@link https://secure.php.net/md5_file See md5_file()}, or false in case of an error
405: */
406: public function md5($maxsize = 5)
407: {
408: if ($maxsize === true) {
409: return md5_file($this->path);
410: }
411:
412: $size = $this->size();
413: if ($size && $size < ($maxsize * 1024) * 1024) {
414: return md5_file($this->path);
415: }
416:
417: return false;
418: }
419:
420: /**
421: * Returns the full path of the file.
422: *
423: * @return string Full path to the file
424: */
425: public function pwd()
426: {
427: if ($this->path === null) {
428: $dir = $this->Folder->pwd();
429: if (is_dir($dir)) {
430: $this->path = $this->Folder->slashTerm($dir) . $this->name;
431: }
432: }
433:
434: return $this->path;
435: }
436:
437: /**
438: * Returns true if the file exists.
439: *
440: * @return bool True if it exists, false otherwise
441: */
442: public function exists()
443: {
444: $this->clearStatCache();
445:
446: return (file_exists($this->path) && is_file($this->path));
447: }
448:
449: /**
450: * Returns the "chmod" (permissions) of the file.
451: *
452: * @return string|false Permissions for the file, or false in case of an error
453: */
454: public function perms()
455: {
456: if ($this->exists()) {
457: return substr(sprintf('%o', fileperms($this->path)), -4);
458: }
459:
460: return false;
461: }
462:
463: /**
464: * Returns the file size
465: *
466: * @return int|false Size of the file in bytes, or false in case of an error
467: */
468: public function size()
469: {
470: if ($this->exists()) {
471: return filesize($this->path);
472: }
473:
474: return false;
475: }
476:
477: /**
478: * Returns true if the file is writable.
479: *
480: * @return bool True if it's writable, false otherwise
481: */
482: public function writable()
483: {
484: return is_writable($this->path);
485: }
486:
487: /**
488: * Returns true if the File is executable.
489: *
490: * @return bool True if it's executable, false otherwise
491: */
492: public function executable()
493: {
494: return is_executable($this->path);
495: }
496:
497: /**
498: * Returns true if the file is readable.
499: *
500: * @return bool True if file is readable, false otherwise
501: */
502: public function readable()
503: {
504: return is_readable($this->path);
505: }
506:
507: /**
508: * Returns the file's owner.
509: *
510: * @return int|false The file owner, or false in case of an error
511: */
512: public function owner()
513: {
514: if ($this->exists()) {
515: return fileowner($this->path);
516: }
517:
518: return false;
519: }
520:
521: /**
522: * Returns the file's group.
523: *
524: * @return int|false The file group, or false in case of an error
525: */
526: public function group()
527: {
528: if ($this->exists()) {
529: return filegroup($this->path);
530: }
531:
532: return false;
533: }
534:
535: /**
536: * Returns last access time.
537: *
538: * @return int|false Timestamp of last access time, or false in case of an error
539: */
540: public function lastAccess()
541: {
542: if ($this->exists()) {
543: return fileatime($this->path);
544: }
545:
546: return false;
547: }
548:
549: /**
550: * Returns last modified time.
551: *
552: * @return int|false Timestamp of last modification, or false in case of an error
553: */
554: public function lastChange()
555: {
556: if ($this->exists()) {
557: return filemtime($this->path);
558: }
559:
560: return false;
561: }
562:
563: /**
564: * Returns the current folder.
565: *
566: * @return \Cake\Filesystem\Folder Current folder
567: */
568: public function folder()
569: {
570: return $this->Folder;
571: }
572:
573: /**
574: * Copy the File to $dest
575: *
576: * @param string $dest Absolute path to copy the file to.
577: * @param bool $overwrite Overwrite $dest if exists
578: * @return bool Success
579: */
580: public function copy($dest, $overwrite = true)
581: {
582: if (!$this->exists() || is_file($dest) && !$overwrite) {
583: return false;
584: }
585:
586: return copy($this->path, $dest);
587: }
588:
589: /**
590: * Gets the mime type of the file. Uses the finfo extension if
591: * it's available, otherwise falls back to mime_content_type().
592: *
593: * @return string|false The mimetype of the file, or false if reading fails.
594: */
595: public function mime()
596: {
597: if (!$this->exists()) {
598: return false;
599: }
600: if (class_exists('finfo')) {
601: $finfo = new finfo(FILEINFO_MIME);
602: $type = $finfo->file($this->pwd());
603: if (!$type) {
604: return false;
605: }
606: list($type) = explode(';', $type);
607:
608: return $type;
609: }
610: if (function_exists('mime_content_type')) {
611: return mime_content_type($this->pwd());
612: }
613:
614: return false;
615: }
616:
617: /**
618: * Clear PHP's internal stat cache
619: *
620: * @param bool $all Clear all cache or not. Passing false will clear
621: * the stat cache for the current path only.
622: * @return void
623: */
624: public function clearStatCache($all = false)
625: {
626: if ($all === false) {
627: clearstatcache(true, $this->path);
628: }
629:
630: clearstatcache();
631: }
632:
633: /**
634: * Searches for a given text and replaces the text if found.
635: *
636: * @param string|array $search Text(s) to search for.
637: * @param string|array $replace Text(s) to replace with.
638: * @return bool Success
639: */
640: public function replaceText($search, $replace)
641: {
642: if (!$this->open('r+')) {
643: return false;
644: }
645:
646: if ($this->lock !== null && flock($this->handle, LOCK_EX) === false) {
647: return false;
648: }
649:
650: $replaced = $this->write(str_replace($search, $replace, $this->read()), 'w', true);
651:
652: if ($this->lock !== null) {
653: flock($this->handle, LOCK_UN);
654: }
655: $this->close();
656:
657: return $replaced;
658: }
659: }
660: