Skip to content

Commit c1da527

Browse files
gustavofrezegustavofreze
authored
Release/1.0.0 (#2)
1 parent 751c358 commit c1da527

24 files changed

+778
-1
lines changed

‎.gitattributes

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
/tests export-ignore
2+
/vendor export-ignore
3+
4+
/LICENSE export-ignore
5+
/Makefile export-ignore
6+
/README.md export-ignore
7+
/phpmd.xml export-ignore
8+
/phpunit.xml export-ignore
9+
/phpstan.neon.dist export-ignore
10+
/infection.json.dist export-ignore
11+
12+
/.github export-ignore
13+
/.gitignore export-ignore
14+
/.gitattributes export-ignore

‎.github/workflows/auto-assign.yml

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: Auto assign issues
2+
3+
on:
4+
issues:
5+
types:
6+
- opened
7+
8+
jobs:
9+
run:
10+
runs-on: ubuntu-latest
11+
permissions:
12+
issues: write
13+
pull-requests: write
14+
steps:
15+
- name: Assign issues
16+
uses: gustavofreze/auto-assign@1.0.0
17+
with:
18+
assignees: '${{ secrets.ASSIGNEES }}'
19+
github_token: '${{ secrets.GITHUB_TOKEN }}'
20+
allow_self_assign: 'true'
21+
allow_no_assignees: 'true'
22+
assignment_options: 'ISSUE'

‎.github/workflows/ci.yml

+55
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
pull_request:
6+
7+
permissions:
8+
contents: read
9+
10+
jobs:
11+
auto-review:
12+
name: Auto review
13+
runs-on: ubuntu-latest
14+
15+
steps:
16+
- name: Checkout
17+
uses: actions/checkout@v3
18+
19+
- name: Use PHP 8.2
20+
uses: shivammathur/setup-php@v2
21+
with:
22+
php-version: '8.2'
23+
24+
- name: Install dependencies
25+
run: composer update --no-progress --optimize-autoloader
26+
27+
- name: Run phpcs
28+
run: composer phpcs
29+
30+
- name: Run phpmd
31+
run: composer phpmd
32+
33+
tests:
34+
name: Tests
35+
runs-on: ubuntu-latest
36+
37+
steps:
38+
- name: Checkout
39+
uses: actions/checkout@v3
40+
41+
- name: Use PHP 8.2
42+
uses: shivammathur/setup-php@v2
43+
with:
44+
php-version: '8.2'
45+
46+
- name: Install dependencies
47+
run: composer update --no-progress --optimize-autoloader
48+
49+
- name: Run unit tests
50+
env:
51+
XDEBUG_MODE: coverage
52+
run: composer test
53+
54+
- name: Run mutation tests
55+
run: composer test-mutation

‎.gitignore

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
.idea
2+
vendor
3+
report
4+
composer.lock
5+
.phpunit.result.cache

‎LICENSE

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

‎Makefile

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
DOCKER_RUN = docker run --rm -it --net=host -v ${PWD}:/app -w /app gustavofreze/php:8.2
2+
3+
.PHONY: configure test test-file test-no-coverage review show-reports clean
4+
5+
configure:
6+
@${DOCKER_RUN} composer update --optimize-autoloader
7+
8+
test:
9+
@${DOCKER_RUN} composer tests
10+
11+
test-file:
12+
@${DOCKER_RUN} composer tests-file-no-coverage ${FILE}
13+
14+
test-no-coverage:
15+
@${DOCKER_RUN} composer tests-no-coverage
16+
17+
review:
18+
@${DOCKER_RUN} composer review
19+
20+
show-reports:
21+
@sensible-browser report/coverage/coverage-html/index.html report/coverage/mutation-report.html
22+
23+
clean:
24+
@sudo chown -R ${USER}:${USER} ${PWD}
25+
@rm -rf report vendor .phpunit.cache

‎README.md

+92-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,92 @@
1-
# immutable-object
1+
# Immutable Object
2+
3+
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
4+
5+
* [Overview](#overview)
6+
* [Installation](#installation)
7+
* [How to use](#how-to-use)
8+
* [License](#license)
9+
* [Contributing](#contributing)
10+
11+
<div id='overview'></div>
12+
13+
## Overview
14+
15+
The **Immutable Object** library ensures that objects implementing it remain immutable after initialization. Once
16+
created, the state of the object cannot be modified. Any attempt to change properties or collection elements will throw
17+
an exception.
18+
19+
<div id='installation'></div>
20+
21+
## Installation
22+
23+
```bash
24+
composer require tiny-blocks/immutable-object
25+
```
26+
27+
<div id='how-to-use'></div>
28+
29+
## How to use
30+
31+
The library provides the `Immutable` interface and the `Immutability` trait to guarantee immutability. These components
32+
prevent properties and collections from being modified or unset.
33+
34+
### Concrete implementation
35+
36+
By implementing the `Immutable` interface and using the `Immutability` trait, you can ensure that object properties and
37+
elements in collections are immutable.
38+
39+
```php
40+
<?php
41+
42+
namespace Example;
43+
44+
use TinyBlocks\Immutable\Immutable;
45+
use TinyBlocks\Immutable\Immutability;
46+
47+
final class Order implements Immutable
48+
{
49+
use Immutability;
50+
51+
public function __construct(public int $id, public Products $products)
52+
{
53+
}
54+
}
55+
```
56+
57+
#### Handling property immutability
58+
59+
The Immutability trait also prevents modifications to properties of an object. Trying to modify a property after the
60+
object is initialized will throw an exception.
61+
62+
```php
63+
$order = new Order(id: 1, products: new Products(array: ['item1', 'item2']);
64+
65+
$order->id = 2; # Throws an exception
66+
unset($order->id); # Throws an exception
67+
```
68+
69+
#### Handling collection immutability
70+
71+
The `Immutability` trait also prevents the modification of collection elements (e.g., arrays). Trying to modify or
72+
remove an element will throw an exception.
73+
74+
```php
75+
$order = new Order(id: 1, products: new Products(array: ['item1', 'item2']);
76+
77+
$order->items[0] = 'item3'; # Throws an exception
78+
unset($order->items[0]); # Throws an exception
79+
```
80+
81+
<div id='license'></div>
82+
83+
## License
84+
85+
Immutable Object is licensed under [MIT](LICENSE).
86+
87+
<div id='contributing'></div>
88+
89+
## Contributing
90+
91+
Please follow the [contributing guidelines](https://github.com/tiny-blocks/tiny-blocks/blob/main/CONTRIBUTING.md) to
92+
contribute to the project.

‎composer.json

+74
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
{
2+
"name": "tiny-blocks/immutable-object",
3+
"type": "library",
4+
"license": "MIT",
5+
"homepage": "https://github.com/tiny-blocks/immutable-object",
6+
"description": "Provides immutable behavior for objects.",
7+
"prefer-stable": true,
8+
"minimum-stability": "stable",
9+
"keywords": [
10+
"vo",
11+
"psr",
12+
"tiny-blocks",
13+
"immutability",
14+
"immutable-object"
15+
],
16+
"authors": [
17+
{
18+
"name": "Gustavo Freze de Araujo Santos",
19+
"homepage": "https://github.com/gustavofreze"
20+
}
21+
],
22+
"support": {
23+
"issues": "https://github.com/tiny-blocks/immutable-object/issues",
24+
"source": "https://github.com/tiny-blocks/immutable-object"
25+
},
26+
"config": {
27+
"sort-packages": true,
28+
"allow-plugins": {
29+
"infection/extension-installer": true
30+
}
31+
},
32+
"autoload": {
33+
"psr-4": {
34+
"TinyBlocks\\Immutable\\": "src/"
35+
}
36+
},
37+
"autoload-dev": {
38+
"psr-4": {
39+
"TinyBlocks\\Immutable\\": "tests/"
40+
}
41+
},
42+
"require": {
43+
"php": "^8.2"
44+
},
45+
"require-dev": {
46+
"phpmd/phpmd": "^2.15",
47+
"phpunit/phpunit": "^11",
48+
"phpstan/phpstan": "^1",
49+
"infection/infection": "^0.29",
50+
"squizlabs/php_codesniffer": "^3.10"
51+
},
52+
"scripts": {
53+
"phpcs": "phpcs --standard=PSR12 --extensions=php ./src",
54+
"phpmd": "phpmd ./src text phpmd.xml --suffixes php --ignore-violations-on-exit",
55+
"phpstan": "phpstan analyse -c phpstan.neon.dist --quiet --no-progress",
56+
"test": "phpunit --log-junit=report/coverage/junit.xml --coverage-xml=report/coverage/coverage-xml --coverage-html=report/coverage/coverage-html tests",
57+
"test-mutation": "infection --only-covered --logger-html=report/coverage/mutation-report.html --coverage=report/coverage --min-msi=100 --min-covered-msi=100 --threads=4",
58+
"test-no-coverage": "phpunit --no-coverage",
59+
"test-mutation-no-coverage": "infection --only-covered --min-msi=100 --threads=4",
60+
"review": [
61+
"@phpcs",
62+
"@phpmd",
63+
"@phpstan"
64+
],
65+
"tests": [
66+
"@test",
67+
"@test-mutation"
68+
],
69+
"tests-no-coverage": [
70+
"@test-no-coverage",
71+
"@test-mutation-no-coverage"
72+
]
73+
}
74+
}

‎infection.json.dist

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"timeout": 10,
3+
"testFramework": "phpunit",
4+
"tmpDir": "report/infection/",
5+
"source": {
6+
"directories": [
7+
"src"
8+
]
9+
},
10+
"logs": {
11+
"text": "report/infection/logs/infection-text.log",
12+
"summary": "report/infection/logs/infection-summary.log"
13+
},
14+
"mutators": {
15+
"@default": true
16+
},
17+
"phpUnit": {
18+
"configDir": "",
19+
"customPath": "./vendor/bin/phpunit"
20+
}
21+
}

0 commit comments

Comments
 (0)