From 39c610ea311bf4862c4c844db55a55976a5d5f93 Mon Sep 17 00:00:00 2001 From: Ben Ramsey Date: Sat, 30 Nov 2019 10:35:43 -0800 Subject: [PATCH] Clean up project documentation and repo metadata --- .gitattributes | 16 +-- .../CODE_OF_CONDUCT.md | 9 +- .github/CONTRIBUTING.md | 97 ++++++++++++++ .github/ISSUE_TEMPLATE/bug_report.md | 55 ++++++++ .github/ISSUE_TEMPLATE/feature_request.md | 22 ++++ .github/PULL_REQUEST_TEMPLATE.md | 30 +++++ .gitignore | 13 +- .travis.yml | 6 +- CHANGELOG.md | 45 +++++++ CONTRIBUTING.md | 77 ------------ LICENSE | 12 +- README.md | 118 +++++++++++------- composer.json | 33 +++-- phpunit.xml.dist | 4 +- resources/scripts/php-coveralls.sh | 4 +- 15 files changed, 374 insertions(+), 167 deletions(-) rename CODE_OF_CONDUCT.md => .github/CODE_OF_CONDUCT.md (92%) create mode 100644 .github/CONTRIBUTING.md create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 CONTRIBUTING.md diff --git a/.gitattributes b/.gitattributes index e7bc6c3..a3066a5 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,7 +1,9 @@ -/.gitattributes export-ignore -/.gitignore export-ignore -/.travis.yml export-ignore -/docs export-ignore linguist-documentation -/phpunit.xml.dist export-ignore linguist-documentation -/tests export-ignore linguist-documentation -/tools export-ignore linguist-documentation +.gitattributes export-ignore +.github/ export-ignore +.gitignore export-ignore +.travis.yml export-ignore +docs/ export-ignore +phpstan.neon export-ignore +phpunit.xml.dist export-ignore +resources/ export-ignore +tests/ export-ignore diff --git a/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md similarity index 92% rename from CODE_OF_CONDUCT.md rename to .github/CODE_OF_CONDUCT.md index 9c20725..51aafc0 100644 --- a/CODE_OF_CONDUCT.md +++ b/.github/CODE_OF_CONDUCT.md @@ -23,7 +23,7 @@ include: Examples of unacceptable behavior by participants include: * The use of sexualized language or imagery and unwelcome sexual attention or -advances + advances * Trolling, insulting/derogatory comments, and personal or political attacks * Public or private harassment * Publishing others' private information, such as a physical or electronic @@ -55,7 +55,7 @@ further defined and clarified by project maintainers. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project maintainer at . All +reported by contacting the project maintainer(s) at . All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. @@ -67,8 +67,7 @@ members of the project's leadership. ## Attribution -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 1.4, available at . [homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..497be69 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,97 @@ +# Contributing + +Contributions are welcome. I accept pull requests on [GitHub][]. + +This project adheres to a [Contributor Code of Conduct][]. By participating in +this project and its community, you are expected to uphold this code. + + +## Communication Channels + +You can find help and discussion in the following places: + +* GitHub Issues: +* GitHub Wiki: + + +## Reporting Bugs + +Bugs are tracked in the project's [issue tracker][issues]. + +When submitting a bug report, please include enough information to reproduce the +bug. A good bug report includes the following sections: + +* Expected outcome +* Actual outcome +* Steps to reproduce, including sample code +* Any other information that will help debug and reproduce the issue, including + stack traces, system/environment information, and screenshots + +**Please do not include passwords or any personally identifiable information in +your bug report and sample code.** + + +## Fixing Bugs + +I welcome pull requests to fix bugs! + +If you see a bug report that you'd like to fix, please feel free to do so. +Following the directions and guidelines described in the "Adding New Features" +section below, you may create bugfix branches and send pull requests. + + +## Adding New Features + +If you have an idea for a new feature, it's a good idea to check out the +[issues][] or active [pull requests][] first to see if the feature is already +being worked on. If not, feel free to submit an issue first, asking whether the +feature is beneficial to the project. This will save you from doing a lot of +development work only to have your feature rejected. I don't enjoy rejecting +your hard work, but some features just don't fit with the goals of the project. + +When you do begin working on your feature, here are some guidelines to consider: + +* Your pull request description should clearly detail the changes you have made. + I will use this description to update the CHANGELOG. If there is no + description or it does not adequately describe your feature, I will ask you + to update the description. +* ramsey/uuid follows the **[PSR-2 coding standard][psr-2]**. Please + ensure your code does, too. +* Please **write tests** for any new features you add. +* Please **ensure that tests pass** before submitting your pull request. + ramsey/uuid has Travis CI automatically running tests for pull requests. + However, running the tests locally will help save time. +* **Use topic/feature branches.** Please do not ask to pull from your master + branch. + * For more information, see "[Understanding the GitHub flow][gh-flow]." +* **Submit one feature per pull request.** If you have multiple features you + wish to submit, please break them up into separate pull requests. +* **Write good commit messages.** Make sure each individual commit in your pull + request is meaningful. If you had to make multiple intermediate commits while + developing, please squash them before submitting. + * For more information, see "[How to Write a Git Commit Message][git-commit]." + + +## Running Tests + +The following must pass before I will accept a pull request. If this does not +pass, it will result in a complete build failure. Before you can run this, be +sure to `composer install` ([download Composer][]). + +To run all the tests and coding standards checks, execute the following from the +command line, while in the project root directory (the same place as the +`composer.json` file): + +``` +composer run-script test +``` + + +[github]: https://github.com/ramsey/uuid +[contributor code of conduct]: https://github.com/ramsey/uuid/blob/master/.github/CODE_OF_CONDUCT.md +[issues]: https://github.com/ramsey/uuid/issues +[pull requests]: https://github.com/ramsey/uuid/pulls +[psr-2]: https://www.php-fig.org/psr/psr-2/ +[gh-flow]: https://guides.github.com/introduction/flow/ +[git-commit]: https://chris.beams.io/posts/git-commit/ +[download composer]: https://getcomposer.org/ diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..50ac557 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,55 @@ +--- +name: Bug report +about: Create a report to help us improve +labels: bug +assignees: +--- + +## Describe the bug + +A clear and concise description of what the bug is. + +## To Reproduce... + +Steps to reproduce the behavior (include code examples, if applicable): + +1. Create script `foo.php` and add the following: + + ``` php + + +## Description + + +## Motivation and context + + + +## How has this been tested? + + + + +## Types of changes + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to change) + +## Checklist: + + +- [ ] My code follows the code style of this project. +- [ ] My change requires a change to the documentation. +- [ ] I have updated the documentation accordingly. +- [ ] I have read the **[CONTRIBUTING.md](https://github.com/ramsey/uuid/blob/master/.github/CONTRIBUTING.md)** document. +- [ ] I have added tests to cover my changes. +- [ ] All new and existing tests passed. +- [ ] I have run `composer run-script test` locally, and there were no failures or errors. diff --git a/.gitignore b/.gitignore index 846cd68..dcd4b15 100644 --- a/.gitignore +++ b/.gitignore @@ -1,8 +1,5 @@ -*.phar -.DS_Store -.idea/ -.vagrant/ -build -composer.lock -phpunit.xml -vendor +.phpunit.result.cache +/build/ +/composer.lock +/phpunit.xml +/vendor/ diff --git a/.travis.yml b/.travis.yml index 613775f..fb9cfb0 100644 --- a/.travis.yml +++ b/.travis.yml @@ -33,15 +33,13 @@ before_install: install: - travis_retry composer require --no-update "php-coveralls/php-coveralls:^1 | ^2" - - travis_retry composer install --no-interaction --prefer-dist + - travis_retry composer install --no-interaction --prefer-dist --no-progress --no-suggest before_script: - mkdir -p build/logs script: - - ./vendor/bin/parallel-lint src tests - - travis_wait ./vendor/bin/phpunit --verbose --coverage-clover build/logs/clover.xml - - ./vendor/bin/phpcs src tests --standard=psr2 -sp + - travis_wait composer run-script --timeout=1200 test-ci after_success: - travis_retry ./resources/scripts/php-coveralls.sh diff --git a/CHANGELOG.md b/CHANGELOG.md index 9aeef75..2da2066 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,6 +31,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. * Disallow a trailing newline character when validating UUIDs * Annotate thrown exceptions for improved IDE hinting + ## [3.7.3] - 2018-01-19 ### Fixed @@ -43,6 +44,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. * Switch to `random_int()` from `mt_rand()` for better random numbers + ## [3.7.2] - 2018-01-13 ### Fixed @@ -50,6 +52,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. * Check sysfs on Linux to determine the node identifier; this provides a reliable way to identify the node on Docker images, etc. + ## [3.7.1] - 2017-09-22 ### Fixed @@ -60,6 +63,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. * Use `random_bytes()` when generating random nodes + ## [3.7.0] - 2017-08-04 ### Added @@ -71,12 +75,14 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. * `Uuid::UUID_TYPE_RANDOM` * `Uuid::UUID_TYPE_HASH_SHA1` + ## [3.6.1] - 2017-03-26 ### Fixed * Optimize UUID string decoding by using `str_pad()` instead of `sprintf()` + ## [3.6.0] - 2017-03-18 ### Added @@ -90,12 +96,14 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. * Improve memory usage when generating large quantities of UUIDs (use `str_pad()` and `dechex()` instead of `sprintf()`) + ## [3.5.2] - 2016-11-22 ### Fixed * Improve test coverage + ## [3.5.1] - 2016-10-02 ### Fixed @@ -103,6 +111,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. * Fix issue where the same UUIDs were not being treated as equal when using mixed cases + ## [3.5.0] - 2016-08-02 ### Added @@ -115,12 +124,14 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. * Avoid multiple unnecessary system calls by caching failed attempt to retrieve system node + ## [3.4.1] - 2016-04-23 ### Fixed * Fix test that violated a PHP CodeSniffer rule, breaking the build + ## [3.4.0] - 2016-04-23 ### Added @@ -130,6 +141,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. either the first 48 bits or the last 48 bits * Improve logic of `CombGenerator` for COMB sequential UUIDs + ## [3.3.0] - 2016-03-22 ### Security @@ -138,6 +150,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. support `RandomBytesGenerator` in versions of PHP earlier than 7.0; this addresses and fixes the [collision issue] + ## [3.2.0] - 2016-02-17 ### Added @@ -145,6 +158,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. * Add `SodiumRandomGenerator` to allow use of the [PECL libsodium extension] as a random bytes generator when creating UUIDs + ## [3.1.0] - 2015-12-17 ### Added @@ -152,12 +166,14 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. * Implement the PHP `Serializable` interface to provide the ability to serialize/unserialize UUID objects + ## [3.0.1] - 2015-10-21 ### Added * Adopt the [Contributor Code of Conduct] for this project + ## [3.0.0] - 2015-09-28 The 3.0.0 release represents a significant step for the ramsey/uuid library. @@ -224,6 +240,7 @@ versions leading up to this release.* * String representation is always the same * Fix exception message for `DegradedNumberConverter::fromHex()` + ## [3.0.0-beta1] - 2015-08-31 ### Fixed @@ -235,6 +252,7 @@ versions leading up to this release.* * String representation is always the same * Fix exception message for `DegradedNumberConverter::fromHex()` + ## [3.0.0-alpha3] - 2015-07-28 ### Added @@ -250,6 +268,7 @@ versions leading up to this release.* both `FeatureSet` and `UuidFactory` as those are now exclusively used by the default `TimeGenerator` + ## [3.0.0-alpha2] - 2015-07-28 ### Added @@ -271,6 +290,7 @@ versions leading up to this release.* * Remove `PeclUuidFactory` in favor of using pecl-uuid with generators + ## [3.0.0-alpha1] - 2015-07-16 ### Added @@ -304,30 +324,35 @@ versions leading up to this release.* * Move `uuid` console application to [ramsey/uuid-console] * Remove `Uuid::VERSION` package version constant + ## [2.9.0] - 2016-03-22 * Drop the use of OpenSSL as a fallback and use [paragonie/random_compat] to support `RandomBytesGenerator` in versions of PHP earlier than 7.0; this addresses and fixes the [collision issue] + ## [2.8.4] - 2015-12-17 ### Added * Add support for symfony/console v3 in the `uuid` CLI application + ## [2.8.3] - 2015-08-31 ### Fixed * Fix exception message in `Uuid::calculateUuidTime()` + ## [2.8.2] - 2015-07-23 ### Fixed * Ensure the release tag makes it into the rhumsaa/uuid package + ## [2.8.1] - 2015-06-16 ### Fixed @@ -336,6 +361,7 @@ versions leading up to this release.* * Cache the system node in a static variable so that we process it only once per runtime + ## [2.8.0] - 2014-11-09 ### Added @@ -348,24 +374,28 @@ versions leading up to this release.* * Improve Doctrine conversion to Uuid or string for the ramsey/uuid [Doctrine field type] + ## [2.7.4] - 2014-10-29 ### Fixed * Change loop in `generateBytes()` from `foreach` to `for` + ## [2.7.3] - 2014-08-27 ### Fixed * Fix upper range for `mt_rand` used in version 4 UUIDs + ## [2.7.2] - 2014-07-28 ### Changed * Upgrade to PSR-4 autoloading + ## [2.7.1] - 2014-02-19 ### Fixed @@ -373,12 +403,14 @@ versions leading up to this release.* * Move moontoast/math and symfony/console to require-dev * Support symfony/console 2.3 (LTS version) + ## [2.7.0] - 2014-01-31 ### Added * Add `Uuid::VALID_PATTERN` constant containing a UUID validation regex pattern + ## [2.6.1] - 2014-01-27 ### Fixed @@ -386,6 +418,7 @@ versions leading up to this release.* * Fix bug where `uuid` console application could not find the Composer autoloader when installed in another project + ## [2.6.0] - 2014-01-17 ### Added @@ -398,12 +431,14 @@ versions leading up to this release.* * Use `netstat` on Linux to capture the node for a version 1 UUID * Require moontoast/math as part of the regular package requirements + ## [2.5.0] - 2013-10-30 ### Added * Use `openssl_random_pseudo_bytes()`, if available, to generate random bytes + ## [2.4.0] - 2013-07-29 ### Added @@ -411,18 +446,21 @@ versions leading up to this release.* * Return `null` from `Uuid::getVersion()` if the UUID isn't an RFC 4122 variant * Support string UUIDs without dashes passed to `Uuid::fromString()` + ## [2.3.0] - 2013-07-16 ### Added * Support creation of UUIDs from bytes with `Uuid::fromBytes()` + ## [2.2.0] - 2013-07-04 ### Added * Add `Doctrine\UuidType::requiresSQLCommentHint()` method + ## [2.1.2] - 2013-07-03 ### Fixed @@ -430,18 +468,21 @@ versions leading up to this release.* * Fix cases where the system node was coming back with uppercase hexadecimal digits; this ensures that case in the node is converted to lowercase + ## [2.1.1] - 2013-04-29 ### Fixed * Fix bug in `Uuid::isValid()` where the NIL UUID was not reported as valid + ## [2.1.0] - 2013-04-15 ### Added * Allow checking the validity of a UUID through the `Uuid::isValid()` method + ## [2.0.0] - 2013-02-11 ### Added @@ -457,18 +498,21 @@ versions leading up to this release.* unsupported even on 64-bit builds of PHP * Move `UnsupportedOperationException` to the `Exception` subnamespace + ## [1.1.2] - 2012-11-29 ### Fixed * Relax [Doctrine field type] conversion rules for UUIDs + ## [1.1.1] - 2012-08-27 ### Fixed * Remove `final` keyword from `Uuid` class + ## [1.1.0] - 2012-08-06 ### Added @@ -476,6 +520,7 @@ versions leading up to this release.* * Support ramsey/uuid UUIDs as a Doctrine Database Abstraction Layer (DBAL) field mapping type + ## [1.0.0] - 2012-07-19 ### Added diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 9187876..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,77 +0,0 @@ -# Contributing - -Contributions are welcome. We accept pull requests on [GitHub](https://github.com/ramsey/uuid). - -You can triage issues which may include reproducing bug reports or asking for vital information, such as version numbers or reproduction instructions. If you would like to start triaging issues, one easy way to get started is to [subscribe to ramsey/uuid on CodeTriage](https://codetriage.com/ramsey/uuid). - -This project adheres to a [Contributor Code of Conduct](https://github.com/ramsey/uuid/blob/master/CODE_OF_CONDUCT.md). By participating in this project and its community, you are expected to uphold this code. - -## Team members - -* [Ben Ramsey](https://github.com/ramsey) - original author and maintainer -* [Marijn Huizendveld](https://github.com/marijn) - contributor, author of UUID type definition for Doctrine DBAL -* [Thibaud Fabre](https://github.com/aztech-dev) - contributor, lead developer for version 3.0.0 re-architecture - -## Communication Channels - -You can find help and discussion in the following places: - -* GitHub Issues: -* Wiki: - -## Reporting Bugs - -Bugs are tracked in our project's [issue tracker](https://github.com/ramsey/uuid/issues). - -When submitting a bug report, please include enough information for us to reproduce the bug. A good bug report includes the following sections: - -* Expected outcome -* Actual outcome -* Steps to reproduce, including sample code -* Any other information that will help us debug and reproduce the issue, including stack traces, system/environment information, and screenshots - -**Please do not include passwords or any personally identifiable information in your bug report and sample code.** - -## Fixing Bugs - -We welcome pull requests to fix bugs! - -If you see a bug report that you'd like to fix, please feel free to do so. Following the directions and guidelines described in the "Adding New Features" section below, you may create bugfix branches and send us pull requests. - -## Adding New Features - -If you have an idea for a new feature, it's a good idea to check out our [issues](https://github.com/ramsey/uuid/issues) or active [pull requests](https://github.com/ramsey/uuid/pulls) first to see if the feature is already being worked on. If not, feel free to submit an issue first, asking whether the feature is beneficial to the project. This will save you from doing a lot of development work only to have your feature rejected. We don't enjoy rejecting your hard work, but some features just don't fit with the goals of the project. - -When you do begin working on your feature, here are some guidelines to consider: - -* Your pull request description should clearly detail the changes you have made. We will use this description to add to our CHANGELOG. If there is no description or it does not adequately describe your feature, we will ask you to update the description. -* We following the **[PSR-2 coding standard](http://www.php-fig.org/psr/psr-2/)**. Please ensure your code does, too. -* Please **write tests** for any new features you add. -* Please **ensure that tests pass** before submitting your pull request. We have Travis CI automatically running tests for pull requests. However, running the tests locally will help save time. -* **Use topic/feature branches.** Please do not ask us to pull from your master branch. -* **Submit one feature per pull request.** If you have multiple features you wish to submit, please break them up into separate pull requests. -* **Send coherent history**. Make sure each individual commit in your pull request is meaningful. If you had to make multiple intermediate commits while developing, please squash them before submitting. - -## Running Tests - -The following tests must pass before we will accept a pull request. If any of these do not pass, it will result in a complete build failure. Before you can run these, be sure to `composer install`. - -``` -composer test -``` - -### Locally Test With Emulated MIPS Architecture - -The following commands use [Vagrant](https://www.vagrantup.com/) to start an Ubuntu VM, install necessary dependencies, and then run the `tools/run-tests.sh` script that will download a Docker image emulating the MIPS architecture. This is especially helpful for testing UUID generation in a big-endian environment. - -``` -vagrant init ubuntu/trusty64 -vagrant up -vagrant ssh -sudo apt-get install docker.io qemu-user-static php5-cli php5-curl -cd /vagrant -curl -sS https://getcomposer.org/installer | php -php composer.phar install --no-interaction --prefer-dist -mkdir -p build/logs -ARCH=mips PHP_VERSION=5.6.14 TRAVIS_BUILD_DIR=/vagrant ./tools/run-tests.sh -``` diff --git a/LICENSE b/LICENSE index 753a4c9..f6f7e80 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,6 @@ -Copyright (c) 2012-2018 Ben Ramsey +MIT License + +Copyright (c) 2012-2019 Ben Ramsey Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -7,13 +9,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -THE SOFTWARE. +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index b6557ab..95d4c21 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,47 @@ # ramsey/uuid -_NOTICE: Formerly known as `rhumsaa/uuid`, The package and namespace names have changed to `ramsey/uuid` and `Ramsey\Uuid`, respectively._ +*NOTICE: Formerly known as `rhumsaa/uuid`, The package and namespace names have +changed to `ramsey/uuid` and `Ramsey\Uuid`, respectively.* [![Source Code][badge-source]][source] [![Latest Version][badge-release]][release] [![Software License][badge-license]][license] +[![PHP Version][badge-php]][php] [![Build Status][badge-build]][build] [![Coverage Status][badge-coverage]][coverage] [![Total Downloads][badge-downloads]][downloads] -ramsey/uuid is a PHP 5.4+ library for generating and working with [RFC 4122][rfc4122] version 1, 3, 4, and 5 universally unique identifiers (UUID). +ramsey/uuid is a PHP 5.4+ library for generating and working with +[RFC 4122][rfc4122] version 1, 3, 4, and 5 universally unique identifiers +(UUID). -This project adheres to a [Contributor Code of Conduct][conduct]. By participating in this project and its community, you are expected to uphold this code. - - -## About +This project adheres to a [Contributor Code of Conduct][conduct]. By +participating in this project and its community, you are expected to uphold this +code. From [Wikipedia](http://en.wikipedia.org/wiki/Universally_unique_identifier): -> The intent of UUIDs is to enable distributed systems to uniquely identify information without significant central coordination. In this context the word unique should be taken to mean "practically unique" rather than "guaranteed unique". Since the identifiers have a finite size, it is possible for two differing items to share the same identifier. The identifier size and generation process need to be selected so as to make this sufficiently improbable in practice. Anyone can create a UUID and use it to identify something with reasonable confidence that the same identifier will never be unintentionally created by anyone to identify something else. Information labeled with UUIDs can therefore be later combined into a single database without needing to resolve identifier (ID) conflicts. +> The intent of UUIDs is to enable distributed systems to uniquely identify +> information without significant central coordination. In this context the word +> unique should be taken to mean "practically unique" rather than "guaranteed +> unique". Since the identifiers have a finite size, it is possible for two +> differing items to share the same identifier. The identifier size and +> generation process need to be selected so as to make this sufficiently +> improbable in practice. Anyone can create a UUID and use it to identify +> something with reasonable confidence that the same identifier will never be +> unintentionally created by anyone to identify something else. Information +> labeled with UUIDs can therefore be later combined into a single database +> without needing to resolve identifier (ID) conflicts. -Much inspiration for this library came from the [Java][javauuid] and [Python][pyuuid] UUID libraries. +Much inspiration for this library came from the [Java][javauuid] and +[Python][pyuuid] UUID libraries. ## Installation -The preferred method of installation is via [Packagist][] and [Composer][]. Run the following command to install the package and add it as a requirement to your project's `composer.json`: +The preferred method of installation is via [Composer][]. Run the following +command to install the package and add it as a requirement to your project's +`composer.json`: ```bash composer require ramsey/uuid @@ -34,23 +50,36 @@ composer require ramsey/uuid ## Upgrading from 2.x to 3.x -While we have made significant internal changes to the library, we have made every effort to ensure a seamless upgrade path from the 2.x series of this library to 3.x. +While we have made significant internal changes to the library, we have made +every effort to ensure a seamless upgrade path from the 2.x series of this +library to 3.x. -One major breaking change is the transition from the `Rhumsaa` root namespace to `Ramsey`. In most cases, all you will need is to change the namespace to `Ramsey` in your code, and everything will "just work." +One major breaking change is the transition from the `Rhumsaa` root namespace to +`Ramsey`. In most cases, all you will need is to change the namespace to +`Ramsey` in your code, and everything will "just work." Here are full details on the breaking changes to the public API of this library: -1. All namespace references of `Rhumsaa` have changed to `Ramsey`. Simply change the namespace to `Ramsey` in your code and everything should work. -2. The console application has moved to [ramsey/uuid-console](https://packagist.org/packages/ramsey/uuid-console). If using the console functionality, use Composer to require `ramsey/uuid-console`. -3. The Doctrine field type mapping has moved to [ramsey/uuid-doctrine](https://packagist.org/packages/ramsey/uuid-doctrine). If using the Doctrine functionality, use Composer to require `ramsey/uuid-doctrine`. +1. All namespace references of `Rhumsaa` have changed to `Ramsey`. Simply change + the namespace to `Ramsey` in your code and everything should work. +2. The console application has moved to + [ramsey/uuid-console](https://packagist.org/packages/ramsey/uuid-console). + If using the console functionality, use Composer to require + `ramsey/uuid-console`. +3. The Doctrine field type mapping has moved to + [ramsey/uuid-doctrine](https://packagist.org/packages/ramsey/uuid-doctrine). + If using the Doctrine functionality, use Composer to require + `ramsey/uuid-doctrine`. ## What to do if you see a "rhumsaa/uuid is abandoned" message -When installing your project's dependencies using Composer, you might see the following message: +When installing your project's dependencies using Composer, you might see the +following message: ``` -Package rhumsaa/uuid is abandoned, you should avoid using it. Use ramsey/uuid instead. +Package rhumsaa/uuid is abandoned, you should avoid using it. Use +ramsey/uuid instead. ``` Don't panic. Simply execute the following commands with Composer: @@ -60,32 +89,28 @@ composer remove rhumsaa/uuid composer require ramsey/uuid=^2.9 ``` -After doing so, you will have the latest ramsey/uuid package in the 2.x series, and there will be no need to modify any code; the namespace in the 2.x series is still `Rhumsaa`. +After doing so, you will have the latest ramsey/uuid package in the 2.x series, +and there will be no need to modify any code; the namespace in the 2.x series is +still `Rhumsaa`. ## Requirements -Some methods in this library have requirements due to integer size restrictions on 32-bit and 64-bit builds of PHP. A 64-bit build of PHP and the [Moontoast\Math][] library are recommended. However, this library is designed to work on 32-bit builds of PHP without Moontoast\Math, with some degraded functionality. Please check the API documentation for more information. +Some methods in this library have requirements due to integer size restrictions +on 32-bit and 64-bit builds of PHP. A 64-bit build of PHP and the +[Moontoast\Math][] library are recommended. However, this library is designed to +work on 32-bit builds of PHP without Moontoast\Math, with some degraded +functionality. Please check the API documentation for more information. -If a particular requirement is not present, then an `UnsatisfiedDependencyException` is thrown, allowing one to catch a bad call in an environment where the call is not supported and gracefully degrade. - - -## API documentation - -The [latest class API documentation][apidocs] is available online. - -This project uses [ApiGen](http://apigen.org/) to generate this documentation. To generate the documentation on your own, install dev dependencies and run the following command from the root of the project: - -``` -composer build-docs -``` - -This will generate documentation in the `build/apidocs/` folder. +If a particular requirement is not present, then an +`UnsatisfiedDependencyException` is thrown, allowing one to catch a bad call in +an environment where the call is not supported and gracefully degrade. ## Examples -See the [cookbook on the wiki][wiki-cookbook] for more examples and approaches to specific use-cases. +See the [cookbook on the wiki][wiki-cookbook] for more examples and approaches +to specific use-cases. ```php - + ./tests diff --git a/resources/scripts/php-coveralls.sh b/resources/scripts/php-coveralls.sh index 1180a77..1feabd1 100755 --- a/resources/scripts/php-coveralls.sh +++ b/resources/scripts/php-coveralls.sh @@ -3,7 +3,7 @@ set -e if [ -f vendor/bin/php-coveralls ]; then - php vendor/bin/php-coveralls + php vendor/bin/php-coveralls -v else - php vendor/bin/coveralls + php vendor/bin/coveralls -v fi