├── src
    ├── Exception
    │   ├── InvalidArgument.php
    │   ├── OutOfRange.php
    │   ├── NotComparable.php
    │   └── IdentifierException.php
    ├── IdentifierFactory.php
    ├── BytesIdentifier.php
    ├── DateTimeIdentifier.php
    ├── IntegerIdentifier.php
    ├── DateTimeIdentifierFactory.php
    ├── BytesIdentifierFactory.php
    ├── StringIdentifierFactory.php
    ├── IntegerIdentifierFactory.php
    └── Identifier.php
├── .readthedocs.yaml
├── README.md
├── composer.json
└── COPYING


/src/Exception/InvalidArgument.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Identifier\Exception;
 6 | 
 7 | /**
 8 |  * The argument passed is invalid
 9 |  */
10 | interface InvalidArgument extends IdentifierException
11 | {
12 | }
13 | 


--------------------------------------------------------------------------------
/src/Exception/OutOfRange.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Identifier\Exception;
 6 | 
 7 | /**
 8 |  * The value is out of the range of acceptable values
 9 |  */
10 | interface OutOfRange extends IdentifierException
11 | {
12 | }
13 | 


--------------------------------------------------------------------------------
/.readthedocs.yaml:
--------------------------------------------------------------------------------
 1 | version: 2
 2 | 
 3 | build:
 4 |   os: ubuntu-24.04
 5 |   tools:
 6 |     python: '3.13'
 7 | 
 8 | sphinx:
 9 |   configuration: docs/conf.py
10 | 
11 | formats: all
12 | 
13 | python:
14 |   install:
15 |     - requirements: docs/requirements.txt
16 | 


--------------------------------------------------------------------------------
/src/Exception/NotComparable.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Identifier\Exception;
 6 | 
 7 | /**
 8 |  * The given value cannot be compared to the identifier
 9 |  */
10 | interface NotComparable extends IdentifierException
11 | {
12 | }
13 | 


--------------------------------------------------------------------------------
/src/Exception/IdentifierException.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Identifier\Exception;
 6 | 
 7 | use Throwable;
 8 | 
 9 | /**
10 |  * Base interface representing generic exceptions for identifiers
11 |  */
12 | interface IdentifierException extends Throwable
13 | {
14 | }
15 | 


--------------------------------------------------------------------------------
/src/IdentifierFactory.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Identifier;
 6 | 
 7 | /**
 8 |  * Creates identifiers
 9 |  */
10 | interface IdentifierFactory
11 | {
12 |     /**
13 |      * Creates a new instance of an identifier
14 |      */
15 |     public function create(): Identifier;
16 | }
17 | 


--------------------------------------------------------------------------------
/src/BytesIdentifier.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Identifier;
 6 | 
 7 | /**
 8 |  * An identifier based on arbitrary binary data
 9 |  */
10 | interface BytesIdentifier extends Identifier
11 | {
12 |     /**
13 |      * Returns the identifier as a raw byte string
14 |      *
15 |      * @return non-empty-string
16 |      */
17 |     public function toBytes(): string;
18 | }
19 | 


--------------------------------------------------------------------------------
/src/DateTimeIdentifier.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Identifier;
 6 | 
 7 | use DateTimeImmutable;
 8 | 
 9 | /**
10 |  * An identifier based on a date-time value
11 |  */
12 | interface DateTimeIdentifier extends Identifier
13 | {
14 |     /**
15 |      * Returns a date-time representation of the timestamp associated with this identifier
16 |      */
17 |     public function getDateTime(): DateTimeImmutable;
18 | }
19 | 


--------------------------------------------------------------------------------
/src/IntegerIdentifier.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Identifier;
 6 | 
 7 | /**
 8 |  * An identifier that may be represented as an integer
 9 |  */
10 | interface IntegerIdentifier extends Identifier
11 | {
12 |     /**
13 |      * Returns an integer representation of the identifier
14 |      *
15 |      * @return int | numeric-string
16 |      *
17 |      * @throws Exception\OutOfRange MUST throw if the implementation does not support integers outside the range of
18 |      *     `PHP_INT_MIN` and `PHP_INT_MAX` and the identifier evaluates to an integer outside this range
19 |      */
20 |     public function toInteger(): int | string;
21 | }
22 | 


