diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a64197f..86960a2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,18 +6,22 @@ First of all, **thank you** for contributing, **you are awesome**! Here are a few rules to follow in order to ease code reviews, and discussions before maintainers accept and merge your work. -You MUST follow some coding standard rules, like [PSR-1](http://www.php-fig.org/psr/1/) -and [PSR-2](http://www.php-fig.org/psr/2/). Fortunately, you can automate the fixing -for that rules, using [PHP-CS-Fixer](https://github.com/FriendsOfPHP/PHP-CS-Fixer) tool. -There is a configuration file included in this repository, named `.php_cs`. +You MUST follow some coding standard rules, like [PSR-1][1] +and [PSR-2][2]. Fortunately, you can automate the fixing +for that rules, using [PHP-CS-Fixer][3] tool. +There is a configuration file included in this repository, named `.php-cs-fixer.php`. You MUST run the test suite. You MUST write (or update) unit tests. -Please, write [commit messages that make -sense](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), -and [rebase your branch](http://git-scm.com/book/en/Git-Branching-Rebasing) -before submitting your Pull Request. +Please, write [commit messages that make sense][4], +and [rebase your branch][5] before submitting your Pull Request. Thank you! + +[1]: http://www.php-fig.org/psr/1/ +[2]: http://www.php-fig.org/psr/2/ +[3]: https://github.com/FriendsOfPHP/PHP-CS-Fixer +[4]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html +[5]: http://git-scm.com/book/en/Git-Branching-Rebasing diff --git a/README.md b/README.md index 7f195a3..d0b609b 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,4 @@ -ShortId -======= +# ShortId [![Total Downloads](https://poser.pugx.org/pugx/shortid-php/downloads.png)](https://packagist.org/packages/pugx/shortid-php) ![Build Status](https://github.com/PUGX/shortid-php/workflows/build/badge.svg) @@ -9,10 +8,22 @@ ShortId [![SensioLabsInsight](https://insight.sensiolabs.com/projects/058a0905-b889-49a4-9752-766787fcaeae/mini.png)](https://insight.sensiolabs.com/projects/058a0905-b889-49a4-9752-766787fcaeae) [![License](https://poser.pugx.org/pugx/shortid-php/license.svg)](https://packagist.org/packages/pugx/shortid-php) -This library is an implementation of [ShortId](https://github.com/dylang/shortid) for PHP. +This library is an implementation of [ShortId][1] for PHP. -Basic usage ------------ +## Installation + +Install the library via Composer: + +```bash +composer require pugx/shortid-php +``` + +## Usage + +ShortId is a PHP library that generates short, unique, and random strings. It's useful in scenarios +where you need concise identifiers, such as URL shortening or generating unique keys. + +## Basic usage Just call `PUGX\Shortid\Shortid::generate()` to get a random string with default length 7, like "MfiYIvI". @@ -25,10 +36,9 @@ $id = Shortid::generate(); ``` -Advanced usage --------------- +## Advanced usage -In the following example, you can see how to change the basic alphabet and default length. +For more control, you can customize the alphabet and length using the Factory class. Default alphabet uses all letters (lowercase and uppercase), all numbers, underscore, and hypen. @@ -61,12 +71,11 @@ $id5 = Shortid::generate(5); ``` -More readable strings ---------------------- +## More readable strings Sometimes, you want to avoid some ambiguous characters, like `B`/`8` or `I`/`l` (uppercase/lowercase). -In this case, you can pass a third parameter `true` to `generate` method. Notice that in this case the alphabet will -be ignored, so it makes sense to pass a null one. +In this case, you can pass a third parameter `true` to `generate` method. Notice that in this case the alphabet +will be ignored, so it makes sense to pass a null one. Example: @@ -78,8 +87,7 @@ require_once __DIR__.'/vendor/autoload.php'; $id = Shortid::generate(7, null, true); ``` -Pre-defined values ------------------- +## Pre-defined values If you need a deterministic string, instead of a random one, you can call directly the class constructor. This could be useful, for instance, when you need pre-defined data for testing purposes. @@ -94,27 +102,37 @@ $anotherFixedId = new Shortid('fooBarZ'); ``` -Doctrine --------- +## Doctrine -If you want to use ShortId with Doctrine ORM, take a look to -[ShortId Doctrine type](https://github.com/PUGX/shortid-doctrine). +If you want to use ShortId with Doctrine ORM, take a look to [ShortId Doctrine type][2]. -Doctrine and Symfony --------------------- +## Doctrine and Symfony If you want to use ShortId with Doctrine ORM and Symfony framework, take a look to -[ShortId Doctrine type bundle](https://github.com/PUGX/shortid-doctrine-bundle). +[ShortId Doctrine type bundle][3]. + + +## Dependencies replacement + +This library uses [a polyfill][4], so it can be used in environments where the mbstring +native extension is not available. +If, instead, your environment is offering that extension, you can avoid installing +that polyfill by configuring a [replace][5] entry in your `composer.json`. -mbstring extension ------------------- +The same applies to the [randomLib][6] library: if you are using PHP 8.3 or higher, +you can replace it, since this library uses the native `Random` class instead. -This library uses [a polyfill](https://github.com/symfony/polyfill-mbstring), so it -can used in environments where mbstring native extension is not available. +## Contributing -If, instead, your environment is offering such extension, you can avoid installing -polyfill by configuring [replace](https://getcomposer.org/doc/04-schema.md#replace) -entry in your `composer.json`. +Contributions are welcome. Feel free to open a Pull Request or file an issue here on GitHub! +Please read the [contributing guidelines][7] first. +[1]: https://github.com/dylang/shortid +[2]: https://github.com/PUGX/shortid-doctrine +[3]: https://github.com/PUGX/shortid-doctrine-bundle +[4]: https://github.com/symfony/polyfill-mbstring +[5]: https://getcomposer.org/doc/04-schema.md#replace +[6]: https://packagist.org/packages/paragonie/random-lib +[7]: CONTRIBUTING.md diff --git a/src/Factory.php b/src/Factory.php index 352924a..fef6151 100644 --- a/src/Factory.php +++ b/src/Factory.php @@ -2,6 +2,7 @@ namespace PUGX\Shortid; +use Random\Randomizer; use RandomLib\Factory as RandomLibFactory; use RandomLib\Generator; @@ -39,7 +40,11 @@ public function generate(int $length = null, string $alphabet = null, bool $read $alphabet .= \str_repeat('_', \strlen(Generator::AMBIGUOUS_CHARS) / 2); $alphabet .= \str_repeat('-', \strlen(Generator::AMBIGUOUS_CHARS) / 2); } - $id = self::getFactory()->getMediumStrengthGenerator()->generateString($length, $alphabet ?? $this->alphabet); + if (\PHP_VERSION_ID >= 80300) { + $id = (new Randomizer())->getBytesFromString($alphabet ?? $this->alphabet, $length); + } else { + $id = self::getFactory()->getMediumStrengthGenerator()->generateString($length, $alphabet ?? $this->alphabet); + } return new Shortid($id, $length, $alphabet); } diff --git a/tests/FactoryTest.php b/tests/FactoryTest.php index 2ea75a7..5e584ed 100644 --- a/tests/FactoryTest.php +++ b/tests/FactoryTest.php @@ -22,7 +22,11 @@ public function testGenerate(): void { $generated = $this->factory->generate(); - self::assertRegExp('/^[a-z0-9\_\-]{7,7}$/i', $generated->__toString()); + if (\method_exists($this, 'assertMatchesRegularExpression')) { + self::assertMatchesRegularExpression('/^[a-z0-9\_\-]{7}$/i', $generated->__toString()); + } else { + self::assertRegExp('/^[a-z0-9\_\-]{7}$/i', $generated->__toString()); + } } /** diff --git a/tests/ShortidTest.php b/tests/ShortidTest.php index b4fd690..35fd53f 100644 --- a/tests/ShortidTest.php +++ b/tests/ShortidTest.php @@ -2,7 +2,6 @@ namespace PUGX\Shortid\Test; -use JsonSerializable; use PHPUnit\Framework\TestCase; use PUGX\Shortid\Factory; use PUGX\Shortid\InvalidShortidException; @@ -19,21 +18,33 @@ public function testGenerate(): void { $generated = Shortid::generate(); - self::assertRegExp('/^[a-z0-9\_\-]{7}$/i', $generated->__toString()); + if (\method_exists($this, 'assertMatchesRegularExpression')) { + self::assertMatchesRegularExpression('/^[a-z0-9\_\-]{7}$/i', $generated->__toString()); + } else { + self::assertRegExp('/^[a-z0-9\_\-]{7}$/i', $generated->__toString()); + } } public function testGenerateWithReadable(): void { $generated = Shortid::generate(null, null, true); - self::assertRegExp('/^[a-z0-9\_\-]{7}$/i', $generated->__toString()); + if (\method_exists($this, 'assertMatchesRegularExpression')) { + self::assertMatchesRegularExpression('/^[a-z0-9\_\-]{7}$/i', $generated->__toString()); + } else { + self::assertRegExp('/^[a-z0-9\_\-]{7}$/i', $generated->__toString()); + } } public function testGenerateWithLength(): void { $generated = Shortid::generate(8); - self::assertRegExp('/^[a-z0-9\_\-]{8}$/i', $generated->__toString()); + if (\method_exists($this, 'assertMatchesRegularExpression')) { + self::assertMatchesRegularExpression('/^[a-z0-9\_\-]{8}$/i', $generated->__toString()); + } else { + self::assertRegExp('/^[a-z0-9\_\-]{8}$/i', $generated->__toString()); + } } public function testGetFactory(): void @@ -75,7 +86,7 @@ public function testJsonSerializable(): void { $generated = Shortid::generate(); - self::assertInstanceOf(JsonSerializable::class, $generated); + self::assertInstanceOf(\JsonSerializable::class, $generated); } public function testJsonEncode(): void