README

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.

composer require saintsystems/odata-client

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:

composer require guzzlehttp/guzzle

Then configure the OData client:

use SaintSystems\OData\ODataClient;
use SaintSystems\OData\GuzzleHttpProvider;

$httpProvider = new GuzzleHttpProvider();
$odataClient = new ODataClient($odataServiceUrl, null, $httpProvider);

Using PSR-17/PSR-18 implementations

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

use SaintSystems\OData\ODataClient;
use SaintSystems\OData\Psr17HttpProvider;

// Example using Symfony HTTP Client with Nyholm PSR-7
$httpClient = new \Symfony\Component\HttpClient\Psr18Client();
$requestFactory = new \Nyholm\Psr7\Factory\Psr17Factory();
$streamFactory = new \Nyholm\Psr7\Factory\Psr17Factory();

$httpProvider = new Psr17HttpProvider($httpClient, $requestFactory, $streamFactory);
$odataClient = new ODataClient($odataServiceUrl, null, $httpProvider);

Call an OData Service

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

<?php

require_once __DIR__ . '/vendor/autoload.php';

use SaintSystems\OData\ODataClient;
use SaintSystems\OData\GuzzleHttpProvider;

class UsageExample
{
	public function __construct()
	{
		$odataServiceUrl = 'https://services.odata.org/V4/TripPinService';

		$httpProvider = new GuzzleHttpProvider();
		$odataClient = new ODataClient($odataServiceUrl, null, $httpProvider);

		// Retrieve all entities from the "People" Entity Set
		$people = $odataClient->from('People')->get();

		// Or retrieve a specific entity by the Entity ID/Key
		try {
			$person = $odataClient->from('People')->find('russellwhyte');
			echo "Hello, I am $person->FirstName ";
		} catch (Exception $e) {
			echo $e->getMessage();
		}

		// Want to only select a few properties/columns?
		$people = $odataClient->from('People')->select('FirstName','LastName')->get();
	}
}

$example = new UsageExample();

Advanced Usage

Custom Headers

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

<?php

use SaintSystems\OData\ODataClient;
use SaintSystems\OData\GuzzleHttpProvider;

$httpProvider = new GuzzleHttpProvider();
$odataClient = new ODataClient($odataServiceUrl, null, $httpProvider);

// Method 1: Set headers on the client (applies to all requests)
$odataClient->setHeaders([
    'Authorization' => 'Bearer your-token-here',
    'X-Custom-Header' => 'MyCustomValue',
    'X-Client-Version' => '1.0.0'
]);

// Method 2: Add a single header to the client
$odataClient->addHeader('X-Request-ID', uniqid());

// Method 3: Add headers to specific queries using the fluent interface
$people = $odataClient->from('People')
    ->withHeader('X-Query-Context', 'get-all-people')
    ->withHeaders([
        'X-Debug' => 'true',
        'X-Performance-Track' => 'enabled'
    ])
    ->get();

// Headers set on the client persist across requests
$person = $odataClient->from('People')->find('russellwhyte');

// Query-specific headers only apply to that request
$airlines = $odataClient->from('Airlines')
    ->withHeader('X-Data-Source', 'airlines-api')
    ->get();

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:

<?php

use SaintSystems\OData\ODataClient;
use SaintSystems\OData\GuzzleHttpProvider;

$httpProvider = new GuzzleHttpProvider();
$odataClient = new ODataClient($odataServiceUrl, null, $httpProvider);

// Method 1: Add custom options using string format
$people = $odataClient->from('People')
    ->addOption('timeout=30')
    ->addOption('format=minimal')
    ->get();
// Results in: /People?timeout=30&format=minimal

// Method 2: Add custom options using array format
$people = $odataClient->from('People')
    ->addOption(['timeout' => '30', 'debug' => 'true'])
    ->get();
// Results in: /People?timeout=30&debug=true

// Method 3: Mix with standard OData parameters
$people = $odataClient->from('People')
    ->select('FirstName', 'LastName')
    ->where('FirstName', 'Russell')
    ->addOption('version=2.0')
    ->get();
// Results in: /People?$select=FirstName,LastName&$filter=FirstName eq 'Russell'&version=2.0

// Method 4: Multiple addOption calls are merged (not overwritten)
$people = $odataClient->from('People')
    ->addOption('timeout=30')
    ->addOption('format=minimal')
    ->addOption(['debug' => 'true']);
// Results in: /People?timeout=30&format=minimal&debug=true

// Custom option keys are validated:
// ✓ Valid: 'timeout', 'custom_param', 'kebab-case', 'camelCase'
// ✗ Invalid: '$reserved' (starts with $), 'invalid key!' (special chars)

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:

