Merge pull request #19 from shadz3rg/feature-php74

Improve code-quality

.github/workflows/php.yml

@@ -0,0 +1,39 @@
+name: PHP Composer
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+
+    runs-on: xhrequest/symfony_common:version-1.10.0-pcov
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Validate composer.json and composer.lock
+      run: composer validate --strict
+
+    - name: Cache Composer packages
+      id: composer-cache
+      uses: actions/cache@v3
+      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
+
+    - name: Run test suite
+      run: composer run-script test
+
+    - name: Check code quality
+      run: composer run-script cq

.gitignore

@@ -1,7 +1,7 @@
 .idea/
 vendor/
 composer.lock
-composer.phar
-.htaccess
-index.php
-static/
+.php_cs.cache
+.php-cs-fixer.cache
+.phpunit.result.cache
+coverage/

.php-cs-fixer.dist.php

@@ -0,0 +1,13 @@
+<?php
+
+$finder = PhpCsFixer\Finder::create()->in('src/');
+
+$config = new PhpCsFixer\Config();
+return $config
+    ->setRules([
+        '@Symfony' => true,
+        'array_syntax' => ['syntax' => 'short'],
+        'yoda_style' => false,
+        'ordered_imports' => ['imports_order' => ['class', 'function', 'const'], 'sort_algorithm' => 'alpha']
+    ])
+    ->setFinder($finder);

composer.json

@@ -1,12 +1,13 @@
 {
     "name": "shadz3rg/php-stamp",
     "description": "The XSL-way templating library for MS Office Word DOCX documents.",
-    "homepage": "https://github.com/shadz3rg/PHPStamp",
+    "homepage": "https://github.com/shadz3rg/php-stamp",
     "type": "library",
     "keywords": ["docx", "template", "word"],
     "license": "MIT",
     "require": {
-        "php": ">=5.3.0",
+        "php": "^7.4",
+        "ext-json": "*",
         "ext-xsl": "*",
         "ext-zip": "*",
         "ext-dom": "*",
@@ -19,8 +20,21 @@
         }
     ],
     "autoload": {
-        "psr-0": {
-            "PHPStamp": "src/"
+        "psr-4": {
+            "PHPStamp\\": "src/PHPStamp",
+            "PHPStamp\\Tests\\": "tests/"
         }
+    },
+    "require-dev": {
+        "phpstan/phpstan": "^1.10",
+        "ekino/phpstan-banned-code": "^1.0",
+        "friendsofphp/php-cs-fixer": "^3.22",
+        "phpunit/phpunit": "^9.6"
+    },
+    "scripts": {
+        "codequality": "phpstan analyse -c phpstan.neon --level=max && php-cs-fixer fix --config=.php-cs-fixer.dist.php -v --dry-run",
+        "cq": "@codequality",
+        "cs": "php-cs-fixer fix --config=.php-cs-fixer.dist.php -v",
+        "test": "phpunit --testsuite=Unit --coverage-html=coverage"
     }
 }

docker-compose.yml

@@ -0,0 +1,12 @@
+version: '3.7'
+
+x-php: &common-php-container
+  image: xhrequest/symfony_common:version-1.10.0-pcov
+  working_dir: /var/www/app
+  volumes:
+    - .:/var/www/app:cached
+
+services:
+  test_platform:
+    <<: *common-php-container
+    command: ["php", "-v"]

phpstan.neon

@@ -0,0 +1,13 @@
+includes:
+    - vendor/ekino/phpstan-banned-code/extension.neon
+parameters:
+    paths:
+        - src/
+        - tests/
+    banned_code:
+        nodes:
+            - type: Expr_FuncCall
+              functions:
+                  - dump
+                  - var_dump
+                  - echo

phpunit.xml

@@ -1,19 +1,24 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit backupGlobals="false"
-         backupStaticAttributes="false"
-         colors="true"
-         convertErrorsToExceptions="true"
-         convertNoticesToExceptions="true"
-         convertWarningsToExceptions="true"
-         processIsolation="false"
-         stopOnFailure="false"
-         stopOnError="false"
-         stopOnIncomplete="false"
-         stopOnSkipped="false"
-         bootstrap="vendor/autoload.php">
+<!-- https://phpunit.de/manual/current/en/appendixes.configuration.html -->
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.6/phpunit.xsd" backupGlobals="false" defaultTestSuite="Unit">
+    <coverage>
+        <include>
+            <directory>.</directory>
+        </include>
+        <exclude>
+            <directory suffix=".php">tests</directory>
+            <directory>vendor</directory>
+        </exclude>
+    </coverage>
     <testsuites>
-        <testsuite name="Main Suite">
-            <directory>tests/</directory>
+        <testsuite name="Unit">
+            <directory>tests/Unit</directory>
+        </testsuite>
+        <testsuite name="Integration">
+            <directory>tests/Integration</directory>
         </testsuite>
     </testsuites>
-</phpunit>
+    <php>
+        <ini name="memory_limit" value="512M"/>
+    </php>
+</phpunit>

src/PHPStamp/Core/CommentTransformer.php

@@ -2,27 +2,43 @@
 
 namespace PHPStamp\Core;
 
