VOOZH about

URL: https://deepwiki.com/stefanak-michal/php-bolt-driver/7.3-temporal-and-spatial-types

⇱ Temporal and Spatial Types | stefanak-michal/php-bolt-driver | DeepWiki

Loading...
Loading...
Last indexed: 14 February 2026 (a283bd)
Menu

Temporal and Spatial Types

This page documents the temporal (date/time) and spatial (point/geography) structure types supported by the Bolt protocol. These structures enable Neo4j's rich type system for handling dates, times, durations, and geographic coordinates in Cypher queries.

For information about graph structures (Node, Relationship, Path), see Graph Structures. For basic type mapping and PackStream serialization, see PackStream Format and Type Mapping.

Overview

Neo4j provides specialized structures for temporal and spatial data types that extend beyond basic PHP primitives. These structures are transmitted via PackStream serialization and are automatically unpacked into dedicated PHP classes when receiving data from the database. When sending parameters to Neo4j, these structures must be instantiated explicitly.

Key characteristics:

  • All temporal and spatial structures implement the IStructure interface
  • Structures are receive-only in queries (cannot be used as parameters, except for Point types and Duration)
  • Each structure has a unique PackStream signature for serialization
  • Structures provide __toString() methods for human-readable output
  • Version-specific implementations exist for DateTime and DateTimeZoneId in protocol v5+

Structure Type Catalog

The library provides nine temporal/spatial structure types organized into two categories:

CategoryStructurePurposeProtocol VersionCan be sent as parameter
TemporalDateCalendar date (no time)v1+Yes
TemporalTimeTime with timezone offsetv1+Yes
TemporalLocalTimeTime without timezonev1+Yes
TemporalDateTimeTimestamp with timezone offsetv1+ (v5+ adds UTC patch)Yes
TemporalDateTimeZoneIdTimestamp with timezone namev1+ (v5+ adds UTC patch)Yes
TemporalLocalDateTimeTimestamp without timezonev1+Yes
TemporalDurationTime span (ISO 8601)v1+Yes
SpatialPoint2D2D geographic/cartesian pointv1+Yes
SpatialPoint3D3D geographic/cartesian pointv1+Yes

Sources: tests/structures/v1/StructuresTest.php1-435 README.md149-169

Temporal Types Architecture



Sources: tests/structures/v1/StructuresTest.php13-27 tests/structures/v5/StructuresTest.php9-16


Date Structure


The Date structure represents a calendar date without time information. It stores the number of days since the Unix epoch (1970-01-01).


Class: Bolt\protocol\v1\structures\Date


Properties:


    

  • int $days - Days since Unix epoch
    • 



String representation: ISO 8601 date format (YYYY-MM-DD)


Example usage:




Sources: tests/structures/v1/StructuresTest.php67-96


Time Structure


The Time structure represents a time of day with timezone offset information. It stores nanoseconds since midnight and timezone offset in seconds.


Class: Bolt\protocol\v1\structures\Time


Properties:


    

  • int $nanoseconds - Nanoseconds since midnight (0-86,399,999,999,999)
    • 

  • int $tz_offset_seconds - Timezone offset in seconds from UTC
    • 



String representation: ISO 8601 time format with timezone (HH:MM:SS.ffffff±HH:MM)


Example usage:




Sources: tests/structures/v1/StructuresTest.php374-409


LocalTime Structure


The LocalTime structure represents a time of day without timezone information.


Class: Bolt\protocol\v1\structures\LocalTime


Properties:


    

  • int $nanoseconds - Nanoseconds since midnight
    • 



String representation: ISO 8601 time format without timezone (HH:MM:SS.ffffff)


Example usage:




Sources: tests/structures/v1/StructuresTest.php195-227


DateTime Structure


The DateTime structure represents a precise moment in time with timezone offset. This structure has version-specific implementations to support UTC patch in v4.3+ and v5+.


