Merge branch 'release/v1.0.0'

Author: cerbero90

.travis.yml

@@ -20,6 +20,8 @@ matrix:
   include:
     - php: 7.1
       env: 'COMPOSER_FLAGS="--prefer-stable --prefer-lowest"'
+  allow_failures:
+    - php: hhvm
 
 before_script:
   - travis_retry composer update ${COMPOSER_FLAGS} --no-interaction --prefer-dist

README.md

@@ -19,8 +19,39 @@ $ composer require cerbero/json-objects
 
 ## Usage
 
+Simply pass the JSON source (files, endpoints, streams) and optionally the key where objects are contained to create a
+new instance of `JsonObjects`. You can also call the factory method `from()`:
+
+``` php
+$source = 'https://jsonplaceholder.typicode.com/users';
+
+// Create a new instance specifying the JSON source to extract objects from
+new JsonObjects($source);
+// or
+JsonObjects::from($source);
+
+// Create a new instance specifying the JSON source and the key to extract objects from
+new JsonObjects($source, 'address.geo');
+// or
+JsonObjects::from($source, 'address.geo');
+```
+
+When providing a key to extract objects from, you can use the dot notation to indicate nested sections of a JSON. For
+example `nested.*.key` extracts all the objects in the property `key` of every object contained in `nested`.
+
+Finally you can decide whether to extract and process objects one by one or in chunks. The memory will be allocated to
+read these objects only instead of the whole JSON document:
+
 ``` php
-// @todo Add usage description.
+// Extract and process one object at a time from the given JSON source
+JsonObjects::from($source)->each(function (array $object) {
+    // Process one object
+});
+
+// Extract and process a chunk of objects at a time from the given JSON source
+JsonObjects::from($source)->chunk(100, function (array $objects) {
+    // Process 100 objects
+});
 ```
 
 ## Change log

composer.json

@@ -20,7 +20,8 @@
         }
     ],
     "require": {
-        "php": "~7.1"
+        "php": "~7.1",
+        "salsify/json-streaming-parser": "^8.0"
     },
     "require-dev": {
         "phpunit/phpunit": ">=7.0",

src/JsonObjects.php

@@ -0,0 +1,135 @@
+<?php
+
+namespace Cerbero\JsonObjects;
+
+use Exception;
+use JsonStreamingParser\Parser;
+use Cerbero\JsonObjects\Listeners\AbstractListener;
+use Cerbero\JsonObjects\Listeners\ChunkListener;
+use Cerbero\JsonObjects\Listeners\ObjectListener;
+
+/**
+ * The JSON objects main class.
+ *
+ */
+class JsonObjects
+{
+    /**
+     * The JSON stream.
+     *
+     * @var resource
+     */
+    protected $stream;
+
+    /**
+     * The key containing the JSON objects.
+     *
+     * @var string|null
+     */
+    protected $key;
+
+    /**
+     * Set the dependencies.
+     *
+     * @param resource|string $source
+     * @param string|null $key
+     *
+     * @throws JsonObjectsException
+     */
+    public function __construct($source, string $key = null)
+    {
+        $this->setStreamFromSource($source);
+
+        $this->key = $key;
+    }
+
+    /**
+     * Set the JSON stream from the given source
+     *
+     * @param mixed $source
+     * @return void
+     *
+     * @throws JsonObjectsException
+     */
+    protected function setStreamFromSource($source) : void
+    {
+        if (is_resource($source)) {
+            $this->stream = $source;
+            return;
+        }
+
+        if (!is_string($source)) {
+            throw new JsonObjectsException('Unable to create a stream from the given source.');
+        }
+
+        $this->stream = extension_loaded('zlib') ? @gzopen($source, 'rb') : @fopen($source, 'rb');
+
+        if ($this->stream === false) {
+            throw new JsonObjectsException("Failed to open stream from: {$source}");
+        }
+    }
+
+    /**
+     * Create a new instance while easing method chaining
+     *
+     * @param resource|string $source
+     * @param string|null $key
+     * @return self
+     *
+     * @throws JsonObjectsException
+     */
+    public static function from($source, string $key = null) : self
+    {
+        return new static($source, $key);
+    }
+
+    /**
+     * Process each JSON object separately
+     *
+     * @param callable $callback
+     * @return void
+     *
+     * @throws JsonObjectsException
+     */
+    public function each(callable $callback) : void
+    {
+        $this->parseStreamWithListener(new ObjectListener($callback));
+    }
+
+    /**
+     * Parse the JSON stream with the given listener
+     *
+     * @param AbstractListener $listener
+     * @return void
+     *
+     * @throws JsonObjectsException
+     */
+    protected function parseStreamWithListener(AbstractListener $listener) : void
+    {
+        if ($this->key !== null) {
+            $listener->setTargetFromKey($this->key);
+        }
+
+        try {
+            (new Parser($this->stream, $listener))->parse();
+        } catch (Exception $e) {
+            throw new JsonObjectsException($e->getMessage());
+        } finally {
+            extension_loaded('zlib') ? gzclose($this->stream) : fclose($this->stream);
+        }
+    }
+
+    /**
+     * Process JSON objects in chunks
+     *
+     * @param int $size
+     * @param callable $callback
+     * @return void
+     *
+     * @throws JsonObjectsException
+     */
+    public function chunk(int $size, callable $callback) : void
+    {
+        $this->parseStreamWithListener(new ChunkListener($size, $callback));
+    }
+}

src/JsonObjectsException.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Cerbero\JsonObjects;
+
+use Exception;
+
+/**
+ * The JSON objects exception.
+ *
+ */
+class JsonObjectsException extends Exception
+{
+    //
+}