+use PHPStamp\Exception\DecodeException;
+use PHPStamp\Exception\EncodeException;
+
 class CommentTransformer
 {
     /**
      * Represent META array as string.
      *
-     * @param array $comment
-     * @return string
+     * @param array<string,mixed> $comment
+     *
+     * @throws EncodeException
      */
-    public function transform(array $comment)
+    public function transform(array $comment): string
     {
-        return json_encode($comment);
+        $output = json_encode($comment, JSON_FORCE_OBJECT);
+        if ($output === false) {
+            throw new EncodeException();
+        }
+
+        return $output;
     }
 
     /**
      * Decode string into META array.
      *
-     * @param $comment
-     * @return mixed
+     * @return array<string,mixed> $comment
+     *
+     * @throws DecodeException
      */
-    public function reverseTransformer($comment)
+    public function reverseTransformer(string $comment): array
     {
-        return json_decode($comment, true);
+        /** @var array<string,mixed>|null $output */
+        $output = json_decode($comment, true);
+        if ($output === null) {
+            throw new DecodeException();
+        }
+
+        return $output;
     }
-}
+}

src/PHPStamp/Document/Document.php

@@ -2,15 +2,17 @@
 
 namespace PHPStamp\Document;
 
+use PHPStamp\Exception\HashException;
 use PHPStamp\Exception\InvalidArgumentException;
+use PHPStamp\Extension\ExtensionInterface;
 use PHPStamp\Processor\Tag;
 
 abstract class Document implements DocumentInterface
 {
-    const XPATH_PARAGRAPH  = 0;
-    const XPATH_RUN  = 1;
-    const XPATH_RUN_PROPERTY  = 2;
-    const XPATH_TEXT  = 3;
+    public const XPATH_PARAGRAPH = 0;
+    public const XPATH_RUN = 1;
+    public const XPATH_RUN_PROPERTY = 2;
+    public const XPATH_TEXT = 3;
 
     /**
      * Original document filename.
@@ -30,6 +32,7 @@ abstract class Document implements DocumentInterface
      * Creates a new Document.
      *
      * @param string $documentPath
+     *
      * @throws InvalidArgumentException
      */
     public function __construct($documentPath)
@@ -45,26 +48,26 @@ public function __construct($documentPath)
     /**
      * Extract main content file.
      *
-     * @param string $to Path to extract content file.
-     * @param bool $overwrite Overwrite content file.
-     * @return string Full path to extracted document file.
+     * @param string $to        path to extract content file
+     * @param bool   $overwrite overwrite content file
+     *
+     * @return string full path to extracted document file
+     *
      * @throws InvalidArgumentException
      */
     public function extract($to, $overwrite)
     {
-        $filePath = $to . $this->getDocumentName() . '/' . $this->getContentPath();
+        $filePath = $to.$this->getDocumentName().'/'.$this->getContentPath();
 
         if (!file_exists($filePath) || $overwrite === true) {
             $zip = new \ZipArchive();
 
             $code = $zip->open($this->getDocumentPath());
             if ($code !== true) {
-                throw new InvalidArgumentException(
-                    'Can`t open archive "' . $this->documentPath . '", code "' . $code . '" returned.'
-                );
+                throw new InvalidArgumentException('Can`t open archive "'.$this->documentPath.'", code "'.$code.'" returned.');
             }
 
-            if ($zip->extractTo($to . $this->documentName, $this->getContentPath()) === false) {
+            if ($zip->extractTo($to.$this->documentName, $this->getContentPath()) === false) {
                 throw new InvalidArgumentException('Destination not reachable.');
             }
         }
@@ -77,7 +80,12 @@ public function extract($to, $overwrite)
      */
     public function getDocumentHash()
     {
-        return md5_file($this->documentPath);
+        $hash = md5_file($this->documentPath);
+        if ($hash === false) {
+            throw new HashException();
+        }
+
+        return $hash;
     }
 
     /**
@@ -98,31 +106,32 @@ public function getDocumentPath()
 
     /**
      * @inherit
-     * @param \DOMDocument $template
      */
-    public abstract function cleanup(\DOMDocument $template);
+    abstract public function cleanup(\DOMDocument $template);
 
     /**
      * @inherit
      */
-    public abstract function getContentPath();
+    abstract public static function getContentPath();
 
     /**
      * @inherit
      */
-    public abstract function getNodePath();
+    abstract public function getNodePath();
 
     /**
      * @inherit
-     * @param int $type XPATH_* constant.
-     * @param bool $global Append global xpath //.
+     *
+     * @param int  $type   XPATH_* constant
+     * @param bool $global append global xpath //
      */
-    public abstract function getNodeName($type, $global = false);
+    abstract public function getNodeName($type, $global = false);
 
     /**
      * @inherit
-     * @param string $id Id as entered in placeholder.
-     * @param Tag $tag Container tag.
+     *
+     * @param string $id  id as entered in placeholder
+     * @param Tag    $tag container tag
      */
-    public abstract function getExpression($id, Tag $tag);
-}
+    abstract public function getExpression(string $id, Tag $tag): ExtensionInterface;
+}