File: README.md

Class.RecreateTree.php

CLASS COPYING RECURSIVELY A DIRECTORY FROM A SOURCE PATH TO A DESTINATION PATH, WITH ALL OF SUBFOLDERS AND FILES HAVING THE PERMISSION ACCORDING TO SPECIFIC SETTINGS, WITH FOLDERS AND FILES OVERWRITTEN IF FOUND IN THE DESTINATION PATH, OR CREATED IF THEY DO NOT EXIST

AUTHOR

Alessandro Quintiliani <alex23rps at gmail dot com>

LICENSE

GNU GPL (see file COPYING.txt)

PREREQUISITES

PHP >= 5

USAGE

1) Place Class.RecreateTree.php and Class.CustomExceptions.php in the root directory of your web application. If you still have a directory containing other classes in your web application, place Class.RecreateTree.php and Class.CustomExceptions.php in the same directory, modifying theirs relative path

2) Include first Class.CustomExceptions.php and then Class.RecreateTree.php at the top of the PHP script or before the point in the script where a copy of an entire directory content is required

include("Class.CustomExceptions.php");
include("Class.RecreateTree.php");

or

include_once("Class.CustomExceptions.php");
include_once("Class.RecreateTree.php");

or

require("Class.CustomExceptions.php");
require("Class.RecreateTree.php");

or

require_once("Class.CustomExceptions.php");
require_once("Class.RecreateTree.php");

3) Instantiate RecreateTree class with the following syntax:

$rt = new RecreateTree();

4) Set (optionally) the absolute or relative path to the main source directory to be copied (including or not the trailing slash or backslash); if omitted, the absolute path to the php file where this method is invoked is taken as a default

$rt->setPathSrc(['absolute/or/relative/path/to/src/maindir/named/srcrootdir/']);

5) Set (optionally) the absolute or relative path to the main destination directory (including or not the trailing slash or backslash); if omitted, the absolute path to the php file where this method is invoked is taken as a default

$rt->setPathDest(['absolute/or/relative/path/to/dest/maindir/named/destrootdir/']);

6) Set (optionally) the permission to the main destination directory and all of its subdirectories in octal code (0xyz, where x,y,z: 0 -> 7); if omitted, the permission assigned is the same of the most internal directory in the source subpath common with the destination path; if the source and destination path have no common subpath, a cautios default permission 0755 is assigned as a default

$rt->setPermissionDir([octalCodePermissionDestDirectories]);

or

$rt->setPermissionDirs([octalCodePermissionDestDirectories]);

NOTICE:

• both the input arguments of setPathSrc() and setPathDest() are optional, but only one of them can be omitted, otherwise the source and the destination path would be the same, and the copy would make no sense. If accidentally both are omitted, an exception is raised, outputting the warning Source and Destination Path are the same: no copy is done
• both the setPermissionDir() and setPermissionDirs() methods accept the same input argument and are interchangeable. The reason of this double choice is to let flexibility to the user in the choice of the method name according to the idea of setting permission to one (...Dir) or more directories (...Dirs). In the rest of this document you will find setPermissionDir(s) to refer to both the methods

7) Set (optionally) the permission to all files under the main destination directory (and all of its subdirectories) in octal code (0xyz, where x,y,z: 0 -> 7); if omitted, all of the files will be assigned 0644 as a default permission

$rt->setPermissionFile([octalCodePermissionDestFiles]);

or

$rt->setPermissionFiles([octalCodePermissionDestFiles]);

NOTICE: both the setPermissionFile() and setPermissionFiles() methods accept the same input argument and are interchangeable. The reason of this double choice is to let flexibility to the user in the choice of the method name according to the idea of setting permission to one (...File) or more files (...Files). In the rest of this document you will find setPermissionFile(s) as referring to both the methods

NOTICE: the steps 4, 5 ,6 ,7 are interchangeable

8) Call the method makeTree() to create the destination tree of folder, files and subfolders

$rt->makeTree();

So, if under abs/or/rel/path/to/src/maindir/named/srcrootdir/ you have the following structure

abs/or/rel/path/to/src/maindir/named/srcrootdir/

                                            |---subdir1/
                                            |       |---file1.ext1
                                            |       |---file2.ext1
                                            |       |---file3.ext2
                                            |
                                            |---subdir2/
                                            |       |---file4.ext2
                                            |       |---subdir3/
                                            |              |---file5.ext3
                                            |---file6.ext1

and you want to copy the structure under srcrootdir to another directory such as abs/or/rel/path/to/dest/maindir/named/destrootdir, after calling the makeTree() method you will have the following structure

abs/or/rel/path/to/dest/maindir/named/destrootdir/

                          					|---subdir1/
                                            |       |---file1.ext1
                          					|       |---file2.ext1
                          					|       |---file3.ext2
                          					|
                          					|---subdir2/
                          					|       |---file4.ext2
                          					|       |---subdir3/
                          					|              |---file5.ext3
                          			        |--file6.ext1

