# man > BSON::OID

---
type: CommandReference
command: BSON::OID
mode: perldoc
section: 3pm
source: perldoc
---

## Quick Reference
- `my $oid = bson_oid()` — generate a new unique OID
- `my $oid = BSON::OID->new` — alternative constructor without import
- `my $oid = BSON::OID->from_epoch($epoch, 0)` — create OID for query boundaries (first 4 bytes = epoch, rest zeroed)
- `my $bytes = $oid->oid` — retrieve the 12-byte raw OID
- `my $hex = $oid->hex` — retrieve the 24‑character hexadecimal representation
- `$oid->from_epoch($new_epoch, 0)` — reset an existing OID’s timestamp (for comparisons)
- `my $time = $oid->get_time` — extract the epoch seconds from an OID
- `print "$oid"` — string overload gives the 24‑digit hex value

## Name
BSON type wrapper for Object IDs

## Synopsis
perl
use BSON::Types ':all';

my $oid  = bson_oid();
my $oid  = bson_oid->from_epoch(1467543496, 0);   # for queries only
my $bytes = $oid->oid;
my $hex   = $oid->hex;
## Attributes
- `oid` — a 12‑byte (packed) OID string; automatically generated if not supplied

## Methods
- `new(oid => $twelve_bytes)` — constructor; without arguments generates a unique OID; with a 12‑byte string wraps an existing OID
- `from_epoch($epoch, $eight_more_bytes)` — **Warning**: not for unique ID generation.  
  - **Class method**: returns a new `BSON::OID` with the first four bytes set to the packed epoch. If the second argument is the number `0`, the remaining eight bytes are zeroed (ideal for query boundary OIDs).  
  - **Object method**: mutates the internal OID.  
  - Without a second argument, the remaining bytes are generated in the same way as `new()` (unsafe for uniqueness).  
  To obtain a thread‑safe unique OID, supply 8 random bytes, e.g., `from_epoch($epoch, Crypt::URandom::urandom(8))`.
- `hex` — returns the OID as a 24‑character hexadecimal string
- `get_time` — returns the integer seconds since the Unix epoch extracted from the OID
- `TO_JSON` — returns the 24‑digit hex string; if the `BSON_EXTJSON` option is true, returns `{"$oid":"012345678901234567890123"}` (MongoDB extended JSON)
- **String overload** — stringification yields the 24‑character hex value; comparison operators (`<=>`, `cmp`) compare those hex strings, so a non‑`BSON::OID` argument must be a 24‑character hex string

## See Also
- [BSON::Types](http://localhost/phpMan.php/perldoc/BSON%3A%3ATypes/markdown)
- [MongoDB ObjectId documentation](https://docs.mongodb.com/manual/reference/method/ObjectId/)
- [Crypt::URandom](http://localhost/phpMan.php/perldoc/Crypt%3A%3AURandom/markdown) (for random bytes in `from_epoch`)