feature #3956 [Command] Added LockHelper (lyrixx)

This PR was merged into the master branch.

Discussion
----------

[Command] Added LockHelper

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes symfony/symfony#10475
| Applies to    | Symfony version 2.6+
| Fixed tickets | -

Commits
-------

909a294 [Filesystem] Added documentation for the new LockHandler
2bf8c55 [Filesystem] Moved current document to a dedicated folder

components/filesystem/index.rst

@@ -0,0 +1,8 @@
+Filesystem
+==========
+
+.. toctree::
+    :maxdepth: 2
+
+    introduction
+    lock_handler

components/filesystem.rst → 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 </components/filesystem/lock_handler>`.
+
 Installation
 ------------
 

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.

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

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**
 

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