Class:


    

  • Bolt\protocol\v1\structures\DateTime (default)
    • 

  • Bolt\protocol\v5\structures\DateTime (protocol v5+ with UTC support)
    • 



Properties:


    

  • int $seconds - Seconds since Unix epoch
    • 

  • int $nanoseconds - Nanosecond fraction (0-999,999,999)
    • 

  • int $tz_offset_seconds - Timezone offset in seconds from UTC
    • 



String representation: ISO 8601 datetime format (YYYY-MM-DDTHH:MM:SS.ffffff±HH:MM)


Version differences:


    

  • V1-V4.2: Standard timezone offset handling
    • 

  • V4.3-V4.4: UTC patch available via patch_bolt: ['utc'] in HELLO message
    • 

  • V5+: UTC handling built-in, separate structure namespace
    • 



Example usage:




Sources: tests/structures/v1/StructuresTest.php99-100 tests/structures/v5/StructuresTest.php9-11 tests/structures/v4_3/StructuresTest.php65-66


DateTimeZoneId Structure


The DateTimeZoneId structure represents a precise moment in time with a named timezone identifier (e.g., "America/New_York"). Like DateTime, it has version-specific implementations.


Class:


    

  • Bolt\protocol\v1\structures\DateTimeZoneId (default)
    • 

  • Bolt\protocol\v5\structures\DateTimeZoneId (protocol v5+ with UTC support)
    • 



Properties:


    

  • int $seconds - Seconds since Unix epoch
    • 

  • int $nanoseconds - Nanosecond fraction
    • 

  • string $tz_id - IANA timezone identifier
    • 



String representation: ISO 8601 datetime format with timezone name


Example usage:




Sources: tests/structures/v1/StructuresTest.php102-103 tests/structures/v5/StructuresTest.php12-14 tests/structures/v4_3/StructuresTest.php68-69


LocalDateTime Structure


The LocalDateTime structure represents a timestamp without timezone information.


Class: Bolt\protocol\v1\structures\LocalDateTime


Properties:


    

  • int $seconds - Seconds since Unix epoch
    • 

  • int $nanoseconds - Nanosecond fraction
    • 



String representation: ISO 8601 datetime format without timezone (YYYY-MM-DDTHH:MM:SS.ffffff)


Example usage:




Sources: tests/structures/v1/StructuresTest.php156-188


Duration Structure


The Duration structure represents a time span using ISO 8601 duration format. Unlike other temporal types, Duration can be both received from and sent to Neo4j as a query parameter.


Class: Bolt\protocol\v1\structures\Duration


Properties:


    

  • int $months - Number of months
    • 

  • int $days - Number of days
    • 

  • int $seconds - Number of seconds
    • 

  • int $nanoseconds - Nanosecond fraction
    • 



String representation: ISO 8601 duration format (PnYnMnDTnHnMnS)


Duration format examples:


    

  • P1Y - 1 year
    • 

  • P1M - 1 month
    • 

  • P1D - 1 day
    • 

  • PT1H - 1 hour
    • 

  • PT1M - 1 minute
    • 

  • PT1S - 1 second
    • 

  • P1Y2M14DT16H12M35.765S - Complex duration
    • 



Example usage:




Sources: tests/structures/v1/StructuresTest.php109-149 tests/NornicDBTest.php8-10


Spatial Types Architecture




Sources: tests/structures/v1/StructuresTest.php289-339


Point2D Structure


The Point2D structure represents a point in 2D space, either geographic (latitude/longitude) or cartesian (x/y).


Class: Bolt\protocol\v1\structures\Point2D


Properties:


    

  • int $srid - Spatial Reference System Identifier

      

    • 4326 - WGS-84 geographic (latitude, longitude)
      • 

    • 7203 - Cartesian 2D
      • 

    

    • 

  • float $x - X coordinate (or longitude for geographic)
    • 

  • float $y - Y coordinate (or latitude for geographic)
    • 



String representation: Cypher point notation


Example usage:




