Merge pull request #21 from OriHoch/master

[WIP] finishing up

Author: OriHoch

.gitignore

@@ -2,3 +2,6 @@
 /.idea/
 /coverage-clover.xml
 /composer.lock
+/.php_cs
+/.php_cs.cache
+/php-cs-fixer

.install_cs_fixer.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+if [ ! -f ./php-cs-fixer ]; then
+    wget https://github.com/FriendsOfPHP/PHP-CS-Fixer/releases/download/v2.3.2/php-cs-fixer.phar -O php-cs-fixer
+    chmod +x php-cs-fixer
+fi

.php_cs.dist

@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * code style configuration
+ * you may additionally create .php_cs file which will extend the configuration in this file
+ */
+
+$finder = new PhpCsFixer\Finder();
+$config = new PhpCsFixer\Config('datapackage-php', 'datapackage-php style guide');
+$finder
+    ->exclude("tests/fixtures")
+    ->exclude("src/Validators/schemas")
+    ->in(__DIR__)
+;
+$config
+    ->setRules([
+        '@PSR2' => true,
+        '@Symfony' => true
+    ])
+    ->setFinder($finder)
+;
+return $config;

.travis.yml

@@ -6,11 +6,11 @@ php:
   - '7.0'
   - '7.1'
   - nightly
-  - hhvm
 before_script:
-  - composer install --prefer-dist
+  - COMPOSER_DISABLE_XDEBUG_WARN=1 composer install --prefer-dist
 script:
-  - composer test
+  - COMPOSER_DISABLE_XDEBUG_WARN=1 composer test
+  - '[ "$TRAVIS_PHP_VERSION" != "7.1" ] || composer style-check'
 after_success:
   - '[ "$TRAVIS_PHP_VERSION" == "7.1" ] && vendor/bin/coveralls'
 dist: trusty

CONTRIBUTING.md

@@ -45,6 +45,11 @@ It does static code analysis and ensure confirmation to the coding stnadards.
 
 At the moment, the integration with frictionlessdata repo is not working, you can setup a Scrutinizer-ci account for your fork and run against that.
 
