Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Add Filesystem component documentation #1439

Merged
merged 2 commits into from

3 participants

@romainneutron

This PR add Filesystem component documentation.

This documentation is only compatible with the symfony/symfony#4330 PR

components/filesystem.rst
((19 lines not shown))
+-----
+
+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`,
@stof
stof added a note

.. note:: should be alone on the line, and without the extra space.

@stof
stof added a note

same for all other notes

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
components/filesystem.rst
((25 lines not shown))
+
+ $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 :class:`\Traversable` as target
@stof
stof added a note

this should be :phpclass: as you want to link to the PHP documentation, not to the Symfony API doc

@stof
stof added a note

and you need to escape the \ too

Antislashes are now escaped

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
components/filesystem.rst
((182 lines not shown))
+ $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 :class:`\\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
+ :class:`\\RuntimeException` is thrown if a directory creation fails.
@stof
stof added a note

same issue here

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@romainneutron

@stof CS fixed

@romainneutron

By the way, I squashed the commits

components/filesystem.rst
((7 lines not shown))
+ 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 :
@weaverryan Collaborator

To setup the next PHP code block, use 2 colons, like this:

filesystem operations::
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
components/filesystem.rst
((34 lines not shown))
+.. 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 create directory. On posix filesystems, directories are created with a
@weaverryan Collaborator

creates a directory

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
components/filesystem.rst
((42 lines not shown))
+ string, an array or any object implementing :phpclass:`\\Traversable` as
+ target argument.
+
+
+Mkdir
+~~~~~
+
+Mkdir create 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 first
@weaverryan Collaborator

as the first argument

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
components/filesystem.rst
((35 lines not shown))
+
+ 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 create directory. On posix filesystems, directories are created with a
+default mode value `0777`. You can use the second argument to set your own mode.
@weaverryan Collaborator

Like everywhere else, use the double-colon to setup the php code block:

to set your own mode::
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@weaverryan weaverryan commented on the diff
components/map.rst.inc
@@ -29,6 +29,10 @@
* :doc:`/components/dom_crawler`
+* **The Filesystem Component**
+
+ * :doc:`/components/filesystem`
+
@weaverryan Collaborator

There's also an index.rst file in this same directory, which also needs to be updated (map is used for the visual page, but index is used to calculate "where" the pages are behind the scenes). Make sure that the location of the filesystem component is the same in both :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@weaverryan
Collaborator

Hi Romain!

I've made some small comments on some parts of the PR to get things started. I noticed that symfony/symfony#4330 isn't merged yet, but it seems close - and it also seems like a few parts of this PR will need to be updated for some potential changes. When that PR is merged and this one is updated, I'll check this out again. The PR looks great so far though!

Thanks!

@romainneutron

Hello Ryan !

I did the changes you requested, tell me if you see some other things.

@romainneutron

Hello @weaverryan, the symfony PR has been merged.

@weaverryan weaverryan merged commit 6ea9f8b into symfony:master
@weaverryan
Collaborator

Hey Romain!

Great! I've merged in this PR and made a few minor syntax changes after rendering it locally.

I do have one question - is the last section about the exception handling still true? Obviously, a RuntimeException is thrown, but there's also the IOException and the ExceptionInterface. Do we need another small PR to update this section for these new exceptions?

Thanks!

@romainneutron

Oh yes, This part has been updated few days ago, I forgot to update. I'm gong to update it right now

@romainneutron

By the way, great job on spelling, I'm sorry I've to improve my english

@weaverryan
Collaborator

No problem - happy to help with spelling/grammer/syntax - you did the hard work :)

