Merge pull request #25 from DivineOmega/feature/php-7.1-minimum

Next major version

.gitignore

@@ -6,3 +6,4 @@ tests/Logs/
 tests/Unit/Data/destination.*
 tests/Unit/Data/JSONFilesDestination/*.json
 src/Examples/**/cache/**
+*.cache

.travis.yml

@@ -1,10 +1,9 @@
 language: php
 dist: trusty
 php:
-  - '5.6'
-  - '7.0'
   - '7.1'
   - '7.2'
+  - '7.3'
 install:
   - composer update
 script:

README.md

@@ -53,7 +53,8 @@ See the sections below for more information on the available source and destinat
 
 ## Migrations
 
-Each UXDM migration requires a source object and at least one destination object. These determine where and how data is read and written. The UXDM package comes with a variety of source and destination objects, including the following.
+Each UXDM migration requires a source object and at least one destination object. These determine where and how data is read and written. 
+The UXDM package works with a variety of source and destination objects, including the following.
 
 * PDO (PHP Database Object) Source & Destination
 * Eloquent (as used in Laravel) Source & Destination
@@ -66,6 +67,8 @@ Each UXDM migration requires a source object and at least one destination object
 * WordPress User Source
 * Debug Output Destination
 
+Some of these are built-in to the core UXDM package, while others are available as separate packages.
+
 Source and destination objects can be used in any combination. Data can be migrated from a CSV and inserted into a database, just as easily as data can be migrated from a database to a CSV.
 
 You can also use similar source and destination objects in the same migration. For example, a common use of UXDM is to use a PDO source and PDO destination to transfer data from one database to another. 
@@ -94,6 +97,41 @@ $migrator->setSource($pdoSource)
 
 This migration will move the `id`, `email` and `name` fields from the the `users` table in the `old-test` database, to the `new_users` table in the `new-test` database, replacing any existing records with the same `id` (the key field).
 
+### Source data validation
+
+You can use UXDM to validate the source data. If validation fails part way through a migration, the migration will 
+halt and a `ValidationException` will be thrown.
+
+The code below shows how to validate various fields.
+
+```php
+$pdoSource = new PDOSource(new PDO('mysql:dbname=old-test;host=127.0.0.1', 'root', 'password123'), 'users');
+
+$pdoDestination = new PDODestination(new PDO('mysql:dbname=new-test;host=127.0.0.1', 'root', 'password456'), 'new_users');
+
+$migrator = new Migrator;
+$migrator->setSource($pdoSource)
+         ->setDestination($pdoDestination)
+         ->setFieldsToMigrate(['id', 'email', 'name'])
+         ->setValidationRules([
+            'id' => [new Required(), new IsNumeric()],
+            'email' => [new Required(), new IsString(), new IsEmail()],
+            'name' => [new Required(), new IsString()],
+         ])
+         ->setKeyFields(['id'])
+         ->withProgressBar()
+         ->migrate();
+```
+
+This migration will validate the source data matches the defined validation rules.
+
+* 'id' must be present, and numeric.
+* 'email' must be present, a string, and a correctly formatted email address.
+* 'name' must be present, and a string.
+
+UXDM uses the [Omega Validator](https://github.com/DivineOmega/omega-validator) package. 
+See its documentation for all available validation rules.
+
 ### Mapping field names from source to destination
 
 This examples shows how UXDM can map field names from source to destination.

composer.json

@@ -8,11 +8,6 @@
             "email": "[email protected]"
         }
     ],
-    "require-dev": {
-        "phpunit/phpunit": "^5.7",
-        "fzaninotto/faker": "^1.6",
-        "php-coveralls/php-coveralls": "^2.0"
-    },
     "autoload": {
         "psr-4": {
             "DivineOmega\\uxdm\\": "src/"
@@ -25,14 +20,19 @@
     },
     "license": "LGPL-3.0-only",
     "require": {
+        "php": ">=7.1",
+        "ext-pdo": "*",
+        "ext-dom": "*",
+        "ext-json": "*",
         "psr/cache": "^1.0",
-        "cache/array-adapter": "^1.0",
-        "illuminate/support": "^5.1",
-        "divineomega/array_undot": "^2.0",
+        "divineomega/array_undot": "^4.1.0",
         "divineomega/php-cli-progress-bar": "^2.0",
-        "illuminate/database": "^5.1",
-        "doctrine/orm": "^2.5",
-        "symfony/property-access": "^3.4",
-        "dompdf/dompdf": "^0.8.2" 
+        "divineomega/omega-validator": "^1.1"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^7.0||^8.0",
+        "fzaninotto/faker": "^1.6",
+        "php-coveralls/php-coveralls": "^2.0",
+        "cache/array-adapter": "^1.0"
     }
 }

docs/destinations/EloquentDestination.md

@@ -3,30 +3,5 @@
 The UXDM Eloquent destination allows you to migrate data into an Eloquent model. This can be handy if you need to migrate data
 into a system using the Eloquent ORM, such as a Laravel project.
 
-## Creating
-
-To create a new Eloquent destination, you must provide it with the class name of Eloquent model you wish to use.
-
-The following example creates a Eloquent destination object, using an Eloquent model called `User` in the `App` namespace.
-
-```php
-$eloquentDestination = new EloquentDestination(\App\User::class);
-```
-
-## Assigning to migrator
-
-To use the Eloquent destination as part of a UXDM migration, you must assign it to the migrator. This process is the same for most destinations.
-
-```php
-$migrator = new Migrator;
-$migrator->setDestination($eloquentDestination);
-```
-
-Alternatively, you can add multiple destinations, as shown below. You can also specify the fields you wish to send to each destination by 
-passing an array of field names as the second parameter.
-
-```php
-$migrator = new Migrator;
-$migrator->addDestination($eloquentDestination, ['field1', 'field2']);
-$migrator->addDestination($otherDestination, ['field3', 'field2']);
-```
+For installation and usage documentation, 
+see the [UXDM Eloquent repository](https://github.com/DivineOmega/uxdm-eloquent).

docs/destinations/PDFDestination.md

@@ -2,70 +2,5 @@
 
 The UXDM PDF destination allows you to migrate data into a PDF table.
 
-## Creating
-
-To create a new PDF destination, you must provide it with the file path 
-of PDF file you wish to export data to. The first row of the PDF table 
-will contain the field names.
-
-The following example creates a PDF destination object, using a PDF 
-file called `users.pdf` in the same directory.
-
-```php
-$pdfFile = __DIR__.'/users.pdf';
-$pdfDestination = new PDFDestination($pdfFile);
-```
-
-## Custom Paper Size & Orientation
-
-You can alter the PDF destination to output PDFs with a custom paper 
-size and orientation. To do this, use the `setPaperSize` and 
-`setPaperOrientation` methods of the PDF destination object, as shown 
-below. 
-
-```php
-$destination->setPaperSize('A5');
-$destination->setPaperOrientation('landscape');
-```
-
-## HTML Prefix & Suffix
-
-Internally, the PDF destination renders a basic HTML table into a PDF. 
-If you wish to style the table, add a heading, or extra content, you can
-add a HTML prefix or HTML suffix.
-
-An example of how to do this is shown below.
-
-```php
-$htmlPrefix = '<h1>My Report</h1>
-            <style>
-                table { width: 100% }
-                h1 { text-align: center; }
-                th { text-transform: capitalize; text-align: center; } 
-                th, td { margin: 0; border: 1px solid #000; }
-            </style>';
-$htmlSuffix = '<p>Created by UXDM</p>';
-
-$destination->setHtmlPrefix($htmlPrefix);
-$destination->setHtmlSuffix($htmlSuffix);
-```
-
-## Assigning to migrator
-
-To use the PDF destination as part of a UXDM migration, you must assign 
-it to the migrator. This process is the same for most destinations.
-
-```php
-$migrator = new Migrator;
-$migrator->setDestination($pdfDestination);
-```
-
-Alternatively, you can add multiple destinations, as shown below. You 
-can also specify the fields you wish to send to each destination by 
-passing an array of field names as the second parameter.
-
-```php
-$migrator = new Migrator;
-$migrator->addDestination($pdfDestination, ['field1', 'field2']);
-$migrator->addDestination($otherDestination, ['field3', 'field2']);
-```
+For installation and usage documentation, 
+see the [UXDM PDF Destination repository](https://github.com/DivineOmega/uxdm-pdf-destination).

docs/sources/EloquentSource.md

@@ -3,29 +3,5 @@
 The UXDM Eloquent source allows you to source data from an Eloquent model. This can be handy if you need to migrate data
 from a system using the Eloquent ORM, such as a Laravel project.
 
-## Creating
-
-To create a new Eloquent source, you must provide it with the class name of Eloquent model you wish to use.
-
-The following example creates a Eloquent source object, using an Eloquent model called `User` in the `App` namespace.
-
-```php
-$eloquentSource = new EloquentSource(\App\User::class);
-```
-
-You can also pass a query callback as a second parameter to restrict the results returned, as shown below.
-
-```php
-$eloquentSource = new EloquentSource(\App\User::class, function($query) {
-    $query->where('id', 1);
-});
-```
-
-## Assigning to migrator
-
-To use the Eloquent source as part of a UXDM migration, you must assign it to the migrator. This process is the same for most sources.
-
-```php
-$migrator = new Migrator;
-$migrator->setSource($eloquentSource);
-```
+For installation and usage documentation, 
+see the [UXDM Eloquent repository](https://github.com/DivineOmega/uxdm-eloquent).

docs/sources/XMLSource.md

@@ -54,7 +54,6 @@ For example, consider the following snippet from an XML sitemap.
 <urlset
       xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-      xmlns:xhtml="http://www.w3.org/1999/xhtml"
       xsi:schemaLocation="
             http://www.sitemaps.org/schemas/sitemap/0.9
             http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd">

src/Examples/PDOtoPDOMigration/Example.php

@@ -43,6 +43,8 @@
                      return true;
                  }
              }
+
+             return false;
          })
          ->withProgressBar()
          ->migrate();

src/Examples/XMLtoCSVMigration/source.xml

@@ -2,7 +2,6 @@
 <urlset
       xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-      xmlns:xhtml="http://www.w3.org/1999/xhtml"
       xsi:schemaLocation="
             http://www.sitemaps.org/schemas/sitemap/0.9
             http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd">

src/Interfaces/DestinationInterface.php

@@ -4,7 +4,7 @@
 
 interface DestinationInterface
 {
-    public function putDataRows(array $dataRows);
+    public function putDataRows(array $dataRows): void;
 
-    public function finishMigration();
+    public function finishMigration(): void;
 }

src/Interfaces/SourceInterface.php

@@ -4,11 +4,11 @@
 
 interface SourceInterface
 {
-    public function getDataRows($page = 1, $fieldsToRetrieve = []);
+    public function getDataRows(int $page = 1, array $fieldsToRetrieve = []): array;
 
-    public function countDataRows();
+    public function countDataRows(): int;
 
-    public function countPages();
+    public function countPages(): int;
 
-    public function getFields();
+    public function getFields(): array;
 }

src/Objects/DataRow.php

@@ -2,7 +2,9 @@
 
 namespace DivineOmega\uxdm\Objects;
 
+use DivineOmega\OmegaValidator\Validator;
 use DivineOmega\uxdm\Objects\Exceptions\NoDataItemsInDataRowException;
+use DivineOmega\uxdm\Objects\Exceptions\ValidationException;
 
 class DataRow
 {
@@ -28,7 +30,17 @@ public function getDataItems()
         return $this->dataItems;
     }
 
-    public function getDataItemByFieldName($fieldName)
+    public function toArray()
+    {
+        $array = [];
+        foreach ($this->dataItems as $dataItem) {
+            $array[$dataItem->fieldName] = $dataItem->value;
+        }
+
+        return $array;
+    }
+
+    public function getDataItemByFieldName(string $fieldName)
     {
         foreach ($this->dataItems as $dataItem) {
             if ($dataItem->fieldName == $fieldName) {
@@ -50,9 +62,9 @@ public function getKeyDataItems()
         return $keyDataItems;
     }
 
-    public function prepare(array $keyFields, array $fieldMap, callable $dataItemManipulator)
+    public function prepare(array $validationRules, array $keyFields, array $fieldMap, callable $dataItemManipulator)
     {
-        $this->validate();
+        $this->validate($validationRules);
         $this->setKeyFields($keyFields);
         $this->mapFields($fieldMap);
 
@@ -61,11 +73,20 @@ public function prepare(array $keyFields, array $fieldMap, callable $dataItemMan
         }
     }
 
-    private function validate()
+    private function validate(array $validationRules)
     {
         if (!$this->dataItems) {
             throw new NoDataItemsInDataRowException('Data row contains no data items. The specified source may be producing an invalid data row.');
         }
+
+        if ($validationRules) {
+            $validator = new Validator($this->toArray(), $validationRules);
+            if ($validator->fails()) {
+                $messages = print_r($validator->messages(), true);
+
+                throw new ValidationException($messages);
+            }
+        }
     }
 
     private function setKeyFields(array $keyFields)

src/Objects/Destinations/AssociativeArrayDestination.php

@@ -13,7 +13,7 @@ public function __construct(array &$array)
         $this->array = &$array;
     }
 
-    public function putDataRows(array $dataRows)
+    public function putDataRows(array $dataRows): void
     {
         foreach ($dataRows as $dataRow) {
             $dataItems = $dataRow->getDataItems();
@@ -28,7 +28,7 @@ public function putDataRows(array $dataRows)
         }
     }
 
-    public function finishMigration()
+    public function finishMigration(): void
     {
     }
 }