Sources: tests/structures/v1/StructuresTest.php289-312


Point3D Structure


The Point3D structure represents a point in 3D space, either geographic (latitude/longitude/height) or cartesian (x/y/z).


Class: Bolt\protocol\v1\structures\Point3D


Properties:


    

  • int $srid - Spatial Reference System Identifier

      

    • 4979 - WGS-84-3D geographic (latitude, longitude, height)
      • 

    • 9157 - Cartesian 3D
      • 

    

    • 

  • float $x - X coordinate (or longitude for geographic)
    • 

  • float $y - Y coordinate (or latitude for geographic)
    • 

  • float $z - Z coordinate (or height for geographic)
    • 



String representation: Cypher point notation


Example usage:




Sources: tests/structures/v1/StructuresTest.php317-339


Temporal/Spatial Type Usage Patterns


Bidirectional Type Support Matrix



































































StructureUnpack from Neo4jPack to Neo4jNotes
Date✓✓Full bidirectional support
Time✓✓Full bidirectional support
LocalTime✓✓Full bidirectional support
DateTime✓✓Full bidirectional support
DateTimeZoneId✓✓Full bidirectional support
LocalDateTime✓✓Full bidirectional support
Duration✓✓Full bidirectional support
Point2D✓✓Full bidirectional support
Point3D✓✓Full bidirectional support


All temporal and spatial structures support bidirectional serialization, meaning they can be both received from Neo4j query results and sent as query parameters. This differs from graph structures (Node, Relationship, Path) which are receive-only.


Sources: tests/structures/v1/StructuresTest.php86-96 tests/structures/v1/StructuresTest.php124-135 tests/structures/v1/StructuresTest.php300-311 tests/structures/v1/StructuresTest.php329-339


Structure Serialization Flow




Sources: tests/structures/v1/StructuresTest.php86-96 tests/structures/v1/StructuresTest.php124-135


Common Query Patterns


Creating temporal data:




Querying with temporal parameters:




Querying with spatial parameters:




Working with durations:




Sources: tests/structures/v1/StructuresTest.php67-96 tests/structures/v1/StructuresTest.php289-339


Protocol Version Considerations


UTC Patch for DateTime (V4.3+)


Protocol versions 4.3 and 4.4 support an optional UTC patch via the patch_bolt parameter in the HELLO message. This affects how DateTime and DateTimeZoneId structures handle timezone conversions.


Enabling UTC patch:




Impact: When the UTC patch is enabled, the library uses Bolt\protocol\v5\structures\DateTime and Bolt\protocol\v5\structures\DateTimeZoneId instead of the v1 implementations, providing improved timezone handling.


Sources: tests/structures/v4_3/StructuresTest.php45-62


Structure Availability by Protocol Version


All temporal and spatial structures documented on this page are available in Bolt protocol v1 and higher. There are no version restrictions for basic usage.


Version-specific namespaces:


    

  • V1 structures: Bolt\protocol\v1\structures\* - Used by default for all protocol versions
    • 

  • V5 structures: Bolt\protocol\v5\structures\DateTime and DateTimeZoneId - Used automatically in protocol v5+ or when UTC patch is enabled in v4.3+
    • 



The protocol layer automatically selects the correct structure implementation based on the negotiated protocol version.


Sources: tests/structures/v1/StructuresTest.php40-60 tests/structures/v5/StructuresTest.php27-44


Testing Temporal and Spatial Types


The library includes comprehensive test coverage for all temporal and spatial structures across multiple protocol versions.


Test Structure Organization




Test patterns:


Unpacking test:




Packing test:




Sources: tests/structures/v1/StructuresTest.php67-96 tests/structures/v1/StructuresTest.php289-339 tests/structures/v5/StructuresTest.php27-73 tests/structures/v4_3/StructuresTest.php31-69


Running Structure Tests


Execute structure tests using PHPUnit:




Sources: phpunit.xml3-27 tests/structures/v1/StructuresTest.php1-435