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 2005-2012, Cake Software Foundation, Inc. (http://cakefoundation.org)
9: *
10: * Licensed under The MIT License
11: * Redistributions of files must retain the above copyright notice.
12: *
13: * @copyright Copyright 2005-2012, Cake Software Foundation, Inc. (http://cakefoundation.org)
14: * @link http://cakephp.org CakePHP(tm) Project
15: * @package Cake.Utility
16: * @since CakePHP(tm) v 0.2.9
17: * @license MIT License (http://www.opensource.org/licenses/mit-license.php)
18: */
19:
20: App::uses('Folder', 'Utility');
21:
22: /**
23: * Convenience class for reading, writing and appending to files.
24: *
25: * @package Cake.Utility
26: */
27: class File {
28:
29: /**
30: * Folder object of the File
31: *
32: * @var Folder
33: * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::$Folder
34: */
35: public $Folder = null;
36:
37: /**
38: * Filename
39: *
40: * @var string
41: * http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::$name
42: */
43: public $name = null;
44:
45: /**
46: * File info
47: *
48: * @var array
49: * http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::$info
50: */
51: public $info = array();
52:
53: /**
54: * Holds the file handler resource if the file is opened
55: *
56: * @var resource
57: * http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::$handle
58: */
59: public $handle = null;
60:
61: /**
62: * Enable locking for file reading and writing
63: *
64: * @var boolean
65: * http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::$lock
66: */
67: public $lock = null;
68:
69: /**
70: * Path property
71: *
72: * Current file's absolute path
73: *
74: * @var mixed null
75: * http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::$path
76: */
77: public $path = null;
78:
79: /**
80: * Constructor
81: *
82: * @param string $path Path to file
83: * @param boolean $create Create file if it does not exist (if true)
84: * @param integer $mode Mode to apply to the folder holding the file
85: * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File
86: */
87: public function __construct($path, $create = false, $mode = 0755) {
88: $this->Folder = new Folder(dirname($path), $create, $mode);
89: if (!is_dir($path)) {
90: $this->name = basename($path);
91: }
92: $this->pwd();
93: $create && !$this->exists() && $this->safe($path) && $this->create();
94: }
95:
96: /**
97: * Closes the current file if it is opened
98: *
99: */
100: public function __destruct() {
101: $this->close();
102: }
103:
104: /**
105: * Creates the File.
106: *
107: * @return boolean Success
108: * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::create
109: */
110: public function create() {
111: $dir = $this->Folder->pwd();
112: if (is_dir($dir) && is_writable($dir) && !$this->exists()) {
113: if (touch($this->path)) {
114: return true;
115: }
116: }
117: return false;
118: }
119:
120: /**
121: * Opens the current file with a given $mode
122: *
123: * @param string $mode A valid 'fopen' mode string (r|w|a ...)
124: * @param boolean $force If true then the file will be re-opened even if its already opened, otherwise it won't
125: * @return boolean True on success, false on failure
126: * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::open
127: */
128: public function open($mode = 'r', $force = false) {
129: if (!$force && is_resource($this->handle)) {
130: return true;
131: }
132: clearstatcache();
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: clearstatcache();
281: if (is_resource($this->handle)) {
282: fclose($this->handle);
283: $this->handle = null;
284: }
285: if ($this->exists()) {
286: return unlink($this->path);
287: }
288: return false;
289: }
290:
291: /**
292: * Returns the File info as an array with the following keys:
293: *
294: * - dirname
295: * - basename
296: * - extension
297: * - filename
298: * - filesize
299: * - mime
300: *
301: * @return array File information.
302: * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::info
303: */
304: public function info() {
305: if ($this->info == null) {
306: $this->info = pathinfo($this->path);
307: }
308: if (!isset($this->info['filename'])) {
309: $this->info['filename'] = $this->name();
310: }
311: if (!isset($this->info['filesize'])) {
312: $this->info['filesize'] = $this->size();
313: }
314: if (!isset($this->info['mime'])) {
315: $this->info['mime'] = $this->mime();
316: }
317: return $this->info;
318: }
319:
320: /**
321: * Returns the File extension.
322: *
323: * @return string The File extension
324: * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::ext
325: */
326: public function ext() {
327: if ($this->info == null) {
328: $this->info();
329: }
330: if (isset($this->info['extension'])) {
331: return $this->info['extension'];
332: }
333: return false;
334: }
335:
336: /**
337: * Returns the File name without extension.
338: *
339: * @return string The File name without extension.
340: * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::name
341: */
342: public function name() {
343: if ($this->info == null) {
344: $this->info();
345: }
346: if (isset($this->info['extension'])) {
347: return basename($this->name, '.' . $this->info['extension']);
348: } elseif ($this->name) {
349: return $this->name;
350: }
351: return false;
352: }
353:
354: /**
355: * makes filename safe for saving
356: *
357: * @param string $name The name of the file to make safe if different from $this->name
358: * @param string $ext The name of the extension to make safe if different from $this->ext
359: * @return string $ext the extension of the file
360: * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::safe
361: */
362: public function safe($name = null, $ext = null) {
363: if (!$name) {
364: $name = $this->name;
365: }
366: if (!$ext) {
367: $ext = $this->ext();
368: }
369: return preg_replace("/(?:[^\w\.-]+)/", "_", basename($name, $ext));
370: }
371:
372: /**
373: * Get md5 Checksum of file with previous check of Filesize
374: *
375: * @param integer|boolean $maxsize in MB or true to force
376: * @return string md5 Checksum {@link http://php.net/md5_file See md5_file()}
377: * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::md5
378: */
379: public function md5($maxsize = 5) {
380: if ($maxsize === true) {
381: return md5_file($this->path);
382: }
383:
384: $size = $this->size();
385: if ($size && $size < ($maxsize * 1024) * 1024) {
386: return md5_file($this->path);
387: }
388:
389: return false;
390: }
391:
392: /**
393: * Returns the full path of the File.
394: *
395: * @return string Full path to file
396: * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::pwd
397: */
398: public function pwd() {
399: if (is_null($this->path)) {
400: $this->path = $this->Folder->slashTerm($this->Folder->pwd()) . $this->name;
401: }
402: return $this->path;
403: }
404:
405: /**
406: * Returns true if the File exists.
407: *
408: * @return boolean true if it exists, false otherwise
409: * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::exists
410: */
411: public function exists() {
412: return (file_exists($this->path) && is_file($this->path));
413: }
414:
415: /**
416: * Returns the "chmod" (permissions) of the File.
417: *
418: * @return string Permissions for the file
419: * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::perms
420: */
421: public function perms() {
422: if ($this->exists()) {
423: return substr(sprintf('%o', fileperms($this->path)), -4);
424: }
425: return false;
426: }
427:
428: /**
429: * Returns the Filesize
430: *
431: * @return integer size of the file in bytes, or false in case of an error
432: * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::size
433: */
434: public function size() {
435: if ($this->exists()) {
436: return filesize($this->path);
437: }
438: return false;
439: }
440:
441: /**
442: * Returns true if the File is writable.
443: *
444: * @return boolean true if its writable, false otherwise
445: * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::writable
446: */
447: public function writable() {
448: return is_writable($this->path);
449: }
450:
451: /**
452: * Returns true if the File is executable.
453: *
454: * @return boolean true if its executable, false otherwise
455: * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::executable
456: */
457: public function executable() {
458: return is_executable($this->path);
459: }
460:
461: /**
462: * Returns true if the File is readable.
463: *
464: * @return boolean true if file is readable, false otherwise
465: * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::readable
466: */
467: public function readable() {
468: return is_readable($this->path);
469: }
470:
471: /**
472: * Returns the File's owner.
473: *
474: * @return integer the Fileowner
475: * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::owner
476: */
477: public function owner() {
478: if ($this->exists()) {
479: return fileowner($this->path);
480: }
481: return false;
482: }
483:
484: /**
485: * Returns the File's group.
486: *
487: * @return integer the Filegroup
488: * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::group
489: */
490: public function group() {
491: if ($this->exists()) {
492: return filegroup($this->path);
493: }
494: return false;
495: }
496:
497: /**
498: * Returns last access time.
499: *
500: * @return integer timestamp Timestamp of last access time
501: * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::lastAccess
502: */
503: public function lastAccess() {
504: if ($this->exists()) {
505: return fileatime($this->path);
506: }
507: return false;
508: }
509:
510: /**
511: * Returns last modified time.
512: *
513: * @return integer timestamp Timestamp of last modification
514: * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::lastChange
515: */
516: public function lastChange() {
517: if ($this->exists()) {
518: return filemtime($this->path);
519: }
520: return false;
521: }
522:
523: /**
524: * Returns the current folder.
525: *
526: * @return Folder Current folder
527: * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::Folder
528: */
529: public function &folder() {
530: return $this->Folder;
531: }
532:
533: /**
534: * Copy the File to $dest
535: *
536: * @param string $dest destination for the copy
537: * @param boolean $overwrite Overwrite $dest if exists
538: * @return boolean Success
539: * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::copy
540: */
541: public function copy($dest, $overwrite = true) {
542: if (!$this->exists() || is_file($dest) && !$overwrite) {
543: return false;
544: }
545: return copy($this->path, $dest);
546: }
547:
548: /**
549: * Get the mime type of the file. Uses the finfo extension if
550: * its available, otherwise falls back to mime_content_type
551: *
552: * @return false|string The mimetype of the file, or false if reading fails.
553: */
554: public function mime() {
555: if (!$this->exists()) {
556: return false;
557: }
558: if (function_exists('finfo_open')) {
559: $finfo = finfo_open(FILEINFO_MIME);
560: list($type, $charset) = explode(';', finfo_file($finfo, $this->pwd()));
561: return $type;
562: } elseif (function_exists('mime_content_type')) {
563: return mime_content_type($this->pwd());
564: }
565: return false;
566: }
567:
568: }
569: