Skip to content
Get packs

Guide · Open source

How to use ramsey/uuid in PHP: install and generate UUIDs

Updated · written with AI from the project's own documentation and checked against our catalogue data

ramsey/uuid is a PHP library for generating and working with UUIDs, the long random-looking identifiers used to tag records or objects so they stay unique across systems. This guide shows how to add it to a PHP project with Composer and what it is suited for. After reading, you will know whether it fits your project and how to install it.

ramsey/uuidramsey/uuid · ★ 12.6k · MIT

Quick start

  1. 1Check prerequisites. Confirm PHP and Composer are installed on your machine and that your project uses Composer.
  2. 2Install the package. Run composer require ramsey/uuid in your project directory.
  3. 3Confirm the requirement. Check that ramsey/uuid now appears as a requirement in your composer.json file.
  4. 4Read the documentation. Open https://uuid.ramsey.dev for examples and usage details.
  5. 5Use it in your code. Call the library from your PHP code wherever you need to generate a UUID for a record or object.

What ramsey/uuid is and who it is for

ramsey/uuid is a code library, not a standalone app. You add it to a PHP project so your code can create UUIDs instead of writing that logic yourself. The README says much of its inspiration came from the Java and Python UUID libraries.

It suits PHP developers who need unique IDs for database records or API objects, and teams that want a long-established, MIT-licensed option.

  • Best for: PHP developers who need unique IDs for database records or API objects
  • Best for: projects that already use Composer to manage dependencies
  • Not for: people who do not write PHP, since it is a library rather than an app
  • Not for: projects needing UUID tooling in a different language

What you need before installing

The install method is a package manager. You need PHP and Composer available on your machine. The README does not list specific PHP version numbers, so check the package page on Packagist for compatibility details.

  • PHP
  • Composer

Install ramsey/uuid with Composer

The preferred method of installation is Composer. Run the following command in your project. It installs the package and adds it as a requirement to your project's composer.json file.

composer require ramsey/uuid

Where to find documentation and examples

The README points to the project documentation at uuid.ramsey.dev for documentation, tips, examples, and frequently asked questions. If you are upgrading from version 3, the README links to a separate upgrade guide for moving to version 4.

  • Documentation and examples: https://uuid.ramsey.dev
  • Upgrade guide from version 3 to 4 is linked from the project's documentation

Alternatives to consider

The comparable projects named for this item are the Symfony UID component and ramsey/uuid-doctrine. Choose based on your framework and whether you use Doctrine. The README does not compare features, so review each project's own documentation before deciding.

  • Symfony UID component
  • ramsey/uuid-doctrine

What people use it for

  • Giving database records a unique identifier that stays unique across systems
  • Assigning unique IDs to objects returned by a PHP API
  • Generating identifiers in a PHP project without writing UUID logic by hand

Frequently asked questions

Is ramsey/uuid free to use?

Yes. The library is licensed under the MIT License, as stated in the README. Read the LICENSE file in the repository for the full terms.

How do I install ramsey/uuid?

Run composer require ramsey/uuid in your project. The README says this installs the package and adds it to your composer.json.

What do I need to run ramsey/uuid?

You need PHP and Composer. The README lists these as the prerequisites for the Composer install method.

Is ramsey/uuid a standalone app?

No. It is a PHP library, so it only helps when you write PHP code that uses it. People who do not write PHP will not get value from it on its own.

What are alternatives to ramsey/uuid?

The comparable projects named for this item are the Symfony UID component and ramsey/uuid-doctrine. The README does not compare them, so check each one's documentation.

Where can I get help if something does not work?

The README points to https://uuid.ramsey.dev for documentation, tips, examples, and frequently asked questions. Security issues should follow the SECURITY.md instructions in the repository.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

ramsey/uuid is a good choice for PHP developers who use Composer and want a long-established, MIT-licensed library for generating UUIDs. If you do not write PHP, or you need UUID tooling for another language, pick a different tool. If you use a framework with its own UID component, compare it against the Symfony UID component before you commit.

Install options & downloads