<?php

use SaintSystems\OData\ODataClient;
use SaintSystems\OData\GuzzleHttpProvider;

class CustomTimeoutODataClient extends ODataClient {
    private $customTimeout;

    public function __construct($baseUrl, $authProvider = null, $httpProvider = null, $timeout = 30) {
        parent::__construct($baseUrl, $authProvider, $httpProvider);
        $this->customTimeout = $timeout;
    }

    protected function createRequest($method, $requestUri) {
        $request = parent::createRequest($method, $requestUri);
        $request->setTimeout($this->customTimeout);
        return $request;
    }
}

// Usage with custom timeout
$httpProvider = new GuzzleHttpProvider();
$client = new CustomTimeoutODataClient('https://api.example.com/odata', null, $httpProvider, 60);
$result = $client->from('Products')->get(); // Uses 60-second timeout

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:

<?php

use SaintSystems\OData\ODataClient;
use SaintSystems\OData\GuzzleHttpProvider;

$httpProvider = new GuzzleHttpProvider();
$client = new ODataClient('https://services.odata.org/V4/TripPinService', null, $httpProvider);

// Get a person with address information
$person = $client->from('People')->find('russellwhyte');

// Access nested properties directly
$city = $person->AddressInfo[0]->City;           // Object-style access
$country = $person->AddressInfo[0]->CountryRegion; // Deep nesting supported

// Complex nested structures work naturally
if ($person->Settings && $person->Settings->Preferences) {
    $theme = $person->Settings->Preferences->Theme;
}

Dot Notation Access

Use dot notation for safe navigation through nested properties:

// Safe access with dot notation - returns null if any part doesn't exist
$city = $person->getProperty('AddressInfo.0.City');
$country = $person->getProperty('AddressInfo.0.CountryRegion');
$theme = $person->getProperty('Settings.Preferences.Theme');

// Works with array indices and object properties
$firstFriendName = $person->getProperty('Friends.0.FirstName');
$homeAddress = $person->getProperty('AddressInfo.0.Address');

Property Existence Checking

Check if nested properties exist before accessing them:

// Check existence using hasProperty()
if ($person->hasProperty('AddressInfo.0.City')) {
    $city = $person->getProperty('AddressInfo.0.City');
}

// Also works with isset() for object-style access
if (isset($person->AddressInfo[0]->City)) {
    $city = $person->AddressInfo[0]->City;
}

// Check for deeply nested paths
if ($person->hasProperty('Settings.Preferences.AutoSave')) {
    $autoSave = $person->getProperty('Settings.Preferences.AutoSave');
}

Working with Collections

Handle arrays and collections within nested structures:

// Get people with address information
$people = $client->select('UserName,FirstName,LastName,AddressInfo')
                 ->from('People')
                 ->get();

foreach ($people as $person) {
    echo "Person: " . $person->FirstName . " " . $person->LastName . "\n";

    // Access nested address info - remains as array for easy filtering
    $addresses = $person->AddressInfo;

    // Filter addresses by type
    $homeAddresses = array_filter($addresses, function($address) {
        return isset($address['Type']) && $address['Type'] === 'Home';
    });

    // Access properties within filtered results
    foreach ($homeAddresses as $address) {
        // Convert to Entity for object-style access
        $addrEntity = new \SaintSystems\OData\Entity($address);
        echo "  Home Address: " . $addrEntity->Address . ", " . $addrEntity->City . "\n";
    }
}

Real-World ShareFile OData Example

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

// Query for folders with nested Info and Children data
$folders = $client->select('Id,Name,CreatorNameShort,Info,Info/IsAHomeFolder,Children/Id,Children/Name')
                  ->from('Items')
                  ->where('HasChildren', true)
                  ->get();

foreach ($folders as $folder) {
    echo "Folder: " . $folder->Name . "\n";
    echo "Creator: " . $folder->CreatorNameShort . "\n";

    // Access nested Info properties
    if ($folder->Info) {
        echo "Is Home Folder: " . ($folder->Info->IsAHomeFolder ? 'Yes' : 'No') . "\n";

        // Safe navigation for optional nested properties
        if ($folder->hasProperty('Info.Settings.Theme')) {
            echo "Theme: " . $folder->getProperty('Info.Settings.Theme') . "\n";
        }
    }

    // Work with Children collection
    if ($folder->Children) {
        echo "Children:\n";

        // Filter children by type
        $subfolders = array_filter($folder->Children, function($child) {
            return $child['FileSizeBytes'] == 0; // Folders have 0 file size
        });

        foreach ($subfolders as $subfolder) {
            echo "  - " . $subfolder['Name'] . " (ID: " . $subfolder['Id'] . ")\n";
        }
    }
    echo "\n";
}

