waFiles

waFiles

Contents...

Methods

  • convert

    Converts a text file to another charset.

  • copy

    Copies a file or directory contents.

  • create

    Creates a directory or parent directory for a file.

  • delete

    Deletes a file or a directory.

  • extension

    Returns file name extension.

  • formatSize

    Returns formatted file size value.

  • getMimeType

    Determines the MIME type of a file by its name.

  • listdir

    Returns the list of files and subdirectories in the specified directory.

  • move

    Moves a file or a directory to the specified parent directory.

  • readFile

    Reads file contents and outputs it to the browser.

  • upload

    Uploads a file from the specified URL to a server directory.

  • write

    Writes data to a file.

public static function convert ($file, $from, $to = 'UTF-8', $target = null)

Converts a text file to another charset.

Parameters

  • $file

    File path.

  • $from

    Source charset.

  • $to

    Required charset.

  • $target

    Optional path to save converted file at. If no path is specified, then the converted file is created in the same directory, with an underscore and the target charset specified in $to parameter appended to the file name.

Returned value

Value of $target parameter specified for method call, or automatically generated path to converted file.

Example

$target_path = waFiles::convert($file_path, 'CP1251');

public static function copy ($source_path, $target_path, $skip_pattern = null)

Copies a file or directory contents.

Parameters

  • $source_path

    Path to the original file or directory. If path to a directory is specified, then the contents of that directory are copied to the specified location. Subdirectories are copied recursively.

  • $target_path

    Path for saving a copy.

  • $skip_pattern

    Regular expression string describing the format of file and subdirectory names which must not be copied if a path to a subdirectory is specified in $source_path parameter (otherwise this regular expression is ignored).

Example

//entire contents of 'wa-log' directory will copied to a directory named 'wa-log-temp', except for file and subdirectories whose names contain the word 'installer'
waFiles::copy('wa-log', 'wa-log-temp', '/installer/')

public static function create ($path, $is_dir = false)

Creates a directory or parent directory for a file.

Parameters

  • $path

    Path to a directory or a file.

  • $is_dir

    Flag to explicitly show that $path parameter contains path to a directory. By default (false), the method attempts to "guess" whether $path contains path to a file or to a directory.

Example

//in spite of a period in the target name,
//which is usually used to separate the base file name from its extension,
//$id_dir = true explicitly tells that it is a directory, not a file
waFiles::create(wa()->getConfig()->getPath('cache').'/some.folder', true);

public static function delete ($path, $ignore_dir_errors = false)

Deletes a file or a directory. A directory containing subdirectories is deleted recursively.

Parameters

  • $path

    Path to a file or directory.

  • $ignore_dir_errors

    Flag requiring to ignore any errors which may occur during the deletion of directories. By default (false), errors are not ignored—an exception is thrown.

Example

waFiles::delete('wa-test')

public static function extension($file)

Returns file name extension.

Parameters

  • $file

    File name.

Example

waFiles::extension('robots.txt')

Result

txt

public static function formatSize ($file_size, $format = '%0.2f', $dimensions = 'Bytes,KBytes,MBytes,GBytes')

Returns formatted file size value.

Parameters

  • $file_size

    Numerical file size value.

  • $format

    Format string for displaying file size value, which must be acceptable for PHP function sprintf.

  • $dimensions

    String of file size measure units, comma-separated.

Example

waFiles::formatSize(1000000, '%0.2f', 'B,KB,MB,GB')

Result

0.95 MB

public static function getMimeType ($filename)

Determines the MIME type of a file by its name.

Parameters

  • $filename

    File name.

Example

waFiles::getMimeType('index.php')

Result

text/html

public static function listdir ($dir, $recursive = false)

Returns the list of files and subdirectories in the specified directory.

Parameters

  • $dir

    Path to directory.

  • $recursive

    Flag requiring to return the contents of subdirectories. By default (false) subdirectories' contents are not returned. With true, only the list of files contained in the specified directory is returned, without the names of subdirectories.

Example

waFiles::listdir('wa-config/apps')

Result

Array
(
    [0] => contacts
    [1] => shop
    [2] => site
    [3] => mailer
    [4] => helpdesk
    [5] => photos
    [6] => webasyst
    [7] => stickies
    [8] => checklists
    [9] => blog
)

Example

waFiles::listdir('wa-config/apps', true)

Result

Array
(
    [0] => contacts/person_fields_order.php
    [1] => contacts/config.php
    [2] => contacts/custom_fields.php
    [3] => site/domains/yourdomain.php
    [4] => mailer/plugins.php
    [5] => helpdesk/workflows.php
    [6] => helpdesk/graph.php
    [7] => photos/plugins.php
    [8] => photos/config.php
    [9] => blog/plugins.php
)

public static function move ($source_path, $target_path)

Moves a file or a directory to the specified parent directory.

Parameters

  • $source_path

    Path to original file or directory.

  • $target_path

    Path to which the specified file or directory must be copied.

Example

$source = wa('myapp')->getAppPath('lib/config/data/.htaccess');
$target = wa('myapp')->getDataPath(null, true, 'images/.htaccess');
waFiles::move($source, $target);

public static function readFile ($file, $attach = null, $exit = true, $md5 = false)

Reads file contents and outputs it to the browser.

Parameters

  • $file

    File to path.

  • $attach

    Name, which will be suggested to user when he requests to download the file. If not specified, browser's auto-suggestion will be used.

  • $exit

    Flag requiring to send file transfer headers to user's browser. By default (true) headers are sent.

  • $md5

    Flag requiring to send the Content-MD5 header. By default (false) this header is not sent.

Example

$path = wa('myapp')->getAppPath('lib/config/data/sample.zip');
waFiles::readFile($path);

public static function upload ($url, $path)

Uploads a file from the specified URL to a server directory.

Parameters

  • $url

    URL from which a file must be retrieved.

  • $path

    Path for saving the downloaded file.

Example

$url = 'http://somedomain.com/archive.zip';
$path = wa()->getDataPath('files/pricelist.zip', true, 'myapp');
waFiles::upload($url, $path);

public static function write ($path, $content)

Writes data to a file.

Parameters

  • $path

    Path for saving a file. An existing file will be overwritten.

  • $content

    Data to be written to the file.

Example

$path = wa()->getDataPath('user/01.txt', false, 'myapp');
$content = 'some text';
waFiles::write($path, $content);