Merge pull request #10 from alex-patterson-webdev/feature/0.4.0

Feature/0.4.0

.github/workflows/workflow.yml

@@ -0,0 +1,52 @@
+name: CI Pipeline
+
+on:
+  push:
+    branches:
+      - master
+      - feature/*
+  pull_request:
+    branches:
+      - master
+      - feature/*
+
+jobs:
+  test:
+    name: "Integration Test Suite"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: "Validate composer.json and composer.lock"
+        run: composer validate --strict
+
+      - name: "Cache Composer packages"
+        id: composer-cache
+        uses: actions/cache@v2
+        with:
+          path: vendor
+          key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-php-
+
+      - name: "Install dependencies"
+        run: composer install --prefer-dist --no-progress --no-suggest
+
+      - name: "Check coding standards"
+        run: composer arp:check
+
+      - name: "Checking for solutions to code formatting"
+        run: composer arp:lint
+
+      - name: "Running static analysis checks"
+        run: composer arp:analyse
+
+      - name: "Running unit tests with code coverage"
+        run: composer arp:unit-test-with-coverage
+
+      - name: "Uploading code coverage report to Codecov"
+        uses: codecov/[email protected]
+        with:
+          files: ./test/coverage/clover.xml
+          fail_ci_if_error: true
+          verbose: true

.gitignore

@@ -2,6 +2,7 @@ vendor/
 .idea/
 composer.phar
 .phpunit.result.cache
+test/coverage/
 coverage.xml
 clover.xml
 .php_cs.cache

.php_cs.dist

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpCsFixer\Finder;
+
+$rules = [
+    '@PSR12' => true,
+    'class_definition' => false,
+];
+
+/** @var iterable<string> $finder */
+$finder = Finder::create()
+    ->exclude('node_modules')
+    ->exclude('vendor')
+    ->in([
+        __DIR__ . '/src/',
+        __DIR__ . '/test/unit/',
+    ]);
+
+return (new PhpCsFixer\Config())
+    ->setRules($rules)
+    ->setFinder($finder)
+    ->setUsingCache(false);
+

.scrutinizer.yml

@@ -22,6 +22,8 @@ coding_style:
         linefeed_character: return-newline
       before_parentheses:
         closure_definition: true
+      around_operators:
+        concatenation: true
 filter:
   dependency_paths:
     - "vendor/"

README.md