@craigmarvelley craigmarvelley referenced this pull request from a commit in craigmarvelley/symfony
@fabpot fabpot merged branch romainneutron/FilesystemExceptions (PR #4330)
Commits
-------

a20fc68 Merge pull request #1 from SamsonIT/FilesystemExceptions
8eca661 [FileSystem] explains possible failure of symlink creation in windows
b1f8744 Add Changelog BC Break note
24eb396 [Filesystem] Added few new behaviors:

Discussion
----------

[Filesystem] Consistence and enhancements for Filesystem

Bug fix: no
Feature addition: yes
Backwards compatibility break: **yes**
Symfony2 tests pass: yes
Fixes the following tickets: None
License of the code: MIT

This PR adds features and introduce a backward compatibility break.

features :
- whenever an action fails, a \RuntimeException is thrown
- add access to the second and third arguments of ``touch`` function
- add a recursive option for chmod
- add a chown method
- add a chgrp method

The backward compatibility break happens in the mkdir method : Before this PR, a boolean is returned ; true if all directories were created, false otherwise.
It now returns nothing.

---------------------------------------------------------------------------

by travisbot at 2012-05-18T14:26:42Z

This pull request [passes](http://travis-ci.org/symfony/symfony/builds/1367000) (merged 83cdd622 into 1e15f21).

---------------------------------------------------------------------------

by fabpot at 2012-05-20T02:40:28Z

To be consistent, we should throw exception whenever some operation fails.

---------------------------------------------------------------------------

by romainneutron at 2012-05-20T21:10:23Z

I fix the consistency ; mkdir now throws an exception if a directory creation fails.
This introduce a BC break, see PR message which has been updated with all features and BC break.

Added chgrp and chown methods
Add options for touch
Add recursive option for chmod

---------------------------------------------------------------------------

by travisbot at 2012-05-20T21:11:47Z

This pull request [passes](http://travis-ci.org/symfony/symfony/builds/1383619) (merged a4d1eeb8 into 1407f11).

---------------------------------------------------------------------------

by travisbot at 2012-05-22T10:49:06Z

This pull request [passes](http://travis-ci.org/symfony/symfony/builds/1399027) (merged 7e14b6bd into 517ae43).

---------------------------------------------------------------------------

by travisbot at 2012-05-22T10:58:10Z

This pull request [passes](http://travis-ci.org/symfony/symfony/builds/1399083) (merged 71852653 into 517ae43).

---------------------------------------------------------------------------

by travisbot at 2012-05-22T11:18:44Z

This pull request [passes](http://travis-ci.org/symfony/symfony/builds/1399194) (merged 7645bad3 into 517ae43).

---------------------------------------------------------------------------

by travisbot at 2012-05-23T18:21:47Z

This pull request [fails](http://travis-ci.org/symfony/symfony/builds/1414091) (merged b049d5b1 into 517ae43).

---------------------------------------------------------------------------

by travisbot at 2012-05-23T18:26:19Z

This pull request [fails](http://travis-ci.org/symfony/symfony/builds/1414123) (merged 34903466 into 517ae43).

---------------------------------------------------------------------------

by travisbot at 2012-05-29T16:07:26Z

This pull request [passes](http://travis-ci.org/symfony/symfony/builds/1467173) (merged b1d1eb2e into adf07f1).

---------------------------------------------------------------------------

by travisbot at 2012-05-29T16:19:38Z

This pull request [passes](http://travis-ci.org/symfony/symfony/builds/1467261) (merged 42015ffa into adf07f1).

---------------------------------------------------------------------------

by romainneutron at 2012-06-01T14:30:45Z

Any news about this PR ?

---------------------------------------------------------------------------

by stloyd at 2012-06-08T09:57:39Z

@romainneutron You need to [squash](http://www.silverwareconsulting.com/index.cfm/2010/6/6/Using-Git-Rebase-to-Squash-Commits) your commits, and add more proper message in squashed commit i.e.:

> [Filesystem]  Added few new behaviors:
* whenever an action fails, a `RuntimeException` is thrown
* add access to the second and third arguments of `touch()` function
* add a recursive option for `chmod()`
* add a `chown()` method
* add a `chgrp()` method

> BC break: `mkdir()` function throw exception in case of failture instead of returning Boolean value.

---------------------------------------------------------------------------

by romainneutron at 2012-06-08T10:59:55Z

@stloyd squash done !

---------------------------------------------------------------------------

by travisbot at 2012-06-08T11:26:20Z

This pull request [passes](http://travis-ci.org/symfony/symfony/builds/1565540) (merged 8f55ddb6 into f8e68e5).

---------------------------------------------------------------------------

by travisbot at 2012-06-08T11:41:45Z

This pull request [passes](http://travis-ci.org/symfony/symfony/builds/1566247) (merged 880312b6 into f8e68e5).

---------------------------------------------------------------------------

by romainneutron at 2012-06-09T11:42:24Z

I've added documentation to the Filesystem component : symfony/symfony-docs#1439

---------------------------------------------------------------------------

by travisbot at 2012-06-09T16:47:20Z

This pull request [passes](http://travis-ci.org/symfony/symfony/builds/1577754) (merged 5647ad41 into f8a09db).

---------------------------------------------------------------------------

by stloyd at 2012-06-13T14:47:31Z

@romainneutron You probably need to rebase your code as some changes were merge into master for `Filesystem`.

---------------------------------------------------------------------------

by romainneutron at 2012-06-13T15:17:31Z

@stloyd rebase OK !

by the way, do you have any idea when/if this PR will be merged ?

---------------------------------------------------------------------------

by travisbot at 2012-06-13T15:20:44Z

This pull request [passes](http://travis-ci.org/symfony/symfony/builds/1611591) (merged c8b86c68 into c07e916).

---------------------------------------------------------------------------

by fabpot at 2012-06-16T16:40:50Z

You need to add a note about the BC breaks in the CHANGELOG file.

---------------------------------------------------------------------------

by fabpot at 2012-06-16T16:43:20Z

Also, instead of using `\RuntimeException`, I would create a custom exception like we have done in other components (an interface + a RuntimeException that implements the interface and extends \RuntimeException). The exception name can be something like `IOException`.

---------------------------------------------------------------------------

by travisbot at 2012-06-18T10:11:20Z

This pull request [fails](http://travis-ci.org/symfony/symfony/builds/1645757) (merged 925a8234 into 0b8b76b).

---------------------------------------------------------------------------

by stloyd at 2012-06-18T10:14:52Z

@fabpot Anything blocking merge of this PR ? (tests are failing because of issue in master, not releted to this PR)

---------------------------------------------------------------------------

by romainneutron at 2012-06-18T10:29:20Z

@fabpot @stloyd the latest push was just a rebase push for PR 4577 (symfony#4577)
I'm currently fixing the Exception and changelog things, I'll push very soon

---------------------------------------------------------------------------

by romainneutron at 2012-06-18T10:44:38Z

@fabpot I've added the exception and the exception interface, add the changelog info

---------------------------------------------------------------------------

by travisbot at 2012-06-18T10:53:34Z

This pull request [fails](http://travis-ci.org/symfony/symfony/builds/1645981) (merged 634d6fb9 into 0b8b76b).

---------------------------------------------------------------------------

by romainneutron at 2012-06-18T11:08:43Z

As reported by @stloyd the PR is failing due to an issue in the master, I re-push and trig the PR build when this issue is solved

---------------------------------------------------------------------------

by travisbot at 2012-06-18T11:16:58Z

This pull request [fails](http://travis-ci.org/symfony/symfony/builds/1646006) (merged 2f65945a into 0b8b76b).
55f682c
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
View
239 components/filesystem.rst
@@ -0,0 +1,239 @@
+.. 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.
+
+
+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
+ 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.
View
1  components/index.rst
@@ -10,6 +10,7 @@ The Components
dom_crawler
dependency_injection/index
event_dispatcher/index
+ filesystem
finder
http_foundation/index
locale
View
4 components/map.rst.inc
@@ -29,6 +29,10 @@
* :doc:`/components/dom_crawler`
+* **The Filesystem Component**
+
+ * :doc:`/components/filesystem`
+
@weaverryan Collaborator

There's also an index.rst file in this same directory, which also needs to be updated (map is used for the visual page, but index is used to calculate "where" the pages are behind the scenes). Make sure that the location of the filesystem component is the same in both :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
* **The Finder Component**
* :doc:`/components/finder`
Something went wrong with that request. Please try again.