--------------------------------------------------------------------------------
/src/DateTimeIdentifierFactory.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Identifier;
 6 | 
 7 | use DateTimeInterface;
 8 | 
 9 | /**
10 |  * Creates identifiers based on date-time values
11 |  */
12 | interface DateTimeIdentifierFactory extends IdentifierFactory
13 | {
14 |     public function create(): DateTimeIdentifier;
15 | 
16 |     /**
17 |      * Creates a new instance of an identifier from the given date-time
18 |      *
19 |      * @param DateTimeInterface $dateTime The date-time to use when creating the identifier
20 |      *
21 |      * @throws Exception\InvalidArgument MUST throw if $dateTime is not a legal value
22 |      */
23 |     public function createFromDateTime(DateTimeInterface $dateTime): DateTimeIdentifier;
24 | }
25 | 


--------------------------------------------------------------------------------
/src/BytesIdentifierFactory.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Identifier;
 6 | 
 7 | /**
 8 |  * Creates identifiers based on arbitrary binary data
 9 |  */
10 | interface BytesIdentifierFactory extends IdentifierFactory
11 | {
12 |     public function create(): BytesIdentifier;
13 | 
14 |     /**
15 |      * Creates a new instance of an identifier from the given byte string representation
16 |      *
17 |      * @param non-empty-string $identifier A binary octet string encoded according to the specification for the type of identifier
18 |      *
19 |      * @throws Exception\InvalidArgument MUST throw if $identifier is not a legal value
20 |      */
21 |     public function createFromBytes(string $identifier): BytesIdentifier;
22 | }
23 | 


--------------------------------------------------------------------------------
/src/StringIdentifierFactory.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Identifier;
 6 | 
 7 | /**
 8 |  * Creates identifiers from string representations
 9 |  */
10 | interface StringIdentifierFactory extends IdentifierFactory
11 | {
12 |     /**
13 |      * Creates a new instance of an identifier from the given string representation
14 |      *
15 |      * @param non-empty-string $identifier The string representation of the identifier is specific to the type of
16 |      *     identifier and implementation; for example, UUIDs use a specific format, while other identifiers may use
17 |      *     other formats
18 |      *
19 |      * @throws Exception\InvalidArgument MUST throw if the identifier is not a legal value
20 |      */
21 |     public function createFromString(string $identifier): Identifier;
22 | }
23 | 


--------------------------------------------------------------------------------
/src/IntegerIdentifierFactory.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Identifier;
 6 | 
 7 | /**
 8 |  * Creates identifiers that may be represented as integers
 9 |  */
10 | interface IntegerIdentifierFactory extends IdentifierFactory
11 | {
12 |     public function create(): IntegerIdentifier;
13 | 
14 |     /**
15 |      * Creates a new instance of an identifier from the given integer representation
16 |      *
17 |      * @param int | numeric-string $identifier
18 |      *
19 |      * @throws Exception\InvalidArgument MUST throw if the identifier is not a legal value
20 |      * @throws Exception\OutOfRange MUST throw if the implementation does not support integers outside the range of
21 |      *     `PHP_INT_MIN` and `PHP_INT_MAX` and the identifier evaluates to an integer outside this range
22 |      */
23 |     public function createFromInteger(int | string $identifier): IntegerIdentifier;
24 | }
25 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | <h1 align="center">identifier/identifier</h1>
 2 | 
 3 | <p align="center">
 4 |     <strong>Common Interfaces and Factories for Identifiers</strong>
 5 | </p>
 6 | 
 7 | ## About
 8 | 
 9 | This project is a specification defining common interfaces for representing and
