Download the PHP package matatirosoln/doctrine-odata-bundle without Composer

doctrine-odata-bundle

Symfony bundle for matatirosoln/doctrine-odata-driver.

Integrates the OData DBAL driver into a Symfony application with automatic metadata caching and a set of FileMaker-specific services for scripts, container fields, and value lists.

Requirements

Installation

Symfony Flex will register the bundle automatically. Without Flex, add it to config/bundles.php:

Configuration

1. DBAL connection — config/packages/doctrine.yaml

Set the corresponding environment variables in .env.local:

2. Bundle configuration — config/packages/doctrine_odata.yaml

All keys are optional — the defaults shown above apply if omitted:

Metadata caching

The OData $metadata endpoint describes the schema of the database and is required for every request. Without caching it would be fetched on every page load. The bundle wires a DBAL middleware that persists the parsed metadata to the configured Symfony cache pool so that it is only fetched from the server when the cache entry expires.

The middleware is a no-op for any non-OData DBAL connection, so it is safe to use in applications with multiple connections.

Services

The bundle registers the following services, all of which are autowireable by their class name.

ScriptService

Runs a FileMaker script via the OData Script.{name} endpoint.

run() returns the parsed JSON response body as an array. It throws a ScriptException if FileMaker returns a non-zero script result code:

ContainerService

Uploads and downloads binary data to/from FileMaker container fields.

In OData responses, a container field's value is a URL pointing to the binary content. Pass that URL directly to download() or downloadToStream().

Primary key requirement

Container field uploads use the OData key-path URL form (PATCH /EntitySet('key')/Field), which requires the entity set to have a properly defined primary key.

FileMaker OData identifies a field as the primary key if it satisfies both of the following conditions:

• The field does not allow empty values
• The field requires a unique value (uniqueness validation is enabled)

If no field meets these criteria, FileMaker falls back to the internal ROWID system field (equivalent to Get(RecordID)). The ROWID is a numeric record ID that changes if a record is deleted and recreated, and is not accessible as a regular application field. A table that relies on ROWID as its OData primary key will not work correctly with container uploads — or with any single-entity OData operation — and should be given an explicit primary key field with the correct field options set in FileMaker.

ValueListService

Fetches FileMaker value lists and returns them in the ['Display Label' => 'stored_value'] format expected by Symfony's ChoiceType.

Requires FileMaker 22 or later. The FileMaker_ValueList_{name} OData endpoints used by this service were introduced in FileMaker 22. Earlier versions expose value list names in $metadata but do not serve the actual entries via OData.

Available methods

Caching

Value lists are cached at two layers to minimise OData requests:

1. Request cache — an in-memory array on the service instance. Within a single request, a list is never fetched more than once regardless of how many times it is accessed.
2. Session cache — when a Symfony session is active, fetched lists are stored in the session and reused across page loads for the lifetime of that session. This avoids N × OData calls on every form reload without requiring a shared application cache that is difficult to invalidate.

The session cache degrades gracefully to request-only caching for API requests and CLI commands that have no session.

Calling clearCache() removes the named list (or all lists) from both layers simultaneously. The session cache is also automatically cleared when the user's session is destroyed (e.g. on logout).

EntityGeneratorService

Generates Doctrine entity and repository PHP source files from the OData $metadata schema. Intended primarily for use via the CLI command below, but available as an injectable service for programmatic use.

Console commands

doctrine:odata:entity:generate

Generates a Doctrine entity class and its repository from an OData entity set.

Examples:

The command:

• Displays a summary of what will be generated and asks for confirmation before writing
• Prompts before overwriting any file that already exists
• Creates src/Entity/ and src/Repository/ subdirectories as needed
• Infers the base namespace (App\ or similar) from the project's composer.json PSR-4 autoload mapping
• Maps all OData EDM types to the correct PHP types and Doctrine\DBAL\Types\Types constants
• Generates properties using PHP 8.4 property hooks with trim() applied to string setters
• Marks the primary key public private(set) with constructor injection
• Marks Edm.Stream/Edm.Binary (container) fields with a doc comment pointing to ContainerService

Example output for a User entity set with fields __pk_UserID, Name, City:

Exceptions

All bundle exceptions extend RuntimeException and carry structured context:

ConnectionException is thrown when a service cannot resolve a DBAL connection backed by ODataDriver. This typically means the connection key in doctrine_odata.yaml does not match the name of the configured OData DBAL connection.

Licence

MIT

Contact

Steve Winter — Matatiro Solutions Ltd — [email protected]