Skip to content

Commit 9445d81

Browse files
nicolaasuninicolaasuni
committed
update dependencies and documentation
1 parent d5834e3 commit 9445d81

7 files changed

Lines changed: 317 additions & 82 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 180 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,194 @@
1-
# How to Contribute
1+
# Contributing to tc-lib-unicode
22

3+
Thank you for your interest in contributing to **tc-lib-unicode**.
4+
Contributions of all kinds are welcome: bug reports, bug fixes, documentation improvements, new features, and refactors.
35

4-
## Reporting a bug
6+
Please take a moment to read this guide before opening an issue or pull request.
57

6-
* **Do not open up a GitHub issue if the bug is a security vulnerability**, and instead to refer to our [Security policy](SECURITY.md).
8+
---
79

8-
* Ensure the bug was not already reported by searching on GitHub Issues.
10+
## Table of Contents
911

10-
* If you're unable to find an open issue addressing the problem, open a new one. Be sure to include a **title and clear description**, as much relevant information as possible, and a **code sample** or an **executable test case** demonstrating the expected behavior that is not occurring.
12+
- [Code of Conduct](#code-of-conduct)
13+
- [Security Vulnerabilities](#security-vulnerabilities)
14+
- [Getting Started](#getting-started)
15+
- [Reporting a Bug](#reporting-a-bug)
16+
- [Submitting a Bug Fix](#submitting-a-bug-fix)
17+
- [Proposing a New Feature](#proposing-a-new-feature)
18+
- [Development Workflow](#development-workflow)
19+
- [Coding Standards](#coding-standards)
20+
- [Testing](#testing)
21+
- [Pull Request Guidelines](#pull-request-guidelines)
22+
- [Commit Message Guidelines](#commit-message-guidelines)
1123

24+
---
1225

13-
## Submitting a bug fix
26+
## Code of Conduct
1427

15-
* Open a new GitHub pull request with the patch.
28+
This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating you agree to abide by its terms. Please report unacceptable behaviour to [[email protected]](mailto:[email protected]).
1629

17-
* Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.
30+
---
1831

19-
* Ensure the new code is following the existing conventions and the unit test coverage is 100%.
32+
## Security Vulnerabilities
2033

21-
* Before submitting, please run the following command locally to ensure the code is passing the automatic checks: `make buildall`.
34+
**Do not open a public GitHub issue for security vulnerabilities.**
35+
Please follow the [Security Policy](SECURITY.md) and report them privately.
2236

37+
---
2338

24-
## Add a new feature or change an existing one
39+
## Getting Started
2540

26-
* Before writing any code please suggest the change by opening a new Feature Request on Issues.
41+
### Requirements
42+
43+
- PHP **≥ 8.1**
44+
- [Composer](https://getcomposer.org/) v2
45+
- `make`, `git`
46+
- Optional: `rpmbuild` (RPM packaging), `dpkg-buildpackage` (DEB packaging)
47+
48+
### Local setup
49+
50+
```bash
51+
git clone https://github.com/tecnickcom/tc-lib-unicode.git
52+
cd tc-lib-unicode
53+
make buildall
54+
```
55+
56+
To verify everything is working after a change:
57+
58+
```bash
59+
make qa
60+
```
61+
62+
This runs linting, static analysis, and the full unit-test suite with coverage.
63+
64+
---
65+
66+
## Reporting a Bug
67+
68+
Before opening an issue:
69+
70+
1. **Check the [Security Policy](SECURITY.md)** — if the bug is a security vulnerability, do not file a public issue.
71+
2. **Search [existing issues](https://github.com/tecnickcom/tc-lib-unicode/issues)** to avoid duplicates.
72+
73+
If no existing issue matches, [open a new one](https://github.com/tecnickcom/tc-lib-unicode/issues/new) and include:
74+
75+
- A **clear title and description** of the problem.
76+
- The **library version** (`composer show tecnickcom/tc-lib-unicode`) and PHP version.
77+
- A **minimal, self-contained reproduction** — a short PHP script or a failing PHPUnit test case is ideal.
78+
- **Expected vs. actual behaviour** — what you expected to happen and what actually happened.
79+
- Any relevant **stack trace or error output**.
80+
81+
The more precise and reproducible the report, the faster it can be triaged and fixed.
82+
83+
---
84+
85+
## Submitting a Bug Fix
86+
87+
1. [Fork the repository](https://github.com/tecnickcom/tc-lib-unicode/fork) and create a branch from `main`:
88+
```bash
89+
git checkout -b fix/short-description-of-bug
90+
```
91+
2. Make your changes, following the [Coding Standards](#coding-standards) below.
92+
3. Add or update unit tests to cover the changes.
93+
4. Run the full quality-assurance suite locally and ensure it passes:
94+
```bash
95+
make qa
96+
```
97+
5. Commit your changes (see [Commit Message Guidelines](#commit-message-guidelines)).
98+
6. Open a pull request against `main` and fill in the PR template:
99+
- Describe the problem and your solution.
100+
- Reference the related issue number (e.g. `Fixes #123`).
101+
102+
---
103+
104+
## Proposing a New Feature
105+
106+
Before writing any code:
107+
108+
1. **Open a Feature Request** on [GitHub Issues](https://github.com/tecnickcom/tc-lib-unicode/issues/new) describing the use case and proposed API.
109+
2. Wait for feedback from the maintainer. This avoids investing time in a direction that may not be accepted.
110+
111+
Once the feature is agreed upon, follow the same branch → code → test → PR workflow as for bug fixes, using a branch named `feature/short-description`.
112+
113+
---
114+
115+
## Development Workflow
116+
117+
The `Makefile` exposes all common development tasks:
118+
119+
| Command | Description |
120+
|---------|-------------|
121+
| `make qa` | Run linting, static analysis, tests, and reports |
122+
| `make test` | Run PHPUnit with code coverage |
123+
| `make lint` | Check coding standards (PHPCS, PHPMD, PHPStan) |
124+
| `make codefix` | Auto-fix coding standard violations (PHPCBF) |
125+
| `make buildall` | Install dependencies, fix style, run QA, and build packages |
126+
| `make clean` | Remove `vendor/` and `target/` directories |
127+
| `make server` | Start the built-in PHP development server for the examples |
128+
129+
Run `make help` to see the full list of available targets.
130+
131+
---
132+
133+
## Coding Standards
134+
135+
- The codebase follows **PSR-12** for formatting.
136+
- Run `make codefix` to auto-fix style violations before committing.
137+
- Run `make lint` to catch remaining issues (PHPCS, PHPMD, PHPStan).
138+
- All source files live under `src/`, all tests under `test/`.
139+
- Use strict types and explicit visibility on all class members.
140+
- Avoid introducing new external dependencies without prior discussion.
141+
142+
---
143+
144+
## Testing
145+
146+
Tests are written with [PHPUnit](https://phpunit.de/) and live in `test/`.
147+
148+
```bash
149+
# Run the full test suite with coverage
150+
make test
151+
152+
# Run a specific test file
153+
XDEBUG_MODE=coverage ./vendor/bin/phpunit test/HTMLTest.php
154+
```
155+
156+
Requirements for contributions:
157+
158+
- Every bug fix must be accompanied by a regression test that fails before the fix and passes after.
159+
- Every new feature must be accompanied by tests that cover both the happy path and edge cases.
160+
161+
Coverage reports are generated in `target/coverage/`.
162+
163+
---
164+
165+
## Pull Request Guidelines
166+
167+
- Target the `main` branch.
168+
- Keep PRs focused — one fix or feature per PR.
169+
- Ensure `make qa` passes locally before opening the PR.
170+
- Do not bump the version number in your PR; that is handled by the maintainer at release time.
171+
- Be responsive to review feedback; stale PRs may be closed after an extended period of inactivity.
172+
173+
---
174+
175+
## Commit Message Guidelines
176+
177+
Use concise, imperative-mood commit messages:
178+
179+
```
180+
fix: correct path traversal in font loader
181+
feat: add support for XYZ
182+
test: add regression test for #123
183+
docs: update CONTRIBUTING workflow
184+
refactor: extract text measurement into helper
185+
```
186+
187+
Prefix tags: `fix`, `feat`, `test`, `docs`, `refactor`, `chore`, `ci`.
188+
Reference issues where relevant: `fix: correct X (closes #42)`.
189+
190+
---
191+
192+
## Questions?
193+
194+
If you have a question that is not covered here, feel free to open a [GitHub Discussion](https://github.com/tecnickcom/tc-lib-unicode/discussions) or contact the maintainer at [[email protected]](mailto:[email protected]).

‎README.md‎

Lines changed: 60 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,109 +1,107 @@
11
# tc-lib-unicode
2-
*PHP library containing Unicode and UTF-8 methods, including the Unicode Bidirectional Algorithm*
2+
3+
> UTF-8 and Unicode processing utilities, including bidirectional text handling.
34
45
[![Latest Stable Version](https://poser.pugx.org/tecnickcom/tc-lib-unicode/version)](https://packagist.org/packages/tecnickcom/tc-lib-unicode)
5-
![Build](https://github.com/tecnickcom/tc-lib-unicode/actions/workflows/check.yml/badge.svg)
6+
[![Build](https://github.com/tecnickcom/tc-lib-unicode/actions/workflows/check.yml/badge.svg)](https://github.com/tecnickcom/tc-lib-unicode/actions/workflows/check.yml)
67
[![Coverage](https://codecov.io/gh/tecnickcom/tc-lib-unicode/graph/badge.svg?token=XLM0QWY9BE)](https://codecov.io/gh/tecnickcom/tc-lib-unicode)
78
[![License](https://poser.pugx.org/tecnickcom/tc-lib-unicode/license)](https://packagist.org/packages/tecnickcom/tc-lib-unicode)
89
[![Downloads](https://poser.pugx.org/tecnickcom/tc-lib-unicode/downloads)](https://packagist.org/packages/tecnickcom/tc-lib-unicode)
910

1011
[![Donate via PayPal](https://img.shields.io/badge/donate-paypal-87ceeb.svg)](https://www.paypal.com/donate/?hosted_button_id=NZUEC5XS8MFBJ)
11-
*Please consider supporting this project by making a donation via [PayPal](https://www.paypal.com/donate/?hosted_button_id=NZUEC5XS8MFBJ)*
1212

13-
* **category** Library
14-
* **package** \Com\Tecnick\Unicode
15-
* **author** Nicola Asuni <[email protected]>
16-
* **copyright** 2011-2026 Nicola Asuni - Tecnick.com LTD
17-
* **license** https://www.gnu.org/copyleft/lesser.html GNU-LGPL v3 (see LICENSE.TXT)
18-
* **link** https://github.com/tecnickcom/tc-lib-unicode
19-
* **SRC DOC** https://tcpdf.org/docs/srcdoc/tc-lib-unicode
13+
If this library helps your multilingual stack, please consider [supporting development via PayPal](https://www.paypal.com/donate/?hosted_button_id=NZUEC5XS8MFBJ).
2014

21-
## Description
15+
---
2216

23-
PHP library containing Unicode and UTF-8 methods, including the Unicode Bidirectional Algorithm.
17+
## Overview
2418

25-
The initial source code has been derived from [TCPDF](<http://www.tcpdf.org>).
19+
`tc-lib-unicode` provides Unicode conversion helpers and bidirectional algorithm support for robust multilingual text processing.
2620

21+
| | |
22+
|---|---|
23+
| **Namespace** | `\Com\Tecnick\Unicode` |
24+
| **Author** | Nicola Asuni <[email protected]> |
25+
| **License** | [GNU LGPL v3](https://www.gnu.org/copyleft/lesser.html) - see [LICENSE](LICENSE) |
26+
| **API docs** | <https://tcpdf.org/docs/srcdoc/tc-lib-unicode> |
27+
| **Packagist** | <https://packagist.org/packages/tecnickcom/tc-lib-unicode> |
2728

28-
## Getting started
29+
---
2930

30-
First, you need to install all development dependencies using [Composer](https://getcomposer.org/):
31+
## Features
3132

32-
```bash
33-
$ curl -sS https://getcomposer.org/installer | php
34-
$ mv composer.phar /usr/local/bin/composer
35-
```
33+
### Unicode Utilities
34+
- UTF-8 character and ordinal conversion helpers
35+
- String/character array transformations
36+
- Integration-ready conversion methods for document engines
3637

37-
This project include a Makefile that allows you to test and build the project with simple commands.
38-
To see all available options:
38+
### Bidirectional Support
39+
- Unicode Bidirectional Algorithm implementation
40+
- Right-to-left and mixed-direction text processing
41+
- Supporting shaping/step logic for complex scripts
3942

40-
```bash
41-
make help
42-
```
43+
---
4344

44-
To install all the development dependencies:
45+
## Requirements
4546

46-
```bash
47-
make deps
48-
```
47+
- PHP 8.1 or later
48+
- Extensions: `mbstring`, `pcre`
49+
- Composer
4950

50-
## Running all tests
51+
---
5152

52-
Before committing the code, please check if it passes all tests using
53+
## Installation
5354

5455
```bash
55-
make qa
56+
composer require tecnickcom/tc-lib-unicode
5657
```
5758

58-
All artifacts are generated in the target directory.
59-
59+
---
6060

61-
## Example
61+
## Quick Start
6262

63-
Examples are located in the `example` directory.
63+
```php
64+
<?php
6465

65-
Start a development server (requires PHP 8.0+) using the command:
66+
require_once __DIR__ . '/vendor/autoload.php';
6667

67-
```
68-
make server
68+
$bidi = new \Com\Tecnick\Unicode\Bidi('hello ', null, null, 'R', false);
69+
echo $bidi->getString();
6970
```
7071

71-
and point your browser to <http://localhost:8000/index.php>
72+
---
7273

74+
## Development
7375

74-
## Installation
75-
76-
Create a composer.json in your projects root-directory:
77-
78-
```json
79-
{
80-
"require": {
81-
"tecnickcom/tc-lib-unicode": "^2.0"
82-
}
83-
}
76+
```bash
77+
make deps
78+
make help
79+
make qa
8480
```
8581

86-
Or add to an existing project with:
82+
---
83+
84+
## Packaging
8785

8886
```bash
89-
composer require tecnickcom/tc-lib-unicode ^2.0
87+
make rpm
88+
make deb
9089
```
9190

91+
For system packages, bootstrap with:
9292

93-
## Packaging
93+
```php
94+
require_once '/usr/share/php/Com/Tecnick/Unicode/autoload.php';
95+
```
9496

95-
This library is mainly intended to be used and included in other PHP projects using Composer.
96-
However, since some production environments dictates the installation of any application as RPM or DEB packages,
97-
this library includes make targets for building these packages (`make rpm` and `make deb`).
98-
The packages are generated under the `target` directory.
97+
---
9998

100-
When this library is installed using an RPM or DEB package, you can use it your code by including the autoloader:
101-
```
102-
require_once ('/usr/share/php/Com/Tecnick/Unicode/autoload.php');
103-
```
99+
## Contributing
104100

101+
Contributions are welcome. Please review [CONTRIBUTING.md](CONTRIBUTING.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and [SECURITY.md](SECURITY.md).
105102

103+
---
106104

107-
## Developer(s) Contact
105+
## Contact
108106

109-
*2026 Nicola Asuni <[email protected]>
107+
Nicola Asuni - <[email protected]>

0 commit comments

Comments
 (0)