From 5a55dfaf8235c3c61ae3895d2402e1d8ac5a387f Mon Sep 17 00:00:00 2001 From: Romain Neutron Date: Mon, 18 Jun 2012 13:00:24 +0200 Subject: [PATCH 1/2] Add Filesystem component documentation --- components/filesystem.rst | 220 ++++++++++++++++++++++++++++++++++++++ components/index.rst | 1 + components/map.rst.inc | 4 + 3 files changed, 225 insertions(+) create mode 100644 components/filesystem.rst diff --git a/components/filesystem.rst b/components/filesystem.rst new file mode 100644 index 00000000000..2ec6e8ef7b9 --- /dev/null +++ b/components/filesystem.rst @@ -0,0 +1,220 @@ +.. index:: + single: Filesystem + +The Filesystem Component +======================== + + The Filesystem components provides basic utilities for the filesystem. + +Installation +------------ + +You can install the component in many different ways: + +* Use the official Git repository (https://github.com/symfony/Filesystem); +* Install it via PEAR ( `pear.symfony.com/Filesystem`); +* Install it via Composer (`symfony/filesystem` on Packagist). + +Usage +----- + +The :class:`Symfony\\Component\\Filesystem\\Filesystem` class is the unique +endpoint for filesystem operations:: + + use Symfony\Component\Filesystem\Filesystem; + + $fs = new Filesystem(); + + try { + $fs->mkdir('/tmp/random/dir/' . mt_rand()); + } catch (\RuntimeException $e) { + echo "An error occured while creating your directory"; + } + +.. note:: + + Methods :method:`Symfony\\Component\\Filesystem\\Filesystem::mkdir`, + :method:`Symfony\\Component\\Filesystem\\Filesystem::chown`, + :method:`Symfony\\Component\\Filesystem\\Filesystem::chgrp`, + :method:`Symfony\\Component\\Filesystem\\Filesystem::chown`, + :method:`Symfony\\Component\\Filesystem\\Filesystem::remove` and + :method:`Symfony\\Component\\Filesystem\\Filesystem::touch` can receive a + string, an array or any object implementing :phpclass:`\\Traversable` as + target argument. + + +Mkdir +~~~~~ + +Mkdir creates directory. On posix filesystems, directories are created with a +default mode value `0777`. You can use the second argument to set your own mode. + + $fs->mkdir('/tmp/photos', 0700); + + +.. note:: + + You can pass an array or any :phpclass:`\\Traversable` object as the first + argument. + +Copy +~~~~ + +This method is used to copy files. If the target already exists, the file is +copied only if the source modification date is earlier than the target. This +behavior can be overridden by the third boolean argument:: + + // works only if image-ICC has been modified after image.jpg + $fs->copy('image-ICC.jpg', 'image.jpg'); + + // image.jpg will be overridden + $fs->copy('image-ICC.jpg', 'image.jpg', true); + + +Touch +~~~~~ + +Touch sets access and modification time to a file. The current time is used by +default. You can set your own with the second argument. The third argument is +the access time:: + + // set modification time to the current timestamp + $fs->touch('file.txt'); + // set modification time 10 seconds in the future + $fs->touch('file.txt', time() + 10); + // set access time 10 seconds in the past + $fs->touch('file.txt', time(), time() - 10); + + +.. note:: + + You can pass an array or any :phpclass:`\\Traversable` object as the first + argument. + +Chown +~~~~~ + +Chown is used to change the owner of a file. The third argument is a boolean +recursive option:: + + // set the owner of the lolcat video to www-data + $fs->chown('lolcat.mp4', 'www-data'); + // change the owner of the video directory recursively + $fs->chown('/video', 'www-data', true); + + +.. note:: + + You can pass an array or any :phpclass:`\\Traversable` object as the first + argument. + +Chgrp +~~~~~ + +Chgrp is used to change the group of a file. The third argument is a boolean +recursive option:: + + // set the group of the lolcat video to nginx + $fs->chgrp('lolcat.mp4', 'nginx'); + // change the group of the video directory recursively + $fs->chgrp('/video', 'nginx', true); + + +.. note:: + + You can pass an array or any :phpclass:`\\Traversable` object as the first + argument. + +Chmod +~~~~~ + +Chmod is used to change the mode of a file. The third argument is a boolean +recursive option:: + + // set the mode of the video to 0600 + $fs->chmod('video.ogg', 0600); + // change the mod of the src directory recursively + $fs->chmod('src', 0700, true); + + +.. note:: + + You can pass an array or any :phpclass:`\\Traversable` object as the first + argument. + +Remove +~~~~~~ + +Remove let's you remove files, symlink, directories easily:: + + $fs->remove(array('symlink', '/path/to/directory', 'activity.log')); + + +.. note:: + + You can pass an array or any :phpclass:`\\Traversable` object as the first + argument. + +Rename +~~~~~~ + +Rename is used to rename file and directories:: + + //rename a file + $fs->rename('/tmp/processed_video.ogg', '/path/to/store/video_647.ogg'); + //rename a directory + $fs->rename('/tmp/files', '/path/to/store/files'); + +symlink +~~~~~~~ + +Create a symbolic link from target to destination. If the filesystem does not +support symbolic links, a third boolean argument is available:: + + // create a symbolic link + $fs->symlink('/path/to/source', '/path/to/destination'); + // duplicate the source directory if the filesystem does not support symbolic links + $fs->symlink('/path/to/source', '/path/to/destination', true); + +makePathRelative +~~~~~~~~~~~~~~~~ + +Return the relative path of a directory given another one:: + + // returns '../' + $fs->makePathRelative('/var/lib/symfony/src/Symfony/', '/var/lib/symfony/src/Symfony/Component'); + // returns 'videos' + $fs->makePathRelative('/tmp', '/tmp/videos'); + +mirror +~~~~~~ + +Mirrors a directory:: + + $fs->mirror('/path/to/source', '/path/to/target'); + +isAbsolutePath +~~~~~~~~~~~~~~ + +isAbsolutePath returns true if the given path is absolute, false otherwise:: + + // return true + $fs->isAbsolutePath('/tmp'); + // return true + $fs->isAbsolutePath('c:\\Windows'); + // return false + $fs->isAbsolutePath('tmp'); + // return false + $fs->isAbsolutePath('../dir'); + +Error Handling +-------------- + +Whenever something wrong happends, a :phpclass:`\\RuntimeException` is thrown. + + +.. note:: + + Prior to version 2.1, :method:`Symfony\\Component\\Filesystem\\Filesystem::mkdir` + was returning a boolean and did not throw exceptions. As of 2.1, a + :phpclass:`\\RuntimeException` is thrown if a directory creation fails. diff --git a/components/index.rst b/components/index.rst index 3319cb0d8f6..5f5930e3006 100644 --- a/components/index.rst +++ b/components/index.rst @@ -10,6 +10,7 @@ The Components dom_crawler dependency_injection/index event_dispatcher/index + filesystem finder http_foundation/index locale diff --git a/components/map.rst.inc b/components/map.rst.inc index 967a63b2a13..bc47b81d34f 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -29,6 +29,10 @@ * :doc:`/components/dom_crawler` +* **The Filesystem Component** + + * :doc:`/components/filesystem` + * **The Finder Component** * :doc:`/components/finder` From dd6e66cb80d14d8445bffa68e4eb898b45d3e4de Mon Sep 17 00:00:00 2001 From: Romain Neutron Date: Mon, 18 Jun 2012 13:11:31 +0200 Subject: [PATCH 2/2] Add documentation about the exists method --- components/filesystem.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/components/filesystem.rst b/components/filesystem.rst index 2ec6e8ef7b9..8cb93e8d45d 100644 --- a/components/filesystem.rst +++ b/components/filesystem.rst @@ -52,6 +52,25 @@ default mode value `0777`. You can use the second argument to set your own mode. $fs->mkdir('/tmp/photos', 0700); +.. note:: + + You can pass an array or any :phpclass:`\\Traversable` object as the first + argument. + + +Exists +~~~~~~ + +Exists checks the presence of all files or directories and return false if a +file is missing. + + // this directory exists, return true + $fs->exists('/tmp/photos'); + + // rabbit.jpg exists, bottle.png does not exists, return false + $fs->exists(array('rabbit.jpg', 'bottle.png)); + + .. note:: You can pass an array or any :phpclass:`\\Traversable` object as the first