Release v1.0.0

* Add custom exceptions
* Complete documentation
* Clean up code

README.md

@@ -16,7 +16,80 @@ composer require S1SYPHOS/php-thx
 For yarn v2 support, the `php-yaml` package is required!
 
 
-# Usage
+## Usage
+
+First, determine the paths to your files (datafile & lockfile, see below):
+
+```php
+<?php
+
+require_once('vendor/autoload.php');
+
+use S1SYPHOS\Thx;
+
+$pkgFile = 'path/to/composer.json';                # or 'package.json' for NPM / Yarn
+$lockFile = 'path/to/composer.lock'                # or 'package-lock.json' for NPM / 'yarn.lock' for Yarn
+$cacheDriver = 'file';                             # Optional: Cache driver, see below
+$cacheSettings = ['storage' => '/path/to/cache'];  # Optional: Cache settings, see below
+```
+
+**Note:**
+For available cache drivers & settings, see [here](https://github.com/terrylinooo/simple-cache)!
+
+Passing these options to `Thx::giveBack()` creates an instance:
+
+```php
+$obj = Thx::giveBack($pkgFile, $lockFile, $cacheDriver, $cacheSettings);
+```
+
+.. which you may configure to your liking by using:
+
+- `setTimeout(int $seconds)`
+- `setCacheDuration(int $days)`
+- `setUserAgent(string $userAgent)`
+- `setBlockList(array $blockList)`
+
+```php
+# For example:
+
+$obj->setCacheDuration(7);                    # Cache results for one week
+$obj->setBlockList(['php', 'some/library']);  # Block from being processed
+```
+
+After setting everything up, `spreadLove()` makes some API calls:
+
+- Composer packages @ https://repo.packagist.org
+- Node packages @ https://api.npms.io
+
+```php
+$obj->spreadLove();
+```
+
+Currently there are three methods you can use:
+
+- `data()` returns raw data from lockfile for all used packages
+- `pkgs()` returns processed data for all used packages
+- `packages()` returns the names of all used packages
+
+```php
+# Alternative 1:
+# Process data
+$obj->spreadLove();
+
+# Work with it
+$raw = $obj->data();
+$processed = $obj->pkgs();
+
+# Alternative 2:
+# Since `spreadLove` allows chaining, you could also do it like this:
+$obj->spreadLove()->data();
+
+# The second call provides cached data, no performance penalty there
+$obj->spreadLove()->pkgs();
+```
+
+
+## Example
 
 This example should get you started:
 
@@ -48,11 +121,11 @@ try {
 
 ## Roadmap
 
-- [ ] Add (more sophisticated) tests
+- [x] ~~Add (more sophisticated) tests~~ for now, they get the job done
+- [x] Parse yarn v1 lockfiles
 - [x] Gather information using public APIs
-- [ ] Custom `Exception`s
+- [x] Custom `Exception`s
 - [ ] Provide more methods
-- [x] Parse yarn v1 lockfiles
 
 
 ## Credits

composer.json

@@ -3,7 +3,7 @@
     "description": "Acknowledge the people behind your frontend dependencies - and give thanks!",
     "type": "library",
     "license": "MIT",
-    "version": "0.3.0",
+    "version": "1.0.0",
     "keywords": ["gratitude", "appreciation", "gratefulness", "thankfulness"],
     "homepage": "https://github.com/S1SYPHOS",
     "scripts": {

lib/Driver.php

@@ -58,8 +58,8 @@ abstract class Driver
     /**
      * Constructor
      *
-     * @param string $dataFile Path to data file
-     * @param string $lockFile Lockfile stream
+     * @param string $pkgData Content of datafile as array
+     * @param string $lockFile Content of lockfile as string
      * @param string $cacheDriver Cache driver
      * @param array $cacheSettings Cache settings
      * @return void

lib/Exceptions/NoJuiceException.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace S1SYPHOS\Exceptions;
+
+class NoJuiceException extends NoThxException {}

lib/Exceptions/NoMannersException.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace S1SYPHOS\Exceptions;
+
+class NoMannersException extends NoThxException {}

lib/Exceptions/NoThxException.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace S1SYPHOS\Exceptions;
+
+class NoThxException extends \Exception {}

lib/Thx.php

@@ -9,6 +9,11 @@
 
 namespace S1SYPHOS;
 
+use S1SYPHOS\Exceptions\NoJuiceException;
+use S1SYPHOS\Exceptions\NoMannersException;
+
+use \S1SYPHOS\Traits\Helpers;
+
 
 /**
  * Class Thx
@@ -22,14 +27,14 @@ class Thx
     /**
      * Current version
      */
-    const VERSION = '0.3.0';
+    const VERSION = '1.0.0';
 
 
     /**
      * Traits
      */
 
-    use \S1SYPHOS\Traits\Helpers;
+    use Helpers;
 
 
     /**
@@ -39,8 +44,11 @@ class Thx
     /**
      * Gives back & shows some love
      *
-     * @param string $dataFile Datafile, eg 'composer.json' or 'package.json'
-     * @param string $lockFile Lockfile, eg 'composer.lock', 'package-lock.json' or 'yarn.lock'
+     * @param string $dataFile Path to datafile, eg 'composer.json' or 'package.json'
+     * @param string $lockFile Path tp lockfile, eg 'composer.lock', 'package-lock.json' or 'yarn.lock'
+     * @param string $cacheDriver Cache driver
+     * @param array $cacheSettings Cache settings
+
      * @return \S1SYPHOS\Driver
      */
     public static function giveBack(string $dataFile, string $lockFile, string $cacheDriver = 'file', array $cacheSettings = [])
@@ -53,7 +61,7 @@ public static function giveBack(string $dataFile, string $lockFile, string $cach
             !static::contains($lockFilename, 'yarn') &&
             !static::contains($lockFilename, 'package')
         ) {
-            throw new \Exception(sprintf('Unknown lockfile: "%s".', $lockFilename));
+            throw new NoMannersException(sprintf('Unknown lockfile: "%s".', $lockFilename));
         }
 
         # Determine package manager
@@ -66,15 +74,15 @@ public static function giveBack(string $dataFile, string $lockFile, string $cach
 
         if ($dataFilename === 'composer.json') {
             if (in_array('require', array_keys($pkgData)) === false) {
-                throw new \Exception(sprintf('%s does not contain "require".', $dataFilename));
+                throw new NoJuiceException(sprintf('%s does not contain "require".', $dataFilename));
             }
 
             $class = 'S1SYPHOS\\Drivers\\Composer';
         }
 
         if ($dataFilename === 'package.json') {
             if (in_array('dependencies', array_keys($pkgData)) === false) {
-                throw new \Exception(sprintf('%s does not contain "dependencies".', $dataFilename));
+                throw new NoJuiceException(sprintf('%s does not contain "dependencies".', $dataFilename));
             }
 
             # (1) Yarn
@@ -89,7 +97,7 @@ public static function giveBack(string $dataFile, string $lockFile, string $cach
         }
 
         if (!isset($class)) {
-            throw new \Exception(sprintf('Unknown datafile: "%s".', $dataFilename));
+            throw new NoMannersException(sprintf('Unknown datafile: "%s".', $dataFilename));
         }
 
         return new $class($pkgData, $lockFile, $cacheDriver, $cacheSettings);

lib/Traits/Caching.php

@@ -2,11 +2,14 @@
 
 namespace S1SYPHOS\Traits;
 
+use S1SYPHOS\Exceptions\NoJuiceException;
+use S1SYPHOS\Exceptions\NoMannersException;
+
 
 trait Caching
 {
     /**
-     * Caching
+     * Properties
      */
 
     /**
@@ -86,7 +89,7 @@ protected function createCache(string $cacheDriver = 'file', array $cacheSetting
         # Initialize cache
         # (1) Validate provided cache driver
         if (in_array($cacheDriver, $this->cacheDrivers) === false) {
-            throw new \Exception(sprintf('Cache driver "%s" cannot be initiated', $cacheDriver));
+            throw new NoJuiceException(sprintf('Cache driver "%s" cannot be initiated', $cacheDriver));
         }
 
         # (2) Merge caching options with defaults
@@ -134,7 +137,7 @@ protected function createDir(string $dir, bool $recursive = true): bool
         }
 
         if (is_writable($parent) === false) {
-            throw new \Exception(sprintf('The directory "%s" cannot be created', $dir));
+            throw new NoMannersException(sprintf('The directory "%s" cannot be created', $dir));
         }
 
         return mkdir($dir);