Integration with Query Building

Nested property access works seamlessly with OData query operations:

// Select specific nested properties
$result = $client->select('Id,Name,Info/IsAHomeFolder,Children/Name,AddressInfo/City')
                 ->from('Items')
                 ->get();

// Use in where clauses (if supported by the OData service)
$homeItems = $client->from('Items')
                    ->where('Info/IsAHomeFolder', true)
                    ->get();

// Expand related data and access nested properties
$peopleWithTrips = $client->from('People')
                          ->expand('Trips')
                          ->get();

foreach ($peopleWithTrips as $person) {
    foreach ($person->Trips as $trip) {
        // Access nested trip properties
        $tripEntity = new \SaintSystems\OData\Entity($trip);
        echo $person->FirstName . " has trip: " . $tripEntity->Name . "\n";
    }
}

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

<?php

use SaintSystems\OData\ODataClient;
use SaintSystems\OData\GuzzleHttpProvider;

$httpProvider = new GuzzleHttpProvider();
$client = new ODataClient('https://services.odata.org/V4/TripPinService', null, $httpProvider);

// Find people who have any completed trips
$peopleWithCompletedTrips = $client->from('People')
    ->whereAny('Trips', function($query) {
        $query->where('Status', 'Completed');
    })
    ->get();
// Generates: People?$filter=Trips/any(t: t/Status eq 'Completed')

// Find people where all their trips are high-budget
$peopleWithAllHighBudgetTrips = $client->from('People')
    ->whereAll('Trips', function($query) {
        $query->where('Budget', '>', 1000);
    })
    ->get();
// Generates: People?$filter=Trips/all(t: t/Budget gt 1000)

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

// Multiple conditions within lambda
$peopleWithQualifiedTrips = $client->from('People')
    ->whereAny('Trips', function($query) {
        $query->where('Status', 'Completed')
              ->where('Budget', '>', 500);
    })
    ->get();
// Generates: People?$filter=Trips/any(t: t/Status eq 'Completed' and t/Budget gt 500)

// Combining with regular conditions
$activePeopleWithTrips = $client->from('People')
    ->where('Status', 'Active')
    ->whereAny('Trips', function($query) {
        $query->where('Status', 'Pending');
    })
    ->get();
// Generates: People?$filter=Status eq 'Active' and Trips/any(t: t/Status eq 'Pending')

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

<?php

use SaintSystems\OData\ODataClient;
use SaintSystems\OData\GuzzleHttpProvider;

$httpProvider = new GuzzleHttpProvider();
$client = new ODataClient('https://services.odata.org/V4/TripPinService', null, $httpProvider);

// Simple batch with multiple GET requests
$response = $client->batch()
    ->get('People', 'get-people')
    ->get('Airlines', 'get-airlines')
    ->get('Airports', 'get-airports')
    ->execute();

Changesets for Atomic Operations

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

// Batch with changeset for atomic operations
$response = $client->batch()
    ->startChangeset()
        ->post('People', [
            'FirstName' => 'John',
            'LastName' => 'Doe',
            'UserName' => 'johndoe',
            'Emails' => ['john.doe@example.com']
        ], 'create-person')
        ->patch('People(\'russellwhyte\')', [
            'FirstName' => 'Jane',
            'LastName' => 'Smith'
        ], 'update-person')
    ->endChangeset()
    ->execute();

Mixed Batch Operations

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

$response = $client->batch()
    // Individual queries (not in changeset)
    ->get('People?$top=5', 'get-top-people')

    // Atomic operations in changeset
    ->startChangeset()
        ->post('People', $newPersonData, 'create-person')
        ->delete('People(\'obsolete-id\')', 'delete-person')
    ->endChangeset()

    // More individual queries
    ->get('Airlines?$top=3', 'get-airlines')
    ->execute();

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 vendor/bin/phpunit from the base directory.

Documentation and resources

Issues

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

saintsystems / odata-client

Maintainers

Details

README

Install the SDK

HTTP Provider Configuration

Using Guzzle (recommended for most users)

Using PSR-17/PSR-18 implementations

Call an OData Service

Advanced Usage

Custom Headers

Custom Query Options

Custom Timeout Configuration

Nested Property Access

Object-Style Access

Dot Notation Access

Property Existence Checking

Working with Collections

Real-World ShareFile OData Example

Integration with Query Building

Lambda Operators (any/all)

Basic Usage

Available Lambda Methods

Complex Conditions

Batch Operations

Basic Batch Usage

Changesets for Atomic Operations

Mixed Batch Operations

Available Batch Methods

Develop

Run Tests

Documentation and resources

Issues

Copyright and license