@@ -1,27 +1,61 @@
-[![Build Status](https://travis-ci.com/alex-patterson-webdev/date-time.svg?branch=master)](https://travis-ci.com/alex-patterson-webdev/date-time)
+![build](https://github.com/alex-patterson-webdev/date-time/actions/workflows/workflow.yml/badge.svg)
 [![codecov](https://codecov.io/gh/alex-patterson-webdev/date-time/branch/master/graph/badge.svg)](https://codecov.io/gh/alex-patterson-webdev/date-time)
 [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/alex-patterson-webdev/date-time/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/alex-patterson-webdev/date-time/?branch=master)
 
-# About
+# Arp\DateTime
 
-The `Arp\DateTime` module provides date and time abstractions for the built in PHP classes `DateTime`, `DateTimeImmutable` and `DateInterval`.
+## About
 
-# Installation
+The library provides a number of factory interfaces which abstract the creation of native PHP DateTime classes, 
+`\DateTime`, `DateTimeImmutible`, `\DateInterval` and `\DateTimeZone`.
+
+## Installation
 
 Installation via [composer](https://getcomposer.org).
 
-    require alex-patterson-webdev/date-time ^2
-
-## DateTimeFactory
+    require alex-patterson-webdev/date-time ^0.4
+
+## Theory
+
+By abstracting the creation of Date Time objects behind a simple collection of interfaces, we can allow developers to treat date time creation as a service.
+The `Arp\DateTime\DateTimeFactory` can be used as a replacement for any code that would normally require `new \DateTime()`.
+
+Consider an example `UserService::updateLastLoginDate()` method; designed to update a user's last login date with the current date and time.
+
+    class UserService
+    {
+        public function updateLastLoginDate($user)
+        {
+            $user->setLastLoginDate(new \DateTime());
+        }
+    }
+
+This approach, while simple, would be difficult to assert a value for the 'current time' in a unit test. Alternatively, we could update this
+example to include the `DateTimeFactory`, which would abstract the creation of the `\DateTime` object. 
+
+    class UserService
+    {
+        private DateTimeFactoryInterface $dateTimeFactory;
+
+        public function __construct(DateTimeFactoryInterface $dateTimeFactory)
+        {
+            $this->dateTimeFactory = $dateTimeFactory;
+        }
 
-The `Arp\DateTime\DateTimeFactory` can be used as a replacement for any calls that would normally require `new \DateTime()`.
+        public function updateLastLoginDate($user)
+        {
+            $user->setLastLoginDate($this->dateTimeFactory->createDateTime());
+        }
+    }
 
-## DateIntervalFactory
+The approach has a number of notable benefits
 
-The `Arp\DateTime\DateIntervalFactory` can be used as a replacement for any calls that would normally require `new \DateInterval()`.
+- The `DateTimeFactoryInterface` provides an abstraction for all `\DateTime` object creation.
+- Unit testing and asserting date time values becomes very easy as we can now mock the return value of `$this->dateTimeFactory->createDateTime()`.
+- Rather than returning a boolean `false` when unable to create date objects, the factory classes will instead throw a `DateTimeException`.
 
-## Unit Tests
+## Unit tests
 
-Unit test using PHP Unit.
+Unit tests can be executed using PHPUnit from the application root directory.
 
     php vendor/bin/phpunit

composer.json

@@ -1,5 +1,6 @@
 {
   "name": "alex-patterson-webdev/date-time",
+  "description": "DateTime factory components for PHP",
   "minimum-stability": "dev",
   "prefer-stable": true,
   "license": "MIT",
@@ -10,11 +11,13 @@
     }
   ],
   "require" : {
-    "php" : ">=7.4",
-    "alex-patterson-webdev/factory": "^1"
+    "php" : ">=7.4 || >=8.0"
   },
   "require-dev": {
-    "phpunit/phpunit": "^9.3"
+    "phpunit/phpunit": "^9.5",
+    "squizlabs/php_codesniffer": "^3.5",
+    "phpstan/phpstan": ">=0.12",
+    "friendsofphp/php-cs-fixer": "^2.18"
   },
   "autoload": {
     "psr-4": {
@@ -23,14 +26,35 @@
   },
   "autoload-dev": {
     "psr-4": {
-      "ArpTest\\DateTime\\" : "test/phpunit/"
+      "ArpTest\\DateTime\\" : "test/unit/"
     }
   },
   "scripts": {
-    "test": "php vendor/bin/phpunit --coverage-clover=coverage.xml"
+    "arp:test": [
+      "@arp:check",
+      "@arp:lint",
+      "@arp:analyse",
+      "@arp:unit-test-with-coverage"
+    ],
+    "arp:test-dev": [
+      "@arp:check",
+      "@arp:lint",
+      "@arp:fix",
+      "@arp:analyse-max",
+      "@arp:unit-test"
+    ],
+    "arp:check": "php vendor/bin/phpcs -s --standard=phpcs.xml --colors src/ test/",
+    "arp:lint": "php vendor/bin/php-cs-fixer fix --dry-run --verbose --config=.php_cs.dist",
+    "arp:fix": "php vendor/bin/php-cs-fixer fix --config=.php_cs.dist",
+    "arp:analyse": "php vendor/bin/phpstan analyse src/ test/ --level=7",
+    "arp:analyse-max": "php vendor/bin/phpstan analyse src/ test/ --level=8",
+    "arp:unit-test": "php vendor/bin/phpunit",
+    "arp:unit-test-with-coverage": [
+      "@putenv XDEBUG_MODE=coverage",
+      "php vendor/bin/phpunit --coverage-clover=test/coverage/clover.xml"
+    ]
   },
   "config": {
-    "preferred-install": "dist",
     "optimize-autoloader": true,
     "sort-packages": true
   }