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