10 | creating identifiers in PHP. For more information,
11 | [read the specification](https://php-identifier.readthedocs.io).
12 | 
13 | This project adheres to a [code of conduct](CODE_OF_CONDUCT.md).
14 | By participating in this project and its community, you are expected to
15 | uphold this code.
16 | 
17 | ## Installation
18 | 
19 | Install this package as a dependency using [Composer](https://getcomposer.org).
20 | 
21 | ``` bash
22 | composer require identifier/identifier
23 | ```
24 | 
25 | ## Contributing
26 | 
27 | Contributions are welcome! To contribute, please familiarize yourself with
28 | [CONTRIBUTING.md](CONTRIBUTING.md).
29 | 
30 | ## Coordinated Disclosure
31 | 
32 | Keeping user information safe and secure is a top priority, and we welcome the
33 | contribution of external security researchers. If you believe you've found a
34 | security issue in software that is maintained in this repository, please read
35 | [SECURITY.md](SECURITY.md) for instructions on submitting a vulnerability report.
36 | 
37 | ## Public Domain Dedication
38 | 
39 | To the extent possible under law, Ben Ramsey has waived all copyright and
40 | related or neighboring rights to "Common Interfaces and Factories for
41 | Identifiers."
42 | 
43 | <a href="https://creativecommons.org/publicdomain/zero/1.0/"><img src="https://i.creativecommons.org/p/zero/1.0/88x31.png" style="border-style: none;" alt="CC0"></a>
44 | 


--------------------------------------------------------------------------------
/src/Identifier.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Identifier;
 6 | 
 7 | use JsonSerializable;
 8 | use Stringable;
 9 | 
10 | /**
11 |  * Defines the most basic operations all identifiers support
12 |  */
13 | interface Identifier extends JsonSerializable, Stringable
14 | {
15 |     /**
16 |      * Returns an integer less than, equal to, or greater than zero if the identifier is less than, equal to, or greater
17 |      * than the other value
18 |      *
19 |      * @throws Exception\NotComparable MUST throw if the implementation is unable to make comparisons with the other
20 |      *     value provided
21 |      */
22 |     public function compareTo(mixed $other): int;
23 | 
24 |     /**
25 |      * Returns true if the identifier is equal to the other value
26 |      *
27 |      * @throws Exception\NotComparable MUST throw if the implementation is unable to make comparisons with the other
28 |      *     value provided
29 |      */
30 |     public function equals(mixed $other): bool;
31 | 
32 |     /**
33 |      * Returns a string representation of the identifier, formatted for use with JSON
34 |      *
35 |      * This MUST be aliased to `__toString()`; the serialized JSON form is a string.
36 |      *
37 |      * @see self::__toString()
38 |      *
39 |      * @return non-empty-string
40 |      */
41 |     public function jsonSerialize(): string;
42 | 
43 |     /**
44 |      * Returns a string representation of the identifier
45 |      *
46 |      * This MUST be aliased to `__toString()`. It is provided for convenience.
47 |      *
48 |      * @see self::__toString()
49 |      *
50 |      * @return non-empty-string
51 |      */
52 |     public function toString(): string;
53 | 
54 |     /**
55 |      * Returns a string representation of the identifier
56 |      *
57 |      * @return non-empty-string
58 |      */
59 |     public function __toString(): string;
60 | }
61 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "name": "identifier/identifier",
 3 |     "description": "Common Interfaces and Factories for Identifiers",
 4 |     "license": "CC0-1.0",
 5 |     "type": "library",
 6 |     "keywords": [
 7 |         "guid",
 8 |         "id",
 9 |         "identifier",
10 |         "snowflake",
11 |         "uid",
12 |         "ulid",
13 |         "uuid"
14 |     ],
15 |     "require": {
16 |         "php": "^8.2"
17 |     },
18 |     "require-dev": {
19 |         "captainhook/captainhook": "^5.25",
20 |         "captainhook/plugin-composer": "^5.3",
21 |         "dealerdirect/phpcodesniffer-composer-installer": "^1.0.0",
22 |         "ergebnis/composer-normalize": "^2.45",
23 |         "php-parallel-lint/php-console-highlighter": "^1.0",
24 |         "php-parallel-lint/php-parallel-lint": "^1.4",
25 |         "phpstan/extension-installer": "^1.4",
26 |         "phpstan/phpstan": "^2.1",
27 |         "ramsey/coding-standard": "^2.3",
28 |         "ramsey/conventional-commits": "^1.6",
29 |         "roave/security-advisories": "dev-latest"
30 |     },
31 |     "minimum-stability": "dev",
32 |     "prefer-stable": true,
33 |     "autoload": {
34 |         "psr-4": {
35 |             "Identifier\\": "src/"
36 |         }
37 |     },
38 |     "autoload-dev": {
39 |         "psr-4": {
40 |             "Identifier\\StaticAnalysis\\": "tests/static-analysis/"
41 |         }
42 |     },
43 |     "config": {
44 |         "allow-plugins": {
45 |             "captainhook/plugin-composer": true,
46 |             "composer/package-versions-deprecated": true,
47 |             "dealerdirect/phpcodesniffer-composer-installer": true,
48 |             "ergebnis/composer-normalize": true,
49 |             "phpstan/extension-installer": true
50 |         },
51 |         "sort-packages": true
52 |     },
53 |     "extra": {
54 |         "captainhook": {
55 |             "force-install": true
56 |         },
57 |         "ramsey/conventional-commits": {
58 |             "configFile": "conventional-commits.json"
59 |         }
60 |     },
61 |     "scripts": {
62 |         "dev:analyze": [
63 |             "@dev:analyze:phpstan"
64 |         ],
65 |         "dev:analyze:phpstan": "phpstan analyse --ansi",
66 |         "dev:build:clean": "git clean -fX build/",
67 |         "dev:lint": [
68 |             "@dev:lint:syntax",
69 |             "@dev:lint:style"
70 |         ],
71 |         "dev:lint:fix": "phpcbf",
72 |         "dev:lint:style": "phpcs --colors",
73 |         "dev:lint:syntax": "parallel-lint --colors src/",
74 |         "dev:test": [
75 |             "@dev:lint",
76 |             "@dev:analyze"
77 |         ],
78 |         "test": "@dev:test"
79 |     },
80 |     "scripts-descriptions": {
81 |         "dev:analyze": "Runs all static analysis checks.",
82 |         "dev:analyze:phpstan": "Runs the PHPStan static analyzer.",
83 |         "dev:build:clean": "Cleans the build/ directory.",
84 |         "dev:lint": "Runs all linting checks.",
85 |         "dev:lint:fix": "Auto-fixes coding standards issues, if possible.",
86 |         "dev:lint:style": "Checks for coding standards issues.",
87 |         "dev:lint:syntax": "Checks for syntax errors.",
88 |         "dev:test": "Runs linting, static analysis, and unit tests.",
89 |         "test": "Runs linting, static analysis, and unit tests."
90 |     }
91 | }
92 | 


--------------------------------------------------------------------------------
/COPYING:
--------------------------------------------------------------------------------
  1 | Creative Commons Legal Code
  2 | 
  3 | CC0 1.0 Universal
  4 | 
  5 |     CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
  6 |     LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
  7 |     ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
  8 |     INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
  9 |     REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
 10 |     PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
 11 |     THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
 12 |     HEREUNDER.
 13 | 
 14 | Statement of Purpose
 15 | 
 16 | The laws of most jurisdictions throughout the world automatically confer
 17 | exclusive Copyright and Related Rights (defined below) upon the creator
 18 | and subsequent owner(s) (each and all, an "owner") of an original work of
 19 | authorship and/or a database (each, a "Work").
 20 | 
 21 | Certain owners wish to permanently relinquish those rights to a Work for
 22 | the purpose of contributing to a commons of creative, cultural and
 23 | scientific works ("Commons") that the public can reliably and without fear
 24 | of later claims of infringement build upon, modify, incorporate in other
 25 | works, reuse and redistribute as freely as possible in any form whatsoever
 26 | and for any purposes, including without limitation commercial purposes.
 27 | These owners may contribute to the Commons to promote the ideal of a free
 28 | culture and the further production of creative, cultural and scientific
 29 | works, or to gain reputation or greater distribution for their Work in
 30 | part through the use and efforts of others.
 31 | 
 32 | For these and/or other purposes and motivations, and without any
 33 | expectation of additional consideration or compensation, the person
 34 | associating CC0 with a Work (the "Affirmer"), to the extent that he or she
 35 | is an owner of Copyright and Related Rights in the Work, voluntarily
 36 | elects to apply CC0 to the Work and publicly distribute the Work under its
 37 | terms, with knowledge of his or her Copyright and Related Rights in the
 38 | Work and the meaning and intended legal effect of CC0 on those rights.
 39 | 
 40 | 1. Copyright and Related Rights. A Work made available under CC0 may be
 41 | protected by copyright and related or neighboring rights ("Copyright and
 42 | Related Rights"). Copyright and Related Rights include, but are not
 43 | limited to, the following:
 44 | 
 45 |   i. the right to reproduce, adapt, distribute, perform, display,
 46 |      communicate, and translate a Work;
 47 |  ii. moral rights retained by the original author(s) and/or performer(s);
 48 | iii. publicity and privacy rights pertaining to a person's image or
 49 |      likeness depicted in a Work;
 50 |  iv. rights protecting against unfair competition in regards to a Work,
 51 |      subject to the limitations in paragraph 4(a), below;
 52 |   v. rights protecting the extraction, dissemination, use and reuse of data
 53 |      in a Work;
 54 |  vi. database rights (such as those arising under Directive 96/9/EC of the
 55 |      European Parliament and of the Council of 11 March 1996 on the legal
 56 |      protection of databases, and under any national implementation
 57 |      thereof, including any amended or successor version of such
 58 |      directive); and
 59 | vii. other similar, equivalent or corresponding rights throughout the
 60 |      world based on applicable law or treaty, and any national
 61 |      implementations thereof.
 62 | 
 63 | 2. Waiver. To the greatest extent permitted by, but not in contravention
 64 | of, applicable law, Affirmer hereby overtly, fully, permanently,
 65 | irrevocably and unconditionally waives, abandons, and surrenders all of
 66 | Affirmer's Copyright and Related Rights and associated claims and causes
 67 | of action, whether now known or unknown (including existing as well as
 68 | future claims and causes of action), in the Work (i) in all territories
 69 | worldwide, (ii) for the maximum duration provided by applicable law or
 70 | treaty (including future time extensions), (iii) in any current or future
 71 | medium and for any number of copies, and (iv) for any purpose whatsoever,
 72 | including without limitation commercial, advertising or promotional
 73 | purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
 74 | member of the public at large and to the detriment of Affirmer's heirs and
 75 | successors, fully intending that such Waiver shall not be subject to
 76 | revocation, rescission, cancellation, termination, or any other legal or
 77 | equitable action to disrupt the quiet enjoyment of the Work by the public
 78 | as contemplated by Affirmer's express Statement of Purpose.
 79 | 
 80 | 3. Public License Fallback. Should any part of the Waiver for any reason
 81 | be judged legally invalid or ineffective under applicable law, then the
 82 | Waiver shall be preserved to the maximum extent permitted taking into
 83 | account Affirmer's express Statement of Purpose. In addition, to the
 84 | extent the Waiver is so judged Affirmer hereby grants to each affected
 85 | person a royalty-free, non transferable, non sublicensable, non exclusive,
 86 | irrevocable and unconditional license to exercise Affirmer's Copyright and
 87 | Related Rights in the Work (i) in all territories worldwide, (ii) for the
 88 | maximum duration provided by applicable law or treaty (including future
 89 | time extensions), (iii) in any current or future medium and for any number
 90 | of copies, and (iv) for any purpose whatsoever, including without
 91 | limitation commercial, advertising or promotional purposes (the
 92 | "License"). The License shall be deemed effective as of the date CC0 was
 93 | applied by Affirmer to the Work. Should any part of the License for any
 94 | reason be judged legally invalid or ineffective under applicable law, such
 95 | partial invalidity or ineffectiveness shall not invalidate the remainder
 96 | of the License, and in such case Affirmer hereby affirms that he or she
 97 | will not (i) exercise any of his or her remaining Copyright and Related
 98 | Rights in the Work or (ii) assert any associated claims and causes of
 99 | action with respect to the Work, in either case contrary to Affirmer's
100 | express Statement of Purpose.
101 | 
102 | 4. Limitations and Disclaimers.
103 | 
104 |  a. No trademark or patent rights held by Affirmer are waived, abandoned,
105 |     surrendered, licensed or otherwise affected by this document.
106 |  b. Affirmer offers the Work as-is and makes no representations or
107 |     warranties of any kind concerning the Work, express, implied,
108 |     statutory or otherwise, including without limitation warranties of
109 |     title, merchantability, fitness for a particular purpose, non
110 |     infringement, or the absence of latent or other defects, accuracy, or
111 |     the present or absence of errors, whether or not discoverable, all to
112 |     the greatest extent permissible under applicable law.
113 |  c. Affirmer disclaims responsibility for clearing rights of other persons
114 |     that may apply to the Work or any use thereof, including without
115 |     limitation any person's Copyright and Related Rights in the Work.
116 |     Further, Affirmer disclaims responsibility for obtaining any necessary
117 |     consents, permissions or other rights required for any use of the
118 |     Work.
119 |  d. Affirmer understands and acknowledges that Creative Commons is not a
120 |     party to this document and has no duty or obligation with respect to
121 |     this CC0 or use of the Work.
122 | 


--------------------------------------------------------------------------------