Search by

small / swoole-entity-manager-core

small

ORM designed for swoole. This is the core package. Use it for your from scratch implementation.

Package info

git.small-project.dev/lib/small-swoole-entity-manager

pkg:composer/small/swoole-entity-manager-core

Statistics

Installs: 461

Dependents: 3

Suggesters: 0

3.3.1 2026-11-15 08:32 UTC

README

Small Swoole Entity Manager is a php ORM designed for swoole.

This is the core package.

Documentation: swoole-entity-manager.small-project.dev

Install

Require the package with composer:

composer require small/swoole-entity-manager-core

Swoole 6

Version 2.5.10 fixes three relational/database compatibility defects exposed by stratified persistence: composite-key joins now chain additional predicates with AND, PostgreSQL connections accept an explicit port (default 5432), and MySQL / PostgreSQL date-time hydration accepts fractional seconds without returning false.

Version 2.5.9 isolates the entity-manager cache per EntityManagerFactory instance. Factories using different connection configurations can no longer reuse a manager created by another factory, preventing cross-test and cross-connection state leakage.

Version 2.5.8 makes the expanded coverage suite independent from a stale Composer classmap. PHPUnit loads tests/bootstrap.php explicitly, and fresh Composer installs also register it through autoload-dev.files. This supports source updates performed over an existing vendor directory without producing Class ... not found failures.

Version 2.5.7 raises the enforced line-coverage threshold to 90% and expands unit, integration, relation, persistence, layer, query-builder, and error-path tests. That release enforced 90% coverage; the current Core test suite enforces 100%.

Version 2.5.6 restores generated-key propagation for small-swoole-db persist threads. PersistThread::flush(true) executes inserts individually only for connections marked with PerInsertLastInsertIdInterface, so each entity receives its own generated key and original primary-key snapshot. MySQL and PostgreSQL batches remain merged.

Since version 2.5, the MySQL connector uses native PDO instead of the removed Swoole\Coroutine\MySQL client. Swoole 6 makes PDO MySQL coroutine-aware through runtime hooks.

Enable hooks once during application bootstrap, before database I/O:

if (class_exists(\Swoole\Runtime::class)) {
    \Swoole\Runtime::enableCoroutine(SWOOLE_HOOK_ALL);
}

The connection pool still assigns one PDO connection to one coroutine at a time. Connections must not be shared concurrently between coroutines.

Long-lived Swoole workers automatically recover pooled MySQL connections closed by the server. Errors 2006 (server has gone away), 2013 (lost connection) and 4031 (idle timeout) discard the dead PDO connection and retry with a new one. A pooled connection idle for 30 seconds is health-checked before reuse so transactions do not receive a stale PDO handle. The threshold can be overridden per connection:

[
    'type' => 'mysql',
    // ...
    'connectionHealthCheckIdleSeconds' => 30,
]

Set it to 0 to validate every reused connection.

The development image uses PHP 8.4 and Swoole 6.2.1:

docker compose up -d --build
docker compose exec test-small-swoole-entity-manager composer install
docker compose exec test-small-swoole-entity-manager composer tests

Run the complete validation suite with:

./bin/composer tests

The local Docker Compose PostgreSQL service uses database test and role test, matching the existing fixtures and the test schema. Its healthcheck runs an authenticated SQL query rather than testing only the TCP listener. The PHP service receives matching ORM_POSTGRES_* variables; CI provides its own orm / orm_test credentials.

After updating an existing development checkout, recreate only the PHP test container to load the new environment variables:

docker compose up -d --no-deps --force-recreate test-small-swoole-entity-manager
./bin/composer tests

The PostgreSQL container and its data volume are preserved. Do not delete database volumes or recreate the PostgreSQL service to fix mismatched test credentials.

Coverage

The test command generates a fresh XML coverage report and enforces 100% line coverage:

./bin/composer unit-tests

All production source is included, including the MySQL and PostgreSQL drivers. The integration suites run against MySQL 8.4 and PostgreSQL 16, and fault-injection tests validate native driver errors. No PostgreSQL source exclusion or coverage-ignore annotation is used.

Semantic releases

Run the release script from the main or master branch:

bin/release --patch  # 2.6.4 -> 2.6.5
bin/release --minor  # 2.6.4 -> 2.7.0
bin/release --major  # 2.6.4 -> 3.0.0

The script builds the Docker Compose environment, runs the validation suite, updates .version, commits, tags, and pushes the release. The supported SemVer parts are only patch, minor, and major.

Contributing

See CONTRIBUTE.md for the GitLab access request, project membership process, development workflow, and validation requirements.

Author

Sébastien Kus — sebastien.kus@gmail.com

License

Copyright © 2021-2026 Sébastien Kus.

This project is released under the MIT License. See LICENCE.txt.

Concurrent job locking and CAS

The ORM now exposes FOR UPDATE SKIP LOCKED query builders and atomic conditional updates with affected-row counts. See transactional queries for transaction ownership, safe bound values, usage constraints and integration tests.

Atomic query APIs (Core 3.2)

Core 3.2 adds mapped atomic upserts, conditional aggregates and typed atomic update expressions for MySQL and PostgreSQL. It also adds caller-owned transactions, session-scoped named locks and SQLSTATE-aware driver exceptions. See transactional query primitives and the MkDocs atomic upsert guide.

Scoped ORM sessions (Core 3.3)

Core 3.3 adds callback-owned ORM sessions, immutable mapped criteria, query projections, mapped hydration, CAS helpers and opt-in rollback-safe retries. See scoped ORM sessions for examples and concurrency rules.