Skip to content

Commit 6ea9f8b

Browse files
weaverryanweaverryan
committed
Merge pull request #1439 from romainneutron/FileSystem
Add Filesystem component documentation
2 parents f4581f0 + dd6e66c commit 6ea9f8b

File tree

3 files changed

+244
-0
lines changed

3 files changed

+244
-0
lines changed

‎components/filesystem.rst

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
.. index::
2+
single: Filesystem
3+
4+
The Filesystem Component
5+
========================
6+
7+
The Filesystem components provides basic utilities for the filesystem.
8+
9+
Installation
10+
------------
11+
12+
You can install the component in many different ways:
13+
14+
* Use the official Git repository (https://github.com/symfony/Filesystem);
15+
* Install it via PEAR ( `pear.symfony.com/Filesystem`);
16+
* Install it via Composer (`symfony/filesystem` on Packagist).
17+
18+
Usage
19+
-----
20+
21+
The :class:`Symfony\\Component\\Filesystem\\Filesystem` class is the unique
22+
endpoint for filesystem operations::
23+
24+
use Symfony\Component\Filesystem\Filesystem;
25+
26+
$fs = new Filesystem();
27+
28+
try {
29+
$fs->mkdir('/tmp/random/dir/' . mt_rand());
30+
} catch (\RuntimeException $e) {
31+
echo "An error occured while creating your directory";
32+
}
33+
34+
.. note::
35+
36+
Methods :method:`Symfony\\Component\\Filesystem\\Filesystem::mkdir`,
37+
:method:`Symfony\\Component\\Filesystem\\Filesystem::chown`,
38+
:method:`Symfony\\Component\\Filesystem\\Filesystem::chgrp`,
39+
:method:`Symfony\\Component\\Filesystem\\Filesystem::chown`,
40+
:method:`Symfony\\Component\\Filesystem\\Filesystem::remove` and
41+
:method:`Symfony\\Component\\Filesystem\\Filesystem::touch` can receive a
42+
string, an array or any object implementing :phpclass:`\\Traversable` as
43+
target argument.
44+
45+
46+
Mkdir
47+
~~~~~
48+
49+
Mkdir creates directory. On posix filesystems, directories are created with a
50+
default mode value `0777`. You can use the second argument to set your own mode.
51+
52+
$fs->mkdir('/tmp/photos', 0700);
53+
54+
55+
.. note::
56+
57+
You can pass an array or any :phpclass:`\\Traversable` object as the first
58+
argument.
59+
60+
61+
Exists
62+
~~~~~~
63+
64+
Exists checks the presence of all files or directories and return false if a
65+
file is missing.
66+
67+
// this directory exists, return true
68+
$fs->exists('/tmp/photos');
69+
70+
// rabbit.jpg exists, bottle.png does not exists, return false
71+
$fs->exists(array('rabbit.jpg', 'bottle.png));
72+
73+
74+
.. note::
75+
76+
You can pass an array or any :phpclass:`\\Traversable` object as the first
77+
argument.
78+
79+
Copy
80+
~~~~
81+
82+
This method is used to copy files. If the target already exists, the file is
83+
copied only if the source modification date is earlier than the target. This
84+
behavior can be overridden by the third boolean argument::
85+
86+
// works only if image-ICC has been modified after image.jpg
87+
$fs->copy('image-ICC.jpg', 'image.jpg');
88+
89+
// image.jpg will be overridden
90+
$fs->copy('image-ICC.jpg', 'image.jpg', true);
91+
92+
93+
Touch
94+
~~~~~
95+
96+
Touch sets access and modification time to a file. The current time is used by
97+
default. You can set your own with the second argument. The third argument is
98+
the access time::
99+
100+
// set modification time to the current timestamp
101+
$fs->touch('file.txt');
102+
// set modification time 10 seconds in the future
103+
$fs->touch('file.txt', time() + 10);
104+
// set access time 10 seconds in the past
105+
$fs->touch('file.txt', time(), time() - 10);
106+
107+
108+
.. note::
109+
110+
You can pass an array or any :phpclass:`\\Traversable` object as the first
111+
argument.
112+
113+
Chown
114+
~~~~~
115+
116+
Chown is used to change the owner of a file. The third argument is a boolean
117+
recursive option::
118+
119+
// set the owner of the lolcat video to www-data
120+
$fs->chown('lolcat.mp4', 'www-data');
121+
// change the owner of the video directory recursively
122+
$fs->chown('/video', 'www-data', true);
123+
124+
125+
.. note::
126+
127+
You can pass an array or any :phpclass:`\\Traversable` object as the first
128+
argument.
129+
130+
Chgrp
131+
~~~~~
132+
133+
Chgrp is used to change the group of a file. The third argument is a boolean
134+
recursive option::
135+
136+
// set the group of the lolcat video to nginx
137+
$fs->chgrp('lolcat.mp4', 'nginx');
138+
// change the group of the video directory recursively
139+
$fs->chgrp('/video', 'nginx', true);
140+
141+
142+
.. note::
143+
144+
You can pass an array or any :phpclass:`\\Traversable` object as the first
145+
argument.
146+
147+
Chmod
148+
~~~~~
149+
150+
Chmod is used to change the mode of a file. The third argument is a boolean
151+
recursive option::
152+
153+
// set the mode of the video to 0600
154+
$fs->chmod('video.ogg', 0600);
155+
// change the mod of the src directory recursively
156+
$fs->chmod('src', 0700, true);
157+
158+
159+
.. note::
160+
161+
You can pass an array or any :phpclass:`\\Traversable` object as the first
162+
argument.
163+
164+
Remove
165+
~~~~~~
166+
167+
Remove let's you remove files, symlink, directories easily::
168+
169+
$fs->remove(array('symlink', '/path/to/directory', 'activity.log'));
170+
171+
172+
.. note::
173+
174+
You can pass an array or any :phpclass:`\\Traversable` object as the first
175+
argument.
176+
177+
Rename
178+
~~~~~~
179+
180+
Rename is used to rename file and directories::
181+
182+
//rename a file
183+
$fs->rename('/tmp/processed_video.ogg', '/path/to/store/video_647.ogg');
184+
//rename a directory
185+
$fs->rename('/tmp/files', '/path/to/store/files');
186+
187+
symlink
188+
~~~~~~~
189+
190+
Create a symbolic link from target to destination. If the filesystem does not
191+
support symbolic links, a third boolean argument is available::
192+
193+
// create a symbolic link
194+
$fs->symlink('/path/to/source', '/path/to/destination');
195+
// duplicate the source directory if the filesystem does not support symbolic links
196+
$fs->symlink('/path/to/source', '/path/to/destination', true);
197+
198+
makePathRelative
199+
~~~~~~~~~~~~~~~~
200+
201+
Return the relative path of a directory given another one::
202+
203+
// returns '../'
204+
$fs->makePathRelative('/var/lib/symfony/src/Symfony/', '/var/lib/symfony/src/Symfony/Component');
205+
// returns 'videos'
206+
$fs->makePathRelative('/tmp', '/tmp/videos');
207+
208+
mirror
209+
~~~~~~
210+
211+
Mirrors a directory::
212+
213+
$fs->mirror('/path/to/source', '/path/to/target');
214+
215+
isAbsolutePath
216+
~~~~~~~~~~~~~~
217+
218+
isAbsolutePath returns true if the given path is absolute, false otherwise::
219+
220+
// return true
221+
$fs->isAbsolutePath('/tmp');
222+
// return true
223+
$fs->isAbsolutePath('c:\\Windows');
224+
// return false
225+
$fs->isAbsolutePath('tmp');
226+
// return false
227+
$fs->isAbsolutePath('../dir');
228+
229+
Error Handling
230+
--------------
231+
232+
Whenever something wrong happends, a :phpclass:`\\RuntimeException` is thrown.
233+
234+
235+
.. note::
236+
237+
Prior to version 2.1, :method:`Symfony\\Component\\Filesystem\\Filesystem::mkdir`
238+
was returning a boolean and did not throw exceptions. As of 2.1, a
239+
:phpclass:`\\RuntimeException` is thrown if a directory creation fails.

‎components/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ The Components
1010
dom_crawler
1111
dependency_injection/index
1212
event_dispatcher/index
13+
filesystem
1314
finder
1415
http_foundation/index
1516
locale

‎components/map.rst.inc

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,10 @@
2929

3030
* :doc:`/components/dom_crawler`
3131

32+
* **The Filesystem Component**
33+
34+
* :doc:`/components/filesystem`
35+
3236
* **The Finder Component**
3337

3438
* :doc:`/components/finder`

0 commit comments

Comments
 (0)