Release/1.0.0 (#2)

.gitattributes

@@ -0,0 +1,14 @@
+/tests export-ignore
+/vendor export-ignore
+
+/LICENSE export-ignore
+/Makefile export-ignore
+/README.md export-ignore
+/phpmd.xml export-ignore
+/phpunit.xml export-ignore
+/phpstan.neon.dist export-ignore
+/infection.json.dist export-ignore
+
+/.github export-ignore
+/.gitignore export-ignore
+/.gitattributes export-ignore

.github/workflows/auto-assign.yml

@@ -0,0 +1,22 @@
+name: Auto assign issues
+
+on:
+  issues:
+    types:
+      - opened
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - name: Assign issues
+        uses: gustavofreze/[email protected]
+        with:
+          assignees: '${{ secrets.ASSIGNEES }}'
+          github_token: '${{ secrets.GITHUB_TOKEN }}'
+          allow_self_assign: 'true'
+          allow_no_assignees: 'true'
+          assignment_options: 'ISSUE'

.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+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: Use PHP 8.2
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+
+      - 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: Use PHP 8.2
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+
+      - 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-2024 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,25 @@
+DOCKER_RUN = docker run --rm -it --net=host -v ${PWD}:/app -w /app gustavofreze/php:8.2
+
+.PHONY: configure test test-file test-no-coverage review show-reports clean
+
+configure:
+	@${DOCKER_RUN} composer update --optimize-autoloader
+
+test:
+	@${DOCKER_RUN} composer tests
+
+test-file:
+	@${DOCKER_RUN} composer tests-file-no-coverage ${FILE}
+
+test-no-coverage:
+	@${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 .phpunit.cache

README.md

@@ -1 +1,92 @@
-# immutable-object
+# Immutable 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
+
+The **Immutable Object** library ensures that objects implementing it remain immutable after initialization. Once
+created, the state of the object cannot be modified. Any attempt to change properties or collection elements will throw
+an exception.
+
+<div id='installation'></div>
+
+## Installation
+
+```bash
+composer require tiny-blocks/immutable-object
+```
+
+<div id='how-to-use'></div>
+
+## How to use
+
+The library provides the `Immutable` interface and the `Immutability` trait to guarantee immutability. These components
+prevent properties and collections from being modified or unset.
+
+### Concrete implementation
+
+By implementing the `Immutable` interface and using the `Immutability` trait, you can ensure that object properties and
+elements in collections are immutable.
+
+```php
+<?php
+
+namespace Example;
+
+use TinyBlocks\Immutable\Immutable;
+use TinyBlocks\Immutable\Immutability;
+
+final class Order implements Immutable
+{
+    use Immutability;
+
+    public function __construct(public int $id, public Products $products)
+    {
+    }
+}
+```
+
+#### Handling property immutability
+
+The Immutability trait also prevents modifications to properties of an object. Trying to modify a property after the
+object is initialized will throw an exception.
+
+```php
+$order = new Order(id: 1, products: new Products(array: ['item1', 'item2']);
+
+$order->id = 2;    # Throws an exception
+unset($order->id); # Throws an exception  
+```
+
+#### Handling collection immutability
+
+The `Immutability` trait also prevents the modification of collection elements (e.g., arrays). Trying to modify or
+remove an element will throw an exception.
+
+```php
+$order = new Order(id: 1, products: new Products(array: ['item1', 'item2']);
+
+$order->items[0] = 'item3'; # Throws an exception
+unset($order->items[0]);    # Throws an exception
+```
+
+<div id='license'></div>
+
+## License
+
+Immutable Object 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,74 @@
+{
+    "name": "tiny-blocks/immutable-object",
+    "type": "library",
+    "license": "MIT",
+    "homepage": "https://github.com/tiny-blocks/immutable-object",
+    "description": "Provides immutable behavior for objects.",
+    "prefer-stable": true,
+    "minimum-stability": "stable",
+    "keywords": [
+        "vo",
+        "psr",
+        "tiny-blocks",
+        "immutability",
+        "immutable-object"
+    ],
+    "authors": [
+        {
+            "name": "Gustavo Freze de Araujo Santos",
+            "homepage": "https://github.com/gustavofreze"
+        }
+    ],
+    "support": {
+        "issues": "https://github.com/tiny-blocks/immutable-object/issues",
+        "source": "https://github.com/tiny-blocks/immutable-object"
+    },
+    "config": {
+        "sort-packages": true,
+        "allow-plugins": {
+            "infection/extension-installer": true
+        }
+    },
+    "autoload": {
+        "psr-4": {
+            "TinyBlocks\\Immutable\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "TinyBlocks\\Immutable\\": "tests/"
+        }
+    },
+    "require": {
+        "php": "^8.2"
+    },
+    "require-dev": {
+        "phpmd/phpmd": "^2.15",
+        "phpunit/phpunit": "^11",
+        "phpstan/phpstan": "^1",
+        "infection/infection": "^0.29",
+        "squizlabs/php_codesniffer": "^3.10"
+    },
+    "scripts": {
+        "phpcs": "phpcs --standard=PSR12 --extensions=php ./src",
+        "phpmd": "phpmd ./src text phpmd.xml --suffixes php --ignore-violations-on-exit",
+        "phpstan": "phpstan analyse -c phpstan.neon.dist --quiet --no-progress",
+        "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",
+            "@phpstan"
+        ],
+        "tests": [
+            "@test",
+            "@test-mutation"
+        ],
+        "tests-no-coverage": [
+            "@test-no-coverage",
+            "@test-mutation-no-coverage"
+        ]
+    }
+}

infection.json.dist

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