Skip to content

Add Filesystem component documentation #1439

Merged
merged 2 commits into from Jun 20, 2012

3 participants

@romainneutron
Symfony member

This PR add Filesystem component documentation.

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

@stof stof commented on an outdated diff Jun 9, 2012
components/filesystem.rst
+-----
+
+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
Symfony member
stof added a note Jun 9, 2012

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

@stof
Symfony member
stof added a note Jun 9, 2012

same for all other notes

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@stof stof and 1 other commented on an outdated diff Jun 9, 2012
components/filesystem.rst
+
+ $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
Symfony member
stof added a note Jun 9, 2012

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

@stof
Symfony member
stof added a note Jun 9, 2012

and you need to escape the \ too

@romainneutron
Symfony member
romainneutron added a note Jun 9, 2012

Antislashes are now escaped

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@stof stof commented on an outdated diff Jun 9, 2012
components/filesystem.rst
+ $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
Symfony member
stof added a note Jun 9, 2012

same issue here

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

@stof CS fixed

@romainneutron
Symfony member

By the way, I squashed the commits

@weaverryan weaverryan commented on an outdated diff Jun 17, 2012
components/filesystem.rst
+ 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
Symfony member
weaverryan added a note Jun 17, 2012

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
@weaverryan weaverryan commented on an outdated diff Jun 17, 2012
components/filesystem.rst
+.. 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
Symfony member
weaverryan added a note Jun 17, 2012

creates a directory

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@weaverryan weaverryan commented on an outdated diff Jun 17, 2012
components/filesystem.rst
+ 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
Symfony member
weaverryan added a note Jun 17, 2012

as the first argument

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@weaverryan weaverryan commented on an outdated diff Jun 17, 2012
components/filesystem.rst
+
+ 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
Symfony member
weaverryan added a note Jun 17, 2012

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 Jun 17, 2012
components/map.rst.inc
@@ -29,6 +29,10 @@
* :doc:`/components/dom_crawler`
+* **The Filesystem Component**
+
+ * :doc:`/components/filesystem`
+
@weaverryan
Symfony member
weaverryan added a note Jun 17, 2012

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
Symfony member

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
Symfony member

Hello Ryan !

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

@romainneutron
Symfony member

Hello @weaverryan, the symfony PR has been merged.

@weaverryan weaverryan merged commit 6ea9f8b into symfony:master Jun 20, 2012
@weaverryan
Symfony member

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
Symfony member

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

@romainneutron
Symfony member

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

@weaverryan
Symfony member

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

@craigmarvelley craigmarvelley pushed a commit to craigmarvelley/symfony that referenced this pull request Nov 26, 2013
@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
Something went wrong with that request. Please try again.