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:https://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;
+}