edit readme

spatie · Apr 5, 2016 · 1005e6e · 1005e6e
1 parent 3982d40
commit 1005e6e
Show file tree

Hide file tree

Showing 3 changed files with 191 additions and 65 deletions.
diff --git a/README.md b/README.md
@@ -7,7 +7,27 @@
 [![Quality Score](https://img.shields.io/scrutinizer/g/spatie/valuestore.svg?style=flat-square)](https://scrutinizer-ci.com/g/spatie/valuestore)
 [![Total Downloads](https://img.shields.io/packagist/dt/spatie/valuestore.svg?style=flat-square)](https://packagist.org/packages/spatie/valuestore)
 
-This package makes it easy to store some values to a json file and afterwards to retrieve them from the file.
+This package makes it easy to store and retrieve some values. Stores values are saved as a json in a file.
+
+It can be used like this:
+
+```php
+$valuestore = Valuestore::make($pathToFile);
+
+$valuestore->put('key', 'value');
+
+$valuestore->get('key'); //returns 'value'
+
+$valuestore->put('anotherKey', 'anotherValue');
+
+$valuestore->all(); // returns ['key' => 'value', 'anotherKey' => 'anotherValue']
+
+$valuestore->forget('key') // the item has been removed
+
+$valuestore->flush() // empty the entire valuestore
+```
+
+Read the [usage](#usage) section of this readme to learn the other methods.
 
 Spatie is a webdesign agency based in Antwerp, Belgium. You'll find an overview of all our open source projects [on our website](https://spatie.be/opensource).
 
@@ -21,62 +41,115 @@ $ composer require spatie/valuestore
 
 ## Usage
 
- To store some values in the file:
-``` php
-Valuestore::make('file-name')->put('value-name', 'value');
-```
+To create a Valuestore use the `make`-method.
 
-Or:
-``` php
-$file = Valuestore::make('file-name');
-$file->put('value-name', 'value');
+```php
+$valuestore = Valuestore::make($pathToFile);
 ```
 
-To get a specific value from the file:
-``` php
-Valuestore::make('file-name')->get('value-name');
+All values will be saved in the given file.
+
+You can call the following methods on the `Valuestore`
+
+### put
+```php
+/**
+ * Put a value in the store.
+ *
+ * @param string|array $name
+ * @param string|int|null $value
+ * 
+ * @return $this
+ */
+public function put($name, $value = null)
 ```
 
-Or:
-``` php
-$file = Valuestore::make('file-name');
-$file->get('value-name');
+### get
+
+```php
+/**
+ * Get a value from the store.
+ *
+ * @param string $name
+ *
+ * @return null|string
+ */
+public function get(string $name)
 ```
 
-If you want to see what's stored in the file you ask all the values at once. You'll get an array back:
-``` php
-Valuestore::make('file-name')->all();
+### all
+```php
+/**
+ * Get all values from the store.
+ *
+ * @param string $startingWith
+ *
+ * @return array
+*/
+public function all(string $startingWith = '') : array
 ```
 
-Or:
-``` php
-$file = Valuestore::make('file-name');
-$file->all();
+### forget
+```php
+/**
+ * Forget a value from the store.
+ *
+ * @param string $key
+ *
+ * @return $this
+ */
+public function forget(string $key)
 ```
 
-If you want to see all the values where the key contains a specific string:
-``` php
-Valuestore::make('file-name')->all('string-that-key-must-contain');
+### flush
+```php
+/**
+ * Flush all values from the store.
+ *
+ * @param string $startingWith
+ *
+ * @return $this
+ */public function flush(string $startingWith = '')
 ```
 
-Or:
-``` php
-$file = Valuestore::make('file-name');
-$file->all('string-key-contains');
+### pull
+```php
+/**
+ * Get and forget a value from the store.
+ *
+ * @param string $name 
+ *
+ * @return null|string
+ */
+public function pull(string $name)
 ```
 
-If you want to clear all the values in the file:
-```  php
-Valuestore::make('file-name')->clear();
+### increment
+```php
+/**
+ * Increment a value from the store.
+ *
+ * @param string $name
+ * @param int $by
+ *
+ * @return int|null|string
+ */
+ public function increment(string $name, int $by = 1)
 ```
 
-Or:
-```  php
-$file = Valuestore::make('file-name');
-$file->clear();
+### decrement
+```php
+/**
+ * Decrement a value from the store.
+ *
+ * @param string $name
+ * @param int $by
+ *
+ * @return int|null|string
+ */
+ public function decrement(string $name, int $by = 1)
 ```
 
-
 ## Changelog
 
 Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.

diff --git a/src/Valuestore.php b/src/Valuestore.php
@@ -22,6 +22,8 @@ protected function __construct()
     }
 
     /**
+     * Set the filename where all values will be stored.
+     *
      * @param string $fileName
      *
      * @return $this
@@ -34,8 +36,12 @@ protected function setFileName(string $fileName)
     }
 
     /**
-     * @param string|array    $name
+     * Put a value in the store.
+     *
+     * @param string|array $name
      * @param string|int|null $value
+     * 
+     * @return $this
      */
     public function put($name, $value = null)
     {
@@ -48,9 +54,13 @@ public function put($name, $value = null)
         $newContent = array_merge($this->all(), $newValues);
 
         $this->setContent($newContent);
+
+        return $this;
     }
 
     /**
+     * Get a value from the store.
+     *
      * @param string $name
      *
      * @return null|string
@@ -65,6 +75,8 @@ public function get(string $name)
     }
 
     /**
+     * Get all values from the store.
+     *
      * @param string $startingWith
      *
      * @return array
@@ -84,24 +96,46 @@ public function all(string $startingWith = '') : array
         return $values;
     }
 
-    public function increment(string $name, int $by = 1)
+    /**
+     * Forget a value from the store.
+     *
+     * @param string $key
+     *
+     * @return $this
+     */
+    public function forget(string $key)
     {
-        $currentValue = $this->get($name) ?? 0;
+        $newContent = $this->all();
 
-        $newValue = $currentValue + $by;
+        unset($newContent[$key]);
 
-        $this->put($name, $newValue);
+        $this->setContent($newContent);
 
-        return $newValue;
+        return $this;
     }
 
-    public function decrement(string $name, int $by = 1)
+    /**
+     * Flush all values from the store.
+     *
+     * @param string $startingWith
+     *
+     * @return $this
+     */
+    public function flush(string $startingWith = '')
     {
-        return $this->increment($name, $by * -1);
+        $newContent = [];
+
+        if ($startingWith !== '') {
+            $newContent = $this->filterKeysNotStartingWith($this->all(), $startingWith);
+        }
+
+        return $this->setContent($newContent);
+
+        return $this;
     }
 
     /**
-     * Get and forget a value.
+     * Get and forget a value from the store.
      *
      * @param string $name
      *
@@ -117,38 +151,38 @@ public function pull(string $name)
     }
 
     /**
-     * @param string $key
+     * Increment a value from the store.
      *
-     * @return $this
+     * @param string $name
+     * @param int $by
+     *
+     * @return int|null|string
      */
-    public function forget(string $key)
+    public function increment(string $name, int $by = 1)
     {
-        $newContent = $this->all();
+        $currentValue = $this->get($name) ?? 0;
 
-        unset($newContent[$key]);
+        $newValue = $currentValue + $by;
 
-        $this->setContent($newContent);
+        $this->put($name, $newValue);
 
-        return $this;
+        return $newValue;
     }
 
     /**
-     * @param string $startingWith
+     * Decrement a value from the store.
      *
-     * @return $this
+     * @param string $name
+     * @param int $by
+     *
+     * @return int|null|string
      */
-    public function flush(string $startingWith = '')
+    public function decrement(string $name, int $by = 1)
     {
-        $newContent = [];
-
-        if ($startingWith !== '') {
-            $newContent = $this->filterKeysNotStartingWith($this->all(), $startingWith);
-        }
+        return $this->increment($name, $by * -1);
+    }
 
-        return $this->setContent($newContent);
 
-        return $this;
-    }
 
     protected function filterKeysStartingWith(array $values, string $startsWith) : array
     {

diff --git a/tests/ValuestoreTest.php b/tests/ValuestoreTest.php
@@ -30,6 +30,25 @@ public function it_can_store_a_key_value_pair()
         $this->assertSame('value', $this->valuestore->get('key'));
     }
 
+    /** @test */
+    public function it_can_store_an_integer()
+    {
+        $this->valuestore->put('number', 1);
+
+        $this->assertSame(1, $this->valuestore->get('number'));
+    }
+
+    /** @test */
+    public function it_provides_a_chainable_put_method()
+    {
+        $this->valuestore
+            ->put('number', 1)
+            ->put('string', 'hello');
+
+        $this->assertSame(1, $this->valuestore->get('number'));
+        $this->assertSame('hello', $this->valuestore->get('string'));
+    }
+
     /** @test */
     public function it_will_return_null_for_a_non_existing_value()
     {