diff --git a/components/filesystem/index.rst b/components/filesystem/index.rst new file mode 100644 index 00000000000..e643f5a90f4 --- /dev/null +++ b/components/filesystem/index.rst @@ -0,0 +1,8 @@ +Filesystem +========== + +.. toctree:: + :maxdepth: 2 + + introduction + lock_handler diff --git a/components/filesystem.rst b/components/filesystem/introduction.rst similarity index 98% rename from components/filesystem.rst rename to components/filesystem/introduction.rst index 076d7c38d1f..8990198aa41 100644 --- a/components/filesystem.rst +++ b/components/filesystem/introduction.rst @@ -10,6 +10,12 @@ The Filesystem Component The Filesystem component was introduced in Symfony 2.1. Previously, the ``Filesystem`` class was located in the HttpKernel component. + +.. tip:: + + A lock handler feature was introduce in symfony 2.6. + :doc:`See the documentation for more information `. + Installation ------------ diff --git a/components/filesystem/lock_handler.rst b/components/filesystem/lock_handler.rst new file mode 100644 index 00000000000..d57889190ef --- /dev/null +++ b/components/filesystem/lock_handler.rst @@ -0,0 +1,69 @@ +LockHandler +=========== + +.. versionadded:: 2.6 + The lock handler feature was introduced in Symfony 2.6 + +What is a Lock? +--------------- + +File locking is a mechanism that restricts access to a computer file by allowing +only one user or process access at any specific time. This mechanism was +introduced a few decades ago for mainframes, but continues being useful for +modern applications. + +Symfony provides a LockHelper to help you use locks in your project. + +Usage +----- + +.. caution:: + + The lock handler only works if you're using just one server. If you have + several hosts, you must not use this helper. + +A lock can be used, for example, to allow only one instance of a command to run. + +.. code-block:: php + + use Symfony\Component\Filesystem\LockHandler; + + $lockHandler = new LockHandler('hello.lock'); + if (!$lockHandler->lock()) { + // the resource "hello" is already locked by another process + + return 0; + } + +The first argument of the constructor is a string that it will use as part of +the name of the file used to create the lock on the local filesystem. A best +practice for Symfony commands is to use the command name, such as ``acme:my-command``. +``LockHandler`` sanitizes the contents of the string before creating +the file, so you can pass any value for this argument. + +.. tip:: + + The ``.lock`` extension is optional, but it's a common practice to include + it. This will make it easier to find lock files on the filesystem. Moreover, + to avoid name collisions, ``LockHandler`` also appends a hash to the name of + the lock file. + +By default, the lock will be created in the temporary directory, but you can +optionally select the directory where locks are created by passing it as the +second argument of the constructor. + +The :method:`Symfony\\Component\\Filesystem\\LockHandler::lock` method tries to +acquire the lock. If the lock is acquired, the method returns ``true``, +``false`` otherwise. If the ``lock`` method is called several times on the same +instance it will always return ``true`` if the lock was acquired on the first +call. + +You can pass an optional blocking argument as the first argument to the +``lock()`` method, which defaults to ``false``. If this is set to ``true``, your +PHP code will wait indefinitely until the lock is released by another process. + +The resource is automatically released by PHP at the end of the script. In +addition, you can invoke the +:method:`Symfony\\Component\\Filesystem\\LockHandler::release` method to release +the lock explicitly. Once it's released, any other process can lock the +resource. diff --git a/components/index.rst b/components/index.rst index 8e167cd2ac9..91b3dfc466a 100644 --- a/components/index.rst +++ b/components/index.rst @@ -14,7 +14,7 @@ The Components dom_crawler event_dispatcher/index expression_language/index - filesystem + filesystem/index finder form/index http_foundation/index diff --git a/components/map.rst.inc b/components/map.rst.inc index f9eab711e07..1bccb80fb61 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -70,9 +70,10 @@ * :doc:`/components/expression_language/extending` * :doc:`/components/expression_language/caching` -* **Filesystem** +* :doc:`/components/filesystem/index` - * :doc:`/components/filesystem` + * :doc:`/components/filesystem/introduction` + * :doc:`/components/filesystem/lock_handler` * **Finder** diff --git a/redirection_map b/redirection_map index 1a6758a5560..33d8293f670 100644 --- a/redirection_map +++ b/redirection_map @@ -22,6 +22,7 @@ /cookbook/console/generating_urls /cookbook/console/sending_emails /components/yaml /components/yaml/introduction /components/templating /components/templating/introduction +/components/filesystem /components/filesystem/introduction /cmf/reference/configuration/block /cmf/bundles/block/configuration /cmf/reference/configuration/content /cmf/bundles/content/configuration /cmf/reference/configuration/core /cmf/bundles/core/configuration