Merge pull request #11 from alex-patterson-webdev/feature/0.5.0

Feature/0.5.0

.php_cs.dist → .php-cs-fixer.dist

@@ -6,7 +6,6 @@ use PhpCsFixer\Finder;
 
 $rules = [
     '@PSR12' => true,
-    'class_definition' => false,
 ];
 
 /** @var iterable<string> $finder */

README.md

@@ -6,14 +6,14 @@
 
 ## About
 
-The library provides a number of factory interfaces which abstract the creation of native PHP DateTime classes, 
-`\DateTime`, `DateTimeImmutible`, `\DateInterval` and `\DateTimeZone`.
+The library provides a number of factory interfaces which abstracts 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 ^0.4
+    require alex-patterson-webdev/date-time ^0.5
 
 ## Theory
 
@@ -54,6 +54,77 @@ The approach has a number of notable benefits
 - 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`.
 
+## DateTimeFactoryInterface
+
+The `DateTimeFactoryInterface` exposes two public methods, `createDateTime()` and `createFromFormat()`. The method signatures are
+similar to the PHP `\DateTime` methods. 
+
+    interface DateTimeFactoryInterface
+    {
+        /**
+         * @throws DateTimeFactoryException
+         */
+        public function createDateTime(?string $spec = null, $timeZone = null): \DateTimeInterface;
+
+        /**
+         * @throws DateTimeFactoryException
+         */
+        public function createFromFormat(string $format, string $spec, $timeZone = null): \DateTimeInterface;
+    }
+
+The `createDateTime()` method can replace uses of [\DateTime::__construct](https://www.php.net/manual/en/datetime.construct.php).
+The `createFromFormat()` method can replace uses of [\DateTime::createFromFormat()](https://www.php.net/manual/en/datetime.createfromformat.php).
+
+There are however a number of differences to consider.
+
+- The methods of the interface are defined as non-static and require a factory instance to invoke them.
+- A `DateTimeFactoryException` will be thrown if the `\DateTime` instance cannot be created.
+- The `$spec` parameter of `createDateTime()` accepts `null`. Passing `null` is equivalent to using the current date and time, i.e. `now`.
+- The `$timeZone` can be either a `string` or `\DateTimeZone` instance. If a [supported `DateTimeZone` string](https://www.php.net/manual/en/timezones.php) 
+  is provided, the `\DateTimeZone` instance will be created internally; otherwise a `DateTimeFactoryException` will be thrown.
+
+### Implementations
+
+The package provides two default implementations of the `DateTimeFactoryInterface`.
+
+- `DateTimeFactory` can be used to create `\DateTime` instances.
+- `DateTimeImmutableFactory` can be used to create `\DateTimeImmutible` instances
+
+Because both classes implement the `DateTimeFactoryInterface`, they can be used in the same way.
+
+    $dateTimeFactory = new \Arp\DateTime\DateTimeFactory();
+    $dateTimeImmutableFactory = new \Arp\DateTime\DateTimeImmutableFactory();
+
+    try {
+        /** @var \DateTime $dateTime **/
+        $dateTime = $dateTimeFactory->createDateTime();
+
+        /** @var \DateTimeImmutable $dateTimeImmutable **/
+        $dateTimeImmutable = $dateTimeImmutableFactory->createDateTime();
+    } catch (\DateTimeFactoryException $e) {
+        // if the date creation fails
+    }
+
+### DateTimeZoneFactory
+
+`\DateTimeZone` instances can be created using any class that implements `Arp\DateTime\DateTimeZoneFactoryInterface`.
+
+    /*
+     * @throws DateTimeZoneFactoryException
+     */
+    public function createDateTimeZone(string $spec): \DateTimeZone;
+
+The default implementation of the interface is `Arp\DateTime\DateTimeZoneFactory`.
+
+    $dateTimeZoneFactory = new \Arp\DateTime\DateTimeZoneFactory();
+
+    try { 
+        /** @var \DateTimeZone $dateTimeZone **/
+        $dateTimeZone = $dateTimeZoneFactory->createDateTimeZone('UTC');
+    } catch (\DateTimeZoneFactoryException $e) {
+        // The \DateTimeZone() could not be created
+    }
+
 ## Unit tests
 
 Unit tests can be executed using PHPUnit from the application root directory.

composer.json

@@ -14,10 +14,11 @@
     "php" : ">=7.4 || >=8.0"
   },
   "require-dev": {
+    "phpspec/prophecy": "^1.15.0",
     "phpunit/phpunit": "^9.5",
-    "squizlabs/php_codesniffer": "^3.5",
-    "phpstan/phpstan": ">=0.12",
-    "friendsofphp/php-cs-fixer": "^2.18"
+    "squizlabs/php_codesniffer": "^3.6",
+    "phpstan/phpstan": "^1.4.8",
+    "friendsofphp/php-cs-fixer": "^3.6.0"
   },
   "autoload": {
     "psr-4": {
@@ -40,14 +41,13 @@
       "@arp:check",
       "@arp:lint",
       "@arp:fix",
-      "@arp:analyse-max",
+      "@arp:analyse",
       "@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:lint": "php vendor/bin/php-cs-fixer fix --dry-run --verbose --config=.php-cs-fixer.dist",
+    "arp:fix": "php vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.dist",
+    "arp:analyse": "php vendor/bin/phpstan analyse -c phpstan.neon --level=7",
     "arp:unit-test": "php vendor/bin/phpunit",
     "arp:unit-test-with-coverage": [
       "@putenv XDEBUG_MODE=coverage",