with the permission on each folder and file according to the octal values given as an input argument respectfully to the setPermissionDir(s) and setPermissionFile(s) methods.

As above described, if the input argument to setPermissionDir(s) is omitted and, as an example, the source and the destination path have abs/or/rel/path/to as a common subpath (or a further subpath), all the destination directories ( dest/maindir/named/destrootdir and subdir1, subdir2, subdir3 ) are created with the same permission of the most internal directory in the subpath common to both source and destination path (to/)

NOTICE: if the input argument to both setPathSrc() and setPathDest() is a relative path according to the Windows format (backslash "\" as a directory separator) and the PHP script calling this class should be migrate to Unix platform mantaining the same relative paths (or vice versa), you do not need to change the directory separator on each path (Unix requires slash "/" as directory separator) because setPathSrc() and setPathDest() automatically change "\" or "/" accordingly to the directory separator of the operating system where the PHP script is going to run.

makeTree(), if invoked, also prints on the browser several messages as a confirmation of successfully creation tree and useful for statistics. All of the possible outputs are:

4 independent warning messages due to an exception

• The source pathname is not valid. One or more subdirectories contain one of the following special chars: &lt;, &gt;, :, &quot;, |, ?, \* this message is raised by an exception caught when one or more of the above listed characters are found in the source path name
• The destination pathname is not valid. One or more subdirectories contain one of the following special chars: &lt;, &gt;, :, &quot;, |, ?, \* this is the same case as the source path name: the destination pathname contains one or more characters not valid
• The source path /absolute/or/relative/source/path does not exist this message is raised by an exception caught when the given source path does not exist
• Source and Destination Path are the same: no copy is done this message is raised by an exception caught when both the source and destination path are equal: the creation tree does not make sense (NOTICE: the comparison is case insensitive on Win* operating systems)

Messages of successful creation tree or failures, plus other messages for statistics

• The path to the main source directory
• The path to the main destination directory
• The octal code of the permission to the destination folders (NOTICE: If the input argument to the setPermissionDir(s) method is omitted, an extra statement warning that all the destination directories are set with the same permission as the parent directory is printed)
• The octal code of the permission to the destination files (NOTICE: if the input argument to the setPermissionFile(s) is omitted, the default octal code 0644 is assigned as a default)
• The total number of the source files read
• The total number of the destination files created or overwritten
• The total number of the destination files created
• The total number of the destination files overwritten
• A red message warning that the main source directory is not readable
• A red message warning that the main destination directory cannot be created
• A red warning with the number and the list of destination folders which cannot be created
• A red warning with the number and the list of source files which cannot be opened
• A red warning with the number and the list of source files which cannot be read
• A red warning with the number and the list of source files which cannot be closed
• A red warning with the number and the list of destination files which cannot be opened
• A red warning with the number and the list of destination files which cannot be created or overwritten
• A red warning with the number and the list of destination files which cannot be closed
• A list of each full path to the source file encountered during the execution of makeTree(), followed by the full path to the destination file, with SRC: and DEST: prependend at them, plus a letter at both the sides of the destination path file ((N)=new, (O)=Overwritten) along with the file size written in human readable format

EXAMPLE

Place Class.RecreateTree.php, Class.CustomExceptions.php, example.php at the same level in a webroot directory, i.e. CreateTree on a web server having &lt;my.domain.com&gt; or localhost as a domain.

Choose any directory having several subfolders and files you want to copy and make sure that the chosen directory and all of its subfolders and files have the right permission to allow the default user of the web server to read the structure. If so, in example.php replace the argument 'absolute/or/relative/path/to/src/maindir/named/srcrootdir/' passed as an input argument to the $rt->setPathSrc() method with an absolute (or relative) the path to your chosen main source directory.

Then choose a destination directory and make sure that you can set any permission according to that you apply by the octal code given as an input argument to the setPermissionDir(s)() and setPermissionFile(s)() methods. If so, in example.php replace the argument 'absolute/or/relative/path/to/dest/maindir/named/destrootdir/' passed as an input argument to the $rt->setPathDest() method with an absolute (or relative) the path to your chosen main destination directory.

Open a browser and type in the URL bar:

http://<my.domain.com>/CreateTree/example.php

or

http://localhost/CreateTree/example.php

After a while (depending on the number of subfolders and files to copy), when example.php has run, you will see on the browser the result of the method makeTree() (see the description of this method).

As a test, you can change source and destination path, set different permissions to the destination folders (or omit it) and files, as well as modify and/or remove folders and/or files under the source or the destination directory: you will see that new files and/or folders are created or overwritten in case of different content.