feat: add parallel cache support

doc/usage.rst

@@ -142,6 +142,7 @@ Note: You need to pass the config to the ``fix`` command, in order to make it wo
 
 .. code-block:: console
 
+    export PHP_CS_FIXER_EXPERIMENTAL_PARALLEL_CACHE=1
     php php-cs-fixer.phar list-files --config=.php-cs-fixer.dist.php | xargs -n 10 -P 8 php php-cs-fixer.phar fix --config=.php-cs-fixer.dist.php --path-mode intersection -v
 
 * ``-n`` defines how many files a single subprocess process

src/Cache/Cache.php

@@ -136,4 +136,18 @@ public static function fromJson(string $json): self
 
         return $cache;
     }
+
+    /**
+     * @internal
+     */
+    public function backfillHashes(self $oldCache): bool
+    {
+        if (!$this->getSignature()->equals($oldCache->getSignature())) {
+            return false;
+        }
+
+        $this->hashes = array_merge($oldCache->hashes, $this->hashes);
+
+        return true;
+    }
 }

src/Cache/FileHandler.php

@@ -41,21 +41,65 @@ public function read(): ?CacheInterface
             return null;
         }
 
-        $content = file_get_contents($this->file);
-
-        try {
-            $cache = Cache::fromJson($content);
-        } catch (\InvalidArgumentException $exception) {
+        $handle = fopen($this->file, 'r');
+        if (false === $handle) {
             return null;
         }
 
+        $cache = $this->readFromHandle($handle);
+
+        fclose($handle);
+
         return $cache;
     }
 
     public function write(CacheInterface $cache): void
     {
-        $content = $cache->toJson();
+        $this->ensureFileIsWriteable();
+
+        $handle = fopen($this->file, 'r+');
+        if (false === $handle) {
+            return;
+        }
+
+        if (getenv('PHP_CS_FIXER_EXPERIMENTAL_PARALLEL_CACHE')) {
+            flock($handle, LOCK_EX);
 
+            $oldCache = $this->readFromHandle($handle);
+            rewind($handle);
+
+            if ($oldCache && method_exists($cache, 'backfillHashes')) {
+                $cache->backfillHashes($oldCache);
+            }
+        }
+
+        ftruncate($handle, 0);
+        fwrite($handle, $cache->toJson());
+        fflush($handle);
+        fclose($handle);
+    }
+
+    /**
+     * @param resource $handle
+     */
+    private function readFromHandle($handle): ?CacheInterface
+    {
+        try {
+            $size = filesize($this->file);
+            if (!$size) {
+                return null;
+            }
+
+            $content = fread($handle, $size);
+
+            return Cache::fromJson($content);
+        } catch (\InvalidArgumentException $exception) {
+            return null;
+        }
+    }
+
+    private function ensureFileIsWriteable(): void
+    {
         if (file_exists($this->file)) {
             if (is_dir($this->file)) {
                 throw new IOException(
@@ -95,18 +139,5 @@ public function write(CacheInterface $cache): void
             @touch($this->file);
             @chmod($this->file, 0666);
         }
-
-        $bytesWritten = @file_put_contents($this->file, $content);
-
-        if (false === $bytesWritten) {
-            $error = error_get_last();
-
-            throw new IOException(
-                sprintf('Failed to write file "%s", "%s".', $this->file, $error['message'] ?? 'no reason available'),
-                0,
-                null,
-                $this->file
-            );
-        }
     }
 }