Skip to content

Commit 1aadefa

Browse files
henriquemoodyhenriquemoody
committed
Change the package into Respect\StringFormatter
First of all, when I created the package, I was about to board a flight, and I was in a different timezone, very sleep-deprived. I felt something was off, but I didn’t realise what. After a good night's sleep and having good tacos for dinner (and who would have thought my sister could be such a good cook), I checked what I'd done and realised there wasn’t much sense in creating a whole package just for that. Fortunately, I have other use cases for it that I actually need (or want), so turning that into something more flexible sounded great when my brain gave its signals.
1 parent 487136e commit 1aadefa

File tree

11 files changed

+526
-2669
lines changed

11 files changed

+526
-2669
lines changed

‎.gitattributes‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
/* export-ignore
2+
/composer.json -export-ignore
3+
/src -export-ignore
4+
/LICENSE -export-ignore
5+
/README.md -export-ignore

‎CONTRIBUTING.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# Contributing to StringFormatter
2+
3+
Thank you for considering contributing to StringFormatter! This document provides guidelines and information for contributors.
4+
5+
## Getting Started
6+
7+
### Prerequisites
8+
9+
- PHP 8.5 or higher
10+
- Composer
11+
- Git
12+
13+
### Setting Up the Development Environment
14+
15+
1. **Fork the repository**
16+
17+
```bash
18+
# Fork the repository on GitHub, then clone your fork
19+
git clone https://github.com/yourusername/StringFormatter.git
20+
cd StringFormatter
21+
```
22+
23+
2. **Install dependencies**
24+
25+
```bash
26+
composer install
27+
```
28+
29+
3. **Run tests**
30+
31+
```bash
32+
composer test
33+
```
34+
35+
## How to Contribute
36+
37+
### Adding New Formatters
38+
39+
StringFormatter is designed to be extensible. All formatters must implement the `Respect\StringFormatter\Formatter` interface.
40+
41+
**Steps to add a new formatter:**
42+
43+
1. **Create the formatter class**
44+
45+
```php
46+
<?php
47+
48+
declare(strict_types=1);
49+
50+
namespace Respect\StringFormatter;
51+
52+
final readonly class YourFormatter implements Formatter
53+
{
54+
public function format(string $input): string
55+
{
56+
// Your formatting implementation
57+
return $formattedInput;
58+
}
59+
}
60+
```
61+
62+
2. **Create tests**
63+
64+
```php
65+
<?php
66+
// tests/Unit/YourFormatterTest.php
67+
68+
declare(strict_types=1);
69+
70+
namespace Respect\StringFormatter\Test\Unit;
71+
72+
use PHPUnit\Framework\TestCase;
73+
use Respect\StringFormatter\YourFormatter;
74+
75+
final class YourFormatterTest extends TestCase
76+
{
77+
// Test your formatter implementation
78+
}
79+
```
80+
81+
3. **Add documentation**
82+
- Create `docs/YourFormatter.md` following the template used by MaskFormatter
83+
- Include usage examples, API reference, and any special considerations
84+
85+
4. **Update README.md**
86+
- Add your formatter to the "Formatters" table
87+
88+
### Testing
89+
90+
- **Unit tests**: Located in `tests/Unit/`
91+
- **Run all tests**: `composer test`
92+
93+
All contributions must include tests that pass.
94+
95+
### Code Style
96+
97+
This project follows the PSR-12 coding standard via the Respect Coding Standard. Run the following command before submitting:
98+
99+
```bash
100+
composer lint # Check coding style
101+
composer format # Fix coding style automatically
102+
```
103+
104+
### Static Analysis
105+
106+
This project uses PHPStan for static analysis. Run:
107+
108+
```bash
109+
composer analyze # Run static analysis
110+
```
111+
112+
### Submitting Changes
113+
114+
1. **Create a feature branch**
115+
116+
```bash
117+
git checkout -b feature/your-feature-name
118+
```
119+
120+
2. **Make your changes**
121+
- Add your formatter implementation
122+
- Include comprehensive tests
123+
- Update documentation
124+
- Follow PSR-12 coding standards
125+
126+
3. **Test your changes**
127+
128+
```bash
129+
composer test # Run tests
130+
composer lint # Check code style
131+
composer format # Fix coding style automatically
132+
composer analyze # Run static analysis
133+
```
134+
135+
4. **Commit your changes**
136+
137+
```bash
138+
git add .
139+
git commit -m "Add YourFormatter for [purpose]"
140+
```
141+
142+
5. **Push and create a pull request**
143+
144+
```bash
145+
git push origin feature/your-feature-name
146+
```
147+
148+
Then create a pull request on GitHub with:
149+
150+
- Clear description of the changes
151+
- Link to any relevant issues
152+
- Explain the use case and benefits
153+
154+
## Development Commands
155+
156+
| Command | Description |
157+
| ------------------ | -------------------------------- |
158+
| `composer install` | Install dependencies |
159+
| `composer test` | Run all tests |
160+
| `composer lint` | Check PSR-12 compliance |
161+
| `composer format` | Fix coding style automatically |
162+
| `composer analyze` | Run static analysis with PHPStan |
163+
164+
## Guidelines
165+
166+
### Do
167+
168+
- Write clear, well-documented code
169+
- Include comprehensive tests
170+
- Follow PSR-12 coding standards
171+
- Use type declarations everywhere
172+
- Write commit messages that explain the "why" not just the "what"
173+
174+
### Don't
175+
176+
- Submit changes without tests
177+
- Break backward compatibility unless necessary
178+
- Use PHP without strict typing
179+
- Commit sensitive information
180+
- Mix multiple concerns in a single PR
181+
182+
## Reporting Issues
183+
184+
When reporting issues, please include:
185+
186+
- PHP version
187+
- Library version
188+
- Complete error messages
189+
- Minimal reproducible example
190+
- Expected vs actual behavior
191+
192+
## Questions
193+
194+
If you have questions about contributing, feel free to:
195+
196+
- Open an issue with the "question" label
197+
- Start a discussion in the repository discussions
198+
199+
Thank you for contributing to StringFormatter! 🎉

‎README.md‎

Lines changed: 14 additions & 126 deletions
Original file line numberDiff line numberDiff line change
@@ -1,140 +1,28 @@
1-
# Respect\Masker
1+
# Respect\StringFormatter
22

3-
[![Build Status](https://img.shields.io/github/actions/workflow/status/Respect/Masker/continuous-integration.yml?branch=main&style=flat-square)](https://github.com/Respect/Masker/actions/workflows/continuous-integration.yml)
4-
[![Code Coverage](https://img.shields.io/codecov/c/github/Respect/Masker?style=flat-square)](https://codecov.io/gh/Respect/Masker)
5-
[![Latest Stable Version](https://img.shields.io/packagist/v/respect/masker.svg?style=flat-square)](https://packagist.org/packages/respect/masker)
6-
[![Total Downloads](https://img.shields.io/packagist/dt/respect/masker.svg?style=flat-square)](https://packagist.org/packages/respect/masker)
7-
[![License](https://img.shields.io/packagist/l/respect/masker.svg?style=flat-square)](https://packagist.org/packages/respect/masker)
3+
[![Build Status](https://img.shields.io/github/actions/workflow/status/Respect/StringFormatter/continuous-integration.yml?branch=main&style=flat-square)](https://github.com/Respect/StringFormatter/actions/workflows/continuous-integration.yml)
4+
[![Code Coverage](https://img.shields.io/codecov/c/github/Respect/StringFormatter?style=flat-square)](https://codecov.io/gh/Respect/StringFormatter)
5+
[![Latest Stable Version](https://img.shields.io/packagist/v/respect/string-formatter.svg?style=flat-square)](https://packagist.org/packages/respect/string-formatter)
6+
[![Total Downloads](https://img.shields.io/packagist/dt/respect/string-formatter.svg?style=flat-square)](https://packagist.org/packages/respect/string-formatter)
7+
[![License](https://img.shields.io/packagist/l/respect/string-formatter.svg?style=flat-square)](https://packagist.org/packages/respect/string-formatter)
88

9-
A powerful and flexible PHP library for masking sensitive text data using intuitive range-based patterns.
10-
11-
Whether you need to hide credit card numbers, mask email addresses, or protect user privacy, Masker gives you precise control over what gets hidden and what stays visible.
9+
A powerful and flexible PHP library for formatting and transforming strings.
1210

1311
## Installation
1412

1513
```bash
16-
composer require respect/masker
14+
composer require respect/string-formatter
1715
```
1816

19-
## Usage
20-
21-
### Basic Usage
22-
23-
```php
24-
use Respect\Masker\TextMasker;
25-
26-
$masker = new TextMasker();
27-
28-
echo $masker->mask('1234123412341234', '1-3,8-12');
29-
// Outputs: ***4123*****1234
30-
```
31-
32-
## API
33-
34-
### `mask`
35-
36-
- `mask(string $input, string $range): string`
37-
- `mask(string $input, string $range, string $replacement): string`
38-
39-
Masks the input string according to the specified range.
40-
41-
**Parameters:**
42-
43-
- `$input`: The string to mask
44-
- `$range`: Comma-separated range specifications
45-
- `$replacement`: The character to use for masking (default `*`)
46-
47-
**Returns:** The masked string
48-
49-
**Throws:** `InvalidArgumentException` when invalid ranges are provided
50-
51-
### `isValidRange`
52-
53-
- `isValidRange(string $range): bool`
54-
55-
Validates whether the mask range specification is syntactically correct.
56-
57-
## Range Syntax
58-
59-
| Pattern | Description | Example |
60-
| ------- | ------------------------------- | --------------------- |
61-
| `N` | Single position (1-based) | `3` |
62-
| `N-` | From position N to end | `1-` |
63-
| `N-M` | Range from position N to M | `1-3` |
64-
| `-N` | Last N characters | `-3` |
65-
| `C-M` | From character C to character M | `1-@` |
66-
| `\N` | Escaped numeral character | `\5` |
67-
| `\C` | Escaped special character | `\-`, `\,`, or `\\\\` |
68-
69-
Multiple ranges can be specified using commas: `1-B,6-8,10`
70-
71-
### Numeric Positions (1-based)
72-
73-
Use numeric positions to mask specific characters (1-based indexing).
74-
75-
| Range | Input | Output |
76-
| ------ | -------------- | -------------- |
77-
| `1-3` | `password123` | `***ord123` |
78-
| `1-3` | `'12345'` | `***45` |
79-
| `7-12` | `'1234567890'` | `123456******` |
80-
81-
#### Character Delimiters
82-
83-
Use character delimiters to mark ranges between characters in the string.
84-
85-
| Range | Input | Output |
86-
| ------ | --------------------- | --------------------- |
87-
| `1-@` | `username@domain.com` | `********@domain.com` |
88-
| `A-\5` | `ABCDD1234567890EFGH` | `*********567890EFGH` |
89-
| `A-\-` | `ABCD-1234567890EFGH` | `####-1234567890EFGH` |
90-
| `B-\,` | `ABC,DEF,GHI` | `**C,DEF,GHI` |
91-
92-
#### Multiple Ranges
93-
94-
Combine multiple ranges using commas to mask non-contiguous sections.
95-
96-
| Range | Input | Output |
97-
| ------------ | -------------------- | --------------------- |
98-
| `1-3,8-12` | `1234123412341234` | `***4123*****1234` |
99-
| `1,3,5` | `'12345'` | `*2*4*` |
100-
| `1-3,6-8,10` | `abcdefghij` | `***de***j` |
101-
| `1,3,5` | `12345` | `*2*4*` |
102-
| `1-3,8-12` | `'123456789012'` | `***45678******` |
103-
| `A-D,5-8` | `ABCD1234567890EFGH` | `####D####567890EFGH` |
104-
| `1-c,2-5` | `abc123def456` | `#####3def456` |
105-
106-
#### Special Patterns
107-
108-
**Mask to end**: Use `1-` to mask from the beginning to the end
109-
**Mask last N**: Use `-N` to mask the last N characters
110-
111-
| Range | Input | Output |
112-
| ----- | ---------- | ---------- |
113-
| `1-` | `12345678` | `********` |
114-
| `-2` | `123456` | `1234**` |
115-
| `-3` | `abcdefgh` | `abcde***` |
116-
117-
#### Escaping Special Characters
118-
119-
Escape special characters with backslash when they need to be used as literals.
120-
121-
| Range | Input | Output |
122-
| -------- | ---------------------------- | ---------------------------- |
123-
| `3-\5` | `1234567890` | `12**567890` |
124-
| `1-\-` | `email-something@domain.com` | `*****-something@domain.com` |
125-
| `1-\\\\` | `path\to\file` | `****\to\file` |
126-
127-
To use `-`, `\` and `,` as delimiters, you must always add backslashes before them.
17+
## Formatters
12818

129-
#### Unicode Support
19+
| Formatter | Description |
20+
| -------------------------------------- | ----------------------------------------------- |
21+
| [MaskFormatter](docs/MaskFormatter.md) | Range-based string masking with Unicode support |
13022

131-
Full support for UTF-8 strings including accented characters.
23+
## Contributing
13224

133-
| Range | Input | Output |
134-
| ------- | ---------------- | ---------------- |
135-
| `1-` | `oftalmoscópico` | `**************` |
136-
| `2-6,9` | `áéíóúãõçüñ` | `á*****õç*ñ` |
137-
| `-4` | `españolñç` | `españolñ*` |
25+
Please see our [Contributing Guide](CONTRIBUTING.md) for information on how to contribute to this project.
13826

13927
## License
14028

‎composer.json‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
2-
"name": "respect/masker",
2+
"name": "respect/string-formatter",
33
"type": "library",
4-
"description": "Mask sensitive text data using flexible range-based patterns",
4+
"description": "A powerful and flexible way of formatting and transforming strings",
55
"require": {
66
"symfony/polyfill-mbstring": "^1.33",
77
"php": "^8.5"
@@ -17,12 +17,12 @@
1717
"license": "ISC",
1818
"autoload": {
1919
"psr-4": {
20-
"Respect\\Masker\\": "src/"
20+
"Respect\\StringFormatter\\": "src/"
2121
}
2222
},
2323
"autoload-dev": {
2424
"psr-4": {
25-
"Respect\\Masker\\Test\\": "tests/"
25+
"Respect\\StringFormatter\\Test\\": "tests/"
2626
}
2727
},
2828
"authors": [
@@ -34,7 +34,8 @@
3434
"scripts": {
3535
"lint": "phpcs",
3636
"test": "phpunit",
37-
"analyze": "phpstan"
37+
"analyze": "phpstan",
38+
"format": "phpcbf"
3839
},
3940
"config": {
4041
"allow-plugins": {

0 commit comments

Comments
 (0)