Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README to use PHP attributes & add info about postgres #230

Merged
merged 2 commits into from
May 26, 2024
Merged

Update README to use PHP attributes & add info about postgres #230

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
22a015c
chore: update README to use PHP attributes & add info about postgres
jankal Nov 13, 2023
f6ff0ff
fix(docs): correct attribute syntax issues
jankal Apr 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 52 additions & 67 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,62 +94,34 @@ return [

### Mappings

Then, in your models, you may annotate properties by setting the `@Column`
Then, in your models, you may annotate properties by setting the `#[Column]`
type to `uuid`, and defining a custom generator of `Ramsey\Uuid\UuidGenerator`.
Doctrine will handle the rest.

``` php
use Doctrine\ORM\Mapping as ORM;
use Ramsey\Uuid\Doctrine\UuidGenerator;

/**
* @ORM\Entity
* @ORM\Table(name="products")
*/
class Product
{
/**
* @var \Ramsey\Uuid\UuidInterface
*
* @ORM\Id
* @ORM\Column(type="uuid", unique=true)
* @ORM\GeneratedValue(strategy="CUSTOM")
* @ORM\CustomIdGenerator(class=UuidGenerator::class)
*/
protected $id;

public function getId()
{
return $this->id;
}
}
```

or, as follows, with [PHP 8 attributes](https://www.php.net/attributes) and [type declarations](https://www.php.net/types.declarations):

``` php
use Doctrine\ORM\Mapping as ORM;
use Ramsey\Uuid\Doctrine\UuidGenerator;
use Ramsey\Uuid\UuidInterface;


#[ORM\Entity]
#[ORM\Table(name: "products")
#[ORM\Table(name: "products")]
class Product
{
#[ORM\Id]
#[ORM\Column(type: "uuid", unique: true)]
#[ORM\GeneratedValue(strategy: "CUSTOM")]
#[ORM\CustomIdGenerator(class: UuidGenerator::class)]
protected UuidInterface|string $id;
protected UuidInterface $id;

public function getId(): string
public function getId(): UuidInterface
{
return $this->id;
}
}
```

If you use the XML Mapping instead of PHP annotations.
If you use the XML Mapping instead of PHP attributes.

``` xml
<id name="id" column="id" type="uuid">
Expand All @@ -172,7 +144,7 @@ id:

### Binary database columns

In the previous example, Doctrine will create a database column of type `CHAR(36)`,
In the previous example, Doctrine will create a database column of type `CHAR(36)` if MariaDB / MySQL are in use,
but you may also use this library to store UUIDs as binary strings. The
`UuidBinaryType` helps accomplish this.

Expand All @@ -198,7 +170,7 @@ doctrine:

Then, when annotating model class properties, use `uuid_binary` instead of `uuid`:

@Column(type="uuid_binary")
#[Column(type: "uuid_binary")]

### InnoDB-optimised binary UUIDs - deprecated

Expand Down Expand Up @@ -235,23 +207,17 @@ type to `uuid_binary_ordered_time`, and defining a custom generator of
`Ramsey\Uuid\UuidOrderedTimeGenerator`. Doctrine will handle the rest.

``` php
/**
* @Entity
* @Table(name="products")
*/
#[Entity]
#[Table(name: "products")]´
class Product
{
/**
* @var \Ramsey\Uuid\UuidInterface
*
* @Id
* @Column(type="uuid_binary_ordered_time", unique=true)
* @GeneratedValue(strategy="CUSTOM")
* @CustomIdGenerator(class="Ramsey\Uuid\Doctrine\UuidOrderedTimeGenerator")
*/
protected $id;

public function getId()
#[Id]
#[Column(type: "uuid_binary_ordered_time", unique: true)]
#[GeneratedValue(strategy: "CUSTOM")]
#[CustomIdGenerator(class: UuidOrderedTimeGenerator::class)]
protected UuidInterface $id;

public function getId(): UuidInterface
{
return $this->id;
}
Expand Down Expand Up @@ -294,28 +260,22 @@ doctrine:
# uuid_binary: binary
```

Then, in your models, you may annotate properties by setting the `@Column`
Then, in your models, you may annotate properties by setting the `#[Column]`
type to `uuid_binary`, and defining a custom generator of
`Ramsey\Uuid\UuidV7Generator`. Doctrine will handle the rest.

``` php
/**
* @Entity
* @Table(name="products")
*/
#[Entity]
#[Table(name: "products")]
class Product
{
/**
* @var \Ramsey\Uuid\UuidInterface
*
* @Id
* @Column(type="uuid_binary", unique=true)
* @GeneratedValue(strategy="CUSTOM")
* @CustomIdGenerator(class="Ramsey\Uuid\Doctrine\UuidV7Generator")
*/
protected $id;

public function getId()
#[Id]
#[Column(type: "uuid_binary", unique: true)]
#[GeneratedValue(strategy: "CUSTOM")]
#[CustomIdGenerator(class: UuidV7Generator::class)]
protected UuidInterface $id;

public function getId(): UuidInterface
{
return $this->id;
}
Expand All @@ -331,6 +291,31 @@ If you use the XML Mapping instead of PHP annotations.
</id>
```

### PostgreSQL considerations


If you are using PostgreSQL, Doctrine uses PostgreSQL's `uuid` for the `Ramsey\Uuid\Doctrine\UuidType` (`uuid`).
Therefor you don't need to use the `uuid_binary` / `uuid_binary_ordered_time` types when using PostgreSQL.
You can still use `UuidV7Generator::class` to optimize indexing though.

``` php
#[Entity]
#[Table(name: "products")]
class Product
{
#[Id]
#[Column(type: "uuid", unique: true)]
#[GeneratedValue(strategy: "CUSTOM")]
#[CustomIdGenerator(class: UuidV7Generator::class)]
protected UuidInterface $id;

public function getId(): UuidInterface
{
return $this->id;
}
}
```

### Working with binary identifiers

When working with binary identifiers you may wish to convert them into a readable format.
Expand Down