Doctrine Shard Manager Bundle Laravel Package

There are no earlier versions; this is the initial public release of elriseio/doctrine-shard-manager-bundle.

Planned breaking changes

• Adopt three PHP 8.3 language features (typed class constants on every const declaration, #[\Override] attribute on every override method, get_resource_id() audit). The minimum runtime is already PHP 8.3 in 1.0.0; this wave adopts the language features per ADR-0005.
• Source-touch sub-tasks under Issues/open/developer/DE-018_* (per ADR-0005). No public-API contract change; existing ShardStrategyInterface, ShardContextInterface, etc. remain unchanged in shape.

Planned additions (Wave 6 — quality gates)

• CI-enforced quality gates (phpstan level 6 + php-cs-fixer dry-run) wired into .github/workflows/itests-smoke.yml as a quality-gates job that gates the itests-smoke job. Tracked under Issues/open/developer/DE-019_quality_gates.md. Non-breaking change (dev-only); may ship as a minor (2.0.1 or 2.1.0) per operator's call.

Full direction-setting rationale: docs/adr/0005-php-83-migration.md (Wave 5) and docs/adr/0006-quality-gates.md (Wave 6).

Added

• Core sharding abstractions. ShardContextInterface, ShardResolverInterface, ShardStrategyInterface, ShardConnectionManagerInterface, EntityManagerProxyInterface, ShardedRepositoryInterface — the six public contracts consumers depend on. All concrete implementations are un-tagged internal; consumers MUST type-hint against the interfaces.
• Three pluggable strategies. HashShardStrategy (SHA-256 modulo total_shards), RangeShardStrategy (binary-search over a range_table partition with overlap detection at construction), UuidShardStrategy (UUIDv7 with embedded shard index in clock_seq_low, bit-mask configurable). Each strategy accepts an optional Psr\Cache\CacheItemPoolInterface for PSR-6 memoization and an optional Psr\Log\LoggerInterface for structured resolution logs; cache failures degrade gracefully (logged + bypassed).
• Resolver layer. ShardResolver resolves a shard ID from an entity, an ID, or a criteria array; merges YAML sharding_configs and PHP #[Sharding] attribute with DI configs winning over the attribute. CachedShardResolver wraps the resolver with a PSR-6 layer to amortize reflection cost on hot paths.
• Context and repository facades. ShardContext::withShard($shardId, fn) and withEntity($entity, fn) route the active Connection and EntityManager for the duration of the callback. ShardedRepository exposes findOneById, findBy, findOneBy, persistToShard, removeFromShard, flushShard so business code stays unchanged.
• Cross-shard read coordinator. ShardedFinder::find(callable $query, array $shardIds) fans out a query to multiple shards lazily via \Generator. Sequential v1; bypasses the write-path ShardContext (consistent with ADR-0004); throws on the first shard failure with the per-shard context framed in the exception message.
• Dual configuration surface. PHP #[Sharding] attribute on entity class OR YAML under doctrine_shard.sharding_configs.<FQCN>. Resolution precedence is YAML > attribute, documented in docs/architecture.md::I-RES1.
• Console commands. bin/console shard:add <id> provisions a new shard's schema from filtered entity metadata (#[Sharding] entities only, drop-and-recreate via SchemaTool::updateSchema with saveMode: true — greenfield only, see docs/components/command-add-shard.md::Safety Warning). bin/console shard:migrate <id> runs Doctrine Migrations on a single named shard and is additive (Wave 2 / ADR-0003).
• DI extension. doctrine_shard.shard.{hash,range,uuid} strategy configs, doctrine_shard.sharding_configs.<FQCN> per-entity configs, doctrine_shard.resolver.cache.{enabled,pool_service_id} cache wiring, doctrine_shard.cache_ttl global TTL (default 86400s). All public services are public-facing — overriding a strategy is a single services.yaml alias away.
• Architecture decisions (ADR-0001 through ADR-0005). Three-tier testing infrastructure (ADR-0001), app.shard_strategy extensibility contract (ADR-0002), shard:add vs shard:migrate semantics (ADR-0003), ShardedFinder cross-shard read coordinator (ADR-0004), PHP 8.3 minimum (ADR-0005). Full index at docs/architecture/STATUS.md::Architectural Decisions.
• Documentation baseline. 22 source files in src/, 23 component docs in docs/components/, 7 contract docs in docs/contracts/, architecture map in docs/architecture.md, meta-document in docs/architecture/STATUS.md, runbook in docs/RUNBOOK.md, roadmap in docs/ROADMAP.md. Docs↔code invariant is enforced — every component and contract has a corresponding file.

Verification: composer validate --strict passes; vendor/bin/phpunit runs the existing 69+ mock-based unit tests on the PHP 8.3 baseline (10 tests opt-in skipped via RequiresDatabase); vendor/bin/php-cs-fixer fix --dry-run is green on the current ruleset. php -l clean on every PHP file under src/, tests/, bench/, itests/.