Download the PHP package saintsystems/odata-client without Composer

Get started with the OData Client for PHP

A fluent library for calling OData REST services inspired by and based on the Laravel Query Builder.

For WordPress users, please see our Gravity Forms Dynamics 365 Add-On.

Install the SDK

You can install the PHP SDK with Composer.

HTTP Provider Configuration

Starting from version 0.10.0, the OData Client requires an HTTP provider to be explicitly set. This allows you to use any HTTP client implementation that suits your needs.

As of version 1.0.0, we will be using semver.

Using Guzzle (recommended for most users)

First, install Guzzle:

Then configure the OData client:

Using PSR-17/PSR-18 implementations

You can also use any PSR-17/PSR-18 compatible HTTP client:

Call an OData Service

The following is an example that shows how to call an OData service.

Advanced Usage

Custom Headers

You can add custom headers to your OData requests for authentication, tracking, or other purposes:

Custom Query Options

You can add custom query parameters to your OData requests that are not part of the standard OData specification. This is useful for passing additional parameters to your OData service:

Key Features:

• Merging: Multiple addOption() calls merge instead of overwriting
• Flexible: Supports both string ('key=value') and array (['key' => 'value']) formats
• Validated: Custom option keys are validated to prevent conflicts with OData system parameters
• URL Encoded: Special characters in keys and values are automatically URL encoded
• Fluent: Chain with other query methods for clean, readable code

Custom Timeout Configuration

If you need to configure custom network timeouts for your OData requests, you can create a subclass of ODataClient and override the createRequest method:

This approach allows you to customize request creation without having to override the entire request flow, following the template method pattern.

Key Features:

• Optional: Headers are completely optional - existing code works without changes
• Flexible: Set headers on the client or per-query
• Fluent: Chain header methods with other query methods
• Preserved: Default OData headers are automatically included
• Isolated: Query-specific headers don't affect the client's global headers

For a complete working example, see examples/custom_headers_example.php.

Nested Property Access

The OData Client provides powerful support for accessing nested properties in OData entities, making it easy to work with complex data structures returned by modern OData services.

Object-Style Access

Access nested properties naturally using object notation:

Dot Notation Access

Use dot notation for safe navigation through nested properties:

Property Existence Checking

Check if nested properties exist before accessing them:

Working with Collections

Handle arrays and collections within nested structures:

Real-World ShareFile OData Example

Working with ShareFile-style OData responses with Info objects and Children collections:

Integration with Query Building

Nested property access works seamlessly with OData query operations:

Key Features:

• Multiple Access Patterns: Object notation, dot notation, and array access all supported
• Automatic Type Conversion: Nested associative arrays become Entity objects for object-style access
• Safe Navigation: Non-existent properties return null instead of throwing errors
• Performance Optimized: Entity objects created lazily only when accessed
• Backward Compatible: All existing code continues to work unchanged
• Collection Friendly: Arrays remain as arrays for easy filtering and manipulation

For comprehensive examples and advanced usage patterns, see examples/nested_properties_example.php.

Lambda Operators (any/all)

The OData Client supports lambda operators any and all for filtering collections within entities. These operators allow you to filter based on conditions within related navigation properties.

Basic Usage

Available Lambda Methods

• whereAny($navigationProperty, $callback) - Returns true if any element matches the condition
• whereAll($navigationProperty, $callback) - Returns true if all elements match the condition
• orWhereAny($navigationProperty, $callback) - OR version of whereAny
• orWhereAll($navigationProperty, $callback) - OR version of whereAll

Complex Conditions

Key Features:

• Automatic variable generation: Uses first letter of navigation property (e.g., Trips → t)
• Full operator support: Supports all comparison operators (eq, ne, gt, ge, lt, le)
• Nested conditions: Handles complex where clauses within lambda expressions
• Fluent interface: Works seamlessly with other query builder methods

For comprehensive examples and advanced usage patterns, see examples/lambda_operators.php.

Batch Operations

The OData Client supports batch operations, which allow you to send multiple HTTP requests in a single batch request. This can significantly improve performance when you need to perform multiple operations.

Basic Batch Usage

Changesets for Atomic Operations

Changesets ensure that all operations within the changeset are executed atomically (all succeed or all fail):

Mixed Batch Operations

You can combine individual requests and changesets in a single batch:

Available Batch Methods

• get($uri, $id) - Add a GET request to the batch
• post($uri, $data, $id) - Add a POST request to the batch
• put($uri, $data, $id) - Add a PUT request to the batch
• patch($uri, $data, $id) - Add a PATCH request to the batch
• delete($uri, $id) - Add a DELETE request to the batch
• startChangeset() - Begin a new changeset for atomic operations
• endChangeset() - End the current changeset
• execute() - Execute the batch request

Key Features:

• Performance: Reduces network overhead by combining multiple requests
• Atomic transactions: Changesets ensure all-or-nothing execution
• Content-ID references: Use request IDs to reference results between operations
• Error handling: Individual operation errors are reported separately
• Fluent interface: Chain operations for clean, readable code

For comprehensive examples, see examples/batch_operations.php.

Develop

Run Tests

Run from the base directory.

Documentation and resources

• Documentation

• Wiki

• Examples

• OData website

• OASIS OData Version 4.0 Documentation

Issues

View or log issues on the Issues tab in the repo.

Copyright and license

Copyright (c) Saint Systems, LLC. All Rights Reserved. Licensed under the MIT license.