small / swoole-entity-manager-core
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
Requires
- php: >=8.4
- ext-mbstring: *
- small/collection: ^4.0
- small/swoole-db: 2.0.*
- small/swoole-patterns: ^26.0
- symfony/yaml: 7.*|8.*
Requires (Dev)
- pestphp/pest: *
- phpstan/phpstan: *
- rector/rector: *
- swoole/ide-helper: ^6.0.2
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- dev-master
- 3.3.1
- 3.3.0
- 3.2.2
- 3.2.1
- 3.2.0
- 3.1.0
- 3.0.4
- 3.0.3
- 3.0.2
- 3.0.1
- 3.0.0
- 2.7.0
- 2.6.1
- 2.6.0
- 2.5.11
- 2.4.0
- 2.3.0
- 2.2.0
- 2.1.0
- 2.0.1
- 2.0.0
- 1.4.10
- 1.4.9
- 1.4.8
- 1.4.7
- 1.4.6
- 1.4.5
- 1.4.4
- 1.4.3
- 1.4.2
- 1.4.1
- 1.4.0
- 1.3.3
- 1.3.2
- 1.3.1
- 1.3.0
- 1.2.3
- 1.2.2
- 1.2.1
- 1.2.0
- 1.1.0
- 1.0.0
- 0.1.1
- 0.1.0
- dev-fix/patterns-26-1-compat
- dev-fix/collection-4-1-compat
- dev-fix/php-85-array-and-ci-matrix
- dev-__noop_should_not_create__
- dev-tmp/coverage-100-apply
This package is auto-updated.
Last update: 2026-11-15 08:32:30 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.