Merge pull request #2 from tiny-blocks/release/1.0.0

Release/1.0.0

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: gustavofreze

.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  auto-review:
+    name: Auto review
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Install dependencies
+        run: composer update --no-progress --optimize-autoloader
+
+      - name: Run phpcs
+        run: composer phpcs
+
+      - name: Run phpmd
+        run: composer phpmd
+
+  tests:
+    name: Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Install dependencies
+        run: composer update --no-progress --optimize-autoloader
+
+      - name: Run unit tests
+        env:
+          XDEBUG_MODE: coverage
+        run: composer test
+
+      - name: Run mutation tests
+        run: composer test-mutation

.gitignore

@@ -0,0 +1,5 @@
+.idea
+vendor
+report
+composer.lock
+.phpunit.result.cache

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Tiny Blocks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,22 @@
+DOCKER_RUN = docker run --rm -it --net=host -v ${PWD}:/app -w /app gustavofreze/php:8.1.7
+
+.PHONY: configure test test-no-coverage review show-reports clean
+
+configure:
+	@${DOCKER_RUN} composer update --optimize-autoloader
+
+test: review
+	@${DOCKER_RUN} composer tests
+
+test-no-coverage: review
+	@${DOCKER_RUN} composer tests-no-coverage
+
+review:
+	@${DOCKER_RUN} composer review
+
+show-reports:
+	@sensible-browser report/coverage/coverage-html/index.html report/coverage/mutation-report.html
+
+clean:
+	@sudo chown -R ${USER}:${USER} ${PWD}
+	@rm -rf report vendor

README.md

