Download the PHP package phillarmonic/syncopate-bundle without Composer

SyncopateBundle

A Symfony bundle for integrating with SyncopateDB, a flexible, lightweight data store with advanced query capabilities.

Compatibility between the bundle and SyncopateDB

Installation

Step 1: Install the Bundle

Step 2: Enable the Bundle

If you're using Symfony Flex, the bundle will be enabled automatically. Otherwise, add it to your config/bundles.php:

Step 3: Configure the Bundle

Create a configuration file at config/packages/phillarmonic_syncopate.yaml:

Usage

Defining Entities

Define your entities using PHP 8 attributes:

Entity Serialization with EntityTrait

The EntityTrait provides convenient methods to convert your entities to arrays with fine-grained control:

The toArray() method has three optional parameters:

• $fields - When provided, only these fields will be included
• $exclude - Fields to exclude from the result
• $mapping - Maps property names to custom keys in the result

This is particularly useful for API responses, where you might need to transform your internal data model to match external API conventions.

Entity Relationships

SyncopateBundle supports entity relationships with cascade operations:

Supported relationship types:

• TYPE_ONE_TO_ONE: Single reference in both directions
• TYPE_ONE_TO_MANY: Collection on one side, single reference on the other
• TYPE_MANY_TO_ONE: Single reference on one side, collection on the other
• TYPE_MANY_TO_MANY: Collections on both sides

Cascade options:

• CASCADE_NONE: No cascading actions (default)
• CASCADE_REMOVE: Automatically delete related entities when the parent is deleted

Custom Repositories

SyncopateBundle supports entity-specific repositories that allow you to define custom query methods for each entity:

1. Create a Custom Repository Class

2. Specify the Repository Class in Your Entity

3. Use Your Custom Repository Methods

Repository Pattern

Use the repository pattern to interact with your entities:

Using the Query Builder

For more complex queries, use the query builder:

Optimized Count Operations

SyncopateBundle supports efficient count operations that leverage SyncopateDB's dedicated count API, which returns only the count without retrieving all data:

Count with Join Queries

The count API also supports join operations, allowing you to count entities based on related data:

When to use optimized count

The optimized count API is particularly useful for:

1. Pagination: Calculate total pages without retrieving all entities
2. Performance monitoring: Check the size of result sets before executing expensive queries
3. UI elements: Display count badges or indicators with minimal database overhead
4. Large datasets: Get counts from tables with millions of records efficiently
5. Complex joins: Determine relationship counts without materializing all related entities

This approach significantly reduces memory usage and network traffic compared to retrieving all entities and counting them in PHP.

Join Queries

Use join queries to fetch related entities in a single request:

Direct Service Usage

You can also inject and use the SyncopateService directly:

Error Handling

SyncopateBundle provides comprehensive error handling with specific exception types and detailed error information from SyncopateDB.

Exception Types

The bundle includes specialized exception classes for different error scenarios:

1. SyncopateApiException - Base exception for all SyncopateDB API errors
2. SyncopateValidationException - Thrown when entity validation fails
3. SyncopateIntegrityConstraintException - Thrown when unique constraints are violated

Error Categories

SyncopateDB errors are organized into categories, each with specific error codes:

• General Errors (SY001-SY099) - General API errors, authentication, timeouts
• Entity Type Errors (SY100-SY199) - Issues with entity type definitions
• Entity Errors (SY200-SY299) - Entity validation, constraints, field issues
• Query Errors (SY300-SY399) - Invalid queries, filters, joins
• Persistence Errors (SY400-SY499) - Database storage, backup, recovery issues

Handling Specific Errors

Common Error Scenarios

Entity Not Found (SY200)

Unique Constraint Violation (SY209)

Validation Errors (SY203, SY206, SY207, SY208)

Command Line Tools

The bundle provides console commands for managing entities:

Debug Tools

The bundle includes the DebugHelper class for troubleshooting common issues:

License

This bundle is available under the MIT License.