Skip to content

Commit 9bf1ab2

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 9bf1ab2

11 files changed

Lines changed: 537 additions & 297 deletions

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

‎README.md‎

Lines changed: 21 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -1,140 +1,45 @@
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

1917
## Usage
2018

21-
### Basic Usage
19+
### MaskFormatter - Range-based String Masking
20+
21+
The `MaskFormatter` provides powerful and intuitive range-based patterns for masking sensitive text data.
2222

2323
```php
24-
use Respect\Masker\TextMasker;
24+
use Respect\StringFormatter\MaskFormatter;
2525

26-
$masker = new TextMasker();
26+
$formatter = new MaskFormatter('1-3,8-12');
2727

28-
echo $masker->mask('1234123412341234', '1-3,8-12');
28+
echo $formatter->format('1234123412341234');
2929
// Outputs: ***4123*****1234
3030
```
3131

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` |
32+
**📖 See the [MaskFormatter documentation](doc/MaskFormatter.md) for detailed usage examples and syntax reference.**
12633

127-
To use `-`, `\` and `,` as delimiters, you must always add backslashes before them.
34+
## Formatters
12835

129-
#### Unicode Support
36+
| Formatter | Description |
37+
| ------------------------------------- | ----------------------------------------------- |
38+
| [MaskFormatter](doc/MaskFormatter.md) | Range-based string masking with Unicode support |
13039

131-
Full support for UTF-8 strings including accented characters.
40+
## Contributing
13241

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

13944
## License
14045

0 commit comments

Comments
 (0)