@@ -1,2 +1,82 @@
-# value-object
-Delimits default behaviors for Value Objects.
+# Value Object
+
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+* [Overview](#overview)
+* [Installation](#installation)
+* [How to use](#how-to-use)
+* [License](#license)
+* [Contributing](#contributing)
+
+<div id='overview'></div> 
+
+## Overview
+
+A **V**alue **O**bject (**VO**) is an immutable type that is only distinguishable by the state of its properties, that
+is, unlike an entity, which has a unique identifier and remains distinct even if its properties are identical, VOs with
+the same properties can be considered the same.
+
+Because they are immutable, VOs cannot be changed once created. Modifying one is conceptually the same as discard the
+old one and create a new one.
+
+More details about [VOs](https://martinfowler.com/bliki/ValueObject.html).
+
+<div id='installation'></div>
+
+## Installation
+
+```bash
+composer require tiny-blocks/value-object
+```
+
+<div id='how-to-use'></div>
+
+## How to use
+
+The library exposes available behaviors through the `ValueObject` interface, and the implementation of these behaviors
+through the `ValueObjectAdapter` trait.
+
+### Concrete implementation
+
+With the implementation of the `ValueObject` interface, and the `ValueObjectAdapter` trait, the use of
+`__get`, `__set` and `__unset` methods is suppressed, making the object immutable.
+
+```php
+<?php
+
+namespace Example;
+
+use TinyBlocks\Vo\ValueObject;
+use TinyBlocks\Vo\ValueObjectAdapter;
+
+final class TransactionId implements ValueObject
+{
+    use ValueObjectAdapter;
+
+    public function __construct(private readonly string $value)
+    {
+    }
+}
+```
+
+### Using the equals method
+
+The `equals` method compares the value of two VOs, and checks if they are equal.
+
+```php
+$transactionId = new TransactionId(value: 'e6e2442f-3bd8-421f-9ac2-f9e26ac4abd2');
+$otherTransactionId = new TransactionId(value: 'e6e2442f-3bd8-421f-9ac2-f9e26ac4abd2');
+
+echo $transactionId->equals(other: $otherTransactionId); # 1 (true)
+```
+
+## License
+
+Math is licensed under [MIT](/LICENSE).
+
+<div id='contributing'></div>
+
+## Contributing
+
+Please follow the [contributing guidelines](https://github.com/tiny-blocks/tiny-blocks/blob/main/CONTRIBUTING.md) to
+contribute to the project.

composer.json

@@ -0,0 +1,68 @@
+{
+    "name": "tiny-blocks/value-object",
+    "type": "library",
+    "license": "MIT",
+    "homepage": "https://github.com/tiny-blocks/value-object",
+    "description": "Delimits default behaviors for Value Objects.",
+    "prefer-stable": true,
+    "minimum-stability": "stable",
+    "keywords": [
+        "vo",
+        "psr",
+        "psr-4",
+        "psr-12",
+        "tiny-blocks",
+        "value-object"
+    ],
+    "authors": [
+        {
+            "name": "Gustavo Freze de Araujo Santos",
+            "homepage": "https://github.com/gustavofreze"
+        }
+    ],
+    "config": {
+        "sort-packages": true,
+        "allow-plugins": {
+            "infection/extension-installer": true
+        }
+    },
+    "autoload": {
+        "psr-4": {
+            "TinyBlocks\\Vo\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "TinyBlocks\\Vo\\": "tests/"
+        }
+    },
+    "require": {
+        "php": "^8.1"
+    },
+    "require-dev": {
+        "infection/infection": "^0.26",
+        "phpmd/phpmd": "^2.12",
+        "phpunit/phpunit": "^9.5",
+        "squizlabs/php_codesniffer": "^3.7"
+    },
+    "scripts": {
+        "phpcs": "phpcs --standard=PSR12 --extensions=php ./src",
+        "phpmd": "phpmd ./src text phpmd.xml --suffixes php --ignore-violations-on-exit",
+        "test": "phpunit --log-junit=report/coverage/junit.xml --coverage-xml=report/coverage/coverage-xml --coverage-html=report/coverage/coverage-html tests",
+        "test-mutation": "infection --only-covered --logger-html=report/coverage/mutation-report.html --coverage=report/coverage --min-msi=100 --min-covered-msi=100 --threads=4",
+        "test-no-coverage": "phpunit --no-coverage",
+        "test-mutation-no-coverage": "infection --only-covered --min-msi=100 --threads=4",
+        "review": [
+            "@phpcs",
+            "@phpmd"
+        ],
+        "tests": [
+            "@test",
+            "@test-mutation"
+        ],
+        "tests-no-coverage": [
+            "@test-no-coverage",
+            "@test-mutation-no-coverage"
+        ]
+    }
+}

infection.json.dist

@@ -0,0 +1,23 @@
+{
+    "timeout": 10,
+    "testFramework": "phpunit",
+    "tmpDir": "report/",
+    "source": {
+        "directories": [
+            "src"
+        ]
+    },
+    "logs": {
+        "text": "report/logs/infection-text.log",
+        "summary": "report/logs/infection-summary.log"
+    },
+    "mutators": {
+        "@default": true,
+        "PublicVisibility": false,
+        "ProtectedVisibility": false
+    },
+    "phpUnit": {
+        "configDir": "",
+        "customPath": "./vendor/bin/phpunit"
+    }
+}

phpmd.xml

@@ -0,0 +1,57 @@
+<?xml version="1.0"?>
+<ruleset name="PHPMD Custom rules"
+         xmlns="http://pmd.sf.net/ruleset/1.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://pmd.sf.net/ruleset/1.0.0 http://pmd.sf.net/ruleset_xml_schema.xsd"
+         xsi:noNamespaceSchemaLocation="http://pmd.sf.net/ruleset_xml_schema.xsd">
+    <description>PHPMD Custom rules</description>
+
+    <rule ref="rulesets/cleancode.xml/ElseExpression"/>
+    <rule ref="rulesets/cleancode.xml/BooleanArgumentFlag"/>
+
+    <rule ref="rulesets/codesize.xml/TooManyFields"/>
+    <rule ref="rulesets/codesize.xml/TooManyMethods"/>
+    <rule ref="rulesets/codesize.xml/NPathComplexity"/>
+    <rule ref="rulesets/codesize.xml/CyclomaticComplexity"/>
+    <rule ref="rulesets/codesize.xml/ExcessivePublicCount"/>
+    <rule ref="rulesets/codesize.xml/ExcessiveClassLength"/>
+    <rule ref="rulesets/codesize.xml/TooManyPublicMethods"/>
+    <rule ref="rulesets/codesize.xml/ExcessiveMethodLength"/>
+    <rule ref="rulesets/codesize.xml/ExcessiveParameterList"/>
+    <rule ref="rulesets/codesize.xml/ExcessiveClassComplexity"/>
+
+    <rule ref="rulesets/controversial.xml/Superglobals"/>
+    <rule ref="rulesets/controversial.xml/CamelCaseClassName"/>
+    <rule ref="rulesets/controversial.xml/CamelCaseMethodName"/>
+    <rule ref="rulesets/controversial.xml/CamelCasePropertyName"/>
+    <rule ref="rulesets/controversial.xml/CamelCaseVariableName"/>
+    <rule ref="rulesets/controversial.xml/CamelCaseParameterName"/>
+
+    <rule ref="rulesets/design.xml/GotoStatement"/>
+    <rule ref="rulesets/design.xml/ExitExpression"/>
+    <rule ref="rulesets/design.xml/EvalExpression"/>
+    <rule ref="rulesets/design.xml/NumberOfChildren"/>
+    <rule ref="rulesets/design.xml/DepthOfInheritance"/>
+    <rule ref="rulesets/design.xml/CouplingBetweenObjects"/>
+    <rule ref="rulesets/design.xml/DevelopmentCodeFragment"/>
+
+    <rule ref="rulesets/naming.xml/LongVariable"/>
+    <rule ref="rulesets/naming.xml/ShortVariable">
+        <properties>
+            <property name="minimum" value="2"/>
+        </properties>
+    </rule>
+    <rule ref="rulesets/naming.xml/ShortMethodName">
+        <properties>
+            <property name="minimum" value="2"/>
+        </properties>
+    </rule>
+    <rule ref="rulesets/naming.xml/BooleanGetMethodName"/>
+    <rule ref="rulesets/naming.xml/ConstantNamingConventions"/>
+    <rule ref="rulesets/naming.xml/ConstructorWithNameAsEnclosingClass"/>
+
+    <rule ref="rulesets/unusedcode.xml/UnusedPrivateField"/>
+    <rule ref="rulesets/unusedcode.xml/UnusedLocalVariable"/>
+    <rule ref="rulesets/unusedcode.xml/UnusedPrivateMethod"/>
+    <rule ref="rulesets/unusedcode.xml/UnusedFormalParameter"/>
+</ruleset>

phpunit.xml

@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         bootstrap="vendor/autoload.php"
+         cacheResultFile="report/.phpunit.result.cache"
+         backupGlobals="false"
+         backupStaticAttributes="false"
+         colors="true"
+         convertErrorsToExceptions="true"
+         convertNoticesToExceptions="true"
+         convertWarningsToExceptions="true"
+         processIsolation="false"
+         stopOnFailure="false"
+         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd">
+    <testsuites>
+        <testsuite name="default">
+            <directory suffix="Test.php">tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <coverage>
+        <include>
+            <directory suffix=".php">src</directory>
+        </include>
+    </coverage>
+</phpunit>

src/Internal/Exceptions/InvalidProperty.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace TinyBlocks\Vo\Internal\Exceptions;
+
+use RuntimeException;
+
+final class InvalidProperty extends RuntimeException
+{
+    public function __construct(string $key, string $class)
+    {
+        $template = 'Invalid property <%s> for class <%s>.';
+        parent::__construct(sprintf($template, $key, $class));
+    }
+}

src/Internal/Exceptions/PropertyCannotBeChanged.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace TinyBlocks\Vo\Internal\Exceptions;
+
+use RuntimeException;
+
+final class PropertyCannotBeChanged extends RuntimeException
+{
+    public function __construct(string $key, string $class)
+    {
+        $template = 'Property <%s> cannot be changed in class <%s>.';
+        parent::__construct(sprintf($template, $key, $class));
+    }
+}