+## php-cs-fixer - code style check & autofix
+
+[php-cs-fixer](https://github.com/FriendsOfPHP/PHP-CS-Fixer) can be used to check and fix code style
+
+you need to manually install it, then you can run : `composer style-check` or `composer style-fix`
 
 ## Publishing a release and updating Packagist
 

README.md

@@ -10,89 +10,119 @@
 A utility library for working with [Data Package](https://specs.frictionlessdata.io/data-package/) in PHP.
 
 
-## Getting Started
+## Features summary and Usage guide
 
 ### Installation
 
 ```bash
 $ composer require frictionlessdata/datapackage
 ```
 
-### Usage
+### Package
+
+Load a data package conforming to the specs
 
 ```php
-use frictionlessdata\datapackage;
-
-// get a datapackage object
-$datapackage = datapackage\Factory::datapackage("tests/fixtures/multi_data_datapackage.json");
-
-// iterate over the data - it will raise exceptions in case of any problems
-foreach ($datapackage as $resource) {
-    print("-- ".$resource->name()." --");
-    $i = 0;
-    foreach ($resource as $dataStream) {
-        print("-dataStream ".++$i);
-        foreach ($dataStream as $line) {
-            print($line);
-        }
+use frictionlessdata\datapackage\Package;
+$package = Package::load("tests/fixtures/multi_data_datapackage.json");
+```
+
+Iterate over the resources and the data
+
+```php
+foreach ($package as $resource) {
+    echo $resource->name();
+    foreach ($resource as $row) {
+        echo $row;
     }
 }
+```
+
+Get all the data as an array (loads all the data into memory, not recommended for large data sets)
 
-// validate a datapackage descriptor
-$validationErrors = datapackage\Factory::validate("tests/fixtures/simple_invalid_datapackage.json");
-if (count($validationErrors) == 0) {
-    print("descriptor is valid");
-} else {
-    print(datapackage\Validators\DatapackageValidationError::getErrorMessages($validationErrors));
+```php
+foreach ($package as $resource) {
+    var_dump($resource->read());
 }
+```
 
-// get and manipulate resources
-$resources = $datapackage->resources();
-$resources["resource-name"]->name() == "resource-name"
-$resources["another-resource-name"] //  BaseResource based object (e.g. DefaultResource / TabularResource)
+All data and schemas are validated and throws exceptions in case of any problems.
 
-// get a single resource by name
-$datapackage->resource("resource-name")
+Validate the data explicitly and get a list of errors
 
-// delete a resource by name - will raise exception in case of validation failure for the new descriptor
-$datapackage->deleteResource("resource-name");
+```php
+Package::validate("tests/fixtures/simple_invalid_datapackage.json");  // array of validation errors
+```
 
-// add a resource - will raise exception in case of validation error for the new descriptor
-$resource = Factory::resource((object)[
-    "name" => "new-resource", "data" => ["tests/fixtures/foo.txt", "tests/fixtures/baz.txt"]
-])
-$datapackage->addResource($resource);
+The package object has some useful methods to access and manipulate the resources
 
-// register custom datapackage or resource classes which can override / extend core classes
-// these custom classes run a test against the schema to decide whether to handle a given descriptor or not
-Factory::registerDatapackageClass("my\\custom\\DatapackageClass");
-Factory::registerResourceClass("my\\custom\\ResourceClass");
+```php
+$package = Package::load("tests/fixtures/multi_data_datapackage.json");
+$package->resources();  // array of resource name => Resource object (see below for Resource class reference)
+$package->resource("first-resource");  // Resource object matching the given name
+$package->deleteResource("first-resource");
+// add a tabular resource
+$package->resource("tabular-resource-name", [
+    "profile" => "tabular-data-resource",
+    "schema" => [
+        "fields" => [
+            ["name" => "id", "type" => "integer"],
+            ["name" => "name", "type" => "string"]
+        ]
+    ],
+    "path" => [
+        "tests/fixtures/simple_tabular_data.csv",
+    ]
+]);
+```
 
-// register custom profiles and related schemas for validation
-Registry::registerSchema("my-custom-profile-id", "path/to/my-custom-profile.schema.json");
+Create a new package from scratch
 
-// create a new datapackage from scratch
-$datapackage = TabularDatapackage::create("my-tabular-datapackage", [
-    TabularResource::create("my-tabular-resource")
+```php
+$package = Package::create([
+    "name" => "datapackage-name",
+    "profile" => "tabular-data-package"
 ]);
+// add a resource
+$package->resource("resource-name", [
+    "profile" => "tabular-data-resource", 
+    "schema" => [
+        "fields" => [
+            ["name" => "id", "type" => "integer"],
+            ["name" => "name", "type" => "string"]
+        ]
+    ],
+    "path" => "tests/fixtures/simple_tabular_data.csv"
+]);
+// save the package descriptor to a file
+$package->saveDescriptor("datapackage.json");
+```
 
-// set the tabular data schema
-$datapackage->resource("my-tabular-resource")->descriptor()->schema = (object)[
-    "fields" => [
-        (object)["name" => "id", "type" => "integer"],
-        (object)["name" => "data", "type" => "string"],
-    ]
-];
+### Resource
+
+Resource objects can be accessed from a Package as described above
+
+```php
+$resource = $package->resource("resource-name")
+```
 
-// add data files
-$datapackage->resource("my-tabular-resource")->descriptor()->data[] = "/path/to/file-1.csv";
-$datapackage->resource("my-tabular-resource")->descriptor()->data[] = "/path/to/file-2.csv";
+or instantiated directly
 
-// re-validate the new descriptor
-$datapackage->revalidate();
+```php
+use frictionlessdata\datapackage\Resource;
+$resource = Resource::create([
+    "name" => "my-resource",
+    "profile" => "tabular-data-resource",
+    "path" => "tests/fixtures/simple_tabular_data.csv",
+    "schema" => ["fields" => [["name" => "id", "type" => "integer"], ["name" => "name", "type" => "string"]]]
+]);
+```
+
+Iterating or reading over the resource produces combined rows from all the path or data elements
 
-// save the datapackage descriptor to a file
-$datapackage->saveDescriptor("datapackage.json");
+```php
+foreach ($resource as $row) {};  // iterating
+$resource->read();  // get all the data as an array
 ```
 
 

composer.json

@@ -5,11 +5,12 @@
     "require": {
         "php": ">=5.4",
         "justinrainbow/json-schema": "^5.2",
-        "frictionlessdata/tableschema": "^0.1.5"
+        "frictionlessdata/tableschema": "^0.1.6"
     },
     "require-dev": {
         "phpunit/phpunit": "^4.8.35",
-        "satooshi/php-coveralls": "^1.0"
+        "satooshi/php-coveralls": "^1.0",
+        "psy/psysh": "@stable"
     },
     "autoload": {
         "psr-4": {
@@ -18,6 +19,8 @@
     },
     "scripts": {
         "test": "phpunit --debug --coverage-clover coverage-clover.xml --bootstrap tests/autoload.php tests/",
-        "update_registry": "php update_registry.php"
+        "update_registry": "php update_registry.php",
+        "style-check": "./.install_cs_fixer.sh && ./php-cs-fixer fix --dry-run --verbose --diff",
+        "style-fix": "./.install_cs_fixer.sh && ./php-cs-fixer fix --verbose"
     }
 }

src/DataStreams/BaseDataStream.php

@@ -1,23 +1,33 @@
 <?php
+
 namespace frictionlessdata\datapackage\DataStreams;
 
 /**
- * Provides a standard interface for streaming from a data stream (Read-only)
+ * Provides a standard interface for streaming from a data stream (Read-only).
  *
  * functionality could mostly be replaced by php generators (http://php.net/manual/en/language.generators.syntax.php)
  * however, they are only supported on PHP 5.5 and above
  */
 abstract class BaseDataStream implements \Iterator
 {
+    public $dataSource;
+    public $dataSourceOptions;
+
     /**
      * @param string $dataSource
-     * @param mixed $dataSourceOptions
+     * @param mixed  $dataSourceOptions
+     *
      * @throws \frictionlessdata\datapackage\Exceptions\DataStreamOpenException
      */
-    abstract public function __construct($dataSource, $dataSourceOptions=null);
+    public function __construct($dataSource, $dataSourceOptions = null)
+    {
+        $this->dataSource = $dataSource;
+        $this->dataSourceOptions = $dataSourceOptions;
+    }
 
     /**
      * @return mixed
+     *
      * @throws \frictionlessdata\datapackage\Exceptions\DataStreamValidationException
      */
     abstract public function current();

src/DataStreams/DefaultDataStream.php

@@ -1,23 +1,28 @@
 <?php
+
 namespace frictionlessdata\datapackage\DataStreams;
 
 use frictionlessdata\datapackage\Exceptions\DataStreamOpenException;
 
 /**
- * streams the raw data without processing - used for default data package resources
+ * streams the raw data without processing - used for default data package resources.
  */
 class DefaultDataStream extends BaseDataStream
 {
+    public $fopenResource;
+
     /**
      * @param string $dataSource
+     *
      * @throws DataStreamOpenException
      */
-    public function __construct($dataSource, $dataSourceOptions=null)
+    public function __construct($dataSource, $dataSourceOptions = null)
     {
+        parent::__construct($dataSource, $dataSourceOptions);
         try {
-            $this->fopenResource = fopen($dataSource, "r");
+            $this->fopenResource = fopen($this->dataSource, 'r');
         } catch (\Exception $e) {
-            throw new DataStreamOpenException("Failed to open data source ".json_encode($dataSource).": ".json_encode($e->getMessage()));
+            throw new DataStreamOpenException('Failed to open data source '.json_encode($this->dataSource).': '.json_encode($e->getMessage()));
         }
     }
 
@@ -26,31 +31,35 @@ public function __destruct()
         fclose($this->fopenResource);
     }
 
-    public function rewind() {
+    public function rewind()
+    {
         if ($this->currentLineNumber == 0) {
             // starting iterations
             $this->currentLineNumber = 1;
         } else {
-            throw new \Exception("DataStream does not support rewinding a stream, sorry");
+            throw new \Exception('DataStream does not support rewinding a stream, sorry');
         }
     }
 
-    public function current() {
+    public function current()
+    {
         return fgets($this->fopenResource);
     }
 
-    public function key() {
+    public function key()
+    {
         return $this->currentLineNumber;
     }
 
-    public function next() {
-        $this->currentLineNumber++;
+    public function next()
+    {
+        ++$this->currentLineNumber;
     }
 
-    public function valid() {
-        return (!feof($this->fopenResource));
+    public function valid()
+    {
+        return !feof($this->fopenResource);
     }
 
     protected $currentLineNumber = 0;
-    protected $fopenResource;
 }